From b41b9034225ab3e49980d9de55c141011b6383b0 Mon Sep 17 00:00:00 2001 From: Taru Karttunen Date: Wed, 30 Mar 2011 16:49:47 +0300 Subject: Import sources from 2011-03-30 iso image - sys/man --- sys/man/1/0intro | 397 ++++++++++ sys/man/1/2a | 60 ++ sys/man/1/2c | 497 ++++++++++++ sys/man/1/2l | 220 ++++++ sys/man/1/INDEX | 329 ++++++++ sys/man/1/INDEX.html | 665 +++++++++++++++++ sys/man/1/abaco | 75 ++ sys/man/1/acid | 492 ++++++++++++ sys/man/1/acme | 727 ++++++++++++++++++ sys/man/1/ap | 16 + sys/man/1/ar | 182 +++++ sys/man/1/ascii | 158 ++++ sys/man/1/awk | 560 ++++++++++++++ sys/man/1/basename | 35 + sys/man/1/bc | 290 +++++++ sys/man/1/bind | 215 ++++++ sys/man/1/bitsyload | 146 ++++ sys/man/1/bundle | 53 ++ sys/man/1/cal | 46 ++ sys/man/1/calendar | 62 ++ sys/man/1/cat | 87 +++ sys/man/1/cb | 46 ++ sys/man/1/chgrp | 36 + sys/man/1/chmod | 106 +++ sys/man/1/cleanname | 32 + sys/man/1/cmp | 57 ++ sys/man/1/col | 55 ++ sys/man/1/colors | 72 ++ sys/man/1/comm | 47 ++ sys/man/1/con | 315 ++++++++ sys/man/1/cp | 130 ++++ sys/man/1/cpp | 119 +++ sys/man/1/cpu | 204 +++++ sys/man/1/crop | 153 ++++ sys/man/1/date | 58 ++ sys/man/1/db | 1018 +++++++++++++++++++++++++ sys/man/1/dc | 257 +++++++ sys/man/1/dd | 196 +++++ sys/man/1/delkey | 42 ++ sys/man/1/deroff | 117 +++ sys/man/1/diff | 176 +++++ sys/man/1/doc2txt | 161 ++++ sys/man/1/doctype | 63 ++ sys/man/1/du | 137 ++++ sys/man/1/echo | 26 + sys/man/1/ecp | 141 ++++ sys/man/1/ed | 683 +++++++++++++++++ sys/man/1/emacs | 17 + sys/man/1/eqn | 339 +++++++++ sys/man/1/expect | 172 +++++ sys/man/1/faces | 124 +++ sys/man/1/factor | 64 ++ sys/man/1/fedex | 27 + sys/man/1/file | 112 +++ sys/man/1/filter | 320 ++++++++ sys/man/1/fmt | 90 +++ sys/man/1/fortune | 23 + sys/man/1/freq | 40 + sys/man/1/games | 312 ++++++++ sys/man/1/grap | 416 +++++++++++ sys/man/1/graph | 155 ++++ sys/man/1/grep | 109 +++ sys/man/1/gs | 280 +++++++ sys/man/1/gview | 204 +++++ sys/man/1/gzip | 210 ++++++ sys/man/1/hget | 86 +++ sys/man/1/history | 102 +++ sys/man/1/hoc | 144 ++++ sys/man/1/htmlroff | 119 +++ sys/man/1/idiff | 73 ++ sys/man/1/join | 147 ++++ sys/man/1/jpg | 263 +++++++ sys/man/1/kbmap | 35 + sys/man/1/kill | 70 ++ sys/man/1/ktrace | 62 ++ sys/man/1/leak | 235 ++++++ sys/man/1/lens | 45 ++ sys/man/1/lex | 81 ++ sys/man/1/lock | 61 ++ sys/man/1/look | 85 +++ sys/man/1/lp | 189 +++++ sys/man/1/ls | 160 ++++ sys/man/1/mail | 164 ++++ sys/man/1/man | 122 +++ sys/man/1/marshal | 173 +++++ sys/man/1/mc | 44 ++ sys/man/1/mk | 655 ++++++++++++++++ sys/man/1/mkdir | 43 ++ sys/man/1/mlmgr | 139 ++++ sys/man/1/mp3dec | 47 ++ sys/man/1/mp3enc | 209 ++++++ sys/man/1/ms2html | 78 ++ sys/man/1/mtime | 13 + sys/man/1/mug | 56 ++ sys/man/1/nedmail | 340 +++++++++ sys/man/1/netstat | 51 ++ sys/man/1/news | 63 ++ sys/man/1/nm | 107 +++ sys/man/1/ns | 44 ++ sys/man/1/p | 33 + sys/man/1/page | 271 +++++++ sys/man/1/passwd | 59 ++ sys/man/1/patch | 158 ++++ sys/man/1/pcc | 185 +++++ sys/man/1/pic | 344 +++++++++ sys/man/1/pipefile | 101 +++ sys/man/1/plot | 61 ++ sys/man/1/plumb | 92 +++ sys/man/1/pr | 110 +++ sys/man/1/prof | 167 +++++ sys/man/1/proof | 134 ++++ sys/man/1/ps | 113 +++ sys/man/1/ps2pdf | 90 +++ sys/man/1/pump | 119 +++ sys/man/1/pwd | 38 + sys/man/1/ratrace | 57 ++ sys/man/1/rc | 993 ++++++++++++++++++++++++ sys/man/1/replica | 341 +++++++++ sys/man/1/resample | 58 ++ sys/man/1/rio | 537 +++++++++++++ sys/man/1/rm | 28 + sys/man/1/rwd | 161 ++++ sys/man/1/sam | 891 ++++++++++++++++++++++ sys/man/1/secstore | 225 ++++++ sys/man/1/sed | 389 ++++++++++ sys/man/1/seq | 75 ++ sys/man/1/size | 28 + sys/man/1/sleep | 33 + sys/man/1/sort | 262 +++++++ sys/man/1/spell | 96 +++ sys/man/1/spin | 331 ++++++++ sys/man/1/split | 82 ++ sys/man/1/src | 83 +++ sys/man/1/ssh | 346 +++++++++ sys/man/1/stop | 36 + sys/man/1/strings | 36 + sys/man/1/strip | 31 + sys/man/1/sum | 94 +++ sys/man/1/syscall | 77 ++ sys/man/1/tail | 87 +++ sys/man/1/tar | 202 +++++ sys/man/1/tbl | 285 +++++++ sys/man/1/tcs | 172 +++++ sys/man/1/tee | 28 + sys/man/1/tel | 49 ++ sys/man/1/test | 218 ++++++ sys/man/1/thesaurus | 11 + sys/man/1/time | 21 + sys/man/1/touch | 35 + sys/man/1/tr | 97 +++ sys/man/1/trace | 84 +++ sys/man/1/troff | 237 ++++++ sys/man/1/troff2html | 99 +++ sys/man/1/tweak | 167 +++++ sys/man/1/uniq | 59 ++ sys/man/1/units | 107 +++ sys/man/1/uptime | 21 + sys/man/1/vac | 176 +++++ sys/man/1/venti | 153 ++++ sys/man/1/vi | 170 +++++ sys/man/1/vnc | 237 ++++++ sys/man/1/vt | 135 ++++ sys/man/1/wc | 53 ++ sys/man/1/weather | 35 + sys/man/1/who | 22 + sys/man/1/winwatch | 46 ++ sys/man/1/xd | 87 +++ sys/man/1/yacc | 167 +++++ sys/man/1/yesterday | 156 ++++ sys/man/2/0intro | 457 ++++++++++++ sys/man/2/9p | 788 ++++++++++++++++++++ sys/man/2/9pcmdbuf | 120 +++ sys/man/2/9pfid | 207 +++++ sys/man/2/9pfile | 223 ++++++ sys/man/2/INDEX | 1514 +++++++++++++++++++++++++++++++++++++ sys/man/2/INDEX.html | 637 ++++++++++++++++ sys/man/2/abort | 18 + sys/man/2/abs | 33 + sys/man/2/access | 60 ++ sys/man/2/addpt | 188 +++++ sys/man/2/aes | 101 +++ sys/man/2/allocimage | 348 +++++++++ sys/man/2/arg | 126 ++++ sys/man/2/arith3 | 268 +++++++ sys/man/2/assert | 25 + sys/man/2/atof | 144 ++++ sys/man/2/auth | 394 ++++++++++ sys/man/2/authsrv | 238 ++++++ sys/man/2/avl | 147 ++++ sys/man/2/bin | 99 +++ sys/man/2/bind | 236 ++++++ sys/man/2/bio | 361 +++++++++ sys/man/2/blowfish | 52 ++ sys/man/2/brk | 62 ++ sys/man/2/cachechars | 313 ++++++++ sys/man/2/chdir | 32 + sys/man/2/cleanname | 34 + sys/man/2/color | 56 ++ sys/man/2/complete | 105 +++ sys/man/2/control | 1948 ++++++++++++++++++++++++++++++++++++++++++++++++ sys/man/2/cputime | 60 ++ sys/man/2/ctime | 129 ++++ sys/man/2/ctype | 160 ++++ sys/man/2/debugger | 386 ++++++++++ sys/man/2/des | 149 ++++ sys/man/2/dial | 333 +++++++++ sys/man/2/dirread | 103 +++ sys/man/2/disk | 172 +++++ sys/man/2/draw | 821 ++++++++++++++++++++ sys/man/2/dsa | 139 ++++ sys/man/2/dup | 42 ++ sys/man/2/elgamal | 125 ++++ sys/man/2/encode | 85 +++ sys/man/2/encrypt | 76 ++ sys/man/2/errstr | 85 +++ sys/man/2/event | 384 ++++++++++ sys/man/2/exec | 200 +++++ sys/man/2/exits | 81 ++ sys/man/2/exp | 62 ++ sys/man/2/fauth | 66 ++ sys/man/2/fcall | 357 +++++++++ sys/man/2/fd2path | 57 ++ sys/man/2/fgetc | 213 ++++++ sys/man/2/flate | 207 +++++ sys/man/2/floor | 58 ++ sys/man/2/fmtinstall | 372 +++++++++ sys/man/2/fopen | 354 +++++++++ sys/man/2/fork | 166 +++++ sys/man/2/fprintf | 506 +++++++++++++ sys/man/2/frame | 362 +++++++++ sys/man/2/frexp | 47 ++ sys/man/2/fscanf | 404 ++++++++++ sys/man/2/fversion | 72 ++ sys/man/2/getcallerpc | 38 + sys/man/2/getenv | 44 ++ sys/man/2/getfcr | 119 +++ sys/man/2/getfields | 99 +++ sys/man/2/getpid | 42 ++ sys/man/2/getuser | 37 + sys/man/2/getwd | 37 + sys/man/2/graphics | 642 ++++++++++++++++ sys/man/2/html | 1420 +++++++++++++++++++++++++++++++++++ sys/man/2/httpd | 307 ++++++++ sys/man/2/hypot | 21 + sys/man/2/intmap | 126 ++++ sys/man/2/ioproc | 178 +++++ sys/man/2/iounit | 37 + sys/man/2/ip | 364 +++++++++ sys/man/2/isalpharune | 54 ++ sys/man/2/keyboard | 104 +++ sys/man/2/lock | 313 ++++++++ sys/man/2/mach | 393 ++++++++++ sys/man/2/malloc | 230 ++++++ sys/man/2/matrix | 350 +++++++++ sys/man/2/memdraw | 448 +++++++++++ sys/man/2/memlayer | 305 ++++++++ sys/man/2/memory | 126 ++++ sys/man/2/mktemp | 40 + sys/man/2/mouse | 249 +++++++ sys/man/2/mp | 610 +++++++++++++++ sys/man/2/muldiv | 31 + sys/man/2/nan | 52 ++ sys/man/2/ndb | 498 +++++++++++++ sys/man/2/notify | 244 ++++++ sys/man/2/object | 150 ++++ sys/man/2/open | 148 ++++ sys/man/2/perror | 92 +++ sys/man/2/pipe | 74 ++ sys/man/2/plumb | 240 ++++++ sys/man/2/pool | 356 +++++++++ sys/man/2/postnote | 49 ++ sys/man/2/prime | 100 +++ sys/man/2/print | 452 +++++++++++ sys/man/2/privalloc | 36 + sys/man/2/proto | 131 ++++ sys/man/2/pushssl | 45 ++ sys/man/2/pushtls | 254 +++++++ sys/man/2/qball | 75 ++ sys/man/2/qsort | 33 + sys/man/2/quaternion | 151 ++++ sys/man/2/quote | 167 +++++ sys/man/2/rand | 175 +++++ sys/man/2/rc4 | 55 ++ sys/man/2/read | 96 +++ sys/man/2/readcolmap | 76 ++ sys/man/2/readv | 82 ++ sys/man/2/regexp | 212 ++++++ sys/man/2/remove | 31 + sys/man/2/rendezvous | 58 ++ sys/man/2/rsa | 219 ++++++ sys/man/2/rune | 193 +++++ sys/man/2/runestrcat | 67 ++ sys/man/2/scribble | 162 ++++ sys/man/2/scsi | 186 +++++ sys/man/2/sechash | 203 +++++ sys/man/2/seek | 46 ++ sys/man/2/segattach | 168 +++++ sys/man/2/segbrk | 66 ++ sys/man/2/segflush | 42 ++ sys/man/2/semacquire | 106 +++ sys/man/2/setjmp | 98 +++ sys/man/2/sin | 64 ++ sys/man/2/sinh | 23 + sys/man/2/sleep | 45 ++ sys/man/2/stat | 326 ++++++++ sys/man/2/strcat | 269 +++++++ sys/man/2/string | 236 ++++++ sys/man/2/stringsize | 69 ++ sys/man/2/subfont | 235 ++++++ sys/man/2/symbol | 436 +++++++++++ sys/man/2/thread | 642 ++++++++++++++++ sys/man/2/time | 44 ++ sys/man/2/tmpfile | 60 ++ sys/man/2/usb | 460 ++++++++++++ sys/man/2/usbfs | 341 +++++++++ sys/man/2/venti | 72 ++ sys/man/2/venti-cache | 246 ++++++ sys/man/2/venti-client | 190 +++++ sys/man/2/venti-conn | 200 +++++ sys/man/2/venti-fcall | 275 +++++++ sys/man/2/venti-file | 325 ++++++++ sys/man/2/venti-log | 136 ++++ sys/man/2/venti-mem | 68 ++ sys/man/2/venti-packet | 281 +++++++ sys/man/2/venti-server | 122 +++ sys/man/2/venti-zero | 56 ++ sys/man/2/wait | 122 +++ sys/man/2/window | 244 ++++++ sys/man/3/0intro | 92 +++ sys/man/3/INDEX | 50 ++ sys/man/3/INDEX.html | 165 ++++ sys/man/3/aoe | 290 +++++++ sys/man/3/apm | 60 ++ sys/man/3/arch | 143 ++++ sys/man/3/audio | 129 ++++ sys/man/3/bridge | 171 +++++ sys/man/3/cap | 81 ++ sys/man/3/cons | 376 ++++++++++ sys/man/3/draw | 791 ++++++++++++++++++++ sys/man/3/dup | 58 ++ sys/man/3/env | 64 ++ sys/man/3/ether | 111 +++ sys/man/3/flash | 173 +++++ sys/man/3/floppy | 54 ++ sys/man/3/fs | 263 +++++++ sys/man/3/i82365 | 41 + sys/man/3/ip | 1269 +++++++++++++++++++++++++++++++ sys/man/3/kbin | 36 + sys/man/3/kbmap | 70 ++ sys/man/3/kprof | 66 ++ sys/man/3/loopback | 88 +++ sys/man/3/lpt | 43 ++ sys/man/3/mnt | 72 ++ sys/man/3/mouse | 212 ++++++ sys/man/3/pipe | 52 ++ sys/man/3/pnp | 146 ++++ sys/man/3/proc | 507 +++++++++++++ sys/man/3/root | 40 + sys/man/3/rtc | 40 + sys/man/3/sd | 254 +++++++ sys/man/3/sdahci | 161 ++++ sys/man/3/sdaoe | 84 +++ sys/man/3/segment | 117 +++ sys/man/3/srv | 74 ++ sys/man/3/ssl | 124 +++ sys/man/3/tls | 273 +++++++ sys/man/3/twsi | 30 + sys/man/3/uart | 135 ++++ sys/man/3/usb | 535 +++++++++++++ sys/man/3/vga | 254 +++++++ sys/man/4/0intro | 14 + sys/man/4/INDEX | 91 +++ sys/man/4/INDEX.html | 193 +++++ sys/man/4/acme | 458 ++++++++++++ sys/man/4/archfs | 46 ++ sys/man/4/cdfs | 261 +++++++ sys/man/4/cfs | 124 +++ sys/man/4/cifs | 188 +++++ sys/man/4/consolefs | 253 +++++++ sys/man/4/cwfs | 317 ++++++++ sys/man/4/dossrv | 221 ++++++ sys/man/4/execnet | 67 ++ sys/man/4/exportfs | 257 +++++++ sys/man/4/ext2srv | 110 +++ sys/man/4/factotum | 728 ++++++++++++++++++ sys/man/4/flashfs | 74 ++ sys/man/4/fossil | 506 +++++++++++++ sys/man/4/fs | 150 ++++ sys/man/4/ftpfs | 218 ++++++ sys/man/4/httpfile | 86 +++ sys/man/4/import | 202 +++++ sys/man/4/iostats | 82 ++ sys/man/4/keyfs | 249 +++++++ sys/man/4/kfs | 136 ++++ sys/man/4/lnfs | 64 ++ sys/man/4/mntgen | 30 + sys/man/4/namespace | 404 ++++++++++ sys/man/4/nfs | 210 ++++++ sys/man/4/nntpfs | 136 ++++ sys/man/4/paqfs | 102 +++ sys/man/4/plumber | 126 ++++ sys/man/4/ramfs | 89 +++ sys/man/4/ratfs | 174 +++++ sys/man/4/rdbfs | 67 ++ sys/man/4/rio | 407 ++++++++++ sys/man/4/sacfs | 59 ++ sys/man/4/snap | 106 +++ sys/man/4/srv | 338 +++++++++ sys/man/4/tapefs | 109 +++ sys/man/4/telco | 237 ++++++ sys/man/4/u9fs | 289 +++++++ sys/man/4/upasfs | 351 +++++++++ sys/man/4/usb | 514 +++++++++++++ sys/man/4/usbd | 245 ++++++ sys/man/4/vacfs | 90 +++ sys/man/4/webcookies | 166 +++++ sys/man/4/webfs | 308 ++++++++ sys/man/4/wikifs | 339 +++++++++ sys/man/5/0intro | 607 +++++++++++++++ sys/man/5/INDEX | 16 + sys/man/5/INDEX.html | 53 ++ sys/man/5/attach | 159 ++++ sys/man/5/clunk | 43 ++ sys/man/5/error | 28 + sys/man/5/flush | 99 +++ sys/man/5/open | 247 ++++++ sys/man/5/read | 125 ++++ sys/man/5/remove | 49 ++ sys/man/5/stat | 298 ++++++++ sys/man/5/version | 101 +++ sys/man/5/walk | 178 +++++ sys/man/6/0intro | 8 + sys/man/6/INDEX | 41 + sys/man/6/INDEX.html | 137 ++++ sys/man/6/a.out | 252 +++++++ sys/man/6/ar | 99 +++ sys/man/6/authsrv | 726 ++++++++++++++++++ sys/man/6/color | 150 ++++ sys/man/6/face | 116 +++ sys/man/6/font | 87 +++ sys/man/6/htmlroff | 358 +++++++++ sys/man/6/image | 205 +++++ sys/man/6/keyboard | 195 +++++ sys/man/6/keys.who | 45 ++ sys/man/6/man | 249 +++++++ sys/man/6/map | 87 +++ sys/man/6/mhtml | 105 +++ sys/man/6/mnihongo | 30 + sys/man/6/mpictures | 151 ++++ sys/man/6/ms | 319 ++++++++ sys/man/6/namespace | 95 +++ sys/man/6/ndb | 351 +++++++++ sys/man/6/plot | 336 +++++++++ sys/man/6/plumb | 417 +++++++++++ sys/man/6/regexp | 129 ++++ sys/man/6/rewrite | 154 ++++ sys/man/6/smtpd | 309 ++++++++ sys/man/6/snap | 98 +++ sys/man/6/style | 109 +++ sys/man/6/thumbprint | 41 + sys/man/6/users | 75 ++ sys/man/6/utf | 98 +++ sys/man/6/venti | 451 +++++++++++ sys/man/6/venti.conf | 88 +++ sys/man/6/vgadb | 486 ++++++++++++ sys/man/7/0intro | 8 + sys/man/7/INDEX | 9 + sys/man/7/INDEX.html | 37 + sys/man/7/astro | 122 +++ sys/man/7/dict | 163 ++++ sys/man/7/juke | 369 +++++++++ sys/man/7/map | 675 +++++++++++++++++ sys/man/7/playlistfs | 156 ++++ sys/man/7/scat | 335 +++++++++ sys/man/8/0intro | 8 + sys/man/8/6in4 | 140 ++++ sys/man/8/9load | 486 ++++++++++++ sys/man/8/9pcon | 160 ++++ sys/man/8/INDEX | 215 ++++++ sys/man/8/INDEX.html | 321 ++++++++ sys/man/8/aan | 99 +++ sys/man/8/aliasmail | 61 ++ sys/man/8/apm | 111 +++ sys/man/8/aquarela | 225 ++++++ sys/man/8/auth | 292 ++++++++ sys/man/8/backup | 176 +++++ sys/man/8/boot | 389 ++++++++++ sys/man/8/booting | 261 +++++++ sys/man/8/cec | 153 ++++ sys/man/8/cpurc | 88 +++ sys/man/8/cron | 128 ++++ sys/man/8/dhcpd | 299 ++++++++ sys/man/8/diskparts | 44 ++ sys/man/8/disksim | 99 +++ sys/man/8/drawterm | 117 +++ sys/man/8/fossilcons | 1180 +++++++++++++++++++++++++++++ sys/man/8/fs | 826 ++++++++++++++++++++ sys/man/8/fsconfig | 431 +++++++++++ sys/man/8/fshalt | 48 ++ sys/man/8/getflags | 72 ++ sys/man/8/gpsfs | 269 +++++++ sys/man/8/histogram | 90 +++ sys/man/8/httpd | 336 +++++++++ sys/man/8/init | 87 +++ sys/man/8/ipconfig | 395 ++++++++++ sys/man/8/ipserv | 195 +++++ sys/man/8/kfscmd | 221 ++++++ sys/man/8/listen | 238 ++++++ sys/man/8/lp | 126 ++++ sys/man/8/mk9660 | 245 ++++++ sys/man/8/mkflashfs | 39 + sys/man/8/mkfs | 191 +++++ sys/man/8/mkpaqfs | 52 ++ sys/man/8/mksacfs | 38 + sys/man/8/mouse | 120 +++ sys/man/8/na | 33 + sys/man/8/ndb | 793 ++++++++++++++++++++ sys/man/8/newuser | 118 +++ sys/man/8/nfsserver | 183 +++++ sys/man/8/partfs | 65 ++ sys/man/8/pci | 38 + sys/man/8/pcmcia | 23 + sys/man/8/pem | 65 ++ sys/man/8/ping | 204 +++++ sys/man/8/plan9.ini | 1000 +++++++++++++++++++++++++ sys/man/8/pop3 | 168 +++++ sys/man/8/ppp | 281 +++++++ sys/man/8/prep | 769 +++++++++++++++++++ sys/man/8/qer | 233 ++++++ sys/man/8/reboot | 20 + sys/man/8/replica | 316 ++++++++ sys/man/8/rsa | 242 ++++++ sys/man/8/scanmail | 447 +++++++++++ sys/man/8/screenlock | 20 + sys/man/8/scuzz | 413 ++++++++++ sys/man/8/secstore | 107 +++ sys/man/8/securenet | 128 ++++ sys/man/8/send | 127 ++++ sys/man/8/smtp | 260 +++++++ sys/man/8/snoopy | 215 ++++++ sys/man/8/stats | 160 ++++ sys/man/8/statusbar | 71 ++ sys/man/8/stub | 53 ++ sys/man/8/swap | 30 + sys/man/8/timesync | 110 +++ sys/man/8/tlssrv | 152 ++++ sys/man/8/trampoline | 68 ++ sys/man/8/udpecho | 16 + sys/man/8/update | 127 ++++ sys/man/8/venti | 512 +++++++++++++ sys/man/8/venti-backup | 112 +++ sys/man/8/venti-fmt | 408 ++++++++++ sys/man/8/vga | 217 ++++++ sys/man/8/wol | 42 ++ sys/man/fonts | 10 + sys/man/index.html | 59 ++ sys/man/mkfile | 110 +++ sys/man/preface.html | 116 +++ sys/man/preface3.html | 84 +++ sys/man/preface4.html | 78 ++ sys/man/searchindex | 566 ++++++++++++++ sys/man/vol1.pdf | Bin 0 -> 3013256 bytes sys/man/vol1.ps.gz | Bin 0 -> 3151122 bytes 563 files changed, 108764 insertions(+) create mode 100755 sys/man/1/0intro create mode 100755 sys/man/1/2a create mode 100755 sys/man/1/2c create mode 100755 sys/man/1/2l create mode 100755 sys/man/1/INDEX create mode 100755 sys/man/1/INDEX.html create mode 100755 sys/man/1/abaco create mode 100755 sys/man/1/acid create mode 100755 sys/man/1/acme create mode 100755 sys/man/1/ap create mode 100755 sys/man/1/ar create mode 100755 sys/man/1/ascii create mode 100755 sys/man/1/awk create mode 100755 sys/man/1/basename create mode 100755 sys/man/1/bc create mode 100755 sys/man/1/bind create mode 100755 sys/man/1/bitsyload create mode 100755 sys/man/1/bundle create mode 100755 sys/man/1/cal create mode 100755 sys/man/1/calendar create mode 100755 sys/man/1/cat create mode 100755 sys/man/1/cb create mode 100755 sys/man/1/chgrp create mode 100755 sys/man/1/chmod create mode 100755 sys/man/1/cleanname create mode 100755 sys/man/1/cmp create mode 100755 sys/man/1/col create mode 100755 sys/man/1/colors create mode 100755 sys/man/1/comm create mode 100755 sys/man/1/con create mode 100755 sys/man/1/cp create mode 100755 sys/man/1/cpp create mode 100755 sys/man/1/cpu create mode 100755 sys/man/1/crop create mode 100755 sys/man/1/date create mode 100755 sys/man/1/db create mode 100755 sys/man/1/dc create mode 100755 sys/man/1/dd create mode 100755 sys/man/1/delkey create mode 100755 sys/man/1/deroff create mode 100755 sys/man/1/diff create mode 100755 sys/man/1/doc2txt create mode 100755 sys/man/1/doctype create mode 100755 sys/man/1/du create mode 100755 sys/man/1/echo create mode 100755 sys/man/1/ecp create mode 100755 sys/man/1/ed create mode 100755 sys/man/1/emacs create mode 100755 sys/man/1/eqn create mode 100755 sys/man/1/expect create mode 100755 sys/man/1/faces create mode 100755 sys/man/1/factor create mode 100755 sys/man/1/fedex create mode 100755 sys/man/1/file create mode 100755 sys/man/1/filter create mode 100755 sys/man/1/fmt create mode 100755 sys/man/1/fortune create mode 100755 sys/man/1/freq create mode 100755 sys/man/1/games create mode 100755 sys/man/1/grap create mode 100755 sys/man/1/graph create mode 100755 sys/man/1/grep create mode 100755 sys/man/1/gs create mode 100755 sys/man/1/gview create mode 100755 sys/man/1/gzip create mode 100755 sys/man/1/hget create mode 100755 sys/man/1/history create mode 100755 sys/man/1/hoc create mode 100755 sys/man/1/htmlroff create mode 100755 sys/man/1/idiff create mode 100755 sys/man/1/join create mode 100755 sys/man/1/jpg create mode 100755 sys/man/1/kbmap create mode 100755 sys/man/1/kill create mode 100755 sys/man/1/ktrace create mode 100755 sys/man/1/leak create mode 100755 sys/man/1/lens create mode 100755 sys/man/1/lex create mode 100755 sys/man/1/lock create mode 100755 sys/man/1/look create mode 100755 sys/man/1/lp create mode 100755 sys/man/1/ls create mode 100755 sys/man/1/mail create mode 100755 sys/man/1/man create mode 100755 sys/man/1/marshal create mode 100755 sys/man/1/mc create mode 100755 sys/man/1/mk create mode 100755 sys/man/1/mkdir create mode 100755 sys/man/1/mlmgr create mode 100755 sys/man/1/mp3dec create mode 100755 sys/man/1/mp3enc create mode 100755 sys/man/1/ms2html create mode 100755 sys/man/1/mtime create mode 100755 sys/man/1/mug create mode 100755 sys/man/1/nedmail create mode 100755 sys/man/1/netstat create mode 100755 sys/man/1/news create mode 100755 sys/man/1/nm create mode 100755 sys/man/1/ns create mode 100755 sys/man/1/p create mode 100755 sys/man/1/page create mode 100755 sys/man/1/passwd create mode 100755 sys/man/1/patch create mode 100755 sys/man/1/pcc create mode 100755 sys/man/1/pic create mode 100755 sys/man/1/pipefile create mode 100755 sys/man/1/plot create mode 100755 sys/man/1/plumb create mode 100755 sys/man/1/pr create mode 100755 sys/man/1/prof create mode 100755 sys/man/1/proof create mode 100755 sys/man/1/ps create mode 100755 sys/man/1/ps2pdf create mode 100755 sys/man/1/pump create mode 100755 sys/man/1/pwd create mode 100755 sys/man/1/ratrace create mode 100755 sys/man/1/rc create mode 100755 sys/man/1/replica create mode 100755 sys/man/1/resample create mode 100755 sys/man/1/rio create mode 100755 sys/man/1/rm create mode 100755 sys/man/1/rwd create mode 100755 sys/man/1/sam create mode 100755 sys/man/1/secstore create mode 100755 sys/man/1/sed create mode 100755 sys/man/1/seq create mode 100755 sys/man/1/size create mode 100755 sys/man/1/sleep create mode 100755 sys/man/1/sort create mode 100755 sys/man/1/spell create mode 100755 sys/man/1/spin create mode 100755 sys/man/1/split create mode 100755 sys/man/1/src create mode 100755 sys/man/1/ssh create mode 100755 sys/man/1/stop create mode 100755 sys/man/1/strings create mode 100755 sys/man/1/strip create mode 100755 sys/man/1/sum create mode 100755 sys/man/1/syscall create mode 100755 sys/man/1/tail create mode 100755 sys/man/1/tar create mode 100755 sys/man/1/tbl create mode 100755 sys/man/1/tcs create mode 100755 sys/man/1/tee create mode 100755 sys/man/1/tel create mode 100755 sys/man/1/test create mode 100755 sys/man/1/thesaurus create mode 100755 sys/man/1/time create mode 100755 sys/man/1/touch create mode 100755 sys/man/1/tr create mode 100755 sys/man/1/trace create mode 100755 sys/man/1/troff create mode 100755 sys/man/1/troff2html create mode 100755 sys/man/1/tweak create mode 100755 sys/man/1/uniq create mode 100755 sys/man/1/units create mode 100755 sys/man/1/uptime create mode 100755 sys/man/1/vac create mode 100755 sys/man/1/venti create mode 100755 sys/man/1/vi create mode 100755 sys/man/1/vnc create mode 100755 sys/man/1/vt create mode 100755 sys/man/1/wc create mode 100755 sys/man/1/weather create mode 100755 sys/man/1/who create mode 100755 sys/man/1/winwatch create mode 100755 sys/man/1/xd create mode 100755 sys/man/1/yacc create mode 100755 sys/man/1/yesterday create mode 100755 sys/man/2/0intro create mode 100755 sys/man/2/9p create mode 100755 sys/man/2/9pcmdbuf create mode 100755 sys/man/2/9pfid create mode 100755 sys/man/2/9pfile create mode 100755 sys/man/2/INDEX create mode 100755 sys/man/2/INDEX.html create mode 100755 sys/man/2/abort create mode 100755 sys/man/2/abs create mode 100755 sys/man/2/access create mode 100755 sys/man/2/addpt create mode 100755 sys/man/2/aes create mode 100755 sys/man/2/allocimage create mode 100755 sys/man/2/arg create mode 100755 sys/man/2/arith3 create mode 100755 sys/man/2/assert create mode 100755 sys/man/2/atof create mode 100755 sys/man/2/auth create mode 100755 sys/man/2/authsrv create mode 100755 sys/man/2/avl create mode 100755 sys/man/2/bin create mode 100755 sys/man/2/bind create mode 100755 sys/man/2/bio create mode 100755 sys/man/2/blowfish create mode 100755 sys/man/2/brk create mode 100755 sys/man/2/cachechars create mode 100755 sys/man/2/chdir create mode 100755 sys/man/2/cleanname create mode 100755 sys/man/2/color create mode 100755 sys/man/2/complete create mode 100755 sys/man/2/control create mode 100755 sys/man/2/cputime create mode 100755 sys/man/2/ctime create mode 100755 sys/man/2/ctype create mode 100755 sys/man/2/debugger create mode 100755 sys/man/2/des create mode 100755 sys/man/2/dial create mode 100755 sys/man/2/dirread create mode 100755 sys/man/2/disk create mode 100755 sys/man/2/draw create mode 100755 sys/man/2/dsa create mode 100755 sys/man/2/dup create mode 100755 sys/man/2/elgamal create mode 100755 sys/man/2/encode create mode 100755 sys/man/2/encrypt create mode 100755 sys/man/2/errstr create mode 100755 sys/man/2/event create mode 100755 sys/man/2/exec create mode 100755 sys/man/2/exits create mode 100755 sys/man/2/exp create mode 100755 sys/man/2/fauth create mode 100755 sys/man/2/fcall create mode 100755 sys/man/2/fd2path create mode 100755 sys/man/2/fgetc create mode 100755 sys/man/2/flate create mode 100755 sys/man/2/floor create mode 100755 sys/man/2/fmtinstall create mode 100755 sys/man/2/fopen create mode 100755 sys/man/2/fork create mode 100755 sys/man/2/fprintf create mode 100755 sys/man/2/frame create mode 100755 sys/man/2/frexp create mode 100755 sys/man/2/fscanf create mode 100755 sys/man/2/fversion create mode 100755 sys/man/2/getcallerpc create mode 100755 sys/man/2/getenv create mode 100755 sys/man/2/getfcr create mode 100755 sys/man/2/getfields create mode 100755 sys/man/2/getpid create mode 100755 sys/man/2/getuser create mode 100755 sys/man/2/getwd create mode 100755 sys/man/2/graphics create mode 100755 sys/man/2/html create mode 100755 sys/man/2/httpd create mode 100755 sys/man/2/hypot create mode 100755 sys/man/2/intmap create mode 100755 sys/man/2/ioproc create mode 100755 sys/man/2/iounit create mode 100755 sys/man/2/ip create mode 100755 sys/man/2/isalpharune create mode 100755 sys/man/2/keyboard create mode 100755 sys/man/2/lock create mode 100755 sys/man/2/mach create mode 100755 sys/man/2/malloc create mode 100755 sys/man/2/matrix create mode 100755 sys/man/2/memdraw create mode 100755 sys/man/2/memlayer create mode 100755 sys/man/2/memory create mode 100755 sys/man/2/mktemp create mode 100755 sys/man/2/mouse create mode 100755 sys/man/2/mp create mode 100755 sys/man/2/muldiv create mode 100755 sys/man/2/nan create mode 100755 sys/man/2/ndb create mode 100755 sys/man/2/notify create mode 100755 sys/man/2/object create mode 100755 sys/man/2/open create mode 100755 sys/man/2/perror create mode 100755 sys/man/2/pipe create mode 100755 sys/man/2/plumb create mode 100755 sys/man/2/pool create mode 100755 sys/man/2/postnote create mode 100755 sys/man/2/prime create mode 100755 sys/man/2/print create mode 100755 sys/man/2/privalloc create mode 100755 sys/man/2/proto create mode 100755 sys/man/2/pushssl create mode 100755 sys/man/2/pushtls create mode 100755 sys/man/2/qball create mode 100755 sys/man/2/qsort create mode 100755 sys/man/2/quaternion create mode 100755 sys/man/2/quote create mode 100755 sys/man/2/rand create mode 100755 sys/man/2/rc4 create mode 100755 sys/man/2/read create mode 100755 sys/man/2/readcolmap create mode 100755 sys/man/2/readv create mode 100755 sys/man/2/regexp create mode 100755 sys/man/2/remove create mode 100755 sys/man/2/rendezvous create mode 100755 sys/man/2/rsa create mode 100755 sys/man/2/rune create mode 100755 sys/man/2/runestrcat create mode 100755 sys/man/2/scribble create mode 100755 sys/man/2/scsi create mode 100755 sys/man/2/sechash create mode 100755 sys/man/2/seek create mode 100755 sys/man/2/segattach create mode 100755 sys/man/2/segbrk create mode 100755 sys/man/2/segflush create mode 100755 sys/man/2/semacquire create mode 100755 sys/man/2/setjmp create mode 100755 sys/man/2/sin create mode 100755 sys/man/2/sinh create mode 100755 sys/man/2/sleep create mode 100755 sys/man/2/stat create mode 100755 sys/man/2/strcat create mode 100755 sys/man/2/string create mode 100755 sys/man/2/stringsize create mode 100755 sys/man/2/subfont create mode 100755 sys/man/2/symbol create mode 100755 sys/man/2/thread create mode 100755 sys/man/2/time create mode 100755 sys/man/2/tmpfile create mode 100755 sys/man/2/usb create mode 100755 sys/man/2/usbfs create mode 100755 sys/man/2/venti create mode 100755 sys/man/2/venti-cache create mode 100755 sys/man/2/venti-client create mode 100755 sys/man/2/venti-conn create mode 100755 sys/man/2/venti-fcall create mode 100755 sys/man/2/venti-file create mode 100755 sys/man/2/venti-log create mode 100755 sys/man/2/venti-mem create mode 100755 sys/man/2/venti-packet create mode 100755 sys/man/2/venti-server create mode 100755 sys/man/2/venti-zero create mode 100755 sys/man/2/wait create mode 100755 sys/man/2/window create mode 100755 sys/man/3/0intro create mode 100755 sys/man/3/INDEX create mode 100755 sys/man/3/INDEX.html create mode 100755 sys/man/3/aoe create mode 100755 sys/man/3/apm create mode 100755 sys/man/3/arch create mode 100755 sys/man/3/audio create mode 100755 sys/man/3/bridge create mode 100755 sys/man/3/cap create mode 100755 sys/man/3/cons create mode 100755 sys/man/3/draw create mode 100755 sys/man/3/dup create mode 100755 sys/man/3/env create mode 100755 sys/man/3/ether create mode 100755 sys/man/3/flash create mode 100755 sys/man/3/floppy create mode 100755 sys/man/3/fs create mode 100755 sys/man/3/i82365 create mode 100755 sys/man/3/ip create mode 100755 sys/man/3/kbin create mode 100755 sys/man/3/kbmap create mode 100755 sys/man/3/kprof create mode 100755 sys/man/3/loopback create mode 100755 sys/man/3/lpt create mode 100755 sys/man/3/mnt create mode 100755 sys/man/3/mouse create mode 100755 sys/man/3/pipe create mode 100755 sys/man/3/pnp create mode 100755 sys/man/3/proc create mode 100755 sys/man/3/root create mode 100755 sys/man/3/rtc create mode 100755 sys/man/3/sd create mode 100755 sys/man/3/sdahci create mode 100755 sys/man/3/sdaoe create mode 100755 sys/man/3/segment create mode 100755 sys/man/3/srv create mode 100755 sys/man/3/ssl create mode 100755 sys/man/3/tls create mode 100755 sys/man/3/twsi create mode 100755 sys/man/3/uart create mode 100755 sys/man/3/usb create mode 100755 sys/man/3/vga create mode 100755 sys/man/4/0intro create mode 100755 sys/man/4/INDEX create mode 100755 sys/man/4/INDEX.html create mode 100755 sys/man/4/acme create mode 100755 sys/man/4/archfs create mode 100755 sys/man/4/cdfs create mode 100755 sys/man/4/cfs create mode 100755 sys/man/4/cifs create mode 100755 sys/man/4/consolefs create mode 100755 sys/man/4/cwfs create mode 100755 sys/man/4/dossrv create mode 100755 sys/man/4/execnet create mode 100755 sys/man/4/exportfs create mode 100755 sys/man/4/ext2srv create mode 100755 sys/man/4/factotum create mode 100755 sys/man/4/flashfs create mode 100755 sys/man/4/fossil create mode 100755 sys/man/4/fs create mode 100755 sys/man/4/ftpfs create mode 100755 sys/man/4/httpfile create mode 100755 sys/man/4/import create mode 100755 sys/man/4/iostats create mode 100755 sys/man/4/keyfs create mode 100755 sys/man/4/kfs create mode 100755 sys/man/4/lnfs create mode 100755 sys/man/4/mntgen create mode 100755 sys/man/4/namespace create mode 100755 sys/man/4/nfs create mode 100755 sys/man/4/nntpfs create mode 100755 sys/man/4/paqfs create mode 100755 sys/man/4/plumber create mode 100755 sys/man/4/ramfs create mode 100755 sys/man/4/ratfs create mode 100755 sys/man/4/rdbfs create mode 100755 sys/man/4/rio create mode 100755 sys/man/4/sacfs create mode 100755 sys/man/4/snap create mode 100755 sys/man/4/srv create mode 100755 sys/man/4/tapefs create mode 100755 sys/man/4/telco create mode 100755 sys/man/4/u9fs create mode 100755 sys/man/4/upasfs create mode 100755 sys/man/4/usb create mode 100755 sys/man/4/usbd create mode 100755 sys/man/4/vacfs create mode 100755 sys/man/4/webcookies create mode 100755 sys/man/4/webfs create mode 100755 sys/man/4/wikifs create mode 100755 sys/man/5/0intro create mode 100755 sys/man/5/INDEX create mode 100755 sys/man/5/INDEX.html create mode 100755 sys/man/5/attach create mode 100755 sys/man/5/clunk create mode 100755 sys/man/5/error create mode 100755 sys/man/5/flush create mode 100755 sys/man/5/open create mode 100755 sys/man/5/read create mode 100755 sys/man/5/remove create mode 100755 sys/man/5/stat create mode 100755 sys/man/5/version create mode 100755 sys/man/5/walk create mode 100755 sys/man/6/0intro create mode 100755 sys/man/6/INDEX create mode 100755 sys/man/6/INDEX.html create mode 100755 sys/man/6/a.out create mode 100755 sys/man/6/ar create mode 100755 sys/man/6/authsrv create mode 100755 sys/man/6/color create mode 100755 sys/man/6/face create mode 100755 sys/man/6/font create mode 100755 sys/man/6/htmlroff create mode 100755 sys/man/6/image create mode 100755 sys/man/6/keyboard create mode 100755 sys/man/6/keys.who create mode 100755 sys/man/6/man create mode 100755 sys/man/6/map create mode 100755 sys/man/6/mhtml create mode 100755 sys/man/6/mnihongo create mode 100755 sys/man/6/mpictures create mode 100755 sys/man/6/ms create mode 100755 sys/man/6/namespace create mode 100755 sys/man/6/ndb create mode 100755 sys/man/6/plot create mode 100755 sys/man/6/plumb create mode 100755 sys/man/6/regexp create mode 100755 sys/man/6/rewrite create mode 100755 sys/man/6/smtpd create mode 100755 sys/man/6/snap create mode 100755 sys/man/6/style create mode 100755 sys/man/6/thumbprint create mode 100755 sys/man/6/users create mode 100755 sys/man/6/utf create mode 100755 sys/man/6/venti create mode 100755 sys/man/6/venti.conf create mode 100755 sys/man/6/vgadb create mode 100755 sys/man/7/0intro create mode 100755 sys/man/7/INDEX create mode 100755 sys/man/7/INDEX.html create mode 100755 sys/man/7/astro create mode 100755 sys/man/7/dict create mode 100755 sys/man/7/juke create mode 100755 sys/man/7/map create mode 100755 sys/man/7/playlistfs create mode 100755 sys/man/7/scat create mode 100755 sys/man/8/0intro create mode 100755 sys/man/8/6in4 create mode 100755 sys/man/8/9load create mode 100755 sys/man/8/9pcon create mode 100755 sys/man/8/INDEX create mode 100755 sys/man/8/INDEX.html create mode 100755 sys/man/8/aan create mode 100755 sys/man/8/aliasmail create mode 100755 sys/man/8/apm create mode 100755 sys/man/8/aquarela create mode 100755 sys/man/8/auth create mode 100755 sys/man/8/backup create mode 100755 sys/man/8/boot create mode 100755 sys/man/8/booting create mode 100755 sys/man/8/cec create mode 100755 sys/man/8/cpurc create mode 100755 sys/man/8/cron create mode 100755 sys/man/8/dhcpd create mode 100755 sys/man/8/diskparts create mode 100755 sys/man/8/disksim create mode 100755 sys/man/8/drawterm create mode 100755 sys/man/8/fossilcons create mode 100755 sys/man/8/fs create mode 100755 sys/man/8/fsconfig create mode 100755 sys/man/8/fshalt create mode 100755 sys/man/8/getflags create mode 100755 sys/man/8/gpsfs create mode 100755 sys/man/8/histogram create mode 100755 sys/man/8/httpd create mode 100755 sys/man/8/init create mode 100755 sys/man/8/ipconfig create mode 100755 sys/man/8/ipserv create mode 100755 sys/man/8/kfscmd create mode 100755 sys/man/8/listen create mode 100755 sys/man/8/lp create mode 100755 sys/man/8/mk9660 create mode 100755 sys/man/8/mkflashfs create mode 100755 sys/man/8/mkfs create mode 100755 sys/man/8/mkpaqfs create mode 100755 sys/man/8/mksacfs create mode 100755 sys/man/8/mouse create mode 100755 sys/man/8/na create mode 100755 sys/man/8/ndb create mode 100755 sys/man/8/newuser create mode 100755 sys/man/8/nfsserver create mode 100755 sys/man/8/partfs create mode 100755 sys/man/8/pci create mode 100755 sys/man/8/pcmcia create mode 100755 sys/man/8/pem create mode 100755 sys/man/8/ping create mode 100755 sys/man/8/plan9.ini create mode 100755 sys/man/8/pop3 create mode 100755 sys/man/8/ppp create mode 100755 sys/man/8/prep create mode 100755 sys/man/8/qer create mode 100755 sys/man/8/reboot create mode 100755 sys/man/8/replica create mode 100755 sys/man/8/rsa create mode 100755 sys/man/8/scanmail create mode 100755 sys/man/8/screenlock create mode 100755 sys/man/8/scuzz create mode 100755 sys/man/8/secstore create mode 100755 sys/man/8/securenet create mode 100755 sys/man/8/send create mode 100755 sys/man/8/smtp create mode 100755 sys/man/8/snoopy create mode 100755 sys/man/8/stats create mode 100755 sys/man/8/statusbar create mode 100755 sys/man/8/stub create mode 100755 sys/man/8/swap create mode 100755 sys/man/8/timesync create mode 100755 sys/man/8/tlssrv create mode 100755 sys/man/8/trampoline create mode 100755 sys/man/8/udpecho create mode 100755 sys/man/8/update create mode 100755 sys/man/8/venti create mode 100755 sys/man/8/venti-backup create mode 100755 sys/man/8/venti-fmt create mode 100755 sys/man/8/vga create mode 100755 sys/man/8/wol create mode 100755 sys/man/fonts create mode 100755 sys/man/index.html create mode 100755 sys/man/mkfile create mode 100755 sys/man/preface.html create mode 100755 sys/man/preface3.html create mode 100755 sys/man/preface4.html create mode 100755 sys/man/searchindex create mode 100755 sys/man/vol1.pdf create mode 100755 sys/man/vol1.ps.gz diff --git a/sys/man/1/0intro b/sys/man/1/0intro new file mode 100755 index 000000000..873fc2b87 --- /dev/null +++ b/sys/man/1/0intro @@ -0,0 +1,397 @@ +.TH INTRO 1 +.SH NAME +intro \- introduction to Plan 9 +.SH DESCRIPTION +Plan 9 is a distributed computing environment assembled from +separate machines acting as terminals, +CPU servers, and file servers. +A user works at a terminal, running a window system on a raster display. +Some windows are connected to CPU servers; the intent is that heavy computing +should be done in those windows but it is also possible to compute on the terminal. +A separate file server provides file storage for terminals and +CPU servers alike. +.SS Name Spaces +In Plan 9, almost all objects look like files. +The object retrieved by a given name is determined by a mapping called the +.IR "name space" . +A quick tour of the standard name space is in +.IR namespace (4). +Every program running in Plan 9 belongs to a +.I process group +(see +.I rfork +in +.IR fork (2)), +and the name space for each process group can be independently +customized. +.PP +A name space is hierarchically structured. +A full file name (also called a +.IR "full path name" ) +has the form +.IP +.RI / e1 / e2 /.../ en +.PP +This represents an object in a tree of files: the tree has a root, +represented by the first +.LR / ; +the root has a child file named +.IR e1 , +which in turn has child +.IR e2 , +and so on; the descendent +.I en +is the object represented by the path name. +.PP +There are a number of Plan 9 +.I services +available, each of which provides a tree of files. +A name space is built by +.I binding +services (or subtrees of services) to names in the name-space-so-far. +Typically, a user's home file server is bound to the root of the name space, +and other services are bound to conventionally named subdirectories. +For example, there is a service resident in the operating system for accessing +hardware devices and that is bound to +.B /dev +by convention. +Kernel services have names (outside the name space) that are a +.L # +sign followed by a single letter; +for example, +.B #c +is conventionally bound to +.BR /dev . +.PP +Plan 9 has +.IR "union directories" : +directories made of several directories all bound to the +same name. +The directories making up a union directory are ordered in a list. +When the bindings are made +(see +.IR bind (1)), +flags specify whether a newly bound member goes at the head or the tail of the list +or completely replaces the list. +To look up a name in a union directory, each member directory is searched +in list order until the name is found. +A bind +flag specifies whether file creation is allowed in a member directory: +a file created in the union directory goes in +the first member directory in list order that allows creation, if any. +.PP +The glue that holds Plan 9 together is a network protocol called +.IR 9P , +described in section 5 of this manual. +All Plan 9 servers read and respond to 9P requests to navigate through +a file tree and to perform operations such as reading and writing +files within the tree. +.SS Booting +When a terminal is powered on or reset, +it must be told the name of a file server to boot from, +the operating system kernel to boot, +and a user name and password. +How this dialog proceeds is environment- and machine-dependent. +Once it is complete, +the terminal loads a Plan 9 kernel, +which sets some environment variables (see +.IR env (3)) +and builds an initial name space. +See +.IR namespace (4), +.IR boot (8), +and +.IR init (8) +for details, but some important aspects of the initial name space are: +.IP \(bu +The environment variable +.B $cputype +is set to the name of the kernel's CPU's architecture: one of +.BR alpha , +.BR mips , +.BR sparc , +.B power +(Power PC), +.BR 386 +(386, 486, Pentium, ...) +etc. +The environment variable +.B $objtype +is initially the same as +.BR $cputype . +.IP \(bu +The environment variable +.B $terminal +is set to a description of the machine running the kernel, +such as +.BR "generic pc" . +Sometimes the middle word of +.B $terminal +encodes the file from which the kernel is booted; +e.g. +.B "alpha apc axp +is bootstrapped from +.BR /alpha/bapc . +.IP \(bu +The environment variable +.B $service +is set to +.BR terminal . +(Other ways of accessing Plan 9 may set +.B $service +to one of +.BR cpu , +.BR con , +or +.BR rx .) +.IP \(bu +The environment variable +.B $user +is set to the name of the user who booted the terminal. +The environment variable +.B $home +is set to that user's home directory. +.IP \(bu +.B /$cputype/bin +and +.B /rc/bin +are unioned into +.BR /bin . +.PD +.PP +After booting, the terminal runs the command interpreter, +.IR rc (1), +on +.B /usr/$user/lib/profile +after moving to the user's home directory. +.PP +Here is a typical profile: +.IP +.EX +bind -a $home/bin/rc /bin +bind -a $home/bin/$cputype /bin +bind -c $home/tmp /tmp +font = /lib/font/bit/pelm/euro.9.font +upas/fs +switch($service){ +case terminal + plumber + prompt=('term% ' ' ') + exec rio -f $font +case cpu + bind /mnt/term/dev/cons /dev/cons + bind /mnt/term/dev/consctl /dev/consctl + bind -a /mnt/term/mnt/wsys /dev + prompt=('cpu% ' ' ') + news +case con + prompt=('cpu% ' ' ') + news +} +.EE +.PD +.PP +The first three lines replace +.B /tmp +with a +.B tmp +in the user's home directory +and union personal +.B bin +directories with +.BR /bin , +to be searched after the standard +.B bin +directories. +The next starts the mail file system; see +.IR mail (1). +Then different things happen, depending on the +.B $service +environment variable, +such as running the window system +.IR rio (1) +on a terminal. +.PP +To do heavy work such as compiling, the +.IR cpu (1) +command connects a window to a CPU server; +the same environment variables are set (to different values) +and the same profile is run. +The initial directory is the current directory in the terminal window +where +.I cpu +was typed. +The value of +.B $service +will be +.BR cpu , +so the second arm of the profile switch is executed. +The root of the terminal's name space is accessible through +.BR /mnt/term , +so the +.I bind +is a way of making the window system's graphics interface (see +.IR draw (3)) +available to programs running on the CPU server. +The +.IR news (1) +command reports current Plan 9 affairs. +.PP +The third possible service type, +.BR con , +is set when the CPU server is called from a non-Plan-9 machine, +such as through +.I telnet +(see +.IR con (1)). +.SS Using Plan 9 +The user commands of Plan 9 are reminiscent of those in Research Unix, version 10. +There are a number of differences, however. +.PP +The standard shell is +.IR rc (1), +not the Bourne shell. +The most noticeable differences appear only when programming and macro processing. +.PP +The character-delete character is backspace, and the line-kill character is +control-U; these cannot be changed. +.PP +DEL is the interrupt character: typing it sends an interrupt to processes running in that window. +See +.IR keyboard (6) +for instructions on typing characters like DEL on the various keyboards. +.PP +If a program dies with something like an address error, it enters a `Broken' +state. It lingers, available for debugging with +.IR db (1) +or +.IR acid (1). +.I Broke +(see +.IR kill (1)) +cleans up broken processes. +.PP +The standard editor is one of +.IR acme (1) +or +.IR sam (1). +There is a variant of +.I sam +that permits running the file-manipulating part of +.I sam +on a non-Plan-9 system: +.IP +.EX +sam -r tcp!kremvax +.EE +.PP +For historical reasons, +.I sam +uses a tab stop setting of 8 spaces, while the other editors and window systems use 4 spaces. +These defaults can be overridden by setting the value of the environment variable +.B $tabstop +to the desired number of spaces per tab. +.PP +Machine names may be prefixed by the network name, +here +.BR tcp ; +and +.B net +for the system default. +.PP +Login connections and remote execution on non-Plan-9 machines are usually +done by saying, for example, +.IP +.EX +con kremvax +.EE +.PP +or +.IP +.EX +rx deepthought chess +.EE +.PP +(see +.IR con (1)). +.PP +.I 9fs +connects to file systems of remote systems +(see +.IR srv (4)). +For example, +.IP +.EX +9fs kremvax +.EE +.PP +sets things up so that the root of +.BR kremvax 's +file tree is visible locally in +.BR /n/kremvax . +.PP +.IR Faces (1) +gives graphical notification of arriving mail. +.PP +The Plan 9 file server has an integrated backup facility. +The command +.IP +.EX +9fs dump +.EE +.PP +binds to +.B /n/dump +a tree containing the daily backups on the file server. +The dump tree has years as top level file names, and month-day +as next level file names. +For example, +.B /n/dump/2000/0120 +is the root of the file system as it appeared at dump time on +January 20, 2000. +If more than one dump is taken on the same day, dumps after +the first have an extra digit. +To recover the version of this file as it was on June 15, 1999, +.IP +.EX +cp /n/dump/1999/0615/sys/man/1/0intro . +.EE +.PP +or use +.IR yesterday (1). +.SH SEE ALSO +This section for general publicly accessible commands. +.br +Section (2) for library functions, including system calls. +.br +Section (3) for kernel devices (accessed via +.IR bind (1)). +.br +Section (4) for file services (accessed via +.IR mount ). +.br +Section (5) for the Plan 9 file protocol. +.br +Section (6) for file formats. +.br +Section (7) for databases and database access programs. +.br +Section (8) for things related to administering Plan 9. +.br +.B /sys/doc +for copies of papers referenced in this manual. +.PP +The back of this volume has a permuted index to aid searches. +.SH DIAGNOSTICS +Upon termination each program returns a string called the +.IR "exit status" . +It was either supplied by a call to +.IR exits (2) +or was written to the command's +.BI /proc/ pid /note +file +(see +.IR proc (3)), +causing an abnormal termination. +The empty string is customary for successful execution; +a non-empty string gives a clue to the failure of the command. diff --git a/sys/man/1/2a b/sys/man/1/2a new file mode 100755 index 000000000..75a92d17b --- /dev/null +++ b/sys/man/1/2a @@ -0,0 +1,60 @@ +.TH 2A 1 +.SH NAME +0a, 1a, 2a, 5a, 6a, 7a, 8a, ka, qa, va \- assemblers +.SH SYNOPSIS +.B 2a +[ +.I option ... +] +[ +.I name ... +] +.br +etc. +.SH DESCRIPTION +These programs +assemble the named files into object files +for the corresponding architectures; see +.IR 2c (1) +for the correspondence between an architecture and the character +.RB ( 1 , +.RB 2 , +etc.) that specifies it. +The assemblers handle the most common C preprocessor directives and the associated +command-line options +.BR -D +and +.BR -I . +Other options are: +.TP +.BI -o " obj" +Place output in file +.I obj +(allowed only if there is just one input file). +Default is to take the last element of the input path name, +strip any trailing +.BR .s , +and append +.RI . O , +where +.I O +is first letter of the assembler's name. +.SH FILES +The directory +.B /sys/include +is searched for include files after +machine-dependent files in +.BR /$objtype/include . +.SH SOURCE +.BR /sys/src/cmd/2a , +etc. +.SH SEE ALSO +.IR 2c (1), +.IR 2l (1). +.PP +Rob Pike, ``A manual for the Plan 9 assembler'' +.SH BUGS +The list of assemblers given above is only partial, +not all architectures are supported on all systems, +some have been retired and some +are provided by third parties. diff --git a/sys/man/1/2c b/sys/man/1/2c new file mode 100755 index 000000000..cb663e306 --- /dev/null +++ b/sys/man/1/2c @@ -0,0 +1,497 @@ +.TH 2C 1 +.SH NAME +0c, 1c, 2c, 5c, 6c, 7c, 8c, kc, qc, vc \- C compilers +.SH SYNOPSIS +.B 2c +[ +.I option ... +] +[ +.I file ... +] +.br +etc. +.SH DESCRIPTION +These commands compile the named C +.I files +into object files for the corresponding architecture. +If there are multiple C +.IR files , +the compilers will attempt to keep +.B $NPROC +compilations running concurrently. +Associated with each compiler is a string +.IR objtype , +for example +.TF "6c amd64 " +.PD +.TP +.B "0c spim +little-endian MIPS 3000 family +.TP +.B "1c 68000 +Motorola MC68000 +.TP +.B "2c 68020 +Motorola MC68020 +.TP +.B "5c arm +little-endian ARM +.TP +.B "6c amd64 +AMD64 and compatibles (e.g., Intel EM64T) +.TP +.B "7c alpha +Digital Alpha APX +.TP +.B "8c 386 +Intel i386, i486, Pentium, etc. +.TP +.B "kc sparc +Sun SPARC +.TP +.B "qc power +Power PC +.TP +.B "vc mips +big-endian MIPS 3000 family +.PP +The compilers handle most preprocessing directives themselves; a complete +preprocessor is available in +.IR cpp (1), +which must be run separately. +.PP +Let the first letter of the compiler name be +.IR O = +.BR 0 , +.BR 1 , +.BR 2 , +.BR 5 , +.BR 6 , +.BR 7 , +.BR 8 , +.BR k , +.BR q , +or +.BR v . +The output object files end in +.RI . O . +The letter is also the prefix of related programs: +.IB O a +is the assembler, +.IB O l +is the loader. +Plan 9 conventionally sets the +.B $objtype +environment variable to the +.I objtype +string appropriate to the current machine's type. +Plan 9 also conventionally has +.RI / objtype +directories, which contain among other things: +.BR include , +for machine-dependent include files; +.BR lib , +for public object code libraries; +.BR bin , +for public programs; +and +.BR mkfile , +for preconditioning +.IR mk (1). +.PP +The compiler options are: +.TF Dname +.PD +.TP +.BI -o " obj" +Place output in file +.I obj +(allowed only if there is just one input file). +Default is to take the last element of the input file name, +strip any trailing +.BR .c , +and append +.RI . O . +.TP +.B -w +Print warning messages about unused variables, etc. +.TP +.B -B +Accept functions without a new-style +ANSI C function prototype. +By default, the compilers reject functions +used without a defined prototype, +although ANSI C permits them. +.TP +.BI -D\*S name=def +.br +.ns +.TP +.BI -D \*Sname +Define the +.I name +to the preprocessor, +as if by +.LR #define . +If no definition is given, the name is defined as +.LR 1 . +.TP +.BI -F +Enable type-checking of calls to +.IR print (2) +and other formatted print routines. See the discussion +of extensions, below. +.TP +.BI -I \*Sdir +An +.L #include +file whose name does not begin with +slash +or is enclosed in double quotes +is always +sought first in the directory +of the +.I file +argument. If this fails, +the +.I -. +flag is given or the name is enclosed in +.BR <> , +it is then sought +in directories named in +.B -I +options, +then in +.BR /sys/include , +and finally in +.BR /$objtype/include . +.TP +.B -. +Suppress the automatic searching for include files in +the directory of the file argument. +.TP +.B -N +Suppress automatic registerization and optimization. +.TP +.B -S +Print an assembly language version of the object code +on standard output as well as generating the +.RI . O +file. +.TP +.B -T +Pass type signatures on all external and global entities. +The signature is based on the C +.B signof +operator. +See +.IR dynld (2). +.TP +.B -V +By default, the compilers are non-standardly lax about type equality between +.B void* +values and other pointers; this flag requires ANSI C conformance. +.TP +.B -p +Invoke a standard ANSI C preprocessor before compiling. +.TP +.B -a +Instead of compiling, print on standard output acid functions (see +.IR acid (1)) +for examining structures declared in the source files. +.TP +.B -aa +Like +.B -a +except suppress information about structures +declared in included header files. +.TP +.B -n +When used with +.B -a +or +.BR -aa , +places acid functions in +.IB file .acid +for input +.IB file .c , +and not on standard output. +.PP +The compilers support several extensions to ANSI C: +.TF \| +.PD +.TP +\- +A structure or union may contain unnamed substructures and subunions. +The fields of the substructures or +subunions can then be used as if they were members of the parent +structure or union (the resolution of a name conflict is unspecified). +When a pointer to the outer structure or union is used in a context +that is only legal for the unnamed substructure, the compiler promotes +the type and adjusts the pointer value to point at the substructure. +If the unnamed structure or union is of a type with a tag name specified by a +.B typedef +statement, +the unnamed structure or union can be explicitly referenced +by .. +.TP +\- +A structure value can be formed with an expression such as +.EX + (struct S){v1, v2, v3} +.EE +where the list elements are values for the fields of struct +.BR S . +.TP +\- +Array initializers can specify the indices of the array in square +brackets, as +.EX + int a[] = { [3] 1, [10] 5 }; +.EE +which initializes the third and tenth elements of the eleven-element array +.BR a . +.TP +\- +Structure initializers can specify the structure element by using the name +following a period, as +.EX + struct { int x; int y; } s = { .y 1, .x 5 }; +.EE +which initializes elements +.B y +and then +.B x +of the structure +.BR s . +These forms also accept the new ANSI C notation, which includes an equal sign: +.EX + int a[] = { [3] = 1, [10] = 5 }; + struct { int x; int y; } s = { .y = 1, .x = 5 }; +.EE +.TP +\- +A global variable can be dedicated to a register +by declaring it +.B "extern register" +in +.I all +modules and libraries. +.TP +\- +A +.B #pragma +of the form +.EX + #pragma lib "libbio.a" +.EE +records that the program needs to be loaded with file +.BR /$objtype/lib/libbio.a ; +such lines, typically placed in library header files, obviate the +.B -l +option of the loaders. To help identify files in non-standard directories, +within the file names in the +.B #pragmas +the string +.B $M +represents the name of the architecture +(e.g., +.BR mips ) +and +.B $O +represents its identifying character +(e.g., +.BR v ). +.TP +\- +A +.B #pragma +of the form +.EX + #pragma varargck argpos error 2 +.EE +tells the compiler that the second argument to +.B error +is a +.BR print -like +format string (see +.IR print (2)) +that identifies the handling of subsequent arguments. +The +.B #pragma +.EX + #pragma varargck type "s" char* +.EE +says that the format verb +.B s +processes an argument of type +.BR char *. +The +.B #pragma +.EX + #pragma varargck flag 'c' +.EE +says that +.B c +is a flag character. +These +.B #pragmas +are used, if the +.B -F +option is enabled, to type-check calls to +.B print +and other such routines. +.TP +\- +A +.B #pragma +with any of the following forms: +.EX + #pragma incomplete \fItype\fP + #pragma incomplete struct \fItag\fP + #pragma incomplete union \fItag\fP +.EE +where +.I type +is a +.BR typedef 'd +name for a structure or union type, and +.I tag +is a structure or union tag, +tells the compiler that +the corresponding type +should have its signature calculated as an incomplete type +even if it is subsequently fully defined. +This allows the type signature mechanism to work in the presence +of opaque types declared in header files, with their full definitions +visible only to the code which manipulates them. +With some imported software it might be necessary to turn off the +signature generation completely for a large body of code (typically +at the start and end of a particular include file). +If +.I type +is the word +.BR _off_ , +signature generation is turned off; if +.I type +is the word +.BR _on_ , +the compiler will generate signatures. +.TP +\- +The C++ comment +.RB ( // +to end of line) +is accepted as well as the normal +convention of +.B /* +.BR */ . +.TP +\- +The compilers accept +.B long +.B long +variables as a 64-bit type. +The standard header typedefs this to +.BR vlong . +Arithmetic on +.B vlong +values is usually emulated by a run-time library, +though in at least +.IR 8c , +only division and modulus use the run-time library +and the other operators generate in-line code +(and +.I uvlong-expression +.I divison-or-modulus +.BI "(1<<" constant ) +will turn into in-line bit operations, +as is done for shorter +.I unsigned +expressions). +.SH EXAMPLE +For the 68020, produce a program +.B prog +from C files +.BR main.c +and +.BR sub.c : +.IP +.EX +2c -FVw main.c sub.c +2l -o prog main.2 sub.2 +.EE +.SH FILES +.TF /$objtype/include +.TP +.B /sys/include +system area for machine-independent +.B #include +directives. +.TP +.B /$objtype/include +system area for machine-dependent +.B #include +directives. +.SH SOURCE +.TF /sys/src/cmd/2c,\ etc. +.TP +.B /sys/src/cmd/cc +machine-independent part +.TP +.BR /sys/src/cmd/2c ,\ etc. +machine-dependent part +.SH "SEE ALSO" +.IR 2a (1), +.IR 2l (1), +.IR cpp (1), +.IR mk (1), +.IR nm (1), +.IR pcc (1), +.IR db (1), +.IR acid (1) +.\" .IR ansitize (1) +.PP +Rob Pike, +``How to Use the Plan 9 C Compiler'' +.SH BUGS +The list of compilers given above is only partial, +not all architectures are supported on all systems, +some have been retired and some +are provided by third parties. +.PP +The default preprocessor only handles +.LR #define , +.LR #include , +.LR #undef , +.LR #ifdef , +.LR #line , +and +.LR #ifndef . +For a full ANSI preprocessor, use +the +.B p +option. +.PP +The default search order for include files +differs to that of +.IR cpp (1). +.PP +Some features of C99, the 1999 ANSI C standard, +are implemented. +.PP +.B switch +expressions may not be either signedness of +.B vlong +on 32-bit architectures +.RI ( 8c +at least). +.PP +The implementation of +.B vlong +assignment can use a static location +and this can be disturbed by interrupts +(e.g., notes) +.RI ( 8c +at least). diff --git a/sys/man/1/2l b/sys/man/1/2l new file mode 100755 index 000000000..f89b0e521 --- /dev/null +++ b/sys/man/1/2l @@ -0,0 +1,220 @@ +.TH 2L 1 +.SH NAME +0l, 1l, 2l, 5l, 6l, 7l, 8l, kl, ql, vl \- loaders +.SH SYNOPSIS +.B 2l +[ +.I option ... +] +[ +.I file ... +] +.br +etc. +.SH DESCRIPTION +These commands +load the named +.I files +into executable files for the corresponding architectures; see +.IR 2c (1) +for the correspondence between an architecture and the character +.RB ( 1 , +.RB 2 , +etc.) that specifies it. +The files should be object files or libraries (archives of object files) +for the appropriate architecture. +Also, a name like +.BI -l ext +represents the library +.BI lib ext .a +in +.BR /$objtype/lib , +where +.I objtype +is one of +.BR 68000 , +etc. as listed in +.IR 2c (1). +The libraries must have tables of contents +(see +.IR ar (1)). +.PP +In practice, +.B -l +options are rarely necessary as the header files for +the libraries cause their archives to be included automatically in the load +(see +.IR 2c (1)). +For example, any program that includes header file +.B libc.h +causes the loader +to search the C library +.BR /$objtype/lib/libc.a . +Also, the loader creates an undefined symbol +.B _main +(or +.B _mainp +if profiling is enabled) to force loading of the +startup linkage from the C library. +.PP +The order of search to resolve undefined symbols is to load all files and libraries +mentioned explicitly on the command line, and then to resolve remaining symbols +by searching in topological order +libraries mentioned in header files included by files already loaded. +When scanning such libraries, the algorithm is to scan each library repeatedly until +no new undefined symbols are picked up, then to start on the next library. Thus if library +.I A +needs +.I B +which needs +.I A +again, it may be necessary to mention +.I A +explicitly so it will be read a second time. +.PP +The loader options are: +.TP 0.75i +.B -l +(As a bare option.) +Suppress the default loading of the startup linkage and libraries +specified by header files. +.TP +.BI -o " out" +Place output in file +.IR out . +Default is +.IB O .out\f1, +where +.I O +is the first letter of the loader name. +.TP +.B -p +Insert profiling code into the executable output; no special action is needed +during compilation or assembly. +.TP +.B -e +Insert (\fLe\fPmbedded) tracing code into the executable output; no special action is needed +during compilation or assembly. +The added code calls +.L _tracein +at function entries +and +.L _traceout +at function exits. +.TP +.B -s +Strip the symbol tables from the output file. +.TP +.B -a +Print the object code in assembly language, with addresses. +.TP +.B -v +Print debugging output that annotates the activities of the load. +.TP +.BI -M +.RI ( Kl +only) Generate instructions rather than calls to emulation routines +for multiply and divide. +.TP +.BI -E symbol +The entry point for the binary is +.I symbol +(default +.BR _main ; +.B _mainp +under +.BR -p ). +.TP +.BI -x " [ file ]" +Produce an export table in the executable. +The optional +.I file +restricts the exported symbols to those listed in the file. +See +.IR dynld (2). +.TP +.BI -u " [ file ]" +Produce an export table, import table +and a dynamic load section in the executable. +The optional +.I file +restricts the imported symbols to those listed in the file. +See +.IR dynld (2). +.TP +.B -t +(\c +.I 5l +and +.I vl +only) +Move strings into the text segment. +.TP +.BI -H n +Executable header is type +.IR n . +The meaning of the types is architecture-dependent; typically +type 1 is Plan 9 boot format and type 2 is the +regular Plan 9 format, the default. These are reversed on the MIPS. +The Next boot format is 3. Type 4 in +.I vl +creates a MIPS executable for an SGI Unix system. +.TP +.BI -T t +The text segment starts at address +.IR t . +.TP +.BI -D d +The data segment starts at address +.IR d . +.TP +.BI -R r +The text segment is rounded to a multiple of +.I r +(if +.I r +is nonzero). +.PP +The numbers in the above options can begin with +.L 0x +or +.L 0 +to change the default base from decimal to hexadecimal or octal. +The defaults for the values depend on the compiler and the +header type. +.PP +The loaded image has several symbols inserted by the loader: +.B etext +is the address of the end of the text segment; +.B bdata +is the address of the beginning of the data segment; +.B edata +is the address of the end of the data segment; +and +.B end +is the address of the end of the bss segment, and of the program. +.SH FILES +.TF /$objtype/lib +.TP +.B /$objtype/lib +for +.BI -l lib +arguments. +.SH SOURCE +.B /sys/src/cmd/2l +etc. +.SH "SEE ALSO" +.IR 2c (1), +.IR 2a (1), +.IR ar (1), +.IR nm (1), +.IR db (1), +.IR prof (1) +.PP +Rob Pike, +``How to Use the Plan 9 C Compiler'' +.SH BUGS +The list of loaders given above is only partial, +not all architectures are supported on all systems, +some have been retired and some +are provided by third parties. diff --git a/sys/man/1/INDEX b/sys/man/1/INDEX new file mode 100755 index 000000000..c62d577b3 --- /dev/null +++ b/sys/man/1/INDEX @@ -0,0 +1,329 @@ +0intro 0intro +intro 0intro +0a 2a +1a 2a +2a 2a +5a 2a +6a 2a +7a 2a +8a 2a +ka 2a +qa 2a +va 2a +0c 2c +1c 2c +2c 2c +5c 2c +6c 2c +7c 2c +8c 2c +kc 2c +qc 2c +vc 2c +0l 2l +1l 2l +2l 2l +5l 2l +6l 2l +7l 2l +8l 2l +kl 2l +ql 2l +vl 2l +abaco abaco +readweb abaco +acid acid +trump acid +truss acid +acme acme +awd acme +win acme +ap ap +ar ar +ascii ascii +unicode ascii +awk awk +basename basename +bc bc +bind bind +mount bind +unmount bind +bitsyload bitsyload +keyboard bitsyload +light bitsyload +params bitsyload +pencal bitsyload +prompter bitsyload +bundle bundle +cal cal +calendar calendar +cat cat +read cat +cb cb +chgrp chgrp +chmod chmod +cleanname cleanname +cmp cmp +col col +colors colors +getmap colors +comm comm +con con +hayes con +rx con +telnet con +xmr con +xms con +cp cp +fcp cp +mv cp +cpp cpp +cpu cpu +crop crop +iconv crop +clock date +date date +db db +dc dc +dd dd +delkey delkey +delatex deroff +deroff deroff +diff diff +doc2ps doc2txt +doc2txt doc2txt +msexceltables doc2txt +mswordstrings doc2txt +olefs doc2txt +wdoc2txt doc2txt +xls2txt doc2txt +doctype doctype +du du +echo echo +ecp ecp +ed ed +emacs emacs +eqn eqn +at expect +drain expect +expect expect +pass expect +faces faces +seemail faces +vwhois faces +factor factor +primes factor +fedex fedex +ups fedex +usps fedex +file file +deliver filter +filter filter +list filter +token filter +vf filter +fmt fmt +htmlfmt fmt +fortune fortune +freq freq +4s games +5s games +games games +juggle games +life games +mahjongg games +memo games +sokoban games +sudoku games +grap grap +graph graph +grep grep +gs gs +gview gview +bunzip2 gzip +bzip2 gzip +compress gzip +gunzip gzip +gzip gzip +uncompress gzip +unzip gzip +zip gzip +hget hget +history history +hoc hoc +htmlroff htmlroff +idiff idiff +join join +bmp jpg +gif jpg +ico jpg +jpg jpg +png jpg +ppm jpg +togif jpg +toico jpg +topng jpg +toppm jpg +v210 jpg +yuv jpg +kbmap kbmap +broke kill +kill kill +slay kill +ktrace ktrace +kmem leak +leak leak +umem leak +lens lens +lex lex +lock lock +look look +lp lp +lc ls +ls ls +go.fishing mail +mail mail +lookman man +man man +sig man +marshal marshal +mc mc +membername mk +mk mk +mkdir mkdir +ml mlmgr +mlmgr mlmgr +mlowner mlmgr +mp3dec mp3dec +mp3enc mp3enc +html2ms ms2html +ms2html ms2html +mtime mtime +mug mug +nedmail nedmail +netstat netstat +news news +nm nm +ns ns +p p +page page +netkey passwd +passwd passwd +patch patch +pcc pcc +pic pic +tpic pic +pipefile pipefile +plot plot +plumb plumb +pr pr +kprof prof +prof prof +tprof prof +proof proof +ps ps +psu ps +pdf2ps ps2pdf +ps2pdf ps2pdf +pump pump +pbd pwd +pwd pwd +. rc +cd rc +eval rc +exec rc +exit rc +flag rc +rc rc +rfork rc +shift rc +wait rc +whatis rc +~ rc +changes replica +pull replica +push replica +replica replica +scan replica +resample resample +label rio +rio rio +window rio +wloc rio +rm rm +conswdir rwd +rwd rwd +B sam +sam sam +sam.save sam +samterm sam +aescbc secstore +ipso secstore +secstore secstore +sed sed +seq seq +size size +sleep sleep +sort sort +spell spell +sprog spell +spin spin +split split +src src +scp ssh +ssh ssh +sshnet ssh +sshserve ssh +start stop +stop stop +strings strings +strip strip +md5sum sum +sha1sum sum +sum sum +syscall syscall +tail tail +dircp tar +tar tar +tbl tbl +tcs tcs +tee tee +iwhois tel +tel tel +test test +thesaurus thesaurus +time time +touch touch +tr tr +trace trace +dpost troff +nroff troff +troff troff +troff2html troff2html +tweak tweak +uniq uniq +units units +uptime uptime +unvac vac +vac vac +copy venti +read venti +venti venti +write venti +5i vi +ki vi +qi vi +vi vi +vnc vnc +vncs vnc +vncv vnc +vt vt +wc wc +weather weather +who who +whois who +winwatch winwatch +xd xd +yacc yacc +diffy yesterday +yesterday yesterday diff --git a/sys/man/1/INDEX.html b/sys/man/1/INDEX.html new file mode 100755 index 000000000..84c4100a0 --- /dev/null +++ b/sys/man/1/INDEX.html @@ -0,0 +1,665 @@ + +plan 9 man section 1 + + +[manual index] +

Plan 9 from Bell Labs - Section 1 - Commands

+
+
+
0intro +- introduction to Plan 9 +
intro + +
2a +- assemblers +
0a, 1a, 2a, 5a, 6a, 7a, 8a, ka, qa, va + +
2c +- C compilers +
0c, 1c, 2c, 5c, 6c, 7c, 8c, kc, qc, vc + +
2l +- loaders +
0l, 1l, 2l, 5l, 6l, 7l, 8l, kl, ql, vl + +
abaco +- browse the World-Wide Web +
abaco, readweb + +
acid +- debugger +
acid, truss, trump + +
acme +- interactive text windows +
acme, win, awd + +
ar +- archive and library maintainer +
ar + +
ascii +- interpret ASCII, Unicode characters +
ascii, unicode + +
awk +- pattern-directed scanning and processing language +
awk + +
basename +- strip file name affixes +
basename + +
bc +- arbitrary-precision arithmetic language +
bc + +
bind +- change name space +
bind, mount, unmount + +
bitsyload +- bitsy-specific utilities +
bitsyload, light, pencal, keyboard, params, prompter + +
bundle +- collect files for distribution +
bundle + +
cal +- print calendar +
cal + +
calendar +- print upcoming events +
calendar + +
cat +- catenate files +
cat, read + +
cb +- C program beautifier +
cb + +
chgrp +- change file group +
chgrp + +
chmod +- change mode +
chmod + +
cleanname +- clean a path name +
cleanname + +
cmp +- compare two files +
cmp + +
col +- column alignment +
col + +
colors +- display color map +
getmap, colors + +
comm +- select or reject lines common to two sorted files +
comm + +
con +- remote login, execution, and XMODEM file transfer +
con, telnet, rx, hayes, xms, xmr + +
cp +- copy, move files +
cp, fcp, mv + +
cpp +- C language preprocessor +
cpp + +
cpu +- connection to CPU server +
cpu + +
crop +- frame, crop, and convert image +
crop, iconv + +
date +- date and time +
date, clock + +
db +- debugger +
db + +
dc +- desk calculator +
dc + +
dd +- convert and copy a file +
dd + +
delkey +- delete keys from factotum +
delkey + +
deroff +- remove formatting requests +
deroff, delatex + +
diff +- differential file comparator +
diff + +
doc2txt +- extract printable text from Microsoft documents +
doc2txt, doc2ps, wdoc2txt, xls2txt, olefs, mswordstrings, msexceltables + +
doctype +- intuit command line for formatting a document +
doctype + +
du +- disk usage +
du + +
echo +- print arguments +
echo + +
ecp +- fast copy, handling errors +
ecp + +
ed +- text editor +
ed + +
emacs +- editor macros +
emacs + +
eqn +- typeset mathematics +
eqn + +
expect +- dialer scripting tools +
at, drain, expect, pass + +
faces +- mailbox interface +
faces, seemail, vwhois + +
factor +- factor a number, generate large primes +
factor, primes + +
fedex +- track shipments +
fedex, ups, usps + +
file +- determine file type +
file + +
filter +- filtering mail +
filter, list, deliver, token, vf + +
fmt +- simple text formatters +
fmt, htmlfmt + +
fortune +- sample lines from a file +
fortune + +
freq +- print histogram of character frequencies +
freq + +
grap +- pic preprocessor for drawing graphs +
grap + +
graph +- draw a graph +
graph + +
grep +- search a file for a pattern +
grep + +
gs +- Aladdin Ghostscript (PostScript and PDF language interpreter) +
gs + +
gview +- interactive graph viewer +
gview + +
gzip +- compress and expand data +
gzip, gunzip, bzip2, bunzip2, compress, uncompress, zip, unzip + +
hget +- retrieve a web page corresponding to a url +
hget + +
history +- print file names from the dump +
history + +
hoc +- interactive floating point language +
hoc + +
htmlroff +- HTML formatting and typesetting +
htmlroff + +
idiff +- interactive diff +
idiff + +
join +- relational database operator +
join + +
jpg +- view and convert pictures +
jpg, gif, png, ppm, bmp, v210, yuv, ico, togif, toppm, topng, toico + +
kbmap +- show a list of available keyboard maps and switch between them. +
kbmap + +
kill +- print commands to kill processes +
kill, slay, broke + +
ktrace +- interpret kernel stack dumps +
ktrace + +
leak +- help find memory leaks +
leak, kmem, umem + +
lens +- interactive screen magnifier +
lens + +
lex +- generator of lexical analysis programs +
lex + +
lock +- run a command under lock +
lock + +
look +- find lines in a sorted list +
look + +
lp +- printer output +
lp + +
ls +- list contents of directory +
ls, lc + +
mail +- mail and mailboxes +
mail, go.fishing + +
man +- print or find pages of this manual +
man, lookman, sig + +
marshal +- formatting and sending mail +
marshal + +
mc +- multicolumn print +
mc + +
mk +- maintain (make) related files +
mk, membername + +
mkdir +- make a directory +
mkdir + +
mlmgr +- unmoderated mailing lists +
ml, mlmgr, mlowner + +
mp3dec +- decode audio MPEG files (layers 1, 2 and 3) +
mp3dec + +
mp3enc +- create mp3 audio files +
mp3enc + +
ms2html +- convert between troff's ms macros and html +
ms2html, html2ms + +
mtime +- print file modification time +
mtime + +
mug +- convert an image to a face icon +
mug + +
nedmail +- reading mail +
nedmail + +
netstat +- summarize network connections +
netstat + +
news +- print news items +
news + +
nm +- name list (symbol table) +
nm + +
ns +- display name space +
ns + +
p +- paginate +
p + +
page +- view FAX, image, graphic, PostScript, PDF, and typesetter output files +
page + +
passwd +- change or verify user password +
passwd, netkey + +
patch +- simple patch creation and tracking system +
patch + +
pcc +- APE C compiler driver +
pcc + +
pic +- troff and tex preprocessors for drawing pictures +
pic, tpic + +
pipefile +- attach filter to file in name space +
pipefile + +
plot +- graphics filter +
plot + +
plumb +- send message to plumber +
plumb + +
pr +- print file +
pr + +
prof +- display profiling data +
prof, tprof, kprof + +
proof +- troff output interpreter +
proof + +
ps +- process status +
ps, psu + +
ps2pdf +- convert between PostScript and PDF +
ps2pdf, pdf2ps + +
pump +- copy asynchronously via a large circular buffer +
pump + +
pwd +- working directory +
pwd, pbd + +
rc +- command language +
rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ + +
replica +- client-server replica management +
changes, pull, push, scan + +
resample +- resample a picture +
resample + +
rio +- window system +
rio, label, window, wloc + +
rm +- remove files +
rm + +
rwd +- maintain remote working directory +
rwd, conswdir + +
sam +- screen editor with structural regular expressions +
sam, B, sam.save, samterm + +
secstore +- secstore commands +
aescbc, ipso, secstore + +
sed +- stream editor +
sed + +
seq +- print sequences of numbers +
seq + +
size +- print size of executable files +
size + +
sleep +- suspend execution for an interval +
sleep + +
sort +- sort and/or merge files +
sort + +
spell +- find spelling errors +
spell, sprog + +
spin +- verification tool for models of concurrent systems +
spin + +
split +- split a file into pieces +
split + +
src +- find source code for executable +
src + +
ssh +- secure login and file copy from/to Unix or Plan 9 +
ssh, sshnet, scp, sshserve + +
stop +- print commands to stop and start processes +
stop, start + +
strings +- extract printable strings +
strings + +
strip +- remove symbols from binary files +
strip + +
sum +- sum and count blocks in a file +
sum, md5sum, sha1sum + +
syscall +- test a system call +
syscall + +
tail +- deliver the last part of a file +
tail + +
tar +- archiver +
tar, dircp + +
tbl +- format tables for nroff or troff +
tbl + +
tcs +- translate character sets +
tcs + +
tee +- pipe fitting +
tee + +
tel +- look in phone book +
tel, iwhois + +
test +- set status according to condition +
test + +
thesaurus +- search online thesaurus +
thesaurus + +
time +- time a command +
time + +
touch +- set modification date of a file +
touch + +
tr +- translate characters +
tr + +
trace +- show (real-time) process behavior +
trace + +
troff +- text formatting and typesetting +
troff, nroff, dpost + +
troff2html +- convert troff output into HTML +
troff2html + +
tweak +- edit image files, subfont files, face files, etc. +
tweak + +
uniq +- report repeated lines in a file +
uniq + +
units +- conversion program +
units + +
uptime +- show how long the system has been running +
uptime + +
vac +- create, extract a vac archive on Venti +
vac, unvac + +
venti +- simple Venti clients +
read, write, copy + +
vi +- instruction simulators +
5i, ki, vi, qi + +
vnc +- remote frame buffer server and viewer for Virtual Network Computing (VNC) +
vncs, vncv + +
vt +- emulate a VT-100 or VT-220 terminal +
vt + +
wc +- word count +
wc + +
weather +- print weather report +
weather + +
who +- who is using the machine +
who, whois + +
winwatch +- monitor rio windows +
winwatch + +
xd +- hex, octal, decimal, or ASCII dump +
xd + +
yacc +- yet another compiler-compiler +
yacc + +
yesterday +- print file names from the dump +
yesterday, diffy + +
diff --git a/sys/man/1/abaco b/sys/man/1/abaco new file mode 100755 index 000000000..9a0182f21 --- /dev/null +++ b/sys/man/1/abaco @@ -0,0 +1,75 @@ +.TH ABACO 1 +.SH NAME +abaco, readweb \- browse the World-Wide Web +.SH SYNOPSIS +.B abaco +[ +.B -p +] [ +.B -c +.I ncols +] [ +.B -m +.I mtpt +] [ +.B -t +.I charset +] [ +.I url +] +.PP +.B readweb +[ +.I url +] +.SH DESCRIPTION +.I Abaco +is a lightweight web browser with the appearance of +.IR acme (1) +with +.I ncols +columns (one by default). +Given a +.IR url , +it will start by displaying that page. +Clicking mouse button 3 on a link +opens it in a new +.I abaco +window. +.B -t +selects an alternate character set; +.B -m +an alternate mount point for +.IR webfs . +Normally the standard error of subshells is closed, +but +.B -p +prevents this. +.PP +.I Readweb +imports the outside network, if necessary, +starts +.I webfs +and +.I webcookies +and finally +.IR abaco . +.\" .SH EXAMPLES +.SH FILES +.TP 15 +.B /mnt/web +default +.I webfs +mount point +.SH SOURCE +.B /sys/src/cmd/abaco +.br +.B /rc/bin/readweb +.SH SEE ALSO +.IR vnc (1), +.IR webcookies (4), +.IR webfs (4), +.SH BUGS +.I Abaco +is a work in progress; +many features of giant web browsers are absent. diff --git a/sys/man/1/acid b/sys/man/1/acid new file mode 100755 index 000000000..bfe671e54 --- /dev/null +++ b/sys/man/1/acid @@ -0,0 +1,492 @@ +.TH ACID 1 +.SH NAME +acid, truss, trump \- debugger +.SH SYNOPSIS +.B acid +[ +.B -kqw +] +[ +.BI -l " library +] [ +.B -m +.I machine +] [ +.I pid +] +[ +.I textfile +] +.PP +.B acid +.B -l +.B truss +.I textfile +.PP +.B acid +.B -l +.B trump +[ +.I pid +] +[ +.I textfile +] +.SH DESCRIPTION +.I Acid +is a programmable symbolic debugger. +It can inspect one or more processes that share an address space. +A program to be debugged may be specified by the process id of +a running or defunct process, +or by the name of the program's text file +.RB ( 8.out +by default). +At the prompt, +.I acid +will store function definitions or print the value of expressions. +Options are +.TP .9i +.B -w +Allow the textfile to be modified. +.TP +.B -q +Print variable renamings at startup. +.TP +.BI -l " library +Load from +.I library +at startup; see below. +.TP +.BI -m " machine +Assume instructions are for the given CPU type +(one of +.BR alpha , +.BR 386 , +etc., as listed in +.IR 2c (1), +or +.B sunsparc +or +.B mipsco +for the manufacturer-defined instruction notation for those processors) +instead of using the magic number to select +the CPU type. +.TP +.BI -k +Debug the kernel state for the process, rather than the user state. +.PP +At startup, +.I acid +obtains standard function definitions from the library file +.BR /sys/lib/acid/port , +architecture-dependent functions from +.BR /sys/lib/acid/$objtype , +user-specified functions from +.BR $home/lib/acid , +and further functions from +.B -l +files. +Definitions in any file may override previously defined functions. +If the function +.IR acidinit () +is defined, it will be invoked after all libraries have been loaded. +See +.IR 2c (1) +for information about creating +.I acid +functions for examining data structures. +.SS Language +Symbols of the program being debugged become integer +variables whose values are addresses. +Contents of addresses are obtained by indirection. +Local variables are qualified by +function name, for example +.BR main:argv . +When program symbols conflict with +.I acid +words, distinguishing +.B $ +signs are prefixed. +Such renamings are reported at startup if the option +.B -q +is enabled. +.PP +Variable types +.RI ( "integer, float, list, string" ) +and formats are inferred from assignments. +Truth values false/true are attributed to zero/nonzero +integers or floats and to empty/nonempty lists or strings. +Lists are sequences of expressions surrounded by +.BR {\^} +and separated by commas. +.PP +Expressions are much as in C, +but yield both a value and a format. +Casts to complex types are allowed. +Lists admit the following operators, with +subscripts counted from 0. +.IP +.BI head " list +.br +.BI tail " list +.br +.BI append " list", " element +.br +.BI delete " list", " subscript +.PP +Format codes are the same as in +.IR db (1). +Formats may be attached to (unary) expressions with +.BR \e , +e.g. +.BR (32*7)\eD . +There are two indirection operators, +.B * +to address a core image, +.B @ +to address a text file. +The type and format of the result are determined by the format of the operand, +whose type must be integer. +.PP +Statements are +.IP +.BI if " expr " then " statement " "\fR[ \fPelse\fI statement \fR] +.br +.BI while " expr " do " statement +.br +.BI loop " expr" , " expr " do " statement +.br +.BI defn " name" ( args ") {" " statement \fP} +.br +.BI defn " name" +.br +.IB name ( args ) +.br +.BI builtin " name" ( args ) +.br +.BI local " name +.br +.BI return " expr +.br +.BR whatis " [ \fI name \fP] +.PP +The statement +.B defn +.I name +clears the definition for +.IR name . +A +.B defn +may override a built-in function; +prefixing a function call with +.B builtin +ignores any overriding +.BR defn , +forcing the use of the built-in function. +.PP +Here is a partial list of functions; see the manual for a complete list. +.TF asm(address) +.TP +.B stk() +Print a stack trace for current process. +.TP +.B lstk() +Print a stack trace with values of local variables. +.TP +.B gpr() +Print general registers. +Registers can also be accessed by name, for example +.BR *R0 . +.TP +.B spr() +Print special registers such as program counter and stack pointer. +.TP +.B fpr() +Print floating-point registers. +.TP +.B regs() +Same as +.BR spr();gpr() . +.TP +.BI fmt( expr , format ) +Expression +.I expr +with format given by the character value of expression +.IR format . +.TP +.BI src( address ) +Print 10 lines of source around the program address. +.TP +.BI Bsrc( address ) +Get the source line for the program address +into a window of a running +.IR sam (1) +and select it. +.TP +.BI line( address ) +Print source line nearest to the program address. +.TP +.B source() +List current source directories. +.TP +.BI addsrcdir( string ) +Add a source directory to the list. +.TP +.BI filepc( where ) +Convert a string of the form +.IB sourcefile : linenumber +to a machine address. +.TP +.BI pcfile( address ) +Convert a machine address to a source file name. +.TP +.BI pcline( address ) +Convert a machine address to a source line number. +.TP +.BI bptab() +List breakpoints set in the current process. +.TP +.BI bpset( address ) +Set a breakpoint in the current process at the given address. +.TP +.BI bpdel( address ) +Delete a breakpoint from the current process. +.TP +.B cont() +Continue execution of current process and wait for it to stop. +.TP +.B step() +Execute a single machine instruction in the current process. +.TP +.B func() +Step repeatedly until after a function return. +.TP +.BI stopped( pid ) +This replaceable function is called automatically when the given process +stops. +It normally prints the program counter and returns to the prompt. +.TP +.BI asm( address ) +Disassemble 30 machine instructions beginning at the given address. +.TP +.BI mem( address , string ) +Print a block of memory +interpreted according to a string of format codes. +.TP +.BI dump( address , n , string\fP) +Like +.BR mem (), +repeated for +.I n +consecutive blocks. +.TP +.BI print( expr , ... ) +Print the values of the expressions. +.TP +.BI newproc( arguments ) +Start a new process with arguments given as a string +and halt at the first instruction. +.TP +.B new() +Like +.IR newproc (), +but take arguments (except +.BR argv[0] ) +from string variable +.BR progargs . +.TP +.B win() +Like +.IR new (), +but run the process in a separate window. +.TP +.BI start( pid ) +Start a stopped process. +.TP +.BI kill( pid ) +Kill the given process. +.TP +.BI setproc( pid ) +Make the given process current. +.TP +.BI rc( string ) +Escape to the shell, +.IR rc (1), +to execute the command string. +.SS Libraries +There are a number of +.I acid +`libraries' that provide higher-level debugging facilities. Two notable +examples are +.I truss +and +.IR trump , +which use +.I acid +to trace system calls +.RI ( truss ) +and memory allocation +.RI ( trump ). +Both require starting +.I acid +on the program, either by attaching to a running process or by +executing +.B new() +on a binary (perhaps after setting +.BR progargs ), +stopping the process, and then running +.B truss() +or +.B trump() +to execute the program under the scaffolding. +The output will be a trace of the system calls +.RI ( truss ) +or memory allocation and free calls +.RI ( trump ) +executed by the program. +When finished tracing, stop the process and execute +.B untruss() +or +.B untrump() +followed by +.B cont() +to resume execution. +.SH EXAMPLES +Start to debug +.BR /bin/ls ; +set some breakpoints; run up to the first one: +.IP +.EX +% acid /bin/ls +/bin/ls: mips plan 9 executable +/sys/lib/acid/port +/sys/lib/acid/mips +acid: new() +70094: system call _main ADD $-0x14,R29 +70094: breakpoint main+0x4 MOVW R31,0x0(R29) +acid: pid +70094 +acid: argv0 = **main:argv\es +acid: whatis argv0 +integer variable format s +acid: *argv0 +/bin/ls +acid: bpset(ls) +acid: cont() +70094: breakpoint ls ADD $-0x16c8,R29 +acid: +.EE +.PP +Display elements of a linked list of structures: +.IP +.EX +complex Str { 'D' 0 val; 'X' 4 next; }; +complex Str s; +s = *headstr; +while s != 0 do{ + print(s.val, "\en"); + s = s.next; +} +.EE +.PP +Note the use of the +.B . +operator instead of +.BR -> . +.PP +Display an array of bytes declared in C as +.BR "char array[]" . +.IP +.EX +*(array\es) +.EE +.PP +This example gives +.B array +string format, then prints the string beginning at the address (in +.I acid +notation) +.BR *array . +.PP +Trace the system calls executed by +.IR ls (1): +.IP +.EX +% acid -l truss /bin/ls +/bin/ls:386 plan 9 executable + +/sys/lib/acid/port +/sys/lib/acid/kernel +/sys/lib/acid/truss +/sys/lib/acid/386 +acid: progargs = "-l lib/profile" +acid: new() +acid: truss() +open("#c/pid", 0) + return value: 3 +pread(3, 0x7fffeeac, 20, -1) + return value: 12 + data: " 166 " +\&... +stat("lib/profile", 0x0000f8cc, 113) + return value: 65 +open("/env/timezone", 0) + return value: 3 +pread(3, 0x7fffd7c4, 1680, -1) + return value: 1518 + data: "EST -18000 EDT -14400 + 9943200 25664400 41392800 57718800 73447200 89168400 + 104896800 ..." +close(3) + return value: 0 +pwrite(1, "--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile +", 54, -1) +--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile + return value: 54 +\&... +166: breakpoint _exits+0x5 INTB $0x40 +acid: cont() +.EE +.SH FILES +.B /proc/*/text +.br +.B /proc/*/mem +.br +.B /proc/*/ctl +.br +.B /proc/*/note +.br +.B /sys/lib/acid/$objtype +.br +.B /sys/lib/acid/port +.br +.B /sys/lib/acid/kernel +.br +.B /sys/lib/acid/trump +.br +.B /sys/lib/acid/truss +.br +.B $home/lib/acid +.SH SOURCE +.B /sys/src/cmd/acid +.SH "SEE ALSO" +.IR 2a (1), +.IR 2c (1), +.IR 2l (1), +.IR mk (1), +.IR db (1) +.br +Phil Winterbottom, +``Acid Manual''. +.SH DIAGNOSTICS +At termination, kill commands are proposed +for processes that are still active. +.SH BUGS +There is no way to redirect the standard input and standard output +of a new process. +.br +Source line selection near the beginning of a file may pick +an adjacent file. +.br +With the extant stepping commands, one cannot step through instructions +outside the text segment and it is hard to debug across process forks. diff --git a/sys/man/1/acme b/sys/man/1/acme new file mode 100755 index 000000000..f01ee38fd --- /dev/null +++ b/sys/man/1/acme @@ -0,0 +1,727 @@ +.TH ACME 1 +.SH NAME +acme, win, awd \- interactive text windows +.SH SYNOPSIS +.B acme +[ +.B -ab +] +[ +.B -c +.I ncol +] +[ +.B -f +.I varfont +] +[ +.B -F +.I fixfont +] +[ +.B -l +.I loadfile +| +.I file +\&... ] +.LP +.B win +[ +.I command +] +.LP +.B awd +[ +.I label +] +.SH DESCRIPTION +.I Acme +manages windows of text that may be edited interactively or by external programs. +The interactive interface uses the keyboard and mouse; external programs +use a set of files served by +.IR acme ; +these are discussed in +.IR acme (4). +.PP +Any named +.I files +are read into +.I acme +windows before +.I acme +accepts input. +With the +.B -l +option, the state of the entire system is loaded +from +.IR loadfile , +which should have been created by a +.B Dump +command (q.v.), +and subsequent +.I file +names are ignored. +Plain files display as text; directories display as columnated lists of the +names of their components, as in +.B "ls -p directory|mc +except that the names of subdirectories have a slash appended. +.PP +The +.B -f +.RB ( -F ) +option sets the main font, usually variable-pitch (alternate, usually fixed-pitch); +the default is +.B /lib/font/bit/lucidasans/euro.8.font +.RB ( \&.../lucm/unicode.9.font ). +Tab intervals are set to the width of 4 (or the value of +.BR $tabstop ) +numeral zeros in the appropriate font. +.PP +.SS Windows +.I Acme +windows are in two parts: a one-line +.I tag +above a multi-line +.IR body . +The body typically contains an image of a file, as in +.IR sam (1), +or the output of a +program, as in an +.IR rio (1) +window. +The tag contains a number of +blank-separated words, followed by a vertical bar character, followed by anything. +The first word is the name of the window, typically the name of the associated +file or directory, and the other words are commands available in that window. +Any text may be added after the bar; examples are strings to search for or +commands to execute in that window. +Changes to the text left of the bar will be ignored, +unless the result is to change the name of the +window. +.PP +If a window holds a directory, the name (first word of the tag) will end with +a slash. +.SS Scrolling +Each window has a scroll bar to the left of the body. +The scroll bar behaves much as in +.IR sam (1) +or +.IR rio (1) +except that scrolling occurs when the button is pressed, rather than released, +and continues +as long as the mouse button is held down in the scroll bar. +For example, to scroll slowly through a file, +hold button 3 down near the top of the scroll bar. Moving the mouse +down the scroll bar speeds up the rate of scrolling. +.SS Layout +.I Acme +windows are arranged in columns. By default, it creates two columns when starting; +this can be overridden with the +.B -c +option. +Placement is automatic but may be adjusted +using the +.I layout box +in the upper left corner of each window and column. +Pressing and holding any mouse button in the box drags +the associated window or column. +For windows, just +clicking in the layout box grows the window in place: button 1 +grows it a little, button 2 grows it as much as it can, still leaving all other +tags in that column visible, and button 3 takes over the column completely, +temporarily hiding other windows in the column. +(They will return +.I en masse +if any of them needs attention.) +The layout box in a window is normally white; when it is black in the center, +it records that the file is `dirty': +.I acme +believes it is modified from its original +contents. +.PP +Tags exist at the top of each column and across the whole display. +.I Acme +pre-loads them with useful commands. +Also, the tag across the top maintains a list of executing long-running commands. +.SS Typing +The behavior of typed text is similar to that in +.IR rio (1) +except that the characters are delivered to the tag or body under the mouse; there is no +`click to type'. +(The experimental option +.B -b +causes typing to go to the most recently clicked-at or made window.) +The usual backspacing conventions apply. +As in +.IR sam (1) +but not +.IR rio , +the ESC key selects the text typed since the last mouse action, +a feature particularly useful when executing commands. +A side effect is that typing ESC with text already selected is identical +to a +.B Cut +command +.RI ( q.v. ). +.PP +Most text, including the names of windows, may be edited uniformly. +The only exception is that the command names to the +left of the bar in a tag are maintained automatically; changes to them are repaired +by +.IR acme . +.PP +When a window is in autoindent mode +(see the +.B Indent +command below) and a newline character is typed, +acme copies leading white space on the current line to the new line. +The option +.B -a +causes each window to start in +autoindent mode. +.SS "Directory context +Each window's tag names a directory: explicitly if the window +holds a directory; implicitly if it holds a regular file +(e.g. the directory +.B /adm +if the window holds +.BR /adm/users ). +This directory provides a +.I context +for interpreting file names in that window. +For example, the string +.B users +in a window labeled +.B /adm/ +or +.B /adm/keys +will be interpreted as the file name +.BR /adm/users . +The directory is defined purely textually, so it can be a non-existent +directory or a real directory associated with a non-existent file +(e.g. +.BR /adm/not-a-file ). +File names beginning with a slash +are assumed to be absolute file names. +.SS Errors +Windows whose names begin with +.B - +or +.B + +conventionally hold diagnostics and other data +not directly associated with files. +A window labeled +.B +Errors +receives all diagnostics produced by +.I acme +itself. +Diagnostics from commands run by +.I acme +appear in a window named +.IB directory /+Errors +where +.I directory +is identified by the context of the command. +These error windows are created when needed. +.SS "Mouse button 1 +Mouse button 1 selects text just as in +.IR sam (1) +or +.IR rio (1) , +including the usual double-clicking conventions. +.SS "Mouse button 2 +By an +action similar to selecting text with button 1, +button 2 indicates text to execute as a command. +If the indicated text has multiple white-space-separated words, +the first is the command name and the second and subsequent +are its arguments. +If button 2 is `clicked'\(emindicates a null string\(em\c +.I acme +.I expands +the indicated text to find a command to run: +if the click is within button-1-selected text, +.I acme +takes that selection as the command; +otherwise it takes the largest string of valid file name characters containing the click. +Valid file name characters are alphanumerics and +.B _ +.B . +.B - +.B + +.BR / . +This behavior is similar to double-clicking with button 1 but, +because a null command is meaningless, only a single click is required. +.PP +Some commands, all by convention starting with a capital letter, are +.I built-ins +that are executed directly by +.IR acme : +.TP +.B Cut +Delete most recently selected text and place in snarf buffer. +.TP +.B Del +Delete window. If window is dirty, instead print a warning; a second +.B Del +will succeed. +.TP +.B Delcol +Delete column and all its windows, after checking that windows are not dirty. +.TP +.B Delete +Delete window without checking for dirtiness. +.TP +.B Dump +Write the state of +.I acme +to the file name, if specified, or +.B $home/acme.dump +by default. +.TP +.B Edit +Treat the argument as a text editing command in the style of +.IR sam (1). +The full +.B Sam +language is implemented except for the commands +.BR k , +.BR n , +.BR q , +and +.BR ! . +The +.B = +command is slightly different: it includes the file name and +gives only the line address unless the command is explicitly +.BR =# . +The `current window' for the command is the body of the window in which the +.B Edit +command is executed. +Usually the +.B Edit +command would be typed in a tag; longer commands may be prepared in a +scratch window and executed, with +.B Edit +itself in the current window, using the 2-1 chord described below. +.TP +.B Exit +Exit +.I acme +after checking that windows are not dirty. +.TP +.B Font +With no arguments, change the font of the associated window from fixed-spaced to +proportional-spaced or +.I vice +.IR versa . +Given a file name argument, change the font of the window to that stored in the named file. +If the file name argument is prefixed by +.B var +.RB ( fix ), +also set the default proportional-spaced (fixed-spaced) font for future use to that font. +Other existing windows are unaffected. +.TP +.B Get +Load file into window, replacing previous contents (after checking for dirtiness as in +.BR Del ). +With no argument, use the existing file name of the window. +Given an argument, use that file but do not change the window's file name. +.TP +.B ID +Print window ID number +.RI ( q.v. ). +.TP +.B Incl +When opening `include' files +(those enclosed in +.BR <> ) +with button 3, +.I acme +searches in directories +.B /$objtype/include +and +.BR /sys/include . +.B Incl +adds its arguments to a supplementary list of include directories, analogous to +the +.B -I +option to the compilers. +This list is per-window and is inherited when windows are created by actions in that window, so +.I Incl +is most usefully applied to a directory containing relevant source. +With no arguments, +.I Incl +prints the supplementary list. +This command is largely superseded by plumbing +(see +.IR plumb (6)). +.TP +.B Indent +Set the autoindent mode according to the argument: +.B on +and +.B off +set the mode for the current window; +.B ON +and +.B OFF +set the mode for all existing and future windows. +.TP +.B Kill +Send a +.B kill +note to +.IR acme -initiated +commands named as arguments. +.TP +.B Load +Restore the state of +.I acme +from a file (default +.BR $home/acme.dump ) +created by the +.B Dump +command. +.TP +.B Local +When prefixed to a command +run the +command in the same file name space and environment variable group as +.IR acme . +The environment of the command +is restricted but is sufficient to run +.IR bind (1), +.IR 9fs +(see +.IR srv (4)), +.IR import (4), +etc., +and to set environment variables such as +.BR $objtype . +.TP +.B Look +Search in body for occurrence of literal text indicated by the argument or, +if none is given, by the selected text in the body. +.TP +.B New +Make new window. With arguments, load the named files into windows. +.TP +.B Newcol +Make new column. +.TP +.B Paste +Replace most recently selected text with contents of snarf buffer. +.TP +.B Put +Write window to the named file. +With no argument, write to the file named in the tag of the window. +.TP +.B Putall +Write all dirty windows whose names indicate existing regular files. +.TP +.B Redo +Complement of +.BR Undo . +.TP +.B Send +Append selected text or snarf buffer to end of body; used mainly with +.IR win . +.TP +.B Snarf +Place selected text in snarf buffer. +.TP +.B Sort +Arrange the windows in the column from top to bottom in lexicographical +order based on their names. +.TP +.B Tab +Set the width of tab stops for this window to the value of the argument, in units of widths of the zero +character. +With no arguments, it prints the current value. +.TP +.B Undo +Undo last textual change or set of changes. +.TP +.B Zerox +Create a copy of the window containing most recently selected text. +.TP +.B <|> +If a regular shell command is preceded by a +.BR < , +.BR | , +or +.B > +character, the selected text in the body of the window is affected by the +I/O from the command. +The +.B < +character causes the selection to be replaced by the standard output +of the command; +.B > +causes the selection to be sent as standard input to the command; and +.B | +does both at once, `piping' the selection through the command and +replacing it with the output. +.PP +A common place to store text for commands is in the tag; in fact +.I acme +maintains a set of commands appropriate to the state of the window +to the left of the bar in the tag. +.PP +If the text indicated with button 2 is not a recognized built-in, it is executed as +a shell command. For example, indicating +.B date +with button 2 runs +.IR date (1). +The standard +and error outputs of commands are sent to the error window associated with +the directory from which the command was run, which will be created if +necessary. +For example, in a window +.B /adm/users +executing +.B pwd +will produce the output +.B /adm +in a (possibly newly-created) window labeled +.BR /adm/+Errors ; +in a window containing +.B /sys/src/cmd/sam/sam.c +executing +.B mk +will run +.IR mk (1) +in +.BR /sys/src/cmd/sam , +producing output in a window labeled +.BR /sys/src/cmd/sam/+Errors . +The environment of such commands contains the variable +.B $% +with value set to the filename of the window in which the command is run, +and +.B $winid +set to the window's id number +(see +.IR acme (4)). +.SS "Mouse button 3 +Pointing at text with button 3 instructs +.I acme +to locate or acquire the file, string, etc. described by the indicated text and +its context. +This description follows the actions taken when +button 3 is released after sweeping out some text. +In the description, +.I text +refers to the text of the original sweep or, if it was null, the result of +applying the same expansion rules that apply to button 2 actions. +.PP +If the text names an existing window, +.I acme +moves the mouse cursor to the selected text in the body of that window. +If the text names an existing file with no associated window, +.I acme +loads the file into a new window and moves the mouse there. +If the text is a file name contained in angle brackets, +.I acme +loads the indicated include file from the directory appropriate to the +suffix of the file name of the window holding the text. +(The +.B Incl +command adds directories to the standard list.) +.PP +If the text begins with a colon, it is taken to be an address, in +the style of +.IR sam (1), +within the body of the window containing the text. +The address is evaluated, the resulting text highlighted, and the mouse moved to it. +Thus, in +.IR acme , +one must type +.B :/regexp +or +.B :127 +not just +.B /regexp +or +.BR 127 . +(There is an easier way to locate literal text; see below.) +.PP +If the text is a file name followed by a colon and an address, +.I acme +loads the file and evaluates the address. For example, clicking button 3 anywhere +in the text +.B file.c:27 +will open +.BR file.c , +select line +27, and put the mouse at the beginning of the line. The rules about Error +files, directories, and so on all combine to make this an efficient way to +investigate errors from compilers, etc. +.PP +If the text is not an address or file, it is taken to +be literal text, which is then searched for in the body of the window +in which button 3 was clicked. If a match is found, it is selected and the mouse is +moved there. Thus, to search for occurrences of a word in a file, +just click button 3 on the word. Because of the rule of using the +selection as the button 3 action, subsequent clicks will find subsequent +occurrences without moving the mouse. +.PP +In all these actions, the mouse motion is not done if the text is a null string +within a non-null selected string in the tag, so that (for example) complex regular expressions +may be selected and applied repeatedly to the +body by just clicking button 3 over them. +.SS "Chords of mouse buttons +Several operations are bound to multiple-button actions. +After selecting text, with button 1 still down, pressing button 2 +executes +.B Cut +and button 3 executes +.BR Paste . +After clicking one button, the other undoes +the first; thus (while holding down button 1) 2 followed by 3 is a +.B Snarf +that leaves the file undirtied; +3 followed by 2 is a no-op. +These actions also apply to text selected by double-clicking because +the double-click expansion is made when the second +click starts, not when it ends. +.PP +Commands may be given extra arguments by a mouse chord with buttons 2 and 1. +While holding down button 2 on text to be executed as a command, clicking button 1 +appends the text last pointed to by button 1 as a distinct final argument. +For example, to search for literal +.B text +one may execute +.B Look text +with button 2 or instead point at +.B text +with button 1 in any window, release button 1, +then execute +.BR Look , +clicking button 1 while 2 is held down. +.PP +When an external command (e.g. +.IR echo (1)) +is executed this way, the extra argument is passed as expected and an +environment variable +.B $acmeaddr +is created that holds, in the form interpreted by button 3, +the fully-qualified address of the extra argument. +.SS "Support programs +.I Win +creates a new +.I acme +window and runs a +.I command +(default +.BR /bin/rc ) +in it, turning the window into something analogous to an +.IR rio (1) +window. +Executing text in a +.I win +window with button +2 is similar to using +.BR Send . +.PP +.I Awd +loads the tag line of its window with the directory in which it's running, suffixed +.BI - label +(default +.BR rc ); +it is +intended to be executed by a +.B cd +function for use in +.I win +windows. An example definition is +.EX + fn cd { builtin cd $1 && awd $sysname } +.EE +.SS "Applications and guide files +In the directory +.B /acme +live several subdirectories, each corresponding to a program or +set of related programs that employ +.I acme's +user interface. +Each subdirectory includes source, binaries, and a +.B readme +file for further information. +It also includes a +.BR guide , +a text file holding sample commands to invoke the programs. +The idea is to find an example in the guide that best matches +the job at hand, edit it to suit, and execute it. +.PP +Whenever a command is executed by +.IR acme , +the default search path includes the directory of the window containing +the command and its subdirectory +.BR $cputype . +The program directories in +.B /acme +contain appropriately labeled subdirectories of binaries, +so commands named +in the guide files will be found automatically when run. +Also, +.I acme +binds the directories +.B /acme/bin +and +.B /acme/bin/$cputype +to the beginning of +.B /bin +when it starts; this is where +.IR acme -specific +programs such as +.I win +and +.I awd +reside. +.SH FILES +.TF $home/acme.dump +.TP +.B $home/acme.dump +default file for +.B Dump +and +.BR Load ; +also where state is written if +.I acme +dies or is killed unexpectedly, e.g. by deleting its window. +.TP +.B /acme/*/guide +template files for applications +.TP +.B /acme/*/readme +informal documentation for applications +.TP +.B /acme/*/src +source for applications +.TP +.B /acme/*/mips +MIPS-specific binaries for applications +.SH SOURCE +.B /sys/src/cmd/acme +.br +.B /acme/bin/source/win +.br +.B /sys/src/cmd/awd.c +.SH SEE ALSO +.IR acme (4) +.br +Rob Pike, +.I +Acme: A User Interface for Programmers. +.SH BUGS +With the +.B -l +option or +.B Load +command, +the recreation of windows under control of external programs +such as +.I win +is just to rerun the command; information may be lost. diff --git a/sys/man/1/ap b/sys/man/1/ap new file mode 100755 index 000000000..1b717f35f --- /dev/null +++ b/sys/man/1/ap @@ -0,0 +1,16 @@ +.TH AP 1 +.SH NAME +ap \- fetch Associated Press news articles +.SH SYNOPSIS +.B ap +[ +.BI article-name +] +.SH DESCRIPTION +.I ap +fetches Associated Press news articles from http://www.newsday.com. +Without any arguments it provides a two column list of article keys and descriptions. +When invoked with an article key it fetches that article. +.PP +.SH SOURCE +.B /rc/bin/ap diff --git a/sys/man/1/ar b/sys/man/1/ar new file mode 100755 index 000000000..4e2e91b48 --- /dev/null +++ b/sys/man/1/ar @@ -0,0 +1,182 @@ +.TH AR 1 +.SH NAME +ar \- archive and library maintainer +.SH SYNOPSIS +.B ar +.I key +[ +.I posname +] +.I afile +[ +.I file ... +] +.SH DESCRIPTION +.I Ar +maintains groups of files +combined into a single archive file, +.IR afile . +The main use of +.I ar +is to create and update library files for the loaders +.IR 2l (1), +etc. +It can be used, though, for any similar purpose. +.PP +.I Key +is one character from the set +.BR drqtpmx , +optionally concatenated with +one or more of +.BR vuaibclo . +The +.I files +are constituents of the archive +.IR afile . +The meanings of the +.I key +characters are: +.TP +.B d +Delete +.I files +from the archive file. +.TP +.B r +Replace +.I files +in the archive file, or add them if missing. +Optional modifiers are +.RS +.PD0 +.TP +.B u +Replace only files with +modified dates later than that of +the archive. +.TP +.B a +Place new files after +.I posname +in the archive rather than at the end. +.TP +.BR b " or " i +Place new files before +.I posname +in the archive. +.RE +.PD +.TP +.B q +Quick. Append +.I files +to the end of the archive without checking for duplicates. +Avoids quadratic behavior in +.LR "for (i in *.v) ar r lib.a $i" . +.TP +.B t +List a table of contents of the archive. +If names are given, only those files are listed. +.TP +.B p +Print the named files in the archive. +.TP +.B m +Move the named files to the end or elsewhere, +specified as with +.LR r . +.TP +.B o +Preserve the access and modification times of files +extracted with the +.B x +command. +.TP +.B x +Extract the named files. +If no names are given, all files in the archive are +extracted. +In neither case does +.B x +alter the archive file. +.TP +.B v +Verbose. +Give a file-by-file +description of the making of a +new archive file from the old archive and the constituent files. +With +.BR p , +precede each file with a name. +With +.BR t , +give a long listing of all information about the files, +somewhat like a listing by +.IR ls (1), +showing +.br +.ns +.IP +.B + mode uid/gid size date name +.\" .TP +.\" .B c +.\" Create. +.\" Normally +.\" .I ar +.\" will create a new archive when +.\" .I afile +.\" does not exist, and give a warning. +.\" Option +.\" .B c +.\" discards any old contents and suppresses the warning. +.TP +.B l +Local. +Normally +.I ar +places its temporary files in the directory +.BR /tmp . +This option causes them to be placed in the local directory. +.PP +When a +.BR d , +.BR r , +or +.BR m +.I key +is specified and all members of the archive are valid object files for +the same architecture, +.I ar +inserts a table of contents, required by the loaders, at +the front of the library. +The table of contents is +rebuilt whenever the archive is modified, except +when the +.B q +.I key +is specified or when the table of contents is +explicitly moved or deleted. +.SH EXAMPLE +.TP +.L +ar cr lib.a *.v +Replace the contents of library +.L lib.a +with the object files in the current directory. +.SH FILES +.TF /tmp/vxxxx +.TP +.B /tmp/v* +temporaries +.SH SOURCE +.B /sys/src/cmd/ar.c +.SH "SEE ALSO" +.IR 2l (1), +.IR ar (6) +.SH BUGS +If the same file is mentioned twice in an argument list, +it may be put in the archive twice. +.br +This command predates Plan 9 and makes some invalid assumptions, +for instance that user id's are numeric. diff --git a/sys/man/1/ascii b/sys/man/1/ascii new file mode 100755 index 000000000..de5cd77cf --- /dev/null +++ b/sys/man/1/ascii @@ -0,0 +1,158 @@ +.TH ASCII 1 +.SH NAME +ascii, unicode \- interpret ASCII, Unicode characters +.SH SYNOPSIS +.B ascii +[ +.B -8cnt +] +[ +.B -dox +| +.B -b +.I n +] +[ +.I text +] +.PP +.B unicode +.IB hexmin - hexmax +.PP +.B unicode +[ +.B -t +] +.I hex +[ +\&... +] +.PP +.B unicode +[ +.B -n +] +.I characters +.PP +.B look +.I hex +.B /lib/unicode +.SH DESCRIPTION +.I Ascii +prints the +.SM ASCII +values corresponding to characters and +.I vice +.IR versa ; +under the +.B -8 +option, the +.SM ISO +Latin-1 extensions (codes 0200-0377) are included. +The values are interpreted in a settable numeric base; +.B -o +specifies octal, +.B -d +decimal, +.B -x +hexadecimal (the default), and +.BI -b n +base +.IR n . +.PP +With no arguments, +.I ascii +prints a table of the character set in the specified base. +Characters of +.I text +are converted to their +.SM ASCII +values, one per line. If, however, the first +.I text +argument is a valid number in the specified base, conversion +goes the opposite way. +Control characters are printed as two- or three-character mnemonics. +Other options are: +.TP +.B -n +Force numeric output. +.TP +.B -c +Force character output. +.TP +.B -t +Convert from numbers to running text; do not interpret +control characters or insert newlines. +.PP +.I Unicode +is similar; it converts between +.SM UTF +and character values from the Unicode Standard (see +.IR utf (6)). +If given a range of hexadecimal numbers, +.I unicode +prints a table of the specified Unicode characters \(em their values and +.SM UTF +representations. +Otherwise it translates from +.SM UTF +to numeric value or vice versa, +depending on the appearance of the supplied text; +the +.B -n +option forces numeric output to avoid ambiguity with numeric characters. +If converting to +.SM UTF , +the characters are printed one per line unless the +.B -t +flag is set, in which case the output is a single string +containing only the specified characters. +Unlike +.IR ascii , +.I unicode +treats no characters specially. +.PP +The output of +.I ascii +and +.I unicode +may be unhelpful if the characters printed are not available in the current font. +.PP +The file +.B /lib/unicode +contains a +table of characters and descriptions, sorted in hexadecimal order, +suitable for +.IR look (1) +on the lower case +.I hex +values of characters. +.SH EXAMPLES +.TP +.B "ascii -d" +Print the +.SM ASCII +table base 10. +.TP +.B "unicode p" +Print the hex value of `p'. +.TP +.B "unicode 2200-22f1" +Print a table of miscellaneous mathematical symbols. +.TP +.B "look 039 /lib/unicode" +See the start of the Greek alphabet's encoding in the Unicode Standard. +.SH FILES +.TF \fL/lib/unicode +.TP +.B /lib/unicode +table of characters and descriptions. +.SH SOURCE +.B /sys/src/cmd/ascii.c +.br +.B /sys/src/cmd/unicode.c +.SH "SEE ALSO" +.IR look (1), +.IR tcs (1), +.IR utf (6), +.IR font (6) diff --git a/sys/man/1/awk b/sys/man/1/awk new file mode 100755 index 000000000..d79b963c4 --- /dev/null +++ b/sys/man/1/awk @@ -0,0 +1,560 @@ +.TH AWK 1 +.SH NAME +awk \- pattern-directed scanning and processing language +.SH SYNOPSIS +.B awk +[ +.B -F +.I fs +] +[ +.B -d +] +[ +.BI -mf +.I n +] +[ +.B -mr +.I n +] +[ +.B -safe +] +[ +.B -v +.I var=value +] +[ +.B -f +.I progfile +| +.I prog +] +[ +.I file ... +] +.SH DESCRIPTION +.I Awk +scans each input +.I file +for lines that match any of a set of patterns specified literally in +.I prog +or in one or more files +specified as +.B -f +.IR progfile . +With each pattern +there can be an associated action that will be performed +when a line of a +.I file +matches the pattern. +Each line is matched against the +pattern portion of every pattern-action statement; +the associated action is performed for each matched pattern. +The file name +.L - +means the standard input. +Any +.IR file +of the form +.I var=value +is treated as an assignment, not a file name, +and is executed at the time it would have been opened if it were a file name. +The option +.B -v +followed by +.I var=value +is an assignment to be done before the program +is executed; +any number of +.B -v +options may be present. +.B -F +.IR fs +option defines the input field separator to be the regular expression +.IR fs . +.PP +An input line is normally made up of fields separated by white space, +or by regular expression +.BR FS . +The fields are denoted +.BR $1 , +.BR $2 , +\&..., while +.B $0 +refers to the entire line. +If +.BR FS +is null, the input line is split into one field per character. +.PP +To compensate for inadequate implementation of storage management, +the +.B -mr +option can be used to set the maximum size of the input record, +and the +.B -mf +option to set the maximum number of fields. +.PP +The +.B -safe +option causes +.I awk +to run in +``safe mode,'' +in which it is not allowed to +run shell commands or open files +and the environment is not made available +in the +.B ENVIRON +variable. +.PP +A pattern-action statement has the form +.IP +.IB pattern " { " action " } +.PP +A missing +.BI { " action " } +means print the line; +a missing pattern always matches. +Pattern-action statements are separated by newlines or semicolons. +.PP +An action is a sequence of statements. +A statement can be one of the following: +.PP +.EX +.ta \w'\fLdelete array[expression]'u +if(\fI expression \fP)\fI statement \fP\fR[ \fPelse\fI statement \fP\fR]\fP +while(\fI expression \fP)\fI statement\fP +for(\fI expression \fP;\fI expression \fP;\fI expression \fP)\fI statement\fP +for(\fI var \fPin\fI array \fP)\fI statement\fP +do\fI statement \fPwhile(\fI expression \fP) +break +continue +{\fR [\fP\fI statement ... \fP\fR] \fP} +\fIexpression\fP #\fR commonly\fP\fI var = expression\fP +print\fR [ \fP\fIexpression-list \fP\fR] \fP\fR[ \fP>\fI expression \fP\fR]\fP +printf\fI format \fP\fR[ \fP,\fI expression-list \fP\fR] \fP\fR[ \fP>\fI expression \fP\fR]\fP +return\fR [ \fP\fIexpression \fP\fR]\fP +next #\fR skip remaining patterns on this input line\fP +nextfile #\fR skip rest of this file, open next, start at top\fP +delete\fI array\fP[\fI expression \fP] #\fR delete an array element\fP +delete\fI array\fP #\fR delete all elements of array\fP +exit\fR [ \fP\fIexpression \fP\fR]\fP #\fR exit immediately; status is \fP\fIexpression\fP +.EE +.DT +.PP +Statements are terminated by +semicolons, newlines or right braces. +An empty +.I expression-list +stands for +.BR $0 . +String constants are quoted \&\fL"\ "\fR, +with the usual C escapes recognized within. +Expressions take on string or numeric values as appropriate, +and are built using the operators +.B + \- * / % ^ +(exponentiation), and concatenation (indicated by white space). +The operators +.B +! ++ \-\- += \-= *= /= %= ^= > >= < <= == != ?: +are also available in expressions. +Variables may be scalars, array elements +(denoted +.IB x [ i ] ) +or fields. +Variables are initialized to the null string. +Array subscripts may be any string, +not necessarily numeric; +this allows for a form of associative memory. +Multiple subscripts such as +.B [i,j,k] +are permitted; the constituents are concatenated, +separated by the value of +.BR SUBSEP . +.PP +The +.B print +statement prints its arguments on the standard output +(or on a file if +.BI > file +or +.BI >> file +is present or on a pipe if +.BI | cmd +is present), separated by the current output field separator, +and terminated by the output record separator. +.I file +and +.I cmd +may be literal names or parenthesized expressions; +identical string values in different statements denote +the same open file. +The +.B printf +statement formats its expression list according to the format +(see +.IR fprintf (2)) . +The built-in function +.BI close( expr ) +closes the file or pipe +.IR expr . +The built-in function +.BI fflush( expr ) +flushes any buffered output for the file or pipe +.IR expr . +If +.IR expr +is omitted or is a null string, all open files are flushed. +.PP +The mathematical functions +.BR exp , +.BR log , +.BR sqrt , +.BR sin , +.BR cos , +and +.BR atan2 +are built in. +Other built-in functions: +.TF length +.TP +.B length +If its argument is a string, the string's length is returned. +If its argument is an array, the number of subscripts in the array is returned. +If no argument, the length of +.B $0 +is returned. +.TP +.B rand +random number on (0,1) +.TP +.B srand +sets seed for +.B rand +and returns the previous seed. +.TP +.B int +truncates to an integer value +.TP +.B utf +converts its numerical argument, a character number, to a +.SM UTF +string +.TP +.BI substr( s , " m" , " n\fL) +the +.IR n -character +substring of +.I s +that begins at position +.IR m +counted from 1. +.TP +.BI index( s , " t" ) +the position in +.I s +where the string +.I t +occurs, or 0 if it does not. +.TP +.BI match( s , " r" ) +the position in +.I s +where the regular expression +.I r +occurs, or 0 if it does not. +The variables +.B RSTART +and +.B RLENGTH +are set to the position and length of the matched string. +.TP +.BI split( s , " a" , " fs\fL) +splits the string +.I s +into array elements +.IB a [1]\f1, +.IB a [2]\f1, +\&..., +.IB a [ n ]\f1, +and returns +.IR n . +The separation is done with the regular expression +.I fs +or with the field separator +.B FS +if +.I fs +is not given. +An empty string as field separator splits the string +into one array element per character. +.TP +.BI sub( r , " t" , " s\fL) +substitutes +.I t +for the first occurrence of the regular expression +.I r +in the string +.IR s . +If +.I s +is not given, +.B $0 +is used. +.TP +.B gsub +same as +.B sub +except that all occurrences of the regular expression +are replaced; +.B sub +and +.B gsub +return the number of replacements. +.TP +.BI sprintf( fmt , " expr" , " ...\fL) +the string resulting from formatting +.I expr ... +according to the +.I printf +format +.I fmt +.TP +.BI system( cmd ) +executes +.I cmd +and returns its exit status +.TP +.BI tolower( str ) +returns a copy of +.I str +with all upper-case characters translated to their +corresponding lower-case equivalents. +.TP +.BI toupper( str ) +returns a copy of +.I str +with all lower-case characters translated to their +corresponding upper-case equivalents. +.PD +.PP +The ``function'' +.B getline +sets +.B $0 +to the next input record from the current input file; +.B getline +.BI < file +sets +.B $0 +to the next record from +.IR file . +.B getline +.I x +sets variable +.I x +instead. +Finally, +.IB cmd " | getline +pipes the output of +.I cmd +into +.BR getline ; +each call of +.B getline +returns the next line of output from +.IR cmd . +In all cases, +.B getline +returns 1 for a successful input, +0 for end of file, and \-1 for an error. +.PP +Patterns are arbitrary Boolean combinations +(with +.BR "! || &&" ) +of regular expressions and +relational expressions. +Regular expressions are as in +.IR regexp (6). +Isolated regular expressions +in a pattern apply to the entire line. +Regular expressions may also occur in +relational expressions, using the operators +.BR ~ +and +.BR !~ . +.BI / re / +is a constant regular expression; +any string (constant or variable) may be used +as a regular expression, except in the position of an isolated regular expression +in a pattern. +.PP +A pattern may consist of two patterns separated by a comma; +in this case, the action is performed for all lines +from an occurrence of the first pattern +though an occurrence of the second. +.PP +A relational expression is one of the following: +.IP +.I expression matchop regular-expression +.br +.I expression relop expression +.br +.IB expression " in " array-name +.br +.BI ( expr , expr,... ") in " array-name +.PP +where a +.I relop +is any of the six relational operators in C, +and a +.I matchop +is either +.B ~ +(matches) +or +.B !~ +(does not match). +A conditional is an arithmetic expression, +a relational expression, +or a Boolean combination +of these. +.PP +The special patterns +.B BEGIN +and +.B END +may be used to capture control before the first input line is read +and after the last. +.B BEGIN +and +.B END +do not combine with other patterns. +.PP +Variable names with special meanings: +.TF FILENAME +.TP +.B CONVFMT +conversion format used when converting numbers +(default +.BR "%.6g" ) +.TP +.B FS +regular expression used to separate fields; also settable +by option +.BI \-F fs\f1. +.TP +.BR NF +number of fields in the current record +.TP +.B NR +ordinal number of the current record +.TP +.B FNR +ordinal number of the current record in the current file +.TP +.B FILENAME +the name of the current input file +.TP +.B RS +input record separator (default newline) +.TP +.B OFS +output field separator (default blank) +.TP +.B ORS +output record separator (default newline) +.TP +.B OFMT +output format for numbers (default +.BR "%.6g" ) +.TP +.B SUBSEP +separates multiple subscripts (default 034) +.TP +.B ARGC +argument count, assignable +.TP +.B ARGV +argument array, assignable; +non-null members are taken as file names +.TP +.B ENVIRON +array of environment variables; subscripts are names. +.PD +.PP +Functions may be defined (at the position of a pattern-action statement) thus: +.IP +.L +function foo(a, b, c) { ...; return x } +.PP +Parameters are passed by value if scalar and by reference if array name; +functions may be called recursively. +Parameters are local to the function; all other variables are global. +Thus local variables may be created by providing excess parameters in +the function definition. +.SH EXAMPLES +.TP +.L +length($0) > 72 +Print lines longer than 72 characters. +.TP +.L +{ print $2, $1 } +Print first two fields in opposite order. +.PP +.EX +BEGIN { FS = ",[ \et]*|[ \et]+" } + { print $2, $1 } +.EE +.ns +.IP +Same, with input fields separated by comma and/or blanks and tabs. +.PP +.EX + { s += $1 } +END { print "sum is", s, " average is", s/NR } +.EE +.ns +.IP +Add up first column, print sum and average. +.TP +.L +/start/, /stop/ +Print all lines between start/stop pairs. +.PP +.EX +BEGIN { # Simulate echo(1) + for (i = 1; i < ARGC; i++) printf "%s ", ARGV[i] + printf "\en" + exit } +.EE +.SH SOURCE +.B /sys/src/cmd/awk +.SH SEE ALSO +.IR sed (1), +.IR regexp (6), +.br +A. V. Aho, B. W. Kernighan, P. J. Weinberger, +.I +The AWK Programming Language, +Addison-Wesley, 1988. ISBN 0-201-07981-X +.SH BUGS +There are no explicit conversions between numbers and strings. +To force an expression to be treated as a number add 0 to it; +to force it to be treated as a string concatenate +\&\fL""\fP to it. +.br +The scope rules for variables in functions are a botch; +the syntax is worse. +.br +UTF is not always dealt with correctly, +though +.I awk +does make an attempt to do so. +The +.I split +function with an empty string as final argument now copes +with UTF in the string being split. diff --git a/sys/man/1/basename b/sys/man/1/basename new file mode 100755 index 000000000..c72638f13 --- /dev/null +++ b/sys/man/1/basename @@ -0,0 +1,35 @@ +.TH BASENAME 1 +.SH NAME +basename \- strip file name affixes +.SH SYNOPSIS +.B basename +[ +.B -d +] +.I string +[ +.I suffix +] +.SH DESCRIPTION +.PP +.I Basename +deletes any prefix ending in slash +.RB ( / ) +and the +.IR suffix , +if present in +.IR string , +from +.IR string , +and prints the result on the standard output. +.PP +The +.B -d +option instead prints the directory component, +that is, +.I string +up to but not including the final slash. +If the string contains no slash, +a period and newline are printed. +.SH SOURCE +.B /sys/src/cmd/basename.c diff --git a/sys/man/1/bc b/sys/man/1/bc new file mode 100755 index 000000000..87c2b1148 --- /dev/null +++ b/sys/man/1/bc @@ -0,0 +1,290 @@ +.TH BC 1 +.SH NAME +bc \- arbitrary-precision arithmetic language +.SH SYNOPSIS +.B bc +[ +.B -cdls +] +[ +.I file ... +] +.SH DESCRIPTION +.I Bc +is an interactive processor for a language that resembles +C but provides arithmetic on numbers of arbitrary length with up +to 100 digits right of the decimal point. +It takes input from any files given, then reads +the standard input. +.PP +The +.B -d +option enables debugging output. +The +.B -l +option stands for the name +of an arbitrary precision math library. +The +.B -s +option suppresses the automatic display +of calculation results; all output is via the +.B print +command. +.PP +The following syntax for +.I bc +programs is like that of C; +.I L +means letter +.BR a - z , +.I E +means expression, +.I S +means statement. +.TF length(E) +.TP +Lexical +.RS +.HP +comments are enclosed in +.B /* */ +.HP +newlines end statements +.RE +.TP +Names +.IP +simple variables: +.I L +.br +array elements: +.IB L [ E ] +.br +The words +.BR ibase , +.BR obase , +and +.B scale +.TP +Other operands +.IP +arbitrarily long numbers with optional sign and decimal point. +.RS +.TP +.BI ( E ) +.TP +.BI sqrt( E ) +.TP +.BI length( E ) +number of significant decimal digits +.TP +.BI scale( E ) +number of digits right of decimal point +.TP +.IB L ( E , ... ,\fIE\fP) +function call +.RE +.TP +Operators +.RS +.HP +.B "+ - * / % ^\ " +.RB ( % +is remainder; +.B ^ +is power) +.HP +.B "++ --\ " +.TP +.B "== <= >= != < >" +.TP +.B "= += -= *= /= %= ^=" +.RE +.TP +Statements +.RS +.br +.I E +.br +.B { +.I S +.B ; +\&... +.B ; +.I S +.B } +.br +.B "print" +.I E +.br +.B "if (" +.I E +.B ) +.I S +.br +.B "while (" +.I E +.B ) +.I S +.br +.B "for (" +.I E +.B ; +.I E +.B ; +.I E +.B ")" +.I S +.br +null statement +.br +.B break +.br +.B quit +.br +\fL"\fRtext\fL"\fR +.RE +.TP +Function definitions +.RS +.br +.B define +.I L +.B ( +.I L +.B , +\&... +.B , +.I L +.B ){ +.PD0 +.br +.B auto +.I L +.B , +\&... +.B , +.I L +.br +.I S +.B ; +\&... +.B ; +.I S +.br +.B return +.I E +.LP +.B } +.RE +.TP +Functions in +.B -l +math library +.RS +.TP +.BI s( x ) +sine +.TP +.BI c( x ) +cosine +.TP +.BI e( x ) +exponential +.TP +.BI l( x ) +log +.TP +.BI a( x ) +arctangent +.TP +.BI j( "n, x" ) +Bessel function +.RE +.PP +.DT +All function arguments are passed by value. +.PD +.PP +The value of an expression at the top level is printed +unless the main operator is an assignment or the +.B -s +command line argument is given. +Text in quotes, which may include newlines, is always printed. +Either semicolons or newlines may separate statements. +Assignment to +.B scale +influences the number of digits to be retained on arithmetic +operations in the manner of +.IR dc (1). +Assignments to +.B ibase +or +.B obase +set the input and output number radix respectively. +.PP +The same letter may be used as an array, a function, +and a simple variable simultaneously. +All variables are global to the program. +Automatic variables are pushed down during function calls. +In a declaration of an array as a function argument +or automatic variable +empty square brackets must follow the array name. +.PP +.I Bc +is actually a preprocessor for +.IR dc (1), +which it invokes automatically, unless the +.B -c +(compile only) +option is present. +In this case the +.I dc +input is sent to the standard output instead. +.SH EXAMPLE +Define a function to compute an approximate value of +the exponential. +Use it to print 10 values. +(The exponential function in the library gives better answers.) +.PP +.EX +scale = 20 +define e(x) { + auto a, b, c, i, s + a = 1 + b = 1 + s = 1 + for(i=1; 1; i++) { + a *= x + b *= i + c = a/b + if(c == 0) return s + s += c + } +} +for(i=1; i<=10; i++) print e(i) +.EE +.SH FILES +.B /sys/lib/bclib +mathematical library +.SH SOURCE +.B /sys/src/cmd/bc.y +.SH "SEE ALSO" +.IR dc (1), +.IR hoc (1) +.SH BUGS +No +.LR && , +.LR || , +or +.L ! +operators. +.PP +A +.L for +statement must have all three +.LR E s. +.PP +A +.L quit +is interpreted when read, not when executed. diff --git a/sys/man/1/bind b/sys/man/1/bind new file mode 100755 index 000000000..7994f7192 --- /dev/null +++ b/sys/man/1/bind @@ -0,0 +1,215 @@ +.TH BIND 1 +.SH NAME +bind, mount, unmount \- change name space +.SH SYNOPSIS +.B bind +[ +.I option ... +] +.I new old +.PP +.B mount +[ +.I option ... +] +.I servename old +[ +.I spec +] +.PP +.B unmount +[ +.I new +] +.I old +.SH DESCRIPTION +.I Bind +and +.I mount +modify the file name space of the current process +and other processes in the same name space group +(see +.IR fork (2)). +For both calls, +.I old +is the name of an existing file or directory in the +current name space where the modification is to be made. +.PP +For +.IR bind , +.I new +is the name of another (or possibly the same) +existing file or directory in +the current name space. +After a successful +.IR bind , +the file name +.I old +is an alias for the object originally named by +.IR new ; +if the modification doesn't hide it, +.I new +will also still refer to its original file. +The evaluation of +.I new +(see +.IR intro (2)) +happens at the time of the +.IR bind , +not when the binding is later used. +.PP +The +.I servename +argument to +.I mount +is the name of a file that, when opened, yields an +existing connection to a file server. +Almost always, +.I servename +will be a file in +.B /srv +(see +.IR srv (3)). +In the discussion below, +.I new +refers to the file named by the +.I new +argument to +.I bind +or the root directory of the service +available in +.I servename +after a +.IR mount . +Either both +.I old +and +.I new +files must be directories, +or both must not be directories. +.PP +Options control aspects of the modification to the name space: +.TP 10 +(none) +Replace the +.I old +file by the new one. +Henceforth, an evaluation of +.I old +will be translated to the new file. +If they are directories (for +.IR mount , +this condition is true by definition), +.I old +becomes a +.I "union directory" +consisting of one directory (the new file). +.TP +.B -b +Both files must be directories. +Add the new directory to the beginning +of the union directory represented by the old file. +.TP +.B -a +Both files must be directories. +Add the new directory to the end +of the union directory represented by the old file. +.TP +.B -c +This can be used in addition to any of the above to permit +creation in a union directory. +When a new file is created in a union directory, +it is placed in the first element of the union that has been bound or mounted with the +.B -c +flag. +If that directory does not have write permission, the create fails. +.TP +.B -C +(Only in +.IR mount .) +By default, file contents are always retrieved from the server. +With this option, the kernel may instead use a local cache to satisfy +.IR read (5) +requests for files accessible through this mount point. +The currency of cached data for a file is verified at each +.IR open (5) +of the file from this client machine. +.TP +.B -q +Exit silently if the +.B bind +or +.B mount +operation fails. +.PD +.PP +.I Mount +takes two additional options. +The first, +.B -k +.IR keypattern , +constrains the set of +.IR factotum (4) +keys used for an authenticated mount. +The second, +.BR -n , +causes +.I mount +to skip authentication entirely. +.PP +The +.I spec +argument to +.I mount +is passed in the +.IR attach (5) +message to the server, and selects among different +file trees served by the server. +.PP +The +.IR srv (3) +service registry device, normally bound to +.BR /srv , +is a convenient rendezvous point for services that can be mounted. +After bootstrap, the file +.B /srv/boot +contains the communications port to the file system from which +the system was loaded. +.PP +The effects of +.I bind +and +.I mount +can be undone with the +.I unmount +command. +If two arguments are given to +.IR unmount , +the effect is to undo a +.I bind +or +.I mount +with the same arguments. +If only one argument is given, +everything bound to or mounted upon +.I old +is unmounted. +.SH EXAMPLES +To compile a program with the C library from July 16, 1992: +.IP +.EX +mount /srv/boot /n/dump dump +bind /n/dump/1992/0716/mips/lib/libc.a /mips/lib/libc.a +mk +.EE +.SH SOURCE +.B /sys/src/cmd/bind.c +.br +.B /sys/src/cmd/mount.c +.br +.B /sys/src/cmd/unmount.c +.SH SEE ALSO +.IR bind (2), +.IR open (2), +.IR srv (3), +.IR srv (4) diff --git a/sys/man/1/bitsyload b/sys/man/1/bitsyload new file mode 100755 index 000000000..e9c464614 --- /dev/null +++ b/sys/man/1/bitsyload @@ -0,0 +1,146 @@ +.TH BITSYLOAD 1 +.SH NAME +bitsyload, light, pencal, keyboard, params, prompter \- bitsy-specific utilities +.SH SYNOPSIS +.PP +.B bitsy/bitsyload +.B k|r +[ +.I file +] +.PP +.B bitsy/light +[ +.I intensity +] +.PP +.B bitsy/params +[ +.B \-f +] +.PP +.B bitsy/pencal +.PP +.B bitsy/keyboard +[ +.B \-n +] +.PP +.B bitsy/prompter +[ +.B \-n +] +.I file +.SH DESCRIPTION +.PP +.I Bitsyload +erases a section of flash memory on the Bitsy (iPAQ 3650 or 3830) +and copies new +information into it, using the format required by the Compaq +boot loader. The required first argument is the destination, either +.B k +for +.B /dev/flash/kernel +or +.B r +for +.BR /dev/flash/ramdisk . +The optional second argument is the name of the file +to load. The default kernel file is +.B /sys/src/9/bitsy/9bitsy +and the default ramdisk file is +.BR /sys/src/9/bitsy/ramdisk . +.PP +.I Light +sets the intensity of the display backlight. +The +values for +.I intensity +are: +.IP on +set intensity to maximum, the default +.IP off +turn off backlight +.IP \fIn\fP +sets the intensity to +.IR n , +where +.I n +is a value between 0 and 128. Intensity 0 doesn't +turn off the backlight, it just sets it to the dimmest +value. +.PP +.I Pencal +calibrates the display with the touch screen on a Bitsy. +It loops prompting the user with crosses whose center that the user +must touch with the stylus. After a consistent set of touches, +it writes the calibration both to the kernel and to standard out. +It is normally called by the bitsy's +.BR /bin/cpurc . +.PP +.I Params +copies the contents of the file +.BR /dev/tmpparams , +into the flash partition, +.BR /dev/flash/params , +or if the +.B -f +flag it set copies in the opposite direction. +.PP +.I Keyboard +creates a virtual on-screen keyboard and, unless the +.B -n +option is specified, a scribble area. +A user inputs characters by tapping the keys or +by drawing characters in the +scribble area (see +.IR scribble (2)). +It is usually run as the keyboard command for +.IR rio (1) +using +.BR rio 's +.B -k +option. +.PP +.I Prompter +is a small editor used to configure parameters when a Bitsy boots. +It displays the file and starts up a keyboard and scribble pad for +input. +Clicking with the stylus in the text selects where input characters will go. +Pressing Button 5 (top left side of the Bitsy) or typing the +.B Esc +key on the keyboard causes +.I prompter +to write back the updated file and exit; +.B Del +causes +.I prompter +to exit without writing the file. +The +.B -n +flag suppresses the scribble area. +.SH EXAMPLE +.PP +.IR Prompter , +.IR params , +and +.I calibrate +are used in only one place, the Bitsy's +.BR /rc/bin/cpurc : +.sp +.EX +# set variables +ramfs +bitsy/params -f +if(! grep -s '^calibrate=' /tmp/tmpparams) + bitsy/pencal >>/tmp/tmpparams +if not { + eval `{grep '^calibrate=' /tmp/tmpparams} + echo calibrate $calibrate > '#m/mousectl' +} +bitsy/prompter /tmp/tmpparams +bitsy/params +. /tmp/tmpparams +.EE +.SH SOURCE +.B /sys/src/cmd/bitsy diff --git a/sys/man/1/bundle b/sys/man/1/bundle new file mode 100755 index 000000000..272d32530 --- /dev/null +++ b/sys/man/1/bundle @@ -0,0 +1,53 @@ +.TH BUNDLE 1 +.SH NAME +bundle \- collect files for distribution +.SH SYNOPSIS +.B bundle +.I file ... +.SH DESCRIPTION +.I Bundle +writes on its standard output a shell script for +.IR rc (1) +or a Bourne shell +which, when executed, +will recreate the original +.IR files . +Its main use is for distributing small numbers of text files by +.IR mail (1). +.PP +Although less refined than standard archives from +.IR ar (1) +or +.IR tar (1), +a +.IR bundle +file +is self-documenting and complete; little preparation is required on +the receiving machine. +.SH EXAMPLES +.TP +.L +bundle mkfile *.[ch] | mail kremvax!boris +Send a makefile to Boris together with related +.L .c +and +.L .h +files. +Upon receiving the mail, Boris may save the file sans postmark, +say in +.BR gift/horse , +then do +.TP +.L +cd gift; rc horse; mk +.SH SOURCE +.B /rc/bin/bundle +.SH SEE ALSO +.IR ar (1), +.IR tar (1), +.IR mail (1) +.SH BUGS +.I Bundle +will not create directories and is unsatisfactory for non-text files. +.PP +Beware of gift horses. diff --git a/sys/man/1/cal b/sys/man/1/cal new file mode 100755 index 000000000..a821f1e5c --- /dev/null +++ b/sys/man/1/cal @@ -0,0 +1,46 @@ +.TH CAL 1 +.SH NAME +cal \- print calendar +.SH SYNOPSIS +.B cal +[ +.I month +] +[ +.I year +] +.SH DESCRIPTION +.I Cal +prints a calendar. +.I Month +is either a number from 1 to 12, +a lower case month name, +or a lower case three-letter prefix of a month name. +.I Year +can be between 1 +and 9999. +If either +.I month +or +.I year +is omitted, the current month or year is used. +If only one argument is given, and it is a number larger than 12, +a calendar for all twelve months of the given year is produced; +otherwise a calendar for just one month is printed. +The calendar +produced is that for England and her colonies. +.PP +Try +.EX + cal sep 1752 +.EE +.SH SOURCE +.B /sys/src/cmd/cal.c +.SH BUGS +The year is always considered to start in January even though this +is historically naive. +.PP +Beware that +.L "cal 90" +refers to the early Christian era, +not the 20th century. diff --git a/sys/man/1/calendar b/sys/man/1/calendar new file mode 100755 index 000000000..c671dedf9 --- /dev/null +++ b/sys/man/1/calendar @@ -0,0 +1,62 @@ +.TH CALENDAR 1 +.SH NAME +calendar \- print upcoming events +.SH SYNOPSIS +.B calendar +[ +.B -dy +] +[ +.B -p +.I days +] +[ +.I file ... +] +.SH DESCRIPTION +.I Calendar +reads the named files, default +.BR /usr/$user/lib/calendar , +and writes to standard output any lines +containing today's or tomorrow's date. +Examples of recognized date formats are +"4/11", +"April 11", +"Apr 11", +"11 April", +and +"11 Apr". +A special form may be used to represent weekly and +monthly events: +"Every Tuesday" +"The third Wednesday" +All comparisons are case insensitive. +.PP +If the +.B -y +flag is given, an attempt is made to match on year too. In this case, +dates of the forms listed above will be accepted if they are followed +by the current year (or last two digits thereof) or not a year — +digits not followed by white space or non-digits. +.PP +If the +.B -p +flag is given, its argument is the number of days ahead to match +dates. This flag is not repeatable, and it performs no special +processing at the end of the week. +.PP +The +.B -d +flag enables debugging output. +.PP +On Friday and Saturday, events through Monday are printed. +.PP +To have your calendar mailed to you every day, use +.IR cron (8). +.SH FILES +.TF /usr/$user/lib/calendar +.TP +.B /usr/$user/lib/calendar +personal calendar +.SH SOURCE +.B /sys/src/cmd/calendar.c diff --git a/sys/man/1/cat b/sys/man/1/cat new file mode 100755 index 000000000..837feb7ae --- /dev/null +++ b/sys/man/1/cat @@ -0,0 +1,87 @@ +.TH CAT 1 +.SH NAME +cat, read \- catenate files +.SH SYNOPSIS +.B cat +[ +.I file ... +] +.br +.B read +[ +.B -m +] [ +.B -n +.I nline +] [ +.I file ... +] +.SH DESCRIPTION +.I Cat +reads each +.I file +in sequence and writes it on the standard output. +Thus +.IP +.L +cat file +.LP +prints a file and +.IP +.L +cat file1 file2 >file3 +.LP +concatenates the first two files and places the result +on the third. +.PP +If no +.I file +is given, +.I cat +reads from the standard input. +Output is buffered in blocks matching the input. +.PP +.I Read +copies to standard output exactly one line from the named +.IR file , +default standard input. +It is useful in interactive +.IR rc (1) +scripts. +.PP +The +.B -m +flag causes it to continue reading and writing multiple lines until end of file; +.B -n +causes it to read no more than +.I nline +lines. +.PP +.I Read +always executes a single +.B write +for each line of input, which can be helpful when +preparing input to programs that expect line-at-a-time data. +It never reads any more data from the input than it prints to the output. +.SH SOURCE +.B /sys/src/cmd/cat.c +.br +.B /sys/src/cmd/read.c +.SH SEE ALSO +.IR cp (1) +.SH DIAGNOSTICS +.I Read +exits with status +.B eof +on end of file or, in the +.B -n +case, if it doesn't read +.I nlines +lines. +.SH BUGS +Beware of +.L "cat a b >a" +and +.LR "cat a b >b" , +which +destroy input files before reading them. diff --git a/sys/man/1/cb b/sys/man/1/cb new file mode 100755 index 000000000..b5eed691e --- /dev/null +++ b/sys/man/1/cb @@ -0,0 +1,46 @@ +.TH CB 1 +.SH NAME +cb \- C program beautifier +.SH SYNOPSIS +.B cb +[ +.B -js +] +[ +.B -l +.I length +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Cb +reads syntactically correct C programs from +from its input or the given files, and writes them to its stdout +with a more visually pleasing spacing and indentation. +.I Cb +understands no C++ syntax bar newline-terminated comments; +and by default all user new-lines are preserved in the output. +.PP +The options are: +.TP +.B -j +Join split lines. +.TP +.B -s +Print code in the so-called K&R style used in +.IR "The C Programming Language" . +.TP +.B -l length +Split lines that are longer than +.IR length . +.PD +.SH SOURCE +.B /sys/src/cmd/cb +.SH BUGS +.I Cb +does not reformat structure initializers. +.br +Punctuation hidden in macros can cause +indentation errors. diff --git a/sys/man/1/chgrp b/sys/man/1/chgrp new file mode 100755 index 000000000..f1924773f --- /dev/null +++ b/sys/man/1/chgrp @@ -0,0 +1,36 @@ +.TH CHGRP 1 +.SH NAME +chgrp \- change file group +.SH SYNOPSIS +.B chgrp +[ +.B -ou +] +.I group file ... +.SH DESCRIPTION +The group of +each named file +is changed to +.IR group , +which should be a name known to the server holding the file. +.PP +A file's group can be changed by the file's owner, if the +owner is a member of the new group, +or by the leader of both +the file's current group and the new group. +.PP +The +.B -o +and +.B -u +option are synonyms; they specify that the +.I owner +is to be set, rather than the group. +They are ineffectual unless the file server is in the bootstrap +state that permits changing file ownership. +.SH SOURCE +.B /sys/src/cmd/chgrp.c +.SH "SEE ALSO" +.IR ls (1), +.IR chmod (1), +.IR stat (2) diff --git a/sys/man/1/chmod b/sys/man/1/chmod new file mode 100755 index 000000000..a5c80b677 --- /dev/null +++ b/sys/man/1/chmod @@ -0,0 +1,106 @@ +.TH CHMOD 1 +.SH NAME +chmod \- change mode +.SH SYNOPSIS +.B chmod +.I mode file ... +.SH DESCRIPTION +The mode of +each named file +is changed +according to +.IR mode, +which may be an octal number or a symbolic change to the existing mode. +A +.I mode +is an octal +number constructed +from the OR of the +following modes. +.TF 0000 +.TP +0400 +read by owner +.TP +0200 +write by owner +.TP +0100 +execute (search in directory) by owner +.TP +0070 +read, write, execute (search) by group +.TP +0007 +read, write, execute (search) by others +.PD +.PP +A symbolic +.I mode +has the form: +.IP +.RI [who] +.I op permission +.PP +The +.I who +part is a combination +of the letters +.B u +(for user's permissions), +.B g +(group) +and +.B o +(other). +The letter +.B a +stands for +.BR ugo . +If +.I who +is omitted, +the default is +.BR a . +.PP +.I Op +can be +.B + +to add +.I permission +to the file's mode, +.B - +to take away +.IR permission , +and +.B = +to assign +.I permission +absolutely +(all other bits will +be reset). +.PP +.I Permission +is any combination of the letters +.B r +(read), +.B w +(write), +.B x +(execute), +.B a +(append only), +.B l +(exclusive access), +and +.B t +(temporary file). +.PP +Only the owner of a file or the group leader of its group +may change the file's mode. +.SH SOURCE +.B /sys/src/cmd/chmod.c +.SH "SEE ALSO" +.IR ls (1), +.IR stat (2), +.IR stat (5) diff --git a/sys/man/1/cleanname b/sys/man/1/cleanname new file mode 100755 index 000000000..41c06c00e --- /dev/null +++ b/sys/man/1/cleanname @@ -0,0 +1,32 @@ +.TH CLEANNAME 1 +.SH NAME +cleanname \- clean a path name +.SH SYNOPSIS +.B cleanname +[ +.B -d +.I pwd +] +.I names ... +.SH DESCRIPTION +For each file name argument, +.IR cleanname , +by lexical processing only, +prints the shortest equivalent string that names the same +(possibly hypothetical) file. +It eliminates multiple and trailing slashes, and it lexically +interprets +.B . +and +.B .. +directory components in the name. +If the +.B -d +option is present, +unrooted names are prefixed with +.IB pwd / +before processing. +.SH SOURCE +.B /sys/src/cmd/cleanname.c +.SH SEE ALSO +.IR cleanname (2). diff --git a/sys/man/1/cmp b/sys/man/1/cmp new file mode 100755 index 000000000..55888ce97 --- /dev/null +++ b/sys/man/1/cmp @@ -0,0 +1,57 @@ +.TH CMP 1 +.SH NAME +cmp \- compare two files +.SH SYNOPSIS +.B cmp +[ +.B -lLs +] +.I file1 file2 +[ +.I offset1 +[ +.I offset2 +] +] +.SH DESCRIPTION +.I Cmp +compares the two files and prints +a message if the contents differ. +.PP +The options are: +.TP +.B -l +Print the byte number (decimal) and the +differing bytes (hexadecimal) for each difference. +.TP +.B -L +Print the line number of the first differing byte. +.TP +.B -s +Print nothing for differing files, +but set the exit status. +.PD +.PP +If offsets are given, +comparison starts at the designated byte position +of the corresponding file. +Offsets that begin with +.B 0x +are hexadecimal; +with +.BR 0 , +octal; with anything else, decimal. +.SH SOURCE +.B /sys/src/cmd/cmp.c +.SH SEE ALSO +.IR diff (1) +.SH DIAGNOSTICS +If a file is inaccessible or missing, the exit status is +.LR open . +If the files are the same, the exit status is empty (true). +If they are the same except that one is longer than the other, the exit status is +.LR EOF . +Otherwise +.I cmp +reports the position of the first disagreeing byte and the exit status is +.LR differ . diff --git a/sys/man/1/col b/sys/man/1/col new file mode 100755 index 000000000..6fb03081a --- /dev/null +++ b/sys/man/1/col @@ -0,0 +1,55 @@ +.TH COL 1 +.SH NAME +col \- column alignment +.SH SYNOPSIS +.B col +[ +.B -bfx +] +.SH DESCRIPTION +.I Col +overlays lines to expunge reverse line feeds +(ESC-7) +and half line feeds (ESC-9 and ESC-8) +as produced by +.I nroff +for .2C in +.IR ms (6) +or +.IR man (6) +and for +.IR tbl (1). +.I Col +is a pure filter. +It normally emits only full line feeds; +option +.B -f +(fine) allows half line feeds too. +Option +.B -b +removes backspaces, printing just one of each pile of overstruck +characters. +.I Col +normally converts white space to tabs; +option +.B -x +overrides this feature. +Other escaped characters and non-printing characters are ignored. +.SH EXAMPLES +.TP +.L +tbl file | nroff -ms | col | p +Format some tables for printing on typewriters; +use +.I col +to remove reverse line feeds, and +paginate the output. +.SH SEE ALSO +.IR pr (1) +.SH BUGS +.I Col +can't back up more than 128 lines or +handle more than 800 characters per line, +and understands +.L VT +(013) as reverse line feed. diff --git a/sys/man/1/colors b/sys/man/1/colors new file mode 100755 index 000000000..67a096a3d --- /dev/null +++ b/sys/man/1/colors @@ -0,0 +1,72 @@ +.TH COLORS 1 +.SH NAME +getmap, colors \- display color map +.SH SYNOPSIS +.PP +.B colors +[ +.B -rx +] +.PP +.B getmap +[ +.I colormap +] +.SH DESCRIPTION +.I Colors +presents a grid showing the colors in the current color map. +If the display is true color, +.I colors +shows a grid of the RGBV color map +(see +.IR color (6)). +.PP +Clicking mouse button 1 over a color in the grid will display the map index for that color, +its +red, green, and blue components, +and the 32-bit hexadecimal color value as defined in +.IR allocimage (2). +If the +.B -x +option is specified, the components will also be listed in hexadecimal. +.PP +The +.B -r +option instead shows, in the same form, a grey-scale ramp. +.PP +A menu on mouse button 3 contains a single entry, to exit the program. +.PP +On 8-bit color-mapped displays, +.I getmap +loads the display's color map (default +.BR rgbv ). +The named +.I colormap +can be a file in the current directory or in the standard repository +.BR /lib/cmap . +It can also be a string of the form +.B gamma +or +.BI gamma N\f1 , +where +.I N +is a floating point value for the gamma, defining the contrast for a monochrome map. +Similarly, +.B rgamma +and +.BI rgamma N +define a reverse-video monochrome map. +Finally, the names +.B screen +or +.B display +or +.B vga +are taken as synonyms for the current color map stored in the display hardware. +.SH FILES +.B /lib/cmap +directory of color map files +.SH SOURCE +.B /sys/src/cmd/colors.c +.SH SEE ALSO +.IR color (6) diff --git a/sys/man/1/comm b/sys/man/1/comm new file mode 100755 index 000000000..2fd883c05 --- /dev/null +++ b/sys/man/1/comm @@ -0,0 +1,47 @@ +.TH COMM 1 +.CT 1 files +.SH NAME +comm \- select or reject lines common to two sorted files +.SH SYNOPSIS +.B comm +[ +.B -123 +] +.I file1 file2 +.SH DESCRIPTION +.I Comm +reads +.I file1 +and +.IR file2 , +which are in lexicographical order, +and produces a three column output: lines only in +.IR file1 ; +lines only in +.IR file2 ; +and lines in both files. +The file name +.L - +means the standard input. +.PP +Flag +.LR 1 , +.LR 2 , +or +.LR 3 +suppresses printing of the corresponding +column. +.SH EXAMPLE +.TP +.EX +comm -12 file1 file2 +.EE +.IP +Print lines common to two sorted files. +.SH SOURCE +.B /sys/src/cmd/comm.c +.SH "SEE ALSO" +.IR sort (1), +.IR cmp (1), +.IR diff (1), +.IR uniq (1) diff --git a/sys/man/1/con b/sys/man/1/con new file mode 100755 index 000000000..44c91b01b --- /dev/null +++ b/sys/man/1/con @@ -0,0 +1,315 @@ +.TH CON 1 +.SH NAME +con, telnet, rx, hayes, xms, xmr \- remote login, execution, and XMODEM file transfer +.SH SYNOPSIS +.B con +[ +.B -CdnrRsTv +] +[ +.B -b +.I baud +] +[ +.B -l +[ +.I user +] +] +[ +.B -S +.I svc +] +[ +.B -c +.I cmd +] +.RI [ net !] machine +.PP +.B telnet +[ +.B -dCrn +] +[ +.B -s +.I svc +] +.RI [ net !] machine +.PP +.B rx +[ +.B -eTr +] +[ +.B -l +.I user +] +.RI [ net !] machine +[ +.I command-word ... +] +.PP +.B hayes +[ +.B -pv +] +.I number +[ +.I device +] +.PP +.B xms +[ +.B -1p +] +.I file +.PP +.B xmr +.I file +.SH DESCRIPTION +.I Con +connects to the computer whose network address is +.IR net ! machine +and logs in if possible. +With no options, the account name used on the remote system is the same +as that on the local system. +Standard input and output go to the local machine. +.PP +Options are: +.TP +.B -b +sets the baud rate of a dial-up connection to +.IR baud . +.TP +.B -n +if the input is a file or pipe, do not hang up the connection when EOF is received, +but instead wait for the remote end to hang up. +.TP +.B -l +with an argument causes +.I user +to be used as the account name on the remote system +when performing BSD +.I rlogin +authentication. +Without an argument this option disables automatic login +and a normal login session ensues. +.TP +.B -C +forces cooked mode, that is, local echo. +.TP +.B -c +runs +.I cmd +as if it had been typed as a command from the escape mode. +.TP +.B -v +(verbose mode) causes information about connection attempts +to be output to standard error. This can be useful when +trying to debug network connectivity. +.TP +.B -d +causes debugging information to be output to standard error. +.TP +.B -r +suppresses printing of any carriage return followed by a new line. +This is useful since carriage return is a printable character in +Plan 9. +.TP +.B -R +translates newlines to carriage returns and +.IR "vice versa" . +.TP +.B -T +translates incoming carriage returns to newlines. +.TP +.B -s +strips received characters to 7 bits to forestall +misinterpretation of +.SM ASCII +with parity as +.SM UTF\c +\&. +.TP +.B -S +Post a pipe as +.BI /srv/ svc +and connect it to standard input and output. +This can be used with +.B -n +to create a standing connection that +.IR consolefs (4), +for example, +can then open. +For +.IR telnet , +this option is +.BR -s . +.PP +The +.RB control\- \e +character is a local escape. +It prompts with +.BR >>> . +Legitimate responses to the prompt are +.TP +.B i +Send a quit [sic] signal to the remote machine. +.PD0 +.TP +.B q +Exit. +.TP +.B b +Send a break. +.TP +.B . +Return from the escape. +.TP +.B !cmd +Run the command with the network connection as its +standard input and standard output. +Standard error will go to the screen. +This is useful for transmitting and receiving files +over the connections using programs such as +.IR xms . +.TP +.B r +Toggle printing of carriage returns. +.PD +.PP +.I Telnet +is similar to con, but uses the +.I telnet +protocol to communicate with the remote machine. +It shares +.I con's +.BR -C , +.BR -d , +.BR -n , +and +.BR -r +options. +.PP +.I Rx +executes one shell command +on the remote machine as if logged in there, +but with local standard input and output. +A rudimentary shell environment is provided. +If the target is a Plan 9 machine, +.B $service +there will be +.BR rx . +Options are: +.TP +.B \-e +a zero length message will not be written to the +connection when standard input is closed. +.TP +.B \-l +runs as +.I user +on the remote machine if the remote is a BSD machine. +.TP +.B \-r +same as for +.I con +.TP +.B -T +same as for +.I con +.PD +.PP +Network addresses for both +.I con +and +.I rx +have the form +.IB network ! machine\f1. +Supported networks are those listed in +.BR /net . +.PP +.I Hayes +dials +.I number +on a Hayes-compatible modem, +.IR device . +Under +.BR -p , +it uses pulse dialing. +Upon connecting, +bytes are copied bidirectionally +between the connection and standard input and output. +.PP +The commands +.I xms +and +.I xmr +respectively send and receive a single file using the +XMODEM protocol. +They use standard input and standard output for communication +and are intended for use with +.IR con . +The +.B -1 +option to +.I xms +causes it to use kilobyte packet size of 1024 bytes. +The +.B -p +option causes it to print a progress +message every ten kilobytes. +.SH EXAMPLES +.TP +.L +rx kremvax cat file1 >file2 +Copy remote +.I file1 +to local +.IR file2 . +.TP +.L +rx kremvax cat file1 '>file2' +Copy remote +.I file1 +to remote +.IR file2. +.TP +.L +eqn paper | rx kremvax troff -ms | rx deepthought lp +Parallel processing: +do each stage of a pipeline on a different machine. +.SH SOURCE +.TF /sys/src/cmd/ip/telnet.c +.TP +.B /sys/src/cmd/rx.c +.TP +.B /sys/src/cmd/ip/telnet.c +.TP +.B /sys/src/cmd/con +for all other commands +.SH SEE ALSO +.IR cpu (1), +.IR ssh (1), +.IR telco (4) +.SH BUGS +.I Con +and +.I telnet +are merely obsolescent; +the other commands are obsolete and deprecated. +.PP +Under +.IR rx , +a program +that should behave specially towards terminals may not: e.g., +remote shells will not prompt. +Also under +.IR rx , +the remote standard error and standard output are combined +and go inseparably to the local standard output. +.I Rx +will consume its standard input by copying it to the remote system, +so redirect it from +.BR /dev/null +if that's not what you want. diff --git a/sys/man/1/cp b/sys/man/1/cp new file mode 100755 index 000000000..ba84be3a3 --- /dev/null +++ b/sys/man/1/cp @@ -0,0 +1,130 @@ +.TH CP 1 +.SH NAME +cp, fcp, mv \- copy, move files +.SH SYNOPSIS +.B cp +[ +.B -gux +] +.I file1 file2 +.br +.B cp +[ +.B -gux +] +.I file ... directory +.PP +.B fcp +[ +.B -gux +] +.I file1 file2 +.br +.B fcp +[ +.B -gux +] +.I file ... directory +.PP +.B mv +.I file1 file2 +.br +.B mv +.I file ... directory +.SH DESCRIPTION +In the first form +.I file1 +is any name and +.I file2 +is any name except an existing directory. +In the second form the commands +copy or move one or more +.I files +into a +.I directory +under their original file names, as if by a sequence of +commands in the first form. +Thus +.L "cp f1 f2 dir +is equivalent to +.LR "cp f1 dir/f1; cp f2 dir/f2" . +.PP +.I Cp +copies the contents of plain +.I file1 +to +.IR file2 . +The mode and owner of +.I file2 +are preserved if it already +exists; the mode of +.I file1 +is used otherwise. +The +.B -x +option sets the mode and modified time of +.I file2 +from +.IR file1 ; +.B -g +sets the group id; and +.B -u +sets the group id and user id (which is usually only possible if the file server is in an administrative mode). +.PP +.I Fcp +behaves like +.I cp +but transfers multiple blocks in parallel while copying; +it is noticeably faster than +.I cp +when the files involved are stored on servers connected over long-distance lines. +It is only appropriate to use +.I fcp +with file servers that respect the +.I offset +in +.IR read (5) +and +.I write +messages. +This includes the disk-based file systems and ramfs +but excludes most device file systems. +.PP +.I Mv +moves +.I file1 +to +.IR file2 . +If the files are in the same directory, +.I file1 +is just renamed; +otherwise +.I mv +behaves like +.I cp +.B -x +followed by +.B rm +.IR file1 . +.I Mv +will rename directories, +but it refuses to move a directory into another directory. +.SH SOURCE +.B /sys/src/cmd/cp.c +.br +.B /sys/src/cmd/fcp.c +.br +.B /sys/src/cmd/mv.c +.SH "SEE ALSO" +.IR cat (1), +.I dircp +in +.IR tar (1), +.IR stat (2), +.IR read (5) +.SH DIAGNOSTICS +.IR Cp , +.IR fcp , +and +.I mv +refuse to copy or move files onto themselves. diff --git a/sys/man/1/cpp b/sys/man/1/cpp new file mode 100755 index 000000000..3fc931585 --- /dev/null +++ b/sys/man/1/cpp @@ -0,0 +1,119 @@ +.TH CPP 1 +.SH NAME +cpp \- C language preprocessor +.SH SYNOPSIS +.B cpp +[ +.I option ... +] +[ +.I ifile +[ +.I ofile +] +] +.SH DESCRIPTION +.I Cpp\^ +interprets ANSI C preprocessor directives +and does macro substitution. +The input +.I ifile +and output +.I ofile +default to standard input and standard output respectively. +.PP +The options are: +.TP +.BI -D name\^ +.PD 0 +.TP +.BI -D name=def\^ +.TP +.BI -I dir\^ +Same as in +.IR 2c "(1): add +.I dir +to the search for +.CW search +directives. +.PD +.TP +.B -M +Generate no output except a list of include files +in a form suitable for specifying dependencies to +.IR mk (1). +Use twice to list files in angle brackets. +.TP +.B -N +Turn off default include directories. All must be +specified with +.BR -I , +or in the environment variable +.BR include . +Without this option, +.B /$objtype/include +and +.B /sys/include +are used as the last two searched directories for include directives, +where +.B $objtype +is read from the environment. +.TP +.B -V +Print extra debugging information. +.TP +.B -P +Do not insert +.RB `` #line '' +directives into the output. +.TP +.B -+ +Understand C++ comments. +.TP +.B -. +Inhibit include search in the source's directory. +.TP +.B -i +Print the list of directories searched when +.I #include +is found. +Last listed are searched first. +.PD +.PP +In the absence of the +.B -P +option, the processed text output is sprinkled +with lines that show the original input line numbering: +.IP +.B #line +.I linenumber +.L +"\fIifile\fP" +.PP +The command reads the environment variable +.IR include +and adds its (blank-separated) list of directories to +the standard search path for +.CW #include +directives. They are looked at before any directories specified with +.BR -I , +which are looked at before the default directories. +.PP +The input language is as described in the ANSI C standard. +The standard Plan 9 C compilers do not use +.IR cpp ; +they contain their own simple but adequate preprocessor, so +.I cpp +is usually superfluous. +.SH FILES +.TF /objtype/include +.TP +.B /sys/include +directory for machine-independent include files +.TP +.B /$objtype/include +directory for machine-dependent include files +.SH SOURCE +.B /sys/src/cmd/cpp +.SH SEE ALSO +.IR 2c (1) diff --git a/sys/man/1/cpu b/sys/man/1/cpu new file mode 100755 index 000000000..e408683bc --- /dev/null +++ b/sys/man/1/cpu @@ -0,0 +1,204 @@ +.TH CPU 1 +.SH NAME +cpu \- connection to CPU server +.SH SYNOPSIS +.B cpu +[ +.B -h +.I server +] [ +.B -u +.I user +] [ +.B -a +.I auth-method +] [ +.B -P +.I patternfile +] [ +.B -e +.I encryption-hash-algs +] [ +.B -k +.I keypattern +] [ +.B -c +.I cmd args ... +] +.PP +.B cpu +[ +.B -R +| +.B -O +] +.SH DESCRIPTION +.I Cpu +starts an +.IR rc (1) +running on the +.I server +machine, or the machine named in the +.B $cpu +environment variable if there is no +.B -h +option. +.IR Rc 's +standard input, output, and error files will be +.B /dev/cons +in the name space where the +.I cpu +command was invoked. +Normally, +.I cpu +is run in an +.IR rio (1) +window on a terminal, so +.IR rc +output goes to that window, and input comes from the keyboard +when that window is current. +.IR Rc 's +current directory is +the working directory of the +.I cpu +command itself. +.PP +The name space for the new +.I rc +is an analogue of the name space where the +.I cpu +command was invoked: +it is the same except for architecture-dependent bindings such as +.B /bin +and the use of fast paths to file servers, if available. +.PP +If a +.B -u +argument is present, +.I cpu +uses the argument as the remote user id. +.PP +If a +.B -c +argument is present, the remainder of the command line is executed by +.I rc +on the server, and then +.I cpu +exits. +.PP +If a +.B -P +argument is present, the +.I patternfile +is passed to +.IR exportfs (4) +to control how much of the local name space will be exported to +the remote system. +.PP +The +.B -a +command allows the user to specify the authentication mechanism used +when connecting to the remote system. The two possibilities for +.I auth-method +are: +.TF netkey +.TP +.B p9 +This is the default. Authentication is done using the standard Plan 9 +mechanisms, (see +.IR authsrv (6)). +No user interaction is required. +.TP +.B netkey +Authentication is done using challenge/response and a hand held +authenticator or the +.I netkey +program +(see +.IR passwd (1)). +The user must encrypt the challenge and type the encryption +back to +.IR cpu . +This is used if the local host is in a different protection domain than +the server or if the user wants to log into the server as a different +user. +.PD +.PP +The +.B -e +option specifies an encryption and/or hash algorithm to +use for the connection. If both are specified, they must +be space separated and comprise a single argument, so they +must be quoted if in a shell command. The default is +.L rc4_256 +encryption and +.L sha1 +hashing. See +.IR ssl (3) +for details on possible algorithms. The argument +.L clear +specifies no encryption algorithm and can be used to talk +to older versions of the +.I cpu +service. +.PP +The +.B -k +flag specifies a key pattern to use to restrict the keys +selected by the +.I auth_proxy +call used for authentication. +.PP +The name space is built by running +.B /usr/$user/lib/profile +with the root of the invoking name space bound to +.BR /mnt/term . +The +.B service +environment variable is set to +.BR cpu ; +the +.B cputype +and +.B objtype +environment variables reflect the server's architecture. +.PP +The +.B -R +flag causes +.I cpu +to run the server (remote) side of the protocol. +It is run from service files such as +.BR /bin/service/tcp17010 . +The +.B -O +flag is similar but simulates the pre-9P2000 version +of the +.I cpu +protocol. +.SH FILES +The name space of the terminal side of the +.I cpu +command is mounted, via +.IR exportfs (4), +on the CPU side on directory +.BR /mnt/term . +The files such as +.B /dev/cons +are bound to their standard locations from there. +.SH SOURCE +.B /sys/src/cmd/cpu.c +.SH SEE ALSO +.IR rc (1) , +.IR rio (1) , +.IR exportfs (4) +.SH BUGS +Binds and mounts done after the terminal +.B lib/profile +is run are not reflected in the new name space. +.PP +When using the +.B -a +option to `log in' as another user, be aware that +resources in the local name space will be made +available to that user. diff --git a/sys/man/1/crop b/sys/man/1/crop new file mode 100755 index 000000000..209cdcc06 --- /dev/null +++ b/sys/man/1/crop @@ -0,0 +1,153 @@ +.TH CROP 1 +.SH NAME +crop, iconv \- frame, crop, and convert image +.SH SYNOPSIS +.B crop +[ +.B -b +.I red +.I green +.I blue +] +[ +.BI -c +.I red +.I green +.I blue +] +[ +.B -i +.I n +| +.B -r +.I minx +.I miny +.I maxx +.I maxy +| +.B -x +.I dx +| +.B -y +.I dy +] +[ +.B -t +.I tx +.I ty +] +[ +.B -b +.I red +.I green +.I blue +] +[ +.I file +] +.PP +.B iconv +[ +.B -u +] [ +.B -c +.I chandesc +] +[ +.I file +] +.SH DESCRIPTION +.I Crop +reads an +.IR image (6) +file (default standard input), crops it, and writes it as a compressed +.IR image (6) +file to standard output. +There are two ways to specify a crop, by color value or by geometry. +They may be combined in a single run of +.IR crop , +in which case the color value crop will be done first. +.PP +The +.B -c +option takes a red-green-blue triplet as described in +.IR color (2). +(For example, white +is +.B 255 +.B 255 +.BR 255 .) +The corresponding color is used as a value to be cut from the outer +edge of the picture; that is, the image is cropped to remove the maximal +outside rectangular strip in which every pixel has the specified color. +.PP +The +.B -i +option insets the image rectangle by a constant amount, +.IR n , +which may be negative to generate extra space around the image. +The +.B -x +and +.B -y +options are similar, but apply only to the +.I x +or +.I y +coordinates of the image. +.PP +The +.B -r +option specifies an exact rectangle. +.PP +The +.B -t +option specifies that the image's coordinate system should +be translated by +.IR tx , +.IR ty +as the last step of processing. +.PP +The +.B -b +option specifies a background color to be used to fill around the image +if the cropped image is larger than the original, such as if the +.B -i +option is given a negative argument. +This can be used to draw a monochrome frame around the image. +The default color is black. +.PP +.I Iconv +changes the format of pixels in the image +.I file +(default standard input) and writes the resulting image to standard output. +Pixels in the image are converted according to the channel descriptor +.IR chandesc , +(see +.IR image (6)). +For example, to convert a 4-bit-per-pixel grey-scale image to an 8-bit-per-pixel +color-mapped image, +.I chandesc +should be +.BR m8 . +If +.I chandesc +is not given, the format is unchanged. +The output image is by default compressed; the +.B -u +option turns off the compression. +.SH EXAMPLE +To crop white edges off the picture and add a ten-pixel pink border, +.IP +.EX +crop -c 255 255 255 -i -10 -b 255 150 150 imagefile > cropped +.EE +.SH SOURCE +.B /sys/src/cmd/crop.c +.SH SEE ALSO +.IR image (6), +.IR color (2) +.SH BUGS +.I Iconv +should be able to do Floyd-Steinberg error diffusion or dithering +when converting to small image depths. diff --git a/sys/man/1/date b/sys/man/1/date new file mode 100755 index 000000000..705a95425 --- /dev/null +++ b/sys/man/1/date @@ -0,0 +1,58 @@ +.TH DATE 1 +.SH NAME +date, clock \- date and time +.SH SYNOPSIS +.B date +[ +.I option +] [ +.I seconds +] +.br +.B clock +.SH DESCRIPTION +Print the date, in the format +.PP +.B + Tue Aug 16 17:03:52 CDT 1977 +.PP +The options are +.TP +.B -u +Report Greenwich Mean Time (GMT) rather than local time. +.TP +.B -n +Report the date as the number of seconds since the +epoch, 00:00:00 GMT, January 1, 1970. +.PP +The conversion from Greenwich Mean Time to local time depends on the +.B $timezone +environment variable; see +.IR ctime (2). +.PP +If the optional argument +.I seconds +is present, it is used as the time to convert rather than +the real time. +.PP +.I Clock +draws a simple analog clock in its window. +.SH FILES +.TF /adm/timezone/local +.TP +.B /env/timezone +Current timezone name and adjustments. +.TP +.B /adm/timezone +A directory containing timezone tables. +.TP +.B /adm/timezone/local +Default timezone file, copied by +.IR init (8) +into +.BR /env/timezone . +.PD +.SH SOURCE +.B /sys/src/cmd/date.c +.br +.B /sys/src/cmd/clock.c diff --git a/sys/man/1/db b/sys/man/1/db new file mode 100755 index 000000000..34f1f4239 --- /dev/null +++ b/sys/man/1/db @@ -0,0 +1,1018 @@ +.TH DB 1 +.SH NAME +db \- debugger +.SH SYNOPSIS +.B db +[ +.I option ... +] +[ +.I textfile +] +[ +.I pid +] +.SH DESCRIPTION +.I Db +is a general purpose debugging program. +It may be used to examine files and to provide +a controlled environment for the execution +of Plan 9 programs. +.PP +A +.I textfile +is a file containing the text and initialized +data of an executable program. +A +.I memfile +is the memory image of an executing process. It is +usually accessed via the process id +.RI ( pid ) +of the process in +.BI /proc/ pid /mem\f1. +A +.I memfile +contains the text, data, and saved registers and +process state. A +.I map +associated with each +.I textfile +or +.I memfile +supports accesses to instructions and data in the file; +see `Addresses'. +.PP +An argument consisting entirely of digits is assumed +to be a process id; otherwise, it is the name of a +.IR textfile . +When a +.I textfile +is given, the textfile map +is associated with it. +If only a +.I pid +is given, the textfile map is +associated with +.BI /proc/ pid /text\f1. +When a +.I pid +is given, the memfile map is associated with +.BI /proc/ pid /mem\f1; +otherwise it is undefined and accesses to the +.I memfile +are not permitted. +.PP +Commands to +.I db +are read from the standard input and +responses are to the standard output. +The options are +.TP +.BI -k +Use the kernel stack of process +.IR pid +to debug the executing kernel process. +If +.I textfile +is not specified, file +.BI / $cputype /9 type +is used, where +.I type +is the second word in +.BR $terminal . +.TP +.B -w +Create +.I textfile +and +.I memfile +if they don't exist; open them for writing +as well as reading. +.TP +.BI -I path +Directory in which to look for relative path names in +.B $< +and +.B $<< +commands. +.TP +.BI -m machine +Assume instructions are for the given CPU type +(any standard architecture name, such as +.B alpha +or +.BR 386 , +plus +.B mipsco +and +.BR sunsparc , +which cause disassembly to the manufacturer's syntax) +instead of using the magic number to select +the CPU type. +.PP +Most +.I db +commands have the following form: +.IP +.RI [ address ] +.RB [ , +.IR count ] +.RI [ command ] +.PP +If +.I address +is present then the current position, called `dot', +is set to +.IR address . +Initially dot +is set to 0. +Most commands are repeated +.I count +times with +dot advancing between repetitions. +The default +.I count +is 1. +.I Address +and +.I count +are expressions. +Multiple commands on one line must be separated by +.LR ; . +.SS Expressions +Expressions are evaluated as long +.IR ints . +.TP 7.2n +.B . +The value of dot. +.TP 7.2n +.B + +The value of dot +incremented by the current increment. +.TP 7.2n +.B ^ +The value of dot +decremented by the current increment. +.TP 7.2n +.B \&" +The last +.I address +typed. +.TP 7.2n +.I integer +A number, in decimal radix by default. +The prefixes +.L 0 +and +.L 0o +and +.L 0O +(zero oh) force interpretation +in octal radix; the prefixes +.L 0t +and +.L 0T +force interpretation in +decimal radix; the prefixes +.LR 0x , +.LR 0X , +and +.L # +force interpretation in +hexadecimal radix. +Thus +.LR 020 , +.LR 0o20 , +.LR 0t16 , +and +.L #10 +all represent sixteen. +.TP 7.2n +.IB integer . fraction +A single-precision floating point number. +.TP 7.2n +.BI \' c\| \' +The +16-bit +value of a character. +.L \e +may be used to escape a +.LR \' . +.TP 7.2n +.BI < name +The value of +.IR name , +which is a register name. +The register names are +those printed by the +.B $r +command. +.TP 7.2n +.I symbol +A +.I symbol +is a sequence +of upper or lower case letters, underscores or +digits, not starting with a digit. +.L \e +may be used to escape other characters. +The location of the +.I symbol +is calculated from the symbol table +in +.IR textfile . +.TP 7.2n +.IB routine . name +The address of the variable +.I name +in the specified +C routine. +Both +.I routine +and +.I name +are +.IR symbols . +If +.I name +is omitted the value is the address of the +most recently activated stack frame +corresponding to +.IR routine ; +if +.I routine +is omitted, +the active procedure +is assumed. +.TP 7.2n +.IB file : integer +The address of the instruction corresponding +to the source statement at the indicated +line number of the file. If the source line contains +no executable statement, the address of the +instruction associated with the nearest +executable source line is returned. Files +begin at line 1. If multiple files of the same +name are loaded, an expression of this form resolves +to the first file encountered in the symbol table. +.TP 7.2n +.BI ( exp ) +The value of the expression +.IR exp . +.LP +.I Monadic operators +.RS +.TP 7.2n +.BI * exp +The contents of the location addressed +by +.I exp +in +.IR memfile . +.TP 7.2n +.BI @ exp +The contents of the location addressed by +.I exp +in +.IR textfile . +.TP 7.2n +.BI - exp +Integer negation. +.TP 7.2n +.BI ~ exp +Bitwise complement. +.TP 7.2n +.BI % exp +When used as an +.IR address , +.I exp +is an offset into the segment named +.IR ublock ; +see `Addresses'. +.RE +.LP +.I "Dyadic\ operators" +are left-associative +and are less binding than monadic operators. +.RS +.TP 7.2n +.IB e1 + e2 +Integer addition. +.TP 7.2n +.IB e1 - e2 +Integer subtraction. +.TP 7.2n +.IB e1 * e2 +Integer multiplication. +.TP 7.2n +.IB e1 % e2 +Integer division. +.TP 7.2n +.IB e1 & e2 +Bitwise conjunction. +.TP 7.2n +.IB e1 | e2 +Bitwise disjunction. +.TP 7.2n +.IB e1 # e2 +.I E1 +rounded up to the next multiple of +.IR e2 . +.RE +.DT +.SS Commands +Most commands have the following syntax: +.TP .5i +.BI ? f +Locations starting at +.I address +in +.I textfile +are printed according to the format +.IR f . +.TP +.BI / f +Locations starting at +.I address +in +.I memfile +are printed according to the format +.IR f . +.TP +.BI = f +The value of +.I address +itself is printed according to the format +.IR f . +.PP +A +.I format +consists of one or more characters that specify a style +of printing. +Each format character may be preceded by a decimal integer +that is a repeat count for the format character. +If no format is given then the last format is used. +.PP +Most format letters fetch some data, +print it, +and advance (a local copy of) dot +by the number of bytes fetched. +The total number of bytes in a format becomes the +.IR current increment . +.ta 2.5n .5i +.RS +.TP +.PD 0 +.B o +Print two-byte integer in octal. +.TP +.B O +Print four-byte integer in octal. +.TP +.B q +Print two-byte integer in signed octal. +.TP +.B Q +Print four-byte integer in signed octal. +.TP +.B d +Print two-byte integer in decimal. +.TP +.B D +Print four-byte integer in decimal. +.TP +.B V +Print eight-byte integer in decimal. +.TP +.B Z +Print eight-byte integer in unsigned decimal. +.TP +.B x +Print two-byte integer in hexadecimal. +.TP +.B X +Print four-byte integer in hexadecimal. +.TP +.B Y +Print eight-byte integer in hexadecimal. +.TP +.B u +Print two-byte integer in unsigned decimal. +.TP +.B U +Print four-byte integer in unsigned decimal. +.TP +.B f +Print +as a single-precision floating point number. +.TP +.B F +Print double-precision floating point. +.TP +.B b +Print the addressed byte in hexadecimal. +.TP +.B c +Print the addressed byte as an +.SM ASCII +character. +.TP +.B C +Print the addressed byte as a character. +Printable +.SM ASCII +characters +are represented normally; others +are printed in the form +.BR \exnn . +.TP +.B s +Print the addressed characters, as a +.SM UTF +string, until a zero byte +is reached. +Advance dot +by the length of the string, +including the zero terminator. +.TP +.B S +Print a string using +the escape convention (see +.B C +above). +.TP +.B r +Print as +.SM UTF +the addressed two-byte integer (rune). +.TP +.B R +Print as +.SM UTF +the addressed two-byte integers as runes +until a zero rune is reached. +Advance dot +by the length of the string, +including the zero terminator. +.TP +.B i +Print as machine instructions. Dot is +incremented by the size of the instruction. +.TP +.B I +As +.B i +above, but print the machine instructions in +an alternate form if possible: +.B sunsparc +and +.B mipsco +reproduce the manufacturers' syntax. +.TP +.B M +Print the addressed machine instruction in a +machine-dependent hexadecimal form. +.TP +.B a +Print the value of dot +in symbolic form. +Dot is unaffected. +.TP +.B A +Print the value of dot +in hexadecimal. +Dot is unaffected. +.TP +.B z +Print the function name, source file, and line number +corresponding to dot (textfile only). Dot is unaffected. +.TP +.B p +Print the addressed value in symbolic form. +Dot is advanced by the size of a machine address. +.TP +.B t +When preceded by an integer, tabs to the next +appropriate tab stop. +For example, +.B 8t +moves to the next 8-space tab stop. +Dot is unaffected. +.TP +.B n +Print a newline. +Dot is unaffected. +.tr '" +.TP +.BR ' ... ' +Print the enclosed string. +Dot is unaffected. +.br +.tr '' +.TP +.B ^ +Dot is decremented by the current increment. +Nothing is printed. +.TP +.B + +Dot is incremented by 1. +Nothing is printed. +.TP +.B - +Dot is decremented by 1. +Nothing is printed. +.RE +.PD +.LP +Other commands include: +.TP +newline +Update dot by the current increment. +Repeat the previous command with a +.I count +of 1. +.TP +.RB [ ?/ ] l "\fI value mask\fR" +Words starting at dot +are masked with +.I mask +and compared with +.I value +until +a match is found. +If +.B l +is used, +the match is for a two-byte integer; +.B L +matches four bytes. +If no match is found then dot +is unchanged; otherwise dot +is set to the matched location. +If +.I mask +is omitted then ~0 is used. +.TP +.RB [ ?/ ] w "\fI value ...\fR" +Write the two-byte +.I value +into the addressed +location. +If the command is +.BR W , +write four bytes. +.TP +.RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR] +.br +New values for +.RI ( b,\ e,\ f ) +in the segment named +.I s +are recorded. Valid segment names are +.IR text , +.IR data , +or +.IR ublock . +If less than three address expressions are given, +the remaining parameters are left unchanged. +If the list is terminated by +.L ? +or +.L / +then the file +.RI ( textfile +or +.I memfile +respectively) is used +for subsequent requests. +For example, +.L /m? +causes +.L / +to refer to +.IR textfile . +.TP +.BI > name +Dot is assigned to the variable or register named. +.TP +.B ! +The rest of the line is passed to +.IR rc (1) +for execution. +.TP +.BI $ modifier +Miscellaneous commands. +The available +.I modifiers +are: +.RS +.TP +.PD 0 +.BI < f +Read commands from the file +.IR f . +If this command is executed in a file, further commands +in the file are not seen. +If +.I f +is omitted, the current input stream is terminated. +If a +.I count +is given, and is zero, the command is ignored. +.TP +.BI << f +Similar to +.B < +except it can be used in a file of commands without +causing the file to be closed. +There is a (small) limit to the number of +.B << +files that can be open at once. +.br +.ns +.TP +.BI > f +Append output to the file +.IR f , +which is created if it does not exist. +If +.I f +is omitted, output is returned to the terminal. +.TP +.B ? +Print process id, the condition which caused stopping or termination, +the registers and the instruction addressed by +.BR pc . +This is the default if +.I modifier +is omitted. +.TP +.B r +Print the general registers and +the instruction addressed by +.BR pc . +Dot is set to +.BR pc . +.TP +.B R +Like +.BR $r , +but include miscellaneous processor control registers +and floating point registers. +.TP +.B f +Print floating-point register values as +single-precision floating point numbers. +.TP +.B F +Print floating-point register values as +double-precision floating point numbers. +.TP +.B b +Print all breakpoints +and their associated counts and commands. `B' produces the same results. +.TP +.B c +Stack backtrace. +If +.I address +is given, it specifies the address of a pair of 32-bit +values containing the +.B sp +and +.B pc +of an active process. This allows selecting +among various contexts of a multi-threaded +process. +If +.B C +is used, the names and (long) values of all +parameters, +automatic +and static variables are printed for each active function. +If +.I count +is given, only the first +.I count +frames are printed. +.TP +.B a +Attach to the running process whose pid +is contained in +.IR address . +.TP +.B e +The names and values of all +external variables are printed. +.TP +.B w +Set the page width for output to +.I address +(default 80). +.TP +.B q +Exit from +.IR db . +.TP +.B m +Print the address maps. +.TP +.B k +Simulate kernel memory management. +.TP +.BI M machine +Set the +.I machine +type used for disassembling instructions. +.PD +.RE +.TP +.BI : modifier +Manage a subprocess. +Available modifiers are: +.RS +.TP +.PD 0 +.BI h +Halt +an asynchronously running process to allow breakpointing. +Unnecessary for processes created under +.IR db , +e.g. by +.BR :r . +.TP +.BI b c +Set breakpoint at +.IR address . +The breakpoint is executed +.IR count \-1 +times before +causing a stop. +Also, if a command +.I c +is given it is executed at each +breakpoint and if it sets dot to zero +the breakpoint causes a stop. +.TP +.B d +Delete breakpoint at +.IR address . +.TP +.B r +Run +.I textfile +as a subprocess. +If +.I address +is given the +program is entered at that point; otherwise +the standard entry point is used. +.I Count +specifies how many breakpoints are to be +ignored before stopping. +Arguments to the subprocess may be supplied on the +same line as the command. +An argument starting with < or > causes the standard +input or output to be established for the command. +.TP +.BI c s +The subprocess is continued. +If +.I s +is omitted +or nonzero, +the subprocess +is sent the note that caused it to stop. +If 0 +is specified, +no note is sent. +(If the stop was due to a breakpoint or single-step, +the corresponding note is elided before continuing.) +Breakpoint skipping is the same +as for +.BR r . +.TP +.BI s s +As for +.B c +except that +the subprocess is single stepped for +.I count +machine instructions. +If a note is pending, +it is received +before the first instruction is executed. +If there is no current subprocess then +.I textfile +is run +as a subprocess as for +.BR r . +In this case no note can be sent; the remainder of the line +is treated as arguments to the subprocess. +.TP +.BI S s +Identical to +.B s +except the subprocess is single stepped for +.I count +lines of C source. In optimized code, the correspondence +between C source and the machine instructions is +approximate at best. +.TP +.BI x +The current subprocess, if any, is released by +.I db +and allowed to continue executing normally. +.TP +.B k +The current subprocess, if any, is terminated. +.TP +.BI n c +Display the pending notes for the process. +If +.I c +is specified, first delete +.I c'th +pending note. +.PD +.RE +.SS Addresses +The location in a file or memory image associated with +an address is calculated from a map +associated with the file. +Each map contains one or more quadruples +.RI ( "t, b, e, f" ), +defining a segment named +.I t +(usually, +.IR text , +.IR data , +or +.IR ublock ) +mapping addresses in the range +.I b +through +.I e +to the part of the file +beginning at +offset +.IR f . +The memory model of a Plan 9 process assumes +that segments are disjoint. There +can be more than one segment of a given type (e.g., a process +may have more than one text segment) but segments +may not overlap. +An address +.I a +is translated +to a file address +by finding a segment +for which +.IR b ≤ a < e ; +the location in the file +is then +.IR address + f \- b . +.PP +Usually, +the text and initialized data of a program +are mapped by segments called +.I text +and +.IR data . +Since a program file does not contain bss, stack or ublock data, +these data are +not mapped by the data segment. +The text segment is mapped similarly in +a normal (i.e., non-kernel) +.IR memfile . +However, the segment called +.I data +maps memory from the beginning of the program's data space to +the base of the ublock. +This region contains the program's static data, the bss, the +heap and the stack. A segment +called +.I ublock +maps the page containing its registers and process state. +.PP +Sometimes it is useful to define a map with a single segment +mapping the region from 0 to 0xFFFFFFFF; a map of this type +allows the entire file to be examined +without address translation. +.PP +Registers are saved at a machine-dependent offset in the ublock. +It is usually not necessary to know this offset; the +.BR $r , +.BR $R , +.BR $f , +and +.BR $F +commands calculate it and display the register contents. +.PP +The +.B $m +command dumps the currently active maps. The +.B ?m +and +.B /m +commands modify the segment parameters in the +.I textfile +and +.I memfile +maps, respectively. +.SH EXAMPLES +To set a breakpoint at the beginning of +.B write() +in extant process 27: +.IP +.EX +% db 27 +:h +write:b +:c +.EE +.PP +To examine the Plan 9 kernel stack for process 27: +.IP +.EX +% db -k 27 +$C +.EE +.PP +Similar, but using a kernel named +.BR test : +.IP +.EX +% db -k test 27 +$C +.EE +.PP +To set a breakpoint at the entry of function +.B parse +when the local variable +.B argc +in +.B main +is equal to 1: +.IP +.EX +parse:b *main.argc-1=X +.EE +.PP +This prints the value of +.B argc-1 +which as a side effect sets dot; when +.B argc +is one the breakpoint will fire. +Beware that local variables may be stored in registers; see the +BUGS section. +.PP +Debug process 127 on remote machine +.BR kremvax : +.IP +.EX +% import kremvax /proc +% db 127 +$C +.EE +.SH FILES +.B /proc/*/text +.br +.B /proc/*/mem +.br +.B /proc/*/ctl +.br +.B /proc/*/note +.SH "SEE ALSO" +.IR acid (1), +.IR nm (1), +.IR proc (3) +.SH SOURCE +.B /sys/src/cmd/db +.SH DIAGNOSTICS +Exit status is null, unless the last command failed or +returned non-null status. +.SH BUGS +Examining a local variable with +.I routine.name +returns the contents of the memory allocated for the variable, but +with optimization (suppressed by the +.B -N +compiler flag) variables often reside in registers. +Also, on some architectures, the first argument is always +passed in a register. +.PP +Variables and parameters that have been +optimized away do not appear in the +symbol table, returning the error +.IR "bad local variable" +when accessed by +.IR db . +.PP +Because of alignment incompatibilities, Motorola 68000 +series machines can not be debugged remotely from a +processor of a different type. +.PP +Breakpoints should not be set on instructions scheduled +in delay slots. When a program stops on such a breakpoint, +it is usually impossible to continue its execution. diff --git a/sys/man/1/dc b/sys/man/1/dc new file mode 100755 index 000000000..7032a2bff --- /dev/null +++ b/sys/man/1/dc @@ -0,0 +1,257 @@ +.TH DC 1 +.SH NAME +dc \- desk calculator +.SH SYNOPSIS +.B dc +[ +.I file +] +.SH DESCRIPTION +.I Dc +is an arbitrary precision desk calculator. +Ordinarily it operates on decimal integers, +but one may specify an input base, output base, +and a number of fractional digits to be maintained. +The overall structure of +.I dc +is +a stacking (reverse Polish) calculator. +If an argument is given, +input is taken from that file until its end, +then from the standard input. +The following constructions are recognized: +.TP +number +The value of the number is pushed on the stack. +A number is an unbroken string of the digits +.B 0-9A-F +or +.BR 0-9a-f . +A hexadecimal number beginning with a lower case +letter must be preceded by a zero to distinguish it +from the command associated with the letter. +It may be preceded by an underscore +.B _ +to input a +negative number. +Numbers may contain decimal points. +.TP +.L ++ - / * % ^ +Add +.LR + , +subtract +.LR - , +multiply +.LR * , +divide +.LR / , +remainder +.LR % , +or exponentiate +.L ^ +the top two values on the stack. +The two entries are popped off the stack; +the result is pushed on the stack in their place. +Any fractional part of an exponent is ignored. +.TP +.BI s x +.br +.ns +.TP +.BI S x +Pop the top of the stack and store into +a register named +.IR x , +where +.I x +may be any character. +Under operation +.B S +register +.I x +is treated as a stack and the value is pushed on it. +.TP +.BI l x +.br +.ns +.TP +.BI L x +Push the value in register +.I x +onto the stack. +The register +.I x +is not altered. +All registers start with zero value. +Under operation +.B L +register +.I x +is treated as a stack and its top value is popped onto the main stack. +.TP +.B d +Duplicate the +top value on the stack. +.TP +.B p +Print the top value on the stack. +The top value remains unchanged. +.B P +interprets the top of the stack as an +text +string, +removes it, and prints it. +.TP +.B f +Print the values on the stack. +.TP +.B q +.br +.ns +.TP +.B Q +Exit the program. +If executing a string, the recursion level is +popped by two. +Under operation +.B Q +the top value on the stack is popped and the string execution level is popped +by that value. +.TP +.B x +Treat the top element of the stack as a character string +and execute it as a string of +.I dc +commands. +.TP +.B X +Replace the number on the top of the stack with its scale factor. +.TP +.B "[ ... ]" +Put the bracketed +text +string on the top of the stack. +.TP +.PD0 +.BI < x +.TP +.BI > x +.TP +.BI = x +.PD +Pop and compare the +top two elements of the stack. +Register +.I x +is executed if they obey the stated +relation. +.TP +.B v +Replace the top element on the stack by its square root. +Any existing fractional part of the argument is taken +into account, but otherwise the scale factor is ignored. +.TP +.B ! +Interpret the rest of the line as a shell command. +.TP +.B c +Clear the stack. +.TP +.B i +The top value on the stack is popped and used as the +number base for further input. +.TP +.B I +Push the input base on the top of the stack. +.TP +.B o +The top value on the stack is popped and used as the +number base for further output. +In bases larger than 10, each `digit' prints as a group of decimal digits. +.TP +.B O +Push the output base on the top of the stack. +.TP +.B k +Pop the top of the stack, and use that value as +a non-negative scale factor: +the appropriate number of places +are printed on output, +and maintained during multiplication, division, and exponentiation. +The interaction of scale factor, +input base, and output base will be reasonable if all are changed +together. +.TP +.B z +Push the stack level onto the stack. +.TP +.B Z +Replace the number on the top of the stack with its length. +.TP +.B ? +A line of input is taken from the input source (usually the terminal) +and executed. +.TP +.B "; :" +Used by +.I bc +for array operations. +.PP +The scale factor set by +.B k +determines how many digits are kept to the right of +the decimal point. +If +.I s +is the current scale factor, +.I sa +is the scale of the first operand, +.I sb +is the scale of the second, +and +.I b +is the (integer) second operand, +results are truncated to the following scales. +.IP +.nf +\fL+\fR,\fL-\fR max(\fIsa,sb\fR) +\fL*\fR min(\fIsa\fR+\fIsb \fR, max\fR(\fIs,sa,sb\fR)) +\fL/\fI s +\fL%\fR so that dividend = divisor*quotient + remainder; remainder has sign of dividend +\fL^\fR min(\fIsa\fR\(mu|\fIb\fR|, max(\fIs,sa\fR)) +\fLv\fR max(\fIs,sa\fR) +.fi +.SH EXAMPLES +.LP +Print the first ten values of +.IR n ! +.IP +.EX +[la1+dsa*pla10>y]sy +0sa1 +lyx +.EE +.SH SOURCE +.B /sys/src/cmd/dc.c +.SH "SEE ALSO" +.IR bc (1), +.IR hoc (1) +.SH DIAGNOSTICS +.I x +.LR "is unimplemented" , +where +.I x +is an octal number: an internal error. +.br +`Out of headers' +for too many numbers being kept around. +.br +`Nesting depth' +for too many levels of nested execution. +.SH BUGS +When the input base exceeds 16, +there is no notation for digits greater than +.BR F . +.PP +Past its time. diff --git a/sys/man/1/dd b/sys/man/1/dd new file mode 100755 index 000000000..afd296b1f --- /dev/null +++ b/sys/man/1/dd @@ -0,0 +1,196 @@ +.TH DD 1 +.SH NAME +dd \- convert and copy a file +.SH SYNOPSIS +.B dd +[ +.I option value +] +\&... +.SH DESCRIPTION +.I Dd\^ +copies the specified input file +to the specified output with +possible conversions. +The standard input and output are used by default. +The input and output block size may be +specified to take advantage of raw physical I/O. +The options are +.TP \w'\fLoseek\ \ \fIn'u +.BI -if\ f +Open file +.I f +for input. +.TP +.BI -of\ f +Open file +.I f +for output. +.TP +.BI -ibs\ n\^ +Set input block size to +.I n\^ +bytes (default 512). +.TP +.BI -obs\ n\^ +Set output block size (default 512). +.TP +.BI -bs\ n\^ +Set both input and output block size, +superseding +.I ibs\^ +and +.IR obs . +If no conversion is specified, +preserve the input block size instead of packing short blocks +into the output buffer. +This is particularly efficient since no in-core copy need be done. +.TP +.BI -cbs\ n\^ +Set conversion buffer size. +.TP +.BI -skip\ n\^ +Skip +.I n +input records before copying. +.TP +.BI -iseek\ n\^ +Seek +.I n +records forward on input file +before copying. +.TP +.BI -files\ n\^ +Catenate +.I n +input files (useful only for magnetic tape or similar input device). +.TP +.BI -oseek\ n\^ +Seek +.I n\^ +records from beginning of output file before copying. +.TP +.BI -count\ n\^ +Copy only +.I n +input records. +.TP +.BI -trunc\ n\^ +By default, +.I dd +truncates the output file when it opens it; +.B -trunc +.B 0 +opens it without truncation. +.TP +.BI -quiet\ n\^ +By default, +.I dd +prints the number of blocks read and written +once it is finished. +.B -quiet +.B 1 +silences this summary. +.HP +\fL-conv\ ascii\ \ \ \ \fRConvert +.SM EBCDIC +to +.SM ASCII. +.PD0 +.RS "\w'\fLconv\ \fP'u" +.TP "\w'\fLunblock\ \ \fP'u" +.B ebcdic +Convert +.SM ASCII +to +.SM EBCDIC. +.TP +.B ibm +Like +.B ebcdic +but with a slightly different character map. +.TP +.B block +Convert variable length +.SM ASCII +records to fixed length. +.TP +.B unblock +Convert fixed length +.SM ASCII +records to variable length. +.TP +.B lcase +Map alphabetics to lower case. +.TP +.B ucase +Map alphabetics to upper case. +.TP +.B swab +Swap every pair of bytes. +.TP +.B noerror +Do not stop processing on an error. +.TP +.B sync +Pad every input record to +.I ibs\^ +bytes. +.RE +.PD +.PP +.fi +Where sizes are specified, +a number of bytes is expected. +A number may end with +.L k +or +.LR b +to specify multiplication by +1024 or 512 respectively; +a pair of numbers may be separated by +.L x +to indicate a product. +Multiple conversions may be specified in the style: +.LR "-conv ebcdic,ucase" . +.PP +.L Cbs\^ +is used only if +.LR ascii\^ , +.LR unblock\^ , +.LR ebcdic\^ , +.LR ibm\^ , +or +.L block\^ +conversion is specified. +In the first two cases, +.I n +characters are copied into the conversion buffer, any specified +character mapping is done, +trailing blanks are trimmed and new-line is added +before sending the line to the output. +In the latter three cases, characters are read into the +conversion buffer and blanks are added to make up an +output record of size +.IR n . +If +.L cbs\^ +is unspecified or zero, the +.LR ascii\^ , +.LR ebcdic\^ , +and +.L ibm\^ +options convert the character set without changing the block +structure of the input file; the +.L unblock\^ +and +.L block\^ +options become a simple file copy. +.SH SOURCE +.B /sys/src/cmd/dd.c +.SH "SEE ALSO" +.IR cp (1) +.SH DIAGNOSTICS +.I Dd +reports the number of full + partial input and output +blocks handled. diff --git a/sys/man/1/delkey b/sys/man/1/delkey new file mode 100755 index 000000000..2f8bbd039 --- /dev/null +++ b/sys/man/1/delkey @@ -0,0 +1,42 @@ +.TH DELKEY 1 +.SH NAME +delkey \- delete keys from factotum +.SH SYNOPSIS +.B delkey +[ +.B -f +] +.I pattern +.SH DESCRIPTION +.I Delkey +shows the user each key stored in +.IR factotum (4) +and matching the +.IR pattern , +prompting for whether the key should be deleted. +At each prompt, typing a response beginning with +.B y +deletes the key, typing a response beginning with +.B q +aborts the listing, +and any other response skips over the key. +.PP +The +.B -f +option disables the prompting; all keys matching the pattern are deleted. +.PP +When run on a CPU server, +.I delkey +uses the terminal's factotum, if present, instead of the server's factotum. +.SH FILES +.TP +.B /mnt/term/mnt/factotum +First choice for +.I factotum +to use +.TP +.B /mnt/factotum +Second choice +.PP +.SH SOURCE +.B /rc/bin/delkey diff --git a/sys/man/1/deroff b/sys/man/1/deroff new file mode 100755 index 000000000..ff94859fe --- /dev/null +++ b/sys/man/1/deroff @@ -0,0 +1,117 @@ +.TH DEROFF 1 +.SH NAME +deroff, delatex \- remove formatting requests +.SH SYNOPSIS +.B deroff +[ +.I option ... +] +.I file ... +.PP +.B delatex +.I file +.SH DESCRIPTION +.I Deroff +reads each file in sequence +and removes all +.I nroff +and +.IR troff (1) +requests and non-text arguments, backslash constructions, +and constructs of preprocessors such as +.IR eqn (1), +.IR pic (1), +and +.IR tbl (1). +Remaining text is written on the standard output. +.I Deroff +follows files included by +.L .so +and +.L .nx +commands; +if a file has already been included, a +.L .so +for that file is ignored and a +.L .nx +terminates execution. +If no input file is given, +.I deroff +reads from standard input. +.PP +The options are +.TP +.B -w +Output a word list, one `word' (string of letters, digits, and +properly embedded ampersands and apostrophes, +beginning with a letter) per line. +Other characters are skipped. +Otherwise, the output follows the original, with the deletions mentioned above. +.TP +.B -_ +Like +.BR -w , +but consider underscores to be alphanumeric rather than punctuation. +.TP +.B -i +Ignore +.L .so +and +.L .nx +requests. +.TP +.BR -ms +.PD0 +.TP +.B -mm +Remove titles, attachments, etc., as well as ordinary +.IR troff +constructs, from +.IR ms (6) +or +.I mm +documents. +.PD +.TP +.B -ml +Same as +.BR -mm , +but remove lists as well. +.PP +.I Delatex +does for +.I tex +and +.I latex +(see +.IR tex (1)) +files what +.B deroff -wi +does for +.I troff +files. +.SH SOURCE +.B /sys/src/cmd/deroff.c +.br +.B /sys/src/cmd/tex/local/delatex.c +.SH "SEE ALSO" +.IR troff (1), +.IR tex (1), +.IR spell (1) +.SH BUGS +These filters are not complete interpreters of +.I troff +or +.IR tex . +For example, macro definitions containing +.L \e$ +cause chaos in +.IR deroff +when the popular +.L $$ +delimiters for +.I eqn +are in effect. +.PP +Text inside macros is emitted at place of +definition, not place of call. diff --git a/sys/man/1/diff b/sys/man/1/diff new file mode 100755 index 000000000..91d3d491a --- /dev/null +++ b/sys/man/1/diff @@ -0,0 +1,176 @@ +.TH DIFF 1 +.SH NAME +diff \- differential file comparator +.SH SYNOPSIS +.B diff +[ +.B -abcefmnrw +] +.I file1 ... file2 +.SH DESCRIPTION +.I Diff +tells what lines must be changed in two files to bring them +into agreement. +If one file +is a directory, +then a file in that directory with basename the same as that of +the other file is used. +If both files are directories, similarly named files in the +two directories are compared by the method of +.I diff +for text +files and +.IR cmp (1) +otherwise. +If more than two file names are given, then each argument is compared +to the last argument as above. +The +.B -r +option causes +.I diff +to process similarly named subdirectories recursively. +When processing more than one file, +.I diff +prefixes file differences with a single line +listing the two differing files, in the form of +a +.I diff +command line. +The +.B -m +flag causes this behavior even when processing single files. +.PP +The normal output contains lines of these forms: +.IP "" 5 +.I n1 +.B a +.I n3,n4 +.br +.I n1,n2 +.B d +.I n3 +.br +.I n1,n2 +.B c +.I n3,n4 +.PP +These lines resemble +.I ed +commands to convert +.I file1 +into +.IR file2 . +The numbers after the letters pertain to +.IR file2 . +In fact, by exchanging `a' for `d' and reading backward +one may ascertain equally how to convert +.I file2 +into +.IR file1 . +As in +.IR ed , +identical pairs where +.I n1 += +.I n2 +or +.I n3 += +.I n4 +are abbreviated as a single number. +.PP +Following each of these lines come all the lines that are +affected in the first file flagged by `<', +then all the lines that are affected in the second file +flagged by `>'. +.PP +The +.B -b +option causes +trailing blanks (spaces and tabs) to be ignored +and other strings of blanks to compare equal. +The +.B -w +option causes all white-space to be removed from input lines +before applying the difference algorithm. +.PP +The +.B -n +option prefixes each range with +.IB file : \fR +and inserts a space around the +.BR a , +.BR c , +and +.B d +verbs. +The +.B -e +option produces a script of +.I "a, c" +and +.I d +commands for the editor +.IR ed , +which will recreate +.I file2 +from +.IR file1 . +The +.B -f +option produces a similar script, +not useful with +.IR ed , +in the opposite order. It may, however, be +useful as input to a stream-oriented post-processor. +.PP +The +.B -c +option includes three lines of context around each +change, merging changes whose contexts overlap. +In this mode, +.I diff +prints +.L - +and +.L + +instead of +.L < +and +.L > +because the former are easier to distinguish when mixed. +The +.B -a +flag displays the entire file as context. +.PP +Except in rare circumstances, +.I diff +finds a smallest sufficient set of file +differences. +.SH FILES +.B /tmp/diff[12] +.SH SOURCE +.B /sys/src/cmd/diff +.SH "SEE ALSO" +.IR cmp (1), +.IR comm (1), +.IR ed (1), +.IR idiff (1) +.SH DIAGNOSTICS +Exit status is the empty string +for no differences, +.L some +for some, +and +.L error +for trouble. +.SH BUGS +Editing scripts produced under the +.BR -e " or" +.BR -f " option are naive about" +creating lines consisting of a single `\fB.\fR'. +.PP +When running +.I diff +on directories, the notion of what is a text +file is open to debate. diff --git a/sys/man/1/doc2txt b/sys/man/1/doc2txt new file mode 100755 index 000000000..9b85e9f8f --- /dev/null +++ b/sys/man/1/doc2txt @@ -0,0 +1,161 @@ +.TH DOC2TXT 1 +.SH NAME +doc2txt, doc2ps, wdoc2txt, xls2txt, olefs, mswordstrings, msexceltables +\- extract printable text from Microsoft documents +.SH SYNOPSIS +.B doc2txt +[ +.I file.doc +] +.br +.B doc2ps +[ +.I file.doc +] +.br +.B wdoc2txt +[ +.I file.doc +] +.br +.B xls2txt +[ +.I file.xls +] +.br +.B aux/olefs +[ +.B -m +.I mtpt +] +.I file.doc +.br +.B aux/mswordstrings +.IB mtpt /WordDocument +.br +.B aux/msexceltables +[ +.B -qaDnt +] [ +.B -d +.I delim +] [ +.B -c +.I column-range +] [ +.B -w +.I worksheet-range +] +.IB mtpt /Workbook +.SH DESCRIPTION +.I Doc2txt +is an +.IR rc (1) +script that uses +.I olefs +and +.I mswordstrings +to extract the printable text from the body of a Microsoft Word document +and write it on the standard output. +.I Doc2ps +is similar, but emits PostScript corresponding to the document. +.I Wdoc2txt +is similar to +.IR doc2txt , +but uses +.IR plumb (1) +to send the output to a new +.IR acme (1) +window instead. +.I Xls2txt +performs a similar function for Microsoft Excel documents. +.PP +Microsoft Office documents are stored in OLE (Object Linking and Embedding) +format, which is a scaled down version of Microsoft's FAT file system. +.I Olefs +presents the contents of an MS Office document as a file system +on +.IR mtpt , +which defaults to +.BR /mnt/doc . +.I Mswordstrings +or +.I msexceltables +may then be used to parse the files inside, extracting +a text stream. +.I Msexceltables +may be given options to control the formatting of its output. +.TF "\fL-d \fIdelim" +.TP +.B -a +Attempt conversion of non-tabular sheets in the workbook (charts). +.TP +.BI -d " delim +Sets the inter-field delimiter to the string +.IR delim , +by default a single space. +.TP +.B -D +Enables debugging output. +.TP +.BI -c " range +.I Range +is a comma-separated list of column numbers and ranges. +Ranges are separated by dashes. +Limit processing to just those columns named; +by default all columns are output. +.TP +.B -n +Disables field padding to column width. +.TP +.B -q +Disable quoting of textural fields (see +.IR quote (2).) +.TP +.B -t +Truncate fields to the column width. +.TP +.BI -w " range +.I Range +is a comma-separated list of worksheet numbers and ranges, this +limits the sheets output using the same syntax as the +.B -c +option above. +Suppressed chart pages are always included in the sheet count. +.SH EXAMPLE +Extract pieces of an MS Excel spreadsheet. +.PD 0 +.IP +.EX +.SM +aux/olefs report.xls +msexceltables -q -w 1,7,9-14 -c 3-5 -n -d '@' /mnt/doc/Workbook > rpt.txt +unmount /mnt/doc +.EE +.PD +.SH SOURCE +.TF "\fL/sys/src/cmd/aux " +.TP +.B /rc/bin +.BR doc2txt , +.BR doc2ps , +.BR wdoc2txt, +and +.BR xls2txt +.TP +.B /sys/src/cmd/aux +the others +.fi +.PD +.SH SEE ALSO +.IR strings (1) +.br +``Microsoft Word 97 Binary File Format'', +at Microsoft's developer (MSDN) home page. +.br +``LAOLA Binary Structures'', +.B http://user.cs.tu-berlin.de/~schwartz/pmh +.br +``OpenOffice.Org's Excel Documentation'', +.br +.B http://sc.openoffice.org/excelfileformat.pdf diff --git a/sys/man/1/doctype b/sys/man/1/doctype new file mode 100755 index 000000000..7811f8e92 --- /dev/null +++ b/sys/man/1/doctype @@ -0,0 +1,63 @@ +.TH DOCTYPE 1 +.SH NAME +doctype \- intuit command line for formatting a document +.SH SYNOPSIS +.B doctype +[ +.B -n +] +[ +.B -T +.I dev +] +[ +.I file +] +\&... +.SH DESCRIPTION +.I Doctype +examines a +.IR troff (1) +input file to deduce the appropriate text formatting command +and prints it on standard output. +.I Doctype +recognizes input for +.IR troff (1), +related preprocessors like +.IR eqn (1), +and the +.IR ms (6) +and +.I mm +macro packages. +.PP +Option +.B -n +invokes +.I nroff +instead of +.IR troff . +The +.B -T +option is passed to +.IR troff . +.SH EXAMPLES +.TP +.L +eval `{doctype chapter.?} | lp +Typeset files named +.BR chapter.0 , +.BR chapter.1 , +\&... +.SH SOURCE +.B /rc/bin/doctype +.SH SEE ALSO +.IR troff (1), +.IR eqn (1), +.IR tbl (1), +.IR pic (1), +.IR grap (1), +.IR ms (6), +.IR man (6) +.SH BUGS +In true A.I. style, its best guesses are inspired rather than accurate. diff --git a/sys/man/1/du b/sys/man/1/du new file mode 100755 index 000000000..c7ecc71e6 --- /dev/null +++ b/sys/man/1/du @@ -0,0 +1,137 @@ +.TH DU 1 +.SH NAME +du \- disk usage +.SH SYNOPSIS +.B du +[ +.B -aefhnqstu +] [ +.B -b +.I size +] [ +.B -p +.I SI-prefix +] [ +.I file ... +] +.SH DESCRIPTION +.I Du +gives the number of Kbytes allocated to data blocks +of named +.I files +and, recursively, of files in named directories. +It assumes storage is quantized in units of 1024 bytes (Kbytes) by default. +Other values can be set by the +.B -b +option; +.I size +is the number of bytes, optionally suffixed +.B k +to specify multiplication by 1024. +If +.I file +is missing, +the current directory is used. +The count for a directory includes the counts of the +contained files and directories. +.PP +The +.B -a +option prints the number of blocks +for every file in a directory. +Normally counts are printed only for contained directories. +.PP +The +.B -f +option suppresses the printing of warning messages. +.PP +The +.B -n +option prints the size in bytes and the name of each file; it sets +.BR -a . +.PP +The +.B -t +option prints, in the format of +.B du +.BR -n , +the modified time of +each file rather than the size. +If the options +.B -tu +are specified then the accessed time is printed. +.PP +The +.B -q +option prints, in the format of +.B du +.BR -n , +the QID path of +each file rather than the size. +.PP +The +.B -s +option causes +.I du +to descend the hierarchy as always, but to print only a summary line +for each +.IR file . +.PP +The +.B -e +option causes +.I du +to print values (sizes, times or QID paths) +in `scientific notation' via +.IR print (2)'s +.BR %g . +.PP +The +.B -h +option causes +.I du +to print values (sizes, times or QID paths) +in scientific notation, +scaled to less than 1024, and with a suitable SI prefix +(e.g., +.L G +for binary gigabytes). +.PP +The +.B -p +option causes +.I du +to print values (sizes, times or QID paths) +in units of +.IR SI-prefix . +Case is ignored when looking up +.IR SI-prefix . +An empty +.IR SI-prefix +corresponds to a scale factor of 1 (e.g., print sizes in bytes). +.\" .PP +.\" The +.\" .B -r +.\" option causes +.\" .I du +.\" to read and discard every byte of every file encountered. +.SH EXAMPLES +Print the size of +.L /tmp +in fractional binary gigabytes: +.IP +.EX +% du -sepg /tmp +\&.6960154 /tmp +.EE +.LP +Print the size of +.L /tmp +in bytes and in scientific notation: +.IP +.EX +% du -sep '' /tmp +7.473408e+08 /tmp +.EE +.SH SOURCE +.B /sys/src/cmd/du.c diff --git a/sys/man/1/echo b/sys/man/1/echo new file mode 100755 index 000000000..86e6cd39b --- /dev/null +++ b/sys/man/1/echo @@ -0,0 +1,26 @@ +.TH ECHO 1 +.SH NAME +echo \- print arguments +.SH SYNOPSIS +.B echo +[ +.B -n +] +[ +.I arg ... +] +.SH DESCRIPTION +.I Echo +writes its arguments separated by blanks and terminated by +a newline on the standard output. +Option +.B -n +suppresses the newline. +.SH SOURCE +.B /sys/src/cmd/echo.c +.SH DIAGNOSTICS +If +.I echo +draws an error while writing to standard output, the exit status is +.LR "write error" . +Otherwise the exit status is empty. diff --git a/sys/man/1/ecp b/sys/man/1/ecp new file mode 100755 index 000000000..6be90dfc3 --- /dev/null +++ b/sys/man/1/ecp @@ -0,0 +1,141 @@ +.TH ECP 1 +.SH NAME +ecp \- fast copy, handling errors +.SH SYNOPSIS +.in +.5i +.ti -.5i +.B ecp +[ +.B \-bcprvZ +] [ +.B \-B +.I block-size +] [ +.B \-e +.I max-errors +] [ +.B \-i +.I issect +] [ +.B \-o +.I ossect +] [ +.B \-s +.I sector-size +] +.I sectors +.I input +.I output +.SH DESCRIPTION +.I Ecp +copies +.I sectors +disk sectors of the specified +.I input +file to the specified +.I output +file. +.I Ecp +copies multiple sectors (a `block') at a time for speed. +When +.I ecp +encounters an I/O error, +it transfers the current block again, +assuming the file is seekable, +one sector at a time, +prints the sector number(s) of the error(s), +and continues copying. +.PP +Options are: +.TP 4 +.B \-b +reblock +.IR input +on short reads; +this was used mainly when reading a pipe on standard input +on 4.2+BSD systems. +.TP +.B \-B +sets the block size (16,384 bytes by default) to +.IR block-size . +.TP +.B \-c +ask for confirmation on +.B /dev/cons +before starting the copy. +.TP +.B \-e +sets a maximum number of consecutive I/O errors to permit +at the beginning of the copy before quitting to +.IR max-errors . +Lots of consecutive errors may indicate a deeper problem, +such as missing media. +By default there is no limit. +.TP +.B \-i +seeks to sector +.I issect +(assuming zero-origin) +before beginning input. +.TP +.B \-o +seeks to sector +.I ossect +(assuming zero-origin) +before beginning output. +.TP +.B \-p +print reassuring progress reports; +helpful mainly when dealing with cranky hardware. +.TP +.B \-r +copy sector groups in reverse order, +assuming the files are seekable; +this is most useful when +.I input +and +.I output +overlap. +.TP +.B \-s +sets the sector size (512 bytes by default) to +.IR sector-size . +.TP +.B \-v +verify the copy by rereading the +.I input +and +.I output +files after copying all sectors. +This is intended to force the disk to deliver the actual +data written on it rather than some cached copy. +The locations of any differences are printed. +.TP +.B \-Z +`Swizzle' the input: stir the bits around in some fashion. +Intended for diagnosing bad disks by copying a disk to itself +a few times with swizzling on (to defeat caching in operating systems +or disk controllers). +.SH "SEE ALSO" +.I fcp +in +.IR cp (1), +.IR dd (1), +.IR dup (3) +.SH BUGS +.BR \-i , +.BR \-o , +.BR \-r , +.B \-v +and error retries only work on devices capable of seeking. +.PP +The set of options reflects decades of experience +dealing with troublesome hardware. +.PP +If the input file is a tape and +the last record on the tape before a file mark is less than +.I blocksize +bytes long, +then +.I ecp +will read through past the file mark and into the next file. diff --git a/sys/man/1/ed b/sys/man/1/ed new file mode 100755 index 000000000..adb79fb72 --- /dev/null +++ b/sys/man/1/ed @@ -0,0 +1,683 @@ +.TH ED 1 +.SH NAME +ed \- text editor +.SH SYNOPSIS +.B ed +[ +.B - +] +[ +.B -o +] +[ +.I file +] +.SH DESCRIPTION +.I Ed +is a venerable text editor. +.PP +If a +.I file +argument is given, +.I ed +simulates an +.L e +command (see below) on that file: +it is read into +.I ed's +buffer so that it can be edited. +The options are +.TP +.B - +Suppress the printing +of character counts by +.LR e , +.LR r , +and +.L w +commands and of the confirming +.L ! +by +.L ! +commands. +.TP +.B -o +(for output piping) +Write all output to the standard error file except writing by +.L w +commands. +If no +.I file +is given, make +.B /fd/1 +the remembered file; see the +.L e +command below. +.PP +.I Ed +operates on a `buffer', a copy of the file it is editing; +changes made +in the buffer have no effect on the file until a +.L w +(write) +command is given. +The copy of the text being edited resides +in a temporary file called the +.IR buffer . +.PP +Commands to +.I ed +have a simple and regular structure: zero, one, or +two +.I addresses +followed by a single character +.IR command , +possibly +followed by parameters to the command. +These addresses specify one or more lines in the buffer. +Missing addresses are supplied by default. +.PP +In general, only one command may appear on a line. +Certain commands allow the +addition of text to the buffer. +While +.I ed +is accepting text, it is said +to be in +.I "input mode." +In this mode, no commands are recognized; +all input is merely collected. +Input mode is left by typing a period +.L . +alone at the +beginning of a line. +.PP +.I Ed +supports the +.I "regular expression" +notation described in +.IR regexp (6). +Regular expressions are used in addresses to specify +lines and in one command +(see +.I s +below) +to specify a portion of a line which is to be replaced. +If it is desired to use one of +the regular expression metacharacters as an ordinary +character, that character may be preceded by +.RB ` \e '. +This also applies to the character bounding the regular +expression (often +.LR / ) +and to +.L \e +itself. +.PP +To understand addressing in +.I ed +it is necessary to know that at any time there is a +.I "current line." +Generally, the current line is +the last line affected by a command; however, +the exact effect on the current line +is discussed under the description of +each command. +Addresses are constructed as follows. +.TP +1. +The character +.LR . , +customarily called `dot', +addresses the current line. +.TP +2. +The character +.L $ +addresses the last line of the buffer. +.TP +3. +A decimal number +.I n +addresses the +.IR n -th +line of the buffer. +.TP +4. +.BI \'x +addresses the line marked with the name +.IR x , +which must be a lower-case letter. +Lines are marked with the +.L k +command. +.TP +5. +A regular expression enclosed in slashes ( +.LR / ) +addresses +the line found by searching forward from the current line +and stopping at the first line containing a +string that matches the regular expression. +If necessary the search wraps around to the beginning of the +buffer. +.TP +6. +A regular expression enclosed in queries +.L ? +addresses +the line found by searching backward from the current line +and stopping at the first line containing +a string that matches the regular expression. +If necessary +the search wraps around to the end of the buffer. +.TP +7. +An address followed by a plus sign +.L + +or a minus sign +.L - +followed by a decimal number specifies that address plus +(resp. minus) the indicated number of lines. +The plus sign may be omitted. +.TP +8. +An address followed by +.L + +(or +.LR - ) +followed by a +regular expression enclosed in slashes specifies the first +matching line following (or preceding) that address. +The search wraps around if necessary. +The +.L + +may be omitted, so +.L 0/x/ +addresses the +.I first +line in the buffer with an +.LR x . +Enclosing the regular expression in +.L ? +reverses the search direction. +.TP +9. +If an address begins with +.L + +or +.L - +the addition or subtraction is taken with respect to the current line; +e.g.\& +.L -5 +is understood to mean +.LR .-5 . +.TP +10. +If an address ends with +.L + +or +.LR - , +then 1 is added (resp. subtracted). +As a consequence of this rule and rule 9, +the address +.L - +refers to the line before the current line. +Moreover, +trailing +.L + +and +.L - +characters +have cumulative effect, so +.L -- +refers to the current +line less 2. +.TP +11. +To maintain compatibility with earlier versions of the editor, +the character +.L ^ +in addresses is +equivalent to +.LR - . +.PP +Commands may require zero, one, or two addresses. +Commands which require no addresses regard the presence +of an address as an error. +Commands which accept one or two addresses +assume default addresses when insufficient are given. +If more addresses are given than a command requires, +the last one or two (depending on what is accepted) are used. +.PP +Addresses are separated from each other typically by a comma +.LR , . +They may also be separated by a semicolon +.LR ; . +In this case the current line +is set to +the previous address before the next address is interpreted. +If no address precedes a comma or semicolon, line 1 is assumed; +if no address follows, the last line of the buffer is assumed. +The second address of any two-address sequence +must correspond to a line following the line corresponding to the first address. +.PP +In the following list of +.I ed +commands, the default addresses +are shown in parentheses. +The parentheses are not part of +the address, but are used to show that the given addresses are +the default. +`Dot' means the current line. +.TP +.RB (\|\fL.\fP\|) \|a +.br +.ns +.TP + +.br +.ns +.TP +.B . +Read the given text +and append it after the addressed line. +Dot is left +on the last line input, if there +were any, otherwise at the addressed line. +Address +.L 0 +is legal for this command; text is placed +at the beginning of the buffer. +.TP +.RB (\|\fL.,.\fP\|) \|b [ +- ][\fIpagesize\fP][ pln\fR] +Browse. +Print a `page', normally 20 lines. +The optional +.L + +(default) or +.L - +specifies whether the next or previous +page is to be printed. +The optional +.I pagesize +is the number of lines in a page. +The optional +.LR p , +.LR n , +or +.L l +causes printing in the specified format, initially +.LR p . +Pagesize and format are remembered between +.L b +commands. +Dot is left at the last line displayed. +.TP +.RB (\|\fL.,.\fP\|) \|c +.br +.ns +.TP + +.br +.ns +.TP +.B . +Change. +Delete the addressed lines, then accept input +text to replace these lines. +Dot is left at the last line input; if there were none, +it is left at the line preceding the deleted lines. +.TP +.RB (\|\fL.,.\fP\|) \|d +Delete the addressed lines from the buffer. +Dot is set to the line following the last line deleted, or to +the last line of the buffer if the deleted lines had no successor. +.TP +.BI e " filename" +Edit. +Delete the entire contents of the buffer; +then read the named file into the buffer. +Dot is set to the last line of the buffer. +The number of characters read is typed. +The file name is remembered for possible use in later +.LR e , +.LR r , +or +.L w +commands. +If +.I filename +is missing, the remembered name is used. +.TP +.BI E " filename" +Unconditional +.LR e ; +see +.RL ` q ' +below. +.TP +.BI f " filename" +Print the currently remembered file name. +If +.I filename +is given, +the currently remembered file name is first changed to +.IR filename . +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/\fIcommand\ list\fP +.PD 0 +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/ +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP +.PD +Global. +First mark every line which matches +the given +.IR regular expression . +Then for every such line, execute the +.I command list +with dot initially set to that line. +A single command or the first of multiple commands +appears on the same line with the global command. +All lines of a multi-line list except the last line must end with +.LR \e . +The +.RB \&` \&. \&' +terminating input mode for an +.LR a , +.LR i , +.L c +command may be omitted if it would be on the +last line of the command list. +The commands +.L g +and +.L v +are not permitted in the command list. +Any character other than space or newline may +be used instead of +.L / +to delimit the regular expression. +The second and third forms mean +.BI g/ regular\ expression /p \f1. +.TP +.RB (\| .\| ) \|i +.PD 0 +.TP + +.TP +.B . +Insert the given text before the addressed line. +Dot is left at the last line input, or, if there were none, +at the line before the addressed line. +This command differs from the +.I a +command only in the placement of the +text. +.PD +.TP +.RB (\| .,.+1 \|) \|j +Join the addressed lines into a single line; +intermediate newlines are deleted. +Dot is left at the resulting line. +.TP +.RB (\|\fL.\fP\|) \|k\fIx\fP +Mark the addressed line with name +.IR x , +which must be a lower-case letter. +The address form +.BI \' x +then addresses this line. +.ne 2.5 +.TP +.RB (\|\fL.,.\fP\|) \|l +List. +Print the addressed lines in an unambiguous way: +a tab is printed as +.LR \et , +a backspace as +.LR \eb , +backslashes as +.LR \e\e , +and non-printing characters as +a backslash, an +.LR x , +and four hexadecimal digits. +Long lines are folded, +with the second and subsequent sub-lines indented one tab stop. +If the last character in the line is a blank, +it is followed by +.LR \en . +An +.L l +may be appended, like +.LR p , +to any non-I/O command. +.TP +.RB (\|\fL.,.\fP\|) \|m\fIa +Move. +Reposition the addressed lines after the line +addressed by +.IR a . +Dot is left at the last moved line. +.TP +.RB (\|\fL.,.\fP\|) \|n +Number. +Perform +.LR p , +prefixing each line with its line number and a tab. +An +.L n +may be appended, like +.LR p , +to any non-I/O command. +.TP +.RB (\|\fL.,.\fP\|) \|p +Print the addressed lines. +Dot is left at the last line printed. +A +.L p +appended to any non-I/O command causes the then current line +to be printed after the command is executed. +.TP +.RB (\|\fL.,.\fP\|) \|P +This command is a synonym for +.LR p . +.TP +.B q +Quit the editor. +No automatic write +of a file is done. +A +.L q +or +.L e +command is considered to be in error if the buffer has +been modified since the last +.LR w , +.LR q , +or +.L e +command. +.TP +.B Q +Quit unconditionally. +.TP +.RB ( $ )\|r\ \fIfilename\fP +Read in the given file after the addressed line. +If no +.I filename +is given, the remembered file name is used. +The file name is remembered if there were no +remembered file name already. +If the read is successful, the number of characters +read is printed. +Dot is left at the last line read from the file. +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/ +.PD 0 +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/g +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP +.PD +Substitute. +Search each addressed +line for an occurrence of the specified regular expression. +On each line in which +.I n +matches are found +.RI ( n +defaults to 1 if missing), +the +.IR n th +matched string is replaced by the replacement specified. +If the global replacement indicator +.L g +appears after the command, +all subsequent matches on the line are also replaced. +It is an error for the substitution to fail on all addressed lines. +Any character other than space or newline +may be used instead of +.L / +to delimit the regular expression +and the replacement. +Dot is left at the last line substituted. +The third form means +.BI s n / regular\ expression / replacement\fP/p\f1. +The second +.L / +may be omitted if the replacement is +empty. +.IP +An ampersand +.L & +appearing in the replacement +is replaced by the string matching the regular expression. +The characters +.BI \e n\f1, +where +.I n +is a digit, +are replaced by the text matched by the +.IR n -th +regular subexpression +enclosed between +.L ( +and +.LR ) . +When +nested parenthesized subexpressions +are present, +.I n +is determined by counting occurrences of +.L ( +starting from the left. +.IP +A literal +.LR & , +.LR / , +.L \e +or newline may be included in a replacement +by prefixing it with +.LR \e . +.TP +.RB (\|\fL.,.\fP\|) \|t\|\fIa +Transfer. +Copy the addressed lines +after the line addressed by +.IR a . +Dot is left at the last line of the copy. +.TP +.RB (\|\fL.,.\fP\|) \|u +Undo. +Restore the preceding contents +of the first addressed line (sic), which must be the last line +in which a substitution was made (double sic). +.TP +.RB (\|\fL1,$\fP\|) \|v/\fIregular\ expression\fP/\fIcommand\ list\fP +This command is the same as the global command +.L g +except that the command list is executed with +dot initially set to every line +.I except +those +matching the regular expression. +.TP +.RB (\|\fL1,$\fP\|) \|w " \fIfilename\fP" +Write the addressed lines to +the given file. +If the file does not exist, +it is created with mode 666 (readable and writable by everyone). +If no +.I filename +is given, the remembered file name, if any, is used. +The file name is remembered if there were no +remembered file name already. +Dot is unchanged. +If the write is successful, the number of characters written is +printed. +.TP +.RB (\|\fL1,$\fP\|) \|W " \fIfilename\fP" +Perform +.LR w , +but append to, instead of overwriting, any existing file contents. +.TP +.RB ( $ ) \|= +Print the line number of the addressed line. +Dot is unchanged. +.TP +.BI ! shell\ command +Send the remainder of the line after the +.L ! +to +.IR rc (1) +to be interpreted as a command. +Dot is unchanged. +.TP +.RB (\| .+1 )\| +An address without a command is taken as a +.L p +command. +A terminal +.L / +may be omitted from the address. +A blank line alone is equivalent to +.LR .+1p ; +it is useful +for stepping through text. +.PP +If an interrupt signal +.SM (DEL) +is sent, +.I ed +prints a +.L ? +and returns to its command level. +.PP +When reading a file, +.I ed +discards +.SM NUL +characters +and all characters after the last newline. +.SH FILES +.B /tmp/e* +.br +.B ed.hup +\ \ work is saved here if terminal hangs up +.SH SOURCE +.B /sys/src/cmd/ed.c +.SH "SEE ALSO" +.IR sam (1), +.IR sed (1), +.IR regexp (6) +.SH DIAGNOSTICS +.BI ? name +for inaccessible file; +.L ?TMP +for temporary file overflow; +.L ? +for errors in commands or other overflows. diff --git a/sys/man/1/emacs b/sys/man/1/emacs new file mode 100755 index 000000000..3854c528f --- /dev/null +++ b/sys/man/1/emacs @@ -0,0 +1,17 @@ +.TH EMACS 1 +.SH NAME +emacs \- editor macros +.SH SYNOPSIS +.B emacs +[ +.I options +] +.SH DESCRIPTION +This page intentionally left blank. +.SH SOURCE +MIT +.SH SEE ALSO +.IR sam (1), +.IR vi (1) +.SH BUGS +Yes. diff --git a/sys/man/1/eqn b/sys/man/1/eqn new file mode 100755 index 000000000..7c917cdbe --- /dev/null +++ b/sys/man/1/eqn @@ -0,0 +1,339 @@ +.TH EQN 1 +.EQ +delim $$ +.EN +.SH NAME +eqn \- typeset mathematics +.SH SYNOPSIS +.B eqn +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Eqn +is a +.IR troff (1) +preprocessor +for typesetting mathematics +on a typesetter. +Usage is almost always +.IP +.L +eqn file ... | troff +.PP +If no files are specified, +.I eqn +reads from the standard input. +.I Eqn +prepares output for the typesetter +named in the +.BI -T dest +option (default +.BR -Tutf ; +see +.IR troff (1)). +When run with other preprocessor filters, +.I eqn +usually comes last. +.PP +A line beginning with +.B .EQ +marks the start of an equation; +the end of an equation +is marked by a line beginning with +.BR .EN . +Neither of these lines is altered, +so they may be defined in macro packages +to get +centering, numbering, etc. +It is also possible to set two characters +as `delimiters'; +text between delimiters is also +.I eqn +input. +Delimiters may be set to characters +.I x +and +.I y +with the option +.BI -d xy +or (more commonly) with +.B delim +.I xy +between +.B .EQ +and +.BR .EN . +Left and right delimiters may be identical. +(They are customarily taken to be +$font L "$$" )$. +Delimiters are turned off by +.LR "delim off" . +All text that is neither between delimiters nor between +.B .EQ +and +.B .EN +is passed through untouched. +.PP +Tokens within +.I eqn +are separated by +spaces, tabs, newlines, braces, double quotes, +tildes or circumflexes. +Braces {} are used for grouping; +generally speaking, +anywhere a single character like +.L x +could appear, a complicated construction +enclosed in braces may be used instead. +Tilde +.L ~ +represents a full space in the output, +circumflex +.L ^ +half as much. +.PP +.vs 13p +Subscripts and superscripts are produced with the keywords +.B sub +and +.BR sup . +Thus +.L "x sub i" +makes +$x sub i$, +.L "a sub i sup 2" +produces +$a sub i sup 2$, +and +.L "e sup {x sup 2 + y sup 2}" +gives +$e sup {x sup 2 + y sup 2}$. +.PP +.B Over +makes fractions: +.L "a over b" +yields $a over b$. +.PP +.B Sqrt +produces square roots: +.L "1 over sqrt {ax sup 2 +bx+c}" +results in +$1 over sqrt {ax sup 2 +bx+c}$ . +.PP +The keywords +.B from +and +.B to +introduce lower and upper +limits on arbitrary things: +$lim from {n -> inf} sum from 0 to n x sub i$ +is made with +.LR "lim from {n -> inf} sum from 0 to n x sub i" . +.PP +Left and right brackets, braces, etc., of the right height are made with +.B left +and +.BR right : +.L "left [ x sup 2 + y sup 2 over alpha right ] ~=~1" +produces +$left [ x sup 2 + y sup 2 over alpha right ] ~=~1$. +The +.B right +clause is optional. +Legal characters after +.B left +and +.B right +are braces, brackets, bars, +.B c +and +.B f +for ceiling and floor, +and +.B +"" +for nothing at all (useful for a right-side-only bracket). +.PP +Vertical piles of things are made with +.BR pile , +.BR lpile , +.BR cpile , +and +.BR rpile : +.L "pile {a above b above c}" +produces +$pile {a above b above c}$. +There can be an arbitrary number of elements in a pile. +.B lpile +left-justifies, +.B pile +and +.B cpile +center, with different vertical spacing, +and +.B rpile +right justifies. +.PP +Matrices are made with +.BR matrix : +.L "matrix { lcol { x sub i above y sub 2 } ccol { 1 above 2 } }" +produces +$matrix { lcol { x sub i above y sub 2 } ccol { 1 above 2 } }$. +In addition, there is +.B rcol +for a right-justified column. +.PP +.vs 12p +Diacritical marks are made with +.BR prime , +.BR dot , +.BR dotdot , +.BR hat , +.BR tilde , +.BR bar , +.BR under , +.BR vec , +.BR dyad , +and +.BR under : +.L "x sub 0 sup prime = f(t) bar + g(t) under" +is +$x sub 0 sup prime = f(t) bar + g(t) under$, +and +.L "x vec = y dyad" +is +$x vec = y dyad$. +.PP +Sizes and fonts can be changed with prefix operators +.B size +.IR n , +.B size +.BI ± n \f1, +.BR fat , +.BR roman , +.BR italic , +.BR bold , +or +.BR font +.IR n . +Size and fonts can be changed globally in a document by +.B gsize +.I n +and +.B gfont +.IR n , +or by the command-line arguments +.BI -s n +and +.BI -f n\f1. +.PP +Normally subscripts and superscripts are reduced by +3 point sizes from the previous size; +this may be changed by the command-line argument +.BI -p n\f1. +.PP +Successive display arguments can be lined up. +Place +.B mark +before the desired lineup point in the first equation; +place +.B lineup +at the place that is to line up vertically in subsequent equations. +.PP +Shorthands may be defined +or existing keywords redefined with +.BR define : +.L define +.I thing +.L % +.I replacement +.L % +defines a new token called +.I thing +which will be replaced by +.I replacement +whenever it appears thereafter. +The +.L % +may be any character that does not occur in +.LR replacement . +.PP +Keywords like +.L sum +.EQ +( sum ), +.EN +.L int +.EQ +( int ), +.EN +.L inf +.EQ +( inf ), +.EN +and shorthands like +.L >= +.EQ +(>=), +.EN +.L -> +.EQ +(->), +.EN +and +.L != +.EQ +( != ) +.EN +are recognized. +Greek letters are spelled out in the desired case, as in +.L alpha +or +.LR GAMMA . +Mathematical words like +.LR sin , +.LR cos , +.L log +are made Roman automatically. +.IR Troff (1) +four-character escapes like +.L \e(lh +(\(lh) can be used anywhere. +Strings enclosed in double quotes " " +are passed through untouched; +this permits keywords to be entered as text, +and can be used to communicate +with +.I troff +when all else fails. +.SH FILES +.TF /sys/lib/troff/font/devutf +.TP +.B /sys/lib/troff/font/devutf +font descriptions for PostScript +.SH SOURCE +.B /sys/src/cmd/eqn +.SH "SEE ALSO" +.IR troff (1), +.IR tbl (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual''. +.br +B. W. Kernighan and L. L. Cherry, +``Typesetting Mathematics\(emUser's Guide'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.SH BUGS +To embolden digits, parens, etc., +it is necessary to quote them, +as in +.LR bold\ "12.3" . +.EQ +delim off +.EN diff --git a/sys/man/1/expect b/sys/man/1/expect new file mode 100755 index 000000000..95ea52b30 --- /dev/null +++ b/sys/man/1/expect @@ -0,0 +1,172 @@ +.TH EXPECT 1 +.SH NAME +at, drain, expect, pass \- dialer scripting tools +.SH SYNOPSIS +.B dial/at +[ +.B -q +] [ +.B -t +.I seconds +] +atcommand +.br +.B dial/expect +[ +.B -iq +] [ +.B -t +.I seconds +] +.I goodstring +[ +.IR badstring ... +] +.br +.B dial/drain +.br +.B dial/pass +[ +.B -q +] +.SH DESCRIPTION +These commands are used to write telephone dialing +scripts, mostly for PPP sessions. They all expect standard input and +output to be connected to a communications device, e.g, +a serial line to a modem. They communicate with the user using +.BR /dev/cons . +.PP +.I At +sends +.B atcommand +to the modem prefixed with the string +.BR at . +It then reads from the modem expecting an AT response. +.I At +will return success if it gets and +.B OK +of +.B CONNECT +response. Otherwise it will return the response as an +error status. The options are: +.TP +.B -t +set the timeout to +.IR seconds . +The default is 300. +.TP +.B -q +don't write to +.B /dev/cons +what is read from standard in. The default is +to copy everything through. +.PD +.PP +.I Expect +reads standard input looking for one of the strings given +as arguments. Reading the first string causes a successul exit +status. Reading any of the others causes an exit status equal to +the string. The command also terminates on a timeout. The options +are: +.TP +.B -t +set the timeout to +.IR seconds . +The default is 300. +.TP +.B -i +ignore case when doing the matches. +.TP +.B -q +don't write to +.B /dev/cons +what is read from standard in. The default is +to copy everything through. +.PD +.PP +.I Pass +copies input from +.B /dev/cons +to standard output. +It terminates on a newline. The only flag is +.B -q +and means the same as it does for +.IR expect . +.PP +.I Drain +discards any input waiting on standard input. It +is used to sync up the stream at the start of dialing +or after an error. +.SH EXAMPLE +The following +.B rc +script dials out through a Hayes compatible modem on +.B /dev/eia1 +and lets the user type in a user name and password +before starting +.BR ppp . +.EX +#!/bin/rc +dev=/dev/eia1 +telno=18005551212 + +fn initfn { + dial/drain + echo +++ + dial/at zh0 +} + +fn dialfn { + dial/drain + dial/at dt^$telno +} +{ + # set up uart + if( test -e $dev^ctl ){ + echo -n b^$baud + echo -n m1 # cts/rts flow control + echo -n q64000 # big buffer + echo -n n1 # nonblocking writes + echo -n r1 # rts on + echo -n d1 # dtr on + echo -n c1 # handup when we lose dcd + } > $dev^ctl + + # get the modem's attention + while( ! initfn ) + sleep 1 + + # dial + while( ! dialfn ) + sleep 30 + + if( ! dial/expect -it 60 'username:' ){ + echo can''t connect >[1=2] + exit connect + } + dial/pass + if( ! dial/expect -it 60 'password:' ){ + echo can''t connect >[1=2] + exit connect + } + dial/pass + if( ! dial/expect -t 60 'ppp or telnet:' ){ + echo can''t connect >[1=2] + exit connect + } + echo ppp + dial/expect -t 5 something + echo connected >[1=2] + + # start ppp + ip/ppp $primary -f +} < $dev > $dev +.EE +.SH FILES +.B /rc/bin/ipconf/* +example dialer scripts for ppp +.SH SOURCE +.B /sys/src/cmd/dial/*.c +.SH SEE ALSO +.IR ppp (8), +.IR telco (4) diff --git a/sys/man/1/faces b/sys/man/1/faces new file mode 100755 index 000000000..633fb688b --- /dev/null +++ b/sys/man/1/faces @@ -0,0 +1,124 @@ +.TH FACES 1 +.SH NAME +faces, seemail, vwhois \- mailbox interface +.SH SYNOPSIS +.B faces +[ +.B -ih +] [ +.B -m +.I maildir +] +.br +.B seemail +.br +.B vwhois +.I person +\&... +.SH DESCRIPTION +The +.I faces +command monitors incoming mail and +displays in its window a representation of the user's mail box +using a small image for each message. +The image is typically a portrait of the sender. Which image to +display is determined by two directories /usr/$user/lib/face +and /lib/face. Entries in /usr/$user/lib/face take priority over +those in /lib/face. See +.IR face (6), +for how these directories are organised. +.PP +If the user is running +.IR plumber (4), +.I faces +reacts to plumb messages to the +.B seemail +port, +typically from +.BR upas/fs , +and is thus notified of message additions and deletions. +.PP +Right-clicking on a message icon causes that message to be `plumbed' to +.BR showmail . +A typical plumb action will be to display the message, such as by +the rule +.EX + plumb start window mail -s $0 +.EE +The +.IR acme (1) +mail reader listens to the +.B showmail +port automatically. +.PP +If the user is not running +.IR plumber , +.I faces +reads the log file +.F /sys/log/mail +and right-clicking has no effect. +.PP +If arrows are visible, clicking on them will scroll the display. +Middle-clicking on the arrows scrolls to the end. +.PP +Starting +.B faces +with the +.B -i +flag causes +.B faces +to read the messages in +.BR /mail/fs/mbox +— or the mailboxes specified with the +.B -m +flag — +upon startup. +.PP +The +.B -m +option directs +.I faces +to watch for messages arriving in +.I maildir +instead of +.BR /mail/fs/mbox . +Multiple +.B -m +flags may be used to watch multiple mailboxes. +.PP +The +.B -h +flag causes a different, venerable behavior in which +the window displays the history of messages received +rather than the current state of the mail box. +In particular, faces are not removed from the screen when messages are deleted. +Also, in this mode clicking button 1 in the display will clear the window. +.PP +.I Seemail +is an +.IR rc (1) +script that invokes +.B faces +.BR -h . +.PP +.I Vwhois +tells +.I faces +to display the icons of the named +.IR persons , +without sending a message. +.SH FILES +.BR /mail/fs/mbox " mail directory. +.SH SOURCE +.B /sys/src/cmd/faces +.br +.B /rc/bin/seemail +.br +.B /rc/bin/vwhois +.SH "SEE ALSO" +.IR mail (1), +.IR marshal (1), +.IR nedmail (1), +.IR plumber (4), +.IR face (6), +.IR plumb (6) diff --git a/sys/man/1/factor b/sys/man/1/factor new file mode 100755 index 000000000..10baf9960 --- /dev/null +++ b/sys/man/1/factor @@ -0,0 +1,64 @@ +.TH FACTOR 1 +.CT 1 numbers +.SH NAME +factor, primes \- factor a number, generate large primes +.SH SYNOPSIS +.B factor +[ +.I number +] +.PP +.B primes +.I start +[ +.I finish +] +.SH DESCRIPTION +.I Factor +prints +.I number +and its prime factors, +each repeated the proper number of times. +The number must be positive and less than +.if n 2**54 +.if t 2\u\s754\s0\d +(about +.if n 1.8e16) +.if t 1.8\(mu10\u\s716\s0\d\|). +.PP +If no +.I number +is given, +.I factor +reads a stream of numbers from the standard input and factors them. +It exits on any input not a positive integer. +Maximum running time is proportional to +.if n sqrt(n). +.if t .I \(sr\o'n\(rn'\f1. +.PP +.PP +.I Primes +prints the prime numbers ranging from +.I start +to +.IR finish , +where +.I start +and +.I finish +are positive numbers less than +.if n 2**56. +.if t 2\u\s756\s0\d. +If +.I finish +is missing, +.I primes +prints without end; +if +.I start +is missing, it reads the starting number from the +standard input. +.SH SOURCE +.B /sys/src/cmd/factor.c +.br +.B /sys/src/cmd/primes.c diff --git a/sys/man/1/fedex b/sys/man/1/fedex new file mode 100755 index 000000000..0434382ec --- /dev/null +++ b/sys/man/1/fedex @@ -0,0 +1,27 @@ +.TH FEDEX 1 +.SH NAME +fedex, ups, usps \- track shipments +.SH SYNOPSIS +.B fedex +.I tracking-number +.br +.B ups +.I tracking-number +.br +.B usps +.I tracking-number +.SH DESCRIPTION +.I Fedex +writes available shipment details for the given Federal Express 12-digit +.I tracking-number +on the standard output. +.I Ups +is similar, but takes a United Parcel Service 18-digit +.IR tracking-number . +.I Usps +takes a US Post Office +.IR tracking-number . +.SH SOURCE +.B /rc/bin +.SH BUGS +Redesigns of the source website can break these programs. diff --git a/sys/man/1/file b/sys/man/1/file new file mode 100755 index 000000000..40b0d3b64 --- /dev/null +++ b/sys/man/1/file @@ -0,0 +1,112 @@ +.TH FILE 1 +.SH NAME +file \- determine file type +.SH SYNOPSIS +.B file +[ +.B -m +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I File +performs a series of tests on its argument +.I files +in an attempt to classify their contents by language or purpose. +If no arguments are given, the classification is performed +on standard input. +.PP +If the +.B -m +flag is given, +.I file +outputs an +appropriate MIME +.B Content-Type +specification describing the +.B type +and +.B subtype +of each file. +.PP +The file types it looks for include +directory, +device file, +zero-filled file, +empty file, +Plan 9 executable, +PAC audio file, +.B cpio +archive, +.B tex +.B dvi +file, +archive symbol table, +archive, +.B rc +script, +.B sh +script, +PostScript, +.B troff +output file for various devices, +mail box, +GIF, +FAX, +object code, +C and Alef source, +assembler source, +compressed files, +encrypted file, +English text, +compressed image, +image, +subfont, +and +font. +.PP +If a file has no apparent format, +.I file +looks at the character set it uses to classify it according to +.SM ASCII\c +, +extended +.SM ASCII\c +, Latin +.SM ASCII\c +, or +.SM UTF +holding one or more of the following blocks of the Unicode Standard: +Extended Latin, +Greek, +Cyrillic, +Armenian, +Hebrew, +Arabic, +Devanagari, +Bengali, +Gurmukhi, +Gujarati, +Oriya, +Tamil, +Telugu, +Kannada, +Malayalam, +Thai, +Lao, +Tibetan, +Georgian, +Japanese, +Chinese, +or Korean. +.PP +If all else fails, +.I file +decides its input is +binary. +.SH SOURCE +.B /sys/src/cmd/file.c +.SH BUGS +It can make mistakes. diff --git a/sys/man/1/filter b/sys/man/1/filter new file mode 100755 index 000000000..ae86aa336 --- /dev/null +++ b/sys/man/1/filter @@ -0,0 +1,320 @@ +.TH FILTER 1 +.SH NAME +filter, list, deliver, token, vf \- filtering mail +.SH SYNOPSIS +.B upas/filter +[ +.B -bh +] +.I rcvr +.I mailbox +[ +.I "regexp file +] ... +.PP +.B upas/list +[ +.B -d +] +.B add|check +.I patternfile +.I addressfile ... +.PP +.B upas/deliver +.I recipient +.I fromfile +.I mbox +.PP +.B upas/token +.I key +[ +.I tokenfile +] +.PP +.B upas/vf +[ +.B -r +] +[ +.B -s +.I savefile +] +.SH DESCRIPTION +A user may filter all incoming mail by creating +a world readable/executable file +.BI /mail/box/ username /pipeto. +If the file is a shell script, it can use the +commands described here to implement a filter. +.PP +.I Filter +provides simple mail filtering. +The first two arguments are the recipient's address and mailbox, that is, +the same arguments provided to +.BR pipeto . +The remaining arguments are all pairs of a regular expression and a file name. +With no flags, the sender's address is matched against each +regular expression starting with the first. If the expression +matches, then the message is delivered to the file whose name +follows the expression. The file must be world writable and should +be append only. +A message that matches none of the expressions is delivered into +the user's standard mail box. +.PP +By default, +.I filter +matches each regular expression against the message's sender. +The +.B -h +flag causes +.I filter +to match against the entire header, +and the +.B -b +flag causes +.I filter +to match against the entire message (header and body). +.PP +For example, to delete any messages of precedence bulk, place in +your +.B pipeto +file: +.IP +.EX +/bin/upas/filter -h $1 $2 'Precedence: bulk' /dev/null +.EE +.PP +Three other commands exist which, combined by an +.IR rc (1) +script, allow you to build your own filter. +.PP +.I List +takes two verbs; +.B check +and +.BR add . +.B Check +directs +.I list +to check each address contained in the +.IR addressfile s +against a list of patterns in +.IR patternfile . +Patterns come in four forms: +.TF ~\fIregular-expression\fP +.PD +.TP +.B ~\fIregular-expression\fP +If any address matches the regular expression, +.I list +returns successfully. +.TP +.BR =\fIstring\fP . +If any address exactly matches +.IR string , +.I list +returns successfully. +.TP +.B !~\fIregular-expression\fP +If any address matches the regular expression +and no other address matches a non `!' rule, +.I list +returns error status "!match". +.TP +.B !=\fIstring\fP +If any address exactly matches +.I string +and no other address matches a non `!' rule, +.I list +returns error status "!match". +.PP +If no addresses match a pattern, +.I list +returns "no match". +.PP +The pattern file may also contain lines of the form +.IP +.EX +#include filename +.EE +.LP +to allow pattern files to include other pattern files. +All pattern matches are case insensitive. +.I List +searches the pattern file (and its includes) in order. +The first matching pattern determines the action. +.PP +.I List +.B add +directs +.I list +to add a pattern to +.I patternfile +for each address in the +.I addressfiles +that doesh't already match a pattern. +.PP +.IR Token , +with only one argument, prints to standard output a unique token +created from the current date and +.IR key . +With two arguments, it checks +.I token +against tokens created over the last 10 days with +.IR key . +If a match is found, it returns successfully. +.PP +.I Deliver +delivers into mail box +.I mbox +the message read from standard input. +It obeys standard mail file locking and logging +conventions. +.PP +.B /sys/src/cmd/upas/filterkit/pipeto.sample +is a sample +.B pipeto +using the filter kit. +.PP +A sample +.BR pipefrom , +.BR /sys/src/cmd/upas/filterkit/pipefrom.sample , +is provided which adds all addresses of your outgoing +mail to your pattern file. +You should copy it into a directory that normally gets +bound by your profile onto +.BR /bin . +.PP +.I Vf +(virus filter) +takes a mail message as standard input +and searches for executable MIME attachments, +either rewriting them to be non-executable or +rejecting the message. +The behavior depends on the attachment's file name +extension and MIME content type. +.B /sys/lib/mimetype +contains the list of known extensions and MIME content types. +The fifth field of each line specifies the +safety of a particular file type: +.B y +(yes), +.B m +(maybe; treated same as yes), +.B n +(no), +.B p +(previous), +or +.B r +(reject). +.I Vf +allows attachments with safety +.B y +or +.B m +to pass through unaltered. +Attachments with safety +.B n +both are wrapped in extra MIME headers +and have +.B .suspect +appended to their file names, to avoid +automatic execution by mail readers. +Attachments with safety +.B r +(currently, +.BR .bat , +.BR .com , +.BR .exe , +and +.BR .scr , +all Microsoft executable extensions) +are taken as +cause for the entire message to be rejected. +A safety of +.B p +(used for the +.B x-gunzip +mime type) +causes the previous extension to be tested, +so that +.B x.tar.gz +is treated the same as +.BR x.tar . +.PP +If +.B /mail/lib/validateattachment +exists and is executable, +.B vf +runs it on all attachments with safety +.B n +(attachments it would normally sanitize). +If +.IR validateattachment 's +exit status contains the string +.LR discard , +.I vf +rejects the entire message. +If the status contains the string +.LR accept , +.I vf +does not sanitize the attachment. +Otherwise, +.I vf +sanitizes the attachment as before. +The standard +.I validateattachment +uses +.IR file (1) +to determine the file type. +It accepts text and image files +and discards messages containing +executables or +.I zip +(see +.IR gzip (1)) +archives of executables. +.PP +The +.B -r +option causes +.I vf +not to sanitize MIME attachments, but instead to +reject messages it determines to be viruses. +The +.B -s +option causes +.I vf +to log all attachments of safety +.B r +in the mail box +.IR savefile . +.SH FILES +.TF /mail/lib/validateattachment +.TP +.B /mail/box/*/pipeto +mail filter +.TP +.B /sys/lib/mimetype +MIME content types +.TP +.B /mail/lib/validateattachment +attachment checker +.SH SOURCE +.B /sys/src/cmd/upas/send +.br +.B /sys/src/cmd/upas/filterkit +.br +.B /sys/src/cmd/upas/vf +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR mail (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR smtp (8), +.IR upasfs (4) diff --git a/sys/man/1/fmt b/sys/man/1/fmt new file mode 100755 index 000000000..511860018 --- /dev/null +++ b/sys/man/1/fmt @@ -0,0 +1,90 @@ +.TH FMT 1 +.SH NAME +fmt, htmlfmt \- simple text formatters +.SH SYNOPSIS +.B fmt +[ +.I option ... +] +[ +.I file ... +] +.PP +.B htmlfmt +[ +.B -a +] [ +.B -c +.I charset +] [ +.B -u +.I url +] [ +.I file ... +] +.SH DESCRIPTION +.I Fmt +copies the given +.I files +(standard input by default) +to its standard output, filling and indenting lines. +The options are +.TP +.BI -l " n +Output line length is +.IR n , +including indent (default 70). +.TP +.BI -w " n +A synonym for +.BR -l . +.TP +.BI -i " n +Indent +.I n +spaces (default 0). +.TP +.BI -j +Do not join short lines: only fold long lines. +.PP +Empty lines and initial white space in input lines are preserved. +Empty lines are inserted between input files. +.PP +.I Fmt +is idempotent: it leaves already formatted text unchanged. +.PP +.I Htmlfmt +performs a similar service, but accepts as input text formatted with +HTML tags. +It accepts +.IR fmt 's +.B -l +and +.B -w +flags and also: +.TP +.BI -a +Normally +.I htmlfmt +suppresses the contents of form fields and anchors (URLs and image files); this flag +causes it to print them, in square brackets. +.TP +.BI -c " charset +change the default character set from iso-8859-1 to +.IR charset . +This is the character set assumed if there isn't one +specified by the html itself in a directive. +.TP +.BI -u " url +Use +.I url +as the base URL for the document when displaying anchors; sets +.BI -a . +.SH SOURCE +.B /sys/src/cmd/fmt.c +.PP +.B /sys/src/cmd/htmlfmt +.SH BUGS +.I Htmlfmt +makes no attempt to render the two-dimensional geometry of tables; +it just treats the table entries as plain, to-be-formatted text. diff --git a/sys/man/1/fortune b/sys/man/1/fortune new file mode 100755 index 000000000..dfae7186a --- /dev/null +++ b/sys/man/1/fortune @@ -0,0 +1,23 @@ +.TH FORTUNE 1 +.SH NAME +fortune \- sample lines from a file +.SH SYNOPSIS +.B fortune +[ +.I file +] +.SH DESCRIPTION +.I Fortune +prints a one-line aphorism chosen at random. +If a +.I file +is specified, the saying is taken from that file; +otherwise it is selected from +.BR /sys/games/lib/fortunes . +.SH FILES +.B /sys/games/lib/fortunes +.br +.B /sys/games/lib/fortunes.index +\ \ fast lookup table, maintained automatically +.SH SOURCE +.B /sys/src/cmd/fortune.c diff --git a/sys/man/1/freq b/sys/man/1/freq new file mode 100755 index 000000000..e6b5086f6 --- /dev/null +++ b/sys/man/1/freq @@ -0,0 +1,40 @@ +.TH FREQ 1 +.SH NAME +freq \- print histogram of character frequencies +.SH SYNOPSIS +.B freq +[ +.B -cdorx +] +[ +.I file ... +] +.SH DESCRIPTION +.I Freq +reads the given files (default standard input) +and prints histograms of the character frequencies. +By default, +.I freq +counts each byte as a character; +under the +.B -r +option it instead counts +.SM UTF +sequences, that is, runes. +.PP +Each non-zero entry of the table is printed preceded by the byte value, +in decimal, octal, hex, and +Unicode +character (if printable). +If any options are given, the +.BR -d , +.BR -x , +.BR -o , +.B -c +flags specify a subset of value formats: decimal, hex, octal, and +character, respectively. +.SH SOURCE +.B /sys/src/cmd/freq.c +.SH SEE ALSO +.IR utf (6), +.IR wc (1) diff --git a/sys/man/1/games b/sys/man/1/games new file mode 100755 index 000000000..c5a23cb30 --- /dev/null +++ b/sys/man/1/games @@ -0,0 +1,312 @@ +.TH GAMES 1 +.SH NAME +4s, 5s, festoon, juggle, life, mahjongg, memo, sokoban, sudoku \- time wasters +.SH SYNOPSIS +.B games/4s +.br +.B games/5s +.br +.B games/festoon +[ +.B -pet +] [ +.I sentences +[ +.I percent-invented-nouns +] ] +.br +.B games/juggle +[ +.B -d +.I delay +] [ +.B -h +.I hands +] [ +.I start +] +.I pattern +.br +.B games/life +.I startfile +.br +.B games/mahjongg +[ +.B -c +] [ +.B -f +] [ +.B -b +.I background +] [ +.B -t +.I tileset +] [ +.B -l +.I layout +] +.br +.B games/memo +[ +.B -h +] +.br +.B games/sokoban +[ +.I level +] +.br +.B games/sudoku +.SH DESCRIPTION +There are a few games in +.BR /bin/games : +.TF mahjongg +.PD +.TP +.BR 4s , " 5s" +Try to fill complete rows using 4-square or 5-square tiles. +Move tiles left or right by moving the mouse. +Rotate tiles with buttons 1 and 3. +Drop tiles for more points with button 2 or the space bar. +Keys +.LR a +and +.LR j +move left, +.LR s +and +.LR k +rotate left, +.LR d +and +.LR l +rotate right, +.LR f +and +.LR ; +move right. +.LR z , +.LR p +and +.LR Esc +toggle suspend/resume. +.LR q , +.LR Del +and +.LR control-D +quit. +.TP +.B festoon +Generate an official-looking but utterly nonsensical bureaucratic report as +.L "pic | eqn | tbl | troff -mm" +input. +Options +.BR -p , +.B -e +and +.B -t +add gibberish diagrams, equations and tables. +.TP +.B juggle +Display the juggling +.I pattern +using the optional initial +.I start +pattern. +The number of hands involved (default 2) can be specified with +.BR -h , +and +.I delay +can be used to speed up or slow down the action (default is 20). +Try the pattern 333333441333333 or 333353505151512333333 +or YWUSQOMKIGECA +(see +.BR http://seehuhn.de/jong/theory.html ). +.TP +.B life +Play the game of Life, given an initial position. +There is a library of interesting initial positions; +the library is consulted if +.I startfile +cannot be found. +.TP +.B mahjongg +Remove all tiles +from the board. Click on tiles with the same face that +are not blocked by others. A blocked tile is one that is partially or +fully covered on top or has neighbouring tiles to the left and right. +The game finishes when either all tiles are gone or there are no +more moves left. The arguments are for changing background +.RB (-b), +tile +.RB (-t) +and layout +.RB (-l) +images; +.RB -c +selects a true-color buffer image, for use with +drawterm or in case selecting a tile obscures it completely; +.RB -f +causes mahjongg to indicate non-blocked tiles on mouse-over. +The +.LR N +key will generate a new level, +.LR R +restarts the current one. +.LR Q +and +.LR Del +quit, +.LR H +gives a hint, either trying to match the currently selected tile, or if no tile is +selected finding out the first available tile. +.LR U +and +.LR Bksp +undo the last move, +.LR C +tries to solve the level. +.TP +.B memo +Remove all tiles from the board. +At first, pictures of various Bell Labs employees, Lucent Technologies' logo, and Glenda will appear. +Memorize the sequence, then click to hide them and begin. +Use the mouse to select two tiles. +If they are the same, the tiles will disappear, otherwise the tiles will flip back and you will get a chance to try again. +Button 3 generates a memu allowing you to restart, switch between easy and hard modes, and exit. +The +.B -h +option sets the game to hard mode. +Once the game has been completed, a message pops up with how long it took to win. +Use the button 3 menu to choose a mode, or click to play again. +.TP +.B sokoban +Guide Glenda through a room full of walls, pebbles and holes to put +the pebbles in. Your goal is to arrange all pebbles into holes by +pushing them around, but you can only push a pebble if there is no +wall or another pebble blocking the way. +Arrow keys move Glenda up-down-left-right. +.LR N +and +.LR P +keys switch between +the next and previous levels, +.LR R +restarts the current level. +.LR Del +and +.LR Q +quit. Button 3 invokes a menu to restart the current level, load different level sets, and en- and disable animation of multi-step moves. +Button 2 lets you change between levels. +Button 1 lets you do multi-step moves and pushes, +by clicking it on the destination where you want Glenda to go. +Glenda will only move if it can reach the destination. +For a multi-step push the pebble must be next to Glenda, +the destination must be on the same row or column, +and there must be a free place next to the destination +where the pebble can be pushed to. +Otherwise, if possible, Glenda will walk to the destination without pushing the pebble. +.I Sokoban +accepts a level file as its argument. +.TP +.B sudoku +.I Sudoku +is a puzzle game from Japan. The goal of the game is to +fill the numbers 1 to 9 in all squares of the 9x9 board following a +few simple rules: no digit should repeat on the same row and column, +and no digit should repeat in the same 3x3 boxes outlined with thicker +lines. The board is initially filled with a partial solution which +can be used for inferring digits for the empty squares. The top row +of the board contains the digits 1 through 9, clicking on one of those +digits selects that number for placement on the board, clicking it +again will deselect that digit. Clicking on an empty square will then +affix the square with the selected digit or, if no digit is selected +empty the square. +.IP +Button 3 presents a menu with the following options: +.RS \w'\fLfireworksXX'u +.TP \w'\fLOffsetXX'u +.B New +autogenerate a new, random board +.TP +.B Check +mark in red any digits not placed according to the rules +.TP +.B Solve +present the board's solution +.TP +.B Clear +clear the board to its starting (or last loaded) state +.TP +.B Save +save the current board to +.B /tmp/sudoku-save +.TP +.B Load +load the last saved board from +.B /tmp/sudoku-save +.TP +.B Print +print the current board and solution in a format +suitable for addition in the +.I sudoku +library to +.B /tmp/sudoku-board +.TP +.B Offline +pretty-print the board for off-line solving to +.B /tmp/sudoku-print +.TP +.B Exit +quit the game +.RE +.IP +Button 2 presents a list of +.I sudoku +boards of varying degrees of difficulty from +.BR /sys/games/lib/sudoku/boards . +.IP +Pressing the +.B Q +key quits +.IR sudoku . +.SH FILES +.TF /sys/games/lib/mahjongg/* +.TP +.B /sys/games/lib/[45]scores +score files of +.I 4s +and +.I 5s +.TP +.B /sys/games/lib/life/* +interesting starting positions +.TP +.B /sys/games/lib/mahjongg/* +image sprites, levels and backgrounds used by +.I mahjongg +.TP +.B /lib/face/* +tiles for +.I memo +.TP +.B /sys/games/lib/sokoban/* +image sprites and levels used by +.I sokoban +.TP +.B /sys/games/lib/sudoku/* +images and boards used by +.I sudoku +.SH SOURCE +.B /sys/src/games +.SH BUGS +In +.I 4s +and +.IR 5s , +mouse warping (when the game is resumed, +and when a new tile appears) does not happen when +the mouse cursor is outside the game window. +Those who prefer to use the keyboard without the mouse +cursor blocking the view (or being warped all the time) +may consider this a feature. diff --git a/sys/man/1/grap b/sys/man/1/grap new file mode 100755 index 000000000..b098f8220 --- /dev/null +++ b/sys/man/1/grap @@ -0,0 +1,416 @@ +.TH GRAP 1 +.SH NAME +grap \- pic preprocessor for drawing graphs +.SH SYNOPSIS +.B grap +[ +.I file ... +] +.SH DESCRIPTION +.I Grap +is a +.IR pic (1) +preprocessor for drawing graphs on a typesetter. +Graphs are surrounded by the +.I troff +`commands' +.B \&.G1 +and +.BR \&.G2 . +Data are scaled and plotted, +with tick marks supplied automatically. +Commands exist to modify the frame, +add labels, override the default ticks, +change the plotting style, +define coordinate ranges and transformations, +and include data from files. +In addition, +.I grap +provides the same loops, conditionals, and macro processing that +.I pic +does. +.PP +.BI frame +.B ht +.I e +.B wid +.I e +.B top +.B dotted +.IR ... : +Set the frame around the graph to specified +.B ht +and +.BR wid ; +default is 2 by 3 (inches). +The line +.I styles +.RB ( dotted , +.BR dashed , +.BR invis , +.BR solid +(default)) +of the +.I sides +.RB ( top , +.BR bot , +.BR left , +.BR right ) +of the frame can be set +independently. +.PP +.B label +.I side +.B \&"a label" +.B \&"as a set of strings" +.IR adjust : +Place label on specified side; default side is bottom. +.I adjust +is +.B up +(or +.B down +.B left +.BR right ) +.I expr +to shift default position; +.B width +.I expr +sets the width explicitly. +.PP +.BI ticks +.I side +.B in +.B at +.IR "optname expr, expr, ..." : +Put ticks on +.I side +at +.I "expr, ..., +and label with +.I \&"expr"\f1. +If any +.I expr +is followed by "...", label tick with "...", +and turn off all automatic labels. +If "..." contains +.BR %f 's, +they will be interpreted as +.B printf +formatting instructions for the tick value. +Ticks point +.B in +or +.B out +(default out). +Tick iterator: instead of +.B at +.IR \&... , +use +.BI from +.I expr +.B to +.I expr +.B by +.I "op expr +where +.I op +is optionally +.B +-*/ +for additive or multiplicative steps. +.B by +can be omitted, to give steps of size 1. +If no ticks are requested, they are supplied automatically; +suppress this with +.B ticks +.BR off . +Automatic ticks normally +leave a margin of 7% on each side; set this to anything by +.B margin +.B = +.IR expr . +.PP +.B grid +.I "side linedesc" +.B at +.IR "optname expr, expr, ..." : +Draw grids perpendicular to +.I side +in style +.I linedesc +at +.I "expr, ....\& +Iterators and labels work as with ticks. +.PP +.B coord +.I optname +.B x +.I "min, max" +.B y +.I "min, max" +.B "log x +.BR " log y" : +Set range of coords and optional log scaling on either or both. +This overrides computation of data range. +Default value of +.I optname +is current coordinate system +(each +.B coord +defines a new coordinate system). +.PP +.B plot +.I \&"str" +.B at +.IR point ; +.B +.I \&"str" +.B at +.IR point : +Put +.I str +at +.IR point . +Text position can be qualified with +.BR rjust , +.BR ljust , +.BR above , +.BR below +after "...". +.PP +.B line +.B from +.I point +.B to +.IR "point linedesc" : +Draw line from here to there. +.B arrow +works in place of +.BR line . +.PP +.B next +.I optname +.B at +.IR "point linedesc" : +Continue plot of data in +.I optname to +.IR point ; +default is current. +.PP +.BI draw +.IR "optname linedesc ..." : +Set mode for +.BR next : +use this style from now on, +and plot "..." at each point (if given). +.PP +.BI new +.IR "optname linedesc ..." : +Set mode for +.BR next , +but disconnect from previous. +.PP +A list of numbers +.I "x y1 y2 y3 ... +is treated as +.B plot +.B bullet +.B at +.IR x,y1 ; +.B plot +.B bullet +.B at +.IR x,y2 ; +etc., or as +.B next +.B at +.I x,y1 +etc., if +.B draw +is specified. +Abscissae of 1,2,3,... are provided if there is only one input number per line. +.PP +A +point +.I "optname expr, expr +maps the point to the named coordinate system. +A +.I linedesc +is one of +.B dot +.B dash +.B invis +.B solid +optionally followed by an expression. +.PP +.BI define +.I name +.BI { whatever } \f1: +Define a macro. +There are macros already defined for standard plotting +symbols like +.BR bullet , +.BR circle , +.BR star , +.BR plus , +etc., in +.BR /sys/lib/grap.defines , +which is included if it exists. +.PP +.I var +.B = +.IR expr : +Evaluate an expression. +Operators are +.B= +.B + +.B - +.B * +and +.BR / . +Functions are +.B log +and +.B exp +(both base 10), +.BR sin , +.BR cos , +.BR sqrt ; +.B rand +returns random number on [0,1); +.BI max( e , e )\f1, +.BI min( e , e )\f1, +.BI int( e )\f1. +.PP +.B print +.IR expr ; +.B print +\fL"\f2...\fL"\f1: +As a debugging aid, print +.I expr +or +.I string +on the standard error. +.PP +.B copy +\fL"\fIfile name\fL"\fR: +Include this file right here. +.PP +.B copy +.B thru +.IR macro : +Pass rest of input (until +.BR \&.G2 ) +through +.IR macro , +treating each field (non-blank, or "...") as an argument. +.I macro +can be the name of a macro previously defined, +or the body of one in place, like +.BR "/plot $1 at $2,$3/" . +.PP +.B copy +.B thru +.I macro +.B until +\fL"\fIstring\fL"\fR: +Stop copy when input is +.I string +(left-justified). +.PP +.BI pic +.IR "remainder of line" : +Copy to output with leading blanks removed. +.PP +.BI graph +.IR "Name pic-position" : +Start a new frame, place it at specified position, +e.g., +.B graph +.B Thing2 +.BR "with .sw at Thing1.se + (0.1,0)" . +.I Name +must be capitalized to keep +.I pic +happy. +.PP +.BI \&. "anything at beginning of +.IR line : +Copied verbatim. +.PP +.B sh +.BI % anything +.BR % : +Pass everything between the +.BR % 's +to the shell; +as with macros, +.B % +may be any character and +.I anything +may include newlines. +.PP +.B # +.IR anything : +A comment, which is discarded. +.PP +Order is mostly irrelevant; no category is mandatory. +Any arguments on the +.B \&.G1 +line are placed on the generated +.B \&.PS +line for +.IR pic . +.SH EXAMPLES +.EX +.ps -1 +.vs -1 +\&.G1 +frame ht 1 top invis right invis +coord x 0, 10 y 1, 3 log y +ticks left in at 1 "bottommost tick", 2,3 "top tick" +ticks bot in from 0 to 10 by 2 +label bot "silly graph" +label left "left side label" "here" +grid left dashed at 2.5 +copy thru / circle at $1,$2 / +1 1 +2 1.5 +3 2 +4 1.5 +10 3 +\&.G2 +.G1 +frame ht 1 top invis right invis +coord x 0, 10 y 1, 3 log y +ticks left in at 1 "bottommost tick", 2,3 "top tick" +ticks bot in from 0 to 10 by 2 +label bot "silly graph" +label left "left side label" "here" +grid left dashed at 2.5 +copy thru / circle at $1,$2 / +1 1 +2 1.5 +3 2 +4 1.5 +10 3 +.G2 +.ps +.vs +.EE +.SH FILES +.TF /sys/lib/grap.defines +.TP +.B /sys/lib/grap.defines +definitions of standard plotting characters, e.g., bullet +.SH SOURCE +.B /sys/src/cmd/grap +.SH "SEE ALSO" +.IR pic (1), +.IR troff (1) +.br +J. L. Bentley and B. W. Kernighan, +``GRAP\(emA Language for Typesetting Graphs'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. diff --git a/sys/man/1/graph b/sys/man/1/graph new file mode 100755 index 000000000..c2c24366c --- /dev/null +++ b/sys/man/1/graph @@ -0,0 +1,155 @@ +.TH GRAPH 1 +.CT 1 numbers graphics +.SH NAME +graph \- draw a graph +.SH SYNOPSIS +.B graph +[ +.I option ... +] +.SH DESCRIPTION +.I Graph +with no options takes pairs of numbers from the +standard input as abscissas +.RI ( x -values) +and ordinates +.RI ( y -values) +of a graph. +Successive points are connected by straight lines. +The graph is encoded on the standard output +for display by +.IR plot (1) +filters. +.PP +If an ordinate is followed by +a nonnumeric string, that string is printed as a +label beginning on the point. +Labels may be surrounded with quotes +.L +" " +in which case they may be empty or contain blanks +and numbers; +labels never contain newlines. +.PP +The following options are recognized, +each as a separate argument. +.TP +.B -a +Supply abscissas automatically; no +.IR x -values +appear in the input. +Spacing is given by the next +argument (default 1). +A second optional argument is the starting point for +automatic abscissas (default 0, or 1 +with a log scale in +.IR x , +or the lower limit given by +.BR -x ). +.TP +.B -b +Break (disconnect) the graph after each label in the input. +.TP +.B -c +Character string given by next argument +is default label for each point. +.TP +.B -g +Next argument is grid style, +0 no grid, 1 frame with ticks, 2 full grid (default). +.TP +.B -l +Next argument is a legend to title the graph. +Grid ranges +are automatically printed as part +of the title unless a +.B -s +option is present. +.TP +.B -m +Next argument is mode (style) +of connecting lines: +0 disconnected, 1 connected. +Some devices give distinguishable line styles +for other small integers. +Mode \-1 (default) begins with style 1 and +rotates styles for successive curves under option +.BR -o . +.TP +.B -o +(Overlay.) +The ordinates for +.I n +superposed curves appear in the input +with each abscissa value. +The next argument is +.IR n . +.TP +.B -p +Next argument is one or more of the characters +.B bcgkmrwy, +choosing pen colors by their initial letter, as in +.IR plot (6). +Successive curves will cycle through the colors in the given order. +.TP +.B -s +Save screen; no new page for this graph. +.TP +.B -x l +If +.B l +is present, +.IR x -axis +is logarithmic. +Next 1 (or 2) arguments are lower (and upper) +.I x +limits. +Third argument, if present, is grid spacing on +.I x +axis. +Normally these quantities are determined automatically. +.TP +.B -y l +Similarly for +.IR y . +.TP +.B -e +Make automatically determined +.I x +and +.I y +scales equal. +.TP +.B -h +Next argument is fraction of space for height. +.TP +.B -w +Similarly for width. +.TP +.B -r +Next argument is fraction of space to move right before plotting. +.TP +.B -u +Similarly to move up before plotting. +.TP +.B -t +Transpose horizontal and vertical axes. +(Option +.B -a +now applies to the vertical axis.) +.PP +If a specified lower limit exceeds the upper limit, +the axis +is reversed. +.SH SOURCE +.B /sys/src/cmd/graph +.SH "SEE ALSO" +.IR plot (1), +.IR grap (1) +.SH BUGS +Segments that run out of bounds are dropped, not windowed. +Logarithmic axes may not be reversed. +Option +.B -e +actually makes automatic limits, rather than automatic scaling, +equal. diff --git a/sys/man/1/grep b/sys/man/1/grep new file mode 100755 index 000000000..8bf2455ee --- /dev/null +++ b/sys/man/1/grep @@ -0,0 +1,109 @@ +.TH GREP 1 +.SH NAME +grep \- search a file for a pattern +.SH SYNOPSIS +.B grep +[ +.B -bchiLlnsv +] +[ +.B -e +] +.I pattern +| +.B -f +.I patternfile +[ +.I file ... +] +.SH DESCRIPTION +.I Grep\^ +searches the input +.I files\^ +(standard input default) +for lines that match the +.IR pattern , +a regular expression as defined in +.IR regexp (6) +with the addition of a newline character as an alternative +(substitute for +.BR | ) +with lowest precedence. +Normally, each line matching the pattern is `selected', +and each selected line is copied to the standard output. +The options are +.TP +.B -c +Print only a count of matching lines. +.PD 0 +.TP +.B -h +Do not print file name tags (headers) with output lines. +.TP +.B -e +The following argument is taken as a +.IR pattern . +This option makes it easy to specify patterns that +might confuse argument parsing, such as +.BR -n . +.TP +.B -i +Ignore alphabetic case distinctions. The implementation +folds into lower case all letters in the pattern and input before +interpretation. Matched lines are printed in their original form. +.TP +.B -l +(ell) Print the names of files with selected lines; don't print the lines. +.TP +.B -L +Print the names of files with no selected lines; +the converse of +.BR -l . +.TP +.B -n +Mark each printed line with its line number counted in its file. +.TP +.B -s +Produce no output, but return status. +.TP +.B -v +Reverse: print lines that do not match the pattern. +.TP +.B -f +The pattern argument is the name of a file containing regular +expressions one per line. +.TP +.B -b +Don't buffer the output: write each output line as soon as it is discovered. +.PD +.PP +Output lines are tagged by file name when there is more than one +input file. +(To force this tagging, include +.B /dev/null +as a file name argument.) +.PP +Care should be taken when +using the shell metacharacters +.B $*[^|()=\e +and newline +in +.IR pattern ; +it is safest to enclose the +entire expression +in single quotes +.BR \&\|' \|.\|.\|.\| ' . +An expression starting with '*' +will treat the rest of the expression +as literal characters. +.SH SOURCE +.B /sys/src/cmd/grep +.SH SEE ALSO +.IR ed (1), +.IR awk (1), +.IR sed (1), +.IR sam (1), +.IR regexp (6) +.SH DIAGNOSTICS +Exit status is null if any lines are selected, +or non-null when no lines are selected or an error occurs. diff --git a/sys/man/1/gs b/sys/man/1/gs new file mode 100755 index 000000000..a65e3e236 --- /dev/null +++ b/sys/man/1/gs @@ -0,0 +1,280 @@ +.TH GS 1 +.\" This file is an edited version of /sys/src/cmd/gs/man/gs.1, to +.\" document the local installation and remove needless background. +.de TQ +.br +.ns +.TP \\$1 +.. +.SH NAME +gs \- Aladdin Ghostscript (PostScript and PDF language interpreter) +.SH SYNOPSIS +.B gs +[ +.I options +] [ +.I files +] ... +.br +.SH DESCRIPTION +Ghostscript is a programming language similar to Adobe Systems' +PostScript and PDF languages, which are in turn similar to Forth. +.I Gs +reads +.I files +in sequence and executes them as Ghostscript programs. +After doing this, it reads further input from the standard input. +If the +.I file +.B - +is named, however, it represents the standard input, which is read +in order and not after the files on the command line. +Each line is interpreted separately. +The `quit' command, or end-of-file, exits the interpreter. +.PP +The interpreter recognizes several switches described below, which may appear +anywhere in the command line and apply to all files thereafter. +.PP +The +.B -h +or +.B -? +options give help and list the available devices; the default is +.BR plan9 , +which produces compressed image files suitable for viewing with +.IR page (1) +(but note that +.IR page (1) +will invoke +.I gs +automatically; see its manual). +.PP +Ghostscript may be built with multiple output devices. Ghostscript +normally opens the first one and directs output to it. To use device xyz +as the initial output device, include the switch +.EX + -sDEVICE=xyz +.EE +in the command line. This switch must precede the first PostScript +file and only its first invocation has any effect. +Output devices can also be selected by the word +.B selectdevice +in the input language, or by setting the environment variable +.BR GS_DEVICE . +The order of precedence for +these alternatives, highest to lowest, is: +.EX + selectdevice + \f1(command line)\fP + GS_DEVICE + plan9 +.EE +.PP +Normally, output goes +directly to a scratch file. +To send the output to a series of files +.BR foo1.xyz , +.BR foo2.xyz , +etc., use the switch +.EX + -sOutputFile=foo%d.xyz +.EE +The %d may be any +.I printf +(see +.IR fprintf (2)) +format specification. Each file will receive one page of output. +If the file name begins with a pipe character, +the output will be sent as standard input to the following pipeline. +For example, +.EX + -sOutputFile=|lp +.EE +Specifying the file +.B - +will send the files to standard output; this also requires enabling the +.B -q +option. +.SS "Initialization files" +When looking for the initialization files +.RB ( gs_*.ps ), +the files related +to fonts, or the file for the +.B run +operator, Ghostscript first looks for the file (if +it doesn't start with a slash) in the current directory, then in these +directories in the following order: +.TP +1. +Any directories specified by +.B -I +switches in the command +line (see below); +.TP +2. +Any directories specified by the +.B GS_LIB +environment variable; +.TP +3. +The directories +.BR /sys/lib/ghostscript , +.BR /sys/lib/ghostscript/font , +and +.BR /sys/lib/postscript/font . +.PP +The +.B GS_LIB +or +.B -I +parameters may be +a single directory or a colon-separated list. +.SS Options +.TP +.BI -- " filename arg1 ..." +Take the next argument as a file name as usual, but take all +remaining arguments (even if they have the syntactic form of switches) +and define the name ARGUMENTS in userdict (not systemdict) as an +array of those strings, +.I before +running the file. When Ghostscript +finishes executing the file, it exits back to the shell. +.TP +.BI -D name = token +.TQ +.BI -d name = token +Define a name in systemdict with the given definition. The token must +be exactly one token (as defined by the `token' operator) and must not +contain any white space. +.TP +.BI -D name +.TQ +.BI -d name +Define a name in systemdict with value=null. +.TP +.BI -S name = string +.TQ +.BI -s name = string +Define a name in systemdict with a given string as value. This is +different from +.BR -d . +For example, +.B -dname=35 +is equivalent to the +program fragment +.EX + /name 35 def +.EE +whereas +.B -sname=35 +is equivalent to +.EX + /name (35) def +.EE +.TP +.B -q +Quiet startup: suppress normal startup messages, and also do the +equivalent of +.BR -dQUIET . +.TP +.BI -g number1 x number2 +Equivalent to +.BI -dDEVICEWIDTH= number1 +and +.BI -dDEVICEHEIGHT= number2\f1. +This is for the benefit of devices, such as windows, +that allow width and height to be specified. +.TP +.BI -r number +.TQ +.BI -r number1 x number2 +Equivalent to +.BI -dDEVICEXRESOLUTION= number1 +and +\fL-dDEVICE\%YRESOLUTION= \f2\%number2\f1. +This is for the benefit of devices, such as printers, +that support multiple X and Y resolutions. +If only one number is given, it is used for both X and Y resolutions. +.TP +.BI -I directories +Adds the designated list of directories at the head of the +search path for library files. +.PP +Note that gs_init.ps makes systemdict read-only, so the values of names +defined with -D/d/S/s cannot be changed (although, of course, they can be +superseded by definitions in userdict or other dictionaries.) +.SS "Special names" +.TP +.B -dBATCH +Exit after the last file has been processed. +This is equivalent to listing +.I quit.ps +at the end of the list of files. +.TP +.B -dDISKFONTS +Causes individual character outlines to be loaded from the disk +the first time they are encountered. (Normally Ghostscript loads all the +character outlines when it loads a font.) This may allow loading more +fonts into RAM, at the expense of slower rendering. +.TP +.B -dNOCACHE +Disables character caching. Only useful for debugging. +.TP +.B -dNOBIND +Disables the `bind' operator. Only useful for debugging. +.TP +.B -dNODISPLAY +Suppresses the normal initialization of the output device. +This may be useful when debugging. +.TP +.B -dNOPAUSE +Disables the prompt and pause at the end of each page. +This may be desirable for applications where another program +(e.g. +.IR page (1)) +is +`driving' Ghostscript. +.TP +.B -dSAFER +Disables the +.B deletefile +and +.B renamefile +operators, and the +ability to open files in any mode other than read-only. This may be +desirable for spoolers or other sensitive environments. +Files in the +.B /fd +directory may still be opened for writing. +.TP +.B -dWRITESYSTEMDICT +Leaves systemdict writable. This is necessary when running +special utility programs such as font2c and pcharstr, which must bypass +normal PostScript access protection. +.TP +.BI -sDEVICE= device +Selects an alternate initial output device, as described above. +.TP +.BI -sOutputFile= filename +Selects an alternate output file (or pipe) for the initial output +device, as described above. +.SH FILES +.TP +.B /sys/lib/ghostscript/* +Startup-files, utilities, examples, and basic font definitions. +.TP +.B /sys/lib/ghostscript/fonts/* +Additional font definitions. +.SH SOURCE +.B /sys/src/cmd/gs +.SH "SEE ALSO" +.IR page (1), +.IR ps2pdf (1) +.br +The Ghostscript document files in +.B doc +and +.B man +subdirectories of the source directory. +.SH BUGS +The treatment of standard input is non-standard. diff --git a/sys/man/1/gview b/sys/man/1/gview new file mode 100755 index 000000000..1777a3f7d --- /dev/null +++ b/sys/man/1/gview @@ -0,0 +1,204 @@ +.TH GVIEW 1 +.SH NAME +gview \- interactive graph viewer +.SH SYNOPSIS +.B gview +[ +.B -mp +] +[ +.B -l +.I logfile +] +[ +.I files +] +.SH DESCRIPTION +.I Gview +reads polygonal lines or a polygonal line drawing from an +.B ASCII +input file (which defaults to standard input), and views it interactively, +with commands to zoom in and out, perform simple editing operations, and +display information about points and polylines. (Multiple input files are +allowed if you want to overlay several line drawings.) The editing commands can +change the color and thickness of the polylines, delete (or undelete) +some of them, and optionally rotate and move them. It is also possible to +generate an output file that reflects these changes and is in the same format +as the input. +.PP +Since the +.B move +and +.B rotate +commands are undesirable when just viewing a graph, they are only enabled if +.I gview +is invoked with the +.B -m +option. +.PP +The +.B -p +option plots only the vertices of the polygons. +.PP +Clicking on a polyline with button 1 displays the coordinates and a +.I t +value that tells how far along the polyline. +.IR (t =0 +at the first vertex, +.IR t =1 +at the first vertex, +.IR t =1.5 +halfway between the second and third vertices, etc.) The +.B -l +option generates a log file that lists all points selected in this manner. +.PP +The most important interactive operations are to +.I zoom in +by sweeping out a rectangle, or to +.I zoom out +so that everything currently being displayed shrinks to fit in the swept-out +rectangle. Other options on the button 3 menu are +.I unzoom +which restores the coordinate system to the default state where everything +fits on the screen, +.I recenter +which takes a point and makes it the center of the window, and +.I square up +which makes the horizontal and vertical scale factors equal. +.PP +To take a graph of a function where some part is almost linear and +see how it deviates from a straight line, select two points on this +part of the graph (i.e., select one with button 1 and then select the +other) and then use the +.I slant +command on the button 3 menu. +This slants the coordinate system so that the line between the two +selected points appears horizontal (but vertical still means positive +.IR y ). +Then the +.I zoom in +command can be used to accentuate deviations from horizontal. +There is also an +.I unslant +command that undoes all of this and goes back to an unslanted coordinate +system. +.PP +There is a +.I recolor +command on button 3 that lets you select a color and change everything +to have that color, and a similar command on button 2 that only affects +the selected polyline. If the input file uses the +.B Multi(...) +feature explained below, either flavor of +.I recolor +allows you to type a digit in lieu of selecting a color. +.PP +The +.I thick +or +.I thin +command on button 2 changes the thickness of the selected polyline +and there is also an undo command for such edits. +Finally, button 3 has commands to +.I read +a new input file and display it on top of everything else, +.I restack +the drawing order (in case lines of different color are drawn on top of +each other), +.I write +everything into an output file, or +.I exit +the program. +.PP +Each polyline in an input or output file is a space-delimited +.I x +.I y +coordinate pair on a line by itself, and the polyline is a sequence +of such vertices followed by a label. The label could be just a +blank line or it could be a string in double +quotes, or virtually any text that does not contain spaces and is +on a line by itself. The label at the end of the last polyline is +optional. It is not legal to have two consecutive labels, since that +would denote a zero-vertex polyline and each polyline must have at least +one vertex. (One-vertex polylines are useful for scatter plots.) +Under the +.B -l +option, a newline causes the selected polyline's label to appear in +the log file (where it could be seen by invoking +.B tail -f +in another window). + +If the label after a polyline contains the word +.B "Thick" +or a color name +.BR (Red , +.BR Pink , +.BR Dkred , +.BR Orange , +.BR Yellow , +.BR Dkyellow , +.BR Green , +.BR Dkgreen , +.BR Cyan , +.BR Blue , +.BR Ltblue , +.BR Magenta , +.BR Violet , +.BR Gray , +.BR Black , +.BR White ), +whichever color name comes first will be used to color the polyline. +Alternatively, labels can contain +.B Multi +followed by single-letter versions of these names: +.BR (R , +.BR P , +.BR r , +.BR O , +.BR Y , +.BR y , +.BR G , +.BR g , +.BR C , +.BR B , +.BR b , +.BR M , +.BR V , +.BR A , +.BR K , +.BR W , +each optionally preceded by +.BR T ). +Then +.I recolor +followed by a nonzero digit +.I n +selects the +.IR n th +alternative for each polyline. + +.SH EXAMPLE +To see a graph of the function +.IR y = sin( x )/ x , +generate input with an awk script and pipe it into +.IR gview : +.IP +.EX +awk 'BEGIN{for(x=.1;x<500;x+=.1)print x,sin(x)/x}' | gview +.EE +.SH SOURCE +.B /sys/src/cmd/gview.c +.SH SEE ALSO +.IR awk (1), +.IR tail (1) +.SH BUGS +The user interface for the +.I slant +command is counter-intuitive. Perhaps it would be better to have a scheme +for sweeping out a parallelogram. +.PP +The +.B -p +option makes the interactive point selection feature behave strangely, and +is unnecessary since extra blank lines in the input achieve essentially the +same effect. diff --git a/sys/man/1/gzip b/sys/man/1/gzip new file mode 100755 index 000000000..f56a6a246 --- /dev/null +++ b/sys/man/1/gzip @@ -0,0 +1,210 @@ +.TH GZIP 1 +.SH NAME +gzip, gunzip, bzip2, bunzip2, compress, uncompress, zip, unzip \- compress and expand data +.SH SYNOPSIS +.B gzip +.RB [ -cvD [ 1-9 ]] +.RI [ file +.BR ... ] +.PP +.B gunzip +.RB [ -ctTvD ] +.RI [ file +.BR ... ] +.PP +.B bzip2 +.RB [ -cvD [ 1-9 ]] +.RI [ file +.BR ... ] +.PP +.B bunzip2 +.RB [ -cvD ] +.RI [ file +.BR ... ] +.PP +.B compress +[ +.B -cv +] [ +.I file +.B ... +] +.PP +.B uncompress +[ +.B -cv +] [ +.I file +.B ... +] +.PP +.B zip +.RB [ -avD [ 1-9 ]] +.RB [ -f +.IR zipfile ] +.I file +.RB [ ... ] +.PP +.B unzip +.RB [ -cistTvD ] +.RB [ -f +.IR zipfile ] +.RI [ file +.BR ... ] +.SH DESCRIPTION +.PP +.I Gzip +encodes files with a hybrid Lempel-Ziv 1977 and Huffman compression algorithm +known as +.BR deflate . +Most of the time, the resulting file is smaller, +and will never be much bigger. +Output files are named by taking the last path element of each file argument +and appending +.BR .gz ; +if the resulting name ends with +.BR .tar.gz , +it is converted to +.B .tgz +instead. +.I Gunzip +reverses the process. +Its output files are named by taking the last path element of each file argument, +converting +.B .tgz +to +.BR .tar.gz , +and stripping any +.BR .gz ; +the resulting name must be different from the original name. +.PP +.I Bzip2 +and +.I bunzip2 +are similar in interface to +.I gzip +and +.IR gunzip , +but use a modified Burrows-Wheeler block sorting +compression algorithm. +The default suffix for output files is +.BR .bz2 , +with +.B .tar.bz2 +becoming +.BR .tbz . +.I Bunzip2 +recognizes the extension +.B .tbz2 +as a synonym for +.BR .tbz . +.PP +.I Compress +and +.I uncompress +are similar in interface to +.I gzip +and +.IR gunzip , +but use the Lempel-Ziv-Welch compression algorithm. +The default suffix for output files is +.BR .Z . +.I Compress +is one of the oldest widespread Unix compression programs. +.PP +.I Zip +encodes the named files and places the results into the archive +.IR zipfile , +or the standard output if no file is given. +.I Unzip +extracts files from an archive created by +.IR zip . +If no files are named as arguments, all of files in the archive are extracted. +A directory's name implies all recursively contained files and subdirectories. +.I Zip +is the +.I "de facto" +standard for compression on Microsoft operating systems. +.PP +None of these programs removes the original files. +If the process fails, the faulty output files are removed. +.PP +The options are: +.TP 0.6i +.B -a +Automaticialy creates directories as needed, needed for zip files +created by broken implementations which omit directories. +.TP +.B -c +Write to standard output rather than creating an output file. +.TP +.B -i +Convert all archive file names to lower case. +.TP +.B -s +Streaming mode. Looks at the file data adjacent to each compressed file +rather than seeking in the central file directory. +This is the mode used by +.I unzip +if no +.I zipfile +is specified. +If +.B -s +is given, +.B -T +is ignored. +.TP +.B -t +List matching files in the archive rather than extracting them. +.TP +.B -T +Set the output time to that specified in the archive. +.TP +.BR -1 " .. " -9 +Sets the compression level. +.B -1 +is tuned for speed, +.B -9 +for minimal output size. +The best compromise is +.BR -6 , +the default. +.TP +.B -v +Produce more descriptive output. +With +.BR -t , +adds the uncompressed size in bytes and the modification time to the output. +Without +.BR -t , +prints the names of files on standard error as they are compressed or decompressed. +.TP +.B -D +Produce debugging output. +.SH SOURCE +.B /sys/src/cmd/gzip +.br +.B /sys/src/cmd/bzip2 +.br +.B /sys/src/cmd/compress +.SH SEE ALSO +.IR tar (1) +.br +"A Technique for High Performance Data Compression", +Terry A. Welch, +.IR "IEEE Computer" , +vol. 17, no. 6 (June 1984), pp. 8-19. +.SH BUGS +.I Unzip +can only extract files which are uncompressed or compressed +with the +.B deflate +compression scheme. Recent zip files fall into this category. +Very recent zip files may have tables of contents that +.I unzip +cannot read. Such files are still readable by invoking +.I unzip +with the +.B -s +option. diff --git a/sys/man/1/hget b/sys/man/1/hget new file mode 100755 index 000000000..7cc8c97c5 --- /dev/null +++ b/sys/man/1/hget @@ -0,0 +1,86 @@ +.TH HGET 1 +.SH NAME +hget \- retrieve a web page corresponding to a url +.SH SYNOPSIS +.B hget +[ +.B -dhv +] [ +.B -o +.I ofile +] [ +.B -p +.I body +] [ +.B -x +.I netmntpt +] [ +.B -r +.I header +] +.I url +.SH DESCRIPTION +.I Hget +retrieves the web page specified by the URL +.I url +and writes it, absent the +.B -o +option, to standard output. +The known URL types are: http and ftp. +.PP +If +.I url +is of type HTTP and the +.B -p +option is specified, then an HTTP POST is performed +with +.I body +as the data to be posted. +.PP +The +.B -o +option is used to keep a local file in sync with a +web page. If the web page has been modified later than the +file, it is copied into the file. If the file is up to date +but incomplete, +.I hget +will fetch the missing bytes. +.PP +Option +.B -h +causes HTTP headers to be printed to standard output +in addition to the transferred web page. +.PP +Option +.B -r +sends an arbitrary HTTP +.IR header . +.PP +Option +.B -d +turns on debugging written to standard error. +.PP +Normally, +.I hget +uses the IP stack mounted under +.BR /net . +The +.B -x +option can be used to specify the mount point of +a different IP stack to use. +.PP +Option +.B -v +writes progress lines to standard error once a second. +Each line contains two numbers, the bytes transferred so +far and the total length to be transferred. +.PP +If the environment variable +.B httpproxy +is set, it is used as a URL denoting an HTTP proxy server. +All HTTP accesses use this server to get the page instead of +calling the destination server. +.SH SOURCE +.B /sys/src/cmd/hget.c +.SH "SEE ALSO" +.IR ftpfs (4) diff --git a/sys/man/1/history b/sys/man/1/history new file mode 100755 index 000000000..889da36a1 --- /dev/null +++ b/sys/man/1/history @@ -0,0 +1,102 @@ +.TH HISTORY 1 +.SH NAME +history \- print file names from the dump +.SH SYNOPSIS +.B history +[ +.B -Dabcemnw +] [ +.B -fuv +] [ +.B -d +.I dumpfilesystem +] [ +.B -s +.I yyyymmdd +] +.I files ... +.SH DESCRIPTION +.I History +prints the names, dates, and sizes, and modifier of all versions of the named +.IR files , +looking backwards in time, +stored in the dump file system. +If the file exists in the main tree, the first line of output will be its current state. +For example, +.IP +.EX +history /adm/users +.EE +.PP +produces +.IP +.EX +May 14 15:29:18 EDT 2001 /adm/users 10083 [adm] +May 14 15:29:18 EDT 2001 /n/dump/2001/0515/adm/users 10083 [adm] +May 11 17:26:24 EDT 2001 /n/dump/2001/0514/adm/users 10481 [adm] +May 10 16:40:51 EDT 2001 /n/dump/2001/0511/adm/users 10476 [adm] + ... +.EE +.PP +When presented with a path of the form +.BI /n/ fs / path \fR, +.I history +will use +.IB fs dump +as the name of the dump file system, and will print a history of +.IR path . +.PP +The +.B -v +option enables verbose debugging printout. +.PP +The +.B -D +option causes +.IR diff (1) +to be run for each adjacent pair of dump files. +The options +.B -abcemnw +are passed through to +.IR diff; +the little-used +.I diff option +.B -f +is replaced by the functionality described below, +and the +.B -r +option is disallowed. +.PP +The +.B -u +option causes times to be printed in GMT (UT) rather than local time. +.PP +The +.B -d +option selects some other dump file system such as +.IR /n/bootesdump . +.PP +The +.B -f +option forces the search to continue even when the +file in question does not exist (useful for files that only +exist intermittently). +.PP +Finally, the +.B -s +option +sets the starting (most recent) date for the output. +.SH EXAMPLES +Check how often a user has been logged in. +.IP +.EX +history /usr/ches/tmp +.EE +.SH FILES +.B /n/dump +.SH SOURCE +.B /sys/src/cmd/history.c +.SH SEE ALSO +.IR fs (4) +.br +.IR yesterday (1) diff --git a/sys/man/1/hoc b/sys/man/1/hoc new file mode 100755 index 000000000..0d939afc0 --- /dev/null +++ b/sys/man/1/hoc @@ -0,0 +1,144 @@ +.TH HOC 1 +.SH NAME +hoc \- interactive floating point language +.SH SYNOPSIS +.B hoc +[ +.B -e +.I expression +] +[ +.I file ... +] +.SH DESCRIPTION +.I Hoc +interprets a simple language for floating point arithmetic, +at about the level of BASIC, with C-like syntax and +functions. +.PP +The named +.I files +are read and interpreted in order. +If no +.I file +is given or if +.I file +is +.L - +.I hoc +interprets the standard input. +The +.B -e +option allows input to +.I hoc +to be specified on the command line, to be treated as if it appeared in a file. +.PP +.I Hoc +input consists of +.I expressions +and +.IR statements . +Expressions are evaluated and their results printed. +Statements, typically assignments and function or procedure +definitions, produce no output unless they explicitly call +.IR print . +.PP +Variable names have the usual syntax, including +.LR _ ; +the name +.L _ +by itself contains the value of the last expression evaluated. +The variables +.BR E , +.BR PI , +.BR PHI , +.BR GAMMA +and +.B DEG +are predefined; the last is 59.25..., degrees per radian. +.PP +Expressions are formed with these C-like operators, listed by +decreasing precedence. +.TP +.B ^ +exponentiation +.TP +.B ! - ++ -- +.TP +.B * / % +.TP +.B + - +.TP +.B > >= < <= == != +.TP +.B && +.TP +.B || +.TP +.B = += -= *= /= %= +.PP +Built in functions are +.BR abs , +.BR acos , +.BR asin , +.B atan +(one argument), +.BR cos , +.BR cosh , +.BR exp , +.BR int , +.BR log , +.BR log10 , +.BR sin , +.BR sinh , +.BR sqrt , +.BR tan , +and +.BR tanh . +The function +.B read(x) +reads a value into the variable +.B x +and returns 0 at EOF; +the statement +.B print +prints a list of expressions that may include +string constants such as +\fL"hello\en"\f1.\fP +.PP +Control flow statements are +.BR if - else , +.BR while , +and +.BR for , +with braces for grouping. +Newline ends a statement. +Backslash-newline is equivalent to a space. +.PP +Functions and procedures are introduced by the words +.B func +and +.BR proc ; +.B return +is used to return with a value from a function. +.SH EXAMPLES +.EX +func gcd(a, b) { + temp = abs(a) % abs(b) + if(temp == 0) return abs(b) + return gcd(b, temp) +} +for(i=1; i<12; i++) print gcd(i,12) +.EE +.SH SOURCE +.B /sys/src/cmd/hoc +.SH "SEE ALSO" +.IR bc (1), +.IR dc (1) +.br +B. W. Kernighan and R. Pike, +.I +The Unix Programming Environment, +Prentice-Hall, 1984 +.SH BUGS +Error recovery is imperfect within function and procedure definitions. diff --git a/sys/man/1/htmlroff b/sys/man/1/htmlroff new file mode 100755 index 000000000..470d1952d --- /dev/null +++ b/sys/man/1/htmlroff @@ -0,0 +1,119 @@ +.TH HTMLROFF 1 +.SH NAME +htmlroff \- HTML formatting and typesetting +.SH SYNOPSIS +.B htmlroff +[ +.B -iuv +] +[ +.B -m +.I name +] +[ +.B -r +.I aN +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Htmlroff +accepts +.IR troff (1) +input in the named +.I files +and formats it as HTML for viewing in a web browser. +.PP +If no +.I file +argument is given, +.I htmlroff +reads the standard input. +An argument consisting of a single minus +.RB ( - ) +is taken to be +a file name corresponding to the standard input. +The options are: +.TP +.B -i +Read standard input after the input files are exhausted. +.TP +.BI -m name +Process the macro file +.BI /sys/lib/tmac/tmac. name +before the input +.IR files . +.TP +.BI -r aN +Set register +.I a +(one character name) to +.IR N . +.TP +.B -u +Generate UTF output. +By default, +.I htmlroff +converts Unicode runes into the corresponding +HTML entity sequences +.RB ( α , +.BR   , +and so on). +.I Htmlroff +invokes +.IR tcs (1) +for the conversion. +.TP +.B -v +Generate debugging output and warnings about suspicious input. +.PD +.PP +Most +.I troff +input files, especially those using the +.IR ms (6) +macros, can be used unaltered. +In general, the macro file +.B tmac.html +should be processed after processing other standard macro files, +as in +.B htmlroff +.B -ms +.BR -mhtml . +.PP +.IR Htmlroff (6) +describes the changes to the input language. +.PP +.IR Mhtml (6) +describes the new macros. +.SH EXAMPLES +Format the Plan 9 web page: +.IP +.EX +cd /usr/web/plan9 +htmlroff -mhtml index.tr >index.html +.EE +.PP +Format a paper: +.IP +.EX +cd /sys/doc +pic auth.ms | tbl | eqn | htmlroff -ms -mhtml >auth.html +.EE +.SH FILES +.TP +.B /sys/lib/troff/font/devutf/utfmap +Mapping from +.I troff +two-character names like +.B \e(*a +to Unicode characters like α. +.SH SOURCE +.B /sys/src/cmd/htmlroff +.SH "SEE ALSO +.IR tcs (1), +.IR troff (1), +.IR htmlroff (6), +.IR mhtml (6) diff --git a/sys/man/1/idiff b/sys/man/1/idiff new file mode 100755 index 000000000..e16bada67 --- /dev/null +++ b/sys/man/1/idiff @@ -0,0 +1,73 @@ +.TH IDIFF 1 +.SH NAME +idiff \- interactive diff +.SH SYNOPSIS +.B idiff +[ +.B -bw +] +.I file1 +.I file2 +.SH DESCRIPTION +.I Idiff +interactively +merges +.I file1 +and +.I file2 +onto standard output. +Wherever +.I file1 +and +.I file2 +differ, +.I idiff +displays the differences in the style of +.RB `` diff +.BR -n '' +on standard error +and prompts the user to select a chunk. +Valid responses are: +.TP +.B < +Use the chunk from +.IR file1 . +.TP +.B > +Use the chunk from +.IR file2 . +.TP +.B = +Use the diff output itself. +.TP +.BR q< ", " q> ", " q= +Use the given response for all future questions. +.TP +.BI ! cmd +Execute +.I cmd +and prompt again. +.PP +.I Idiff +invokes +.IR diff (1) +to compare the files. +The +.B -b +and +.B -w +flags, +if passed, +are +passed to +.IR diff . +.SH FILES +.B /tmp/idiff.* +.SH SOURCE +.B /sys/src/cmd/idiff.c +.SH "SEE ALSO +.IR diff (1) +.br +Kernighan and Pike, +.IR "The Unix Programming Environment" , +Prentice-Hall, 1984. diff --git a/sys/man/1/join b/sys/man/1/join new file mode 100755 index 000000000..9c3368163 --- /dev/null +++ b/sys/man/1/join @@ -0,0 +1,147 @@ +.TH JOIN 1 +.CT 1 files +.SH NAME +join \- relational database operator +.SH SYNOPSIS +.B join +[ +.I options +] +.I file1 file2 +.SH DESCRIPTION +.I Join +forms, on the standard output, +a join +of the two relations specified by the lines of +.I file1 +and +.IR file2 . +If one of the file names is +.LR - , +the standard input is used. +.PP +.I File1 +and +.I file2 +must be sorted in increasing +.SM ASCII +collating +sequence on the fields +on which they are to be joined, +normally the first in each line. +.PP +There is one line in the output +for each pair of lines in +.I file1 +and +.I file2 +that have identical join fields. +The output line normally consists of the common field, +then the rest of the line from +.IR file1 , +then the rest of the line from +.IR file2 . +.PP +Input fields are normally separated spaces or tabs; +output fields by space. +In this case, multiple separators count as one, and +leading separators are discarded. +.PP +The following options are recognized, with POSIX syntax. +.TP +.BI -a " n +In addition to the normal output, +produce a line for each unpairable line in file +.IR n , +where +.I n +is 1 or 2. +.TP +.BI -v " n +Like +.BR -a , +omitting output for paired lines. +.TP +.BI -e " s +Replace empty output fields by string +.IR s . +.TP +.BI -1 " m +.br +.ns +.TP +.BI -2 " m +Join on the +.IR m th +field of +.I file1 +or +.IR file2 . +.TP +.BI -j "n m" +Archaic equivalent for +.BI - n " m"\f1. +.TP +.BI -o fields +Each output line comprises the designated fields. +The comma-separated field designators are either +.BR 0 , +meaning the join field, or have the form +.IR n . m , +where +.I n +is a file number and +.I m +is a field number. +Archaic usage allows separate arguments for field designators. +.PP +.TP +.BI -t c +Use character +.I c +as the only separator (tab character) on input and output. +Every appearance of +.I c +in a line is significant. +.SH EXAMPLES +.TP +.L +sort -t: +1 /adm/users | join -t: -1 2 -a 1 -e "" - bdays +Add birthdays to the +.B /adm/users +file, leaving unknown +birthdays empty. +The layout of +.B /adm/users +is given in +.IR users (6); +.B bdays +contains sorted lines like +.LR "ken:Feb\ 4,\ 1953" . +.TP +.L +tr : ' ' temp +.br +.ns +.TP +.L +join -1 3 -2 3 -o 1.1,2.1 temp temp | awk '$1 < $2' +Print all pairs of users with identical userids. +.SH SOURCE +.B /sys/src/cmd/join.c +.SH "SEE ALSO" +.IR sort (1), +.IR comm (1), +.IR awk (1) +.SH BUGS +With default field separation, +the collating sequence is that of +.BI "sort -b" +.BI -k y , y\f1; +with +.BR -t , +the sequence is that of +.BI "sort -t" x +.BI -k y , y\f1. +.PP +One of the files must be randomly accessible. diff --git a/sys/man/1/jpg b/sys/man/1/jpg new file mode 100755 index 000000000..f9b42adc5 --- /dev/null +++ b/sys/man/1/jpg @@ -0,0 +1,263 @@ +.TH JPG 1 +.SH NAME +jpg, gif, png, ppm, bmp, v210, yuv, ico, togif, toppm, topng, toico \- view and convert pictures +.SH SYNOPSIS +.B jpg +[ +.B -39cdefFkJrtv +] [ +.I file ... +] +.br +.B gif +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B png +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B ppm +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B bmp +[ +.I file +] +.br +.B v210 +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B yuv +[ +.I file +] +.PP +.B togif +[ +.B -c +.I comment +] [ +.B -l +.I loopcount +] [ +.B -d +.I msec +] [ +.B -t +.I transindex +] [ +.I file ... +[ +.B -d +.I msec +] +.I file ... +] +.br +.B toppm +[ +.B -c +.I comment +] [ +.I file +] +.br +.B topng +[ +.B -c +.I comment +] [ +[ +.B -g +.I gamma +] [ +.I file +] +.PP +.B ico +[ +.I file +] +.br +.B toico +[ +.I file ... +] +.SH DESCRIPTION +These programs read, display, and write image files in public formats. +.IR Jpg , +.IR gif , +.IR png , +.IR ppm , +.IR bmp , +.IR v210 , +and +.IR yuv +read files in the corresponding formats and, by default, display +them in the current window; options cause them instead to convert the images +to Plan 9 image format and write them to standard output. +.IR Togif , +.IR Toppm , +and +.I topng +read Plan 9 images files, convert them to GIF, PPM, or PNG, and write them to standard output. +.PP +The default behavior of +.IR jpg , +.IR gif , +and +.IR ppm +is to display the +.IR file , +or standard input if no file is named. +Once a file is displayed, typing a character causes the program to display the next image. +Typing a +.BR q , +DEL, or control-D exits the program. +For a more user-friendly interface, use +.IR page (1), +which invokes these programs to convert the images to standard format, +displays them, and offers scrolling, panning, and menu-driven navigation among the files. +.PP +These programs share many options: +.TP +.B -e +Disable Floyd-Steinberg error diffusion, which is used to improve the appearance +of images on color-mapped displays, typically with 8 bits per pixel. +Primarily useful for debugging; if the display has true RGB color, the image +will be displayed in full glory. +.TP +.B -k +Convert and display the image as a black and white (really grey-scale) image. +.TP +.B -v +Convert the image to an RGBV color-mapped image, even if the +display has true RGB color. +.TP +.B -d +Suppress display of the image; this is set automatically by +any of the following options: +.TP +.B -c +Convert the image to a Plan 9 representation, as defined by +.IR image (6), +and write it to standard output. +.TP +.B -9 +Like +.BR -c , +but produce an uncompressed image. +This saves processing time, particularly when the output is +being piped to another program such as +.IR page (1), +since it avoids compression and decompression. +.TP +.B -t +Convert the image, if it is in color, to a true color RGB image. +.TP +.B -3 +Like +.BR -t , +but force the image to RGB even if it is originally grey-scale. +.PD +.PP +.I Jpg +has two extra options used to process the output of the LML +video card: +.TP +.B -f +Merge two adjacent images, which represent the two fields of a video picture, +into a single image. +.TP +.B -F +The input is a motion JPEG file, with multiple images representing frames of the movie. Sets +.BR -f . +.PD +.PP +The +.IR togif +and +.IR toppm +programs go the other way: they convert from Plan 9 images to GIF and PPM, +and have no display capability. +Both accept an option +.B -c +to set the comment field of the resulting file. +If there is only one input picture, +.I togif +converts the image to GIF format. +If there are many +.IR files , +though, it will assemble them into an animated GIF file. +The options control this process: +.TP +.BI -l loopcount +By default, the animation will loop forever; +.I loopcount +specifies how many times to loop. +A value of zero means loop forever and a negative value means +to stop after playing the sequence once. +.TP +.BI -d msec +By default, the images are displayed as fast as they can be rendered. +This option specifies the time, in milliseconds, to pause while +displaying the next named +.IR file . +.PP +.I Gif +translates files that contain a `transparency' index by attaching +an alpha channel to the converted image. +.PP +.I Ico +displays a Windows icon (.ico) file. If no file is +specified, +.I ico +reads from standard input. +Icon files +contain sets of icons represented by an image and a mask. +Clicking the right button pops up a menu that lets you +write any icon's image as a Plan 9 image (\fIwidth\fBx\fIheight\fB.image\fR), +write any icon's mask as a Plan 9 image (\fIwidth\fBx\fIheight\fB.mask\fR), +or exit. Selecting one of the write menu items yields a sight cursor. +Move the sight over the icon and right click again to write. +.PP +.I Toico +takes a list of Plan 9 image files (or standard input) and creates +a single icon file. The masks in the icon file will be the white +space in the image. The icon file is written to standard output. +.SH SOURCE +.B /sys/src/cmd/jpg +.SH "SEE ALSO" +.IR page (1), +.IR image (6). +.br +.B http://www.w3.org/Graphics/JPEG/itu-t81.pdf +.br +.B http://www.w3.org/Graphics/GIF/spec-gif89a.txt +.br +.B http://www.w3.org/TR/2003/REC-PNG-20031110 +.br +.B http://netpbm.sourceforge.net/doc/ppm.html +.br +.B http://en.wikipedia.org/wiki/Windows_bitmap +.br +.B http://en.wikipedia.org/wiki/Yuv +.SH BUGS +Writing an animated GIF using +.I togif +is a clumsy undertaking. diff --git a/sys/man/1/kbmap b/sys/man/1/kbmap new file mode 100755 index 000000000..5a8d8a4e3 --- /dev/null +++ b/sys/man/1/kbmap @@ -0,0 +1,35 @@ +.TH KBMAP 1 +.SH NAME +kbmap \- show a list of available keyboard maps and switch between them. +.SH SYNOPSIS +.B kbmap +[ +.IR file ... +] +.SH DESCRIPTION +.I Kbmap +shows a single column consisting of the names of keyboard maps for different +alphabets available on the system. With no arguments +.B kbmap +will look for files in +.BR /sys/lib/kbmap . +.PP +Clicking the right mouse button will highlight the entry and force the +keyboard mapping defined in the corresponding file to become current +for the system; typing 'q' quits. +.PP +.I Kbmap +requires that the file +.B /dev/kbmap +served by +.IR kbmap (3) +exists and is writable. +..SH FILES +.TF /lib/kbmap/* +.SH SOURCE +.B /sys/src/cmd/kbmap.c +.SH "SEE ALSO" +.IR kbmap (3) +.SH BUGS +Not all keyboards map the entire set of characters, so one has to +switch back to the default map before changing to another. diff --git a/sys/man/1/kill b/sys/man/1/kill new file mode 100755 index 000000000..a4abe8a2f --- /dev/null +++ b/sys/man/1/kill @@ -0,0 +1,70 @@ +.TH KILL 1 +.SH NAME +kill, slay, broke \- print commands to kill processes +.SH SYNOPSIS +.B kill +.I name ... +.PP +.B slay +.I name ... +.PP +.B broke +[ +.I user +] +.SH DESCRIPTION +.I Kill +prints commands that will cause all processes called +.I name +and owned by the current user to be terminated. +Use the +.B send +command of +.IR rio (1), +or pipe the output of +.I kill +into +.IR rc (1) +to execute the commands. +.PP +.I Kill +suggests sending a +.B "kill" +note to the process; the same +message delivered to the process's +.B ctl +file (see +.IR proc (3)) +is a surer, if heavy handed, kill, +but is necessary if the offending process is +ignoring notes. +The +.I slay +command prints commands to do this. +.PP +.I Broke +prints commands that will cause all processes +in the +.I Broken +state +and owned by +.I user +(by default, the current user) +to go away. +When a process dies because of an error caught by +the system, it may linger in the +.I Broken +state to allow examination with a debugger. +Executing the commands printed by +.I broke +lets the system reclaim the resources used by +the broken processes. +.SH SOURCE +.B /rc/bin/kill +.br +.B /rc/bin/broke +.SH "SEE ALSO" +.IR ps (1), +.IR stop (1), +.IR notify (2), +.IR proc (3) diff --git a/sys/man/1/ktrace b/sys/man/1/ktrace new file mode 100755 index 000000000..ef1086f11 --- /dev/null +++ b/sys/man/1/ktrace @@ -0,0 +1,62 @@ +.TH KTRACE 1 +.SH NAME +ktrace \- interpret kernel stack dumps +.SH SYNOPSIS +.B ktrace +[ +.B -i +] +.I kernel +.I pc +.I sp +[ +.I link +] +.SH DESCRIPTION +.I Ktrace +translates a hexadecimal kernel stack dump +into a sequence of +.IR acid (1) +commands to show the points in the call trace. +The +.I kernel +argument should be the path of the kernel being debugged, +and +.I pc +and +.I sp +are the PC and SP values given in the stack dump. +For MIPS kernels, the contents of the +.I link +register must also be supplied. +.PP +A stack trace consists of a +.I ktrace +command followed by a series of lines containing +fields of the form +.IB location = contents \fR: +.EX +ktrace /kernel/path 80105bc1 8048e174 +8048e114=80105ac6 8048e120=80140bb4 8048e134=8010031c +8048e16c=80137e45 8048e170=80105bc1 8048e178=80137e62 +\&... +.EE +.PP +The trace can be edited to provide the correct kernel path +and then pasted into a shell window. +If the +.B -i +option is present, +.I ktrace +instead prompts for the contents of the memory locations in which it is interested; +this is useful when the stack trace is on a screen rather than +in a machine readable form. +.SH SOURCE +.B /sys/src/cmd/ktrace.c +.SH SEE ALSO +.IR acid (1), +.IR rdbfs (4) +.SH BUGS +When examining a kernel trace resulting from +an interrupt on top of other interrupts, +only the topmost call trace is printed. diff --git a/sys/man/1/leak b/sys/man/1/leak new file mode 100755 index 000000000..6890b0553 --- /dev/null +++ b/sys/man/1/leak @@ -0,0 +1,235 @@ +.TH LEAK 1 +.SH NAME +leak, kmem, umem \- help find memory leaks +.SH SYNOPSIS +.B leak +[ +.B -abcds +] +[ +.B -f +.I binary +] +[ +.B -r +.I res +] +[ +.B -x +.I width +] +.I pid ... +.PP +.B kmem +[ +.I kernel +] +.PP +.B umem +.I pid +[ +.I textfile +] +.SH DESCRIPTION +.I Leak +examines the named processes, which +should be sharing their data and bss segments, +for memory leaks. +It uses a mark and sweep-style algorithm to +determine which allocated blocks are no longer +reachable from the set of root pointers. +The set of root pointers is created by looking through +the shared bss segment as well as each process's registers. +.PP +Unless directed otherwise, +.I leak +prints, for each block, a line with seven space-separated fields: +the string +.BR block , +the address of the block, +the size of the block, +the first two words of the block, +and the function names represented by the first two words of the block. +Usually, the first two words of the block +contain the malloc and realloc tags +(see +.IR malloc (2)), +useful for finding who allocated the leaked blocks. +.PP +If the +.B -s +or the +.B -c +option is given, +.I leak +will instead present a sequence of +.IR acid (1) +commands that show each leaky allocation site. +With +.B -s +a comment appears next to each command to +indicate how many lost blocks were allocated +at that point in the program. +With +.B -c +the comments are extended to indicate also the total +number of bytes lost at that point in the program, +and an additional comment line gives the +overall total number of bytes. +.PP +If the +.B -a +option is given, +.I leak +will print information as decribed above, +but for all allocated blocks, +not only leaked ones. +If the +.B -d +option is given, +.I leak +will print information as decribed above, +but for all free blocks, +i.e. those freed, +or those that are not yet +in use (fragmentation?). +The +.B -a +and +.B -d +options can be combined. +.PP +If the +.B -b +option is given, +.I leak +will print a Plan 9 image file +graphically summarizing the memory arenas. +In the image, each pixel represents +.I res +(default 8) +bytes. +The color code is: +.TP "\w'\fIbright blue\fR 'u +.I "dark blue +Completely allocated. +.TP +.I "bright blue +Contains malloc headers. +.TP +.I "bright red +Contains malloc headers for leaked memory. +.TP +.I "dark red +Contains leaked memory. +.TP +.I "yellow +Completely free +.TP +.I "white +Padding to fill out the image. +.PD +The bright pixels representing headers help in +counting the number of blocks. +Magnifying the images with +.IR lens (1) +is often useful. +.PP +If given a name rather than a list of process ids, +.I leak +echoes back a command-line with process ids of every process +with that name. +.PP +The +.B -f +option specifies a binary to go on the +.IR acid (1) +command-line used to inspect the +processes, and is only necessary +when inspecting processes started +from stripped binaries. +.PP +.I Umem +prints a summary of all allocated blocks in the process with id +.IR pid . +Each line of the summary gives the count and total size of +blocks allocated at an allocation point. +The list is sorted by count in decreasing order. +.I Umem +prints summarizes all allocations, not just +memory leaks, but it is faster and requires less memory than +.I leak . +.PP +.I Kmem +is like +.I umem +but prints a summary for the running kernel. +.SH EXAMPLES +List lost blocks in +.IR 8.out . +This depends on the fact that there is only +once instance of +.I 8.out +running; if there were more, the output of +.B "leak -s 8.out +would need editing before sending to the shell. +.IP +.EX +% leak -s 8.out +leak -s 229 230 +% leak -s 8.out | rc +src(0x0000bf1b); // 64 +src(0x000016f5); // 7 +src(0x0000a988); // 7 +% +.EE +.LP +View the memory usage graphic for the window system. +.IP +.EX +% leak -b rio | rc | page +.EE +.PP +List the top allocation points in the kernel, +first by count and then by total size: +.IP +.EX +% kmem | sed 10q +% kmem | sort -nr +1 | sed 10q +.EE +.SH SOURCE +.B /sys/lib/acid/leak +.br +.B /sys/src/cmd/aux/acidleak.c +.br +.B /rc/bin/leak +.br +.B /rc/bin/kmem +.br +.B /rc/bin/umem +.SH SEE ALSO +.IR getcallerpc (2), +.I setmalloctag +in +.IR malloc (2) +.SH BUGS +.I Leak +and +.I kmem +depend on the internal structure of the +libc pool memory allocator (see +.IR pool (2)). +Since the ANSI/POSIX environment uses a different +allocator, +.I leak +will not work on APE programs. +.PP +.I Leak +is not speedy, and +.I acidleak +can consume more memory than the process(es) being examined. +.PP +These commands require +.B /sys/src/libc/port/pool.acid +to be present and generated from +.BR pool.c . diff --git a/sys/man/1/lens b/sys/man/1/lens new file mode 100755 index 000000000..f944540c1 --- /dev/null +++ b/sys/man/1/lens @@ -0,0 +1,45 @@ +.TH LENS 1 +.SH NAME +lens \- interactive screen magnifier +.SH SYNOPSIS +.B lens +.SH DESCRIPTION +.I Lens +presents a magnified view in its window of an arbitrary area on the screen. +The default magnification is 4 (showing each pixel as a 4×4 pixel block in +.IR lens 's +window). This may be changed by typing a digit on the keyboard (with +.B 0 +standing for 10), or by using the +.B + +and +.B - +keys to increase or decrease the magnification by one unit. +The lower limit is ×1; the upper ×16. +.PP +The interface to indicate what area to magnify is dictated by the mouse multiplexing rules of +.IR rio (1). +Start by pressing mouse button 1 in the +.I lens +window and dragging, with the button pressed, to the center of the area to magnify. +.I Lens +will update the display as the mouse moves. +Releasing the button freezes the +.I lens +display. +The magnified view is static\(ema snapshot, not a movie\(embut typing a space or +.B . +key in the +.I lens +window will refresh the +display, as will changing the magnification. +.PP +To make counting pixels easier, typing a +.B g +toggles whether a checkerboard grid is imposed on the magnified area. +.PP +Button 3 brings up a menu of actions. +.SH SOURCE +.B /sys/src/cmd/lens.c +.SH BUGS +There should be an easier way to indicate what to magnify. diff --git a/sys/man/1/lex b/sys/man/1/lex new file mode 100755 index 000000000..f0f148335 --- /dev/null +++ b/sys/man/1/lex @@ -0,0 +1,81 @@ +.TH LEX 1 +.SH NAME +lex \- generator of lexical analysis programs +.SH SYNOPSIS +.B lex +[ +.B -tvn9 +] +[ +.I file ... +] +.SH DESCRIPTION +.I Lex +generates programs to be used in simple lexical analysis of text. +The input +.I files +(standard input default) +contain regular expressions +to be searched for and actions written in C to be executed when +expressions are found. +.PP +A C source program, +.B lex.yy.c +is generated. +This program, when run, copies unrecognized portions of +the input to the output, +and executes the associated +C action for each regular expression that is recognized. +.PP +The options have the following meanings. +.TP +.B -t +Place the result on the standard output instead of in file +.BR lex.yy.c . +.TP +.B -v +Print a one-line summary of statistics of the generated analyzer. +.TP +.B -n +Opposite of +.BR -v ; +.B -n +is default. +.TP +.B -9 +Adds code to be able to compile through the native C compilers. +.SH EXAMPLES +This program converts upper case to lower, +removes blanks at the end of lines, +and replaces multiple blanks by single blanks. +.PP +.EX +%% +[A-Z] putchar(yytext[0]+\'a\'-\'A\'); +[ ]+$ +[ ]+ putchar(\' \'); +.EE +.SH FILES +.TF /sys/lib/lex/ncform +.TP +.B lex.yy.c +output +.TP +.B /sys/lib/lex/ncform +template +.SH "SEE ALSO" +.IR yacc (1), +.IR sed (1) +.br +M. E. Lesk and E. Schmidt, +`LEX\(emLexical Analyzer Generator', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.SH SOURCE +.B /sys/src/cmd/lex +.SH BUGS +Cannot handle +.SM UTF. +.PP +The asteroid to kill this dinosaur is still in orbit. diff --git a/sys/man/1/lock b/sys/man/1/lock new file mode 100755 index 000000000..bc6251e04 --- /dev/null +++ b/sys/man/1/lock @@ -0,0 +1,61 @@ +.TH LOCK 1 +.SH NAME +lock \- run a command under lock +.SH SYNOPSIS +.B lock +[ +.B -w +] +.I lockfile +[ +.I command +[ +.I argument +\&... +] ] +.SH DESCRIPTION +.I Lock +runs +.I command +(default +.LR rc ) +with +.I arguments +while holding +.I lockfile +open and (over)writing at least one byte each minute +to keep the exclusive-access lock alive. +If +.I lockfile +doesn't already have the exclusive-access bit set in +its mode, +the exclusive-access bits are set in its mode and +.BR qid.type . +.PP +Under +.BR -w , +.I lock +waits for exclusive access to +.I lockfile +instead of just trying once. +.PP +.I Lock +sets +.B /env/prompt +to contain the name of the lock file. +.SH EXAMPLES +Build a +.IR replica (1) +database while preventing collisions with other occurrences. +.IP +.EX +cd /sys/lib/dist +lock scan.lock replica/scan $dist/sources.replica +.EE +.SH SOURCE +.B /sys/src/cmd/lock.c +.SH SEE ALSO +.IR intro (5), +.IR stat (5) +.\" .SH DIAGNOSTICS +.\" .SH BUGS diff --git a/sys/man/1/look b/sys/man/1/look new file mode 100755 index 000000000..1bf634fd7 --- /dev/null +++ b/sys/man/1/look @@ -0,0 +1,85 @@ +.TH LOOK 1 +.SH NAME +look \- find lines in a sorted list +.SH SYNOPSIS +.B look +[ +.BI -dfnixt c +] +[ +.I string +] +[ +.I file +] +.SH DESCRIPTION +.I Look +consults a sorted +.I file +and prints all lines that begin with +.IR string . +It uses binary search. +.PP +The following options are recognized. +Options +.B dfnt +affect comparisons as in +.IR sort (1). +.TP +.B -i +Interactive. +There is no +.I string +argument; instead +.I look +takes lines from the standard input as strings to be looked up. +.TP +.B -x +Exact. +Print only lines of the file whose key matches +.I string +exactly. +.TP +.B -d +`Directory' order: +only letters, digits, +tabs and blanks participate in comparisons. +.TP +.B -f +Fold. +Upper case letters compare equal to lower case. +.TP +.B -n +Numeric comparison with initial string of digits, optional minus sign, +and optional decimal point. +.TP +.BR -t [ \f2c\f1 ] +Character +.I c +terminates the sort key in the +.IR file . +By default, tab terminates the key. If +.I c +is missing the entire line comprises the key. +.PP +If no +.I file +is specified, +.B /lib/words +is assumed, with collating sequence +.BR df . +.SH FILES +.B /lib/words +.SH SOURCE +.B /sys/src/cmd/look.c +.SH "SEE ALSO" +.IR sort (1), +.IR grep (1) +.SH DIAGNOSTICS +The exit status is +.RB `` "not found" '' +if no match is found, and +.RB `` "no dictionary" '' +if +.I file +or the default dictionary cannot be opened. diff --git a/sys/man/1/lp b/sys/man/1/lp new file mode 100755 index 000000000..35b30e7c6 --- /dev/null +++ b/sys/man/1/lp @@ -0,0 +1,189 @@ +.TH LP 1 +.SH NAME +lp \- printer output +.SH SYNOPSIS +.B lp +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Lp +is a generalized output printing service. +It can be used to queue files for printing, +check a queue, or kill jobs in a queue. +The options are: +.TF -d\ \fIde\fP +.TP +.BI -d " dest" +Select the destination printer. +If +.I dest +is +.LR ? , +list the currently available printers. +In the absence of +.LR -d , +the destination is taken from the environment variable +.BR LPDEST . +Destination +.L stdout +is the standard output. +Destination +.L safari +is +.L /dev/lpt1data +line printer port on a 386 machine, assumed +to be connected to a PostScript printer. +Destinations +.L hpdeskjet +and +.L bjc240l +are also +.L /dev/lpt1data +but assumed to be connected to an HP Deskjet 670 or +Canon BJC-240. +.I Lp +can print to any printer supported by +Ghostscript using syntax +.BI gs!device +where +.I device +is a Ghostscript output device. +See +.IR gs (1) +and the +.L canonbjc240l +entry in +.LR /sys/lib/lp/devices . +.TP +.B -k +Kill the job(s) given as subsequent arguments, instead of file names, +for the given destination. +.TP +.BI -p " proc" +The given processor is invoked. +The default processor is +.LR generic , +which tries to do the right thing for regular text, +.IR troff (1) +output, or +.IR tex (1) +output. +If no processing is desired +.L noproc +may be specified. +.TP +.B -q +Print the queue for the given destination. +For some devices, include printer status. +.TP +.B -R +Stops and restarts the printer daemon. +If the printer is wedged, it is often useful to cycle the power on the printer +before running this command. +.PD +.PP +The remaining options may be used to affect the output at a given device. +These options may not be applicable to all devices. +.TF "-p\ \fIpr\fP" +.TP +.BI -c " n" +Print +.I n +copies. +.TP +.BI -f " font" +Set the font (default +.LR CW.11 ). +.TP +.BI -H +Suppress printing of header page. +.TP +.BI -i " n" +Select paper input tray. +.I n +may be a number 0-9, the word +.L man +for the manual feed slot, and/or +.L simplex +or +.L duplex +to get single or double sided output. +Multiple input tray options may be specified if they are +separated by commas. +.TP +.BI -l " n" +Set the number of lines per page to +.IR n . +.TP +.B -L +Print pages in landscape mode (i.e. turned 90 degrees). +.TP +.BI -m " v" +Set magnification to +.IR v . +.TP +.BI -n " n" +Print +.I n +logical pages per physical page. +.TP +.BI -o " list" +Print only pages whose page numbers appear in +the comma-separated +.I list +of numbers and ranges. +A range +.IB n - m +means pages +.I n +through +.IR m ; +a range +.BI - n +means from the beginning to page +.IR n ; +a range +.IB n - +means from page +.I n +to the end. +.TP +.B -r +Reverse the order of page printing. +.TP +.BI -x " v" +Set the horizontal +offset of the print image, measured in inches. +.TP +.BI -y " v" +Set the vertical +offset of the print image, measured in inches. +.SH EXAMPLES +.TP 0 +.L +eqn paper | troff -ms | lp -dsafari +Typeset and print a paper containing equations. +.TP +.L +pr -l100 file | lp -l100 -fCW.8 +Print a file in a small font at 100 lines per page. +.TP +.L +lp -dstdout /dev/windows/3/window > doc.ps +Convert an image to a postscript file. +.SH SOURCE +.nf +.B /rc/bin/lp +.B /sys/src/cmd/lp +.SH SEE ALSO +.IR lp (8) +.br +P. Glick, +``A Guide to the Lp Printer Spooler''. +.SH BUGS +Not all options work with all output devices. +Any user can kill any job. diff --git a/sys/man/1/ls b/sys/man/1/ls new file mode 100755 index 000000000..e89d75d6a --- /dev/null +++ b/sys/man/1/ls @@ -0,0 +1,160 @@ +.TH LS 1 +.SH NAME +ls, lc \- list contents of directory +.SH SYNOPSIS +.B ls +[ +.B -dlmnpqrstuFQT +] +.I name ... +.PP +.B lc +[ +.B -dlmnqrstuFQT +] +.I name ... +.SH DESCRIPTION +For each directory argument, +.I ls +lists the contents of the directory; +for each file argument, +.I ls +repeats its name and any other information requested. +When no argument is given, the current directory is listed. +By default, the output is sorted alphabetically by name. +.PP +.I Lc +is the same as +.IR ls , +but sets the +.B -p +option and pipes the output through +.IR mc (1). +.PP +There are a number of options: +.TP +.B -d +If argument is a directory, list it, not +its contents. +.TP +.B -l +List in long format, giving mode (see below), file system type +(e.g., for devices, the +.B # +code letter that names it; see +.IR intro (3)), +the instance or subdevice number, owner, group, +size in bytes, and time of last modification +for each file. +.TP +.B -m +List the name of the user who most recently modified the file. +.TP +.B -n +Don't sort the listing. +.TP +.B -p +Print only the final path element of each file name. +.TP +.B -q +List the +.I qid +(see +.IR stat (2)) +of each file; the printed fields are in the order +path, version, and type. +.TP +.B -r +Reverse the order of sort. +.TP +.B -s +Give size in Kbytes for each entry. +.TP +.B -t +Sort by time modified (latest first) instead of +by name. +.TP +.B -u +Under +.B -t +sort by time of last access; +under +.B -l +print time of last access. +.TP +.B -F +Add the character +.B / +after all directory names +and the character +.B * +after all executable files. +.TP +.B -T +Print the character +.B t +before each file if it has the temporary flag set, and +.B - +otherwise. +.TP +.B -Q +By default, printed file names are quoted if they contain characters special to +.IR rc (1). +The +.B -Q +flag disables this behavior. +.PP +The mode printed under the +.B -l +option contains 11 characters, +interpreted +as follows: +the first character is +.TP +.B d +if the entry is a directory; +.TP +.B a +if the entry is an append-only file; +.TP +.B - +if the entry is a plain file. +.PD +.PP +The next letter is +.B l +if the file is exclusive access (one writer or reader at a time). +.PP +The last 9 characters are interpreted +as three sets of three bits each. +The first set refers to owner permissions; +the next to permissions to others in the same user-group; +and the last to all others. +Within each set the three characters indicate +permission respectively to read, to write, or to +execute the file as a program. +For a directory, `execute' permission is interpreted +to mean permission to search the directory +for a specified file. +The permissions are indicated as follows: +.TP 3 +.B r +if the file is readable; +.PD 0 +.TP 3 +.B w +if the file is writable; +.TP 3 +.B x +if the file is executable; +.TP 3 +.B - +if none of the above permissions is granted. +.PD +.SH SOURCE +.B /sys/src/cmd/ls.c +.br +.B /rc/bin/lc +.SH SEE ALSO +.IR stat (2), +.IR mc (1) diff --git a/sys/man/1/mail b/sys/man/1/mail new file mode 100755 index 000000000..cfe042969 --- /dev/null +++ b/sys/man/1/mail @@ -0,0 +1,164 @@ +.TH MAIL 1 +.SH NAME +mail, go.fishing \- mail and mailboxes +.SH SYNOPSIS +.B mail +[ +.I arg ... +] +.PP +.B go.fishing +.SH DESCRIPTION +.PP +Mail is a shell script that invokes +.IR nedmail (1), +the mail reader, +when no recipients appear on the command line and +.IR marshal (1), +the mail preparer, +otherwise. +All command line options are passed through. +See the man pages for those two commands for +more details. +.PP +Incoming mail for a user +.I username +is put in the file +.BI /mail/box/ username /mbox +unless either the file +.BI /mail/box/ username /forward +or +.BI /mail/box/ username /pipeto +exists. +The mailbox must have append-only and exclusive-access mode +(see +.IR chmod (1)). +A user must create his or her own mailbox using the +.B -c +option of +.IR nedmail (1). +Mailboxes are created writable (append-only) but not readable by others. +.PP +If the file +.BI /mail/box/ username /forward +exists and is readable by everyone, incoming mail +will be forwarded to the addresses contained in the first line of the file. +The file may contain multiple addresses. +Forwarding loops are caught and resolved by local delivery. +.PP +If the file +.BI /mail/box/ username /pipeto +exists and is readable and executable by everyone, +it will be run for each incoming message for the user. +The message will be piped to it rather +than appended to his/her mail box. +The file is run as user +.BR none . +Its two arguments are the +with arguments of the destination address +(e.g., +.BR local!gremlin ) +and the user's mail box path +(e.g., +.BR /mail/box/gremlin/mbox ) +.SS Auto-answer +.PP +To use +.I mail +as an answering machine while you are away, +run +.IR go.fishing , +which will create +.B /mail/box/$user/gone.fishing +as a flag for +.B pipeto +processing, +and truncate +.BR /mail/box/$user/gone.addrs . +Any existing +.B pipeto +file that uses +.B /mail/lib/pipeto.lib +will invoke the +.I gone.fishing +machinery when it calls +.B spool +or +.BR spool-tagged-spam . +.PP +If +.B /mail/box/$user/gone.msg +exists, it +will be sent (just once) to everyone who +sends you mail that lists your address in a +.L To +or +.L Cc +header; +if not, +.B /mail/lib/gone.msg +will be sent. +Upon your return, remove +.B /mail/box/$user/gone.fishing +to stop automatic responses. +.SH FILES +.TF /mail/box/$user/gone.fishing +.TP +.B /sys/log/mail +mail log file +.TP +.B /mail/box/* +mail directories +.TP +.B /mail/box/*/mbox +mailbox files +.TP +.B /mail/box/*/forward +forwarding address(es) +.TP +.B /mail/box/*/pipeto +mail filter +.TP +.B /mail/box/*/L.reading +mutual exclusion lock for multiple mbox readers +.TP +.B /mail/box/*/L.mbox +mutual exclusion lock for altering mbox +.TP +.B /lib/face/48x48x? +directories of icons for +.I seemail +.TP +.B /mail/lib/pipeto.lib +helper functions for pipeto files +.TP +.B /mail/lib/gone.msg +default vacation message +.TP +.B /mail/lib/gone.fishing +auto-responder as +.I pipeto +script +.TP +.B /mail/box/$user/gone.fishing +flag to active gone processing +.TP +.B /mail/box/$user/gone.addrs +list of senders answered by +.I gone.fishing +.SH SOURCE +.B /rc/bin/mail +.br +.B /rc/bin/go.fishing +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR smtp (8), +.IR upasfs (4) diff --git a/sys/man/1/man b/sys/man/1/man new file mode 100755 index 000000000..fd85456c9 --- /dev/null +++ b/sys/man/1/man @@ -0,0 +1,122 @@ +.TH MAN 1 +.SH NAME +man, lookman, sig \- print or find pages of this manual +.SH SYNOPSIS +.B man +[ +.B -bnpPStw +] +[ +.I section ... +] +.I title ... +.PP +.B lookman +.I key ... +.PP +.B sig +.I function ... +.SH DESCRIPTION +.I Man +locates and prints pages of this manual named +.I title +in the specified +.IR sections . +.I Title +is given in lower case. +Each +.I section +is a number; +pages marked (2S), for example, +belong to chapter 2. +If no +.I section +is specified, pages +in all sections are printed. +Any name from the +.SM NAME +section at the top of the page will serve as a +.IR title . +.PP +The options are: +.TP +.B -n +(Default) +Print the pages on the standard output using +.IR nroff . +.TP +.B -b +Print the pages using +.I nroff +and send them to +.IR plumber (4) +for display in the editor. +.TP +.B -p +Run +.IR proof (1) +on the specified man pages. +.TP +.B -P +Run +.IR page (1) +on the specified man pages. +.TP +.B -S +Do not search the manual indices for the names. +Only print pages whose file names match the names. +.TP +.B -t +Run +.IR troff (1) +and send its output +to standard output. +.TP +.B -w +Print the names of the man page source files. +.PD +.PP +.B Lookman +prints the names of all manual sections that contain +all of the +.I key +words given on the command line. +.PP +.B Sig +prints the signature (i.e. C definition) of the +.IR function s +given on the command line. +.SH FILES +.TP +.B /sys/man/?/* +.I troff +source for manual; this page is +.B /sys/man/1/man +.TP +.B /sys/man/?/INDEX +indices searched to find pages corresponding to titles +.TP +.B /sys/lib/man/secindex +command to make an index for a given section +.TP +.B /sys/lib/man/lookman/index +index for +.I lookman +.SH SOURCE +.B /rc/bin/man +.br +.B /rc/bin/lookman +.SH "SEE ALSO" +.IR page (1), +.IR proof (1) +.SH BUGS +The manual was intended to be typeset; some detail is sacrificed on text terminals. +.PP +There is no automatic mechanism to keep the indices up to date. +.PP +Except for special cases, +.I man +doesn't recognize things that should be run through +.I tbl +and/or +.IR eqn . diff --git a/sys/man/1/marshal b/sys/man/1/marshal new file mode 100755 index 000000000..b2fc90e27 --- /dev/null +++ b/sys/man/1/marshal @@ -0,0 +1,173 @@ +.TH MARSHAL 1 +.SH NAME +marshal \- formatting and sending mail +.SH SYNOPSIS +.B upas/marshal +[ +.B -[aA] +.I attachment +] [ +.B -C +.I copyaddr +] [ +.B -nrx# +] [ +.B -R +.I reply-msg +] [ +.B -s +.I subject +] [ +.B -t +.I mime-type +] [ +.I mailaddr ... +] +.SH DESCRIPTION +.I Marshal +builds a mail message from standard input and passes it, +if the body is non-empty, +for transmission or delivery to +.BI /mail/box/ username /pipefrom +if it exists, otherwise to +.BR /bin/upas/send . +The message format is both RFC 822 and +MIME conformant, so +.I marshal +adds any required headers not already in the message, prefixed by +the contents of +.BI /mail/box/ username /headers\f1. +This allows the addition of personal headers like +.B From: +lines with a full name or a different +return address. +Command line options direct marshal to add a subject line +and append attachments. The arguments to +.I marshal +are the addresses of the recipients. +.PP +When running in a +.IR rio (1) +window, +.I marshal +automatically puts the window into hold mode (see +.IR rio (1)); +this means that the message can be edited freely, +because nothing will be sent to +.I marshal +until the ESC key is hit to exit hold mode. +.PP +The options are: +.TF "-a file" +.TP +.BI -a file +directs +.I marshal +to append +.I file +as a mime attachment. +Unless explicitly specified by the +.B -t +option, the type of the attachment is determined +by running the +.IR file (1) +command. +.TP +.BI -A file +is like +.B -a +but the message disposition is marked as +.I inline +directing any mail reader to display the attachment +(if it can) when the mail message is read. +.TP +.BI -C copyaddr +adds a +.B Cc: +header with +.I copyaddr +and also adds +.I copyaddr +as a recipient. +.TP +.BI -n +intentionally no standard input +.TP +.B -#xr +are all passed as command line options to the +.I send +that +.I marshal +invokes. +.TP +.BI -R replymsg +tells marshal what message this one is in reply to. +.I Replymsg +is an +.IR upasfs (4) +directory containing the message. +.I Marshal +uses any message id in this message in its +.B In-Reply-To +field. It also passes the directory to +.BI /mail/box/ username /pipefrom +in the +.B replymsg +environment variable. Thus, +.B pipefrom +can alter the message to somehow match +the reply to the message it is replying to. +.TP +.BI -s subject +adds a +.B Subject: +header line to the message if one does not +already exist. +.TP +.BI -t type +sets the content type for the attachments from +all subsequent +.B -a +and +.B -A +options. +.PD +.PP +.I Marshal +also expands any user mail aliases contained in +.BI /mail/box/ username /names. +The format of the alias file is the same as that +for system aliases, see +.IR aliasmail (8). +.PP +.I Marshal +uses the login name as the reply address. This +can be overriden using the environment variable +.BR upasname . +Its value will become both the envelope +and +.B From: +mailbox name. +For example: +.IP +.EX +upasname=natasha@kremvax.com upas/mail boris@squirrel.com +.EE +.SH FILES +.TP +.B /mail/box/*/dead.letter +.SH SOURCE +.TP +.B /sys/src/cmd/upas/marshal +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR mail (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR smtp (8), +.IR upasfs (4) diff --git a/sys/man/1/mc b/sys/man/1/mc new file mode 100755 index 000000000..40fec44d4 --- /dev/null +++ b/sys/man/1/mc @@ -0,0 +1,44 @@ +.TH MC 1 +.SH NAME +mc \- multicolumn print +.SH SYNOPSIS +.B mc +[ +.B - +] +[ +.BI - N +] +[ +.I file ... +] +.SH DESCRIPTION +.I Mc +splits the input into as many columns as will fit in +.I N +print positions. +If run in a +.IR rio (1) +or +.IR acme (1) +window, the default +.I N +is the number of blanks that will fit across the window; +otherwise the default +.I N +is 80. +Under option +.B - +each input line ending in a colon +.L : +is printed separately. +.SH SOURCE +.B /sys/src/cmd/mc.c +.SH "SEE ALSO" +.IR rio (1), +.IR acme (1), +.IR acme (4), +.IR pr (1), +.I lc +in +.IR ls (1) diff --git a/sys/man/1/mk b/sys/man/1/mk new file mode 100755 index 000000000..bd1a8ae8f --- /dev/null +++ b/sys/man/1/mk @@ -0,0 +1,655 @@ +.TH MK 1 +.SH NAME +mk, membername \- maintain (make) related files +.SH SYNOPSIS +.B mk +[ +.B -f +.I mkfile +] ... +[ +.I option ... +] +[ +.I target ... +] +.PP +.B membername +.I aggregate ... +.SH DESCRIPTION +.I Mk +uses the dependency rules specified in +.I mkfile +to control the update (usually by compilation) of +.I targets +(usually files) +from the source files upon which they depend. +The +.I mkfile +(default +.LR mkfile ) +contains a +.I rule +for each target that identifies the files and other +targets upon which it depends and an +.IR rc (1) +script, a +.IR recipe , +to update the target. +The script is run if the target does not exist +or if it is older than any of the files it depends on. +.I Mkfile +may also contain +.I meta-rules +that define actions for updating implicit targets. +If no +.I target +is specified, the target of the first rule (not meta-rule) in +.I mkfile +is updated. +.PP +The environment variable +.B $NPROC +determines how many targets may be updated simultaneously; +Plan 9 sets +.B $NPROC +automatically to the number of CPUs on the current machine. +.PP +Options are: +.TP \w'\fL-d[egp]\ 'u +.B -a +Assume all targets to be out of date. +Thus, everything is updated. +.PD 0 +.TP +.BR -d [ egp ] +Produce debugging output +.RB ( p +is for parsing, +.B g +for graph building, +.B e +for execution). +.TP +.B -e +Explain why each target is made. +.TP +.B -i +Force any missing intermediate targets to be made. +.TP +.B -k +Do as much work as possible in the face of errors. +.TP +.B -n +Print, but do not execute, the commands +needed to update the targets. +.TP +.B -s +Make the command line arguments sequentially rather than in parallel. +.TP +.B -t +Touch (update the modified date of) file targets, without +executing any recipes. +.TP +.BI -w target1 , target2,... +Pretend the modify time for each +.I target +is the current time; useful in conjunction with +.B -n +to learn what updates would be triggered by +modifying the +.IR targets . +.PD +.PP +The +.IR rc (1) +script +.I membername +extracts member names +(see `Aggregates' below) +from its arguments. +.SS The \fLmkfile\fP +A +.I mkfile +consists of +.I assignments +(described under `Environment') and +.IR rules . +A rule contains +.I targets +and a +.IR tail . +A target is a literal string +and is normally a file name. +The tail contains zero or more +.I prerequisites +and an optional +.IR recipe , +which is an +.B rc +script. +Each line of the recipe must begin with white space. +A rule takes the form +.IP +.EX +target: prereq1 prereq2 + rc \f2recipe using\fP prereq1, prereq2 \f2to build\fP target +.EE +.PP +When the recipe is executed, +the first character on every line is elided. +.PP +After the colon on the target line, a rule may specify +.IR attributes , +described below. +.PP +A +.I meta-rule +has a target of the form +.IB A % B +where +.I A +and +.I B +are (possibly empty) strings. +A meta-rule acts as a rule for any potential target whose +name matches +.IB A % B +with +.B % +replaced by an arbitrary string, called the +.IR stem . +In interpreting a meta-rule, +the stem is substituted for all occurrences of +.B % +in the prerequisite names. +In the recipe of a meta-rule, the environment variable +.B $stem +contains the string matched by the +.BR % . +For example, a meta-rule to compile a C program using +.IR 2c (1) +might be: +.IP +.EX +%: %.c + 2c $stem.c + 2l -o $stem $stem.2 +.EE +.PP +Meta-rules may contain an ampersand +.B & +rather than a percent sign +.BR % . +A +.B % +matches a maximal length string of any characters; +an +.B & +matches a maximal length string of any characters except period +or slash. +.PP +The text of the +.I mkfile +is processed as follows. +Lines beginning with +.B < +followed by a file name are replaced by the contents of the named +file. +Lines beginning with +.B "<|" +followed by a file name are replaced by the output +of the execution of the named +file. +Blank lines and comments, which run from unquoted +.B # +characters to the following newline, are deleted. +The character sequence backslash-newline is deleted, +so long lines in +.I mkfile +may be folded. +Non-recipe lines are processed by substituting for +.BI `{ command } +the output of the +.I command +when run by +.IR rc . +References to variables are replaced by the variables' values. +Special characters may be quoted using single quotes +.BR \&'' +as in +.IR rc (1). +.PP +Assignments and rules are distinguished by +the first unquoted occurrence of +.B : +(rule) +or +.B = +(assignment). +.PP +A later rule may modify or override an existing rule under the +following conditions: +.TP +\- +If the targets of the rules exactly match and one rule +contains only a prerequisite clause and no recipe, the +clause is added to the prerequisites of the other rule. +If either or both targets are virtual, the recipe is +always executed. +.TP +\- +If the targets of the rules match exactly and the +prerequisites do not match and both rules +contain recipes, +.I mk +reports an ``ambiguous recipe'' error. +.TP +\- +If the target and prerequisites of both rules match exactly, +the second rule overrides the first. +.SS Environment +Rules may make use of +.B rc +environment variables. +A legal reference of the form +.B $OBJ +is expanded as in +.IR rc (1). +A reference of the form +.BI ${name: A % B = C\fL%\fID\fL}\fR, +where +.I A, B, C, D +are (possibly empty) strings, +has the value formed by expanding +.B $name +and substituting +.I C +for +.I A +and +.I D +for +.I B +in each word in +.B $name +that matches pattern +.IB A % B\f1. +.PP +Variables can be set by +assignments of the form +.I + var\fL=\fR[\fIattr\fL=\fR]\fIvalue\fR +.br +Blanks in the +.I value +break it into words, as in +.I rc +but without the surrounding parentheses. +Such variables are exported +to the environment of +recipes as they are executed, unless +.BR U , +the only legal attribute +.IR attr , +is present. +The initial value of a variable is +taken from (in increasing order of precedence) +the default values below, +.I mk's +environment, the +.IR mkfiles , +and any command line assignment as an argument to +.IR mk . +A variable assignment argument overrides the first (but not any subsequent) +assignment to that variable. +.PP +The variable +.B MKFLAGS +contains all the option arguments (arguments starting with +.L - +or containing +.LR = ) +and +.B MKARGS +contains all the targets in the call to +.IR mk . +.PP +It is recommended that mkfiles start with +.IP +.EX +\fP/address-list +.TP +.B /mail/box/\fI\fP +list's mailbox directory +.TP +.B /mail/box/\fI\fP-owner +owner's mailbox directory +.TP +.B /mail/box/\fI\fP/address-list +log of mailing list deletions and additions +.SH SOURCE +.TP +.B /sys/src/cmd/upas/ml +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR mail (1), +.IR marshal (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR smtp (8), +.IR upasfs (4) + diff --git a/sys/man/1/mp3dec b/sys/man/1/mp3dec new file mode 100755 index 000000000..b455f54a7 --- /dev/null +++ b/sys/man/1/mp3dec @@ -0,0 +1,47 @@ +.TH MP3DEC 1 +.SH NAME +mp3dec \- decode audio MPEG files (layers 1, 2 and 3) +.SH SYNOPSIS +.B mp3dec +[ +.B -o +.I outfile +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Mp3dec +decodes one or more MPEG audio files, writing +16-bit stereo linear PCM sample data to +.I outfile +(default +.BR /dev/audio ). +If no files are named, +.I mp3dec +reads standard input. +.PP +In the absence of the +.B -o +option, +.I mp3dec +also opens +.BR /dev/volume +and sets the sample rate for playback to +match the audio stream. +When writing to +.IR outfile , +.I mp3dec +prints a warning to standard error +if the stream rate is not 44100 Hz. +.SH SOURCE +.B /sys/src/games/mp3dec +.SH "SEE ALSO" +.IR mp3enc (1), +.IR juke (7), +.IR playlistfs (7) +.br +.B http://www.underbit.com/products/mad/ +.SH BUGS +It's another GNU behemoth, lightly tamed. diff --git a/sys/man/1/mp3enc b/sys/man/1/mp3enc new file mode 100755 index 000000000..53b533bb2 --- /dev/null +++ b/sys/man/1/mp3enc @@ -0,0 +1,209 @@ +.TH MP3ENC 1 +.SH NAME +mp3enc \- create mp3 audio files +.SH SYNOPSIS +.in +0.5i +.ti -0.5i +.B games/mp3enc +[ +.B -hprv +] [ +.B -b +.I bitrate +] [ +.B -B +.I bitrate +] [ +.B -m +.I mode +] [ +.B -q +q ] [ +.B -s +.I sfreq +] [ +.B -V +.I q +] [ +.I "long or silly options" +] +.in -0.5i +.SH DESCRIPTION +.I Mp3enc +compresses audio on standard input, +normally PCM-encoded, +and produces MP3-encoded audio on standard output. +By default, the MP3 file will use `constant bit-rate' (CBR) +encoding, but that can be changed via +.B --abr +(average bitrate desired, ABR) +or +.BR -v +(variable bitrate, VBR). +.SS Options +.TF "\fB-b \fP" +.TP +.B -b +set minimum allowed +.I bitrate +in Kb/s for VBR, default 32Kb/s. +For CBR, +set the exact bitrate in Kb/s, which defaults to 128Kb/s. +.TP +.B -B +set maximum allowed +.I bitrate +in Kb/s for VBR, default 256Kb/s. +.TP +.BI -h +same as +.LR "-q 2" . +.TP +.B -m +.I mode +may be +(s)tereo, +(j)oint, +(f)orce +or +(m)ono +(default j). +.B force +forces mid/side stereo on all frames. +.TP +.B -p +add CRC error protection (adds an additional 16 bits per frame to the stream). +This seems to break playback. +.TP +.B -q +sets output quality to +.I q +(see +.BR -V ). +.TP +.B -r +input is raw pcm +.TP +.B -s +set sampling frequency of input file (in KHz) to +.IR sfreq , +default is 44.1. +.TP +.B -v +use variable bitrate (VBR) encoding +.TP +.B -V +set quality setting for VBR to +.IR q . +Default +.I q +is 4; +0 produces highest-quality and largest files, and +9 produces lowest-quality and smallest files. +.SS Long options +.TF "\fB--resample sfreq \fP" +.TP +.BI --abr " bitrate" +sets average +.I bitrate +desired in Kb/s, instead of setting quality, +and generates ABR encoding. +.TP +.BI --resample " sfreq" +set sampling frequency of output file (in KHz) to +.IR sfreq , +default is input sfreq. +.TP +.BI --mp3input +.I input +is an MP3 file +. +.SS Silly options +.TF --nohist +.TP +.BI -f +same as +.LR "-q 7" . +Such a deal. +.TP +.BI -o +mark as non-original (i.e. do not set the original bit) +.TP +.BI -c +mark as copyright +.TP +.BI -k +disable sfb=21 cutoff +.TP +.BI -e " emp" +de-emphasis n/5/c +(default n) +.TP +.BI -d +allow channels to have different blocktypes +.TP +.BI -t +disable Xing VBR informational tag +.TP +.BI -a +autoconvert from stereo to mono file for mono encoding +.TP +.BI -x +force byte-swapping of input (see +.IR dd (1) +instead) +.TP +.BI -S +don't print progress report, VBR histograms +.TP +.BI --athonly +only use the ATH for masking +.TP +.BI --nohist +disable VBR histogram display +.TP +.BI --voice +experimental voice mode +. +.SH EXAMPLES +Encode a +.L .wav +file as highest-quality MP3. +.IP +.EX +games/mp3enc -q 0 -b 320 +.EE +.LP +Create a fixed 128Kb/s MP3 file from a +.L .wav +file. +.IP +.EX +games/mp3enc -h foo.mp3 +.EE +.LP +Streaming from stereo 44.1KHz raw PCM data, encoding mono at 16KHz +(you may not need +.IR dd ): +.IP +.EX +dd -conv swab | games/mp3enc -a -r -m m --resample 16 -b 24 +.EE +.SH SOURCE +.B /sys/src/games/mp3enc +.SH SEE ALSO +.IR dd (1), +.IR mp3dec (1), +.IR audio (3), +.IR cdfs (4), +.IR audio (7), +.IR juke (7), +.IR playlistfs (7) +.br +.B http://www.sulaco.org/mp3 +.SH BUGS +Quality is much better than encoders based on the ISO routines, +but still not as good as the FhG encoder. +.PP +It's a GNU behemoth, lightly rehabilitated. +There are zillions of undocumented options. diff --git a/sys/man/1/ms2html b/sys/man/1/ms2html new file mode 100755 index 000000000..6f4b45dd4 --- /dev/null +++ b/sys/man/1/ms2html @@ -0,0 +1,78 @@ +.TH MS2HTML 1 +.SH NAME +ms2html, html2ms \- convert between troff's ms macros and html +.SH SYNOPSIS +.B ms2html +[ +.B -q +] [ +.B -b +.I basename +] [ +.B -d +.I delims +] [ +.B -t +.I title +] +.br +.B html2ms +.SH DESCRIPTION +.I Ms2html +converts the +.IR ms (6) +source on standard input into HTML and prints it to +standard output. +If the source contains +.IR tbl (1) +or +.IR eqn +input, you must first pipe the text through those +preprocessors. +Postscript images, equations, and tables will be +converted to gif files. +If the document has a +.B .TL +entry, its contents will be used as the title; otherwise +.I ms2html +will look for a +.B ._T +macro, unknown to +.IR ms (6), +and take its value. +Options are: +.TF q +.IP q +suppresses warnings about malformed input; +.IP b +sets the HTML base name to +.IR basename ; +.IP d +sets the +.IR eqn (1) +delimiters to +.IR delim ; +.IP t +sets the HTML title to +.IR title . +.PD +.PP +.I Html2ms +reads HTML from standard input and converts it +to +.IR ms (6) +source on standard output. +.SH SOURCE +.B /sys/src/cmd/ms2html.c +.br +.B /sys/src/cmd/html2ms.c +.SH SEE ALSO +.IR htmlroff (1), +.IR ms (6) +.SH BUGS +.PP +Ms2html doesn't understand a number of troff +commands. It does handle macros and defined +strings. +.PP +Html2ms doesn't understand html tables. diff --git a/sys/man/1/mtime b/sys/man/1/mtime new file mode 100755 index 000000000..5bfe4da32 --- /dev/null +++ b/sys/man/1/mtime @@ -0,0 +1,13 @@ +.TH MTIME 1 +.SH NAME +mtime \- print file modification time +.SH SYNOPSIS +.B mtime +.I file ... +.SH DESCRIPTION +.I Mtime +prints the modification time (in seconds since the epoch) and name +of each +.IR file . +.SH SOURCE +.B /sys/src/cmd/mtime.c diff --git a/sys/man/1/mug b/sys/man/1/mug new file mode 100755 index 000000000..93815fc0b --- /dev/null +++ b/sys/man/1/mug @@ -0,0 +1,56 @@ +.TH MUG 1 +.SH NAME +mug - convert an image to a face icon +.SH SYNOPSIS +.B mug +[ +.I file +] +.SH DESCRIPTION +.I Mug +reads a Plan 9 +.IR image (6) +from +.I file +(or standard input if there is no +.IR file ) +and +displays a working version of the icon +a gray ramp, +and a larger image (the `crop box'), +all derived from +.IR file . +Selecting +.L Write +from the button-3 menu will write the icon in +.IR face (6) +format to standard output. +.LP +Imagine a 3x3 grid on the crop box. You can move an +edge or corner of the box by putting the mouse in the +corresponding section of the grid and dragging. +Dragging in the middle box in the grid translates the +crop box. The mouse cursor changes to tell you where you are. +.LP +The bar in the gray ramp controls the map from picture +gray levels to the output levels. The values along the +bar are mapped to 0 through 255 in the output. You can +move the bar vertically by grabbing the midsection or +adjust the width by grabbing an endpoint. +.LP +The current icon is shown in the bottom left corner, +surrounded by eight small empty boxes. You can save the +settings as they are by dragging the current icon into +one of the other boxes. You can restore the settings by +dragging an icon from one of the periphery boxes into the middle. +.SH EXAMPLES +Convert a JPEG image into a face icon. +.IP +.EX +jpg -c plus.jpg | mug >plus.1 +.EE +.SH SEE ALSO +.IR faces (1), +.IR jpg (1), +.IR face (6), +.IR image (6) diff --git a/sys/man/1/nedmail b/sys/man/1/nedmail new file mode 100755 index 000000000..6cf29cc39 --- /dev/null +++ b/sys/man/1/nedmail @@ -0,0 +1,340 @@ +.TH NEDMAIL 1 +.SH NAME +nedmail \- reading mail +.SH SYNOPSIS +.B upas/nedmail +[ +.B -nr +] +[ +.B -f +.I mailfile +] +[ +.B -s +.I mailfile +] +.PP +.B upas/nedmail +.B -c +.I dir +.SH DESCRIPTION +.I Nedmail +edits a mailbox. +The default mailbox is +.BI /mail/box/ username /mbox\f1. +The +.B -f +command line option specifies an alternate mailbox. +Unrooted path names are interpreted relative to +.BI /mail/box/ username. +If the +.I mailfile +argument is omitted, the name defaults to +.BR stored . +.PP +The options are: +.TF "-f mailfile" +.TP +.BI -c " dir +Create a mailbox. If +.I dir +is specified, the new mailbox is created in +.BI /mail/box/ username / dir /mbox\f1. +Otherwise, the default mailbox is created. +.TP +.B -r +Reverse: show messages in first-in, first-out order; the default is last-in, first-out. +.TP +.B -n +Make the message numbers the same as the file names in the mail +box directory. This implies the +.B -r +option. +.TP +.BI -f " mailfile" +Read messages from the specified file (see above) instead of the default mailbox. +.TP +.BI -s " mailfile" +Read a single message file +.IR mailfile , +as produced by +.IR fs , +and treat it as an entire mailbox. +This is provided for +use in plumbing rules; see +.IR faces (1). +.PD +.PP +.I Nedmail +starts by reading the mail box, printing out the number +of messages, and then prompting for commands from standard input. +Commands, as in +.IR ed (1), +are of the form +.RI `[ range ] +.I command +.RI [ arguments ]'. +The command is applied to each message in the (optional) range. +.PP +The address range can be: +.TP 1.4i +.I address +to indicate a single message header +.PD 0 +.TP +.IB address , address +to indicate a range of contiguous message headers +.TP +.BI g/ expression / +to indicate all messages whose headers match the regular +.IR expression . +.TP +.BI g% expression % +to indicate all messages whose contents match the regular +.IR expression . +.PD +.PP +The addresses can be: +.TP 1.4i +.I number +to indicate a particular message +.PD 0 +.TP +.IB address . number +to indicate a subpart of a particular message +.TP +.BI / expression / +to indicate the next message whose header matches +.I expression +.TP +.BI % expression % +to indicate the next message whose contents match +expression +.TP +.I "empty or . +to indicate the current message +.TP +.BI - address +to indicate backwards search or movement +.PD +.PP +Since messages in MIME are hierarchical +structures, in +.I nedmail +all the subparts are individually addressable. +For example if message 2 contains 3 attachments, +the attachments are numbered 2.1, 2.2, and 2.3. +.PP +The commands are: +.TP 1.1i +.BI a " args +Reply to all addresses in the +.BR To: , +.BR From: , +and +.BR Cc: +header lines. +.I Marshal +is used to format the reply and any arguments the +user specifies are added to the command line to +.I marshal +before the recipient. +The possibility of making a fool of yourself is very +high with this command. +.PD 0 +.TP +.BI A " args +Like +.B a +but with the message +appended to the reply. +.TP +.B b +Print the headers for the next ten messages. +.TP +.B d +Mark message to be deleted upon exiting +.IR nedmail . +.TP +.B f +Append the message to the file +.BI /mail/box/ username / sendername +where +.I sendername +is the account name of the sender. +.TP +.B h +Print the disposition, size in characters, reception time, sender, +and subject of the message. +.TP +.B H +Print the MIME structure of the message. +.TP +.B help +Print a summary of the commands. +.TP +.BI m " person ... +Forward the message as a mime attachment to the named +.IR persons . +.TP +.BI M " person ... +Like +.B m +but allow the user to type in text to be included +with the forwarded message. +.TP +.B p +Print message. An interrupt stops the printing. +.TP +.BI r " args +Reply to the sender of the message. +.I Marshal +is used to format the reply. +If and optional +.I Args +are specified, they are added to the command line to +.I marshal +before the recipient's address. +.TP +.B R " args +Like +.B r +but with the original message included as an attachment. +.TP +.B rf +Like +.B r +but append the message and the reply to the file +.BI /mail/box/ username / sendername +where +.I sendername +is the account name of the sender. +.TP +.B Rf +Like +.B R +but append the message and the reply to the file +.BI /mail/box/ username / sendername +where +.I sendername +is the account name of the sender. +.TP +.BI s " mfile" +Append the message to the specified mailbox. +If +.I mfile +doesn't start with a `/', it is interpreted relative to the directory in which the mailbox resides. +If +.I mfile +is a directory then the destination is a file in that directry. +If the MIME header specifies a file name, that one is used. +Otherwise, one is generated using +.IR mktemp (2) +and the string +.BR att.XXXXXXXXXXX . +.TP +.B q +Put undeleted mail back in the mailbox and stop. +.TP +EOT (control-D) +Same as +.BR q . +.TP +.BI w " file +Same as +.B s +with the mail header line(s) stripped. This can be used to +save binary mail bodies. +.TP +.B u +Remove mark for deletion. +.TP +.B x +Exit, without changing the mailbox file. +.TP +.B y +Synchronize with the mail box. Any deleted +messages are purged and any new messages read. +This is equivalent to quiting nedmail and restarting. +.TP +.BI | command +Run the +.I command +with the message body as standard input. +.TP +.BI || command +Run the +.I command +with the whole message as standard input. +.TP +.BI ! command +Escape to the shell to do +.IR command . +.TP +.B \&= +Print the number of the current message. +.PD +.PP +Here's an example of a mail session that looks at a summary +of the mail messages, saves away an html file added as an +attachment to a message and then deletes the message: +.LP +.EX +% mail +7 messages +: ,h +1 H 2129 07/22 12:30 noone@madeup.net "Add Up To 2000 free miles" +2 504 07/22 11:43 jmk +3 H 784 07/20 09:05 presotto +4 822 07/11 09:23 xxx@yyy.net "You don't call, you don't write..." +5 193 07/06 16:55 presotto +6 529 06/01 19:42 jmk +7 798 09/02 2000 howard +: 1H +1 multipart/mixed 2129 from=noone@madeup.net + 1.1 text/plain 115 + 1.2 text/html 1705 filename=northwest.htm +: 1.2w /tmp/northwest.html +!saved in /tmp/northwest.html +1.2: d +1: q +!1 message deleted +% +.EE +.PP +Notice that the delete of message 1.2 deleted the entire message and +not just the attachment. +.SH FILES +.TF /mail/box/*/dead.letter +.TP +.B /mail/box/* +mail directories +.TP +.B /mail/box/*/mbox +mailbox files +.TP +.B /mail/box/*/forward +forwarding address(es) +.TP +.B /mail/box/*/pipeto +mail filter +.TP +.B /mail/box/*/L.reading +mutual exclusion lock for multiple mbox readers +.TP +.B /mail/box/*/L.mbox +mutual exclusion lock for altering mbox +.SH SOURCE +.B /sys/src/cmd/upas/ned +.SH "SEE ALSO" +.IR mail (1), +.IR aliasmail (8), +.IR filter (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR upasfs (4), +.IR smtp (8), +.IR faces (1), +.IR rewrite (6) diff --git a/sys/man/1/netstat b/sys/man/1/netstat new file mode 100755 index 000000000..817e763f1 --- /dev/null +++ b/sys/man/1/netstat @@ -0,0 +1,51 @@ +.TH NETSTAT 1 +.SH NAME +netstat \- summarize network connections +.SH SYNOPSIS +.B netstat +[ +.B -in +] [ +.B -p +.I proto +] [ +.I netmtpt +] +.SH DESCRIPTION +.I Netstat +prints information about network mounted at +.IR netmtpt , +default +.BR /net . +For +.I IP +connections, +.I netstat +reports the protocol, connection number, user, +connection state, local port, remote port and +remote address. +.PP +The options are: +.TP +.B -i +Instead of the usual listing, print one line per network interface. +Each line gives the +device, MTU, local address, mask, remote address, packets in, +packets out, errors in, and errors out for this interface. +.TP +.B -n +By default, +.I netstat +looks up port numbers and addresses in the network databases +to print symbolic names if possible. +This option disables such translation. +.TP +.B -p +Show only connections with the given protocol. +.PD +.SH FILES +.B /net/*/* +.SH SOURCE +.B /sys/src/cmd/netstat.c +.SH "SEE ALSO" +.IR ipconfig (8) diff --git a/sys/man/1/news b/sys/man/1/news new file mode 100755 index 000000000..f95b987f3 --- /dev/null +++ b/sys/man/1/news @@ -0,0 +1,63 @@ +.TH NEWS 1 +.SH NAME +news \- print news items +.SH SYNOPSIS +.B news +[ +.B -a +] +[ +.B -n +] +[ +.I item ... +] +.SH DESCRIPTION +When invoked without options, +this simple local news service +prints files that have appeared in +.BR /lib/news +since last reading, most recent first, +with each preceded by an appropriate header. +The time of reading is recorded. +The options are +.TP +.B -a +Print all items, regardless of currency. +The recorded time is not changed. +.TP +.B -n +Report the names of the current items without +printing their contents, and without changing +the recorded time. +.PP +Other arguments +select particular news items. +.PP +To post a news item, create a file in +.BR /lib/news . +.PP +You may arrange to receive news automatically by +registering your mail address in +.BR /sys/lib/subscribers . +A daemon mails recent news +to all addresses on the list. +.PP +Empty news items, and news items named +.B core +or +.B dead.letter +are ignored. +.SH FILES +.TF \fL/sys/lib/subscribers +.TP +.B /lib/news/* +articles +.TP +.B $HOME/lib/newstime +modify time is time news was last read +.TP +.B /sys/lib/subscribers +who gets news mailed to them +.SH SOURCE +.B /sys/src/cmd/news.c diff --git a/sys/man/1/nm b/sys/man/1/nm new file mode 100755 index 000000000..a77480180 --- /dev/null +++ b/sys/man/1/nm @@ -0,0 +1,107 @@ +.TH NM 1 +.SH NAME +nm \- name list (symbol table) +.SH SYNOPSIS +.B nm +[ +.B -aghnsTu +] +.I file ... +.SH DESCRIPTION +.I Nm +prints the name list of each executable or object +.I file +in the argument list. +If the +.I file +is an archive +(see +.IR ar (1)), +the name list of each file in the archive is printed. +If more than one file is given in the argument list, +the name of each file is printed at the beginning of each line. +.PP +Each symbol name is preceded by its hexadecimal +value (blanks if undefined) +and one of the letters +.TP +.B T +text segment symbol +.PD0 +.TP +.B t +static text segment symbol +.TP +.B L +leaf function text segment symbol +.TP +.B l +static leaf function text segment symbol +.TP +.B D +data segment symbol +.TP +.B d +static data segment symbol +.TP +.B B +bss segment symbol +.TP +.B b +static bss segment symbol +.TP +.B a +automatic (local) variable symbol +.TP +.B p +function parameter symbol +.TP +.B z +source file name +.TP +.B Z +source file line offset +.TP +.B f +source file name components +.PD +.PP +The output is sorted alphabetically. +.PP +Options are: +.TP +.B -a +Print all symbols; normally only user-defined text, data, +and bss segment symbols are printed. +.TP +.B -g +Print only global +.RB ( T , +.BR L , +.BR D , +.BR B ) +symbols. +.TP +.B -h +Do not print file name headers with output lines. +.TP +.B -n +Sort according to the address of the symbols. +.TP +.B -s +Don't sort; print in symbol-table order. +.TP +.B -T +Prefix each line with the symbol's type signature. +.TP +.B -u +Print only undefined symbols. +.SH SOURCE +.B /sys/src/cmd/nm.c +.SH SEE ALSO +.IR ar (1), +.IR 2l (1), +.IR db (1), +.IR acid (1), +.IR a.out (6) + diff --git a/sys/man/1/ns b/sys/man/1/ns new file mode 100755 index 000000000..b62398abc --- /dev/null +++ b/sys/man/1/ns @@ -0,0 +1,44 @@ +.TH NS 1 +.SH NAME +ns \- display name space +.SH SYNOPSIS +.B ns +[ +.B -r +] [ +.I pid +] +.SH DESCRIPTION +.I Ns +prints a representation of the file name space of the process with the named +.IR pid , +or by default itself. +The output is in the form of an +.IR rc (1) +script that could, in principle, recreate the name space. +The output is produced by reading and reformatting the contents of +.BI /proc/ pid /ns . +.PP +By default, +.I ns +rewrites the names of network data files to represent the network +address that data file is connected to, for example replacing +.B /net/tcp/82/data +with +.BR tcp!123.122.121.9 . +The +.B -r +flag suppresses this rewriting. +.SH FILES +.B /proc/*/ns +.SH SOURCE +.B /sys/src/cmd/ns.c +.SH "SEE ALSO" +.IR ps (1), +.IR proc (3), +.IR namespace (4), +.IR namespace (6) +.SH BUGS +The names of files printed by +.I ns +will be inaccurate if a file or directory it includes has been renamed. diff --git a/sys/man/1/p b/sys/man/1/p new file mode 100755 index 000000000..d3287599b --- /dev/null +++ b/sys/man/1/p @@ -0,0 +1,33 @@ +.TH P 1 +.SH NAME +p \- paginate +.SH SYNOPSIS +.B p +[ +.BI - number +] +[ +.I file ... +] +.SH DESCRIPTION +.I P +copies its standard input, or the named files if given, +to its standard output, +stopping at the end of every 22nd line, and between files, +to wait for a newline from the user. +The option sets the +.I number +of lines on a page. +.PP +While waiting for a newline, +.I p +interprets the commands: +.TP +.B ! +Pass the rest of the line to the shell as a command. +.TP +.B q +Quit. +.PP +.SH SOURCE +.B /sys/src/cmd/p.c diff --git a/sys/man/1/page b/sys/man/1/page new file mode 100755 index 000000000..4246080c0 --- /dev/null +++ b/sys/man/1/page @@ -0,0 +1,271 @@ +.TH PAGE 1 +.SH NAME +page \- view +FAX, +image, graphic, PostScript, PDF, and +typesetter output +files +.SH SYNOPSIS +.B page +[ +.B -abirPRvVw +] +[ +.B -p +.I ppi +] +[ +.IR file ... +] +.SH DESCRIPTION +.I Page +is a general purpose document viewer. +It can be used to display the individual pages +of a +PostScript, +PDF, +or +.IR tex (1) +or +.IR troff (1) +device independent output +file. +.I Tex +or +.I troff +output is simply converted to PostScript in order to be viewed. +It can also be used to view any number of +graphics files +(such as a +FAX +page, +a Plan 9 +.IR image (6) +file, an Inferno bitmap file, or other common format). +.I Page +displays these +in sequence. +In the absence of named files, +.I page +reads one from standard input. +.PP +By default, +.I page +runs in the window in which it is started +and leaves the window unchanged. +The +.B -R +option causes +.I page +to grow the window if necessary +to display the page being viewed. +The +.B -w +option causes +.I page +to create a new window for itself. +The newly created window will grow as under the +.B -R +option. +If being used to display +multipage documents, +only one file may be specified on the command line. +.PP +The +.B -p +option sets the resolution for PostScript and PDF +files, in pixels per inch. +The default is 100 ppi. +The +.B -r +option reverses the order in which pages are displayed. +.PP +When viewing a document, +.I page +will try to guess the true bounding box, usually rounding up from +the file's bounding box to +8½×11 or A4 size. +The +.B -b +option causes it to respect the bounding box given in the file. +As a more general problem, +some PostScript files claim to conform to Adobe's +Document Structuring Conventions but do not. +The +.B -P +option enables a slightly slower and slightly more +skeptical version of the PostScript processing code. +Unfortunately, there are PostScript documents +that can only be viewed with the +.B -P +option, and there are PostScript documents that +can only be viewed without it. +.PP +When viewing images with +.IR page , +it listens to the +.B image +plumbing channel +(see +.IR plumber (4)) +for more images to display. +The +.B -i +option causes +.I page +to not load any graphics files nor to read +from standard input but rather to listen +for ones to load from the plumbing channel. +.PP +The +.B -v +option turns on extra debugging output, and +the +.B -V +option turns on even more debugging output. +The +.B -a +option causes +.I page +to call +.IR abort (2) +rather than exit cleanly on errors, +to facilitate debugging. +.PP +Pressing and holding button 1 permits panning about the page. +.PP +Button 2 raises a menu of operations on the current image or the +entire set. The image transformations are non-destructive and are +valid only for the currently displayed image. They are lost as soon +as another image is displayed. +The button 2 menu operations are: +.TF Resize +.TP +.B Orig size +Restores the image to the original. All modifications are lost. +.TP +.B Zoom +Prompts the user to sweep a rectangle on the image which is +expanded proportionally to the rectangle. +.TP +.B Fit window +Resizes the image so that it fits in the current window. +.TP +.B Rotate 90 +Rotates the image 90 degrees clockwise +.TP +.B Upside down +Toggles whether images are displayed upside-down. +.TP +.B Next +Displays the next page. +.TP +.B Prev +Displays the previous page. +.TP +.B Zerox +Displays the current image in a new page window. +Useful for selecting important pages from large documents. +.TP +.B Reverse +Reverses the order in which pages are displayed. +.TP +.B Write +Writes the image to file. +.PD +.PP +Button 3 raises a menu of the +pages +to be selected for viewing in any order. +.PP +Typing a +.B q +or +control-D exits the program. +Typing a +.B u +toggles whether images are displayed upside-down. +(This is useful in the common case of mistransmitted upside-down faxes). +Typing a +.B r +reverses the order in which pages are displayed. +Typing a +.B w +will write the currently viewed page to a new file as a compressed +.IR image (6) +file. +When possible, the filename is of the form +.IR basename . pagenum . bit . +Typing a +.B d +removes an image from the working set. +.PP +To go to a specific page, one can type its number followed by enter. +Typing left arrow, backspace, or minus displays the previous page. +Typing right arrow, space, or enter displays the next page. +The up and down arrow pan up and down one half screen height, +changing pages when panning off the top or bottom of the page. +.PP +.I Page +calls +.IR gs (1) +to draw each page of PostScript +and +PDF +.IR files . +It also calls a variety of conversion programs, such as those described in +.IR jpg (1), +to convert the various raster graphics formats +into Inferno bitmap files. +Pages are converted ``on the fly,'' as needed. +.SH EXAMPLES +.TP +.L +page /sys/src/cmd/gs/examples/tiger.eps +Display a color PostScript file. +.TP +.L +page /usr/inferno/icons/*.bit +Browse the Inferno bitmap library. +.TP +.L +man -t page | page -w +Preview this manual in a new window. +.SH "SEE ALSO +.IR gs (1), +.IR jpg (1), +.IR tex (1), +.IR troff (1) +.SH SOURCE +.B /sys/src/cmd/page +.SH DIAGNOSTICS +The mouse cursor changes to an arrow and ellipsis +when +.I page +is reading or writing a file. +.SH BUGS +.I Page +supports reading of only one document +file at a time, and +the user interface is clumsy when viewing very large documents. +.PP +When viewing multipage PostScript files that do not contain +.RB `` %%Page '' +comments, the button 3 menu only contains +``this page'' and ``next page'': +correctly determining +page boundaries in Postscript code is not computable +in the general case. +.PP +If +.I page +has trouble viewing a Postscript file, +it might not be exactly conforming: try viewing it with the +.B -P +option. +.PP +The interface to the plumber is unsatisfactory. In particular, +document references cannot be sent +via plumbing messages. +.PP +There are too many keyboard commands. diff --git a/sys/man/1/passwd b/sys/man/1/passwd new file mode 100755 index 000000000..d15461e3b --- /dev/null +++ b/sys/man/1/passwd @@ -0,0 +1,59 @@ +.TH PASSWD 1 +.SH NAME +passwd, netkey \- change or verify user password +.SH SYNOPSIS +.B passwd +[ +.IR username [@ domain ] +] +.PP +.B netkey +.SH DESCRIPTION +.I Passwd +changes the invoker's Plan 9 password and/or APOP secret. +The Plan 9 password is used to login to a terminal while +the APOP secret is used for a number of external services: +POP3, IMAP, and VPN access. The optional argument specifies +the user name and authentication domain to use if different +than the one associated with the machine +.I passwd +is run on. +.PP +The program first prompts for the old Plan 9 password in the specified +domain to establish +identity. +It then prompts for changes to the password and the +secret. +New passwords and secrets must be typed twice, to forestall mistakes. +New passwords must be sufficiently hard to guess. +They may be of any length greater than seven characters. +.PP +.I Netkey +prompts for a password to encrypt network challenges. +It is a substitute for a SecureNet box. +.PP +These commands may be run only on a terminal, to avoid +transmitting clear text passwords over the network. +.SH SOURCE +.B /sys/src/cmd/auth/passwd.c +.br +.B /sys/src/cmd/auth/netkey.c +.SH "SEE ALSO" +.I readnvram +in +.IR authsrv (2), +.IR encrypt (2), +.IR cons (3), +.IR auth (8), +.IR securenet (8) +.PP +Robert Morris and Ken Thompson, +``UNIX Password Security,'' +.I AT&T Bell Laboratories Technical Journal +Vol 63 (1984), pp. 1649-1672 +.SH BUGS +Now that +.I cpu +connections are always encrypted, the only good reason +to require that these commands be run only on terminals +is concern that the CPU server might be subverted. diff --git a/sys/man/1/patch b/sys/man/1/patch new file mode 100755 index 000000000..3fb4a490c --- /dev/null +++ b/sys/man/1/patch @@ -0,0 +1,158 @@ +.TH PATCH 1 +.SH NAME +patch \- simple patch creation and tracking system +.SH SYNOPSIS +.B patch/create +.I name +.I email +.I files ... +[ +.B < +.I description +] +.PP +.B patch/list +[ +.I name ... +] +.PP +.B patch/diff +.I name +.PP +.B patch/apply +.I name +.PP +.B patch/undo +.I name +.PP +.B patch/note +.I name +[ +.B < +.I note +] +.SH DESCRIPTION +These scripts are a simple patch submission and tracking system +used to propose additions or changes to Plan 9. +There is no guarantee that any patch will be accepted, nor +that it will be accepted verbatim. +Each patch has a +.I name +(lowercase letters, numbers, dash, dot, and underscore only) +and is stored in +.BI /n/sources/patch/ name. +.PP +.I Patch/create +creates a new patch consisting of the changes to +the listed files from the distribution, reading +a description of the patch from standard input: +please provide an explanation of what the change is supposed to do, +some context, and a rationale for the change. +Test data or pointers to same to verify that the fix works are also welcome. +When sending a patch, follow these guidelines: +.IP • 3 +Before preparing the patch, run +.I replica/pull +and base your patch on current distribution source code. +.IP • +If this is a bug fix, explain the bug clearly. +Don't assume the bug is obvious from the fix. +.IP • +If this is a new feature, explain it clearly. +Don't assume it is obvious from the change. +.IP • +Make the new code look as much like the old code as possible: +don't make gratuitous changes, and do follow the style of the old code. +See +.IR style (6) +for the canonical Plan 9 coding style. +.IP • +If your patch changes externally-visible behaviour, +update the manual page. +.PP +The +.I email +address, if not +.LR - , +will be sent notification messages when the patch is applied, rejected, +or commented on. +If rejected, the e-mail will contain a note explaining why and +probably listing suggested changes and encouraging you to resubmit. +.PP +.I Patch/list +displays information about the named patches, +or all currently pending patches if none are specified. +.PP +.I Patch/diff +shows a patch as diffs between the original +source files and the patched source files. +.PP +.I Patch/apply +applies the patch to the current source tree. +It is intended to be run by the Plan 9 developers with +.B pie +as their root file system. +If the source has changed since the patch was +created, +.I apply +will report the conflict and not change any files. +Before changing any files, +.I patch/apply +makes backup copies of the current source tree's +files. The backups are stored in the patch directory. +.PP +.I Patch/undo +will copy the backups saved by +.I patch/apply +back into the source tree. +It will not restore a backup if the file +being replaced is not byte-identical to the one +created by +.I patch/apply. +.SH EXAMPLES +Propose a change to +.IR pwd , +which you have modified locally: +.IP +.EX +% patch/create pwd-errors user@host.dom /sys/src/cmd/pwd.c +Fix pwd to print errors to fd 2 rather than 1. +^D +% +.EE +.PP +Then the developers at Bell Labs run +.IP +.EX +patch/diff pwd-errors +.EE +.PP +to inspect the change (possibly viewing +.B /n/sources/patch/pwd-errors/pwd.c +to see the larger context). +To make the change, they run +.IP +.EX +patch/apply pwd-errors +.EE +.LP +Otherwise they run +.IP +.EX +% patch/note pwd-errors +Pwd should definitely print errors to fd 1 because ... +^D +% +.EE +.PP +to add a note to the +.B /n/sources/pwd-errors/notes +file. +.SH FILES +.B /n/sources/patch +.SH SOURCE +.B /rc/bin/patch +.SH SEE ALSO +.IR diff (1) +.br +.B http://plan9.bell-labs.com/wiki/plan9/How_to_contribute diff --git a/sys/man/1/pcc b/sys/man/1/pcc new file mode 100755 index 000000000..fd7acd916 --- /dev/null +++ b/sys/man/1/pcc @@ -0,0 +1,185 @@ +.TH PCC 1 +.SH NAME +pcc \- APE C compiler driver +.SH SYNOPSIS +.B pcc +[ +.I option ... +] +[ +.I name ... +] +.SH DESCRIPTION +.I Pcc +compiles and loads C programs, +using APE (ANSI C/POSIX) include files and libraries. +Named files ending with +.B .c +are preprocessed with +.IR cpp (1), +then compiled with one of the compilers described in +.IR 2c (1), +as specified by the environment variable +.BR $objtype . +The object files are then loaded using one of the loaders described in +.IR 2l (1). +The options are: +.TP \w'\fL-D\ \fIname=def\ 'u +.B "-+ +Accept C++ +.B // +comments. +.TP +.BI -o " out" +Place loader output in file +.I out +instead of the default +.BR 2.out , +.BR v.out , +etc. +.TP +.B -P +Omit the compilation and loading phases; +leave the result of preprocessing +.IB name .c +in +.IB name .i\f1. +.TP +.B -E +Like +.BR -P , +but send the result to standard output. +.TP +.B -c +Omit the loading phase. +.TP +.B -p +Insert profiling code into the executable output. +.TP +.B -w +Print compiler warning messages. +.TP +.BI -l lib +Include +.BI / $objtype /lib/ape/lib lib .a +as a library during the linking phase. +.TP +.B -B +Don't complain about functions used without +ANSI function prototypes. +.TP +.B -V +Enable +.B void* +conversion warnings, as in +.IR 2c (1). +.TP +.B -v +Echo the preprocessing, compiling, and loading commands +before they are executed. +.TP +.BI -D name=def +.br +.ns +.TP +.BI -D name +Define the +.I name +to the preprocessor, +as if by +.LR #define . +If no definition is given, the name is defined as +.LR 1 . +.TP +.BI -U name +Undefine the +.I name +to the preprocessor, +as if by +.LR #undef . +.TP +.BI -I dir +.L #include +files whose names do not begin with +.L / +are always +sought first in the directory +of the +.I file +argument, +then in directories named in +.B -I +options, +then in +.BR /$objtype/include/ape . +.TP +.B -N +Don't optimize compiled code. +.TP +.B -S +Print an assembly language version of the object code +on standard output. +.TP +.B -a +Instead of compiling, print on standard output acid functions (see +.IR acid (1)) +for examining structures declared in the source files. +.TP +.B -aa +Like +.B -a +except that functions for structures declared in included header files +are omitted. +.TP +.B -F +Enable vararg type checking as described in +.IR 2c (1). +This is of limited use without the appropriate +.B #pragma +definitions. +.PP +The APE environment contains all of the include +files and library routines specified in the ANSI C standard +(X3.159-1989), as well as those specified in the IEEE Portable +Operating System Interface standard (POSIX, 1003.1-1990, ISO 9945-1). +In order to access the POSIX routines, source programs should +define the preprocessor constant +.BR _POSIX_SOURCE . +.SH FILES +.TF /$objtype/lib/ape/libap.a +.TP +.B /sys/include/ape +directory for machine-independent +.B #include +files. +.TP +.B /$objtype/include/ape +directory for machine-dependent +.B #include +files. +.TP +.B /$objtype/lib/ape/libap.a +ANSI C/POSIX library. +.SH "SEE ALSO" +.IR cpp (1), +.IR 2c (1), +.IR 2a (1), +.IR 2l (1), +.IR mk (1), +.IR nm (1), +.IR acid (1), +.IR db (1), +.IR prof (1) +.PP +Howard Trickey, +``APE \(em The ANSI/POSIX Environment'' +.SH SOURCE +.B /sys/src/cmd/pcc.c +.SH BUGS +The locale manipulation functions are minimal. +Signal functions and terminal characteristic +handlers are only minimally implemented. +.IR Link +always fails, because Plan 9 doesn't support multiple links to a file. +The functions related to setting effective user and group ids +cannot be implemented because the concept doesn't exist in Plan 9. diff --git a/sys/man/1/pic b/sys/man/1/pic new file mode 100755 index 000000000..685de68fc --- /dev/null +++ b/sys/man/1/pic @@ -0,0 +1,344 @@ +.TH PIC 1 +.de PS \" start picture +. \" $1 is height, $2 is width, both in inches +.if \\$1>0 .sp .35 +.ie \\$1>0 .nr $1 \\$1 +.el .nr $1 0 +.in (\\n(.lu-\\$2)/2u +.ne \\$1 +.. +.de PE \" end of picture +.in +.if \\n($1>0 .sp .65 +.. +.SH NAME +pic, tpic \- troff and tex preprocessors for drawing pictures +.SH SYNOPSIS +.B pic +[ +.I files +] +.PP +.B tpic +[ +.I files +] +.SH DESCRIPTION +.I Pic +is a +.IR troff (1) +preprocessor for drawing figures on a typesetter. +.I Pic +code is contained between +.B .PS +and +.B .PE +lines: +.IP +.EX +\&.PS \f2optional-width\fP \f2optional-height\fP +\f2element-list\fP +\&.PE +.EE +.LP +or in a file mentioned in a +.B .PS +line: +.IP +.BI .PS " " < file +.LP +If +.IR optional-width +is present, the picture is made that many inches wide, +regardless of any dimensions used internally. +The height is scaled in the same proportion unless +.IR optional-height +is present. +If +.B .PF +is used instead of +.BR .PE , +the typesetting position after printing is restored to what it was +upon entry. +.PP +An +.IR element-list +is a list of elements: +.EX + \f2primitive attribute-list\fP + \f2placename\fP : \f2element\fP + \f2placename\fP : \f2position\fP + \f2var\fP = \f2expr\fP + \f2direction\fP + { \f2element-list\fP } + [ \f2element-list\fP ] + for \f2var\fP = \f2expr\fP to \f2expr\fP by \f2expr\fP do { \f2anything\fP } + if \f2expr\fP then { \f2anything\fP } else { \f2anything\fP } + copy \f2file,\fP copy thru \f2macro,\fP copy \f2file\fP thru \fPmacro\fP + sh { \f2commandline\fP } + print \f2expr\fP + reset \f2optional var-list\fP + \f2troff-command\fP +.EE +.PP +Elements are separated by newlines or semicolons; +a long element may be continued by ending the line with a backslash. +Comments are introduced by a +.BI # +and terminated by a newline. +Variable names begin with a lower case letter; +place names begin with upper case. +Place and variable names retain their values +from one picture to the next. +.PP +After each primitive +the current position moves in the current direction +.RB ( up , down , +.BR left , right +(default)) by the size of the primitive. +The current position and direction are saved upon entry +to a +.BR { ... } +block and restored upon exit. +Elements within a block enclosed in +.BR [ ... ] +are treated as a unit; +the dimensions are determined by the extreme points +of the contained objects. +Names, variables, and direction of motion within a block are local to that block. +.PP +.IR Troff-command +is any line that begins with a period. +Such a line is assumed to make sense in the context where it appears; +generally, this means only size and font changes. +.PP +The +.I primitive +objects are: +.br +.EX + box circle ellipse arc line arrow spline move \f2text-list\fP +.EE +.L arrow +is a synonym for +.LR "line ->" . +.PP +An +.IR attribute-list +is a sequence of zero or more attributes; +each attribute consists of a keyword, perhaps followed by a value. +.EX +.ta .5i 2.5i + h(eigh)t \f2expr\fP wid(th) \f2expr\fP + rad(ius) \f2expr\fP diam(eter) \f2expr\fP + up \f2opt-expr\fP down \f2opt-expr\fP + right \f2opt-expr\fP left \f2opt-expr\fP + from \f2position\fP to \f2position\fP + at \f2position\fP with \f2corner\fP + by \f2expr, expr\fP then + dotted \f2opt-expr\fP dashed \f2opt-expr\fP + chop \f2opt-expr\fP -> <- <-> + invis same + fill \f2opt-expr\fP + \f2text-list\fP \f2expr\fP +.EE +Missing attributes and values are filled in from defaults. +Not all attributes make sense for all primitives; +irrelevant ones are silently ignored. +The attribute +.L at +causes the geometrical center to be put at the specified place; +.L with +causes the position on the object to be put at the specified place. +For lines, splines and arcs, +.L height +and +.L width +refer to arrowhead size. +A bare +.I expr +implies motion in the current direction. +.PP +Text is normally an attribute of some primitive; +by default it is placed at the geometrical center of the object. +Stand-alone text is also permitted. +A text list +is a list of text items: +.EX +\f2 text-item\fP: + "..." \f2positioning ...\fP + sprintf("\f2format\fP", \f2expr\fP, \f2...\fP) \f2positioning ...\fP +\f2 positioning\fP: + center ljust rjust above below +.EE +If there are multiple text items for some primitive, +they are arranged vertically and centered except as qualified. +Positioning requests apply to each item independently. +Text items may contain +.I troff +commands for size and font changes, local motions, etc., +but make sure that these are balanced +so that the entering state is restored before exiting. +.PP +A position is ultimately an +.I x,y +coordinate pair, but it may be specified in other ways. +.EX +\f2 position\fP: + \f2expr, expr\fP + \f2place\fP ± \f2expr, expr\fP + \f2place\fP ± ( \f2expr, expr\fP ) + ( \f2position\fP,\f2 position\fP ) \f2x\fP\fR from one, \f2y\fP\fR the other\fP + \f2expr\fP [\fLof the way\fP] between \f2position\fP and \f2position\fP + \f2expr\fP < \f2position\fP , \f2position\fP > + ( \f2position\fP ) +.EE +.PP +.EX +\f2 place\fP: + \f2placename\fP \f2optional-corner\fP + \f2corner\fP of \f2placename\fP + \f2nth\fP \f2primitive\fP \f2optional-corner\fP + \f2corner\fP of \f2nth\fP \f2primitive\fP + Here +.EE +An +.IR optional-corner +is one of the eight compass points +or the center or the start or end of a primitive. +.EX +\f2 optional-corner\fP: + .n .e .w .s .ne .se .nw .sw .c .start .end +\f2 corner\fP: + top bot left right start end +.EE +Each object in a picture has an ordinal number; +.IR nth +refers to this. +.EX +\f2 nth\fP: + \f2n\fPth\f2, n\fPth last +.EE +.PP +The built-in variables and their default values are: +.EX +.ta .5i 2.5i + boxwid 0.75 boxht 0.5 + circlerad 0.25 arcrad 0.25 + ellipsewid 0.75 ellipseht 0.5 + linewid 0.5 lineht 0.5 + movewid 0.5 moveht 0.5 + textwid 0 textht 0 + arrowwid 0.05 arrowht 0.1 + dashwid 0.1 arrowhead 2 + scale 1 +.EE +These may be changed at any time, +and the new values remain in force from picture to picture until changed again +or reset by a +.L reset +statement. +Variables changed within +.B [ +and +.B ] +revert to their previous value upon exit from the block. +Dimensions are divided by +.B scale +during output. +.PP +Expressions in +.I pic +are evaluated in floating point. +All numbers representing dimensions are taken to be in inches. +.EX +\f2 expr\fP: + \f2expr\fP \f2op\fP \f2expr\fP + - \f2expr\fP + ! \f2expr\fP + ( \f2expr\fP ) + variable + number + \f2place\fP .x \f2place\fP .y \f2place\fP .ht \f2place\fP .wid \f2place\fP .rad + sin(\f2expr\fP) cos(\f2expr\fP) atan2(\f2expr,expr\fP) log(\f2expr\fP) exp(\f2expr\fP) + sqrt(\f2expr\fP) max(\f2expr,expr\fP) min(\f2expr,expr\fP) int(\f2expr\fP) rand() +\f2 op\fP: + + - * / % < <= > >= == != && || +.EE +.PP +The +.B define +and +.B undef +statements are not part of the grammar. +.EX + define \f2name\fP { \f2replacement text\fP } + undef \f2name\fP +.EE +Occurrences of +.BR $1 , +.BR $2 , +etc., +in the replacement text +will be replaced by the corresponding arguments if +.I name +is invoked as +.EX + \f2name\fP(\f2arg1\fP, \f2arg2\fP, ...) +.EE +Non-existent arguments are replaced by null strings. +Replacement text +may contain newlines. +The +.B undef +statement removes the definition of a macro. +.PP +.I Tpic +is a +.IR tex (1) +preprocessor that accepts +.IR pic +language. +It produces Tex commands that define a box called +.BR \egraph , +which contains the picture. +The box may be output this way: +.IP +.L +\ecenterline{\ebox\egraph} +.SH EXAMPLES +.EX +arrow "input" above; box "process"; arrow "output" above +move +A: ellipse + circle rad .1 with .w at A.e + circle rad .05 at 0.5 + circle rad .065 at 0.5 + spline from last circle.nw left .25 then left .05 down .05 + arc from A.c to A.se rad 0.5 + for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 } +.EE +.PP +.PS +arrow "input" above; box "process"; arrow "output" above +move +A: ellipse + circle rad .1 with .w at A.e + circle rad .05 at 0.5 + circle rad .065 at 0.5 + spline from last circle.nw left .25 then left .05 down .05 + arc from A.c to A.se rad 0.5 + for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 } +.PE +.SH SOURCE +.B /sys/src/cmd/pic +.SH "SEE ALSO" +.IR grap (1), +.IR doctype (1), +.IR troff (1) +.br +B. W. Kernighan, +``PIC\(ema Graphics Language for Typesetting'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2 diff --git a/sys/man/1/pipefile b/sys/man/1/pipefile new file mode 100755 index 000000000..19f207f31 --- /dev/null +++ b/sys/man/1/pipefile @@ -0,0 +1,101 @@ +.TH PIPEFILE 1 +.SH NAME +pipefile \- attach filter to file in name space +.SH SYNOPSIS +.B pipefile +[ +.B -d +] [ +.B -r +.I command +] [ +.B -w +.I command +] +.I file +.SH DESCRIPTION +.I Pipefile +uses +.IR bind (2) +to attach a pair of pipes to +.IR file , +using them to +interpose filter +.I commands +between the true file and the simulated file that subsequently +appears in the name space. +Option +.B -r +interposes a filter that will affect the data delivered to programs that read from +.IR file ; +.B -w +interposes a filter that will affect the data written by programs to +.IR file . +At least one +.I command +must be specified; +.I pipefile +will insert a +.IR cat (1) +process in the other direction. +.PP +After +.I pipefile +has been run, the filters are established for programs that subsequently +open the +.IR file ; +programs already using the +.I file +are unaffected. +.PP +.I Pipefile +opens the +.I file +twice, once for each direction. If the +.I file +is a single-use device, such as +.BR /dev/mouse , +use the +.B -d +flag to specify that the file is to be opened once, in +.B ORDWR +mode. +.SH EXAMPLES +Simulate an old terminal: +.EX +.IP +% pipefile -w 'tr a-z A-Z' /dev/cons +% rc -i /dev/cons >[2=1] +% echo hello +HELLO +% +.EE +.PP +Really simulate an old terminal: +.EX +.IP +% pipefile -r 'tr A-Z a-z' -w 'tr a-z A-Z' /dev/cons +% rc -i /dev/cons >[2=1] +% DATE +THU OCT 12 10:13:45 EDT 2000 +% +.EE +.SH SOURCE +.B /sys/src/cmd/pipefile.c +.SH SEE ALSO +.IR mouse (8) +.SH BUGS +The I/O model of +.I pipefile +is peculiar; it doesn't work well on plain files. +It is really intended for use with continuous devices such as +.I /dev/cons +and +.IR /dev/mouse . +.I Pipefile +should be rewritten to be a user-level file system. +.PP +If the program using the file managed by +.I pipefile +exits, the filter will see EOF and exit, and the file will be unusable +until the name space is repaired. diff --git a/sys/man/1/plot b/sys/man/1/plot new file mode 100755 index 000000000..cd1a1b816 --- /dev/null +++ b/sys/man/1/plot @@ -0,0 +1,61 @@ +.TH PLOT 1 +.SH NAME +plot \- graphics filter +.SH SYNOPSIS +.B plot +[ +.I file ... +] +.SH DESCRIPTION +.I Plot +interprets plotting instructions (see +.IR plot (6)) +from the +.I files +or standard input, +drawing the results in a newly created +.IR rio (1) +window. +Plot persists until a newline is typed in the window. +Various options may be interspersed with the +.I file +arguments; they take effect at the given point in processing. +Options are: +.TP "\w'\fL-g \fIgrade\fLXX'u" +.B -d +Double buffer: accumulate the plot off-screen and write to the screen all at once +when an erase command is encountered or at end of file. +.TP +.B -e +Erase the screen. +.TP +.BI -c " col" +Set the foreground color (see +.IR plot (6) +for color names). +.TP +.BI -f " fill" +Set the background color. +.TP +.BI -g " grade" +Set the quality factor for arcs. +Higher grades give better quality. +.TP +.BI -p " col" +Set the pen color. +.TP +.BI -w +Pause until a newline is typed on standard input. +.TP +.B -C +Close the current plot. +.TP +.B -W " x0,y0,x1,y1" +Specify the bounding rectangle of plot's window. +By default it uses a 512×512 window in the +middle of the screen. +.SH SOURCE +.B /sys/src/cmd/plot +.SH "SEE ALSO" +.IR rio (1), +.IR plot (6) diff --git a/sys/man/1/plumb b/sys/man/1/plumb new file mode 100755 index 000000000..6c51d68bd --- /dev/null +++ b/sys/man/1/plumb @@ -0,0 +1,92 @@ +.TH PLUMB 1 +.SH NAME +plumb \- send message to plumber +.SH SYNOPSIS +.B plumb +[ +.B -p +.I plumbfile +] [ +.B -a +.I attributes +] [ +.B -s +.I source +] [ +.B -d +.I destination +] [ +.B -t +.I type +] [ +.B -w +.I directory +] +.B -i +| +.I data... +.SH DESCRIPTION +The +.I plumb +command formats and sends a plumbing message whose data +is, by default, the concatenation of the argument strings separated by blanks. +The options are: +.TP +.B -p +write the message to +.I plumbfile +(default +.BR /mnt/plumb/send ). +.TP +.B -a +set the +.B attr +field of the message (default is empty). +.TP +.B -s +set the +.B src +field of the message (default is +.BR plumb ). +.TP +.B -d +set the +.B dst +field of the message (default is empty). +.TP +.B -t +set the +.B type +field of the message (default is +.BR text ). +.TP +.B -w +set the +.B wdir +field of the message (default is the current working directory of +.IR plumb ). +.TP +.B -i +take the data from standard input rather than the argument strings. +If an +.B action= +attribute is not otherwise specified, +.I plumb +will add an +.B action=showdata +attribute to the message. +.SH FILES +.TF /usr/$user/lib/plumbing +.TP +.B /usr/$user/lib/plumbing +default rules file +.TP +.B /mnt/plumb +mount point for +.IR plumber (4). +.SH SOURCE +.B /sys/src/cmd/plumb +.SH "SEE ALSO" +.IR plumb (2), +.IR plumber (4), +.IR plumb (6) diff --git a/sys/man/1/pr b/sys/man/1/pr new file mode 100755 index 000000000..14da53770 --- /dev/null +++ b/sys/man/1/pr @@ -0,0 +1,110 @@ +.TH PR 1 +.SH NAME +pr \- print file +.SH SYNOPSIS +.B pr +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Pr +produces a printed listing of one or more +.I files +on its standard output. +The output is separated into pages headed by a date, +the name of the file or a specified header, and the page number. +With no file arguments, +.I pr +prints its standard input. +.PP +Options apply to all following files but may be reset +between files: +.TP +.BI - n +Produce +.IR n -column +output. +.TP +.BI + n +Begin printing with page +.IR n . +.TP +.B -b +Balance columns on last page, in case of multi-column output. +.TP +.B -d +Double space. +.TP +.BI -e n +Set the tab stops for input text every +.I n +spaces. +.TP +.B -h +Take the next argument as a page header +.RI ( file +by default). +.TP +.BI -i n +Replace sequences of blanks in the output +by tabs, using tab stops set every +.I n +spaces. +.TP +.BI -f +Use form feeds to separate pages. +.TP +.BI -l n +Take the length of the page to be +.I n +lines instead of the default 66. +.TP +.B -m +Print all +.I files +simultaneously, +each in one column. +.TP +.BI -n m +Number the lines of each +.IR file . +The numeric argument +.IR m , +default 5, +sets the width of the line-number field. +.TP +.BI -o n +Offset the left margin +.I n +character positions. +.TP +.BI -p +Pad each file printed to an even number of pages, if necessary. +For two-sided printers, +this will ensure each file will start a new page. +.TP +.BI -s c +Separate columns by the single character +.I c +instead of aligning them with white space. +A missing +.I c +is taken to be a tab. +.TP +.B -t +Do not print the 5-line header or the +5-line trailer normally supplied for each page. +.TP +.BI -w n +For multi-column output, +take the width of the page to be +.I n +characters instead of the default 72. +.SH SOURCE +.B /sys/src/cmd/pr.c +.SH "SEE ALSO" +.IR cat (1), +.IR lp (1) diff --git a/sys/man/1/prof b/sys/man/1/prof new file mode 100755 index 000000000..40e4a9901 --- /dev/null +++ b/sys/man/1/prof @@ -0,0 +1,167 @@ +.TH PROF 1 +.SH NAME +prof, tprof, kprof \- display profiling data +.SH SYNOPSIS +.B prof +[ +.B -dr +] +[ +.I program +] +[ +.I profile +] +.PP +.B tprof +.I pid +.PP +.B kprof +.I kernel +.I kpdata +.SH DESCRIPTION +.I Prof +interprets files produced automatically by programs loaded using the +.B -p +option of +.IR 2l (1) +or other loader. +The symbol table in the +named program file +.RL ( 2.out +etc., according to +.BR $objtype , +by default) +is read and correlated with the +profile file +.RL ( prof.out +by default). +For each symbol, the percentage +of time (in seconds) spent executing between that symbol +and the next +is printed (in decreasing order), +together with the time spent there and +the number of times that routine was called. +.PP +Under option +.BR -d , +.I prof +prints the dynamic call graph of the target program, +annotating the calls with the time spent in each routine +and those it calls, recursively. The output is indented +two spaces for each call, and is formatted as +.IP +.EX +symbol:time/ncall +.EE +.LP +where +.I symbol +is the entry point of the call, +.I time +is in milliseconds, +and +.I ncall +is the number of times that entry point was called at that +point in the call graph. If +.I ncall +is one, the +.B /ncall +is elided. +Normally recursive calls are compressed to keep the output brief; +option +.B -r +prints the full call graph. +.PP +The size of the buffer +in +.I program +used to hold the profiling +data, by default 2000 entries, +may be controlled by setting the environment variable +.B profsize +before running +.IR program . +If the buffer fills, subsequent function calls may not be recorded. +.PP +The profiling code provided by the linker initializes itself to profile the current pid, +producing a file called +.B prof.\f2pid\fP. +If a process forks, only the parent will continue to be profiled. Forked children +can cause themselves to be profile by calling +.IP +.EX +prof(fn, arg, entries, what) +.EE +.LP +which causes the function \f2fn\fP(\f2arg\fP) to be profiled. When \f2fn\fP +returns +.B prof.\f2pid\fP +is produced for the current process pid. +.PP +The environment variable +.B proftype +can be set to one of +.BR user , +.BR kernel , +.BR elapsed , +or +.BR sample , +to profile time measured spent in user mode, time spent in user+kernel mode, or elapsed time, +using the cycle counter, or the time in user mode using the kernel's HZ clock. The cycle counter +is currently only available on modern PCs and on the PowerPC. Default profiling measures user +time, using the cycle counter if it is available. +.PP +.I Tprof +is similar to +.IR prof , +but is intended for profiling multiprocess programs. +It uses the +.BI /proc/ pid /profile +file to collect instruction frequency counts for the text image associated with the process, +for all processes that share that text. +It must be run while the program is still active, since the data is stored with the running program. +To enable +.I tprof +profiling for a given process, +.IP +.EX +echo profile > /proc/\f2pid\f1/ctl +.EE +.LP +and then, after the program has run for a while, execute +.IP +.EX +tprof \f2pid\f1 +.EE +.LP +Since the data collected for +.I tprof +is based on interrupt-time sampling of the program counter, +.I tprof +has no +.B -d +or +.B -r +options. +.PP +.I Kprof +is similar to +.IR prof , +but presents the data accumulated by the kernel +profiling device, +.IR kprof (3) . +The symbol table file, that of the operating system kernel, +and the data file, typically +.BR /dev/kpdata , +must be provided. +.I Kprof +has no options and cannot present dynamic data. +.SH SOURCE +.B /sys/src/cmd/prof.c +.br +.B /sys/src/cmd/kprof.c +.SH SEE ALSO +.IR 2l (1), +.IR exec (2), +.IR kprof (3) diff --git a/sys/man/1/proof b/sys/man/1/proof new file mode 100755 index 000000000..f0c6c7f5e --- /dev/null +++ b/sys/man/1/proof @@ -0,0 +1,134 @@ +.TH PROOF 1 +.SH NAME +proof \- troff output interpreter +.SH SYNOPSIS +.B proof +[ +.BI -m mag +] +[ +.BI -/ nview +] +[ +.B -F +.I dir +] +[ +.B -d +] +[ +.I file +] +.SH DESCRIPTION +.I Proof +reads +.IR troff (1) +intermediate language from +.I file +or standard input +and simulates the resulting pages on the screen. +.PP +After a page of text is displayed, +.I proof +pauses for a command from the keyboard. +The typed commands are: +.TP \w'newline\ \ \ 'u +newline +Go on to next page of text. +.TP +.B - +Go back to the previous page. +.TP +.B q +Quit. +.TP +.BI p n +Print page +.IR n . +An out-of-bounds page number means the end nearer to that number; +a missing number means the current page; +a signed number means an offset to the current page. +.TP +.I n +Same as +.BI p n\f1. +.TP +.B c +Clear the screen, then wait for another command. +.TP +.BI m mag +Change the magnification at which the output is printed. +Normally it is printed with magnification .9; +.IR mag "=.5" +shrinks it to half size; +.IR mag "=2" +doubles the size. +.TP +.BI x val +Move everything +.I val +screen pixels to the right (left, if +.I val +is negative). +.TP +.BI y val +Move everything +.I val +screen pixels down (up, if +.I val +is negative). +.TP +.BI / nview +Split the window into +.I nview +pieces. The current page goes into the rightmost, bottommost piece, +and previous pages are shown in the other pieces. +.TP +.BI "-F " dir +Use +.I dir +for fonts instead of +.BR /lib/font/bit . +.TP +.B d +Toggle the debug flag. +.PD +.PP +These commands are also available, under slightly different form, +from a menu on button 3. The +.B pan +menu item allows arbitrary positioning of the page: +after selecting +.BR pan , +press the mouse button again and hold it down while moving +the page to the desired location. The page will be redisplayed +in its entirety when the button is released. +Mouse button 1 also pans, without the need for selecting from a menu. +.PP +The +.BR m , +.BR x , +.BR y , +.BR F , +.BR / , +and +.B d +commands are also available as command line options. +.SH FILES +.TF \fL/lib/font/bit/MAP +.TP +.B /lib/font/bit/* +fonts +.TP +.B /lib/font/bit/MAP +how to convert troff output fonts and character names +into screen fonts and character numbers +.SH SOURCE +.B /sys/src/cmd/proof +.SH SEE ALSO +.IR lp (1), +.IR gs (1), +.IR page (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual'' diff --git a/sys/man/1/ps b/sys/man/1/ps new file mode 100755 index 000000000..3f3c9629d --- /dev/null +++ b/sys/man/1/ps @@ -0,0 +1,113 @@ +.TH PS 1 +.SH NAME +ps, psu \- process status +.SH SYNOPSIS +.B ps +[ +.B -apr +] +.PP +.B psu +[ +.B -apr +] +[ +.I user +] +.SH DESCRIPTION +.I Ps +prints information about processes. +.I Psu +prints only information about processes started by +.I user +(default +.BR $user ). +.PP +For each process reported, +the user, +process id, +user time, +system time, +size, +state, +and command name are printed. +State is one of the following: +.TP \w'\fLno\ \fIresource\ \ \ 'u +.B Moribund +Process has exited and is about to have its +resources reclaimed. +.TP +.B Ready +on the queue of processes ready to be run. +.TP +.B Scheding +about to be run. +.TP +.B Running +running. +.TP +.B Queueing +waiting on a queue for a resource. +.TP +.B Wakeme +waiting for I/O or some other kernel event to wake it up. +.TP +.B Broken +dead of unnatural causes; lingering +so that it can be examined. +.TP +.B Stopped +stopped. +.TP +.B Stopwait +waiting for another process to stop. +.TP +.B Fault +servicing a page fault. +.TP +.B Idle +waiting for something to do (kernel processes only). +.TP +.B New +being created. +.TP +.B Pageout +paging out some other process. +.TP +.I Syscall +performing the named system call. +.TP +.BI no " resource +waiting for more of a critical +.IR resource . +.PD +.PP +The +.B -r +flag causes +.I ps +to print, before the user time, the elapsed real time for the process. +.PP +The +.B -p +flag causes +.I ps +to print, after the system time, the baseline and current priorities of each process. +.PP +The +.B -a +flag causes +.I ps +to print the arguments for the process. Newlines in arguments will be translated to spaces for display. +.SH FILES +.B /proc/*/status +.SH SOURCE +.B /sys/src/cmd/ps.c +.br +.B /rc/bin/psu +.SH "SEE ALSO" +.IR acid (1), +.IR db (1), +.IR kill (1), +.IR ns (1), +.IR proc (3) diff --git a/sys/man/1/ps2pdf b/sys/man/1/ps2pdf new file mode 100755 index 000000000..a4b9a5dd1 --- /dev/null +++ b/sys/man/1/ps2pdf @@ -0,0 +1,90 @@ +.TH PS2PDF 1 +.SH NAME +ps2pdf, pdf2ps \- convert between PostScript and PDF +.SH SYNOPSIS +.B ps2pdf +[ +.I gs-options +] +[ +.I input-file +[ +.I output-file +] +] +.PP +.B pdf2ps +[ +.I gs-options +] +[ +.I input-file +[ +.I output-file +] +] +.SH DESCRIPTION +.I Ps2pdf +and +.I pdf2ps +convert from PostScript to PDF and back by invoking +.IR gs (1). +If +.I output-file +is not specified, they write to standard output. +If neither +.I input-file +nor +.I output-file +is not specified, they read from standard input and write to standard output. +.PP +The +.I gs-options +are passed to Ghostscript unaltered. +The most useful option to +.I ps2pdf +is +.BR -dCompatibilityLevel=\fIlevel , +which sets the version of PDF to be written. +The default is +.BR 1.2 ; +.B 1.3 +and +.B 1.4 +are also possible. +Similarly, the most useful option to +.I pdf2ps +is +.BR -dLanguageLevel=\fIlevel , +which sets the version of PostScript to be written. +The default is +.BR 2 ; +.B 1 +and +.B 3 +are also possible. +.PP +.I Ps2pdf +produces output competitive with +Adobe Distiller in most cases, and it +accepts all the embedded PDF-generation hints that Adobe Distiller does. +.PP +.I Pdf2ps +produces a PostScript file containing one large bitmap +per page. For a more direct and smaller translation, +use Adobe Acrobat's +.B -toPostScript +command-line option. +.SH SOURCE +.B /rc/bin/ps2pdf +.br +.B /rc/bin/pdf2ps +.SH SEE ALSO +.IR gs (1) +.SH BUGS +.IR Gs 's +.I pdfwrite +sometimes emits bad PDF at the default level 1.2. +Adding +.BR '-dCompatibilityLevel=1.4' +should cure it. diff --git a/sys/man/1/pump b/sys/man/1/pump new file mode 100755 index 000000000..d1868d023 --- /dev/null +++ b/sys/man/1/pump @@ -0,0 +1,119 @@ +.TH PUMP 1 +.SH NAME +pump \- copy asynchronously via a large circular buffer +.SH SYNOPSIS +.B pump +[ +.B -b +.I iando +] [ +.B -d +.I sleepms +] [ +.B -f +.I ofile +] [ +.B -i +.I ireadsize +] [ +.B -k +.I KB-buf +] [ +.B -o +.I owritesize +] [ +.B -s +.I start-KB +] [ +.I file +\&... ] +.SH DESCRIPTION +.I Pump +copies +.IR files +(or standard input if none) +to standard output +by using two processes, +one reading and one writing, +sharing a large circular buffer, +thus permitting the reading process to +get ahead of the writing process if the +output device is slow (e.g., an optical disc). +This in turn can keep the output device busy. +The pipeline +.L "dd | dd" +can approximate this, but pipe buffering is limited to 64K +bytes, which is fairly modest. +.PP +Options are: +.TF \fL-m +.TP +.B -b +sets the size of +.I read +and +.I write +operations to +.I iando +bytes. +The default size is 8 kilobytes. +.TP +.B -d +causes the output process to sleep for +.I sleepms +milliseconds initially, giving the reading +process time to accumulate data in the buffer. +.TP +.B -f +writes +.I ofile +rather than standard output +.TP +.B -i +sets the size of +.I read +operations to +.I ireadsize +bytes. +.TP +.B -k +allocates a circular buffer of +.I KB-buf +kilobytes rather than the default +5000 kilobytes. +.TP +.B -o +sets the size of +.I write +operations to +.I owritesize +bytes. +.TP +.B -s +prevents output until +.I start-KB +kilobytes have been read. +.SH EXAMPLES +Append a +.IR venti (8) +arena to a DVD or BD quickly. +.PD 0 +.IP +.EX +cdfs +venti/rdarena arena0 arena.3 | + pump -b 65536 -k 51200 >/mnt/cd/wd/arena.3 +.EE +.PD +.\" .SH FILES +.SH SOURCE +.B /sys/src/cmd/pump.c +.SH SEE ALSO +.IR cp (1), +.IR dd (1), +.IR ecp (1), +.IR cdfs (4) +.SH BUGS +.I Pump +processes spin while waiting for the circular buffer +to fill or drain. diff --git a/sys/man/1/pwd b/sys/man/1/pwd new file mode 100755 index 000000000..f36e4fbf5 --- /dev/null +++ b/sys/man/1/pwd @@ -0,0 +1,38 @@ +.TH PWD 1 +.SH NAME +pwd, pbd \- working directory +.SH SYNOPSIS +.B pwd +.br +.B pbd +.SH DESCRIPTION +.I Pwd +prints the path name of the working (current) directory. +.I Pwd +is guaranteed to return the same path that was used to +enter the directory. +If, however, the name space has changed, or directory names +have been changed, this path name may no longer be valid. +(See +.IR fd2path (2) +for a description of +.BR pwd 's +mechanism.) +.PP +.I Pbd +prints the base name of the working (current) directory. +It prints no final newline and is intended for applications +such as constructing shell prompts. +.SH SOURCE +.B /sys/src/cmd/pwd.c +.br +.B /sys/src/cmd/pbd.c +.SH SEE ALSO +.I cd +in +.IR rc (1), +.IR bind (1), +.IR intro (2), +.IR getwd (2), +.IR fd2path (2) + diff --git a/sys/man/1/ratrace b/sys/man/1/ratrace new file mode 100755 index 000000000..515b5214f --- /dev/null +++ b/sys/man/1/ratrace @@ -0,0 +1,57 @@ +.TH RATRACE 1 +.SH NAME +ratrace \- trace process system calls +.SH SYNOPSIS +.B ratrace +[ +.I pid +] | [ +.I -c command +] +.SH DESCRIPTION +.I Ratrace +shows the system calls executed by a process, +either the one with +.I pid +or a fresh invocation of +.IR command . +.PP +Trace output is determined by the kernel, not +.IR ratrace . +Certain fixed rules apply. +The first four fields of the output are +pid, text name, system call name, and the PC of the user program. +Data is always printed as +.IB pointer /\c +"\fIstring\fP", +where the +.I string +is the first 32 bytes of the data, with +.L \&. +replacing non-printing ASCII characters +(printing characters are those between ASCII space (SP) and delete (DEL), exclusive). +Return values follow an +.LR = , +and include the integer return value, +the +.I errstr +(with "" if there is no +.IR errstr ), +and +the start and stop times for the system call in nanoseconds. +The times are exclusive of the overhead for tracing. +.SH FILES +.BI /proc/ pid /syscalltrace +.br +.BI /proc/ pid /ctl +.SH SOURCE +.B /sys/src/cmd/ratrace.c +.SH "SEE ALSO" +.IR acid (1), +.IR db (1), +.IR proc (3) +.SH BUGS +The printing of the data is too limited in length; +printing +.L \&. +instead of something more sensible is limiting. diff --git a/sys/man/1/rc b/sys/man/1/rc new file mode 100755 index 000000000..2dd2a1dd3 --- /dev/null +++ b/sys/man/1/rc @@ -0,0 +1,993 @@ +.TH RC 1 +.SH NAME +rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ \- command language +.SH SYNOPSIS +.B rc +[ +.B -srdiIlxepvV +] +[ +.B -c +.I command +] +[ +.B -m +.I initial +] +[ +.I file +[ +.I arg ... +]] +.SH DESCRIPTION +.I Rc +is the Plan 9 shell. +It executes command lines read from a terminal or a file or, with the +.B -c +flag, from +.I rc's +argument list. +.SS Command Lines +A command line is a sequence of commands, separated by ampersands or semicolons +.RB ( & +or +.BR ; ), +terminated by a newline. +The commands are executed in sequence +from left to right. +.I Rc +does not wait for a command followed by +.B & +to finish executing before starting +the following command. +Whenever a command followed by +.B & +is executed, its process id is assigned to the +.I rc +variable +.BR $apid . +Whenever a command +.I not +followed by +.B & +exits or is terminated, the +.I rc +variable +.B $status +gets the process's wait message (see +.IR wait (2)); +it will be the null string if the command was successful. +.PP +A long command line may be continued on subsequent lines by typing +a backslash +.RB ( \e ) +followed by a newline. +This sequence is treated as though it were a blank. +Backslash is not otherwise a special character. +.PP +A number-sign +.RB ( # ) +and any following characters up to (but not including) the next newline +are ignored, except in quotation marks. +.SS Simple Commands +A simple command is a sequence of arguments interspersed with I/O redirections. +If the first argument is the name of an +.I rc +function or of one of +.I rc's +built-in commands, it is executed by +.IR rc . +Otherwise if the name starts with a slash +.RB ( / ), +it must be the path name of the program to be executed. +Names containing no initial slash are searched for in +a list of directory names stored in +.BR $path . +The first executable file of the given name found +in a directory in +.B $path +is the program to be executed. +To be executable, the user must have execute permission (see +.IR stat (2)) +and the file must be either an executable binary +for the current machine's CPU type, or a shell script. +Shell scripts begin with a line containing the full path name of a shell +(usually +.BR /bin/rc ), +prefixed by +.LR #! . +.PP +The first word of a simple command cannot be a keyword unless it is +quoted or otherwise disguised. +The keywords are +.EX + for in while if not switch fn ~ ! @ +.EE +.SS Arguments and Variables +A number of constructions may be used where +.I rc's +syntax requires an argument to appear. +In many cases a construction's +value will be a list of arguments rather than a single string. +.PP +The simplest kind of argument is the unquoted word: +a sequence of one or more characters none of which is a blank, tab, +newline, or any of the following: +.EX + # ; & | ^ $ = ` ' { } ( ) < > +.EE +An unquoted word that contains any of the characters +.B * +.B ? +.B [ +is a pattern for matching against file names. +The character +.B * +matches any sequence of characters, +.B ? +matches any single character, and +.BI [ class ] +matches any character in the +.IR class . +If the first character of +.I class +is +.BR ~ , +the class is complemented. +The +.I class +may also contain pairs of characters separated by +.BR - , +standing for all characters lexically between the two. +The character +.B / +must appear explicitly in a pattern, as must the +first character of the path name components +.B . +and +.BR .. . +A pattern is replaced by a list of arguments, one for each path name matched, +except that a pattern matching no names is not replaced by the empty list, +but rather stands for itself. +Pattern matching is done after all other +operations. +Thus, +.EX + x=/tmp echo $x^/*.c +.EE +matches +.BR /tmp/*.c , +rather than matching +.B "/*.c +and then prefixing +.BR /tmp . +.PP +A quoted word is a sequence of characters surrounded by single quotes +.RB ( ' ). +A single quote is represented in a quoted word by a pair of quotes +.RB ( '' ). +.PP +Each of the following is an argument. +.PD 0 +.HP +.BI ( arguments ) +.br +The value of a sequence of arguments enclosed in parentheses is +a list comprising the members of each element of the sequence. +Argument lists have no recursive structure, although their syntax may +suggest it. +The following are entirely equivalent: +.EX + echo hi there everybody + ((echo) (hi there) everybody) +.EE +.HP +.BI $ argument +.HP +.BI $ argument ( subscript ) +.br +The +.I argument +after the +.B $ +is the name of a variable whose value is substituted. +Multiple levels +of indirection are possible, but of questionable utility. +Variable values +are lists of strings. +If +.I argument +is a number +.IR n , +the value is the +.IR n th +element of +.BR $* , +unless +.B $* +doesn't have +.I n +elements, in which case the value is empty. +If +.I argument +is followed by a parenthesized list of subscripts, the +value substituted is a list composed of the requested elements (origin 1). +The parenthesis must follow the variable name with no spaces. +Subscripts can also take the form +.IB m - n +or +.IB m - +to indicate a sequence of elements. +Assignments to variables are described below. +.HP +.BI $# argument +.br +The value is the number of elements in the named variable. +A variable +never assigned a value has zero elements. +.HP +$"\c +.I argument +.br +The value is a single string containing the components of the named variable +separated by spaces. A variable with zero elements yields the empty string. +.HP +.BI `{ command } +.br +.I rc +executes the +.I command +and reads its standard output, splitting it into a list of arguments, +using characters in +.B $ifs +as separators. +If +.B $ifs +is not otherwise set, its value is +.BR "'\ \et\en'" . +.HP +.BI <{ command } +.HP +.BI >{ command } +.br +The +.I command +is executed asynchronously with its standard output or standard input +connected to a pipe. +The value of the argument is the name of a file +referring to the other end of the pipe. +This allows the construction of +non-linear pipelines. +For example, the following runs two commands +.B old +and +.B new +and uses +.B cmp +to compare their outputs +.EX + cmp <{old} <{new} +.EE +.HP +.IB argument ^ argument +.br +The +.B ^ +operator concatenates its two operands. +If the two operands +have the same number of components, they are concatenated pairwise. +If not, +then one operand must have one component, and the other must be non-empty, +and concatenation is distributive. +.PD +.SS Free Carets +In most circumstances, +.I rc +will insert the +.B ^ +operator automatically between words that are not separated by white space. +Whenever one of +.B $ +.B ' +.B ` +follows a quoted or unquoted word or an unquoted word follows a quoted word +with no intervening blanks or tabs, +a +.B ^ +is inserted between the two. +If an unquoted word immediately follows a +.BR $ +and contains a character other than an alphanumeric, underscore, +or +.BR * , +a +.B ^ +is inserted before the first such character. +Thus +.IP +.B cc -$flags $stem.c +.LP +is equivalent to +.IP +.B cc -^$flags $stem^.c +.SS I/O Redirections +The sequence +.BI > file +redirects the standard output file (file descriptor 1, normally the +terminal) to the named +.IR file ; +.BI >> file +appends standard output to the file. +The standard input file (file descriptor 0, also normally the terminal) +may be redirected from a file by the sequence +.BI < file \f1, +or from an inline `here document' +by the sequence +.BI << eof-marker\f1. +The contents of a here document are lines of text taken from the command +input stream up to a line containing nothing but the +.IR eof-marker , +which may be either a quoted or unquoted word. +If +.I eof-marker +is unquoted, variable names of the form +.BI $ word +have their values substituted from +.I rc's +environment. +If +.BI $ word +is followed by a caret +.RB ( ^ ), +the caret is deleted. +If +.I eof-marker +is quoted, no substitution occurs. +The standard input file +may also be redirected from a file by the sequence +.BI <> file \f1, +which opens +.I file +exactly once, for reading and writing. +.PP +Redirections may be applied to a file-descriptor other than standard input +or output by qualifying the redirection operator +with a number in square brackets. +For example, the diagnostic output (file descriptor 2) +may be redirected by writing +.BR "cc junk.c >[2]junk" . +.PP +A file descriptor may be redirected to an already open descriptor by writing +.BI >[ fd0 = fd1 ], +.BI <>[ fd0 = fd1 ], +or +.BI <[ fd0 = fd1 ]\f1. +.I Fd1 +is a previously opened file descriptor and +.I fd0 +becomes a new copy (in the sense of +.IR dup (2)) +of it. +A file descriptor may be closed by writing +.BI >[ fd0 =] +or +.BI <[ fd0 =]\f1. +.PP +Redirections are executed from left to right. +Therefore, +.B cc junk.c >/dev/null >[2=1] +and +.B cc junk.c >[2=1] >/dev/null +have different effects: the first puts standard output in +.BR /dev/null +and then puts diagnostic output in the same place, where the second +directs diagnostic output to the terminal and sends standard output to +.BR /dev/null . +.PP +.B newconn <>/net/tcp/clone >[1=0] +opens +.B /net/tcp/clone +exactly once for reading and writing and puts it on standard input and output. +.B lpd <>[3]/net/tcp/42/data +opens +.B /net/tcp/42/data +exactly once for reading and writing and puts it on file descriptor 3. +.SS Compound Commands +A pair of commands separated by a pipe operator +.RB ( | ) +is a command. +The standard output of the left command is sent through a pipe +to the standard input of the right command. +The pipe operator may be decorated +to use different file descriptors. +.BI |[ fd ] +connects the output end of the pipe to file descriptor +.I fd +rather than 1. +.BI |[ fd0 = fd1 ] +connects output to +.I fd1 +of the left command and input to +.I fd0 +of the right command. +.PP +A pair of commands separated by +.B && +or +.B || +is a command. +In either case, the left command is executed and its exit status examined. +If the operator is +.B && +the right command is executed if the left command's status is null. +.B || +causes the right command to be executed if the left command's status is non-null. +.PP +The exit status of a command may be inverted (non-null is changed to null, null +is changed to non-null) by preceding it with a +.BR ! . +.PP +The +.B | +operator has highest precedence, and is left-associative (i.e. binds tighter +to the left than the right). +.B ! +has intermediate precedence, and +.B && +and +.B || +have the lowest precedence. +.PP +The unary +.B @ +operator, with precedence equal to +.BR ! , +causes its operand to be executed in a subshell. +.PP +Each of the following is a command. +.PD 0 +.HP +.B if ( +.I list +.B ) +.I command +.br +A +.I list +is a sequence of commands, separated by +.BR & , +.BR ; , +or newline. +It is executed and +if its exit status is null, the +.I command +is executed. +.HP +.B if not +.I command +.br +The immediately preceding command must have been +.BI if( list ) +.IR command . +If its condition was non-zero, the +.I command +is executed. +.HP +.BI for( name +.B in +.IB arguments ) +.I command +.HP +.BI for( name ) +.I command +.br +The +.I command +is executed once for each +.IR argument +with that argument assigned to +.IR name . +If the argument list is omitted, +.B $* +is used. +.HP +.BI while( list ) +.I command +.br +The +.I list +is executed repeatedly until its exit status is non-null. +Each time it returns null status, the +.I command +is executed. +An empty +.I list +is taken to give null status. +.HP +.BI "switch(" argument "){" list } +.br +The +.IR list +is searched for simple commands beginning with the word +.BR case . +(The search is only at the `top level' of the +.IR list . +That is, +.B cases +in nested constructs are not found.) +.I Argument +is matched against each word following +.B case +using the pattern-matching algorithm described above, except that +.B / +and the first characters of +.B . +and +.B .. +need not be matched explicitly. +When a match is found, commands in the list are executed up to the next +following +.B case +command (at the top level) or the closing brace. +.HP +.BI { list } +.br +Braces serve to alter the grouping of commands implied by operator +priorities. +The +.I body +is a sequence of commands separated by +.BR & , +.BR ; , +or newline. +.HP +.BI "fn " name { list } +.HP +.BI "fn " name +.br +The first form defines a function with the given +.IR name . +Subsequently, whenever a command whose first argument is +.I name +is encountered, the current value of +the remainder of the command's argument list will be assigned to +.BR $* , +after saving its current value, and +.I rc +will execute the +.IR list . +The second form removes +.IR name 's +function definition. +.HP +.BI "fn " note { list } +.br +.HP +.BI "fn " note +.br +A function with a special name will be called when +.I rc +receives a corresponding note; see +.IR notify (2). +The valid note names (and corresponding notes) are +.B sighup +.RB ( hangup ), +.B sigint +.RB ( interrupt ), +.BR sigalrm +.RB ( alarm ), +and +.B sigfpe +(floating point trap). +By default +.I rc +exits on receiving any signal, except when run interactively, +in which case interrupts and quits normally cause +.I rc +to stop whatever it's doing and start reading a new command. +The second form causes +.I rc +to handle a signal in the default manner. +.I Rc +recognizes an artificial note, +.BR sigexit , +which occurs when +.I rc +is about to finish executing. +.HP +.IB name = "argument command" +.br +Any command may be preceded by a sequence of assignments +interspersed with redirections. +The assignments remain in effect until the end of the command, unless +the command is empty (i.e. the assignments stand alone), in which case +they are effective until rescinded by later assignments. +.PD +.SS Built-in Commands +These commands are executed internally by +.IR rc , +usually because their execution changes or depends on +.IR rc 's +internal state. +.PD 0 +.HP +.BI . " file ..." +.br +Execute commands from +.IR file . +.B $* +is set for the duration to the remainder of the argument list following +.IR file . +.I File +is searched for using +.BR $path . +.HP +.BI builtin " command ..." +.br +Execute +.I command +as usual except that any function named +.I command +is ignored in favor of the built-in meaning. +.HP +.BI "cd [" dir "]" +.br +Change the current directory to +.IR dir . +The default argument is +.BR $home . +.I dir +is searched for in each of the directories mentioned in +.BR $cdpath . +.HP +.BI "eval [" "arg ..." "]" +.br +The arguments are concatenated separated by spaces into a single string, +read as input to +.IR rc , +and executed. +.HP +.BI "exec [" "command ..." "]" +.br +This instance of +.I rc +replaces itself with the given (non-built-in) +.IR command . +.HP +.BI "flag " f " [+-]" +.br +Either set +.RB ( + ), +clear +.RB ( - ), +or test (neither +.B + +nor +.BR - ) +the flag +.IR f , +where +.I f +is a single character, one of the command line flags (see Invocation, below). +.HP +.BI "exit [" status "]" +.br +Exit with the given exit status. +If none is given, the current value of +.B $status +is used. +.HP +.BR "rfork " [ nNeEsfFm ] +.br +Become a new process group using +.BI rfork( flags ) +where +.I flags +is composed of the bitwise OR of the +.B rfork +flags specified by the option letters +(see +.IR fork (2)). +If no +.I flags +are given, they default to +.BR ens . +The +.I flags +and their meanings are: +.B n +is +.BR RFNAMEG ; +.B N +is +.BR RFCNAMEG ; +.B e +is +.BR RFENVG ; +.B E +is +.BR RFCENVG ; +.B s +is +.BR RFNOTEG ; +.B f +is +.BR RFFDG ; +.B F +is +.BR RFCFDG ; +and +.B m +is +.BR RFNOMNT . +.HP +.BI "shift [" n "]" +.br +Delete the first +.IR n +(default 1) +elements of +.BR $* . +.HP +.BI "wait [" pid "]" +.br +Wait for the process with the given +.I pid +to exit. +If no +.I pid +is given, all outstanding processes are waited for. +.HP +.BI whatis " name ..." +.br +Print the value of each +.I name +in a form suitable for input to +.IR rc . +The output is +an assignment to any variable, +the definition of any function, +a call to +.B builtin +for any built-in command, or +the completed pathname of any executable file. +.HP +.BI ~ " subject pattern ..." +.br +The +.I subject +is matched against each +.I pattern +in sequence. +If it matches any pattern, +.B $status +is set to zero. +Otherwise, +.B $status +is set to one. +Patterns are the same as for file name matching, except that +.B / +and the first character of +.B . +and +.B .. +need not be matched explicitly. +The +.I patterns +are not subjected to +file name matching before the +.B ~ +command is executed, so they need not be enclosed in quotation marks. +.PD +.SS Environment +The +.I environment +is a list of strings made available to executing binaries by the +.B env +device +(see +.IR env (3)). +.I Rc +creates an environment entry for each variable whose value is non-empty, +and for each function. +The string for a variable entry has the variable's name followed by +.B = +and its value. +If the value has more than one component, these +are separated by ctrl-a +.RB ( '\e001' ) +characters. +The string for a function is just the +.I rc +input that defines the function. +The name of a function in the environment is the function name +preceded by +.LR fn# . +.PP +When +.I rc +starts executing it reads variable and function definitions from its +environment. +.SS Special Variables +The following variables are set or used by +.IR rc . +.PD 0 +.TP \w'\fL$promptXX'u +.B $* +Set to +.IR rc 's +argument list during initialization. +Whenever a +.B . +command or a function is executed, the current value is saved and +.B $* +receives the new argument list. +The saved value is restored on completion of the +.B . +or function. +.TP +.B $apid +Whenever a process is started asynchronously with +.BR & , +.B $apid +is set to its process id. +.TP +.B $home +The default directory for +.BR cd . +.TP +.B $ifs +The input field separators used in backquote substitutions. +If +.B $ifs +is not set in +.IR rc 's +environment, it is initialized to blank, tab and newline. +.TP +.B $path +The search path used to find commands and input files +for the +.B . +command. +If not set in the environment, it is initialized by +.BR "path=(.\ /bin)" . +Its use is discouraged; instead use +.IR bind (1) +to build a +.B /bin +containing what's needed. +.TP +.B $pid +Set during initialization to +.IR rc 's +process id. +.TP +.B $prompt +When +.I rc +is run interactively, the first component of +.B $prompt +is printed before reading each command. +The second component is printed whenever a newline is typed and more lines +are required to complete the command. +If not set in the environment, it is initialized by +.BR "prompt=('%\ '\ '\ ')" . +.TP +.B $status +Set to the wait message of the last-executed program. +(unless started with +.BR &). +.B ! +and +.B ~ +also change +.BR $status . +Its value is used to control execution in +.BR && , +.BR || , +.B if +and +.B while +commands. +When +.I rc +exits at end-of-file of its input or on executing an +.B exit +command with no argument, +.B $status +is its exit status. +.PD +.SS Invocation +If +.I rc +is started with no arguments it reads commands from standard input. +Otherwise its first non-flag argument is the name of a file from which +to read commands (but see +.B -c +below). +Subsequent arguments become the initial value of +.BR $* . +.I Rc +accepts the following command-line flags. +.PD 0 +.TP \w'\fL-c\ \fIstring\fLXX'u +.BI -c " string" +Commands are read from +.IR string . +.TP +.B -s +Print out exit status after any command where the status is non-null. +.TP +.B -e +Exit if +.B $status +is non-null after executing a simple command. +.TP +.B -i +If +.B -i +is present, or +.I rc +is given no arguments and its standard input is a terminal, +it runs interactively. +Commands are prompted for using +.BR $prompt . +.TP +.B -I +Makes sure +.I rc +is not run interactively. +.TP +.B -l +If +.B -l +is given or the first character of argument zero is +.BR - , +.I rc +reads commands from +.BR $home/lib/profile , +if it exists, before reading its normal input. +.TP +.B -m +Read commands to initialize +.I rc +from +.I initial +instead of from +.BR /rc/lib/rcmain . +.TP +.B -p +A no-op. +.TP +.B -d +A no-op. +.TP +.B -v +Echo input on file descriptor 2 as it is read. +.TP +.B -x +Print each simple command before executing it. +.TP +.B -r +Print debugging information (internal form of commands +as they are executed). +.PD +.SH SOURCE +.B /sys/src/cmd/rc +.SH "SEE ALSO" +Tom Duff, +``Rc \- The Plan 9 Shell''. +.SH BUGS +There should be a way to match patterns against whole lists rather than +just single strings. +.PP +Using +.B ~ +to check the value of +.B $status +changes +.BR $status . +.PP +Functions containing here documents don't work. +.PP +Free carets don't get inserted next to keywords. diff --git a/sys/man/1/replica b/sys/man/1/replica new file mode 100755 index 000000000..2201c017a --- /dev/null +++ b/sys/man/1/replica @@ -0,0 +1,341 @@ +.TH REPLICA 1 +.SH NAME +changes, pull, push, scan \- client-server replica management +.SH SYNOPSIS +.B replica/pull +[ +.B -nv +] +[ +.B -c +.I name +]... +[ +.B -s +.I name +]... +.I name +[ +.I path +... +] +.br +.B replica/push +[ +.B -nv +] +.I name +[ +.I path +... +] +.br +.B replica/changes +.I name +[ +.I path +... +] +.br +.B replica/scan +.I name +[ +.I path +... +] +.SH DESCRIPTION +These shell scripts provide a simple log-based client-server replica management. +The server keeps a log of changes made to its file system, +and clients synchronize by reading the log and applying these changes locally. +.PP +These scripts are a polished interface to the low-level tools described in +.IR replica (8). +See +.IR replica (8) +for details on the inner workings of replica management. +These tools were written primarily as the fourth +edition Plan 9 distribution mechanism, but they +have wider applicability. +For example, they could be used to synchronize one's +home directory between a laptop and a central file server. +.PP +Replicas are described by configuration files. +The +.I name +in all the replica commands is a configuration +file. Paths that do not begin with +.BR / , +.BR ./ , +or +.B ../ +are assumed to be relative to +.BR $home/lib/replica . +Configuration files are described below. +.PP +.I Replica/scan +is the only one of these programs that does not +need to be run on the client. +It scans the server file system for changes +and appends entries for those changes into the server log. +Typically it is run on a machine with a fast network +connection to the server file system. +.PP +.I Replica/pull +copies changes from the server to the client, +while +.I replica/push +copies changes from the client to the server. +(Both run on the client.) +If a list of +.I paths +is given, only changes to those paths or their children are copied. +The +.B -v +flag causes +.I pull +or +.I push +to print a summary of what it is doing. +Each status line is of the form +.ift .sp 0.5 +.ifn .sp +\h'0.25i' +.I verb +.I path +.I serverpath +.I mode +.I uid +.I gid +.I mtime +.I length +.ift .sp 0.5 +.ifn .sp +.I Verb +describes the event: +addition of a file +.RB ( a ), +deletion of a file +.RB ( d ), +a change to a file's contents +.RB ( c ), +or a change to a file's metadata +.RB ( m ). +.I Path +is the file path on the client; +.I serverpath +is the file path on the server. +.IR Mode , +.IR uid , +.IR gid , +and +.I mtime +are the file's metadata as in the +.B Dir +structure (see +.IR stat (5)). +For deletion events, the metadata is that of the deleted file. +For other events, the metadata is that after the event. +The +.B -n +flag causes +.I pull +or +.I push +to print the summary but not actually carry out the actions. +.PP +.I Push +and +.I pull +are careful to notice simultaneous changes to a file or +its metadata on both client and server. +Such simultaneous changes are called +.IR conflicts . +Here, simultaneous does not mean at the same instant +but merely that both changes were carried out without knowledge +of the other. +For example, if a client and server both make changes to a file +without an intervening +.I push +or +.IR pull , +the next +.I push +or +.I pull +will report an update/update conflict. +If a conflict is detected, both files are left the same. +The +.B -c +flag to +.I pull +specifies that conflicts for paths beginning with +.I name +should be resolved using the client's copy, +while +.B -s +specifies the server's copy. +The +.B -c +and +.B -s +options may be repeated. +.PP +.I Replica/changes +prints a list of local changes made on the client +that have not yet been pushed to the server. +It is like +.I push +with the +.B -n +flag, except that it does not check for conflicts +and thus does not require the server to be available. +.PP +The replica configuration file is an +.IR rc (1) +script that must define the following functions and variables: +.TP +.B servermount +A function that mounts the server; run on both client and server. +.TP +.B serverupdate +A function that rescans the server for changes. +Typically this command dials a CPU server known +to be close to the file server and runs +.I replica/scan +on that well-connected machine. +.TP +.B serverroot +The path to the root of the replicated file +system on the server, as it will be in the name space +after running +.BR servermount . +.TP +.B serverlog +The path to the server's change log, after running +.BR servermount . +.TP +.B serverproto +The path to the proto file describing the server's files, +after running +.BR servermount . +Only used by +.IR scan . +.TP +.B serverdb +The path to the server's file database, after running +.BR servermount . +Only used by +.IR scan . +.TP +.B clientmount +A function to mount the client file system; run only on the client. +.TP +.B clientroot +The path to the root of the replicated file system on the client, +after running +.BR clientmount . +.TP +.B clientlog +The path to the client's copy of the server log file. +The client log is maintained by +.IR pull . +.TP +.B clientproto +The path to the proto file describing the client's files. +Only used by +.IR changes . +Often just a copy of +.BR $serverproto . +.TP +.B clientdb +The path to the client's file database, after running +.BR clientmount . +.TP +.B clientexclude +A (potentially empty) list of paths to exclude from +synchronization. A typical use of this is to exclude +the client database and log files. +These paths are relative to the root of the replicated file system. +.PD +.PP +As an example, the Plan 9 distribution replica configuration looks like: +.EX + fn servermount { 9fs sources; bind /n/sources/plan9 /n/dist } + fn serverupdate { status='' } + serverroot=/n/dist + s=/n/dist/dist/replica + serverlog=$s/plan9.log + serverproto=$s/plan9.proto + + fn clientmount { 9fs kfs } + clientroot=/n/kfs + c=/n/kfs/dist/replica + clientlog=$c/client/plan9.log + clientproto=$c/plan9.proto + clientdb=$c/client/plan9.db + clientexclude=(dist/replica/client) +.EE +.PP +(Since the Plan 9 developers run +.I scan +manually to update the log, the clients need not do anything +to rescan the file system. +Thus +.B serverupdate +simply returns successfully.) +.PP +The fourth edition Plan 9 distribution uses these +tools to synchronize installations with the central +server at Bell Labs. +The replica configuration files and metadata are kept +in +.BR /dist/replica . +To update your system, make sure you are connected +to the internet and run +.EX + replica/pull /dist/replica/network +.EE +If conflicts are reported (say you have made local changes to +.B /rc/bin/cpurc +and +.BR /rc/bin/termrc , +but only want to keep the +.B cpurc +changes), +use +.EX + replica/pull -c rc/bin/cpurc -s rc/bin/termrc /dist/replica/network +.EE +to instruct +.I pull +to ignore the server's change to +.BR cpurc . +.PP +The script +.B /usr/glenda/bin/rc/pull +runs +.I pull +with the +.B -v +flag and with +.B /dist/replica/network +inserted at the right point on the command line. +Logged in as glenda, one can repeat the above example with: +.EX + pull -c rc/bin/cpurc -s rc/bin/termrc +.EE +.PP +To see a list of changes made to the local file system +since installation, run +.EX + replica/changes /dist/replica/network +.EE +(Although the script is called +.IR network , +since +.I changes +is a local-only operation, the network need not be configured.) +.SH SOURCE +.B /rc/bin/replica +.SH SEE ALSO +.IR replica (8) diff --git a/sys/man/1/resample b/sys/man/1/resample new file mode 100755 index 000000000..35968d054 --- /dev/null +++ b/sys/man/1/resample @@ -0,0 +1,58 @@ +.TH RESAMPLE 1 +.SH NAME +resample \- resample a picture +.SH SYNOPSIS +.B resample +[ +.B -x +.I size +] [ +.B -y +.I size +] [ +.I file +] +.SH DESCRIPTION +.I Resample +resamples its input image (default standard input) to a new size. +The image is decimated or interpolated using +a Kaiser window. +.PP +The size of the resampled image can be specified +with the +.B -x +and +.B -y +options. +An unadorned value sets the number of pixels of that dimension; a suffixed percent sign specifies a percentage. +If only one of +.B -x +or +.B -y +is given, the other dimension is scaled to preserve +the aspect ratio of the original image. +Thus, +.B -x50% +will reduce the image to half its original dimension in both +.B x +and +.BR y . +.PP +The input should be a Plan 9 image +as described in +.IR image (6), +and the output will be a compressed 24-bit +.B r8g8b8 +image. +To uncompress the image or change the pixel format, use +.I iconv +(see +.IR crop (1)). +.PP +.SH SOURCE +.B /sys/src/cmd/resample.c +.SH "SEE ALSO +.IR crop (1), +.IR image (6) +.SH BUGS +Faster algorithms exist, but this implementation produces correct pictures. diff --git a/sys/man/1/rio b/sys/man/1/rio new file mode 100755 index 000000000..e0b297dcb --- /dev/null +++ b/sys/man/1/rio @@ -0,0 +1,537 @@ +.TH RIO 1 +.SH NAME +rio, label, window, wloc \- window system +.SH SYNOPSIS +.B rio +[ +.BI "-i '"cmd ' +] +[ +.BI "-k '"kbdcmd ' +] +[ +.B -s +] +[ +.B -f +.I font +] +.PP +.B label +.I name +.PP +.B window +[ +.B -m +] [ +.B -r +.I minx miny maxx maxy +] [ +.B -dx +.I n +] [ +.B -dy +.I n +] [ +.B -minx +.I n +] [ +.B -miny +.I n +] [ +.B -maxx +.I n +] [ +.B -maxy +.I n +] [ +.B -cd +.I dir +] [ +.B -hide +] [ +.B -scroll +] [ +.B -noscroll +] [ +.I cmd +.I arg ... +] +.PP +.B wloc +.SH DESCRIPTION +.I Rio +manages asynchronous layers of text, or windows, on a raster display. +It also serves a variety of files for communicating with +and controlling windows; these are discussed in section +.IR rio (4). +.SS Commands +The +.I rio +command starts a new instance of the window system. +Its +.B -i +option names a startup script, which typically contains several +.I window +commands generated by +.IR wloc . +The +.B -k +option causes +.I rio +to run the command +.I kbdcmd +at startup and allow it to provide characters as keyboard input; the +.B keyboard +program described in +.IR bitsyload (1) +is the usual choice. +.PP +The +.B -s +option initializes windows so that text scrolls; +the default is not to scroll. +The +.I font +argument names a font used to display text, both in +.IR rio 's +menus +and as a default for any programs running in its windows; it also +establishes the +environment variable +.BR $font . +If +.B -f +is not given, +.I rio +uses the imported value of +.BR $font +if set; otherwise it imports the default font from the underlying graphics +server, usually the terminal's operating system. +.PP +The +.I label +command changes a window's identifying name. +.PP +The +.I window +command creates a window. +By default, it creates a shell window and sizes and places it automatically. +The geometry arguments control the size +.IB ( dx , +.BR dy ) +and placement +.RB ( minx , +.BR miny , +.BR maxx , +.BR maxy ); +the units are pixels with the +upper left corner of the screen at (0, 0). +The +.B hide +option causes the window to be created off-screen. +The +.B scroll +and +.B noscroll +options set the scroll mode. +The +.B cd +option sets the working directory. +The optional command and arguments +define which program to run in the window. +.PP +By default, +.I window +uses +.B /dev/wctl +(see +.IR rio (4)) +to create the window and run the command. Therefore, the window and command +will be created by +.I rio +and run in a new file name space, just as if the window had been created using the interactive menu. +However, the +.B -m +option uses the file server properties of +.I rio +to +.B mount +(see +.IR bind (1)) +the new window's name space within the name space of the program calling +.IR window . +This means, for example, that running +.B window +in a CPU window will create another window whose command runs on the terminal, where +.I rio +is running; while +.B window +.B -m +will create another window whose command runs on the CPU server. +.PP +The +.I wloc +command prints the coordinates and label of each window in its instance of +.I rio +and is used to construct arguments for +.IR window . +.SS Window control +Each window behaves as a separate terminal with at least one process +associated with it. +When a window is created, a new process (usually a shell; see +.IR rc (1)) +is established and bound to the window as a new process group. +Initially, each window acts as a simple terminal that displays character text; +the standard input and output of its processes +are attached to +.BR /dev/cons . +Other special files, accessible to the processes running in a window, +may be used to make the window a more general display. +Some of these are mentioned here; the complete set is +discussed in +.IR rio (4). +.PP +One window is +.IR current , +and is indicated with a dark border and text; +characters typed on the keyboard are available in the +.B /dev/cons +file of the process in the current window. +Characters written on +.B /dev/cons +appear asynchronously in the associated window whether or not the window +is current. +.PP +Windows are created, deleted and rearranged using the mouse. +Clicking (pressing and releasing) mouse button 1 in a non-current +window makes that window current and brings it in front of +any windows that happen to be overlapping it. +When the mouse cursor points to the background area or is in +a window that has not claimed the mouse for its own use, +pressing mouse button 3 activates a +menu of window operations provided by +.IR rio . +Releasing button 3 then selects an operation. +At this point, a gunsight or cross cursor indicates that +an operation is pending. +The button 3 menu operations are: +.TF Resize +.TP +.B New +Create a window. +Press button 3 where one corner of the new rectangle should +appear (cross cursor), and move the mouse, while holding down button 3, to the +diagonally opposite corner. +Releasing button 3 creates the window, and makes it current. +Very small windows may not be created. +.TP +.B Resize +Change the size and location of a window. +First click button 3 in the window to be changed +(gunsight cursor). +Then sweep out a window as for the +.B New +operation. +The window is made current. +.TP +.B Move +Move a window to another location. +After pressing and holding button 3 over the window to be moved (gunsight cursor), +indicate the new position by dragging the rectangle to the new location. +The window is made current. +Windows may be moved partially off-screen. +.TP +.B Delete +Delete a window. Click in the window to be deleted (gunsight cursor). +Deleting a window causes a +.L hangup +note to be sent to all processes in the window's process group +(see +.IR notify (2)). +.TP +.B Hide +Hide a window. Click in the window to be hidden (gunsight cursor); +it will be moved off-screen. +Each hidden window is given a menu entry in the button 3 menu according to the +value of the file +.BR /dev/label , +which +.I rio +maintains +(see +.IR rio (4)). +.TP +.I label +Restore a hidden window. +.PD +.PP +Windows may also be arranged by dragging their borders. +Pressing button 1 or 2 over a window's border allows one to +move the corresponding edge or corner, while button 3 +moves the whole window. +.PD +.SS Text windows +Characters typed on the keyboard or written to +.B /dev/cons +collect in the window to form +a long, continuous document. +.PP +There is always some +.I selected +.IR text , +a contiguous string marked on the screen by reversing its color. +If the selected text is a null string, it is indicated by a hairline cursor +between two characters. +The selected text +may be edited by mousing and typing. +Text is selected by pointing and clicking button 1 +to make a null-string selection, or by pointing, +then sweeping with button 1 pressed. +Text may also be selected by double-clicking: +just inside a matched delimiter-pair +with one of +.B {[(<«`'" +on the left and +.B }])>»`'" +on the right, it selects all text within +the pair; at the beginning +or end of a line, it selects the line; within or at the edge of an alphanumeric word, +it selects the word. +.PP +Characters typed on the keyboard replace the selected text; +if this text is not empty, it is placed in a +.I snarf buffer +common to all windows but distinct from that of +.IR sam (1). +.PP +Programs access the text in the window at a single point +maintained automatically by +.IR rio . +The +.I output point +is the location in the text where the next character written by +a program to +.B /dev/cons +will appear; afterwards, the output point is the null string +beyond the new character. +The output point is also the location in the text of the next character +that will be read (directly from the text in the window, +not from an intervening buffer) +by a program from +.BR /dev/cons . +When such a read will occur is, however, under control of +.I rio +and the user. +.PP +In general there is text in the window after the output point, +usually placed there by typing but occasionally by the editing +operations described below. +A pending read of +.B /dev/cons +will block until the text after the output point contains +a newline, whereupon the read may +acquire the text, up to and including the newline. +After the read, as described above, the output point will be at +the beginning of the next line of text. +In normal circumstances, therefore, typed text is delivered +to programs a line at a time. +Changes made by typing or editing before the text is read will not +be seen by the program reading it. +If the program in the window does not read the terminal, +for example if it is a long-running computation, there may +accumulate multiple lines of text after the output point; +changes made to all this text will be seen when the text +is eventually read. +This means, for example, that one may edit out newlines in +unread text to forestall the associated text being read when +the program finishes computing. +This behavior is very different from most systems. +.PP +Even when there are newlines in the output text, +.I rio +will not honor reads if the window is in +.I hold +.IR mode , +which is indicated by a white cursor and blue text and border. +The ESC character toggles hold mode. +Some programs, such as +.IR mail (1), +automatically turn on hold mode to simplify the editing of multi-line text; +type ESC when done to allow +.I mail +to read the text. +.PP +An EOT character (control-D) behaves exactly like newline except +that it is not delivered to a program when read. +Thus on an empty line an EOT serves to deliver an end-of-file indication: +the read will return zero characters. +Like newlines, unread EOTs may be successfully edited out of the text. +The BS character (control-H) erases the character before the selected text. +The ETB character (control-W) erases any nonalphanumeric characters, then +the alphanumeric word just before the selected text. +`Alphanumeric' here means non-blanks and non-punctuation. +The NAK character (control-U) erases the text after the output point, +and not yet read by a program, but not more than one line. +All these characters are typed on the keyboard and hence replace +the selected text; for example, typing a BS with a word selected +places the word in the snarf buffer, removes it from the screen, +and erases the character before the word. +.PP +An ACK character (control-F) or Insert character triggers file name completion +for the preceding string (see +.IR complete (2)). +.PP +Typing a left or right arrow moves the cursor one character in that direction. +Typing an SOH character (control-A) moves the cursor to the beginning of the +current line; an ENQ character (control-E) moves to the end. +.PP +Text may be moved vertically within the window. +A scroll bar on the left of the window shows in its clear portion what fragment of the +total output text is visible on the screen, and in its gray part what +is above or below view; +it measures characters, not lines. +Mousing inside the scroll bar moves text: +clicking button 1 with the mouse pointing inside the scroll bar +brings the line at the top of the +window to the cursor's vertical location; +button 3 takes the line at the cursor to the top of the window; +button 2, treating the scroll bar as a ruler, jumps to the indicated portion +of the stored text. +Holding a button pressed in the scroll bar will cause the text +to scroll continuously until the button is released. +Also, a page down +or down-arrow +scrolls forward +half a window, and page up or up-arrow scrolls back. +Typing the home key scrolls to the top of the window; typing the end key scrolls +to the bottom. +.PP +The DEL character sends an +.L interrupt +note to all processes in the window's process group. +Unlike the other characters, the DEL, VIEW, and up- and down-arrow +keys do not affect the selected text. +The left (right) arrow key moves the selection to one character +before (after) the current selection. +.PP +Normally, written output to a window blocks when +the text reaches the end of the screen; +a button 2 menu item toggles scrolling. +.PP +Other editing operations are selected from a menu on button 2. +The +.B cut +operation deletes the selected text +from the screen and puts it in the snarf buffer; +.B snarf +copies the selected text to the buffer without deleting it; +.B paste +replaces the selected text with the contents of the buffer; +and +.B send +copies the snarf buffer to just after the output point, adding a final newline +if missing. +.B Paste +will sometimes and +.B send +will always place text after the output point; the text so placed +will behave exactly as described above. Therefore when pasting +text containing newlines after the output point, it may be prudent +to turn on hold mode first. +.PP +The +.B plumb +menu item sends the contents of the selection (not the snarf buffer) to the +.IR plumber (4). +If the selection is empty, it sends the white-space-delimited text +containing the selection (typing cursor). +A typical use of this feature is to tell the editor to find the source of an error +by plumbing the file and line information in a compiler's diagnostic. +.SS Raw text windows +Opening or manipulating certain files served by +.IR rio +suppresses some of the services supplied to ordinary text windows. +While the file +.B /dev/mouse +is open, any mouse operations are the responsibility of another program +running in the window. Thus, +.I rio +refrains from maintaining +the scroll bar, +supplying text editing or menus, interpreting the +VIEW key as a request to scroll, and also turns scrolling on. +.PP +The file +.B /dev/consctl +controls interpretation of keyboard input. +In particular, a raw mode may be set: +in a raw-input window, no typed keyboard characters are special, +they are not echoed to the screen, and all are passed +to a program immediately upon reading, instead of being gathered into +lines. +.SS Graphics windows +A program that holds +.B /dev/mouse +and +.B /dev/consctl +open after putting the console in raw mode +has complete control of the window: +it interprets all mouse events, gets all keyboard characters, +and determines what appears on the screen. +.SH FILES +.TF /srv/riowctl.\fIuser\fP.\fIpid\fP +.TP +.B /lib/font/bit/* +font directories +.TP +.B /mnt/wsys +Files served by +.I rio +(also unioned in +.B /dev +in a window's name space, before the terminal's real +.B /dev +files) +.TP +.B /srv/rio.\fIuser\fP.\fIpid\fP +Server end of +.IR rio . +.TP +.B /srv/riowctl.\fIuser\fP.\fIpid\fP +Named pipe for +.I wctl +messages. +.SH SOURCE +.TF /sys/src/cmd/rio +.TP +.B /sys/src/cmd/rio +.TP +.B /rc/bin/label +.TP +.B /rc/bin/window +.TP +.B /rc/bin/wloc +.SH "SEE ALSO" +.IR rio (4), +.IR rc (1), +.IR cpu (1), +.IR sam (1), +.IR mail (1), +.IR proof (1), +.IR graphics (2), +.IR frame (2), +.IR window (2), +.IR notify (2), +.IR cons (3), +.IR draw (3), +.IR mouse (3), +.IR keyboard (6) +.SH BUGS +The standard input of +.I window +is redirected to the newly created window, so there is no way to pipe the output +of a program to the standard input of the new window. +In some cases, +.IR plumb (1) +can be used to work around this limitation. diff --git a/sys/man/1/rm b/sys/man/1/rm new file mode 100755 index 000000000..c5786f92e --- /dev/null +++ b/sys/man/1/rm @@ -0,0 +1,28 @@ +.TH RM 1 +.SH NAME +rm \- remove files +.SH SYNOPSIS +.B rm +[ +.B -fr +] +.I file ... +.SH DESCRIPTION +.I Rm +removes files or directories. +A directory is removed only if it is empty. +Removal of a file requires write permission in its directory, +but neither read nor write permission on the file itself. +The options are +.TP +.B -f +Don't report files that can't be removed. +.TP +.B -r +Recursively delete the +entire contents of a directory +and the directory itself. +.SH SOURCE +.B /sys/src/cmd/rm.c +.SH "SEE ALSO" +.IR remove (2) diff --git a/sys/man/1/rwd b/sys/man/1/rwd new file mode 100755 index 000000000..14e1a57ce --- /dev/null +++ b/sys/man/1/rwd @@ -0,0 +1,161 @@ +.TH RWD 1 +.SH NAME +rwd, conswdir \- maintain remote working directory +.SH SYNOPSIS +.B rwd +.I path +.PP +.B conswdir +[ +.I prog +] +.SH DESCRIPTION +.I Rwd +and +.I conswdir +conspire to keep +.IR rio (4) +and +.IR acme (4) +informed about the current directory on +remote systems during login sessions. +.I Rio +and +.I acme +include this information in plumb messages sent to +.IR plumber (4). +If the remote system's name space is mounted in the +plumber's name space, +the end result is that file paths printed during the session +are plumbable. +.PP +.I Rwd +informs +.IR rio +and +.IR acme +of directory changes. +The name of the remote machine is taken from +the environment variable +.BR $remotesys . +.I Rwd +writes the full path to +.BR /dev/wdir ; +writes the last element of the path, +suffixed by +.BI @ remotesys \fR, +to +.BR /dev/label ; +and when run inside a +.I win +(see +.IR acme (1)) +window, changes the window title to +.IB path /- remotesys +using +.BR /dev/acme/ctl . +.PP +.I Conswdir +copies standard input to standard output, looking for in-band messages +about directory changes. +The messages are of the form: +.IP +.EX +\e033];\fIpath\fP\e007 +.EE +.LP +where +.B \e033 +and +.B \e007 +are ASCII escape and bell characters. +Such messages are removed from the stream and not printed to standard output; +for each such message +.I conswdir +runs +.I prog +(default +.BR /bin/rwd ) +with +.I path +as its only argument. +.SH EXAMPLES +Add this plumbing rule (see +.IR plumb (6)) +in order to run commands in the plumber's name space: +.IP +.EX +# have plumber run command +kind is text +data matches 'Local (.*)' +plumb to none +plumb start rc -c $1 +.EE +.PP +Mount a Unix system in your name space and the plumber's: +.IP +.EX +% 9fs unix +% plumb 'Local 9fs unix' +.EE +.LP +(If you're using acme, execute +.B "Local 9fs unix +with the middle button to mount the Unix system in acme's name space.) +.PP +Connect to the Unix system, processing in-band directory change messages: +.IP +.EX +% ssh unix | aux/conswdir +.EE +.PP +Add this shell function to your +.B .profile +on the Unix system +to generate directory change messages every time a +.B cd +command is executed: +.IP +.EX +H=`hostname | sed 's/\e..*//'` +_cd () { + \ecd $* && + case $- in + *i*) + _dir=`pwd` + echo /n/$H$_dir | awk '{printf("\e033];%s\e007", $1);}' + esac +} +alias cd=_cd +.EE +.PP +The examples described so far only help for relative +path names. Add this plumbing rule to handle rooted names +like +.BR /usr/include/stdio.h : +.IP +.EX +# remote rooted path names +type is text +wdir matches '/n/unix(/.*)?' +data matches '/([.a-zA-Z¡-￿0-9_/\e-]*[a-zA-Z¡-￿0-9_/\e-])('$addr')?' +arg isfile /n/unix/$1 +data set $file +attr add addr=$3 +plumb to edit +plumb client window $editor +.EE +.SH SOURCE +.B /rc/bin/rwd +.br +.B /sys/src/cmd/aux/conswdir.c +.SH SEE ALSO +.IR plumber (4), +.IR plumb (6), +.IR srv (4) +.SH BUGS +This mechanism is clunky, but Unix and SSH +make it hard to build a better one. +.PP +The escape sequence was chosen because +it changes the title on xterm windows. diff --git a/sys/man/1/sam b/sys/man/1/sam new file mode 100755 index 000000000..282448d24 --- /dev/null +++ b/sys/man/1/sam @@ -0,0 +1,891 @@ +.TH SAM 1 +.ds a \fR*\ \fP +.SH NAME +sam, B, sam.save, samterm \- screen editor with structural regular expressions +.SH SYNOPSIS +.B sam +[ +.I option ... +] [ +.I files +] +.PP +.B sam +.B -r +.I machine +.PP +.B sam.save +.PP +.B B +[ +.BI -nnnn +] +.I file ... +.SH DESCRIPTION +.I Sam +is a multi-file editor. +It modifies a local copy of an external file. +The copy is here called a +.IR file . +The files are listed in a menu available through mouse button 3 +or the +.B n +command. +Each file has an associated name, usually the name of the +external file from which it was read, and a `modified' bit that indicates whether +the editor's file agrees with the external file. +The external file is not read into +the editor's file until it first becomes the current file\(emthat to +which editing commands apply\(emwhereupon its menu entry is printed. +The options are +.TF -rmachine +.TP +.B -a +Autoindent. In this mode, when a newline character is typed +in the terminal interface, +.I samterm +copies leading white space on the current line to the new line. +.TP +.B -d +Do not `download' the terminal part of +.IR sam . +Editing will be done with the command language only, as in +.IR ed (1). +.TP +.BI -r " machine +Run the host part remotely +on the specified machine, the terminal part locally. +.TP +.BI -s " path +Start the host part from the specified file on the remote host. +Only meaningful with the +.BI -r +option. +.TP +.BI -t " path +Start the terminal part from the specified file. Useful +for debugging. +.PD +.SS Regular expressions +Regular expressions are as in +.IR regexp (6) +with the addition of +.BR \en +to represent newlines. +A regular expression may never contain a literal newline character. +The empty +regular expression stands for the last complete expression encountered. +A regular expression in +.I sam +matches the longest leftmost substring formally +matched by the expression. +Searching in the reverse direction is equivalent +to searching backwards with the catenation operations reversed in +the expression. +.SS Addresses +An address identifies a substring in a file. +In the following, `character +.IR n ' +means the null string +after the +.IR n -th +character in the file, with 1 the +first character in the file. +`Line +.IR n ' +means the +.IR n -th +match, +starting at the beginning of the file, of the regular expression +.LR .*\en? . +All files always have a current substring, called dot, +that is the default address. +.SS Simple Addresses +.PD 0 +.TP +.BI # n +The empty string after character +.IR n ; +.B #0 +is the beginning of the file. +.TP +.I n +Line +.IR n ; +.B 0 +is the beginning of the file. +.TP +.BI / regexp / +.PD 0 +.TP +.BI ? regexp ? +The substring that matches the regular expression, +found by looking toward the end +.RB ( / ) +or beginning +.RB ( ? ) +of the file, +and if necessary continuing the search from the other end to the +starting point of the search. +The matched substring may straddle +the starting point. +When entering a pattern containing a literal question mark +for a backward search, the question mark should be +specified as a member of a class. +.PD +.TP +.B 0 +The string before the first full line. +This is not necessarily +the null string; see +.B + +and +.B - +below. +.TP +.B $ +The null string at the end of the file. +.TP +.B . +Dot. +.TP +.B \&' +The mark in the file (see the +.B k +command below). +.TP +\fB"\f2regexp\fB"\f1\f1 +Preceding a simple address (default +.BR . ), +refers to the address evaluated in the unique file whose menu line +matches the regular expression. +.PD +.SS Compound Addresses +In the following, +.I a1 +and +.I a2 +are addresses. +.TF a1+a2 +.TP +.IB a1 + a2 +The address +.I a2 +evaluated starting at the end of +.IR a1 . +.TP +.IB a1 - a2 +The address +.I a2 +evaluated looking in the reverse direction +starting at the beginning of +.IR a1 . +.TP +.IB a1 , a2 +The substring from the beginning of +.I a1 +to the end of +.IR a2 . +If +.I a1 +is missing, +.B 0 +is substituted. +If +.I a2 +is missing, +.B $ +is substituted. +.TP +.IB a1 ; a2 +Like +.IB a1 , a2\f1, +but with +.I a2 +evaluated at the end of, and dot set to, +.IR a1 . +.PD +.PP +The operators +.B + +and +.B - +are high precedence, while +.B , +and +.B ; +are low precedence. +.PP +In both +.B + +and +.B - +forms, if +.I a2 +is a line or character address with a missing +number, the number defaults to 1. +If +.I a1 +is missing, +.L . +is substituted. +If both +.I a1 +and +.I a2 +are present and distinguishable, +.B + +may be elided. +.I a2 +may be a regular +expression; if it is delimited by +.LR ? 's, +the effect of the +.B + +or +.B - +is reversed. +.PP +It is an error for a compound address to represent a malformed substring. +Some useful idioms: +.IB a1 +- +\%(\f2a1\fB-+\f1) +selects the line containing +the end (beginning) of a1. +.BI 0/ regexp / +locates the first match of the expression in the file. +(The form +.B 0;// +sets dot unnecessarily.) +.BI ./ regexp /// +finds the second following occurrence of the expression, +and +.BI .,/ regexp / +extends dot. +.SS Commands +In the following, text demarcated by slashes represents text delimited +by any printable +character except alphanumerics. +Any number of +trailing delimiters may be elided, with multiple elisions then representing +null strings, but the first delimiter must always +be present. +In any delimited text, +newline may not appear literally; +.B \en +may be typed for newline; and +.B \e/ +quotes the delimiter, here +.LR / . +Backslash is otherwise interpreted literally, except in +.B s +commands. +.PP +Most commands may be prefixed by an address to indicate their range +of operation. +Those that may not are marked with a +.L * +below. +If a command takes +an address and none is supplied, dot is used. +The sole exception is +the +.B w +command, which defaults to +.BR 0,$ . +In the description, `range' is used +to represent whatever address is supplied. +Many commands set the +value of dot as a side effect. +If so, it is always set to the `result' +of the change: the empty string for a deletion, the new text for an +insertion, etc. (but see the +.B s +and +.B e +commands). +.br +.ne 1.2i +.SS Text commands +.PD 0 +.TP +.BI a/ text / +.TP +or +.TP +.B a +.TP +.I lines of text +.TP +.B . +Insert the text into the file after the range. +Set dot. +.PD +.TP +.B c\fP +.br +.ns +.TP +.B i\fP +Same as +.BR a , +but +.B c +replaces the text, while +.B i +inserts +.I before +the range. +.TP +.B d +Delete the text in the range. +Set dot. +.TP +.BI s/ regexp / text / +Substitute +.I text +for the first match to the regular expression in the range. +Set dot to the modified range. +In +.I text +the character +.B & +stands for the string +that matched the expression. +Backslash behaves as usual unless followed by +a digit: +.BI \e d +stands for the string that matched the +subexpression begun by the +.IR d -th +left parenthesis. +If +.I s +is followed immediately by a +number +.IR n , +as in +.BR s2/x/y/ , +the +.IR n -th +match in the range is substituted. +If the +command is followed by a +.BR g , +as in +.BR s/x/y/g , +all matches in the range +are substituted. +.TP +.BI m " a1 +.br +.ns +.TP +.BI t " a1 +Move +.RB ( m ) +or copy +.RB ( t ) +the range to after +.IR a1 . +Set dot. +.SS Display commands +.PD 0 +.TP +.B p +Print the text in the range. +Set dot. +.TP +.B = +Print the line address and character address of the range. +.TP +.B =# +Print just the character address of the range. +.PD +.SS File commands +.PD 0 +.TP +.BI \*ab " file-list +Set the current file to the first file named in the list +that +.I sam +also has in its menu. +The list may be expressed +.BI < "Plan 9 command" +in which case the file names are taken as words (in the shell sense) +generated by the Plan 9 command. +.TP +.BI \*aB " file-list +Same as +.BR b , +except that file names not in the menu are entered there, +and all file names in the list are examined. +.TP +.B \*an +Print a menu of files. +The format is: +.RS +.TP 11 +.BR ' " or blank +indicating the file is modified or clean, +.TP 11 +.BR - " or \&" + +indicating the file is unread or has been read +(in the terminal, +.B * +means more than one window is open), +.TP 11 +.BR . " or blank +indicating the current file, +.TP 11 +a blank, +.TP 11 +and the file name. +.RE +.TP 0 +.BI \*aD " file-list +Delete the named files from the menu. +If no files are named, the current file is deleted. +It is an error to +.B D +a modified file, but a subsequent +.B D +will delete such a file. +.PD +.SS I/O Commands +.PD 0 +.TP +.BI \*ae " filename +Replace the file by the contents of the named external file. +Set dot to the beginning of the file. +.TP +.BI r " filename +Replace the text in the range by the contents of the named external file. +Set dot. +.TP +.BI w " filename +Write the range (default +.BR 0,$ ) +to the named external file. +.TP +.BI \*af " filename +Set the file name and print the resulting menu entry. +.PP +If the file name is absent from any of these, the current file name is used. +.B e +always sets the file name; +.B r +and +.B w +do so if the file has no name. +.TP +.BI < " Plan 9-command +Replace the range by the standard output of the +Plan 9 command. +.TP +.BI > " Plan 9-command +Send the range to the standard input of the +Plan 9 command. +.TP +.BI | " Plan 9-command +Send the range to the standard input, and replace it by +the standard output, of the +Plan 9 command. +.TP +.BI \*a! " Plan 9-command +Run the +Plan 9 command. +.TP +.BI \*acd " directory +Change working directory. +If no directory is specified, +.B $home +is used. +.PD +.PP +In any of +.BR < , +.BR > , +.B | +or +.BR ! , +if the +.I Plan 9 command +is omitted the last +.I Plan 9 command +(of any type) is substituted. +If +.I sam +is +.I downloaded +(using the mouse and raster display, i.e. not using option +.BR -d ), +.B ! +sets standard input to +.BR /dev/null , +and otherwise +unassigned output +.RB ( stdout +for +.B ! +and +.BR > , +.B stderr +for all) is placed in +.B /tmp/sam.err +and the first few lines are printed. +.SS Loops and Conditionals +.PD 0 +.TP +.BI x/ regexp / " command +For each match of the regular expression in the range, run the command +with dot set to the match. +Set dot to the last match. +If the regular +expression and its slashes are omitted, +.L /.*\en/ +is assumed. +Null string matches potentially occur before every character +of the range and at the end of the range. +.TP +.BI y/ regexp / " command +Like +.BR x , +but run the command for each substring that lies before, between, +or after +the matches that would be generated by +.BR x . +There is no default regular expression. +Null substrings potentially occur before every character +in the range. +.TP +.BI \*aX/ regexp / " command +For each file whose menu entry matches the regular expression, +make that the current file and +run the command. +If the expression is omitted, the command is run +in every file. +.TP +.BI \*aY/ regexp / " command +Same as +.BR X , +but for files that do not match the regular expression, +and the expression is required. +.TP +.BI g/ regexp / " command +.br +.ns +.TP +.BI v/ regexp / " command +If the range contains +.RB ( g ) +or does not contain +.RB ( v ) +a match for the expression, +set dot to the range and run the command. +.PP +These may be nested arbitrarily deeply, but only one instance of either +.B X +or +.B Y +may appear in a \%single command. +An empty command in an +.B x +or +.B y +defaults to +.BR p ; +an empty command in +.B X +or +.B Y +defaults to +.BR f . +.B g +and +.B v +do not have defaults. +.PD +.SS Miscellany +.TF (empty) +.TP +.B k +Set the current file's mark to the range. Does not set dot. +.TP +.B \*aq +Quit. +It is an error to quit with modified files, but a second +.B q +will succeed. +.TP +.BI \*au " n +Undo the last +.I n +(default 1) +top-level commands that changed the contents or name of the +current file, and any other file whose most recent change was simultaneous +with the current file's change. +Successive +.BR u 's +move further back in time. +The only commands for which u is ineffective are +.BR cd , +.BR u , +.BR q , +.B w +and +.BR D . +If +.I n +is negative, +.B u +`redoes,' undoing the undo, going forwards in time again. +.TP +(empty) +If the range is explicit, set dot to the range. +If +.I sam +is downloaded, the resulting dot is selected on the screen; +otherwise it is printed. +If no address is specified (the +command is a newline) dot is extended in either direction to +line boundaries and printed. +If dot is thereby unchanged, it is set to +.B .+1 +and printed. +.PD +.SS Grouping and multiple changes +Commands may be grouped by enclosing them in braces +.BR {} . +Commands within the braces must appear on separate lines (no backslashes are +required between commands). +Semantically, an opening brace is like a command: +it takes an (optional) address and sets dot for each sub-command. +Commands within the braces are executed sequentially, but changes made +by one command are not visible to other commands (see the next +paragraph). +Braces may be nested arbitrarily. +.PP +When a command makes a number of changes to a file, as in +.BR x/re/c/text/ , +the addresses of all changes to the file are computed in the original file. +If the changes are in sequence, +they are applied to the file. +Successive insertions at the same address are catenated into a single +insertion composed of the several insertions in the order applied. +.SS The terminal +What follows refers to behavior of +.I sam +when downloaded, that is, when +operating as a display editor on a raster display. +This is the default +behavior; invoking +.I sam +with the +.B -d +(no download) option provides access +to the command language only. +.PP +Each file may have zero or more windows open. +Each window is equivalent +and is updated simultaneously with changes in other windows on the same file. +Each window has an independent value of dot, indicated by a highlighted +substring on the display. +Dot may be in a region not within +the window. +There is usually a `current window', +marked with a dark border, to which typed text and editing +commands apply. +Text may be typed and edited as in +.IR rio (1); +also the escape key (ESC) selects (sets dot to) text typed +since the last mouse button hit. +.PP +The button 3 menu controls window operations. +The top of the menu +provides the following operators, each of which uses one or +more +.IR rio -like +cursors to prompt for selection of a window or sweeping +of a rectangle. +`Sweeping' a null rectangle gets a large window, disjoint +from the command window or the whole screen, depending on +where the null rectangle is. +.TF resize +.TP +.B new +Create a new, empty file. +.TP +.B zerox +Create a copy of an existing window. +.TP +.B resize +As in +.IR rio . +.TP +.B close +Delete the window. +In the last window of a file, +.B close +is equivalent to a +.B D +for the file. +.TP +.B write +Equivalent to a +.B w +for the file. +.PD +.PP +Below these operators is a list of available files, starting with +.BR ~~sam~~ , +the command window. +Selecting a file from the list makes the most recently +used window on that file current, unless it is already current, in which +case selections cycle through the open windows. +If no windows are open +on the file, the user is prompted to open one. +Files other than +.B ~~sam~~ +are marked with one of the characters +.B -+* +according as zero, one, or more windows +are open on the file. +A further mark +.L . +appears on the file in the current window and +a single quote, +.BR ' , +on a file modified since last write. +.PP +The command window, created automatically when +.B sam +starts, is an ordinary window except that text typed to it +is interpreted as commands for the editor rather than passive text, +and text printed by editor commands appears in it. +The behavior is like +.IR rio , +with an `output point' that separates commands being typed from +previous output. +Commands typed in the command window apply to the +current open file\(emthe file in the most recently +current window. +.SS Manipulating text +Button 1 changes selection, much like +.IR rio . +Pointing to a non-current window with button 1 makes it current; +within the current window, button 1 selects text, thus setting dot. +Double-clicking selects text to the boundaries of words, lines, +quoted strings or bracketed strings, depending on the text at the click. +.PP +Button 2 provides a menu of editing commands: +.TF /regexp +.TP +.B cut +Delete dot and save the deleted text in the snarf buffer. +.TP +.B paste +Replace the text in dot by the contents of the snarf buffer. +.TP +.B snarf +Save the text in dot in the snarf buffer. +.TP +.B plumb +Send the text in the selection as a plumb +message. If the selection is empty, +the white-space-delimited block of text is sent as a plumb message +with a +.B click +attribute defining where the selection lies (see +.IR plumb (6)). +.TP +.B look +Search forward for the next occurrence of the literal text in dot. +If dot is the null string, the text in the snarf buffer is +used. +The snarf buffer is unaffected. +.TP +.B +Exchange snarf buffers with +.IR rio . +.TP +.BI / regexp +Search forward for the next match of the last regular expression +typed in a command. +(Not in command window.) +.TP +.B send +Send the text in dot, or the snarf buffer if +dot is the null string, as if it were typed to the command window. +Saves the sent text in the snarf buffer. +(Command window only.) +.PD +.SS External communication +.I Sam +listens to the +.B edit +plumb port. +If plumbing is not active, +on invocation +.I sam +creates a named pipe +.BI /srv/sam. user +which acts as an additional source of commands. Characters written to +the named pipe are treated as if they had been typed in the command window. +.PP +.I B +is a shell-level command that causes an instance of +.I sam +running on the same terminal to load the named +.IR files . +.I B +uses either plumbing or the named pipe, whichever service is available. +If plumbing is not enabled, +the option allows a line number to be specified for +the initial position to display in the last named file +(plumbing provides a more general mechanism for this ability). +.SS Abnormal termination +If +.I sam +terminates other than by a +.B q +command (by hangup, deleting its window, etc.), modified +files are saved in an +executable file, +.BR $home/sam.save . +This program, when executed, asks whether to write +each file back to a external file. +The answer +.L y +causes writing; anything else skips the file. +.SH FILES +.TF /sys/src/cmd/samterm +.TP +.B $home/sam.save +.TP +.B $home/sam.err +.TP +.B /sys/lib/samsave +the program called to unpack +.BR $home/sam.save . +.SH SOURCE +.TF /sys/src/cmd/samterm +.TP +.B /sys/src/cmd/sam +source for +.I sam +itself +.TP +.B /sys/src/cmd/samterm +source for the separate terminal part +.TP +.B /rc/bin/B +.SH SEE ALSO +.IR ed (1), +.IR sed (1), +.IR grep (1), +.IR rio (1), +.IR regexp (6). +.PP +Rob Pike, +``The text editor sam''. diff --git a/sys/man/1/secstore b/sys/man/1/secstore new file mode 100755 index 000000000..113db5a92 --- /dev/null +++ b/sys/man/1/secstore @@ -0,0 +1,225 @@ +.TH SECSTORE 1 +.SH NAME +aescbc, ipso, secstore \- secstore commands +.SH SYNOPSIS +.B auth/secstore +[ +.B -cinv +] [ +.B -(g|G) +.I getfile +] [ +.B -p +.I putfile +] [ +.B -r +.I rmfile +] [ +.B -s +.I server +] [ +.B -u +.I user +] +.PP +.B auth/aescbc +-e +[ -in ] +.I ciphertext +.br +.B auth/aescbc +-d +[ -in ] +.I cleartext +.PP +.B ipso +[ +.B -a -e -l -f -s +] [ +.I file +\&... +] +.SH DESCRIPTION +.I Secstore +authenticates to a secure-store server +using a password and optionally a hardware token, +then saves or retrieves a file. +This is intended to be a credentials store (public/private keypairs, +passwords, and other secrets) for a factotum. +.PP +Option +.B -c +prompts for a password change. +.PP +Option +.B -g +retrieves a file to the local directory; +option +.B -G +writes it to standard output instead. +Specifying +.I getfile +of +.L \&. +will send to standard output +a list of remote files with dates, lengths and SHA1 hashes. +.PP +Option +.B -i +says that the password should be read from standard input +instead of from +.BR /dev/cons . +.PP +Option +.B -n +says that the password should be read from NVRAM +(see +.IR authsrv (2)) +instead of from +.BR /dev/cons . +.PP +Option +.B -p +stores a file on the secstore. +.PP +Option +.B -r +removes a file from the secstore. +.PP +The server is +.BR tcp!$auth!secstore , +or the server specified by option +.BR -s . +.PP +Option +.B -u +access the secure-store files belonging to +.IR user . +.PP +Option +.B -v +produces more verbose output, in particular providing a few +bits of feedback to help the user detect mistyping. +.PP +For example, to add a secret to the file read by +.IR factotum (4) +at startup, open a new window, type +.LP +.EX + % ramfs -p; cd /tmp + % auth/secstore -g factotum + secstore password: + % echo 'key proto=apop dom=x.com user=ehg !password=hi' >> factotum + % auth/secstore -p factotum + secstore password: + % read -m factotum > /mnt/factotum/ctl +.EE +.LP +and delete the window. +The first line creates an ephemeral memory-resident workspace, +invisible to others and automatically removed when the window is deleted. +The next three commands fetch the persistent copy of the secrets, +append a new secret, +and save the updated file back to secstore. +The final command loads the new secret into the running factotum. +.PP +The +.I ipso +command packages this sequence into a convenient script to simplify editing of +.I files +stored on a secure store. +It copies the named +.I files +into a local +.IR ramfs (4) +and invokes +.IR acme (1) +on them. When the editor exits, +.I ipso +prompts the user to confirm copying modifed or newly created files back to +.I secstore. +If no +.I file +is mentioned, +.I ipso +grabs all the user's files from +.I secstore +for editing. +.PP +By default, +.I ipso +will edit the +.I secstore +files and, if +one of them is named +.BR factotum , +flush current keys from factotum and load +the new ones from the file. +If the +.BR -e , +.BR -f , +or +.BR -l +options are given, +.I ipso +will just perform only the requested operations, i.e., +edit, flush, and/or load. +.PP +The +.B -s +option of +.I ipso +invokes +.IR sam (1) +as the editor insted of +.BR acme ; +the +.B -a +option provides a similar service for files encrypted by +.I aescbc +.RI ( q.v. ). +With the +.B -a +option, the full rooted pathname of the +.I file +must be specified and all +.I files +must be encrypted with the same key. +Also with +.BR -a , +newly created files are ignored. +.PP +.I Aescbc +encrypts (under +.LR -e ) +and decrypts (under +.LR -d ) +using AES (Rijndael) in cipher block chaining (CBC) mode. +Options +.L i +and +.L n +are as per +.IR secstore , +except that +.L i +reads from file descriptor 3. +.SH SOURCE +.B /rc/bin/ipso +.br +.B /sys/src/cmd/auth/secstore +.SH SEE ALSO +.IR factotum (4), +.IR secstore (8) +.SH BUGS +There is deliberately no backup of files on the secstore, so +.B -r +(or a disk crash) is irrevocable. You are advised to store +important secrets in a second location. +.PP +When using +.IR ipso , +secrets will appear as plain text in the editor window, +so use the command in private. diff --git a/sys/man/1/sed b/sys/man/1/sed new file mode 100755 index 000000000..6bb2e6123 --- /dev/null +++ b/sys/man/1/sed @@ -0,0 +1,389 @@ +.TH SED 1 +.SH NAME +sed \- stream editor +.SH SYNOPSIS +.B sed +[ +.B -n +] +[ +.B -g +] +[ +.B -e +.I script +] +[ +.B -f +.I sfile +] +[ +.I file ... +] +.SH DESCRIPTION +.I Sed +copies the named +.I files +(standard input default) to the standard output, +edited according to a script of commands. +The +.B -f +option causes the script to be taken from file +.IR sfile ; +these options accumulate. +If there is just one +.B -e +option and no +.BR -f 's, +the option +.B -e +may be omitted. +The +.B -n +option suppresses the default output; +.B -g +causes all substitutions to be global, as if suffixed +.BR g . +.PP +A script consists of editing commands, one per line, +of the following form: +.IP +[\fIaddress\fR [\fL,\fI address\fR] ] \fIfunction\fR [\fIargument\fR ...] [\fL;\fP] +.PP +In normal operation +.I sed +cyclically copies a line of input into a +.I pattern space +(unless there is something left after +a +.L D +command), +applies in sequence +all commands whose +.I addresses +select that pattern space, +and at the end of the script copies the pattern space +to the standard output (except under +.BR -n ) +and deletes the pattern space. +.PP +An +.I address +is either a decimal number that counts +input lines cumulatively across files, a +.L $ +that +addresses the last line of input, or a context address, +.BI / regular-expression / \f1, +in the style of +.IR regexp (6), +with the added convention that +.L \en +matches a +newline embedded in the pattern space. +.PP +A command line with no addresses selects every pattern space. +.PP +A command line with +one address selects each pattern space that matches the address. +.PP +A command line with +two addresses selects the inclusive range from the first +pattern space that matches the first address through +the next pattern space that matches +the second. +(If the second address is a number less than or equal +to the line number first selected, only one +line is selected.) +Thereafter the process is repeated, looking again for the +first address. +.PP +Editing commands can be applied to non-selected pattern +spaces by use of the negation function +.L ! +(below). +.PP +An argument denoted +.I text +consists of one or more lines, +all but the last of which end with +.L \e +to hide the +newline. +Backslashes in text are treated like backslashes +in the replacement string of an +.L s +command, +and may be used to protect initial blanks and tabs +against the stripping that is done on +every script line. +.PP +An argument denoted +.I rfile +or +.I wfile +must terminate the command +line and must be preceded by exactly one blank. +Each +.I wfile +is created before processing begins. +There can be at most 120 distinct +.I wfile +arguments. +.TP \w'\fL!\ \fIfunction\fLXXX'u +.B a\e +.br +.ns +.TP +.I text +Append. +Place +.I text +on the output before +reading the next input line. +.TP +.BI b " label" +Branch to the +.B : +command bearing the +.IR label . +If +.I label +is empty, branch to the end of the script. +.TP +.B c\e +.br +.ns +.TP +.I text +Change. +Delete the pattern space. +With 0 or 1 address or at the end of a 2-address range, place +.I text +on the output. +Start the next cycle. +.TP +.B d +Delete the pattern space. +Start the next cycle. +.TP +.B D +Delete the initial segment of the +pattern space through the first newline. +Start the next cycle. +.TP +.B g +Replace the contents of the pattern space +by the contents of the hold space. +.TP +.B G +Append the contents of the hold space to the pattern space. +.TP +.B h +Replace the contents of the hold space by the contents of the pattern space. +.TP +.B H +Append the contents of the pattern space to the hold space. +.ne 3 +.TP +.B i\e +.br +.ns +.TP +.I text +Insert. +Place +.I text +on the standard output. +.TP +.B n +Copy the pattern space to the standard output. +Replace the pattern space with the next line of input. +.TP +.B N +Append the next line of input to the pattern space +with an embedded newline. +(The current line number changes.) +.TP +.B p +Print. +Copy the pattern space to the standard output. +.TP +.B P +Copy the initial segment of the pattern space through +the first newline to the standard output. +.TP +.B q +Quit. +Branch to the end of the script. +Do not start a new cycle. +.TP +.BI r " rfile" +Read the contents of +.IR rfile . +Place them on the output before reading +the next input line. +.TP +.B s/\fIregular-expression\fP/\fIreplacement\fP/\fIflags +Substitute the +.I replacement +string for instances of the +.I regular-expression +in the pattern space. +Any character may be used instead of +.LR / . +For a fuller description see +.IR regexp (6). +.I Flags +is zero or more of +.RS +.TP +.B g +Global. +Substitute for all non-overlapping instances of the +.I regular expression +rather than just the +first one. +.TP +.B p +Print the pattern space if a replacement was made. +.TP +.BI w " wfile" +Write. +Append the pattern space to +.I wfile +if a replacement +was made. +.RE +.TP +.BI t " label" +Test. +Branch to the +.L : +command bearing the +.I label +if any +substitutions have been made since the most recent +reading of an input line or execution of a +.LR t . +If +.I label +is empty, branch to the end of the script. +.TP +.B w +.I wfile +.br +Write. +Append the pattern space to +.IR wfile . +.TP +.B x +Exchange the contents of the pattern and hold spaces. +.TP +.B y/\fIstring1\fP/\fIstring2\fP/ +Transform. +Replace all occurrences of characters in +.I string1 +with the corresponding character in +.IR string2 . +The lengths of +.I +string1 +and +.I string2 +must be equal. +.TP +.BI ! "function" +Don't. +Apply the +.I function +(or group, if +.I function +is +.LR { ) +only to lines +.I not +selected by the address(es). +.TP +.B # +Comment. +Ignore the rest of the line. +.TP +.BI : " label" +This command does nothing; it bears a +.I label +for +.B b +and +.B t +commands to branch to. +.TP +.B = +Place the current line number on the standard output as a line. +.TP +.B { +Execute the following commands through a matching +.L } +only when the pattern space is selected. +.TP +.B " " +An empty command is ignored. +.ne 4 +.SH EXAMPLES +.TP +.B sed 10q file +Print the first 10 lines of the file. +.TP +.B sed '/^$/d' +Delete empty lines from standard input. +.TP +.B sed 's/UNIX/& system/g' +Replace every instance of +.L UNIX +by +.LR "UNIX system" . +.PP +.EX +sed 's/ *$// \fRdrop trailing blanks\fP +/^$/d \fRdrop empty lines\fP +s/ */\e \fRreplace blanks by newlines\fP +/g +/^$/d' chapter* +.EE +.ns +.IP +Print the files +.BR chapter1 , +.BR chapter2 , +etc. one word to a line. +.PP +.EX +nroff -ms manuscript | sed ' +${ + /^$/p \fRif last line of file is empty, print it\fP +} +//N \fRif current line is empty, append next line\fP +/^\en$/D' \fRif two lines are empty, delete the first\fP +.EE +.ns +.IP +Delete all but one of each group of empty lines from a +formatted manuscript. +.SH SOURCE +.B /sys/src/cmd/sed.c +.SH SEE ALSO +.IR ed (1), +.IR grep (1), +.IR awk (1), +.IR lex (1), +.IR sam (1), +.IR regexp (6) +.br +L. E. McMahon, +`SED \(em A Non-interactive Text Editor', +Unix Research System Programmer's Manual, Volume 2. +.SH BUGS +If input is from a pipe, buffering may consume +characters beyond a line on which a +.L q +command is executed. diff --git a/sys/man/1/seq b/sys/man/1/seq new file mode 100755 index 000000000..60d1f12a9 --- /dev/null +++ b/sys/man/1/seq @@ -0,0 +1,75 @@ +.TH SEQ 1 +.SH NAME +seq \- print sequences of numbers +.SH SYNOPSIS +.B seq +[ +.B -w +] +[ +.BI -f format +] +[ +.I first +[ +.I incr +] +] +.I last +.SH DESCRIPTION +.I Seq +prints a sequence of numbers, one per line, from +.I first +(default 1) to as near +.I last +as possible, in increments of +.I incr +(default 1). +The loop is: +.sp +.EX + for(val = min; val <= max; val += incr) print val; +.EE +.sp +The numbers are interpreted as floating point. +.PP +Normally integer values are printed as decimal integers. +The options are +.TP "\w'\fL-f \fIformat\fLXX'u" +.BI -f format +Use the +.IR print (2)-style +.I format +.IR print +for printing each (floating point) number. +The default is +.LR %g . +.TP +.B -w +Equalize the widths of all numbers by padding with +leading zeros as necessary. +Not effective with option +.BR -f , +nor with numbers in exponential notation. +.SH EXAMPLES +.TP +.L +seq 0 .05 .1 +Print +.BR "0 0.05 0.1" +(on separate lines). +.TP +.L +seq -w 0 .05 .1 +Print +.BR "0.00 0.05 0.10" . +.SH SOURCE +.B /sys/src/cmd/seq.c +.SH BUGS +Option +.B -w +always surveys every value in advance. +Thus +.L +seq -w 1000000000 +is a painful way to get an `infinite' sequence. diff --git a/sys/man/1/size b/sys/man/1/size new file mode 100755 index 000000000..cd7ba9b84 --- /dev/null +++ b/sys/man/1/size @@ -0,0 +1,28 @@ +.TH SIZE 1 +.SH NAME +size \- print size of executable files +.SH SYNOPSIS +.B size +[ +.I file ... +] +.SH DESCRIPTION +.I Size +prints the size of the segments for each of the argument executable files +(default +.BR v.out ). +The format is +.IP +.IB textsize t ++ +.IB datasize d ++ +.IB bsssize b += +.I total +.PP +where the numbers are in bytes. +.SH SOURCE +.B /sys/src/cmd/size.c +.SH "SEE ALSO +.IR a.out (6) diff --git a/sys/man/1/sleep b/sys/man/1/sleep new file mode 100755 index 000000000..cc7d49218 --- /dev/null +++ b/sys/man/1/sleep @@ -0,0 +1,33 @@ +.TH SLEEP 1 +.SH NAME +sleep \- suspend execution for an interval +.SH SYNOPSIS +.B sleep +.I time +.SH DESCRIPTION +.I Sleep +suspends execution for +.I time +seconds. +.I Time +may be floating-point. +.SH EXAMPLES +Execute a command +100 seconds hence. +.IP +.EX +{sleep 100; command}& +.EE +.PP +Repeat a command every 30 seconds. +.IP +.EX +while (){ + command + sleep 30 +} +.EE +.SH SOURCE +.B /sys/src/cmd/sleep.c +.SH "SEE ALSO" +.IR sleep (2) diff --git a/sys/man/1/sort b/sys/man/1/sort new file mode 100755 index 000000000..168e4dd19 --- /dev/null +++ b/sys/man/1/sort @@ -0,0 +1,262 @@ +.TH SORT 1 +.SH NAME +sort \- sort and/or merge files +.SH SYNOPSIS +.B sort +[ +.BI -cmuMbdf\&inrwt x +] +[ +.BI + pos1 +[ +.BI - pos2 +] ... +] ... +[ +.B -k +.I pos1 +[ +.I ,pos2 +] +] ... +.br +\h'0.5in +[ +.B -o +.I output +] +[ +.B -T +.I dir +\&... +] +[ +.I option +\&... +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Sort\^ +sorts +lines of all the +.I files +together and writes the result on +the standard output. +If no input files are named, the standard input is sorted. +.PP +The default sort key is an entire line. +Default ordering is +lexicographic by runes. +The ordering is affected globally by the following options, +one or more of which may appear. +.TP +.B -M +Compare as months. +The first three +non-white space characters +of the field +are folded +to upper case +and compared +so that +.L JAN +precedes +.LR FEB , +etc. +Invalid fields +compare low to +.LR JAN . +.TP +.B -b +Ignore leading white space (spaces and tabs) in field comparisons. +.TP +.B -d +`Phone directory' order: +only letters, +accented letters, +digits and white space +are significant in comparisons. +.TP +.B -f +Fold lower case +letters onto upper case. +Accented characters are folded to their +non-accented upper case form. +.TP +.B -i +Ignore characters outside the +.SM ASCII +range 040-0176 +in non-numeric comparisons. +.TP +.B -w +Like +.BR -i , +but ignore only tabs and spaces. +.TP +.B -n +An initial numeric string, +consisting of optional white space, +optional plus or minus sign, +and zero or more digits with optional decimal point, +is sorted by arithmetic value. +.TP +.B -g +Numbers, like +.B -n +but with optional +.BR e -style +exponents, are sorted by value. +.TP +.B -r +Reverse the sense of comparisons. +.TP +.BI -t x\^ +`Tab character' separating fields is +.IR x . +.PP +The notation +.BI + "pos1\| " - pos2\^ +restricts a sort key to a field beginning at +.I pos1\^ +and ending just before +.IR pos2 . +.I Pos1\^ +and +.I pos2\^ +each have the form +.IB m . n\f1, +optionally followed by one or more of the flags +.BR Mbdfginr , +where +.I m\^ +tells a number of fields to skip from the beginning of the line and +.I n\^ +tells a number of characters to skip further. +If any flags are present they override all the global +ordering options for this key. +A missing +.BI \&. n\^ +means +.BR \&.0 ; +a missing +.BI - pos2\^ +means the end of the line. +Under the +.BI -t x\^ +option, fields are strings separated by +.IR x ; +otherwise fields are +non-empty strings separated by white space. +White space before a field +is part of the field, except under option +.BR -b . +A +.B b +flag may be attached independently to +.IR pos1 +and +.IR pos2. +.PP +The notation +.B -k +.IR pos1 [, pos2 ] +is how POSIX +.I sort +defines fields: +.I pos1 +and +.I pos2 +have the same format but different meanings. +The value of +.I m\^ +is origin 1 instead of origin 0 +and a missing +.BI \&. n\^ +in +.I pos2 +is the end of the field. +.PP +When there are multiple sort keys, later keys +are compared only after all earlier keys +compare equal. +Lines that otherwise compare equal are ordered +with all bytes significant. +.PP +These option arguments are also understood: +.TP \w'\fL-z\fIrecsize\fLXX'u +.B -c +Check that the single input file is sorted according to the ordering rules; +give no output unless the file is out of sort. +.TP +.B -m +Merge; assume the input files are already sorted. +.TP +.B -u +Suppress all but one in each +set of equal lines. +Ignored bytes +and bytes outside keys +do not participate in +this comparison. +.TP +.B -o +The next argument is the name of an output file +to use instead of the standard output. +This file may be the same as one of the inputs. +.TP +.BI -T dir +Put temporary files in +.I dir +rather than in +.BR /tmp . +.ne 4 +.SH EXAMPLES +.TP +.L sort -u +0f +0 list +Print in alphabetical order all the unique spellings +in a list of words +where capitalized words differ from uncapitalized. +.TP +.L sort -t: +1 /adm/users +Print the users file +sorted by user name +(the second colon-separated field). +.TP +.L sort -umM dates +Print the first instance of each month in an already sorted file. +Options +.B -um +with just one input file make the choice of a +unique representative from a set of equal lines predictable. +.TP +.L +grep -n '^' input | sort -t: +1f +0n | sed 's/[0-9]*://' +A stable sort: input lines that compare equal will +come out in their original order. +.SH FILES +.BI /tmp/sort. . +.SH SOURCE +.B /sys/src/cmd/sort.c +.SH SEE ALSO +.IR uniq (1), +.IR look (1) +.SH DIAGNOSTICS +.I Sort +comments and exits with non-null status for various trouble +conditions and for disorder discovered under option +.BR -c . +.SH BUGS +An external null character can be confused +with an internally generated end-of-field character. +The result can make a sub-field not sort +less than a longer field. +.PP +Some of the options, e.g. +.B -i +and +.BR -M , +are hopelessly provincial. diff --git a/sys/man/1/spell b/sys/man/1/spell new file mode 100755 index 000000000..62f621a8b --- /dev/null +++ b/sys/man/1/spell @@ -0,0 +1,96 @@ +.TH SPELL 1 +.SH NAME +spell, sprog \- find spelling errors +.SH SYNOPSIS +.B spell +[ +.I options +] +\&... +[ +.I file +] +\&... +.PP +.B aux/sprog +[ +.I options +] +[ +.B -f +.I file +] +.SH DESCRIPTION +.I Spell +looks up words from the named +.I files +(standard input default) +in a spelling list and places +possible misspellings\(emwords +not sanctioned there\(emon the standard output. +.PP +.I Spell +ignores constructs of +.IR troff (1) +and its standard preprocessors. +It understands these options: +.TP +.B -b +Check British spelling. +.TP +.B -v +Print all words not literally in the spelling list, with +derivations. +.TP +.B -x +Print on standard error, marked with +.LR = , +every stem as it is looked up in the spelling list, +along with its affix classes. +.PP +As a matter of policy, +.I spell +does not admit multiple spellings of the same word. +Variants that follow general rules are preferred +over those that don't, even when the unruly spelling is +more common. +Thus, in American usage, `modelled', `sizeable', and `judgment' are +rejected in favor of `modeled', `sizable', and `judgement'. +Agglutinated variants are shunned: `crewmember' and `backyard' +cede to `crew member' and `back yard' (noun) or `back-yard' +(adjective). +.SH FILES +.TF \fL/sys/lib/brspell +.TP +.B /sys/lib/amspell +American spelling list +.TP +.B /sys/lib/brspell +British spelling list +.TP +.B /bin/aux/sprog +The actual spelling checker. +It expects one word per line on standard input, +and takes the same arguments as +.IR spell . +.SH SOURCE +.TF /sys/src/cmd/spell +.TP +.B /rc/bin/spell +the script +.TP +.B /sys/src/cmd/spell +source for +.I sprog +.SH SEE ALSO +.IR deroff (1) +.SH BUGS +The heuristics of +.IR deroff (1) +used to excise formatting information are imperfect. +.PP +The spelling list's coverage is uneven; +in particular biology, medicine, and chemistry, and +perforce proper names, +not to mention languages other than English, +are covered very lightly. diff --git a/sys/man/1/spin b/sys/man/1/spin new file mode 100755 index 000000000..fd30b024b --- /dev/null +++ b/sys/man/1/spin @@ -0,0 +1,331 @@ +.TH SPIN 1 +.SH NAME +spin - verification tool for models of concurrent systems +.SH SYNOPSIS +.B spin +.B -a +[ +.B -m +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +[ +.B -bglmprsv +] +[ +.BI -n N +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -c +[ +.B -t +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -d +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -f +.I ltl +.PP +.B spin +.B -F +.I file +.PP +.B spin +.B -i +[ +.B -bglmprsv +] +[ +.BI -n N +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -M +[ +.B -t +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.BR -t [ \fIN ] +[ +.B -bglmprsv +] +[ +.BI -j N +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -V +.SH DESCRIPTION +.I Spin +is a tool for analyzing the logical consistency of +asynchronous systems, specifically distributed software +amd communication protocols. +A verification model of the system is first specified +in a guarded command language called +.IR Promela . +This specification language, described in the reference, +allows for the modeling of dynamic creation of +asynchronous processes, +nondeterministic case selection, loops, gotos, local and +global variables. +It also allows for a concise specification of logical +correctness requirements, including, but not restricted +to requirements expressed in linear temporal logic. +.PP +Given a Promela model stored in +.IR file , +.I spin +can perform interactive, guided, or random simulations +of the system's execution. +It can also generate a C program that performs an exhaustive +or approximate verification of the correctness requirements +for the system. +. +.TP +.B -a +Generate a verifier (model checker) for the specification. +The output is written into a set of C files, named +.BR pan.[cbhmt] , +that can be compiled +.RB ( "pcc pan.c" ) +to produce an executable verifier. +The online +.I spin +manuals (see below) contain +the details on compilation and use of the verifiers. +. +.TP +.B -c +Produce an ASCII approximation of a message sequence +chart for a random or guided (when combined with +.BR -t ) +simulation run. See also option +.BR -M . +. +.TP +.B -d +Produce symbol table information for the model specified in +.IR file . +For each Promela object this information includes the type, name and +number of elements (if declared as an array), the initial +value (if a data object) or size (if a message channel), the +scope (global or local), and whether the object is declared as +a variable or as a parameter. For message channels, the data types +of the message fields are listed. +For structure variables, the third field defines the +name of the structure declaration that contains the variable. +. +.TP +.BI -f " ltl" +Translate the LTL formula +.I ltl +into a +.I never +claim. +.br +This option reads a formula in LTL syntax from the second argument +and translates it into Promela syntax (a +.I never +claim, which is Promela's +equivalent of a Büchi Automaton). +The LTL operators are written: +.B [] +(always), +.B <> +(eventually), +and +.B U +(strong until). There is no +.B X +(next) operator, to secure +compatibility with the partial order reduction rules that are +applied during the verification process. +If the formula contains spaces, it should be quoted to form a +single argument to the +.I spin +command. +. +.TP +.BI -F " file" +Translate the LTL formula stored in +.I file +into a +.I never +claim. +.br +This behaves identically to option +.B -f +but will read the formula from the +.I file +instead of from the command line. +The file should contain the formula as the first line. Any text +that follows this first line is ignored, so it can be used to +store comments or annotation on the formula. +(On some systems the quoting conventions of the shell complicate +the use of option +.BR -f . +Option +.B -F +is meant to solve those problems.) +. +.TP +.B -i +Perform an interactive simulation, prompting the user at +every execution step that requires a nondeterministic choice +to be made. The simulation proceeds without user intervention +when execution is deterministic. +. +.TP +.B -M +Produce a message sequence chart in Postscript form for a +random simulation or a guided simulation +(when combined with +.BR -t ), +for the model in +.IR file , +and write the result into +.IR file.ps . +See also option +.BR -c . +. +.TP +.B -m +Changes the semantics of send events. +Ordinarily, a send action will be (blocked) if the +target message buffer is full. +With this option a message sent to a full buffer is lost. +. +.TP +.BI -n N +Set the seed for a random simulation to the integer value +.IR N . +There is no space between the +.B -n +and the integer +.IR N . +. +.TP +.B -t +Perform a guided simulation, following the error trail that +was produces by an earlier verification run, see the online manuals +for the details on verification. +. +.TP +.B -V +Prints the +.I spin +version number and exits. +. +.PP +With only a filename as an argument and no options, +.I spin +performs a random simulation of the model specified in +the file (standard input is the default if the filename is omitted). +If option +.B -i +is added, the simulation is +.IR interactive , +or if option +.B -t +is added, the simulation is +.IR guided . +.PP +The simulation normally does not generate output, except what is generated +explicitly by the user within the model with +.I printf +statements, and some details about the final state that is +reached after the simulation completes. +The group of options +.B -bglmprsv +sets the desired level of information that the user wants +about a random, guided, or interactive simulation run. +Every line of output normally contains a reference to the source +line in the specification that generated it. +. +.TP +.B -b +Suppress the execution of +.I printf +statements within the model. +.TP +.B -g +Show at each time step the current value of global variables. +.TP +.B -l +In combination with option +.BR -p , +show the current value of local variables of the process. +.TP +.B -p +Show at each simulation step which process changed state, +and what source statement was executed. +.TP +.B -r +Show all message-receive events, giving +the name and number of the receiving process +and the corresponding the source line number. +For each message parameter, show +the message type and the message channel number and name. +.TP +.B -s +Show all message-send events. +.TP +.B -v +Verbose mode, add some more detail, and generate more +hints and warnings about the model. +.SH SOURCE +.B /sys/src/cmd/spin +.SH SEE ALSO +.in +4 +.ti -4 +.BR http://spinroot.com : +.BR GettingStarted.pdf , +.BR Roadmap.pdf , +.BR Manual.pdf , +.BR WhatsNew.pdf , +.B Exercises.pdf +.br +.in -4 +G.J. Holzmann, +.IR "Design and Validation of Computer Protocols" , +Prentice Hall, 1991. +.br +—, `Design and validation of protocols: a tutorial,' +.IR "Computer Networks and ISDN Systems" , +Vol. 25, No. 9, 1993, pp. 981-1017. +.br +—, `The model checker Spin,' +.IR "IEEE Trans. on SE" , +Vol, 23, No. 5, May 1997. diff --git a/sys/man/1/split b/sys/man/1/split new file mode 100755 index 000000000..ffb012d79 --- /dev/null +++ b/sys/man/1/split @@ -0,0 +1,82 @@ +.TH SPLIT 1 +.CT 1 files +.SH NAME +split \- split a file into pieces +.SH SYNOPSIS +.B split +[ +.I option ... +] +[ +.I file +] +.SH DESCRIPTION +.I Split +reads +.I file +(standard input by default) +and writes it in pieces of 1000 +lines per output file. +The names of the +output files are +.BR xaa , +.BR xab , +and so on to +.BR xzz . +The options are +.TP +.BI -n " n" +Split into +.IR n -line +pieces. +.TP +.BI -l " n" +Synonym for +.B -n +.IR n , +a nod to Unix's syntax. +.TP +.BI -e " expression" +File divisions occur at each line +that matches a regular +.IR expression ; +see +.IR regexp (6). +Multiple +.B -e +options may appear. +If a subexpression of +.I expression +is contained in parentheses +.BR ( ... ) , +the output file name is the portion of the +line which matches the subexpression. +.TP +.BI -f " stem +Use +.I stem +instead of +.B x +in output file names. +.TP +.BI -s " suffix +Append +.I suffix +to names identified under +.BR -e . +.TP +.B -x +Exclude the matched input line from the output file. +.TP +.B -i +Ignore case in option +.BR -e ; +force output file names (excluding the suffix) +to lower case. +.SH SOURCE +.B /sys/src/cmd/split.c +.SH SEE ALSO +.IR sed (1), +.IR awk (1), +.IR grep (1), +.IR regexp (6) diff --git a/sys/man/1/src b/sys/man/1/src new file mode 100755 index 000000000..f6e22ce91 --- /dev/null +++ b/sys/man/1/src @@ -0,0 +1,83 @@ +.TH SRC 1 +.SH NAME +src \- find source code for executable +.SH SYNOPSIS +.B src +[ +.B -n +] +[ +.B -s +.I symbol +] +.I file +.B ... +.SH DESCRIPTION +.I Src +examines the named +.I files +to find the corresponding source code, which is then sent to the editor using +.B B +(see +.IR sam (1)). +If +.I file +is an +.IR rc (1) +script, the source is the file itself. +If +.I file +is an executable, the source is defined to be the single file containing the +definition of +.B main +and +.I src +will point the editor at the line that begins the definition. +.I Src +uses +.IR db (1) +to extract the symbol table information that identifies the source. +.PP +.I Src +looks for each +.I file +in the current directory, in +.BR /bin , +and in the subdirectories of +.BR /bin , +in that order. +.PP +The +.B -n +flag causes +.B src +to print the file name but not send it to the editor. +The +.B -s +flag identifies a +.I symbol +other than +.B main +to locate. +.SH EXAMPLES +Find the source to the +.B main +routine in +.BR /bin/ed : +.IP +.EX +src ed +.EE +.PP +Find the source for +.BR strcmp : +.IP +.EX +src -s strcmp rc +.EE +.SH SOURCE +.B /rc/bin/src +.SH "SEE ALSO" +.IR db (1), +.IR plumb (1), +.IR sam (1). diff --git a/sys/man/1/ssh b/sys/man/1/ssh new file mode 100755 index 000000000..b43f3152a --- /dev/null +++ b/sys/man/1/ssh @@ -0,0 +1,346 @@ +.TH SSH 1 +.SH NAME +ssh, sshnet, scp, sshserve \- secure login and file copy from/to Unix or Plan 9 +.SH SYNOPSIS +.B ssh +[ +.B -CfiImPpRrw +] +[ +.B -A +.I authlist +] +[ +.B -c +.I cipherlist +] +[ +.B -[lu] +.I user +] +.RI [ user\fB@ ] host +[ +.I cmd +[ +.I args +\&... ]] +.PP +.B sshnet +[ +.B -A +.I authlist +] +[ +.B -c +.I cipherlist +] +[ +.B -m +.I mtpt +] +[ +.B -s +.I service +] +.RI [ user\fB@ ] host +.PP +.B scp +[host:]file [host:]file +.br +.B scp +[host:]file ... [host:]dir +.PP +.B aux/sshserve +[ +.B -p +] +.I address +.SH DESCRIPTION +.I Ssh +allows authenticated login over an encrypted channel to hosts that +support the ssh protocol (see the RFCs listed below for encryption and +authentication details). +.LP +.I Ssh +takes the host name of the machine to connect to as its mandatory argument. +It may be specified as a domain name or an IP address. +Normally, login is attempted using the user name from /dev/user. +.PP +Command-line options are: +.TP +.B -C +force input to be read in cooked mode: +``line at a time'' with local echo. +.TP +.B -f +enable agent forwarding. +With this flag, +.I ssh +uses SSH's agent forwarding protocol to allow +programs running on the remote server to +interact with +.IR factotum (4) +to perform RSA authentication. +.TP +.B -i +force interactive mode. +In interactive mode, +.I ssh +prompts for passwords and confirmations of +new host keys when necessary. +(In non-interactive mode, password requests +are rejected and unrecognized host keys are +cause for disconnecting.) +By default, +.I ssh +runs in interactive mode only when its +input file descriptor is +.BR /dev/cons . +.TP +.B -I +force non-interactive mode. +.TP +.B -m +disable the +.RB control- \e +menu, described below. +.TP +.B -p +force pseudoterminal request. +The +.I ssh +protocol, grounded in Unix tradition, +differentiates between connections +that request controlling pseudoterminals +and those that do not. +By default, +.I ssh +requests a pseudoterminal only when no +.I command +is given. +.TP +.B -P +force no pseudoterminal request. +.TP +.B -r +strip carriage returns. +.TP +.B -R +put the allocated pseudoterminal, if any, in raw mode. +.TP +.B -w +notify the remote side whenever the window changes size. +.TP +.BR - [ lu ] "\fI user +specify user name. +This option is deprecated in favor of the +.IB user @ hostname +syntax. +.TP +.B "-A\fI authlist +specify an ordered space-separated list of authentication protocols to try. +The full set of authentication protocols is +.B rsa +(RSA using +.IR factotum (4) +to moderate key usage), +.B password +(use a password gathered from factotum), +and +.B tis +(challenge-response). +The default list is all three in that order. +.TP +.B "-c\fI cipherlist +specify an ordered space-separated list of allowed ciphers to use when encrypting the channel. +The full set of ciphers is +.B des +(standard DES), +.B 3des +(a somewhat doubtful variation on triple DES), +.B blowfish +(Bruce Schneier's Blowfish), +.B rc4 +(RC4), +and +.B none +(no encryption). +The default cipher list is +.B blowfish +.B rc4 +.BR 3des . +.PD +.PP +The +.RB control\- \e +character is a local escape, as in +.IR con (1). +It prompts with +.BR >>> . +Legitimate responses to the prompt are +.TP +.B q +Exit. +.TP +.B . +Return from the escape. +.TP +.B !cmd +Run the command with the network connection as its +standard input and standard output. +Standard error will go to the screen. +.TP +.B r +Toggle printing of carriage returns. +.PD +.LP +If no command is specified, +a login session is started on the remote +host. +Otherwise, the command is executed with its arguments. +.LP +.I Ssh +establishes a connection with an ssh daemon on the remote host. +The daemon sends to +.I ssh +its RSA public host key and session key. +Using these, +.I ssh +sends a session key which, presumably, only the +daemon can decipher. After this, both sides start encrypting their +data with this session key. +.LP +When the daemon's host key has been received, +.I ssh +looks it up in +.B $home/lib/keyring +and in +.BR /sys/lib/ssh/keyring . +If +the key is found there, and it matches the received key, +.I ssh +is satisfied. If not, +.I ssh +reports this and offers to add the key to +.BR $home/lib/keyring . +.LP +Over the encrypted channel, +.I ssh +attempts to convince the daemon to accept the call +using the listed authentication protocols +(see the +.B -A +option above). +.LP +The preferred way to authenticate is a +.IR netkey -style +challenge/response or via a SecurID token. +.I Ssh +users on other systems than Plan 9 should enable \s-2TIS_A\s0uthentication. +.LP +When the connection is authenticated, the given command line, +(by default, a login shell) is executed on the remote host. +.sp 1 +The SSH protocol allows clients to make outgoing TCP calls via the server. +.I Sshnet +establishes an SSH connection and, rather than execute a remote command, +presents the remote server's TCP stack as a network stack +(see the discussion of TCP in +.IR ip (3)) +mounted at +.I mtpt +(default +.BR /net ), +optionally posting a 9P service +descriptor for the new file system as +.IB /srv/ service \fR. +The +.B -A +and +.B -c +arguments are as in +.IR ssh . +.sp 1 +.I Scp +uses +.I ssh +to copy files from one host to another. A remote file is identified by +a host name, a colon and a file name (no spaces). +.I Scp +can copy files from remote hosts and to remote hosts. +.sp 1 +.I Sshserve +is the server that services +.I ssh +calls from remote hosts. +The +.B -A +and +.B -c +options set valid authentication methods and ciphers +as in +.IR ssh , +except that there is no +.B rsa +authentication method. +Unlike in +.IR ssh , +the list is not ordered: the server presents a set and the client makes the choice. +The default sets are +.B tis +and +.B blowfish +.B rc4 +.BR 3des . +By default, users start with the namespace defined in +.BR /lib/namespace . +Users in group +.B noworld +in +.B /adm/users +start with the namespace defined in +.BR /lib/namespace.noworld . +.I Sshserve +does not provide the TCP forwarding functionality used +by +.IR sshnet , +because many Unix clients present +this capability in an insecure manner. +.PP +.I Sshserve +requires that +.IR factotum (4) +hold the host key, +identified by having attributes +.B proto=rsa +.BR service=sshserve . +To generate a host key: +.IP +.EX +auth/rsagen -t 'service=sshserve' >/mnt/factotum/ctl +.EE +.LP +To extract the public part of the host key in the form +used by SSH key rings: +.IP +.EX +grep 'service=sshserve' /mnt/factotum/ctl | auth/rsa2ssh +.EE +.SH FILES +.TP +.B /sys/lib/ssh/keyring +System key ring file containing public keys for remote ssh clients and servers. +.TP +.B /usr/\fIuser\fP/lib/keyring +Personal key ring file containing public keys for remote ssh clients and +servers. +.SH SOURCE +.B /sys/src/cmd/ssh +.SH "SEE ALSO" +.B /lib/rfc/rfc425[0-6] +.br +.IR factotum (4), +.IR authsrv (6), +.IR rsa (8) +.SH BUGS +Only version 1 of the SSH protocol is implemented. diff --git a/sys/man/1/stop b/sys/man/1/stop new file mode 100755 index 000000000..46e88772c --- /dev/null +++ b/sys/man/1/stop @@ -0,0 +1,36 @@ +.TH STOP 1 +.SH NAME +stop, start \- print commands to stop and start processes +.SH SYNOPSIS +.B stop +.I name +.PP +.B start +.I name +.SH DESCRIPTION +.I Stop +prints commands that will cause all processes called +.I name +and owned by the current user to be stopped. +The processes can then be debugged when they are in a consistent state. +.PP +.I Start +prints commands that will cause all stopped processes called +.I name +and owned by the current user to be started again. +.PP +Use the +.B send +command of +.IR rio (1), +or pipe into +.IR rc (1) +to execute the commands. +.SH SOURCE +.B /rc/bin/stop +.br +.B /rc/bin/start +.SH "SEE ALSO" +.IR ps (1), +.IR kill (1), +.IR proc (3) diff --git a/sys/man/1/strings b/sys/man/1/strings new file mode 100755 index 000000000..9164194bd --- /dev/null +++ b/sys/man/1/strings @@ -0,0 +1,36 @@ +.TH STRINGS 1 +.SH NAME +strings \- extract printable strings +.SH SYNOPSIS +.B strings +[ +.B -m +.I min +] [ +.I file ... +] +.SH DESCRIPTION +.I Strings +finds and prints strings containing +.I min +(default 6) +or more +consecutive printable +.SM UTF\c +-encoded characters +in a (typically) binary file, default +standard input. +Printable characters are taken to be +.SM ASCII +characters from blank through tilde (hexadecimal 20 through 7E), inclusive, +and +all other characters from value 00A0 to FFFF. +Strings reports +the decimal offset within the file at which the string starts and the text +of the string. If the string is longer than 70 runes the line is +terminated by three dots and the printing is resumed on the next +line with the offset of the continuation line. +.SH SOURCE +.B /sys/src/cmd/strings.c +.SH SEE ALSO +.IR nm (1) diff --git a/sys/man/1/strip b/sys/man/1/strip new file mode 100755 index 000000000..20de5f2da --- /dev/null +++ b/sys/man/1/strip @@ -0,0 +1,31 @@ +.TH STRIP 1 +.SH NAME +strip \- remove symbols from binary files +.SH SYNOPSIS +.B strip +.I file ... +.PP +.B strip +.B -o +.I ofile +.I file +.SH DESCRIPTION +.I Strip +removes symbol table segments from executable files, +rewriting the files in place. +Stripping a file requires write permission of the file +and the directory it is in. +.PP +If the +.B -o +flag is given, +the single input file +.I file +is stripped and the result written to +.IR ofile . +.I File +is unchanged. +.SH SOURCE +.B /sys/src/cmd/strip.c +.SH "SEE ALSO" +.IR a.out (6) diff --git a/sys/man/1/sum b/sys/man/1/sum new file mode 100755 index 000000000..0a6084fba --- /dev/null +++ b/sys/man/1/sum @@ -0,0 +1,94 @@ +.TH SUM 1 +.SH NAME +sum, md5sum, sha1sum \- sum and count blocks in a file +.SH SYNOPSIS +.B sum +[ +.B -5r +] +[ +.I file ... +] +.PP +.B md5sum +[ +.I file ... +] +.PP +.B sha1sum +[ +.B -2 +.I bits +] [ +.I file ... +] +.SH DESCRIPTION +By default, +.I sum +calculates and prints a 32-bit hexadecimal checksum, +a byte count, +and the name of +each +.IR file . +The checksum is also a function of the input length. +If no +.IR file s +are given, +the standard input is +summed. +Other summing algorithms are available. +The options are +.TF -r +.PD +.TP +.B -r +Sum with the algorithm of System V's +.B "sum -r" +and print the length (in 1K blocks) of the input. +.TP +.B -5 +Sum with System V's default algorithm +and print the length (in 512-byte blocks) of the input. +.PP +.I Sum +is typically used to look for bad spots, +to validate a file communicated over +some transmission line or +as a quick way to determine if two files on different machines might be the same. +.PP +.I Md5sum +computes the 32 hex digit RSA Data Security, Inc. MD5 Message-Digest Algorithm +described in RFC1321. +.PP +.I Sha1sum +computes the 40 hex digit National Institute of Standards and Technology +(NIST) +SHA1 secure hash algorithm +described in FIPS PUB 180-1, +by default. +Given the +.L 2 +option, +it instead computes the +.IR bits -bit +NIST SHA2 secure hash algorithm +described in FIPS PUB 180-2 +and prints the hash in hex. +Currently supported values of +.I bits +are +224, +256, +384, +and +512. +.SH SOURCE +.B /sys/src/cmd/sum.c +.br +.B /sys/src/cmd/md5sum.c +.br +.B /sys/src/cmd/sha1sum.c +.SH "SEE ALSO" +.IR cmp (1), +.IR wc (1), +.IR sechash (2) diff --git a/sys/man/1/syscall b/sys/man/1/syscall new file mode 100755 index 000000000..54cf5516d --- /dev/null +++ b/sys/man/1/syscall @@ -0,0 +1,77 @@ +.TH SYSCALL 1 +.SH NAME +syscall \- test a system call +.SH SYNOPSIS +.B syscall +[ +.B -osx +] +.I entry +[ +.I arg ... +] +.SH DESCRIPTION +.I Syscall +invokes the system call +.I entry +with the given arguments. +(Some functions, such as +.I write +and +.IR read (2), +although not strictly system calls, are valid +.IR entries .) +It prints the return value and the error string, if there was an error. +An argument is either an integer constant as in C (its value is passed), +a string (its address is passed), +or the literal +.B buf +(a pointer to a 1MB buffer is passed). +.PP +If +.B -o +is given, the contents of the 1MB buffer are printed as a zero-terminated string +after the system call is done. +The +.B -x +and +.B -s +options are similar, but +.B -x +formats the data as hexadecimal bytes, while +.B -s +interprets the data as a +.IR stat (5) +message and formats it similar to the style of +.B ls +.B -lqm +(see +.IR ls (1)), +with extra detail about the modify and access times. +.SH EXAMPLES +Write a string to standard output: +.IP +.EX +syscall write 1 hello 5 +.EE +.PP +Print information about the file connected to standard input: +.IP +.EX +syscall -s fstat 0 buf 1024 +.EE +.SH SOURCE +.B /sys/src/cmd/syscall +.SH "SEE ALSO" +Section 2 of this manual. +.SH DIAGNOSTICS +If +.I entry +is not known to +.IR syscall , +the exit status is +.LR unknown . +If the system call succeeds, the exit status is null; +otherwise the exit status is the string that +.IR errstr (2) +returns. diff --git a/sys/man/1/tail b/sys/man/1/tail new file mode 100755 index 000000000..3a4f3c692 --- /dev/null +++ b/sys/man/1/tail @@ -0,0 +1,87 @@ +.TH TAIL 1 +.SH NAME +tail \- deliver the last part of a file +.SH SYNOPSIS +.B tail +[ +.BR +- \fInumber\fP[ lbc ][ rf ] +] +[ +.I file +] +.PP +.B tail +[ +.B -fr +] +[ +.B -n +.I nlines +] +[ +.B -c +.I nbytes +] +[ +.I file +] +.SH DESCRIPTION +.I Tail +copies the named file to the standard output beginning +at a designated place. +If no file is named, the standard input is copied. +.PP +Copying begins at position +.BI + number +measured from the beginning, or +.BI - number +from the end of the input. +.I Number +is counted in lines, 1K blocks or bytes, +according to the appended flag +.LR l , +.LR b , +or +.LR c . +Default is +.B -10l +(ten ell). +.PP +The further flag +.L r +causes tail to print lines from the end of the file in reverse order; +.L f +(follow) causes +.IR tail , +after printing to the end, to keep watch and +print further data as it appears. +.PP +The second syntax is that promulgated by POSIX, where +the +.I numbers +rather than the options are signed. +.SH EXAMPLES +.TP +.B tail file +Print the last 10 lines of a file. +.TP +.B tail +0f file +Print a file, and continue to watch +data accumulate as it grows. +.TP +.B sed 10q file +Print the first 10 lines of a file. +.SH SOURCE +.B /sys/src/cmd/tail.c +.SH BUGS +Tails relative to the end of the file +are treasured up in a buffer, and thus +are limited in length. +.PP +According to custom, option +.BI + number +counts lines from 1, and counts +blocks and bytes from 0. +.PP +.I Tail +is ignorant of UTF. diff --git a/sys/man/1/tar b/sys/man/1/tar new file mode 100755 index 000000000..da79167dd --- /dev/null +++ b/sys/man/1/tar @@ -0,0 +1,202 @@ +.TH TAR 1 +.SH NAME +tar, dircp \- archiver +.SH SYNOPSIS +.B tar +.I key +[ +.I file ... +] +.PP +.B dircp +.I fromdir +.I todir +.SH DESCRIPTION +.I Tar +saves and restores file trees. +It is most often used to transport a tree of files from one +system to another. +The +.I key +is a string that contains +at most one function letter plus optional modifiers. +Other arguments to the command are names of +files or directories to be dumped or restored. +A directory name implies all the contained +files and subdirectories (recursively). +.PP +The function is one of the following letters: +.TP +.B c +Create a new archive with the given files as contents. +.TP +.B r +The named files +are appended to the archive. +.TP +.B t +List all occurrences of each +.I file +in the archive, or of all files if there are no +.I file +arguments. +.TP +.B x +Extract the named files from the archive. +If a file is a directory, the directory is extracted recursively. +Modes are restored if possible. +If no file argument is given, extract the entire archive. +If the archive contains multiple entries for a file, +the latest one wins. +.PP +The modifiers are: +.TP +.B f +Use the next argument as the name of the archive instead of +the default standard input (for keys +.B x +and +.BR t ) +or standard output (for keys +.B c +and +.BR r ). +.TP +.B g +Use the next (numeric) argument as the group id for files in +the output archive. +.TP +.B i +Ignore errors encountered when reading. +Errors writing either produce a corrupt archive +or indicate deeper file system problems. +.TP +.B k +(keep) +Modifies the behavior of +.B x +not to extract files which already exist. +.TP +.B m +Do not set the modification time on extracted files. +This is the default behavior; the flag exists only for compatibility with other tars. +.TP +.B p +Create archive in POSIX ustar format, +which raises the maximum pathname length from 100 to 256 bytes. +Ustar archives are recognised automatically by +.I tar +when reading archives. +This is the default behavior; the flag exists only for backwards compatibility +with older versions of tar. +.TP +.B P +Do not generate the POSIX ustar format. +.TP +.B R +When extracting, respect leading slash on file names. +By default, files are always extracted relative to the current directory. +.TP +.B s +When extracting, attempt to resynchronise after not finding a tape header +block where expected. +.TP +.B T +Modifies the behavior of +.B x +to set the modified time, +mode and, for POSIX archives and filesystem permitting, +the user and group +of each file to that specified in the archive. +.TP +.B u +Use the next (numeric) argument as the user id for files in +the output archive. This is only useful when moving files to +a non-Plan 9 system. +.TP +.B v +(verbose) +Print the name of each file as it is processed. +With +.BR t , +give more details about the +archive entries. +.TP +.B z +Operate on compressed +.I tar +archives. +The type of compression is inferred from the file name extension: +.IR gzip (1) +for +.B .tar.gz +and +.BR .tgz ; +.I bzip2 +(see +.IR gzip (1)) +for +.BR .tar.bz , +.BR .tbz , +.BR .tar.bz2 , +and +.BR .tbz2 ; +.I compress +for +.B .tar.Z +and +.BR .tz . +If no extension matches, +.I gzip +is used. +The +.B z +flag is unnecessary (but allowed) when using the +.B t +and +.B x +verbs on archives with recognized extensions. +.br +.ne 6 +.SH EXAMPLES +.I Tar +can be used to copy hierarchies thus: +.IP +.EX +@{cd fromdir && tar c .} | @{cd todir && tar xT} +.EE +.PP +.I Dircp +does this. +.SH SOURCE +.B /sys/src/cmd/tar.c +.br +.B /rc/bin/dircp +.SH SEE ALSO +.IR ar (1), +.IR bundle (1), +.IR tapefs (4), +.IR mkfs (8) +.SH BUGS +There is no way to ask for any but the last +occurrence of a file. +.PP +File path names are limited to +100 characters +(256 when using ustar format). +.PP +The +.I tar +format allows specification of links and symbolic links, +concepts foreign to Plan 9: they are ignored. +.PP +The +.B r +key (append) +cannot be used on compressed archives. +.PP +.IR Tar , +thus +.IR dircp , +doesn't record Plan-9-specific metadata +such as append-only and exclusive-open permission bits, so they aren't copied. diff --git a/sys/man/1/tbl b/sys/man/1/tbl new file mode 100755 index 000000000..921e9e85e --- /dev/null +++ b/sys/man/1/tbl @@ -0,0 +1,285 @@ +.TH TBL 1 +.SH NAME +tbl \- format tables for nroff or troff +.SH SYNOPSIS +.B tbl +[ +.I file ... +] +.SH DESCRIPTION +.I Tbl +is a preprocessor for formatting tables for +.I nroff +or +.IR troff (1). +The input +.I files +are copied to the standard output, +except for segments of the form +.IP +.nf +.B .TS +.IB options " ; +.IB format " . +.I data +.B .T& +.IB format " . +.I data +\&. . . +.B .TE +.fi +.LP +which describe tables +and are replaced by +.I troff +requests to lay out the tables. +If no arguments are given, +.I tbl +reads the standard input. +.PP +The (optional) +.I options +line is terminated by a semicolon and contains one or more +of +.RS +.TF linesize(n) +.TP +.B center +center the table; default is left-adjust +.TP +.B expand +make table as wide as current line length +.TP +.B box +.TP +.B doublebox +enclose the table in a box or double box +.TP +.B allbox +enclose every item in a box +.TP +.BI tab( x ) +use +.I x +to separate input items; default is tab +.TP +.BI linesize( n ) +set rules in +.IR n -point +type +.TP +.BI delim( xy ) +recognize +.I x +and +.I y +as +.IR eqn (1) +delimiters +.PD +.RE +.PP +Each line, except the last, of the obligatory +.I format +describes one row of the table. +The last line describes all rows until the next +.BR .T& , +where the format changes, +or the end of the table at +.BR .TE . +A format is specified by key letters, one per column, either upper or lower case: +.RS +.TP 0 +.B L +Left justify: the default for +columns without format keys. +.PD0 +.TP +.B R +Right justify. +.TP +.B C +Center. +.TP +.B N +Numeric: align at decimal point (inferred for integers) or at +.LR \e& . +.TP +.B S +Span: extend previous column across this one. +.TP +.B A +Alphabetic: left-aligned within column, widest item centered, indented relative to +.B L +rows. +.TP +.B ^ +Vertical span: continue item from previous row into this row. +.TP +.B - +Draw a horizontal rule in this column. +.TP +.B = +Draw a double horizontal rule in this column. +.PD +.RE +.PP +Key letters may be followed by modifiers, also either case: +.RS +.TP \w'\fLF\fIfont\fLXX'u +.B | +Draw vertical rule between columns. +.PD0 +.TP +.B || +Draw a double vertical rule between columns. +.TP +.I n +Gap between column is +.I n +ens wide. +Default is 3. +.TP +.BI F font +Use specified +.IR font . +.B B +and +.B I +mean +.B FB +and +.BR FI . +.TP +.B T +Begin vertically-spanned item at top row of range; default is +vertical centering (with +.LR ^ ). +.TP +.BI P n +Use point size +.IR n . +.TP +.BI V n +Use +.IR n -point +vertical spacing in text block; signed +.I n +means relative change. +.TP +.BI W( n ) +Column width as a +.I troff +width specification. +Parens are optional if +.I n +is a simple integer. +.TP +.B E +Equalize the widths of all columns marked +.BR E . +.PD +.RE +.PP +Each line of +.I data +becomes one row of the table; tabs separate items. +Lines beginning with +.L . +are +.I troff +requests. +Certain special data items are recognized: +.RS +.TP 0 +.B _ +Draw a horizontal rule in this column. +.PD0 +.TP +.B = +Draw a double horizontal rule in this column. +A data line consisting of a single +.L _ +or +.L = +draws the rule across the whole table. +.TP +.B \e_ +Draw a rule only as wide as the contents of the column. +.TP +.BI \eR x +Repeat character +.I x +across the column. +.TP +.B \e^ +Span the previous item in this column down into this row. +.TP +.B T{ +The item is a text block to be separately formatted +by +.I troff +and placed in the table. +The block continues to the next line beginning with +.BR T} . +The remainder of the data line follows at that point. +.PD +.RE +.PP +When it is used in a pipeline with +.IR eqn , +the +.I tbl +command should be first, to minimize the volume +of data passed through +pipes. +.SH EXAMPLES +.ds tb \fR\fP +Let \*(tb +represent a tab (which should +be typed as a genuine tab). +.if t .2C +.EX +\&.TS +c s s +c c s +c c c +l n n. +Household Population +Town\*(tbHouseholds +\*(tbNumber\*(tbSize +Bedminster\*(tb789\*(tb3.26 +Bernards Twp.\*(tb3087\*(tb3.74 +Bernardsville\*(tb2018\*(tb3.30 +\&.TE +.if t \{\0 +\0 +\0\} +.if n .PP +.TS +c s s +c c s +c c c +l n n. +Household Population +Town Households + Number Size +Bedminster 789 3.26 +Bernards Twp. 3087 3.74 +Bernardsville 2018 3.30 +.TE +.EE +.if t \{.sp3 +.1C\} +.SH SOURCE +.B /sys/src/cmd/tbl +.SH SEE ALSO +.IR troff (1), +.IR eqn (1), +.IR doctype (1) +.br +M. E. Lesk and L. L. Cherry, +``TBL\(ema Program to Format Tables'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. diff --git a/sys/man/1/tcs b/sys/man/1/tcs new file mode 100755 index 000000000..664073d36 --- /dev/null +++ b/sys/man/1/tcs @@ -0,0 +1,172 @@ +.TH TCS 1 +.SH NAME +tcs \- translate character sets +.SH SYNOPSIS +.B tcs +[ +.B -slcv +] +[ +.B -f +.I ics +] +[ +.B -t +.I ocs +] +[ +.I file ... +] +.SH DESCRIPTION +.I Tcs +interprets the named +.I file(s) +(standard input default) as a stream of characters from the +.I ics +character set or format, converts them to runes, +and then converts them into a stream of characters from the +.I ocs +character set or format on the standard output. +The default value for +.I ics +and +.I ocs +is +.BR utf , +the +.SM UTF +encoding described in +.IR utf (6). +The +.B -l +option lists the character sets known to +.IR tcs . +Processing continues in the face of conversion errors (the +.B -s +option prevents reporting of these errors). +The +.B -c +option forces the output to contain only correctly converted characters; +otherwise, +.B Runeerror +(0xFFFD) +characters will be substituted for +.SM UTF +encoding errors and unknown characters. +.PP +The +.B -v +option generates various diagnostic and summary information on standard error, +or makes the +.B -l +output more verbose. +.PP +.I Tcs +recognizes an ever changing list of character sets. +In particular, it supports a variety of Russian and Japanese encodings. +Some of the supported encodings are +.TF jis-kanji +.TP +.B utf +The Plan 9 +.SM UTF +encoding, known by ISO as UTF-8 +.TP +.B utf1 +The deprecated original +.SM UTF +encoding from ISO 10646 +.TP +.B ascii +7-bit ASCII +.TP +.B 8859-1 +Latin-1 (Central European) +.TP +.B 8859-2 +Latin-2 (Czech .. Slovak) +.TP +.B 8859-3 +Latin-3 (Dutch .. Turkish) +.TP +.B 8859-4 +Latin-4 (Scandinavian) +.TP +.B 8859-5 +Part 5 (Cyrillic) +.TP +.B 8859-6 +Part 6 (Arabic) +.TP +.B 8859-7 +Part 7 (Greek) +.TP +.B 8859-8 +Part 8 (Hebrew) +.TP +.B 8859-9 +Latin-5 (Finnish .. Portuguese) +.TP +.B html +Unicode as encoded by HTML +.TP +.B koi8 +KOI-8 (GOST 19769-74) +.TP +.B jis-kanji +ISO 2022-JP +.TP +.B ujis +EUC-JX: JIS 0208 +.TP +.B ms-kanji +Microsoft, or Shift-JIS +.TP +.B jis +(from only) guesses between ISO 2022-JP, EUC or Shift-Jis +.TP +.B gb +Chinese national standard (GB2312-80) +.TP +.B big5 +Big 5 (HKU version) +.TP +.B unicode +Unicode Standard 1.0 +.TP +.B tis +Thai character set plus +.SM ASCII +(TIS 620-1986) +.TP +.B msdos +IBM PC: CP 437 +.TP +.B atari +Atari-ST character set +.SH EXAMPLES +.TP +.B tcs -f 8859-1 +Convert 8859-1 (Latin-1) characters into +.SM UTF +format. +.TP +.B tcs -s -f jis +Convert characters encoded in one of several shift JIS encodings into +.SM UTF +format. +Unknown Kanji will be converted into +.B 0xFFFD +characters. +.TP +.B tcs -t html +Convert UTF into character set-independent HTML. +.TP +.B tcs -lv +Print an up to date list of the supported character sets. +.SH SOURCE +.B /sys/src/cmd/tcs +.SH SEE ALSO +.IR ascii (1), +.IR rune (2), +.IR utf (6). diff --git a/sys/man/1/tee b/sys/man/1/tee new file mode 100755 index 000000000..d237fb7fa --- /dev/null +++ b/sys/man/1/tee @@ -0,0 +1,28 @@ +.TH TEE 1 +.SH NAME +tee \- pipe fitting +.SH SYNOPSIS +.B tee +[ +.B -i +] +[ +.B -a +] +.I files +.SH DESCRIPTION +.I Tee +transcribes the standard input to the standard +output and makes copies in the +.IR files . +The options are +.TP +.B -i +Ignore interrupts. +.TP +.B -a +Append the output to the +.I files +rather than rewriting them. +.SH SOURCE +.B /sys/src/cmd/tee.c diff --git a/sys/man/1/tel b/sys/man/1/tel new file mode 100755 index 000000000..69bc37331 --- /dev/null +++ b/sys/man/1/tel @@ -0,0 +1,49 @@ +.TH TEL 1 +.SH NAME +tel, iwhois \- look in phone book +.SH SYNOPSIS +.B tel +.I key ... +.PP +.B iwhois +.IR name [ \fL@\f2domain ] +.SH DESCRIPTION +.I Tel +looks up +.I key +in a private telephone book, +.BR $home/lib/tel , +and in the public telephone book, +.BR /lib/tel . +It uses +.IR grep +(with the +.B -i +option to ignore case differences), so the key may be any part of a +name or number. Customarily, the telephone book contains names, +userids, home numbers, and office numbers of users. It also contains +a directory of area codes and miscellaneous people of general +interest. +.PP +.I Iwhois +looks up names in the Internet NIC's personnel database. +.I Name +should be a surname optionally followed by a comma and given name. +A different server can be chosen by appending to the name an +.B @ +followed by the server's domain name. +.SH FILES +.TF /lib/areacodes +.TP +.B /lib/areacodes +Telephone area codes database. +.TP +.B /lib/tel +Public telephone number database. +.TP +.B $home/lib/tel +Personal telephone number database. +.SH SOURCE +.B /rc/bin/tel +.br +.B /rc/bin/iwhois diff --git a/sys/man/1/test b/sys/man/1/test new file mode 100755 index 000000000..8feabf19a --- /dev/null +++ b/sys/man/1/test @@ -0,0 +1,218 @@ +.TH TEST 1 +.SH NAME +test \- set status according to condition +.SH SYNOPSIS +.B test +.I expr +.SH DESCRIPTION +.I Test +evaluates the expression +.IR expr . +If the value is true the exit status is null; otherwise the +exit status is non-null. +If there are no arguments the exit status is non-null. +.PP +The following primitives are used to construct +.IR expr . +.TP "\w'\fIn1 \fL-eq \fIn2\fLXX'u" +.BI -r " file" +True if the file exists (is accessible) and is readable. +.PD0 +.TP +.BI -w " file" +True if the file exists and is writable. +.TP +.BI -x " file" +True if the file exists and has execute permission. +.TP +.BI -e " file +True if the file exists. +.TP +.BI -f " file" +True if the file exists and is a plain file. +.TP +.BI -d " file" +True if the file exists and is a directory. +.TP +.BI -s " file" +True if the file exists and has a size greater than zero. +.TP +.BI -t " fildes +True if the open file whose file descriptor number is +.I fildes +(1 by default) +is the same file as +.BR /dev/cons . +.TP +.BI -A " file" +True if the file exists and is append-only. +.TP +.BI -L " file" +True if the file exists and is exclusive-use. +.TP +.BI -T "file" +True if the file exists and is temporary. +.TP +.IB s1 " = " s2 +True +if the strings +.I s1 +and +.I s2 +are identical. +.TP +.IB s1 " != " s2 +True +if the strings +.I s1 +and +.I s2 +are not identical. +.TP +s1 +True if +.I s1 +is not the null string. +(Deprecated.) +.TP +.BI -n " s1" +True if the length of string +.I s1 +is non-zero. +.TP +.BI -z " s1" +True if the length of string +.I s1 +is zero. +.TP +.IB n1 " -eq " n2 +True if the integers +.I n1 +and +.I n2 +are arithmetically equal. +Any of the comparisons +.BR -ne , +.BR -gt , +.BR -ge , +.BR -lt , +or +.BR -le +may be used in place of +.BR -eq . +The (nonstandard) construct +.BI -l " string\f1, +meaning the length of +.IR string , +may be used in place of an integer. +.TP +.IB a " -nt " b +True if file +.I a +is newer than (modified after) file +.IR b . +.TP +.IB a " -ot " b +True if file +.I a +is older than (modified before) file +.IR b . +.TP +.IB f " -older " t +True if file +.I f +is older than (modified before) time +.IR t . +If +.I t +is a integer followed by the letters +.BR y (years), +.BR M (months), +.BR d (days), +.BR h (hours), +.BR m (minutes), +or +.BR s (seconds), +it represents current time minus the specified time. +If there is no letter, it represents seconds since +epoch. +You can also concatenate mixed units. For example, +.B 3d12h +means three days and twelve hours ago. +.PD +.PP +These primaries may be combined with the +following operators: +.TP "\w'\fL( \fIexpr\fL )XX'u" +.B ! +unary negation operator +.PD0 +.TP +.B -o +binary +.I or +operator +.TP +.B -a +binary +.I and +operator; higher precedence than +.BR -o +.TP +.BI "( " expr " )" +parentheses for grouping. +.PD +.PP +The primitives +.BR -b , +.BR -u , +.BR -g , +and +.BR -s +return false; they are recognized for compatibility with POSIX. +.PP +Notice that all the operators and flags are separate +arguments to +.IR test . +Notice also that parentheses and equal signs are meaningful +to +.I rc +and must be enclosed in quotes. +.SH EXAMPLES +.I Test +is a dubious way to check for specific character strings: +it uses a process to do what an +.IR rc (1) +match or switch statement can do. +The first example is not only inefficient but wrong, because +.I test +understands the purported string +.B \&"-c" +as an option. +.IP +.EX +if (test $1 '=' "-c") echo OK # wrong! +.EE +.LP +A better way is +.IP +.EX +if (~ $1 -c) echo OK +.EE +.PP +Test whether +.L abc +is in the current directory. +.IP +.B test -f abc -o -d abc +.SH SOURCE +.B /sys/src/cmd/test.c +.SH "SEE ALSO" +.IR rc (1) +.SH BUGS +Won't complain about extraneous arguments +since there may be arguments left unprocessed by +short-circuit evaluation of +.B -a +or +.BR -o . diff --git a/sys/man/1/thesaurus b/sys/man/1/thesaurus new file mode 100755 index 000000000..c605e635c --- /dev/null +++ b/sys/man/1/thesaurus @@ -0,0 +1,11 @@ +.TH THESAURUS 1 +.SH NAME +thesaurus \- search online thesaurus +.SH SYNOPSIS +.B thesaurus +.BI word +.SH DESCRIPTION +.I thesaurus +searches the online thesaurus at http://thesaurus.reference.com +.SH SOURCE +.B /rc/bin/thesaurus diff --git a/sys/man/1/time b/sys/man/1/time new file mode 100755 index 000000000..2c6b834b2 --- /dev/null +++ b/sys/man/1/time @@ -0,0 +1,21 @@ +.TH TIME 1 +.SH NAME +time \- time a command +.SH SYNOPSIS +.B time +.I command +[ +.I arg ... +] +.SH DESCRIPTION +The +.I command +is executed with the given arguments; after it is complete, +.I time +reports on standard error the program's elapsed user time, +system time, and real time, in seconds, +followed by the command line. +.SH SOURCE +.B /sys/src/cmd/time.c +.SH "SEE ALSO" +.IR prof (1) diff --git a/sys/man/1/touch b/sys/man/1/touch new file mode 100755 index 000000000..ac5937ec1 --- /dev/null +++ b/sys/man/1/touch @@ -0,0 +1,35 @@ +.TH TOUCH 1 +.SH NAME +touch \- set modification date of a file +.SH SYNOPSIS +.B touch +[ +.B -c +] +[ +.B -t +.I time +] +.I file ... +.SH DESCRIPTION +.I Touch +attempts to set the modification time of the +.I files +to +.I time +(by default, the current time). +If a +.I file +does not exist, +it will be created unless option +.B -c +is present. +.SH SOURCE +.B /sys/src/cmd/touch.c +.SH SEE ALSO +.IR ls (1), +.IR stat (2), +.IR chmod (1) +.SH BUGS +.I Touch +will not touch directories. diff --git a/sys/man/1/tr b/sys/man/1/tr new file mode 100755 index 000000000..0e11f5b96 --- /dev/null +++ b/sys/man/1/tr @@ -0,0 +1,97 @@ +.TH TR 1 +.SH NAME +tr \- translate characters +.SH SYNOPSIS +.B tr +[ +.B -cds +] +[ +.I string1 +[ +.I string2 +] +] +.SH DESCRIPTION +.I Tr +copies the standard input to the standard output with +substitution or deletion of selected characters (runes). +Input characters found in +.I string1 +are mapped into the corresponding characters of +.IR string2 . +When +.I string2 +is short it is padded to the length of +.I string1 +by duplicating its last character. +Any combination of the options +.B -cds +may be used: +.TP +.B -c +Complement +.IR string1 : +replace it with a lexicographically ordered +list of all other characters. +.TP +.B -d +Delete from input all characters in +.IR string1 . +.TP +.B -s +Squeeze repeated output characters that occur in +.I string2 +to single characters. +.PP +In either string a noninitial sequence +.BI - x\f1, +where +.I x +is any character (possibly quoted), stands for +a range of characters: +a possibly empty sequence of codes running from +the successor of the previous code up through +the code for +.IR x . +The character +.L \e +followed by 1, 2 or 3 octal digits stands for the +character whose +16-bit +value is given by those digits. +The character sequence +.L \ex +followed by 1, 2, 3, or 4 hexadecimal digits stands +for the character whose +16-bit value is given by those digits. +A +.L \e +followed by any other character stands +for that character. +.SH EXAMPLES +Replace all upper-case +.SM ASCII +letters by lower-case. +.IP +.EX +tr A-Z a-z lower +.EE +.PP +Create a list of all +the words in +.L file1 +one per line in +.LR file2 , +where a word is taken to be a maximal string of alphabetics. +.I String2 +is given as a quoted newline. +.IP +.EX +tr -cs A-Za-z ' +\&' file2 +.EE +.SH SOURCE +.B /sys/src/cmd/tr.c +.SH "SEE ALSO" +.IR sed (1) diff --git a/sys/man/1/trace b/sys/man/1/trace new file mode 100755 index 000000000..6acabe11d --- /dev/null +++ b/sys/man/1/trace @@ -0,0 +1,84 @@ +.TH TRACE 1 +.SH NAME +trace \- show (real-time) process behavior +.SH SYNOPSIS +.B trace +[ +.B -d +.I file +] +[ +.B -v +] +[ +.B -w +] +[ +.I pid +\&... +] +.SH DESCRIPTION +.I Trace +displays the behavior of processes running on the machine. In its +window it shows a time line for each traced process. Running +processes appear as colored blocks, with arrows marking important +events in real-time processes +(see +.IR proc (3)). +Black up arrows mark process releases, +black down arrows mark process deadlines, +green down arrows mark times when a process yielded the processor +before its deadline, +red down arrows mark times when the process overran its allotted time. +.PP +.I Trace +reads +.B /proc/trace +to retrieve trace events from the kernel +scheduler. Trace events are binary data structures generated by +the kernel scheduler. +It is assumed that the reader of +.B /proc/trace +and the kernel providing it have the same byte order. +.PP +The options are: +.TP +.B -d +specify an alternate trace event file +.TP +.B -v +print events as they are read from the trace event file +.TP +.B -w +run in a new window rather than using the current one +.PD +.PP +.I Trace +recognizes these keystroke commands while it is running: +.TP +.B + +zoom in by a factor of two +.TP +.B - +zoom out by a factor of two +.TP +.B p +pause or resume +.TP +.B q +quit +.PD +.PP +.SH SEE ALSO +.IR proc (3) +.SH FILES +.TF /sys/include/trace.h +.TP +.B /proc/trace +trace event file +.TP +.B /sys/include/trace.h +trace event data structures +.PD +.SH SOURCE +.B /sys/src/cmd/trace.c diff --git a/sys/man/1/troff b/sys/man/1/troff new file mode 100755 index 000000000..2838fcd26 --- /dev/null +++ b/sys/man/1/troff @@ -0,0 +1,237 @@ +.TH TROFF 1 +.SH NAME +troff, nroff, dpost \- text formatting and typesetting +.SH SYNOPSIS +.B troff +[ +.I option ... +] +[ +.I file ... +] +.PP +.B dpost +[ +.B -f +] [ +.I file ... +] +.PP +.B nroff +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Troff +formats text in the named +.I files +for +printing on a typesetter, +emitting a textual intermediate format called +`typesetter-independent +.I troff +output', +understood by programs such as +.IR proof (1) +and +.IR lp (1), +but also by a +.I troff +post-processor named +.IR dpost , +which emits corresponding Postscript. +Under +.BR -f , +.I dpost +also emits Postscript font definitions as needed. +.I Nroff +does the same as +.IR troff , +but produces output suitable +for typewriter-like devices, +usually without further post-processing, +but see +.IR col (1). +.PP +If no +.I file +argument is present, the standard input is read. +An argument consisting of a single minus +.RB ( - ) +is taken to be +a file name corresponding to the standard input. +The options are: +.nr xx \w'\fL-m\f2name\ \ ' +.TP \n(xxu +.BI -o list +Print pages in the comma-separated +.I list +of numbers and ranges. +A range +.IB N - M +means +.I N +through +.IR M ; +initial +.BI - M +means up to +.IR M ; +final +.IB N - +means from +.I N +to the end. +.TP +.BI -n N +Number first generated page +.IR N . +.TP +.BI -m name +Process the macro file +.BI /sys/lib/tmac/tmac. name +before the input +.IR files . +.TP +.BI -r aN +Set register +.I a +(one character name) to +.IR N . +.TP +.B -i +Read standard input after the input files are exhausted. +.TP +.B -q +Invoke the simultaneous input-output mode of the +.B rd +request. +.TP +.B -N +Produce output suitable for typewriter-like devices. +.SS Typesetter devices (not \fL-N\fP) only +.TP \n(xxu +.B -a +Send a printable +textual +approximation +of the results to the standard output. +.TP +.BI -T dest +Prepare output for typesetter +.IR dest : +.br +.ns +.RS +.TP \w'\fL-TLatin1\ 'u +.B -Tutf +(The default.) PostScript printers with +preprocessing to handle Unicode +characters encoded in +.SM UTF +.PD0 +.TP +.B -Tpost +Regular PostScript printers +.PD0 +.TP +.B -T202 +Mergenthaler Linotron 202 +.RE +.PD +.TP "\w'\fL-m\f2name 'u" +.BI -F dir +Take font information from directory +.IR dir . +.SS Typewriter (\fL-N\fP) output only +.TP \n(xxu +.BI -s N +Halt prior to every +.I N +pages (default +.IR N =1) +to allow paper loading or changing. +.TP +.BI -T name +Prepare output for specified terminal. +Known +.I names +include +.B utf +for the normal Plan 9 +.SM UTF +encoding of the Unicode Standard character set (default), +.B 37 +for the +Teletype model 37, +.B lp +(`line-printer') +for any terminal without half-line capability, +.B 450 +for the \s-1DASI\s+1-450 +(Diablo Hyterm), +and +.B think +(HP ThinkJet). +.TP +.B -e +Produce equally-spaced words in adjusted +lines, using full terminal resolution. +.TP +.B -h +Use output tabs during horizontal spacing +to speed output and reduce output character count. +Tab settings are assumed to be every +8 nominal character widths. +.SH FILES +.TF /sys/lib/troff/term/* +.TP +.B /tmp/trtmp* +temporary file +.TP +.B /sys/lib/tmac/tmac.* +standard macro files +.TP +.B /sys/lib/troff/term/* +terminal driving tables for +.I nroff +.TP +.B /sys/lib/troff/font/* +font width tables for +.I troff +.SH SOURCE +.B /sys/src/cmd/troff +.br +.B /rc/bin/dpost +.br +.ne 3 +.SH "SEE ALSO" +.IR lp (1), +.IR proof (1), +.IR page (1), +.IR eqn (1), +.IR tbl (1), +.IR pic (1), +.IR grap (1), +.IR doctype (1), +.IR ms (6), +.IR image (6), +.IR tex (1), +.IR deroff (1), +.IR col (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual'' +.br +B. W. Kernighan, +``A Typesetter-Independent TROFF'', +CSTR #97 +.br +B. W. Kernighan, +``A TROFF Tutorial'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. diff --git a/sys/man/1/troff2html b/sys/man/1/troff2html new file mode 100755 index 000000000..7f777a766 --- /dev/null +++ b/sys/man/1/troff2html @@ -0,0 +1,99 @@ +.TH TROFF2HTML 1 +.SH NAME +troff2html \- convert troff output into HTML +.SH SYNOPSIS +.B troff2html +[ +.B -t +.I title +] [ +.I file +\ ... +] +.SH DESCRIPTION +.I Troff2html +reads the +.IR troff (1) +output in the named +.IR files , +default standard input, +and converts them into HTML. +.PP +.I Troff2html +does a tolerable job with straight +.B troff +output, but it is helped by annotations, described below. +Its main use is for +.B man2html +(see +.IR httpd (8)), +which converts +.IR man (1) +pages into HTML +and depends on a specially annotated set of +.IR man (6) +macros, invoked by +.B troff +.BR -manhtml . +.PP +.B Troff +output lines beginning +.IP +.EX +x X html \f1... +.EE +.LP +which are introduced by placing +.B \eX'html\ \f1...\fP' +in the +.IR input , +cause the rest of the line to be interpolated into the HTML produced. +Several such lines are recognized specially by +.IR troff2html . +The most important are the pair +.IP +.EX +x X html manref start cp 1 +x X html manref end cp 1 +.EE +.PP +which are used to create HTML hyperlinks around text of the form +.IR cp (1) +pointing to +.BR /magic/man2html/1/cp . +.PP +.I Troff2html +is new and experimental; in time, it may improve and subsume +.IR ms2html (1). +On the one hand, because it uses the input, +.B ms2html +can handle +.IR pic (1), +.IR eqn (1), +etc., which +.I troff2html +does not handle at all; on the other hand, +.B ms2html +understands only +.IR ms (6) +documents and is easily confused by complex +.B troff +constructions. +.I Troff2html +has the reverse properties: it does not handle the preprocessors but its output +is reliable and (modulo helper annotations) is independent of macro package. +.SH SOURCE +.B /sys/src/cmd/troff2html +.SH SEE ALSO +.IR troff (1), +.IR ms2html (1), +.B man2html +in +.IR httpd (8). +.SH BUGS +.B Troff +and HTML have different models, and they don't mesh well in all cases. +.BR Troff 's +indented paragraphs are not well served in HTML, and the output of +.I troff2html +shows this. diff --git a/sys/man/1/tweak b/sys/man/1/tweak new file mode 100755 index 000000000..e3f195038 --- /dev/null +++ b/sys/man/1/tweak @@ -0,0 +1,167 @@ +.TH TWEAK 1 +.CT 1 graphics +.SH NAME +tweak \- edit image files, subfont files, face files, etc. +.SH SYNOPSIS +.B tweak +[ +.I file ... +] +.SH DESCRIPTION +.I Tweak +edits existing files holding various forms of images. +To create original images, start from an existing image, subfont, etc. +.PP +.I Tweak +reads its argument +.I files +and displays the resulting images in a vertical column. +If the image is too wide to fit across the display, it +is folded much like a long line of text in an +.IR rio +window. +Under each image is displayed one or two lines of text +presenting its parameters. +The first line shows the image's +.BR depth , +the number +of bits per pixel; +.BR r , +the rectangle covered by the image; +and the name of the +.B file +from which it was read. +If the file is a subfont, a second line presents a hexadecimal 16-bit +.B offset +to be applied to character values from the subfont +(typically as stored in a font file; see +.IR font (6)); +and the subfont's +.BR n , +.BR height , +and +.B ascent +as defined in +.IR cachechars (2). +.PP +By means described below, magnified views of portions of the images +may be displayed. +The text associated with such a view includes +.BR mag , +the magnification. +If the view is of a single character from a subfont, the second +line of text shows the character's value (including the subfont's offset) +in hexadecimal and as a character in +.I tweak's +default font; the character's +.BR x , +.BR top , +.BR bottom , +.BR left , +and +.BR width +as defined in +.IR cachechars (2); +and +.BR iwidth , +the physical width of the image in the subfont's image. +.PP +There are two methods to obtain a magnified view of a character from a +subfont. +The first is to click mouse button 1 over the image of the character in +the subfont. The second is to select the +.B char +entry on the button 3 menu, +point the resulting gunsight cursor at the desired subfont and click button 3, +and then type at the text prompt at the bottom of the screen the +character value, either as a multi-digit hexadecimal number or as a single +rune representing the character. +.PP +To magnify a portion of other types of image files, +click button 1 over the unmagnified file. +The cursor will switch to a cross. +Still with button 1, sweep a rectangle, as in +.BR rio , +that encloses the portion of the image to be magnified. +(If the file is 16×16 or smaller, +.I tweak +will just magnify the entire file; no sweeping is necessary.) +.PP +Pressing buttons 1 and 2 within magnified images changes pixel values. +By default, button 1 sets the pixel to all zeros and button 2 sets the pixel +to all ones. +.PP +Across the top of the screen is a textual display of global parameters. +These values, as well as many of the textual values associated with +the images, may be edited by clicking button 1 on the displayed +value and typing a new value. +The values along the top of the screen are: +.TP +.B mag +Default magnification. +.TP +.B val(hex) +The value used to modify pixels within magnified images. +The value must be in hexadecimal, optionally preceded by a +tilde for bitwise negation. +.TP +.B but1 +.TP +.B but2 +The pixel value written when the corresponding button is pressed over a pixel. +.TP +.B invert-on-copy +Whether the pixel values are inverted when a +.B copy +operation is performed. +.PP +Under button 3 is a menu holding a variety of functions. +Many of these functions prompt for the image upon which to act +by switching to a gunsight cursor; click button 3 over the +selection, or click a different button to cancel the action. +.TP +.B open +Read and display a file. The name of the file is typed to the prompt +on the bottom line. +.TP +.B read +Reread a file. +.TP +.B write +Write a file. +.TP +.B copy +Use the copy function, default +.BR S , +to transfer a rectangle of pixels from one image to another. +The program prompts with a cross cursor; sweep out a rectangle in +one image or just click button 3 to select the whole image. +The program will leave that rectangle in place and +attach another one to the cursor. Move that rectangle to the desired +place in any image and click button 3, or another button to cancel the action. +.TP +.B char +As described above, open a magnified view of a character image in a subfont. +.TP +.B pixels +Report the coordinate and value of individual pixels indicated by pressing button 3. +This is a mode of operation canceled by pressing button 1 or 2. +.TP +.B close +Close the specified image. +If the image is the unmagnified file, also close any magnified views of that file. +.TP +.B exit +Quit +.IR tweak . +The program will complain once about modified but unwritten files. +.SH SOURCE +.B /sys/src/cmd/tweak.c +.SH "SEE ALSO" +.IR cachechars (2), +.IR image (6), +.IR font (6) +.SH BUGS +For a program written to adjust width tables in fonts, +.I tweak +has been pushed unreasonably far. diff --git a/sys/man/1/uniq b/sys/man/1/uniq new file mode 100755 index 000000000..65fcd49fa --- /dev/null +++ b/sys/man/1/uniq @@ -0,0 +1,59 @@ +.TH UNIQ 1 +.SH NAME +uniq \- report repeated lines in a file +.SH SYNOPSIS +.B uniq +[ +.B -udc +[ +.BI +- num +] +] +[ +.I file +] +.SH DESCRIPTION +.I Uniq +copies the input +.IR file , +or the standard input, to the +standard output, comparing adjacent lines. +In the normal case, the second and succeeding copies +of repeated lines are +removed. +Repeated lines must be adjacent +in order to be found. +.TP +.B -u +Print unique lines. +.TP +.B -d +Print (one copy of) duplicated lines. +.TP +.B -c +Prefix a repetition count and a tab to each output line. +Implies +.B -u +and +.BR -d . +.TP +.BI - num +The first +.IR num +fields +together with any blanks before each are ignored. +A field is defined as a string of non-space, non-tab characters +separated by tabs and spaces from its neighbors. +.TP +.BI + num +The first +.IR num +characters are ignored. +Fields are skipped before characters. +.SH SOURCE +.B /sys/src/cmd/uniq.c +.SH "SEE ALSO" +.IR sort (1) +.SH BUGS +Field selection and comparison should be compatible with +.IR sort (1). diff --git a/sys/man/1/units b/sys/man/1/units new file mode 100755 index 000000000..504c26f2e --- /dev/null +++ b/sys/man/1/units @@ -0,0 +1,107 @@ +.TH UNITS 1 +.if n .ds / / +.SH NAME +units \- conversion program +.SH SYNOPSIS +.B units +[ +.B -v +] +[ +.I file +] +.SH DESCRIPTION +.I Units +converts quantities expressed +in various standard scales to +their equivalents in other scales. +It works interactively in this fashion: +.IP +.EX +you have: inch +you want: cm + * 2.54 + / 0.393701 +.EE +.PP +A quantity is specified as a multiplicative combination +of units and floating point numbers. +Operators have the following precedence: +.IP +.EX +.ta \w'\fLXXXXXXXXXXXXXXX'u +\fL+\fP \fL-\fP \f1add and subtract +\fL*\fP \fL/\fP \fL×\fP \fL÷\fP \f1multiply and divide +catenation multiply +\fL²\fP \fL³\fP \fL^\fP \f1exponentiation +\fL|\fP \f1divide +\fL(\fP ... \fL)\fP \f1grouping +.EE +.PP +Most familiar units, +abbreviations, and metric prefixes are recognized, +together with a generous leavening of exotica +and a few constants of nature including: +.IP +.de fq +\fL\\$1\\fP \\$2 \\$3 \\$4 \\$5 \\$6 +.. +.ta \w'\fLwaterXXX'u +.nf +.fq pi,\f1π\fP ratio of circumference to diameter +.fq c speed of light +.fq e charge on an electron +.fq g acceleration of gravity +.fq force same as \fLg\fP +.fq mole Avogadro's number +.fq water "pressure head per unit height of water" +.fq au astronomical unit +.fi +.PP +The +.L pound +is a unit of +mass. +Compound names are run together, e.g. +.LR lightyear . +British units that differ from their US counterparts +are prefixed thus: +.LR brgallon . +Currency is denoted +.LR belgiumfranc , +.LR britainpound , +etc. +.PP +The complete list of units can be found in +.BR /lib/units . +A +.I file +argument to +.I units +specifies a file to be used instead of +.BR /lib/units. +The +.B -v +flag causes +.I units +to print its entire database. +.SH EXAMPLE +.EX +you have: 15 pounds force/in² +you want: atm + * 1.02069 + / .97973 +.EE +.SH FILES +.B /lib/units +.SH SOURCE +.B /sys/src/cmd/units.y +.SH BUGS +Since +.I units +does only multiplicative scale changes, +it can convert Kelvin to Rankine but not Centigrade to +Fahrenheit. +.PP +Currency conversions are only as accurate as the last time someone +updated the database. diff --git a/sys/man/1/uptime b/sys/man/1/uptime new file mode 100755 index 000000000..75470077b --- /dev/null +++ b/sys/man/1/uptime @@ -0,0 +1,21 @@ +.TH UPTIME 1 +.SH NAME +uptime \- show how long the system has been running +.SH SYNOPSIS +.B uptime +.SH DESCRIPTION +.I Uptime +shows how long the system has been running. It uses the following format: +.PP +.B + sysname up 33 days, 17:56:42 +.PP +The time given accounts for the timezone. + +..SH FILES +.TF /dev/time +.TF /dev/sysname +.SH SOURCE +.B /rc/bin/uptime +.SH "SEE ALSO" +.IR date (1) diff --git a/sys/man/1/vac b/sys/man/1/vac new file mode 100755 index 000000000..0cf30b01d --- /dev/null +++ b/sys/man/1/vac @@ -0,0 +1,176 @@ +.TH VAC 1 +.SH NAME +vac, unvac \- create, extract a vac archive on Venti +.SH SYNOPSIS +.B vac +[ +.B -mqsv +] [ +.B -b +.I blocksize +] [ +.B -d +.I oldvacfile +] [ +.B -e +.I exclude +] [ +.B -f +.I vacfile +] [ +.B -i +.I name +] [ +.B -h +.I host +] +.I file ... +.PP +.B unvac +[ +.B -Tctv +] [ +.B -h +.I host +] +.I vacfile +[ +.I file ... +] +.SH DESCRIPTION +.I Vac +creates an archival copy of Plan 9 file trees on Venti. It can be used +to build a simple backup system. One of the unusual properties of Venti is +that duplicate blocks are detected and coalesced. When +.I vac +is used on a file tree that shares data with an existing archive, the consumption of +storage will be approximately equal to an incremental backup. +This reduction in storage consumption occurs transparently to the user. +.PP +As an optimization, the +.B -d +and +.B -q +options, described below, can be used to explicitly create an archive relative to an existing archive. +These options do not change the resulting archive generated by +.IR vac , +but simply reduce the number of write operations to Venti. +.PP +The output of +.I vac +is the hexadecimal representation of the SHA1 fingerprint of the root of the archive, in this format: +.IP +.EX +vac:64daefaecc4df4b5cb48a368b361ef56012a4f46 +.EE +.PP +The options to +.I vac +are: +.TF "-d\fI oldvacfile" +.PD +.TP +.BI -b " blocksize +Specifies the block size that data will be broken into. +The units for the size can be specified by appending +.L k +to indicate kilobytes. +The default is 8k. +The size must be in the range +of 512 bytes to 52k. +.TP +.BI -d " oldvacfile +Reduce the number of blocks written to Venti by comparing the files to be stored with +the contents of an existing +.I vac +file tree whose score is stored in +.IR oldvacfile . +.TP +.BI -e " exclude +Do not include the file or directory specified by +.IR exclude . +This option may be repeated multiple times. +.TP +.BI -f " vacfile +The results of +.I vac +are placed in +.IR vacfile , +or the standard output if no file is given. +.TP +.BI -i " name +Include standard input as one of the input files, storing it in the archive +with the specified +.IR name . +.TP +.BI -h " host +The network address of the Venti server. +The default is taken from the environment variable +.BR venti . +If this variable does not exist, then the default is the +metaname +.BR $venti , +which can be configured via +.IR ndb (6). +.TP +.B -m +Expand and merge any +.I vac +archives that are found while reading the input files. This option is +useful for building an archive from a collection of existing archives. Each archive is inserted +into the new archive as if it had been unpacked in the directory in which it was found. Multiple +archives can be unpacked in a single directory and the contents will be merged. To be detected, the +archives must end in +.LR .vac . +Note, an archive is inserted by simply copying the root fingerprint and does not require +the archive to be unpacked. +.TP +.B -q +Increase the performance of the +.B -d +option by detecting unchanged files based on a match of the files name and other meta data, +rather than examining the contents of the files. +.TP +.B -s +Print out various statistics on standard error. +.TP +.B -v +Produce more verbose output on standard error, including the name of the files added to the archive +and the vac archives that are expanded and merged. +.PP +.I Unvac +lists or extracts files stored in the vac archive +.IR vacfile , +which can be either a vac archive string in the format +given above or the name of a file containing one. +If +.I file +arguments are given, only those files or directories +will be extracted. +The options are: +.TP +.B -T +Set the modification time on extracted files +to the time listed in the archive. +.TP +.B -c +Write extracted files to standard output instead of creating a file. +.TP +.B -h +as per +.IR vac . +.TP +.B -t +Print a list of the files to standard output rather than extracting them. +.TP +.B -v +If extracting files, print the name of each file and directory +to standard error. +If listing files, print metadata in addition to the names. +.SH SOURCE +.B /sys/src/cmd/vac +.br +.B /sys/src/cmd/unvac +.SH "SEE ALSO" +.IR vacfs (4), +.IR venti (8) diff --git a/sys/man/1/venti b/sys/man/1/venti new file mode 100755 index 000000000..4b9510338 --- /dev/null +++ b/sys/man/1/venti @@ -0,0 +1,153 @@ +.TH VENTI 1 +.SH NAME +read, write, copy \- simple Venti clients +.SH SYNOPSIS +.B venti/read +[ +.B -h +.I host +] +[ +.B -t +.I type +] +.I score +.br +.B venti/write +[ +.B -z +] +[ +.B -h +.I host +] +[ +.B -t +.I type +] +.br +.B venti/copy +[ +.B -fir +] +[ +.B -t +.I type +] +.I srchost +.I dsthost +.I score +[ +.I type +] +.SH DESCRIPTION +Venti is a SHA1-addressed block storage server. +See +.IR venti (6) +for a full introduction. +.PP +.I Read +reads a block with the given +.I score +and numeric +.I type +from the server +.I host +and prints the block to standard output. +If the +.B -h +option is omitted, +.I read +consults the environment variable +.B $venti +for the name of the Venti server. +If the +.B -t +option is omitted, +.I read +will try each type, one at a time, until it finds +one that works. +It prints the corresponding +.B read +.B -t +command to standard error +to indicate the type of the block. +.PP +.I Write +writes at most 56 kilobytes of data from standard input +to the server +.I host +and prints the resulting score to standard output. +If the +.B -t +option is omitted, +.I write +uses type 0, +denoting a data block. +If the +.B -z +option is given, +.I write +zero truncates the block before writing it to the server. +.PP +.I Copy +expects +.I score +to be the score of a +.B VtRoot +block. +It copies the entire tree of blocks reachable from +the root block from the server +.I srchost +to the server +.IR dsthost . +.PP +The +.B -f +option causes +.I copy +to run in `fast' mode, +assuming that if a block already exists on the +destination Venti server, all its children also +exist and need not be checked. +.PP +The +.B -i +and +.B -r +options control +.IR copy 's +reaction to errors reading +from +.IR srchost . +.I Copy +always prints information to standard error +about each read error. +By default, +.I copy +exits after printing the first error. +If the +.B -i +option is given, read errors are ignored. +This is dangerous behavior because it breaks the +assumption made by `fast' mode. +If the +.B -r +option is given, +.I copy +replaces pointers to unreadable blocks with +pointers to the zero block. +It writes the new root score to standard output. +.SH SOURCE +.B /sys/src/cmd/venti +.SH SEE ALSO +.IR vac (1), +.IR venti (2), +.IR vacfs (4), +.IR venti (6), +.IR venti (8), +.IR venti-backup (8), +.IR venti-fmt (8) +.SH BUGS +There should be programs to read and write +venti files and directories. diff --git a/sys/man/1/vi b/sys/man/1/vi new file mode 100755 index 000000000..1adf8d209 --- /dev/null +++ b/sys/man/1/vi @@ -0,0 +1,170 @@ +.TH VI 1 +.SH NAME +5i, ki, vi, qi \- instruction simulators +.SH SYNOPSIS +.B vi +[ +.I textfile +] +.br +.B vi +.I pid +.br +.B 5i +[ +.I textfile +] +.br +.B 5i +.I pid +.br +.B ki +[ +.I textfile +] +.br +.B ki +.I pid +.br +.B qi +[ +.I textfile +] +.br +.B qi +.I pid +.SH DESCRIPTION +.I Vi +simulates the execution of a MIPS binary in +a Plan 9 environment. +It has two main uses: as +a debugger and as a statistics gatherer. +Programs running under +.I vi +execute about two hundred times +slower than normal\(embut faster than +single stepping under +.IR db . +.IR 5i , +.IR ki , +and +.IR qi +are similar to +.I vi +but interpret ARM, SPARC, and PowerPC binaries. +The following discussion refers to +.I vi +but applies to the others +as well. +.PP +.I Vi +will simulate the execution of a named +.IR textfile . +It will also make a copy of an existing process with process id +.I pid +and simulate its continuation. +.PP +As a debugger +.I vi +offers more complete information +than +.IR db (1). +Tracing can be performed at the level of instructions, +system calls, or function calls. +.I Vi +allows breakpoints to be triggered when specified addresses +in memory are accessed. +A report of instruction counts, +load delay fills and distribution is produced for +each run. +.I Vi +simulates the CPU's caches and MMU +to assist the optimization of compilers and programs. +.PP +The command interface mirrors the interface to +.IR db ; +see +.IR db (1) +for a detailed description. +Data formats and addressing are compatible with +.I db +except +for disassembly: +.I vi +offers only MIPS +.RB ( db +.BR -mmipsco ) +mnemonics for +machine instructions. +.I Ki +offers both Plan 9 and Sun SPARC formats. +.PP +Several extra commands allow +extended tracing and printing of statistics: +.TP +.BR $t [ 0ics ] +The +.I t +command controls tracing. Zero cancels all tracing +options. +.RS +.TP +.B i +Enable instruction tracing +.TP +.B c +Enable call tracing +.TP +.B s +Enable system call tracing +.RE +.TP +.BR $i [ itsp ] +The +.B i +command prints statistics accumulated by +all code run in this session. +.RS +.TP +.B i +Print instruction counts and frequency. +.TP +.B p +Print cycle profile. +.TP +.B t +.RI ( Vi +only) Print TLB and cache statistics. +.TP +.B s +Print memory reference, working set and size statistics. +.RE +.TP +.BR :b [ arwe ] +.I Vi +allows breakpoints to be set on any memory location. +These breakpoints monitor when a location is +accessed, read, written, or equals a certain value. +For equality the compared value is the +.I count +(see +.IR db (1)) +supplied to the command. +.SH SOURCE +.B /sys/src/cmd/vi +etc. +.SH "SEE ALSO" +.IR nm (1), +.IR db (1) +.SH BUGS +The code generated by +the compilers +is well supported, but some unusual instructions are unimplemented. +Some Plan 9 system calls such as +.I rfork +cause simulated traps. +The floating point simulation makes assumptions about the interpreting +machine's floating point support. The floating point conversions performed +by +.I vi +may cause a loss of precision. diff --git a/sys/man/1/vnc b/sys/man/1/vnc new file mode 100755 index 000000000..41f7ffd2f --- /dev/null +++ b/sys/man/1/vnc @@ -0,0 +1,237 @@ +.TH VNC 1 +.SH NAME +vncs, vncv \- remote frame buffer server and viewer for Virtual Network Computing (VNC) +.SH SYNOPSIS +.B vncs +[ +.B -v +] +[ +.B -c +.I cert +] +[ +.B -d +.BI : display +] +[ +.B -g +.IB width x height +] +[ +.B -p +.I pixfmt +] +[ +.B -x +.I net +] +[ +.I cmd +[ +.I args +... +] +] +.PP +.B vncs +.B -k +.BI : display +[ +.B -x +.I net +] +.PP +.B vncv +[ +.B -cstv +] +[ +.B -e +.I encodings +] +[ +.B -k +.I keypattern +] +.IR host [\fL: n ] +.SH DESCRIPTION +VNC is a lightweight protocol +for accessing graphical applications +remotely. The protocol allows one or more +clients to connect to a server. +While connected, clients display the frame buffer +presented by the server and can send mouse events, +keyboard events, and exchange snarf buffers. +The server persists across viewer sessions, so that +the virtual application can be accessed from various locations +as its owner moves around. +.PP +VNC displays have names of the form +.IB host : n \fR, +where +.I host +is the machine's network name and +.I n +is a small integer identifier; display +.I n +is served on TCP port +.RI 5900+ n . +.PP +.I Vncs +starts a new virtual frame buffer in memory, simulating +a Plan 9 terminal running +.I cmd +.IR args , +by default an interactive shell. +As viewers connect, each is authenticated using a +(rather breakable) challenge-response protocol using +the user's Inferno/POP password. +.PP +The options are: +.TF "\fL-p \fIpixfmt" +.PD +.TP +.B -c \fIcert +start TLS on each viewer connection using the certificate +in the file +.IR cert . +The corresponding private key must be loaded into +the server's +.IR factotum (4). +When serving TLS connections, the base port is +35729 rather than 5900. +.TP +.B -d :\fIn +run on display +.I n ; +without this option, the server searches +for an unused display. +.TP +.B -g \fIwidth\fBx\fIheight\fR +set the virtual frame buffer to be +.IB width x height +(default +1024x768) +pixels. +.TP +.B -p \fIpixfmt +set the virtual frame buffer's internal pixel format to +.I pixfmt +(default +.BR r5g6b5 ). +.TP +.B -v +print verbose output to standard error. +.TP +.B -x \fInet +announce on an alternate network interface. +Because of the weak authentication protocol and +default lack of encryption, this option must +be accompanied by +.BR -c . +.PD +.PP +The command +.B vncs +.B -k +.BI : n +kills the VNC server running on display +.IR n . +.PP +.I Vncv +provides access to remote display +.IB host : n \fR. +It resizes its window to be the smaller of the +remote frame buffer size and the local screen. +.PP +The options are: +.TP +.B -c +when connecting to 8-bit displays, request +.B r4g4b4 +pixels rather than +.B r3g3b2 +pixels. +This takes up more bandwidth but usually gives +significantly better matching to the Plan 9 color map. +.TP +.B -e \fIencodings +set the ordered list of allowed frame buffer update encodings. +The default (and full) set is +.B copyrect +.B corre +.B hextile +.B rre +.BR raw . +The encodings should be given as a single space-separated argument +(quoted when using the shell). +.TP +.B -k \fIkeypattern +add +.I keypattern +to the pattern used to select a key from +.IR factotum (4). +.TP +.B -s +share the display with extant viewers; +by default extant viewers are closed +when a new viewer connects. +.TP +.B -t +start TLS on the connection. +.TP +.B -v +print verbose output to standard error. +.PD +.PP +The VNC protocol represents keyboard input as +key up/down events. +Plan 9 does not expose the state of the +Ctl and Shift keys except as it can be inferred +from receipt of control or shifted characters. +It does not expose the state of the Alt key at all, +since the Alt key is used to compose Unicode characters +(see +.IR keyboard (6)). +.I Vncv +correctly handles the sending of control and shifted +characters. +To support systems that use key sequences like Alt-X +(or worse, Alt-mouse-click), typing the Plan 9 compose +sequences +.B Alt +.B Z +.B A +(for Alt), +.B Alt +.B Z +.B C +(for Ctrl), +and +.B Alt +.B Z +.B S +(for Shift) +will send a ``key down'' message for +the given key. +A corresponding ``key up'' message +will be sent after the next key is pressed, +or when the sequence is retyped, +whichever happens first. +.SH SOURCE +.B /sys/src/cmd/vnc +.SH "SEE ALSO +.IR drawterm (8) +.br +.B http://www.uk.research.att.com/vnc +.SH BUGS +If the remote frame buffer is larger than the local screen, +only the upper left corner can be accessed. +.PP +.I Vncv +does no verification of the TLS certificate presented +by the server. +.PP +.I Vncv +supports only version 3.3 of the RFB protocol. diff --git a/sys/man/1/vt b/sys/man/1/vt new file mode 100755 index 000000000..fefd7b8c2 --- /dev/null +++ b/sys/man/1/vt @@ -0,0 +1,135 @@ +.TH VT 1 +.SH NAME +vt \- emulate a VT-100 or VT-220 terminal +.SH SYNOPSIS +.B vt +[ +.B -2abcx +] +[ +.B -f +.I font +] [ +.B -l +.I log +] +.SH DESCRIPTION +.I Vt +replaces a +.I rio +window with a fresh instance of the shell, +.IR rc (1), +running within an emulation of a DEC VT-100 terminal. +To exit +.IR vt , +exit the +.B rc +it starts. +.SS Options +.TF m +.TP +.B 2 +.TP +.B a +.TP +.B x +change +.I vt +to emulate a VT-220, ANSI, or XTerm terminal respectively. +.TP +.B b +changes the color scheme to white text on a black background, +but potentially with colors from escape sequences. +.TP +.B c +changes the color scheme to monochrome (no colors). +.TP +.B f +sets the +.IR font . +.TP +.B l +names a +.I log +file for the session. +.SS Menus +The right button has a menu with the following entries to provide +the sort of character processing expected by non-Plan 9 systems: +.TF cooked +.TP +.B 24x80 +Resize the +.I vt +window to hold 24 rows of 80 columns. +.TP +.B crnl +Print a newline (linefeed) character after receiving a carriage return from the host. +.TP +.B cr +Do not print a newline after carriage return. +.TP +.B nlcr +Print a carriage return after receiving a newline from the host. +.TP +.B nl +Do not print a carriage return after newline. +.TP +.B raw +Enter raw (no echo, no interpretation) character mode for input. +.TP +.B cooked +Leave raw mode. +.TP +.B exit +Exit +.IR vt . +.PD +.PP +The middle button has a menu with the following entries: +.TF right_key +.TP +.B backup +Move the display back one screenful. +.TP +.B forward +Move the display forward one screenful. +(These are a poor substitute for a scroll bar.) +.TP +.B reset +Display the last screenful; the same as going +.B forward +to the end. +.TP +.B clear +Clear the screen. Previous contents can be recovered using +.BR backup . +.TP +.B send +Send the contents of the +.B rio +snarf buffer, just as +.B send +in the +.B rio +menu. +.TP +.B scroll +Make new lines visible as they appear at the bottom. +.TP +.B page +When the page fills, pause and wait for a character to be typed before proceeding. +The down arrow key advances a page without sending the character to the host. +.PD +.SH SOURCE +.B /sys/src/cmd/vt +.SH BUGS +This program is used only for communicating with foreign systems, +so it is not +as rich an emulation as its equivalent in other environments. +.PP +Use care in setting raw and newline modes when connecting to Unix systems +via +.IR con (1) +or +.IR ssh (1). +It may also be necessary to set the emulator into raw mode. diff --git a/sys/man/1/wc b/sys/man/1/wc new file mode 100755 index 000000000..fe2b80340 --- /dev/null +++ b/sys/man/1/wc @@ -0,0 +1,53 @@ +.TH WC 1 +.SH NAME +wc \- word count +.SH SYNOPSIS +.B wc +[ +.B -lwrbc +] +[ +.I file ... +] +.SH DESCRIPTION +.I Wc +counts lines, words, runes, syntactically-invalid +.SM UTF +codes and bytes in the named +.IR files , +or in the standard input if no file is named. +A word is a maximal string of characters +delimited by spaces, tabs or newlines. +The count of runes includes invalid codes. +.PP +If the optional argument is present, +just the specified counts (lines, words, runes, broken +.SM UTF +codes or bytes) +are selected by the letters +.BR l , +.BR w , +.BR r , +.BR b , +or +.BR c . +Otherwise, lines, words and bytes +.RB ( -lwc ) +are reported. +.SH SOURCE +.B /sys/src/cmd/wc.c +.SH BUGS +The Unicode Standard has many blank characters scattered through it, +but +.I wc +looks for only +.SM ASCII +space, tab and newline. +.PP +.I Wc +should have options to count suboptimal +.SM UTF +codes +and bytes that cannot occur in any +.SM UTF +code. diff --git a/sys/man/1/weather b/sys/man/1/weather new file mode 100755 index 000000000..a4ccbd88c --- /dev/null +++ b/sys/man/1/weather @@ -0,0 +1,35 @@ +.TH WEATHER 1 +.SH NAME +weather \- print weather report +.SH SYNOPSIS +.B weather +[ +.I air +] [ +.I st +] +.SH DESCRIPTION +.I Weather +prints the local conditions and seven-day forecast most recently reported at the +.SM US +airport with the three-letter location identifier +.IR air . +Given a two-letter +.SM US +state abbreviation +.I st +instead, +.I weather +prints a table of +.I air +location identifiers known for +.IR st . +.PP +The arguments are mutually exclusive and case-insensitive. +If neither is given, +.I air +defaults to location identifier +.BR ewr , +designating the Newark, NJ, airport near Bell Labs, Murray Hill. +.SH SOURCE +.B /rc/bin/weather diff --git a/sys/man/1/who b/sys/man/1/who new file mode 100755 index 000000000..1a13c3af0 --- /dev/null +++ b/sys/man/1/who @@ -0,0 +1,22 @@ +.TH WHO 1 +.SH NAME +who, whois \- who is using the machine +.SH SYNOPSIS +.B who +.PP +.B whois +.I person +.SH DESCRIPTION +.I Who +prints the name of everyone with a non-Exiting process +on the current machine. +.PP +.I Whois +looks in +.B /adm/whois +and +.B /adm/users +to find out more information about +.IR person . +.SH SOURCE +.B /rc/bin/who diff --git a/sys/man/1/winwatch b/sys/man/1/winwatch new file mode 100755 index 000000000..46183dcc3 --- /dev/null +++ b/sys/man/1/winwatch @@ -0,0 +1,46 @@ +.TH WINWATCH 1 +.SH NAME +winwatch \- monitor rio windows +.SH SYNOPSIS +.B winwatch +[ +.B -e +.I exclude +] [ +.B -f +.I font +] +.SH DESCRIPTION +.I Winwatch +displays the labels of all current +.IR rio (4) +windows, refreshing the display every five seconds. +Right clicking a window's label unhides, raises and gives focus to that window. +Typing +.B q +or +DEL +quits +.IR winwatch . +.PP +If the +.B -e +flag +is given, +windows matching the regular expression +.I exclude +are not shown. +.SH EXAMPLE +Excluding winwatch, stats and faces from being showed. +.IP +.EX +% winwatch -e '^(winwatch|stats|faces)' +.EE +.SH FILES +.B /dev/wsys/*/label +.SH SOURCE +.B /sys/src/cmd/winwatch.c +.SH SEE ALSO +.IR rio (1), +.IR rio (4), +.IR regexp (6). diff --git a/sys/man/1/xd b/sys/man/1/xd new file mode 100755 index 000000000..cc2d394f4 --- /dev/null +++ b/sys/man/1/xd @@ -0,0 +1,87 @@ +.TH XD 1 +.SH NAME +xd \- hex, octal, decimal, or ASCII dump +.SH SYNOPSIS +.B xd +[ +.I option ... +] +[ +.BI - "format ... +] [ +.I file ... +] +.SH DESCRIPTION +.I Xd +concatenates and dumps the +.I files +(standard input by default) +in one or more formats. +Groups of 16 bytes are printed in each of the named formats, one +format per line. +Each line of output is prefixed by its address (byte offset) +in the input file. +The first line of output for each group is zero-padded; subsequent are blank-padded. +.PP +Formats other than +.B -c +are specified by pairs of characters telling size and style, +.L 4x +by default. +The sizes are +.TP \w'2\ or\ w\ \ \ 'u +.BR 1 " or " b +1-byte units. +.PD0 +.TP +.BR 2 " or " w +2-byte big-endian units. +.TP +.BR 4 " or " l +4-byte big-endian units. +.TP +.BR 8 " or " v +8-byte big-endian units. +.PD +.PP +The styles are +.TP 0 +.B o +Octal. +.PD0 +.TP +.B x +Hexadecimal. +.TP +.B d +Decimal. +.PD +.PP +Other options are +.TP \w'\fL-a\fIstyle\fLXX'u +.B -c +Format as +.B 1x +but print +.SM ASCII +representations or C escape sequences where possible. +.TP +.BI -a style +Print file addresses in the given style (and size 4). +.TP +.B -u +(Unbuffered) Flush the output buffer after each 16-byte sequence. +.TP +.B -s +Reverse (swab) the order of bytes in each group of 4 before printing. +.TP +.B -r +Print repeating groups of identical 16-byte sequences as the first group +followed by an asterisk. +.SH SOURCE +.B /sys/src/cmd/xd.c +.SH "SEE ALSO" +.IR db (1) +.SH BUGS +The various output formats don't line up properly in the output of +.IR xd . diff --git a/sys/man/1/yacc b/sys/man/1/yacc new file mode 100755 index 000000000..a965f9537 --- /dev/null +++ b/sys/man/1/yacc @@ -0,0 +1,167 @@ +.TH YACC 1 +.SH NAME +yacc \- yet another compiler-compiler +.SH SYNOPSIS +.B yacc +[ +.I option ... +] +.I grammar +.SH DESCRIPTION +.I Yacc +converts a context-free grammar and translation code +into a set of +tables for an LR(1) parser and translator. +The grammar may be ambiguous; +specified precedence rules are used to break ambiguities. +.PP +The output file, +.BR y.tab.c , +must be compiled by the C compiler +to produce a program +.LR yyparse . +This program must be loaded with a lexical analyzer function, +.B yylex(void) +(often generated by +.IR lex (1)), +with a +.B main(int argc, char *argv[]) +program, and with an error handling routine, +.BR yyerror(char*) . +.PP +The options are +.TP "\w'\fL-o \fIoutput\fLXX'u" +.BI -o " output +Direct output to the specified file instead of +.BR y.tab.c . +.TP +.BI -D n +Create file +.BR y.debug , +containing diagnostic messages. +To incorporate them in the parser, compile it with preprocessor symbol +.B yydebug +defined. +The amount of +diagnostic output from the parser is regulated by +value +.IR n . +The value 0 reports errors; 1 reports reductions; +higher values (up to 4) include more information about +state transitions. +.TP +.B -v +Create file +.BR y.output , +containing a description of the parsing tables and of +conflicts arising from ambiguities in the grammar. +.TP +.B -d +Create file +.BR y.tab.h , +containing +.B #define +statements that associate +.IR yacc -assigned +`token codes' with user-declared `token names'. +Include it in source files other than +.B y.tab.c +to give access to the token codes. +.TP +.BI -s " stem +Change the prefix +.L y +of the file names +.BR y.tab.c , +.BR y.tab.h , +.BR y.debug , +and +.B y.output +to +.IR stem . +.TP +.B -S +Write a parser that uses +Stdio +instead of the +.B print +routines in libc. +.PP +The specification of +.I yacc +itself is essentially the same as the UNIX version +described in the references mentioned below. +Besides the +.B -D +option, the main relevant differences are: +.IP +The interface to the C environment is by default through +.B +rather than +.BR ; +the +.B -S +option reverses this. +.IP +The parser accepts +.SM UTF +input text (see +.IR utf (6)), +which has a couple of effects. +First, the return value of +.B yylex() +no longer fits in a +.BR short ; +second, the starting value for non-terminals is now 0xE000 rather than 257. +.IP +The generated parser can be recursive: actions can call +.IR yyparse , +for example to implement a sort of +.B #include +statement in an interpreter. +.IP +Finally, some undocumented inner workings of the parser have been +changed, which may affect programs that know too much about its structure. +.SH FILES +.TF /sys/lib/yaccpars +.TP +.B y.output +.TP +.B y.tab.c +.TP +.B y.tab.h +.TP +.B y.debug +.TP +.B y.tmp.* +temporary file +.TP +.B y.acts.* +temporary file +.TP +.B /sys/lib/yaccpar +parser prototype +.TP +.B /sys/lib/yaccpars +parser prototype using stdio +.SH SOURCE +.B /sys/src/cmd/yacc.c +.SH "SEE ALSO" +.IR lex (1) +.br +S. C. Johnson and R. Sethi, +``Yacc: A parser generator'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2 +.br +B. W. Kernighan and Rob Pike, +.I +The UNIX Programming Environment, +Prentice Hall, 1984 +.SH BUGS +The parser may not have full information when it writes to +.B y.debug +so that the names of the tokens returned by +.L yylex +may be missing. diff --git a/sys/man/1/yesterday b/sys/man/1/yesterday new file mode 100755 index 000000000..7d924ce47 --- /dev/null +++ b/sys/man/1/yesterday @@ -0,0 +1,156 @@ +.TH YESTERDAY 1 +.SH NAME +yesterday, diffy \- print file names from the dump +.SH SYNOPSIS +.B yesterday +[ +.B -abcCdDs +] [ +.B -n +.I daysago +] [ +.I \-date +] +.I files ... +.PP +.B diffy +[ +.B -abcefmnrw +] +.I files ... +.SH DESCRIPTION +.I Yesterday +prints the names of the +.I files +from the most recent dump. +Since dumps are done early in the morning, +yesterday's files are really in today's dump. +For example, if today is March 17, 1992, +.IP +.EX +yesterday /adm/users +.EE +.PP +prints +.IP +.EX +/n/dump/1992/0317/adm/users +.EE +.PP +In fact, the implementation is to select the most recent dump in +the current year, so the dump selected may not be from today. +.PP +When presented with a path of the form +.BI /n/ fs / path \fR, +.I yesterday +will look for +dump files of the form +\fL/n/\fIfs\fLdump/\fIyyyy\fL/\fIhhmm\fL/\fIpath\fR. +.PP +By default, +.I yesterday +prints the names of the dump files corresponding to the named files. +The first set of options changes this behavior. +.TP +.B -a +Run +.IR acme (1)'s +.I adiff +to compare the dump files with the named files. +.TP +.B -b +Bind the dump files over the named files. +.TP +.B -c +Copy the dump files over the named files. +.TP +.B -C +Copy the dump files over the named files only when +they differ. +.TP +.B -d +Run +.B diff +to compare the dump files with the named files. +.TP +.B -D +Run +.B diff +.B -n +to compare the dump files with the named files. +.PP +The +.I date +option selects other day's dumps, with a format of +1, 2, 4, 6, or 8 digits of the form +.IR d, +.IR dd , +.IR mmdd , +.IR yymmdd , +or +.IR yyyymmdd . +.PP +The +.B -n +option selects the dump +.I daysago +prior to the current day. +.PP +The +.B -s +option selects the most recent snapshot instead of the most +recent archived dump. Snapshots may occur more frequently +than dumps. +.PP +.I Yesterday +does not guarantee that the string it prints represents an existing file. +.PP +.I Diffy +runs +.IR diff (1) +with the given options +to compare yesterday's version of each of the named files +with today's. +.SH EXAMPLES +.PP +Back up to yesterday's MIPS binary of +.BR vc : +.IP +.EX +yesterday -c /mips/bin/vc +.EE +.PP +Temporarily back up to March 1's MIPS C library to see if a program +runs correctly when loaded with it: +.IP +.EX +yesterday -b -0301 /mips/lib/libc.a +rm v.out +mk +v.out +.EE +.PP +Find what has changed in the C library since March 1: +.IP +.EX +yesterday -d -0301 /sys/src/libc/port/*.c +.EE +.PP +Find what has changed in the source tree today: +.IP +.EX +diffy -r /sys/src +.EE +.SH FILES +.B /n/dump +.SH SOURCE +.B /rc/bin/yesterday +.br +.B /rc/bin/diffy +.SH SEE ALSO +.IR history (1), +.IR bind (1), +.IR diff (1), +.IR fs (4). +.SH BUGS +It's hard to use this command without singing. diff --git a/sys/man/2/0intro b/sys/man/2/0intro new file mode 100755 index 000000000..ad5ea1c4a --- /dev/null +++ b/sys/man/2/0intro @@ -0,0 +1,457 @@ +.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 needs +.BR . +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 uchar , +.IR ushort , +.IR uint , +and +.IR ulong , +the unsigned integer types; +.IR schar , +the signed char type; +.I vlong +and +.IR uvlong , +the signed and unsigned very long integral types; +.IR Rune , +the Unicode character type; +.IR u8int , +.IR u16int , +.IR u32int , +and +.IR u64int , +the unsigned integral types with specific widths; +.IR uintptr , +the unsigned integral type with the same width as a pointer; +.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); +and +the macros +.B va_arg +and friends for accessing arguments of variadic functions (identical to the +macros defined in +.B +in ANSI C). +.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 +.I "path elements" +with the slashes corresponding to directories. +A path element must contain only printable +characters (those outside the control spaces of +.SM ASCII +and Latin-1). +A path element cannot contain a 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" . +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 +(see +.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 +.IR wait (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 examples of this design, see +.IR ioproc (2) +or +.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. diff --git a/sys/man/2/9p b/sys/man/2/9p new file mode 100755 index 000000000..5ec62552f --- /dev/null +++ b/sys/man/2/9p @@ -0,0 +1,788 @@ +.TH 9P 2 +.SH NAME +Srv, +dirread9p, +emalloc9p, +erealloc9p, +estrdup9p, +listensrv, +postfd, +postmountsrv, +readbuf, +readstr, +respond, +responderror, +threadlistensrv, +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 *r); + void (*auth)(Req *r); + void (*open)(Req *r); + void (*create)(Req *r); + void (*read)(Req *r); + void (*write)(Req *r); + void (*remove)(Req *r); + void (*flush)(Req *r); + void (*stat)(Req *r); + void (*wstat)(Req *r); + void (*walk)(Req *r); + + char* (*walk1)(Fid *fid, char *name, Qid *qid); + char* (*clone)(Fid *oldfid, Fid *newfid); + + void (*destroyfid)(Fid *fid); + void (*destroyreq)(Req *r); + void (*end)(Srv *s); + void* aux; + + int infd; + int outfd; + int srvfd; + int nopipe; +} Srv; +.fi +.PP +.nf +.ft L +.ta \w'\fLvoid* 'u +int srv(Srv *s) +void postmountsrv(Srv *s, char *name, char *mtpt, int flag) +void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag) +void listensrv(Srv *s, char *addr) +void threadlistensrv(Srv *s, char *addr) +int postfd(char *srvname, int fd) +void respond(Req *r, char *error) +void responderror(Req*) +void readstr(Req *r, char *src) +void readbuf(Req *r, void *src, long nsrc) +typedef int Dirgen(int n, Dir *dir, void *aux) +void dirread9p(Req *r, Dirgen *gen, void *aux) +void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v), + char *(*clone)(Fid *old, Fid *new, void *v), void *v) +.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 +serves a 9P session by reading requests from +.BR s->infd , +dispatching them to the function pointers kept in +.BR Srv , +and +writing the responses to +.BR s->outfd . +(Typically, +.I postmountsrv +or +.I threadpostmountsrv +initializes the +.B infd +and +.B outfd +structure members. See the description below.) +.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. +.PP +.I Srv +does not return until the 9P conversation is finished. +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 estrdup9p +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. +.PP +.I Postmountsrv +and +.I threadpostmountsrv +are wrappers that create a separate process in which to run +.IR srv . +They do the following: +.IP +If +.IB s -> nopipe +is zero (the common case), +initialize +.IB s -> infd +and +.IB s -> outfd +to be one end of a freshly allocated pipe, +with +.IB s -> srvfd +initialized as the other end. +.IP +If +.B name +is non-nil, call +.BI postfd( s -> srvfd , +.IB name ) +to post +.IB s -> srvfd +as +.BI /srv/ name . +.IP +Fork a child process via +.I rfork +(see +.IR fork (2)) +or +.I procrfork +(see +.IR thread (2)), +using the +.BR RFFDG , +.RR RFNOTEG , +.BR RFNAMEG , +and +.BR RFMEM +flags. +The child process +calls +.IB close( s -> srvfd ) +and then +.IB srv( s ) \fR; +it will exit once +.I srv +returns. +.IP +If +.I mtpt +is non-nil, +call +.BI amount( s -> srvfd, +.IB mtpt , +.IB flag , +\fB"")\fR; +otherwise, close +.IB s -> srvfd \fR. +.IP +The parent returns to the caller. +.LP +If any error occurs during +this process, the entire process is terminated by calling +.I sysfatal +(see +.IR perror (2)). +.PP +.I Listensrv +and +.I threadlistensrv +create a separate process to announce as +.IR addr . +The process listens for incoming connections, +creating a new process to serve each. +Using these functions results in +.I srv +and the service functions +being run in multiple processes simultaneously. +The library locks its own data structures as necessary; +the client may need to lock data it shares between +the multiple connections. +.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 +.IR 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.oldtag \fR. +The outgoing response data should be stored in +.IB r -> ofcall \fR. +The one exception to this rule is that +.I 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, +.I 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 +.I 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 +.I 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 +.I Responderror +calls +.I respond +with the system error string +(see +.IR errstr (2)). +.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 +.IB r -> afid +is the new authentication fid and +set +.IB r -> 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 +.I 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 +.I 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 +.IB r -> ifcall . wname +and +.IB r -> ifcall . nwname \fR, +filling in +.IB ofcall . qid +and +.IB ofcall . nqid \fR, +and also copying any necessary +.I aux +state from +.IB r -> fid +to +.IB r -> newfid +when the two are different. +As long as +.I walk +sets +.IB 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. +.IP +Because implementing the full walk message is intricate and +prone to error, the helper routine +.I walkandclone +will handle the request given pointers to two functions +.I walk1 +and (optionally) +.I clone . +.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 +.IB fid -> qid +to the new path's qid. +Both should return nil +on success or an error message on error. +.I Walkandclone +will call +.I respond +after handling the request. +.TP +.I Walk1\fR, \fPClone +If the client provides functions +.IB srv -> walk1 +and (optionally) +.IB srv -> clone \fR, +the 9P service loop will call +.I walkandclone +with these functions to handle the request. +Unlike the +.I walk1 +above, +.IB srv -> walk1 +must fill in both +.IB fid -> qid +and +.BI * qid +with the new qid on a successful walk. +.TP +.I 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. +.IP +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 +.I 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 +.I 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 +.I 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 -> ifcall . 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 +.IB r -> ifcall \fR, +they fill +.IB r -> ofcall . data +and set +.IB r -> ofcall . count \fR; +they do not call +.IB 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 +.IR 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 +.I 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 . count +bytes of +.IB r -> ifcall . data +to offset +.IB r -> ifcall . offset +of the file, setting +.IB r -> ofcall . count +to the number of bytes actually written. +Most programs consider it an error to +write less than the requested amount. +.TP +.I 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 +.I Flush +Servers that always call +.I respond +before returning from the service functions +need not provide a +.I flush +implementation: +.I flush +is only necessary in programs +that arrange for +.I respond +to be called asynchronously. +.I Flush +should cause the request +.IB r -> oldreq +to be cancelled or hurried along. +If +.I oldreq +is cancelled, this should be signalled by calling +.I respond +on +.I oldreq +with error string +.RB ` interrupted '. +.I Flush +must respond to +.I r +with a nil error string. +.I Flush +may respond to +.I r +before forcing a response to +.IB r -> oldreq \fR. +In this case, the library will delay sending +the +.I Rflush +message until the response to +.IB r -> oldreq +has been sent. +.PD +.PP +.IR Destroyfid , +.IR destroyreq , +and +.I end +are auxiliary functions, not called in direct response to 9P requests. +.TP +.I 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 +.IB fid -> aux +pointer. +.TP +.I Destroyreq +Similarly, when a +.BR Req 's +reference count drops to zero +.RI ( i.e. , +it has been handled via +.I respond +and other outstanding pointers to it have been closed), +.I destroyreq +is called to allow the program to dispose of the +.IB r -> aux +pointer. +.TP +.I 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 was used by the Palm Pilot synchronization +file system (never finished) to gracefully terminate the serial conversation once +the file system had 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/sys/man/2/9pcmdbuf b/sys/man/2/9pcmdbuf new file mode 100755 index 000000000..83dcef887 --- /dev/null +++ b/sys/man/2/9pcmdbuf @@ -0,0 +1,120 @@ +.TH 9PCMDBUF 2 +.SH NAME +Cmdbuf, parsecmd, respondcmderror, lookupcmd \- control message parsing +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fL1234'u +\w'\fL12345678'u +typedef struct Cmdbuf +{ + char *buf; + char **f; + int nf; +} Cmdbuf; + +typedef struct Cmdtab +{ + int index; + char *cmd; + int narg; +}; + +Cmdbuf *parsecmd(char *p, int n) +Cmdtab *lookupcmd(Cmdbuf *cb, Cmdtab *tab, int ntab) +void respondcmderror(Req *r, Cmdbuf *cb, char *fmt, ...) +.fi +.SH DESCRIPTION +These data structures and functions provide parsing of textual control messages. +.PP +.I Parsecmd +treats the +.I n +bytes at +.I p +(which need not be NUL-terminated) as a UTF string and splits it +using +.I tokenize +(see +.IR getfields (2)). +It returns a +.B Cmdbuf +structure holding pointers to each field in the message. +It is the caller's responsibility to +free this structure when it is no longer needed. +.PP +.I Lookupcmd +walks through the array +.IR ctab , +which has +.I ntab +entries, +looking for the first +.B Cmdtab +that matches the parsed command. +(If the parsed command is empty, +.I lookupcmd +returns nil immediately.) +A +.B Cmdtab +matches the command if +.I cmd +is equal to +.IB cb -> f [0] +or if +.I cmd +is +.LR * . +Once a matching +.B Cmdtab +has been found, if +.I narg +is not zero, then the parsed command +must have exactly +.I narg +fields (including the command string itself). +If the command has the wrong number of arguments, +.I lookupcmd +returns nil. +Otherwise, it returns a pointer to the +.B Cmdtab +entry. +If +.I lookupcmd +does not find a matching command at all, +it returns nil. +Whenever +.I lookupcmd +returns nil, it sets the system error string. +.PP +.I Respondcmderror +resoponds to request +.I r +with an error of the form +`\fIfmt\fB:\fI cmd\fR,' +where +.I fmt +is the formatted string and +.I cmd +is a reconstruction of the parsed command. +Fmt +is often simply +.B "%r" . +.SH EXAMPLES +This interface is not used in any distributed 9P servers. +It was lifted from the Plan 9 kernel. +Almost any kernel driver +.RB ( /sys/src/9/*/dev*.c ) +is a good example. +.SH SOURCE +.B /sys/src/lib9p/parse.c +.SH SEE ALSO +.IR 9p (2) diff --git a/sys/man/2/9pfid b/sys/man/2/9pfid new file mode 100755 index 000000000..6ad79aa85 --- /dev/null +++ b/sys/man/2/9pfid @@ -0,0 +1,207 @@ +.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 <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 ifcall; + Fcall ofcall; + Req *oldreq; + void *aux; + Fid *fid; + Fid *afid; + Fid *newfid; + \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) +Fid* removefid(Fidpool *p, ulong fid); +void closefid(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) +Req* removereq(Reqpool *p, ulong tag); +void closereq(Req *f) +.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 lookupfid +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/sys/man/2/9pfile b/sys/man/2/9pfile new file mode 100755 index 000000000..668d61689 --- /dev/null +++ b/sys/man/2/9pfile @@ -0,0 +1,223 @@ +.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 <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, uchar *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, listensrv, postfd, postmountsrv, readbuf, readstr, respond, responderror, threadlistensrv, threadpostmountsrv, srv + +
9pcmdbuf +- control message parsing +
Cmdbuf, parsecmd, respondcmderror, lookupcmd + +
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, aesCTRencrypt, aesCTRdecrypt, setupAESXCBCstate, aesXCBCmac + +
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 + +
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 +- routines for authenticating users +
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 + +
authsrv +- routines for communicating with authentication servers +
authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp + +
avl +- AVL tree routines +
mkavltree, insertavl, lookupavl, deleteavl, avlwalk, avlnext, avlprev, endwalk + +
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 + +
complete +- file name completion +
complete + +
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, cycles + +
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 PB L +
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 + +
dsa +- digital signature algorithm +
dsagen, dsasign, dsaverify, dsapuballoc, dsapubfree, dsaprivalloc, dsaprivfree, dsasigalloc, dsasigfree, dsaprivtopub + +
dup +- duplicate an open file descriptor +
dup + +
elgamal +- elgamal encryption +
eggen, egencrypt, egdecrypt, egsign, egverify, 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, _privates, _nprivates, _tos + +
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, sizeS2M, 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 + +
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, 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, hvprint, hwrite, hxferenc, + +
hypot +- Euclidean distance +
hypot + +
intmap +- integer to data structure maps +
Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey, deletekey + +
ioproc +- slave I/O processes for threaded programs +
closeioproc, iocall, ioclose, iointerrupt, iodial, ioopen, ioproc, ioread, ioreadn, iowrite + +
iounit +- return size of atomic I/O unit for file descriptor +
iounit + +
ip +- Internet Protocol addressing +
eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip4, equivip6, defmask, isv4, v4tov6, v6tov4, nhgetv, nhgetl, nhgets, hnputv, 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 +- spin locks, queueing rendezvous locks, reader-writer locks, rendezvous points, and reference counts +
lock, canlock, unlock, qlock, canqlock, qunlock, rlock, canrlock, runlock, wlock, canwlock, wunlock, rsleep, rwakeup, rwakeupall, 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, mallocalign, 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, 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, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetvalue, ndbfree, ipattr, ndbgetipaddr, ndbipinfo, csipinfo, ndbhash, ndbparse, csgetvalue, ndbfindattr, dnsquery, ndbdiscard, ndbconcatenate, ndbreorder, ndbsubstitute, ndbgetval, csgetval, ndblookval + +
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, poolallocalign, 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, readcertchain + +
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, needsrcquote + +
rand +- random number generators +
rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, genrandom, prng, 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 +- RSA encryption algorithm +
asn1dump, asn1toRSApriv, decodePEM, rsadecrypt, rsaencrypt, rsagen, rsaprivalloc, rsaprivfree, rsaprivtopub, rsapuballoc, rsapubfree, X509toRSApub, X509gen, X509verify + +
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, closescsi, scsiready, scsi, scsicmd, scsierror + +
sechash +- cryptographically secure hashes +
md4, md5, sha1, sha2_224, sha2_256, sha2_384, sha2_512, aes, hmac_x, hmac_md5, hmac_sha1, hmac_sha2_224, hmac_sha2_256, hmac_sha2_384, hmac_sha2_512, hmac_aes, 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 + +
semacquire +- user level semaphores +
semacquire, semrelease + +
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, chanclose, chancreate, chanfree, chaninit, chanclosing, 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, threadsetgrp, threadsetname, threadwaitchan, yield + +
time +- time in seconds and nanoseconds since epoch +
time, nsec + +
tmpfile +- Stdio temporary files +
tmpfile, tmpnam + +
usb +- USB device driver library +
usbcmd, classname, closedev, configdev, devctl, finddevs, loaddevstr, matchdevcsp, opendev, opendevdata, openep, startdevs, unstall, class, subclass, proto, CSP + +
usbfs +- USB device driver file system library +
usbreadbuf, usbfsadd, usbfsdel, usbdirread, usbfsinit, usbdirfs, usbfs + +
venti +- archival storage server +
venti + +
venti-cache +- Venti block cache +
VtBlock, VtCache, vtblockcopy, vtblockdirty, vtblockduplock, vtblockput, vtblockwrite, vtcachealloc, vtcacheallocblock, vtcacheblocksize, vtcachefree, vtcacheglobal, vtcachelocal, vtcachesetwrite, vtglobaltolocal, vtlocaltoglobal + +
venti-client +- Venti client +
vtconnect, vthello, vtread, vtwrite, vtreadpacket, vtwritepacket, vtsync, vtping, vtrpc, ventidoublechecksha1 + +
venti-conn +- Venti network connections +
VtConn, vtconn, vtdial, vtfreeconn, vtsend, vtrecv, vtversion, vtdebug, vthangup + +
venti-fcall +- venti data formats +
VtEntry, VtFcall, VtRoot, vtentrypack, vtentryunpack, vtfcallclear, vtfcallfmt, vtfcallpack, vtfcallunpack, vtfromdisktype, vttodisktype, vtgetstring, vtputstring, vtrootpack, vtrootunpack, vtparsescore, vtscorefmt + +
venti-file +- Venti files +
VtFile, vtfileblock, vtfileblockscore, vtfileclose, vtfilecreate, vtfilecreateroot, vtfileflush, vtfileflushbefore, vtfilegetdirsize, vtfilegetentry, vtfilegetsize, vtfileincref, vtfilelock, vtfilelock2, vtfileopen, vtfileopenroot, vtfileread, vtfileremove, vtfilesetdirsize, vtfilesetentry, vtfilesetsize, vtfiletruncate, vtfileunlock, vtfilewrite + +
venti-log +- Venti logs +
VtLog, VtLogChunk, vtlog, vtlogclose, vtlogdump, vtlognames, vtlogopen, vtlogprint, vtlogremove, vtlogopen, ventilogging + +
venti-mem +- error-checking memory allocators +
vtbrk, vtmalloc, vtmallocz, vtrealloc, vtstrdup, vtfree + +
venti-packet +- zero-copy network buffers +
Packet, packetalloc, packetappend, packetasize, packetcmp, packetconcat, packetconsume, packetcopy, packetdup, packetforeign, packetfragments, packetfree, packetheader, packetpeek, packetprefix, packetsha1, packetsize, packetsplit, packetstats, packettrailer, packettrim + +
venti-server +- Venti server +
vtsrvhello, vtlisten, vtgetreq, vtrespond + +
venti-zero +- Venti block truncation +
vtzerotruncate, vtzeroextend, vtzeroscore + +
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/sys/man/2/abort b/sys/man/2/abort new file mode 100755 index 000000000..feec9d856 --- /dev/null +++ b/sys/man/2/abort @@ -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/sys/man/2/abs b/sys/man/2/abs new file mode 100755 index 000000000..b2df7fba6 --- /dev/null +++ b/sys/man/2/abs @@ -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/sys/man/2/access b/sys/man/2/access new file mode 100755 index 000000000..25c368320 --- /dev/null +++ b/sys/man/2/access @@ -0,0 +1,60 @@ +.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 for open is 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.) diff --git a/sys/man/2/addpt b/sys/man/2/addpt new file mode 100755 index 000000000..9738c51bf --- /dev/null +++ b/sys/man/2/addpt @@ -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/sys/man/2/aes b/sys/man/2/aes new file mode 100755 index 000000000..caae33630 --- /dev/null +++ b/sys/man/2/aes @@ -0,0 +1,101 @@ +.TH AES 2 +.SH NAME +setupAESstate, aesCBCencrypt, aesCBCdecrypt, aesCTRencrypt, aesCTRdecrypt, setupAESXCBCstate, aesXCBCmac - advanced encryption standard (rijndael) +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.in +0.5i +.ti -0.5i +.B +void aes_encrypt(ulong rk[], int Nr, uchar pt[16], uchar ct[16]); +.PP +.B +void aes_decrypt(ulong rk[], int Nr, uchar ct[16], uchar pt[16]); +.PP +.B +void setupAESstate(AESstate *s, uchar key[], int keybytes, uchar *ivec) +.PP +.B +void aesCBCencrypt(uchar *p, int len, AESstate *s) +.PP +.B +void aesCBCdecrypt(uchar *p, int len, AESstate *s) +.PP +.B +void aesCTRencrypt(uchar *p, int len, AESstate *s) +.PP +.B +void aesCTRdecrypt(uchar *p, int len, AESstate *s) +.PP +.B +void setupAESXCBCstate(AESstate *s) +.PP +.B +void aesXCBCmac(uchar *p, int len, AESstate *s) +.SH DESCRIPTION +AES (a.k.a. Rijndael) has replaced DES as the preferred +block cipher. +.I Aes_encrypt +and +.I aes_decrypt +are the block ciphers, corresponding to +.IR des (2)'s +.IR block_cipher . +.IR SetupAESstate , +.IR aesCBCencrypt , +and +.I aesCBCdecrypt +implement cipher-block-chaining encryption. +.I AesCTRencrypt +and +.I aesCTRdecrypt +implement counter mode, per RFC 3686; +they are identical operations. +.I setupAESXCBCstate +and +.I aesXCBCmac +implement AES XCBC message authentication, per RFC 3566. +All ciphering is performed in place. +.I Keybytes +should be 16, 24, or 32. +The initialization vector +.I ivec +of +.I AESbsize +bytes should be 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 +.I aescbc +in +.IR secstore (1), +.IR mp (2), +.IR blowfish (2), +.IR des (2), +.IR dsa (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) +.br +.B http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf +.SH BUGS +The functions +.IR aes_encrypt , +.IR aes_decrypt , +.IR aesCTRencrypt , +.IR aesCTRdecrypt , +.IR setupAESXCBCstate , +and +.IR aesXCBCmac +have not yet been verified by running test vectors through them. diff --git a/sys/man/2/allocimage b/sys/man/2/allocimage new file mode 100755 index 000000000..2a584c143 --- /dev/null +++ b/sys/man/2/allocimage @@ -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 , +but for +.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 an image from data contained in 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/sys/man/2/arg b/sys/man/2/arg new file mode 100755 index 000000000..e54394310 --- /dev/null +++ b/sys/man/2/arg @@ -0,0 +1,126 @@ +.TH ARG 2 +.SH NAME +ARGBEGIN, ARGEND, ARGC, ARGF, EARGF \- 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 +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() , +as in +.BR EARGF(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 +.SH SEE ALSO +.IR getflags (8) diff --git a/sys/man/2/arith3 b/sys/man/2/arith3 new file mode 100755 index 000000000..d2c4acb08 --- /dev/null +++ b/sys/man/2/arith3 @@ -0,0 +1,268 @@ +.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 +.B +#include +.br +.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/sys/man/2/assert b/sys/man/2/assert new file mode 100755 index 000000000..56e092f86 --- /dev/null +++ b/sys/man/2/assert @@ -0,0 +1,25 @@ +.TH ASSERT 2 +.SH NAME +assert \- check program invariants +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +#define assert(cond) if(cond);else _assert("cond") +.PP +.B +void _assert(char* 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/sys/man/2/atof b/sys/man/2/atof new file mode 100755 index 000000000..cf7a88fde --- /dev/null +++ b/sys/man/2/atof @@ -0,0 +1,144 @@ +.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 +uvlong 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. +.SH BUGS +.I Atoi, +.I atol, +and +.I atoll +accept octal and hexadecimal numbers in the style of C, +contrary to the ANSI specification. diff --git a/sys/man/2/auth b/sys/man/2/auth new file mode 100755 index 000000000..f2aee745d --- /dev/null +++ b/sys/man/2/auth @@ -0,0 +1,394 @@ +.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/namespace ). +It uses +.I auth_userpasswd +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). +.IP +.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 +.PP +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: +.IP +.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 +.PP +.I Auth_challenge +requires a key template generated by an +.B sprint +of +.I fmt +and the variable arguments. It must contain the protocol +(\fLproto=\fIxxx\fR) +and depending on the protocol, the user name (\c +.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: +.IP +.ne 8 +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +typedef struct UserPasswd { + char *user; + char *passwd; +} UserPasswd; +.EE +.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 +.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/sys/man/2/authsrv b/sys/man/2/authsrv new file mode 100755 index 000000000..9eec0a426 --- /dev/null +++ b/sys/man/2/authsrv @@ -0,0 +1,238 @@ +.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 +.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. +If it finds neither, it tries +.BI p9auth. ad +in DNS as the authentication server. +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: +.PP +.EX +.ta 4n +4n +8n +4n +4n +4n +4n +struct Nvrsafe +{ + char machkey[DESKEYLEN]; /* was file server's authid's des key */ + uchar machsum; + char authkey[DESKEYLEN]; /* authid's des key from password */ + uchar authsum; + /* + * file server config string of device holding full configuration; + * secstore key on non-file-servers. + */ + char config[CONFIGLEN]; + uchar configsum; + char authid[ANAMELEN]; /* auth userid, e.g., bootes */ + uchar authidsum; + char authdom[DOMLEN]; /* auth domain, e.g., cs.bell-labs.com */ + uchar authdomsum; +}; +.EE +.PP +On Sparc, MIPS, and SGI machines this information is +in non-volatile ram, accessible in the file +.BR #r/nvram . +On x86s and Alphas +.I readnvram +successively opens the following areas stopping with the +first to succeed: +.PP +\- the partition named by the +.B $nvram +environment variable +(commonly set via +.IR plan9.ini (8)) +.br +\- the partition +.B #S/sdC0/nvram +.br +\- a file called +.B plan9.nvr +in the partition +.B #S/sdC0/9fat +.br +\- the partition +.B #S/sd00/nvram +.br +\- a file called +.B plan9.nvr +in the partition +.B #S/sd00/9fat +.br +\- a file called +.B plan9.nvr +on a DOS floppy in drive 0 +.br +\- a file called +.B plan9.nvr +on a DOS floppy in drive 1 +.PP +The +.IR nvcsum s +of the fields +.BR machkey , +.BR authid , +and +.B authdom +must match their respective checksum or that field is zeroed. +If +.I flag +is +.B NVwrite +or at least one checksum fails and +.I flag +is +.BR NVwriteonerr , +.I readnvram +will prompt for new values on +.B #c/cons +and then write them back to the storage area. +If +.I flag +is +.BR NVwritemem , +.I readnvram +will write the values in +.I *nv +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/sys/man/2/avl b/sys/man/2/avl new file mode 100755 index 000000000..681f1dcc3 --- /dev/null +++ b/sys/man/2/avl @@ -0,0 +1,147 @@ +.TH AVL 2 +.SH NAME +mkavltree, insertavl, lookupavl, deleteavl, avlwalk, avlnext, avlprev, endwalk - AVL tree routines +.SH SYNOPSIS +.\" .ta 0.75i 1.5i 2.25i 3i 3.75i 4.5i +.ta 0.7i +0.7i +0.7i +0.7i +0.7i +0.7i +0.7i +.EX +#include +#include +#include +.sp 0.3v +typedef struct Avl Avl; +struct Avl +{ + Avl *p; /* parent */ + Avl *n[2]; /* children */ + int bal; /* balance bits */ +}; +.sp 0.3v +Avl *avlnext(Avlwalk *walk); +Avl *avlprev(Avlwalk *walk); +Avlwalk *avlwalk(Avltree *tree); +void deleteavl(Avltree *tree, Avl *key, Avl **oldp); +void endwalk(Avlwalk *walk); +void insertavl(Avltree *tree, Avl *new, Avl **oldp); +Avl *lookupavl(Avltree *tree, Avl *key); +Avl *searchavl(Avltree *tree, Avl *key, int neighbor); +Avltree *mkavltree(int(*cmp)(Avl*, Avl*)); +.EE +.SH DESCRIPTION +An AVL tree is a self-balancing binary search tree. +These routines allow creation and maintenance of in-memory AVL trees. +.PP +An empty AVL tree is created by calling +.I mkavltree +with a comparison function as argument. +This function should take two pointers to +.B Avl +objects and return -1, 0 or 1 as the first is +respectively less than, +equal to, or greater than, +the second. +.I Insertavl +adds a +.I new +tree node into +.IR tree . +If +.I oldp +is non-nil upon return, +it points to storage for an old node +with the same key that may now be freed. +.I Lookupavl +returns the +.I tree +node that matches +.I key +by +.IR tree 's +comparison function, +or +.B nil +if none. +.PP +.I Searchavl +returns the +.I tree +node that matches +.I key +by +.IR tree 's +comparison function, if it exists. +If it does not, and +.I neighbor +is positive, it returns the nearest node whose +.I key +is greater or +.B nil +if there is none and, if +.I neighbor +is negative, it returns the nearest node whose +.I key +is less or +.B nil +if there is none. +It is an error to set +.I neighbor +to values other than \-1, 0, or +1. +.PP +.I Deleteavl +removes the node matching +.I key +from +.IR tree ; +.I oldp +is handled as per +.IR insertavl . +.PP +.I Avlwalk +returns a pointer to a newly-allocated +.B Avlwalk +object. +.I Endwalk +frees such an object. +.I Avlnext +and +.I avlprev +walk the tree associated with +.IR walk , +returning the next +(respectively, previous) +tree node in the comparison order +defined by the comparison function +associated with the tree associated with +.IR walk . +.SH EXAMPLES +Intended usage seems to be to make an anonymous +.B Avl +the first member of the application's tree-node structure, +then pass these routines tree-node pointers instead of +.BR Avl* s. +.IP +.EX +typedef struct Node { + Avl; + uchar score[VtScoreSize]; + int type; +} Node; +.sp 0.3v +Avltree *tree; +Avl *res; +Node *np; +\fI\&...\fP + res = lookupavl(tree, np); +.EE +.SH SOURCE +.B /sys/src/libavl +.SH SEE ALSO +G. M. Adelson-Velsky, +E. M. Landis, +``An algorithm for the organization of information'', +.IR "Soviet Mathematics" , +Vol. 3, pp. 1256—1263. +.SH DIAGNOSTICS +Functions returning pointers return +.B nil +on error. diff --git a/sys/man/2/bin b/sys/man/2/bin new file mode 100755 index 000000000..f711b21da --- /dev/null +++ b/sys/man/2/bin @@ -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/sys/man/2/bind b/sys/man/2/bind new file mode 100755 index 000000000..98feb41f7 --- /dev/null +++ b/sys/man/2/bind @@ -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/sys/man/2/bio b/sys/man/2/bio new file mode 100755 index 000000000..4d8189ebf --- /dev/null +++ b/sys/man/2/bio @@ -0,0 +1,361 @@ +.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 +and returns +.IR Bflush 's +return value. +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, thus the returned string probably won't be NUL-terminated. +.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, +.I Bprint +returns the number of bytes written. +.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 +Only the low byte of +.IR Brdstr 's +.I delim +is examined, so +.I delim +cannot be an arbitrary rune. +.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/sys/man/2/blowfish b/sys/man/2/blowfish new file mode 100755 index 000000000..578efc6fc --- /dev/null +++ b/sys/man/2/blowfish @@ -0,0 +1,52 @@ +.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 dsa (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/sys/man/2/brk b/sys/man/2/brk new file mode 100755 index 000000000..f916a6877 --- /dev/null +++ b/sys/man/2/brk @@ -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/sys/man/2/cachechars b/sys/man/2/cachechars new file mode 100755 index 000000000..3a0d2d2da --- /dev/null +++ b/sys/man/2/cachechars @@ -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/sys/man/2/chdir b/sys/man/2/chdir new file mode 100755 index 000000000..24e1626b7 --- /dev/null +++ b/sys/man/2/chdir @@ -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/sys/man/2/cleanname b/sys/man/2/cleanname new file mode 100755 index 000000000..cd760e427 --- /dev/null +++ b/sys/man/2/cleanname @@ -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/sys/man/2/color b/sys/man/2/color new file mode 100755 index 000000000..27569cb91 --- /dev/null +++ b/sys/man/2/color @@ -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/sys/man/2/complete b/sys/man/2/complete new file mode 100755 index 000000000..56e119b57 --- /dev/null +++ b/sys/man/2/complete @@ -0,0 +1,105 @@ +.TH COMPLETE 2 +.SH NAME +complete \- file name completion +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ft L +.nf +.ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u +typedef struct Completion Completion; +struct Completion{ + uchar advance; /* whether forward progress has been made */ + uchar complete; /* whether the completion now represents a file or directory */ + char *string; /* the string to advance, suffixed " " or "/" for file or directory */ + int nmatch; /* number of files that matched */ + int nfile; /* number of files returned */ + char **filename; /* their names */ +}; + +.fi +.PP +.B +.ta \w'\fLchar* 'u + +.PP +.B +Completion* complete(char *dir, char *s); +.PP +.B +void freecompletion(Completion *c); +.SH DESCRIPTION +The +.I complete +function implements file name completion. +Given a directory +.I dir +and a string +.IR s , +it returns an analysis of the file names in that directory that begin with the string +.IR s . +The fields +.B nmatch +and +.B nfile +will be set to the number of files that match the prefix and +.B filename +will be filled in with their names. +If the file named is a directory, a slash character will be appended to it. +.PP +If no files match the string, +.B nmatch +will be zero, but +.I complete +will return the full set of files in the directory, with +.I nfile +set to their number. +.PP +The flag +.B advance +reports whether the string +.I s +can be extended without changing the set of files that match. If true, +.B string +will be set to the extension; that is, the value of +.B string +may be appended to +.I s +by the caller to extend the embryonic file name unambiguously. +.PP +The flag +.B complete +reports whether the extended file name uniquely identifies a file. +If true, +.B string +will be suffixed with a blank, or a slash and a blank, +depending on whether the resulting file name identifies a plain file or a directory. +.PP +The +.I freecompletion +function frees a +.B Completion +structure and its contents. +.PP +In +.IR rio (1) +and +.IR acme (1), +file name completion is triggered by a control-F character or an Insert character. +.SH SOURCE +.B /sys/src/libcomplete +.SH SEE ALSO +.IR rio (1), +.IR acme (1) +.SH DIAGNOSTICS +The +.I complete +function returns a null pointer and sets +.I errstr +if the directory is unreadable or there is some other error. +.SH BUGS +The behavior of file name completion should be controlled by the plumber. diff --git a/sys/man/2/control b/sys/man/2/control new file mode 100755 index 000000000..26de90f94 --- /dev/null +++ b/sys/man/2/control @@ -0,0 +1,1948 @@ +.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.3 +typedef struct Control Control; +typedef struct Controlset Controlset; +.sp 0.3 +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.3 +struct Controlset +{ + \&... + Channel *ctl; + Channel *data; + \&... + int clicktotype; + \&... +}; +.sp 0.3 +void initcontrols(void) +.sp 0.3 +Controlset* newcontrolset(Image *i, Channel *kc, Channel *mc, Channel *rc) +.sp 0.3 +void closecontrolset(Controlset *cs) +.sp 0.3 +int namectlfont(Font *font, char *name) +.sp 0.3 +int freectlfont(char *name) +.sp 0.3 +int namectlimage(Image *image, char *name) +.sp 0.3 +int freectlimage(char *name) +.sp 0.3 +Control* createbox(Controlset *cs, char *name) +.sp 0.3 +Control* createboxbox(Controlset *cs, char *name) +.sp 0.3 +Control* createbutton(Controlset *cs, char *name) +.sp 0.3 +Control* createcolumn(Controlset*, char*) +.sp 0.3 +Control* createentry(Controlset *cs, char *name) +.sp 0.3 +Control* createkeyboard(Controlset *cs, char *name) +.sp 0.3 +Control* createlabel(Controlset *cs, char *name) +.sp 0.3 +Control* createmenu(Controlset *cs, char *name) +.sp 0.3 +Control* createradiobutton(Controlset *cs, char *name) +.sp 0.3 +Control* createrow(Controlset*, char*) +.sp 0.3 +Control* createscribble(Controlset *cs, char *name) +.sp 0.3 +Control* createslider(Controlset *cs, char *name) +.sp 0.3 +Control* createstack(Controlset*, char*) +.sp 0.3 +Control* createtab(Controlset*, char *) +.sp 0.3 +Control* createtext(Controlset *cs, char *name) +.sp 0.3 +Control* createtextbutton(Controlset *cs, char *name) +.sp 0.3 +void closecontrol(Control *c) +.sp 0.3 +int ctlprint(Control*, char*, ...); +.sp 0.3 +void ctlerror(char *fmt, ...) +.sp 0.3 +Control* controlcalled(char *name) +.sp 0.3 +void controlwire(Control *c, char *cname, Channel *ch) +.sp 0.3 +void activate(Control *c) +.sp 0.3 +void deactivate(Control *c) +.sp 0.3 +void resizecontrolset(Controlset *cs) +.sp 0.3 +void* ctlmalloc(uint n) +.sp 0.3 +void* ctlrealloc(void *p, uint n) +.sp 0.3 +char* ctlstrdup(char *s) +.sp 0.3 +int ctldeletequits; +.EE +.SH DESCRIPTION +This library provides a set of interactive +controls for graphical displays: buttons, sliders, text entry boxes, and so on. +It also provides aggregator +.BR Control s: +boxes, columns, rows and stacks of +.BR Control s. +A stack is a collection of co-located +.BR Control s, +of which one is normally visible. +A +.B Controlset +collects a group of +.BR Control s +that share mouse and keyboard. Each +.B Controlset +has a separate thread of control that processes keyboard and mouse events as +well as commands to be passed on to the +.BR Control s. +Since each +.B Controlset +uses a thread, programs using the control library must +be linked with the thread library, +.IR thread (2). +.PP +.BR Control s +are manipulated by reading and writing to the control channel, +.BR ctl , +of their +.BR Controlset . +.BR Channel s +are defined in +.IR thread (2). +Each +.B 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 +.BR Control s +then use these sizes to lay out their constituent +.BR Control s +when called upon +to do so. See the description of these grouping +.BR Control s +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 +.B 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 +.BR 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 +.BR 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 +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 +.BR Control 's +.IR "format string" . +For example, when the user types a newline at a text entry +.B 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 +.BR Controlset 's +.I ctl +channel. +One special command is recognized by the +.B Controlset +itself: Sending +the string +.B sync +to the +.I ctl +channel causes tha string to be echoed to the +.BR 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 +.BR 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 +.B 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: +.TF \fLreveal +.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 +.BR Control s. +.TP +.B hide +Disable drawing of the control and ignore mouse and keyboard events +until the control is once again revealed. +Grouping +.BR Control s +(\f2column\fP, \f2row\fP, and \f2stack\fP) pass the +request down to their constituent +.BR Control s. +.TP +.B reveal +This is the opposite of +.BR hide : +the +.B Control +is displayed and mouse and keyboard operations resume. +Grouping +.BR Control s +(\f2column\fP, \f2row\fP, and \f2stack\fP) pass the +request down to their constituent +.BR Control s. +The +.B reveal +command for +.I stacks +takes an optional argument naming the +.B Control +to be revealed; all +other +.BR Control s +will be hidden. +.TP +.B show +Display the +.B Control +on its screen if not hidden. +Some actions will also cause the +.BR Control s +to show themselves automatically +(but never when the +.B control +is hidden). +Grouping +.BR Control s +(\f2column\fP, \f2row\fP, and \f2stack\fP) pass the +request down to their constituent +.BR Control s. +.PD +.PP +Many messages are common between multiple +.BR Control s. +Such messages are described in detail here to avoid repetition. +In the individual descriptions, only the syntax is presented. +.TF "\fLformat fmt" +.TP +.BI align " n +Specify the alignment of (some part of) the +.BR Control 's +display within its rectangle. +For textual +.BR control s, +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 +.BR Control s, +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 +.B Control +(or separate constituent +.BR Control s +in +.IR boxbox , +.I column +and +.I row +.BR Control s +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 +.B Control +now has (if +.I n +is non-zero) or does not have ( if +.I n +is zero) focus. +Most +.BR Control s +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 +.BR Control s, +.B \&"%q: value %d" +for integer-valued +.B Control s +such as buttons, +and +.B \&"%q: value 0x%x" +for the keyboard and scribble +.BR Control s. +The +.B %q +prints the name of the +.BR Control ; +the rest the value. +Any supplied format string must be type-equivalent to the default for that +.BR 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 +.B 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 +.BR 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: +.TF "\fLalign a" +.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 +.PD +.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 +.BR Control s +to be displayed. This aggregator works well for collections +of buttons, labels, or textbuttons that all have a fixed height. +.TF "\fLadd name ..." +.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 +.BR 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 +.PD +.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: +.TF "\fLborder b" +.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). +.PD +.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. +.TF "\fLadd name .." +.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 +.BR 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. +.PD +.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: +.TF "\fLborder b" +.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. +.PD +.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: +.TF "\fLfont" +.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 +.PD +.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: +.TF "\fLvalue s" +.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. +.PD +.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: +.TF "\fLwindow n" +.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 +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. +.PD +.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: +.TF "\fLadd name" +.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 +.PD +.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. +.PP +The control messages it accepts are: +.TF "\fLfont" +.TP +.BI add " name ... +.TP +.BI border " width +.TP +.BI bordercolor " color +.TP +.BI hide +.TP +.BR 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 ] +.PD +.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: +.TF "\fLlinecolor \fIname\f(CW " +.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 +.PD +.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. +.PP +The control messages it accepts are: +.TF "\fLreveal [\f2n\fP]" +.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. +.PD +.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: +.TF "\fLabsolute n" +.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. +.PD +.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 +.TF "\fLformat fmt" +.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. +.PD +.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 +The control messages the text control accepts are: +.TF "\fLselectmode \fIs\fP " +.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 +.BI 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 . +.PD +.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 +.LP +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: +.TF "\fLalign a" +.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 +.sp 0.4v +Controlset *cs; +.sp 0.4v +int ctldeletequits = 1; +.sp 0.4v +void +resizecontrolset(Controlset*) +{ + int i; + Rectangle r, r1, r2; +.sp 0.4v + 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\entop show", r1); + chanprint(cs->ctl, "bot rect %R\enbot show", r2); +} +.sp 0.4v +void +threadmain(int argc, char *argv[]) +{ + char *s, *args[3]; + Channel *c; + Control *top, *bot; + int n; +.sp 0.4v + initdraw(0, 0, "example"); + initcontrols(); + cs = newcontrolset(screen, nil, nil, nil); + cs->clicktotype = 1; +.sp 0.4v + 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"); +.sp 0.4v + c = chancreate(sizeof(char*), 0); + controlwire(top, "event", c); + controlwire(bot, "event", c); +.sp 0.4v + activate(top); + activate(bot); + resizecontrolset(cs); +.sp 0.4v + 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"); +.sp 0.4v + controlwire(top, "event", cs->ctl); + controlwire(bot, "event", cs->ctl); +.sp 0.4v + activate(top); + activate(bot); + resizecontrolset(cs); +.sp 0.4v + 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/sys/man/2/cputime b/sys/man/2/cputime new file mode 100755 index 000000000..8b122bb72 --- /dev/null +++ b/sys/man/2/cputime @@ -0,0 +1,60 @@ +.TH CPUTIME 2 +.SH NAME +cputime, times, cycles \- 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) +.PP +.B +void cycles(vlong *cyclep) +.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. +.PP +.I Cycles +reads the processor's timestamp counter of cycles since reset, +if any, and stores it via +.IR cyclep . +Currently supported architectures are +.BR 386 , +.BR amd64 , +and +.BR power ; +on all others, +.I cycles +will store zero. +.SH SOURCE +.B /sys/src/libc/9sys +.br +.B /sys/src/libc/*/cycles.[cs] +.SH SEE ALSO +.IR exec (2), +.IR cons (3) +.SH BUGS +Only +.B 386 +processors starting with the Pentium have timestamp counters; +calling +.I cycles +on earlier processors may execute an illegal instruction. diff --git a/sys/man/2/ctime b/sys/man/2/ctime new file mode 100755 index 000000000..a4e074343 --- /dev/null +++ b/sys/man/2/ctime @@ -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/sys/man/2/ctype b/sys/man/2/ctype new file mode 100755 index 000000000..5a8bc864d --- /dev/null +++ b/sys/man/2/ctype @@ -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 +.if t .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) +.if t .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/sys/man/2/debugger b/sys/man/2/debugger new file mode 100755 index 000000000..5a2ec634f --- /dev/null +++ b/sys/man/2/debugger @@ -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/sys/man/2/des b/sys/man/2/des new file mode 100755 index 000000000..be25d399b --- /dev/null +++ b/sys/man/2/des @@ -0,0 +1,149 @@ +.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, int decrypting) +.PP +.B +void setupDESstate(DESstate *s, uchar key[8], uchar *ivec) +.PP +.B +void desCBCencrypt(uchar *p, int len, DESstate *s) +.PP +.B +void desCBCdecrypt(uchar *p, int len, DESstate *s) +.PP +.B +void desECBencrypt(uchar *p, int len, DESstate *s) +.PP +.B +void desECBdecrypt(uchar *p, int len, DESstate *s) +.PP +.in +0.5i +.ti -0.5i +.B +void triple_block_cipher(ulong expanded_key[3][32], uchar text[8], int ende) +.PP +.B +void setupDES3state(DES3state *s, uchar key[3][8], uchar *ivec) +.PP +.B +void des3CBCencrypt(uchar *p, int len, DES3state *s) +.PP +.B +void des3CBCdecrypt(uchar *p, int len, DES3state *s) +.PP +.B +void des3ECBencrypt(uchar *p, int len, DES3state *s) +.PP +.B +void des3ECBdecrypt(uchar *p, int len, DES3state *s) +.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 +The Digital Encryption Standard (DES) +is a shared-key or symmetric encryption algorithm 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 (DES3-EDE) 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 +.IR 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 . +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR dsa (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) +.br +.IR "Breaking DES" , +Electronic Frontier Foundation, +O'Reilly, 1998 +.SH BUGS +Single DES can be realistically broken by brute-force; +its 56-bit key is just too short. +It should not be used in new code, which should probably use +.IR aes (2) +instead, or at least triple DES. diff --git a/sys/man/2/dial b/sys/man/2/dial new file mode 100755 index 000000000..0d76065f8 --- /dev/null +++ b/sys/man/2/dial @@ -0,0 +1,333 @@ +.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 parallel all addresses on +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 */ + char *laddr; /* local address */ + char *raddr; /* remote address */ + }; +.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/sys/man/2/dirread b/sys/man/2/dirread new file mode 100755 index 000000000..6a3ad34c5 --- /dev/null +++ b/sys/man/2/dirread @@ -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/sys/man/2/disk b/sys/man/2/disk new file mode 100755 index 000000000..726131391 --- /dev/null +++ b/sys/man/2/disk @@ -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/sys/man/2/draw b/sys/man/2/draw new file mode 100755 index 000000000..2cda38ec4 --- /dev/null +++ b/sys/man/2/draw @@ -0,0 +1,821 @@ +.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 +.de PB +.PP +.ft L +.nf +.. +.SH SYNOPSIS +.de PB +.PP +.ft L +.nf +.. +.PB +#include +#include +#include +.PB +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; +.PB +typedef enum +{ + /* Porter-Duff compositing operators */ + Clear = 0, +.sp 0.1 + SinD = 8, + DinS = 4, + SoutD = 2, + DoutS = 1, +.sp 0.1 + S = SinD|SoutD, + SoverD = SinD|SoutD|DoutS, + SatopD = SinD|DoutS, + SxorD = SoutD|DoutS, +.sp 0.1 + D = DinS|DoutS, + DoverS = DinS|DoutS|SoutD, + DatopS = DinS|SoutD, + DxorS = DoutS|SoutD, /* == SxorD */ +.sp 0.1 + Ncomp = 12, +} Drawop; +.PB +.PD 0 +.ta +\w'\fL 'u +\w'\fL 'u +6n +4n +void draw(Image *dst, Rectangle r, Image *src, + Image *mask, Point p) +.PB +void drawop(Image *dst, Rectangle r, Image *src, + Image *mask, Point p, Drawop op) +.PB +void gendraw(Image *dst, Rectangle r, Image *src, Point sp, + Image *mask, Point mp) +.PB +void gendrawop(Image *dst, Rectangle r, Image *src, Point sp, + Image *mask, Point mp, Drawop op) +.PB +int drawreplxy(int min, int max, int x) +.PB +Point drawrepl(Rectangle r, Point p) +.PB +void replclipr(Image *i, int repl, Rectangle clipr) +.PB +void line(Image *dst, Point p0, Point p1, int end0, int end1, + int radius, Image *src, Point sp) +.PB +void lineop(Image *dst, Point p0, Point p1, int end0, int end1, + int radius, Image *src, Point sp, Drawop op) +.PB +void poly(Image *dst, Point *p, int np, int end0, int end1, + int radius, Image *src, Point sp) +.PB +void polyop(Image *dst, Point *p, int np, int end0, int end1, + int radius, Image *src, Point sp, Drawop op) +.PB +void fillpoly(Image *dst, Point *p, int np, int wind, + Image *src, Point sp) +.PB +void fillpolyop(Image *dst, Point *p, int np, int wind, + Image *src, Point sp, Drawop op) +.PB +int bezier(Image *dst, Point p0, Point p1, Point p2, Point p3, + int end0, int end1, int radius, Image *src, Point sp) +.PB +int bezierop(Image *dst, Point p0, Point p1, Point p2, Point p3, + int end0, int end1, int radius, Image *src, Point sp, + Drawop op) +.PB +int bezspline(Image *dst, Point *pt, int npt, int end0, int end1, + int radius, Image *src, Point sp) +.PB +int bezsplineop(Image *dst, Point *pt, int npt, int end0, int end1, + int radius, Image *src, Point sp, Drawop op) +.PB +int bezsplinepts(Point *pt, int npt, Point **pp) +.PB +int fillbezier(Image *dst, Point p0, Point p1, Point p2, Point p3, + int w, Image *src, Point sp) +.PB +int fillbezierop(Image *dst, Point p0, Point p1, Point p2, Point p3, + int w, Image *src, Point sp, Drawop op) +.PB +int fillbezspline(Image *dst, Point *pt, int npt, int w, + Image *src, Point sp) +.PB +int fillbezsplineop(Image *dst, Point *pt, int npt, int w, + Image *src, Point sp, Drawop op) +.PB +void ellipse(Image *dst, Point c, int a, int b, int thick, + Image *src, Point sp) +.PB +void ellipseop(Image *dst, Point c, int a, int b, int thick, + Image *src, Point sp, Drawop op) +.PB +void fillellipse(Image *dst, Point c, int a, int b, + Image *src, Point sp) +.PB +void fillellipseop(Image *dst, Point c, int a, int b, + Image *src, Point sp, Drawop op) +.PB +void arc(Image *dst, Point c, int a, int b, int thick, + Image *src, Point sp, int alpha, int phi) +.PB +void arcop(Image *dst, Point c, int a, int b, int thick, + Image *src, Point sp, int alpha, int phi, Drawop op) +.PB +void fillarc(Image *dst, Point c, int a, int b, Image *src, + Point sp, int alpha, int phi) +.PB +void fillarcop(Image *dst, Point c, int a, int b, Image *src, + Point sp, int alpha, int phi, Drawop op) +.PB +int icossin(int deg, int *cosp, int *sinp) +.PB +int icossin2(int x, int y, int *cosp, int *sinp) +.PB +void border(Image *dst, Rectangle r, int i, Image *color, Point sp) +.br +.PB +Point string(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s) +.PB +Point stringop(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, Drawop op) +.PB +Point stringn(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, int len) +.PB +Point stringnop(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, int len, Drawop op) +.PB +Point runestring(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r) +.PB +Point runestringop(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, Drawop op) +.PB +Point runestringn(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, int len) +.PB +Point runestringnop(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, int len, Drawop op) +.PB +Point stringbg(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, Image *bg, Point bgp) +.PB +Point stringbgop(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, Image *bg, Point bgp, Drawop op) +.PB +Point stringnbg(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, int len, Image *bg, Point bgp) +.PB +Point stringnbgop(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, int len, Image *bg, Point bgp, Drawop op) +.PB +Point runestringbg(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, Image *bg, Point bgp) +.PB +Point runestringbgop(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, Image *bg, Point bgp, Drawop op) +.PB +Point runestringnbg(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, int len, Image *bg, Point bgp) +.PB +Point runestringnbgop(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, int len, Image *bg, Point bgp, Drawop op) +.PB +Point _string(Image *dst, Point p, Image *src, + Point sp, Font *f, char *s, Rune *r, int len, + Rectangle clipr, Image *bg, Point bgp, Drawop op) +.PB +void drawsetdebug(int on) +.PD +.PB +enum +{ + /* line ends */ + Endsquare = 0, + Enddisc = 1, + Endarrow = 2, + Endmask = 0x1F +}; +.PB +#define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23)) +.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. ). +.PP +Most of the drawing functions come in two forms: +a basic form, and an extended form that takes an extra +.B Drawop +to specify a Porter-Duff compositing operator to use. +The basic forms assume the operator is +.BR SoverD , +which suffices for the vast majority of applications. +The extended forms are named by adding an +.RB - op +suffix to the basic form. +Only the basic forms are listed below. +.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 . +(In the extended form, +``over'' is replaced by +.IR op ). +.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 +\f5bezsplinepts(\f2pt\fP, \f2npt\fP, \f2pp\fP) +.I Bezsplinepts +returns in +.I pp +a list of points making up the open polygon that +.I bezspline +would draw. +The caller is responsible for freeing +.IR *pp . +.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/sys/man/2/dsa b/sys/man/2/dsa new file mode 100755 index 000000000..31c31f038 --- /dev/null +++ b/sys/man/2/dsa @@ -0,0 +1,139 @@ +.TH DSA 2 +.SH NAME +dsagen, dsasign, dsaverify, dsapuballoc, dsapubfree, dsaprivalloc, dsaprivfree, dsasigalloc, dsasigfree, dsaprivtopub - digital signature algorithm +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +DSApriv* dsagen(DSApub *opub) +.PP +.B +DSAsig* dsasign(DSApriv *k, mpint *m) +.PP +.B +int dsaverify(DSApub *k, DSAsig *sig, mpint *m) +.PP +.B +DSApub* dsapuballoc(void) +.PP +.B +void dsapubfree(DSApub*) +.PP +.B +DSApriv* dsaprivalloc(void) +.PP +.B +void dsaprivfree(DSApriv*) +.PP +.B +DSAsig* dsasigalloc(void) +.PP +.B +void dsasigfree(DSAsig*) +.PP +.B +DSApub* dsaprivtopub(DSApriv*) +.SH DESCRIPTION +.PP +DSA is the NIST approved digital signature algorithm. The owner of a key publishes +the public part of the key: +.IP +.EX +struct DSApub +{ + mpint *p; // modulus + mpint *q; // group order, q divides p-1 + mpint *alpha; // group generator + mpint *key; // alpha**secret mod p +}; +.EE +.LP +This part can be used for verifying signatures (with +.IR dsaverify ) +created by the owner. +The owner signs (with +.IR dsasign ) +using his private key: +.IP +.EX +struct DSApriv +{ + DSApub pub; + mpint *secret; // (decryption key) +}; +.EE +.PP +Keys are generated using +.IR dsagen . +If +.IR dsagen 's +argument +.I opub +is +.BR nil , +a key is created using a new +.B p +and +.B q +generated by +.I DSAprimes +(see +.IR prime (2)). +Otherwise, +.B p +and +.B q +are copied from the old key. +.PP +.I Dsaprivtopub +returns a newly allocated copy of the public key +corresponding to the private key. +.PP +The routines +.IR dsapuballoc , +.IR dsapubfree , +.IR dsaprivalloc , +and +.I dsaprivfree +are provided to manage key storage. +.PP +.I Dsasign +signs message +.I m +using a private key +.I k +yielding a +.IP +.EX +struct DSAsig +{ + mpint *r, *s; +}; +.EE +.LP +.I Dsaverify +returns 0 if the signature is valid and \-1 if not. +.PP +The routines +.I dsasigalloc +and +.I dsasigfree +are provided to manage signature storage. +.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/sys/man/2/dup b/sys/man/2/dup new file mode 100755 index 000000000..cd3414106 --- /dev/null +++ b/sys/man/2/dup @@ -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/sys/man/2/elgamal b/sys/man/2/elgamal new file mode 100755 index 000000000..a3d999191 --- /dev/null +++ b/sys/man/2/elgamal @@ -0,0 +1,125 @@ +.TH ELGAMAL 2 +.SH NAME +eggen, egencrypt, egdecrypt, egsign, egverify, 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 +Elgamal is a public key encryption and signature algorithm. The owner of a key publishes +the public part of the key: +.EX + struct EGpub + { + mpint *p; // modulus + mpint *alpha; // generator + mpint *key; // (encryption key) alpha**secret mod p + }; +.EE +This part can be used for encrypting data (with +.IR egencrypt ) +to be sent to the owner. +The owner decrypts (with +.IR egdecrypt ) +using his private key: +.EX + struct EGpriv + { + EGpub pub; + mpint *secret; // (decryption key) + }; +.EE +.PP +Keys are generated using +.IR eggen . +.I Eggen +takes both bit length of the modulus +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 Egprivtopub +returns a newly allocated copy of the public key +corresponding to the private key. +.PP +The routines +.IR egpuballoc , +.IR egpubfree , +.IR egprivalloc , +and +.I egprivfree +are provided to manage key storage. +.PP +.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. +.PP +The routines +.I egsigalloc +and +.I egsigfree +are provided to manage signature storage. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR dsa (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/sys/man/2/encode b/sys/man/2/encode new file mode 100755 index 000000000..9436d94de --- /dev/null +++ b/sys/man/2/encode @@ -0,0 +1,85 @@ +.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). The default encoding is +in upper case. The +.B l +flag forces lower case. +.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/sys/man/2/encrypt b/sys/man/2/encrypt new file mode 100755 index 000000000..3f7b41da9 --- /dev/null +++ b/sys/man/2/encrypt @@ -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/sys/man/2/errstr b/sys/man/2/errstr new file mode 100755 index 000000000..4e801c395 --- /dev/null +++ b/sys/man/2/errstr @@ -0,0 +1,85 @@ +.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 null terminated 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 +The per-process buffer is +.B ERRMAX +bytes long. Any error string provided by the user will +be truncated at +.B ERRMAX-1 +bytes. +.B ERRMAX +is defined in +.BR . +.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/sys/man/2/event b/sys/man/2/event new file mode 100755 index 000000000..11324a9af --- /dev/null +++ b/sys/man/2/event @@ -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/sys/man/2/exec b/sys/man/2/exec new file mode 100755 index 000000000..5c5e79669 --- /dev/null +++ b/sys/man/2/exec @@ -0,0 +1,200 @@ +.TH EXEC 2 +.SH NAME +exec, execl, _privates, _nprivates, _tos \- execute a file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +void* exec(char *name, char* argv[]) +.PP +.B +void* execl(char *name, ...) +.PP +.B +void **_privates; +.PP +.B +int _nprivates; +.PP +.B +#include +.PP +.ft L +typedef struct Tos Tos; +struct Tos { + struct { ... } prof; /* profiling data */ + uvlong cyclefreq; /* cycle clock frequency */ + vlong kcycles; /* kernel cycles */ + vlong pcycles; /* process cycles (kernel + user) */ + ulong pid; /* process id */ + ulong clock; /* profiling clock */ + /* top of stack is here */ +}; +.PP +.B +extern Tos *_tos; +.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 +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 +When the new program begins, the global pointer +.B _tos +is set to the address of a structure +that holds information +allowing accurate time keeping and clock reading in user space. +These data are updated by the kernel during of the life of the process, +including across +.IR rfork s +and +.IR exec s. +If there is a user-space accessible fast clock (a processor +cycle counter), +.B cyclefreq +will be set to its frequency in Hz. +.B Kcycles +.RB ( pcycles ) +counts the number of cycles +this process has spent in kernel mode +(kernel and user mode). +.B Pid +is the current process's id. +.B Clock +is the user-profiling clock (see +.IR prof (1)). +Its 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 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 information. +.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 to the calling process from a successful +.I exec +or +.IR execl ; +the calling image is lost. +.SH BUGS +There is a large but finite limit on the size of an argment list, +typically around 409,600 bytes. +The kernel constant +.B TSTKSIZ +controls this. diff --git a/sys/man/2/exits b/sys/man/2/exits new file mode 100755 index 000000000..78e3f6d29 --- /dev/null +++ b/sys/man/2/exits @@ -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/sys/man/2/exp b/sys/man/2/exp new file mode 100755 index 000000000..55147ed9f --- /dev/null +++ b/sys/man/2/exp @@ -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/sys/man/2/fauth b/sys/man/2/fauth new file mode 100755 index 000000000..4b666ee83 --- /dev/null +++ b/sys/man/2/fauth @@ -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/sys/man/2/fcall b/sys/man/2/fcall new file mode 100755 index 000000000..1ca3edb77 --- /dev/null +++ b/sys/man/2/fcall @@ -0,0 +1,357 @@ +.TH FCALL 2 +.SH NAME +Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeS2M, 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 sizeS2M(Fcall *f) +.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 { + ushort oldtag; /* Tflush */ + }; + struct { + char *ename; /* Rerror */ + }; + struct { + Qid qid; /* Rattach, Ropen, Rcreate */ + u32int iounit; /* Ropen, Rcreate */ + }; + struct { + Qid aqid; /* Rauth */ + }; + struct { + u32int afid; /* Tauth, Tattach */ + char *uname; /* Tauth, Tattach */ + char *aname; /* Tauth, Tattach */ + }; + 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 Tversion , +.BR Rversion , +.BR Tattach , +.BR Rattach , +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 +The routine +.I sizeS2M +returns the number of bytes required to store the machine-independent representation of the +.B Fcall +structure +.IR f , +including its initial 32-bit size field. +In other words, it reports the number of bytes produced +by a successful call to +.IR convS2M . +.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 +Analogous to +.IR sizeS2M , +.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. +.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\f1). +It returns +.B 0 +for a valid entry and +.B -1 +for an incorrectly formatted entry. +.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/sys/man/2/fd2path b/sys/man/2/fd2path new file mode 100755 index 000000000..9876c132a --- /dev/null +++ b/sys/man/2/fd2path @@ -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/sys/man/2/fgetc b/sys/man/2/fgetc new file mode 100755 index 000000000..87bc98e9c --- /dev/null +++ b/sys/man/2/fgetc @@ -0,0 +1,213 @@ +.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 +.br +.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/sys/man/2/flate b/sys/man/2/flate new file mode 100755 index 000000000..39f4c108d --- /dev/null +++ b/sys/man/2/flate @@ -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/sys/man/2/floor b/sys/man/2/floor new file mode 100755 index 000000000..9205c011d --- /dev/null +++ b/sys/man/2/floor @@ -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/sys/man/2/fmtinstall b/sys/man/2/fmtinstall new file mode 100755 index 000000000..6d10f0eb1 --- /dev/null +++ b/sys/man/2/fmtinstall @@ -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; +}; +.sp 0.3v +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, +.sp 0.3v + FmtFlag = FmtComma << 1 +}; +.fi +.PP +.B +.ta \w'\fLchar* 'u +.sp 0.3v +.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); +.sp 0.3v +.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 like +.B fprint +(see +.IR print (2)) +or +.B vfprint +except that the characters are buffered until +.I fmtfdflush +is called and the return value is either 0 or \-1. +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 one. +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. +Both functions return 0 for success and \-1 for failure. +.PP +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. +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 fatal 1 +.sp 0.3v +void +fatal(char *fmt, ...) +{ + Fmt f; + char buf[64]; + va_list arg; +.sp 0.3v + 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; +.sp 0.3v +#pragma varargck type "X" Complex +.sp 0.3v +int +Xfmt(Fmt *f) +{ + Complex c; +.sp 0.3v + c = va_arg(f->args, Complex); + return fmtprint(f, "(%g,%g)", c.r, c.i); +} +.sp 0.3v +main(...) +{ + Complex x = (Complex){ 1.5, -2.3 }; +.sp 0.3v + 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 . diff --git a/sys/man/2/fopen b/sys/man/2/fopen new file mode 100755 index 000000000..c91a8bdf9 --- /dev/null +++ b/sys/man/2/fopen @@ -0,0 +1,354 @@ +.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 +.br +.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/sys/man/2/fork b/sys/man/2/fork new file mode 100755 index 000000000..6f80e68de --- /dev/null +++ b/sys/man/2/fork @@ -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/sys/man/2/fprintf b/sys/man/2/fprintf new file mode 100755 index 000000000..b7f616c33 --- /dev/null +++ b/sys/man/2/fprintf @@ -0,0 +1,506 @@ +.TH FPRINTF 2 +.SH NAME +fprintf, printf, sprintf, snprintf, vfprintf, vprintf, vsprintf, vsnprintf \- print formatted output +.SH SYNOPSIS +.B #include +.br +.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/sys/man/2/frame b/sys/man/2/frame new file mode 100755 index 000000000..1ef43dbfe --- /dev/null +++ b/sys/man/2/frame @@ -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/sys/man/2/frexp b/sys/man/2/frexp new file mode 100755 index 000000000..59b4eabcc --- /dev/null +++ b/sys/man/2/frexp @@ -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 signed 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/sys/man/2/fscanf b/sys/man/2/fscanf new file mode 100755 index 000000000..d57c06b0f --- /dev/null +++ b/sys/man/2/fscanf @@ -0,0 +1,404 @@ +.TH FSCANF 2 +.SH NAME +fscanf, scanf, sscanf, vfscanf \- scan formatted input +.SH SYNOPSIS +.B "#include +.br +.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/sys/man/2/fversion b/sys/man/2/fversion new file mode 100755 index 000000000..711cca7ba --- /dev/null +++ b/sys/man/2/fversion @@ -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/sys/man/2/getcallerpc b/sys/man/2/getcallerpc new file mode 100755 index 000000000..b5e6a7775 --- /dev/null +++ b/sys/man/2/getcallerpc @@ -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 uintptr 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(int arg) +{ + print("Called from %p\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/sys/man/2/getenv b/sys/man/2/getenv new file mode 100755 index 000000000..339acb823 --- /dev/null +++ b/sys/man/2/getenv @@ -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/sys/man/2/getfcr b/sys/man/2/getfcr new file mode 100755 index 000000000..87e93d5a2 --- /dev/null +++ b/sys/man/2/getfcr @@ -0,0 +1,119 @@ +.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. +Where possible, the initial state is equivalent to +.IP +.EX +setfcr(FPPDBL|FPRNR|FPINVAL|FPZDIV|FPOVFL); +.EE +.PP +However, this may vary between architectures: +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 +setfcr((getfcr() & ~FPPMASK) | FPPDBL | FPOVFL); +.ft +.EE +.SH SOURCE +.B /sys/src/libc/$objtype/getfcr.s diff --git a/sys/man/2/getfields b/sys/man/2/getfields new file mode 100755 index 000000000..9a5281fda --- /dev/null +++ b/sys/man/2/getfields @@ -0,0 +1,99 @@ +.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 +places into the array +.I args +pointers to the first +.I maxargs +fields of the null terminated +.SM UTF +string +.IR str . +Delimiters between these fields are set to null. +.PP +Fields are substrings of +.I str +whose definition depends on the value of +.IR multiflag. +If +.I multiflag +is zero, +adjacent fields are separated by exactly one delimiter. +For example +.EX + + getfields("#alice#bob##charles###", arg, 3, 0, "#"); + +.EE +yields three substrings: +null-string , +.BR "alice" , +and +.BR "bob##charles###" . +If the +.I multiflag +argument is not zero, +a field is a non-empty string of non-delimiters. +For example +.EX + + getfields("#alice#bob##charles###", arg, 3, 1, "#"); + +.EE +yields the three substrings: +.BR "alice" , +.BR "bob" , +and +.BR "charles###" . +.PP +Getfields returns the number of fields pointed to. +.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). +Any such quotes remain in the resulting +.IR args . +See +.IR quote (2) +for related quote-handling software. +.PP +.I Tokenize +is similar to +.I gettokens +with +.I delims +set to \f5"\et\er\en\ "\fP, +except that quotes are interpreted but do not appear in the resulting +.IR args . +.SH SOURCE +.B /sys/src/libc/port/tokenize.c +.SH SEE ALSO +.I strtok +in +.IR strcat (2), +.IR quote (2). diff --git a/sys/man/2/getpid b/sys/man/2/getpid new file mode 100755 index 000000000..6d795746d --- /dev/null +++ b/sys/man/2/getpid @@ -0,0 +1,42 @@ +.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 exec (2), +.IR cons (3), +.IR proc (3) +.SH DIAGNOSTICS +Returns 0 and +sets +.I errstr +if unsuccessful. diff --git a/sys/man/2/getuser b/sys/man/2/getuser new file mode 100755 index 000000000..7303fe24a --- /dev/null +++ b/sys/man/2/getuser @@ -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/sys/man/2/getwd b/sys/man/2/getwd new file mode 100755 index 000000000..ac99719e0 --- /dev/null +++ b/sys/man/2/getwd @@ -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/sys/man/2/graphics b/sys/man/2/graphics new file mode 100755 index 000000000..315e59aad --- /dev/null +++ b/sys/man/2/graphics @@ -0,0 +1,642 @@ +.TH GRAPHICS 2 +.SH NAME +Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth \- interactive graphics +.SH SYNOPSIS +.nf +.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 +int newwindow(char *str) +.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 +Subfont* getdefont(Display *d) +.PP +.B +int flushimage(Display *d, int vis) +.PP +.B +uchar* bufimage(Display *d, int n) +.PP +.B +void lockdisplay(Display *d) +.PP +.B +void 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 +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 +{ + ... + 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. +.I Setcursor +and +.I moveto +(see +.IR mouse (2)) +and +.I esetcursor +and +.I emoveto +(see +.IR event (2)) +change the cursor image and its location on the screen. +.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 +The function +.I newwindow +may be called before +.I initdraw +or +.IR geninitdraw +to cause the program to occupy a newly created window rather than take over the one in +which it is running when it starts. +The +.I str +argument, if non-null, is concatenated to the string \f5\&"new\ "\fP +that is used to create the window (see +.IR rio (4)). +For example, +.B newwindow("-hide -dy 100") +will cause the program to run in a newly created, hidden window +100 pixels high. +.PP +.I Initdisplay +is part of +.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 Subfont +structure from in-core data describing a default subfont. +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 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, -1, "/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/sys/man/2/html b/sys/man/2/html new file mode 100755 index 000000000..ef641e41d --- /dev/null +++ b/sys/man/2/html @@ -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/sys/man/2/httpd b/sys/man/2/httpd new file mode 100755 index 000000000..3318f550f --- /dev/null +++ b/sys/man/2/httpd @@ -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, +hvprint, +hwrite, +hxferenc, + \- routines for creating an http server +.SH SYNOPSIS +.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 hvprint(Hio*, char*, va_list); +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/sys/man/2/hypot b/sys/man/2/hypot new file mode 100755 index 000000000..dc25ed2d6 --- /dev/null +++ b/sys/man/2/hypot @@ -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/sys/man/2/intmap b/sys/man/2/intmap new file mode 100755 index 000000000..22dec998a --- /dev/null +++ b/sys/man/2/intmap @@ -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/sys/man/2/ioproc b/sys/man/2/ioproc new file mode 100755 index 000000000..b20ba034b --- /dev/null +++ b/sys/man/2/ioproc @@ -0,0 +1,178 @@ +.TH IOPROC 2 +.SH NAME +closeioproc, +iocall, +ioclose, +iointerrupt, +iodial, +ioopen, +ioproc, +ioread, +ioreadn, +iowrite \- slave I/O processes for threaded programs +.SH SYNOPSIS +.PP +.de XX +.ift .sp 0.5 +.ifn .sp +.. +.EX +.ta \w'Ioproc* 'u +#include +#include +#include +.sp +typedef struct Ioproc Ioproc; +.sp +Ioproc* ioproc(void); +.XX +int ioopen(Ioproc *io, char *file, int omode); +int ioclose(Ioproc *io, int fd); +long ioread(Ioproc *io, int fd, void *a, long n); +long ioreadn(Ioproc *io, int fd, void *a, long n); +long iowrite(Ioproc *io, int fd, void *a, long n); +int iodial(Ioproc *io, char *addr, char *local, char *dir, char *cdfp); +.XX +void iointerrupt(Ioproc *io); +void closeioproc(Ioproc *io); +.XX +long iocall(Ioproc *io, long (*op)(va_list *arg), ...); +.EE +.SH DESCRIPTION +.PP +These routines provide access to I/O in slave procs. +Since the I/O itself is done in a slave proc, other threads +in the calling proc can run while the calling thread +waits for the I/O to complete. +.PP +.I Ioproc +forks a new slave proc and returns a pointer to the +.B Ioproc +associated with it. +.I Ioproc +uses +.I mallocz +and +.IR proccreate ; +if either fails, it calls +.I sysfatal +rather than return an error. +.PP +.IR Ioopen , +.IR ioclose , +.IR ioread , +.IR ioreadn , +.IR iowrite , +and +.IR iodial +execute the +similarly named library or system calls +(see +.IR open (2), +.IR read (2), +and +.IR dial (2)) +in the slave process associated with +.IR io . +It is an error to execute more than one call +at a time in an I/O proc. +.PP +.I Iointerrupt +interrupts the call currently executing in the I/O proc. +If no call is executing, +.IR iointerrupt +is a no-op. +.PP +.I Closeioproc +terminates the I/O proc and frees the associated +.B Ioproc . +.PP +.I Iocall +is a primitive that may be used to implement +more slave I/O routines. +.I Iocall +arranges for +.I op +to be called in +.IR io 's +proc, with +.I arg +set to the variable parameter list, +returning the value that +.I op +returns. +.SH EXAMPLE +Relay messages between two file descriptors, +counting the total number of bytes seen: +.IP +.EX +.ta +\w'xxxx'u +\w'xxxx'u +\w'xxxx'u +int tot; + +void +relaythread(void *v) +{ + int *fd, n; + char buf[1024]; + Ioproc *io; + + fd = v; + io = ioproc(); + while((n = ioread(io, fd[0], buf, sizeof buf)) > 0){ + if(iowrite(io, fd[1], buf, n) != n) + sysfatal("iowrite: %r"); + tot += n; + } + closeioproc(io); +} + +void +relay(int fd0, int fd1) +{ + int fd[4]; + + fd[0] = fd[3] = fd0; + fd[1] = fd[2] = fd1; + threadcreate(relaythread, fd, 8192); + threadcreate(relaythread, fd+2, 8192); +} +.EE +.LP +If the two +.I relaythread +instances were running in different procs, the +common access to +.I tot +would be unsafe. +.PP +Implement +.IR ioread : +.IP +.EX +static long +_ioread(va_list *arg) +{ + int fd; + void *a; + long n; + + fd = va_arg(*arg, int); + a = va_arg(*arg, void*); + n = va_arg(*arg, long); + return read(fd, a, n); +} + +long +ioread(Ioproc *io, int fd, void *a, long n) +{ + return iocall(io, _ioread, fd, a, n); +} +.EE +.SH SOURCE +.B /sys/src/libthread/io*.c +.SH SEE ALSO +.IR dial (2), +.IR open (2), +.IR read (2), +.IR thread (2) + diff --git a/sys/man/2/iounit b/sys/man/2/iounit new file mode 100755 index 000000000..a31d70792 --- /dev/null +++ b/sys/man/2/iounit @@ -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/sys/man/2/ip b/sys/man/2/ip new file mode 100755 index 000000000..e84b14c08 --- /dev/null +++ b/sys/man/2/ip @@ -0,0 +1,364 @@ +.TH IP 2 +.SH NAME +eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip4, equivip6, defmask, isv4, v4tov6, v6tov4, nhgetv, nhgetl, nhgets, hnputv, hnputl, hnputs, ptclbsum, readipifc \- Internet Protocol addressing +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +int eipfmt(Fmt*) +.PP +.B +vlong parseip(uchar *ipaddr, char *str) +.PP +.B +vlong 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 equivip4(uchar *ipaddr1, uchar *ipaddr2) +.PP +.B +int equivip6(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 +uvlong nhgetv(void *p) +.PP +.B +void hnputs(void *p, ushort v) +.PP +.B +void hnputl(void *p, uint v) +.PP +.B +void hnputv(void *p, uvlong v) +.PP +.B +ushort ptclbsum(uchar *a, int n) +.PP +.B +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 /addr +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. +.I Equivip4 +operates on v4 addresses, +.I equivip6 +operates on v6 addresses. +.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 4-byte 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 4-byte V4 address and puts the result in +.IR v4ip . +.PP +.IR Hnputs , +.I hnputl +and +.I hnputv +are used to store 16-bit, 32-bit, and 64-bit integers, respectively, into IP big-endian form. +.IR Nhgets , +.I nhgetl +and +.I nhgetv +convert big-endian 2, 4 and 8 byte quantities into integers (or +.IR uvlong s). +.PP +.I Pctlbsum +returns the one's complement checksum used in IP protocols, typically invoked as +.IP +.EX +hnputs(hdr->cksum, ~ptclbsum(data, len) & 0xffff); +.EE +.PP +A number of standard IP addresses in V6 format are also defined. They are: +.TF IPv4allrouter +.TP +.B IPv4bcast +the V4 broadcast address +.TP +.B IPv4allsys +the V4 all systems multicast address +.TP +.B IPv4allrouter +the V4 all routers multicast address +.TP +.B IPallbits +the V6 all bits on address +.TP +.B IPnoaddr +the V6 null address, all zeros +.TP +.B v4prefix +the IP V6 prefix to all embedded V4 addresses +.PD +.PP +.I Readipifc +returns information about +a particular interface +.RI ( index +>= 0) +or all IP interfaces +.RI ( index +< 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 */ + + 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: +.PP +.EX +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; +}; +.EE +.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), +.IR ip (3) diff --git a/sys/man/2/isalpharune b/sys/man/2/isalpharune new file mode 100755 index 000000000..1c28369a2 --- /dev/null +++ b/sys/man/2/isalpharune @@ -0,0 +1,54 @@ +.TH ISALPHARUNE 2 +.SH NAME +isalpharune, islowerrune, isspacerune, istitlerune, isupperrune, isdigitrune, 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 +int isdigitrune(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/sys/man/2/keyboard b/sys/man/2/keyboard new file mode 100755 index 000000000..d0463f789 --- /dev/null +++ b/sys/man/2/keyboard @@ -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/sys/man/2/lock b/sys/man/2/lock new file mode 100755 index 000000000..76d15b1fe --- /dev/null +++ b/sys/man/2/lock @@ -0,0 +1,313 @@ +.TH LOCK 2 +.SH NAME +lock, canlock, unlock, +qlock, canqlock, qunlock, +rlock, canrlock, runlock, +wlock, canwlock, wunlock, +rsleep, rwakeup, rwakeupall, +incref, decref +\- spin locks, queueing rendezvous locks, reader-writer locks, rendezvous points, and reference counts +.SH SYNOPSIS +.ft L +.nf +#include +#include +.PP +.ft L +.nf +void lock(Lock *l) +int canlock(Lock *l) +void unlock(Lock *l) +.PP +.ft L +.nf +void qlock(QLock *l) +int canqlock(QLock *l) +void qunlock(QLock *l) +.PP +.ft L +.nf +void rlock(RWLock *l) +int canrlock(RWLock *l) +void runlock(RWLock *l) +.PP +.ft L +.nf +void wlock(RWLock *l) +int canwlock(RWLock *l) +void wunlock(RWLock *l) +.PP +.ft L +.nf +typedef struct Rendez { + QLock *l; + \fI...\fP +} Rendez; +.PP +.ft L +.nf +void rsleep(Rendez *r) +int rwakeup(Rendez *r) +int rwakeupall(Rendez *r) +.PP +.ft L +#include +.PP +.ft L +.nf +typedef struct Ref { + long ref; +} Ref; +.PP +.ft L +.nf +void incref(Ref*) +long decref(Ref*) +.fi +.SH DESCRIPTION +These routines are used to synchronize processes sharing memory. +.PP +.B Locks +are spin locks, +.B QLocks +and +.B RWLocks +are different types of queueing rendezvous locks, +and +.B Rendezes +are rendezvous points. +.PP +Locks and rendezvous points work in regular programs as +well as programs that use the thread library +(see +.IR thread (2)). +The thread library replaces the +.IR rendezvous (2) +system call +with its own implementation, +.IR 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 +.B Rendezes +are rendezvous points. Each +.B Rendez +.I r +is protected by a +.B QLock +.IB r -> l \fR, +which must be held by the callers of +.IR rsleep , +.IR rwakeup , +and +.IR rwakeupall . +.I Rsleep +atomically releases +.IB r -> l +and suspends execution of the calling task. +After resuming execution, +.I rsleep +will reacquire +.IB r -> l +before returning. +If any processes are sleeping on +.IR r , +.I rwakeup +wakes one of them. +it returns 1 if a process was awakened, 0 if not. +.I Rwakeupall +wakes all processes sleeping on +.IR r , +returning the number of processes awakened. +.I Rwakeup +and +.I rwakeupall +do not release +.IB r -> l +and do not suspend execution of the current task. +.PP +Before use, +.B Rendezes +should be initialized to all zeros except for +.IB r -> l +pointer, which should point at the +.B QLock +that will guard +.IR r . +It is important that this +.B QLock +is the same one that protects the rendezvous condition; see the example. +.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 EXAMPLE +Implement a buffered single-element channel using +.I rsleep +and +.IR rwakeup : +.IP +.EX +.ta +4n +4n +4n +typedef struct Chan +{ + QLock l; + Rendez full, empty; + int val, haveval; +} Chan; +.EE +.IP +.EX +.ta +4n +4n +4n +Chan* +mkchan(void) +{ + Chan *c; + + c = mallocz(sizeof *c, 1); + c->full.l = &c->l; + c->empty.l = &c->l; + return c; +} +.EE +.IP +.EX +.ta +4n +4n +4n +void +send(Chan *c, int val) +{ + qlock(&c->l); + while(c->haveval) + rsleep(&c->full); + c->haveval = 1; + c->val = val; + rwakeup(&c->empty); /* no longer empty */ + qunlock(&c->l); +} +.EE +.IP +.EX +.ta +4n +4n +4n +int +recv(Chan *c) +{ + int v; + + qlock(&c->l); + while(!c->haveval) + rsleep(&c->empty); + c->haveval = 0; + v = c->val; + rwakeup(&c->full); /* no longer full */ + qunlock(&c->l); + return v; +} +.EE +.LP +Note that the +.B QLock +protecting the +.B Chan +is the same +.B QLock +used for the +.BR Rendez ; +this ensures that wakeups are not missed. +.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) +.SH BUGS +.B Locks +are not strictly spin locks. +After each unsuccessful attempt, +.I lock +calls +.B sleep(0) +to yield the CPU; this handles the common case +where some other process holds the lock. +After a thousand unsuccessful attempts, +.I lock +sleeps for 100ms between attempts. +After another thousand unsuccessful attempts, +.I lock +sleeps for a full second between attempts. +.B Locks +are not intended to be held for long periods of time. +The 100ms and full second sleeps are only heuristics to +avoid tying up the CPU when a process deadlocks. +As discussed above, +if a lock is to be held for much more than a few instructions, +the queueing lock types should be almost always be used. +.PP +It is an error for a program to +.I fork +when it holds a lock in shared memory, since this will result +in two processes holding the same lock at the same time, +which should not happen. diff --git a/sys/man/2/mach b/sys/man/2/mach new file mode 100755 index 000000000..a41170dad --- /dev/null +++ b/sys/man/2/mach @@ -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 +Map *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/sys/man/2/malloc b/sys/man/2/malloc new file mode 100755 index 000000000..4ae226591 --- /dev/null +++ b/sys/man/2/malloc @@ -0,0 +1,230 @@ +.TH MALLOC 2 +.SH NAME +malloc, mallocalign, 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* mallocalign(ulong size, ulong align, long offset, ulong span) +.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) +.PP +.B +void setrealloctag(void *ptr, ulong tag) +.PP +.B +ulong getrealloctag(void *ptr) +.PP +.B +void* malloctopoolblock(void*) +.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. +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 Mallocalign +allocates a block of at least +.I n +bytes of memory respecting alignment contraints. +If +.I align +is non-zero, +the returned pointer is aligned to be equal to +.I offset +modulo +.IR align . +If +.I span +is non-zero, +the +.I n +byte block allocated will not span a +.IR span -byte +boundary. +.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. +.I Realloc +takes on special meanings when one or both arguments are zero: +.TP +.B "realloc(0,\ size) +means +.LR malloc(size) ; +returns a pointer to the newly-allocated memory +.TP +.B "realloc(ptr,\ 0) +means +.LR free(ptr) ; +returns null +.TP +.B "realloc(0,\ 0) +no-op; returns null +.PD +.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/sys/man/2/matrix b/sys/man/2/matrix new file mode 100755 index 000000000..6291aa6de --- /dev/null +++ b/sys/man/2/matrix @@ -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/sys/man/2/memdraw b/sys/man/2/memdraw new file mode 100755 index 000000000..ac1b73961 --- /dev/null +++ b/sys/man/2/memdraw @@ -0,0 +1,448 @@ +.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 +.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, Drawop op) +void mempoly(Memimage *dst, Point *p, int np, int end0, + int end1, int radius, Memimage *src, Point sp, Drawop op) +void memellipse(Memimage *dst, Point c, int a, int b, + int thick, Memimage *src, Point sp, Drawop op) +void memfillpoly(Memimage *dst, Point *p, int np, int wind, + Memimage *src, Point sp, Drawop op) +void memimageline(Memimage *dst, Point p0, Point p1, int end0, + int end1, int radius, Memimage *src, Point sp, Drawop op) +void memimagedraw(Memimage *dst, Rectangle r, Memimage *src, + Point sp, Memimage *mask, Point mp, Drawop op) +.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 +.B memdraw +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/sys/man/2/memlayer b/sys/man/2/memlayer new file mode 100755 index 000000000..b652bc0be --- /dev/null +++ b/sys/man/2/memlayer @@ -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, Drawop op) +.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/sys/man/2/memory b/sys/man/2/memory new file mode 100755 index 000000000..42bcc0555 --- /dev/null +++ b/sys/man/2/memory @@ -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, ulong n) +.PP +.B +void* memchr(void *s, int c, ulong n) +.PP +.B +int memcmp(void *s1, void *s2, ulong n) +.PP +.B +void* memcpy(void *s1, void *s2, ulong n) +.PP +.B +void* memmove(void *s1, void *s2, ulong n) +.PP +.B +void* memset(void *s, int c, ulong 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/sys/man/2/mktemp b/sys/man/2/mktemp new file mode 100755 index 000000000..683620ac7 --- /dev/null +++ b/sys/man/2/mktemp @@ -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/sys/man/2/mouse b/sys/man/2/mouse new file mode 100755 index 000000000..76625b683 --- /dev/null +++ b/sys/man/2/mouse @@ -0,0 +1,249 @@ +.TH MOUSE 2 +.SH NAME +initmouse, readmouse, closemouse, moveto, 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/sys/man/2/mp b/sys/man/2/mp new file mode 100755 index 000000000..9db58d106 --- /dev/null +++ b/sys/man/2/mp @@ -0,0 +1,610 @@ +.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 +.ta +\w'\fLCRTpre* \fP'u +.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, +.br +.B + 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, +.br +.B + 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, +.br +.B + mpdigit *quotient) +.PP +.B +void mpvecadd(mpdigit *a, int alen, mpdigit *b, int blen, +.br +.B + mpdigit *sum) +.PP +.B +void mpvecsub(mpdigit *a, int alen, mpdigit *b, int blen, +.br +.B + 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, +.br +.B + 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 +.DT +.SH DESCRIPTION +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: +.IP +.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, +.I mpbits +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. +The conventional verb is +.LR B , +for which +.I mp.h +provides a +.LR pragma . +.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 . +Sign is ignored in these conversions, i.e., the byte +array version is always positive. +.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" . +Both +.I a +and +.I b +are required to be positive. +If called with negative arguments, it will +return a gcd of 0. +.PP +.I Mpinverse +computes the multiplicative inverse of +.I b +.B mod +.IR m . +.PP +.I Mpsignif +returns the number of significant bits in +.IR b . +.I Mplowbits0 +returns the number of consecutive zero bits +at the low end of the significant bits. +For example, for 0x14, +.I mpsignif +returns 5 and +.I mplowbits0 +returns 2. +For 0, +.I mpsignif +and +.I mplowbits0 +both return 0. +.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: +.IP +.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/sys/man/2/muldiv b/sys/man/2/muldiv new file mode 100755 index 000000000..93444bd55 --- /dev/null +++ b/sys/man/2/muldiv @@ -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/sys/man/2/nan b/sys/man/2/nan new file mode 100755 index 000000000..90e39b994 --- /dev/null +++ b/sys/man/2/nan @@ -0,0 +1,52 @@ +.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. +By default, manipulating these values may cause a floating point exception +on some processors but +.I setfcr +(see +.IR getfcr (2)) +can change that behavior. +.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 +.SH "SEE ALSO" +.IR getfcr (2) diff --git a/sys/man/2/ndb b/sys/man/2/ndb new file mode 100755 index 000000000..8024816a8 --- /dev/null +++ b/sys/man/2/ndb @@ -0,0 +1,498 @@ +.TH NDB 2 +.SH NAME +ndbopen, ndbcat, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetvalue, ndbfree, ipattr, ndbgetipaddr, ndbipinfo, csipinfo, ndbhash, ndbparse, csgetvalue, ndbfindattr, dnsquery, ndbdiscard, ndbconcatenate, ndbreorder, ndbsubstitute, ndbgetval, csgetval, ndblookval \- 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 ndbchanged(Ndb *db) +.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 +char* ndbgetvalue(Ndb *db, Ndbs *s, char *attr, char *val, +.br +.B + char *rattr, Ndbtuple **tp) +.PP +.B +char* csgetvalue(char *netroot, char *attr, char *val, +.B + char *rattr, Ndbtuple **tp) +.PP +.B +char* ipattr(char *name) +.PP +.B +Ndbtuple* ndbgetipaddr(Ndb *db, char *sys); +.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, +.br +.B char **attrs, 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* ndbfindattr(Ndbtuple *entry, Ndbtuple *line, char *attr) +.PP +.B +void ndbfree(Ndbtuple *db) +.PP +.B +Ndbtuple* ndbdiscard(Ndbtuple *t, Ndbtuple *a) +.PP +.B +Ndbtuple* ndbconcatenate(Ndbtuple *a, Ndbtuple *b) +.PP +.B +Ndbtuple* ndbreorder(Ndbtuple *t, Ndbtuple *a) +.PP +.B +Ndbtuple* ndbsubstitute(Ndbtuple *t, Ndbtuple *from, Ndbtuple *to) +.PP +.B +void ndbsetmalloctag(Ndbtuple *t, uintptr tag) +.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 +throws out any cached information +for the database files associated with +.I db +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; + Ndbtuple *entry; + Ndbtuple *line; + ulong ptr; /* for the application; starts 0 */ + char valbuf[Ndbvlen]; /* initial allocation for val */ +}; +.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 Ndbgetvalue +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 returns a malloced copy of the NUL-terminated value associated with +.IR rattr . +If +.I tp +is non nil, +.I *tp +will point to the entry. Otherwise the entry will be freed. +.PP +.I Csgetvalue +is like +.I ndbgetvalue +but queries the connection server +instead of looking directly at the database. +Its 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 Ndbgetipaddr +looks in +.I db +for an entry matching +.I sys +as the value of a +.B sys= +or +.B dom= +attribute/value pair and returns all IP addresses in the entry. +If +.I sys +is already an IP address, a tuple containing just +that address is returned. +.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 . +If any +.I attrs +begin with +.LR @ , +the +.L @ +is excluded from the attribute name, +but causes any corresponding value returned +to be a resolved IP address(es), not a name. +For example, consider the following database entries describing a network, +a subnetwork, and a system. +.IP +.EX +ipnet=big ip=10.0.0.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 +.IP +.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 next three routines 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 logically arranged into lines using the +.B line +field in 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 Ndbfindattr +searches +.I entry +for the tuple +with attribute +.I attr +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. +.PP +All of the routines provided to search the database +provide an always consistent view of the relevant +files. However, it may be advantageous for an application +to read in the whole database using +.I ndbopen +and +.I ndbparse +and provide its own search routines. The +.I ndbchanged +routine can be used by the application to periodically +check for changes. It returns zero +if none of the files comprising the database have +changes and non-zero if they have. +.PP +Finally, a number of routines are provided for manipulating tuples. +.PP +.I Ndbdiscard +removes attr/val pair +.I a +from tuple +.I t +and frees it. +If +.I a +isn't in +.I t +it is just freed. +.PP +.I Ndbconcatenate +concatenates two tuples and returns the result. Either +or both tuples may be nil. +.PP +.I Ndbreorder +reorders a tuple +.IR t +to make the line containing attr/val pair +.I a +first in the entry and making +.I a +first in its line. +.PP +.I Ndbsubstitute +replaces a single att/val pair +.I from +in +.I t +with the tuple +.IR to . +All attr/val pairs in +.I to +end up on the same line. +.I from +is freed. +.PP +.I Ndbsetmalloctag +sets the malloc tag +(see +.I setmalloctag +in +.IR malloc (2)) +of each tuple in the list +.I t +to +.IR tag . +.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 +.IR Ndbgetvalue , +.IR csgetvalue , +and +.I ndblookvalue +set +.I errstr +to +.L "buffer too short" +if the buffer provided isn't long enough for the +returned value. +.SH BUGS +.IR Ndbgetval , +.IR csgetval , +and +.I ndblookval +are deprecated versions of +.IR ndbgetvalue , +.IR csgetvalue , +and +.IR ndblookvalue . +They expect a fixed 64 byte long result +buffer and existed when the values of a +.I Ndbtuple +structure were fixed length. diff --git a/sys/man/2/notify b/sys/man/2/notify new file mode 100755 index 000000000..fb78de427 --- /dev/null +++ b/sys/man/2/notify @@ -0,0 +1,244 @@ +.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. +Handlers may not perform floating point operations. +.PP +After a note is posted, +the handler is called with two arguments: +the first is a pointer to a +.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. +.SS Atnotify +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 . +.SS APE +.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. +.SS Notes +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/sys/man/2/object b/sys/man/2/object new file mode 100755 index 000000000..29a6bde3b --- /dev/null +++ b/sys/man/2/object @@ -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/sys/man/2/open b/sys/man/2/open new file mode 100755 index 000000000..10852cffa --- /dev/null +++ b/sys/man/2/open @@ -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/sys/man/2/perror b/sys/man/2/perror new file mode 100755 index 000000000..9d2856cb3 --- /dev/null +++ b/sys/man/2/perror @@ -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/sys/man/2/pipe b/sys/man/2/pipe new file mode 100755 index 000000000..d91fc0811 --- /dev/null +++ b/sys/man/2/pipe @@ -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/sys/man/2/plumb b/sys/man/2/plumb new file mode 100755 index 000000000..c9d521650 --- /dev/null +++ b/sys/man/2/plumb @@ -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/sys/man/2/pool b/sys/man/2/pool new file mode 100755 index 000000000..544fcf565 --- /dev/null +++ b/sys/man/2/pool @@ -0,0 +1,356 @@ +.TH POOL 2 +.SH NAME +poolalloc, poolallocalign, poolfree, poolmsize, poolrealloc, poolcompact, poolcheck, poolblockcheck, +pooldump \- general memory management routines +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void* poolalloc(Pool* pool, ulong size) +.PP +.B +void* poolallocalign(Pool *pool, ulong size, +.br +.B + ulong align, long offset, ulong span) +.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. +.PP +.I Poolallocalign +attempts to allocate a block of size +.B size +with the given alignment constraints. +If +.I align +is non-zero, +the returned pointer is aligned to be equal to +.I offset +modulo +.IR align . +If +.I span +is non-zero, +the +.I n +byte block allocated will not span a +.IR span -byte +boundary. +.PP +.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/sys/man/2/postnote b/sys/man/2/postnote new file mode 100755 index 000000000..6b4de1d41 --- /dev/null +++ b/sys/man/2/postnote @@ -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/sys/man/2/prime b/sys/man/2/prime new file mode 100755 index 000000000..40e31f0e9 --- /dev/null +++ b/sys/man/2/prime @@ -0,0 +1,100 @@ +.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 \- +(\fIp\fR-1)/2 is prime. Therefore +.IR p -1 +has a large prime factor, +.IR p '. +.IP \- +.IR p '-1 +has a large prime factor +.IP \- +.IR p +1 +has a large prime factor +.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/sys/man/2/print b/sys/man/2/print new file mode 100755 index 000000000..0188b5318 --- /dev/null +++ b/sys/man/2/print @@ -0,0 +1,452 @@ +.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 nul-terminated 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. +If a +.I precision +is given, it is safe for the string not to be nul-terminated +as long as it is at least +.I precision +characters (not bytes!) long. +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 single pointer or pointer-sized integer +.RB ( uintptr , +see +.IR intro (2)) +in hexadecimal. +.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 = seprint(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/sys/man/2/privalloc b/sys/man/2/privalloc new file mode 100755 index 000000000..20dd0bf2f --- /dev/null +++ b/sys/man/2/privalloc @@ -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/sys/man/2/proto b/sys/man/2/proto new file mode 100755 index 000000000..563a19174 --- /dev/null +++ b/sys/man/2/proto @@ -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/sys/man/2/pushssl b/sys/man/2/pushssl new file mode 100755 index 000000000..efd552943 --- /dev/null +++ b/sys/man/2/pushssl @@ -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/sys/man/2/pushtls b/sys/man/2/pushtls new file mode 100755 index 000000000..d9de3717c --- /dev/null +++ b/sys/man/2/pushtls @@ -0,0 +1,254 @@ +.TH PUSHTLS 2 +.SH NAME +pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +int pushtls(int fd, char *hashalg, char *encalg, +.B + int isclient, char *secret, char *dir) +.PP +.nf +.B #include +.B #include +.PP +.B +int tlsClient(int fd, TLSconn *conn) +.PP +.B +int tlsServer(int fd, TLSconn *conn) +.PP +.B +uchar *readcert(char *filename, int *pcertlen) +.PP +.B +PEMchain *readcertchain(char *filename) +.PP +.B +Thumbprint *initThumbprints(char *ok, char *crl) +.PP +.B +void freeThumbprints(Thumbprint *table) +.PP +.B +int okThumbprint(uchar *hash, Thumbprint *table) +.SH DESCRIPTION +Transport Layer Security (TLS) comprises a record layer protocol, +doing message digesting and encrypting in the kernel, +and a handshake protocol, +doing initial authentication and secret creation at +user level and then starting a data channel in the record protocol. +TLS is nearly the same as SSL 3.0, and the software should interoperate +with implementations of either standard. +.PP +To use just the record layer, as described in +.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. +.SS Certificates +.\" and other horseshit +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: +.IP +.EX +typedef struct TLSconn { + char dir[40]; /* OUT connection directory */ + uchar *cert; /* IN/OUT certificate */ + uchar *sessionID; /* IN/OUT session ID */ + int certlen, sessionIDlen; + void (*trace)(char*fmt, ...); + PEMChain *chain; + char *sessionType; /* opt IN session type */ + uchar *sessionKey; /* opt IN/OUT session key */ + int sessionKeylen; /* opt IN session key length */ + char *sessionConst; /* opt IN session constant */ +} TLSconn; +.EE +.PP +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 way to check the remote certificate is to use +.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. +.PP +.I TlsClient +will optionally compute a session key for use +by higher-level protocols. +To compute a session key, the caller must set +.I sessionType +to a known session type; +.I sessionKeylen +to the desired key length; +.I sessionKey +to a buffer of length +.IR sessionKeylen ; +and +.I sessionConst +to the desired salting constant. +The only supported session type is +.BR ttls , +as used by 802.1x. +.PP +.I TlsServer +executes the server side of the handshake. +The caller must initialize +.IB conn ->cert \fR, +usually by calling +.I readcert +to read and decode the PEM-encoded certificate from +.IR filename , +return a pointer to +.IR malloc ed +storage containing the certificate, +and store its length through +.IR pcertlen . +The private key corresponding to +.I cert.pem +should have been previously loaded into factotum. +(See +.IR rsa (8) +for more about key generation.) +.PP +.I Readcertchain +will read a PEM-encoded chain of certificates from +.I filename +and return a pointer to a linked list of +.IR malloc ed +.B PEMChain +structures, defined in +.IR tls.h : +.IP +.EX +typedef struct PEMChain PEMChain; +struct PEMChain { + PEMChain*next; + uchar *pem; + int pemlen; +}; +.EE +.LP +By setting +.IP +.EX +conn->chain = readcertchain("intermediate-certs.pem"); +.EE +.LP +the server can present extra certificate evidence +to establish the chain of trust to a root authority +known to the client. +.PP +.I Conn +is not required for the ongoing conversation and may +be freed by the application whenever convenient. +.SH EXAMPLES +Start the client half of TLS and check the remote certificate: +.IP +.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"); +\fI...application begins...\fP +.EE +.PP +Run the server side: +.IP +.EX +fd = accept(lcfd, ldir); +conn = (TLSconn*)mallocz(sizeof *conn, 1); +conn->cert = readcert("cert.pem", &conn->certlen); +fd = tlsServer(fd, conn); +\fI...application begins...\fP +.EE +.SH FILES +.TF /sys/lib/tls +.TP +.B /sys/lib/tls +thumbprints of trusted services +.TP +.B /sys/lib/ssl +PEM certificate files +.SH SOURCE +.B /sys/src/libc/9sys/pushtls.c +.br +.B /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 +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 +.IR factotum . diff --git a/sys/man/2/qball b/sys/man/2/qball new file mode 100755 index 000000000..95f00561e --- /dev/null +++ b/sys/man/2/qball @@ -0,0 +1,75 @@ +.TH QBALL 2 +.SH NAME +qball \- 3-d rotation controller +.SH SYNOPSIS +.B +#include +.br +.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/sys/man/2/qsort b/sys/man/2/qsort new file mode 100755 index 000000000..9f0aedaeb --- /dev/null +++ b/sys/man/2/qsort @@ -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/sys/man/2/quaternion b/sys/man/2/quaternion new file mode 100755 index 000000000..3b637b184 --- /dev/null +++ b/sys/man/2/quaternion @@ -0,0 +1,151 @@ +.TH QUATERNION 2 +.SH NAME +qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, qmid, qsqrt \- Quaternion arithmetic +.SH SYNOPSIS +.B +#include +.br +.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/sys/man/2/quote b/sys/man/2/quote new file mode 100755 index 000000000..ee96421a9 --- /dev/null +++ b/sys/man/2/quote @@ -0,0 +1,167 @@ +.TH QUOTE 2 +.SH NAME +quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote, needsrcquote \- 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 +.B +int needsrcquote(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. +.I Needsrcquote +is provided as a +.I doquote +function that flags any character special to +.IR rc (1). +.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/sys/man/2/rand b/sys/man/2/rand new file mode 100755 index 000000000..aba8a8b9c --- /dev/null +++ b/sys/man/2/rand @@ -0,0 +1,175 @@ +.TH RAND 2 +.SH NAME +rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, genrandom, prng, fastrand, nfastrand \- random number generators +.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) +.sp +.B #include +.br +.B #include +.PP +.B +void genrandom(uchar *buf, int nbytes) +.PP +.B +void prng(uchar *buf, int nbytes) +.PP +.B +ulong fastrand(void) +.PP +.B +ulong nfastrand(ulong val) +.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 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 +.I genrandom +and +.I prng +may be passed to +.I mprand +(see +.IR mp (2)). +.PP +.I Fastrand +uses +.I genrandom +to return a uniform +.B "unsigned long +.IR x , +.RI 0≤ x < 2\u\s732\s10\d-1. +.PP +.I Nfastrand +uses +.I genrandom +to return a uniform +.B "unsigned long +.IR x , +.RI 0≤ x < val ≤ 2\u\s732\s10\d-1. +.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 +.br +.B /sys/src/libsec/port/*fastrand.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/sys/man/2/rc4 b/sys/man/2/rc4 new file mode 100755 index 000000000..d35b43e4c --- /dev/null +++ b/sys/man/2/rc4 @@ -0,0 +1,55 @@ +.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 dsa (2), +.IR elgamal (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/sys/man/2/read b/sys/man/2/read new file mode 100755 index 000000000..1ae092862 --- /dev/null +++ b/sys/man/2/read @@ -0,0 +1,96 @@ +.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 +are 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 dirread (2), +.IR dup (2), +.IR open (2), +.IR pipe (2), +.IR readv (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/sys/man/2/readcolmap b/sys/man/2/readcolmap new file mode 100755 index 000000000..5ea74cb33 --- /dev/null +++ b/sys/man/2/readcolmap @@ -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/sys/man/2/readv b/sys/man/2/readv new file mode 100755 index 000000000..31dcb8842 --- /dev/null +++ b/sys/man/2/readv @@ -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/sys/man/2/regexp b/sys/man/2/regexp new file mode 100755 index 000000000..6558dc710 --- /dev/null +++ b/sys/man/2/regexp @@ -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/sys/man/2/remove b/sys/man/2/remove new file mode 100755 index 000000000..7547e46a7 --- /dev/null +++ b/sys/man/2/remove @@ -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/sys/man/2/rendezvous b/sys/man/2/rendezvous new file mode 100755 index 000000000..1bba3fc90 --- /dev/null +++ b/sys/man/2/rendezvous @@ -0,0 +1,58 @@ +.TH RENDEZVOUS 2 +.SH NAME +rendezvous \- user level process synchronization +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +void* rendezvous(void* tag, void* 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 fork (2), +.IR lock (2), +.IR segattach (2) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/sys/man/2/rsa b/sys/man/2/rsa new file mode 100755 index 000000000..957ac05c2 --- /dev/null +++ b/sys/man/2/rsa @@ -0,0 +1,219 @@ +.TH RSA 2 +.SH NAME +asn1dump, +asn1toRSApriv, +decodePEM, +rsadecrypt, +rsaencrypt, +rsagen, +rsaprivalloc, +rsaprivfree, +rsaprivtopub, +rsapuballoc, +rsapubfree, +X509toRSApub, +X509gen, +X509verify \- RSA encryption algorithm +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ta +\w'\fLRSApriv* \fP'u +.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 +void asn1dump(uchar *der, int len) +.PP +.B +uchar* decodePEM(char *s, char *type, int *len, char **new_s) +.PP +.B +uchar* X509gen(RSApriv *priv, char *subj, ulong valid[2], int *certlen); +.PP +.B +uchar* X509req(RSApriv *priv, char *subj, int *certlen); +.PP +.B +char* X509verify(uchar *cert, int ncert, RSApub *pk) +.DT +.SH DESCRIPTION +RSA is a public key encryption algorithm. The owner of a key publishes +the public part of the key: +.IP +.EX +struct RSApub +{ + mpint *n; /* modulus */ + mpint *ek; /* exp (encryption key) */ +}; +.EE +.LP +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: +.IP +.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 . +For the special case of +certificates signed by a known trusted key +(in a single step, without certificate chains), +.I X509verify +checks the signature on +.IR cert . +It returns nil if successful, else an error string. +.PP +.I X509gen +creates a self-signed X.509 certificate, given an RSA keypair +.IR priv , +a issuer/subject string +.IR subj , +and the starting and ending validity dates, +.IR valid . +Length of the allocated binary certificate is stored in +.IR certlen . +The subject line is conventionally of the form +.IP +.EX +C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric +.EE +.LP +using the quoting conventions of +.I tokenize +in +.IR getfields (2). +.PP +.I Asn1toRSApriv +converts an ASN1 formatted RSA private key into the corresponding +.B RSApriv +structure. +.PP +.I Asn1dump +prints an ASN1 object to standard output. +.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 +.IR malloc ed +storage containing the decoded section, +which the caller must free, +and sets +.BI * len +to its decoded length. +Otherwise +.B nil +is returned and +.BI * len +is undefined. +If not nil, +.I new_s +is set to the first character beyond the +.I type +section. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR dsa (2), +.IR elgamal (2), +.IR rc4 (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2), +.IR rsa (8) diff --git a/sys/man/2/rune b/sys/man/2/rune new file mode 100755 index 000000000..ca290115d --- /dev/null +++ b/sys/man/2/rune @@ -0,0 +1,193 @@ +.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 +.B Runeerror +(0xFFFD) +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/sys/man/2/runestrcat b/sys/man/2/runestrcat new file mode 100755 index 000000000..043de093d --- /dev/null +++ b/sys/man/2/runestrcat @@ -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/sys/man/2/scribble b/sys/man/2/scribble new file mode 100755 index 000000000..6f394add5 --- /dev/null +++ b/sys/man/2/scribble @@ -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/sys/man/2/scsi b/sys/man/2/scsi new file mode 100755 index 000000000..280ba5f57 --- /dev/null +++ b/sys/man/2/scsi @@ -0,0 +1,186 @@ +.TH SCSI 2 +.SH NAME +openscsi, closescsi, 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 +.ft L +int scsi(Scsi *s, uchar *cmd, int ncmd, +.br + void *data, int ndata, int dir) +.PP +.ft L +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 +.I inquire +in the 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/sys/man/2/sechash b/sys/man/2/sechash new file mode 100755 index 000000000..7524881f8 --- /dev/null +++ b/sys/man/2/sechash @@ -0,0 +1,203 @@ +.TH SECHASH 2 +.SH NAME +md4, md5, +sha1, sha2_224, sha2_256, sha2_384, sha2_512, +aes, hmac_x, hmac_md5, +hmac_sha1, hmac_sha2_224, hmac_sha2_256, hmac_sha2_384, hmac_sha2_512, +hmac_aes, md5pickle, md5unpickle, +sha1pickle, sha1unpickle \- cryptographically secure hashes +.SH SYNOPSIS +.nr Wd \w'\fLDS* \fP'u +.nr In \w'\fLDS* \fP'u +.ta \n(Wdu \w'\fLSHA1state* \fP'u +\n(Wdu +\n(Wdu +\n(Wdu +\n(Wdu +. +.de Ti +.PP +.in +\\n(Inu +.ti -\\n(Inu +.B +.nh +.. +. +.ft L +.nf +#include +#include +#include +#include +#define DS DigestState /* only to abbreviate SYNOPSIS */ +.fi +. +.Ti +DS* md4(uchar *data, ulong dlen, uchar *digest, DS *state) +.Ti +DS* md5(uchar *data, ulong dlen, uchar *digest, DS *state) +.PP +.B +char* md5pickle(MD5state *state) +.PP +.B +MD5state* md5unpickle(char *p); +.Ti +DS* sha1(uchar *data, ulong dlen, uchar *digest, DS *state) +.PP +.B +char* sha1pickle(SHA1state *state) +.PP +.B +SHA1state* sha1unpickle(char *p); +.Ti +DS* sha2_224(uchar *data, ulong dlen, uchar *digest, DS *state) +.Ti +DS* sha2_256(uchar *data, ulong dlen, uchar *digest, DS *state) +.Ti +DS* sha2_384(uchar *data, ulong dlen, uchar *digest, DS *state) +.Ti +DS* sha2_512(uchar *data, ulong dlen, uchar *digest, DS *state) +.Ti +DS* aes(uchar *data, ulong dlen, uchar *digest, DS *state) +.Ti +DS* hmac_x(uchar *p, ulong len, uchar *key, ulong klen, uchar *digest, DS *s, DS*(*x)(uchar*, ulong, uchar*, DS*), int xlen) +.Ti +DS* hmac_md5(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state) +.Ti +DS* hmac_sha1(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state) +.Ti +DS* hmac_sha2_224(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state) +.Ti +DS* hmac_sha2_256(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state) +.Ti +DS* hmac_sha2_384(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state) +.Ti +DS* hmac_sha2_512(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state) +.Ti +DS* hmac_aes(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DS *state) +.SH DESCRIPTION +.DT +We support several secure hash functions. The output of a +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 sha2_224 , +.IR sha2_256 , +.IR sha2_384 , +.IR sha2_512 , +.IR aes , +.IR hmac_md5 , +.IR hmac_sha1 , +.IR hmac_sha2_224 , +.IR hmac_sha2_256 , +.IR hmac_sha2_384 , +.IR hmac_sha2_512 , +and +.I hmac_aes +differ only in the length of the resulting digest +and in the security of the hash. +.I Sha2_* +and +.I hmac_sha2_* +are the SHA-2 functions; the number after the final underscore +is the number of bits in the resulting digest. +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 +.RL non- nil . +.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 . +.PP +The constants +.IR MD4dlen , +.IR MD5dlen , +.IR SHA1dlen , +.IR SHA2_224dlen , +.IR SHA2_256dlen , +.IR SHA2_384dlen, +.IR SHA2_512dlen , +and +.I AESdlen +define the lengths of the digests. +.PP +.IR Hmac_md5 , +.IR hmac_sha1 , +.IR hmac_sha2_224 , +.IR hmac_sha2_256 , +.IR hmac_sha2_384 , +.IR hmac_sha2_512 , +and +.I hmac_aes +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 the obvious ones from +the above list of length constants. +These routines all call +.I hmac_x +internally, but +.I hmac_x +is not intended for general use. +.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 EXAMPLES +To hash a single buffer using +.IR md5 : +.IP +.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: +.IP +.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 +.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) +.PD 0 +.TF /lib/rfc/rfc2104 +.TP +.B /lib/rfc/rfc2104 +HMAC specification diff --git a/sys/man/2/seek b/sys/man/2/seek new file mode 100755 index 000000000..8597376e7 --- /dev/null +++ b/sys/man/2/seek @@ -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/sys/man/2/segattach b/sys/man/2/segattach new file mode 100755 index 000000000..b6199fefb --- /dev/null +++ b/sys/man/2/segattach @@ -0,0 +1,168 @@ +.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 +void* 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. +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 initial stack segment 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 . +.I Segattach +returns +.B (void*)-1 +on error. +.SH BUGS +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/sys/man/2/segbrk b/sys/man/2/segbrk new file mode 100755 index 000000000..9cdb18f0b --- /dev/null +++ b/sys/man/2/segbrk @@ -0,0 +1,66 @@ +.TH SEGBRK 2 +.SH NAME +segbrk \- change memory allocation +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid* 'u +.B +void* 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 . +.I Segbrk +returns +.B (void*)-1 +on error. +.SH BUGS +.I Segbrk +is not fully defined or implemented. +In particular, +it cannot always return the top of bss +when called with a zero +.I addr +argument. +The +.I segbrk +system call may go away or be re-implemented +to give more general segment control, +subsuming the functions of +.IR brk (2), +.IR segflush (2) +and +.I segfree +in +.IR segattach (2). diff --git a/sys/man/2/segflush b/sys/man/2/segflush new file mode 100755 index 000000000..536825483 --- /dev/null +++ b/sys/man/2/segflush @@ -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/sys/man/2/semacquire b/sys/man/2/semacquire new file mode 100755 index 000000000..386734800 --- /dev/null +++ b/sys/man/2/semacquire @@ -0,0 +1,106 @@ +.TH SEMACQUIRE 2 +.SH NAME +semacquire, semrelease \- user level semaphores +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int semacquire(long *addr, int block); +.PP +.B +long semrelease(long *addr, long count); +.SH DESCRIPTION +.I Semacquire +and +.I semrelease +facilitate scheduling between processes sharing memory. +Processes arrange to share memory by using +.I rfork +with the +.B RFMEM +flag +(see +.IR fork (2)), +.IR segattach (2), +or +.IR thread (2). +.PP +The semaphore's value is the integer pointed at by +.IR addr . +.I Semacquire +atomically waits until the semaphore has a positive value +and then decrements that value. +It returns 1 if the semaphore was acquired and \-1 on error +(e.g., if it was interrupted). +If +.I block +is zero +and the semaphore is not immediately available, +.I semacquire +returns 0 instead of waiting. +.I Semrelease +adds +.I count +to the semaphore's value +and returns the new value. +.PP +.I Semacquire +and +.I semrelease +can be thought of as efficient, correct replacements for: +.IP +.EX +int +semacquire(long *addr, int block) +{ + while(*addr == 0){ + if(!block) + return 0; + if(interrupted) + return -1; + } + --*addr; + return 1; +} + +int +semrelease(long *addr, int count) +{ + return *addr += count; +} +.EE +.PP +Like +.IR rendezvous (2), +.I semacquire +and +.I semrelease +are not typically used directly. +Instead, they are intended to be used to coordinate +scheduling in higher-level abstractions such as +locks, rendezvous points, and channels +(see +.IR lock (2) +and +.IR thread (2)). +Also like +.I rendezvous , +.I semacquire +and +.I semrelease +cannot be used to coordinate between threads +in a single process. +Use locks, rendezvous points, or channels instead. +.SH SOURCE +.B /sys/src/9/port/sysproc.c +.SH SEE ALSO +.IR fork (2), +.IR lock (2), +.IR rendezvous (2), +.IR segattach (2), +.IR thread (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/sys/man/2/setjmp b/sys/man/2/setjmp new file mode 100755 index 000000000..48e4f969f --- /dev/null +++ b/sys/man/2/setjmp @@ -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. +Several macros are defined in +.B /$objtype/include/u.h +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/sys/man/2/sin b/sys/man/2/sin new file mode 100755 index 000000000..ac2c2c505 --- /dev/null +++ b/sys/man/2/sin @@ -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/sys/man/2/sinh b/sys/man/2/sinh new file mode 100755 index 000000000..7dd4184b5 --- /dev/null +++ b/sys/man/2/sinh @@ -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/sys/man/2/sleep b/sys/man/2/sleep new file mode 100755 index 000000000..013df3c5b --- /dev/null +++ b/sys/man/2/sleep @@ -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/sys/man/2/stat b/sys/man/2/stat new file mode 100755 index 000000000..26823e109 --- /dev/null +++ b/sys/man/2/stat @@ -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/sys/man/2/strcat b/sys/man/2/strcat new file mode 100755 index 000000000..57bd38e4a --- /dev/null +++ b/sys/man/2/strcat @@ -0,0 +1,269 @@ +.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 distinctions 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), +.IR string (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/sys/man/2/string b/sys/man/2/string new file mode 100755 index 000000000..ffae39bf3 --- /dev/null +++ b/sys/man/2/string @@ -0,0 +1,236 @@ +.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. +.I S_getline +will recursively read through files included with +.B #include +and discard all other lines beginning with +.BR # . +.SH SOURCE +.B /sys/src/libString +.SH SEE ALSO +.IR bio (2) diff --git a/sys/man/2/stringsize b/sys/man/2/stringsize new file mode 100755 index 000000000..128528151 --- /dev/null +++ b/sys/man/2/stringsize @@ -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/sys/man/2/subfont b/sys/man/2/subfont new file mode 100755 index 000000000..fb43b2a3c --- /dev/null +++ b/sys/man/2/subfont @@ -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/sys/man/2/symbol b/sys/man/2/symbol new file mode 100755 index 000000000..a25e73598 --- /dev/null +++ b/sys/man/2/symbol @@ -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/sys/man/2/thread b/sys/man/2/thread new file mode 100755 index 000000000..b06e31b96 --- /dev/null +++ b/sys/man/2/thread @@ -0,0 +1,642 @@ +.TH THREAD 2 +.SH NAME +alt, +chanclose, +chancreate, +chanfree, +chaninit, +chanclosing, +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, +threadsetgrp, +threadsetname, +threadwaitchan, +yield \- thread and proc management +.SH SYNOPSIS +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +#include +#include +#include +.sp +typedef enum { + CHANEND, + CHANSND, + CHANRCV, + CHANNOP, + CHANNOBLK, +} ChanOp; +.sp +.ta \w' 'u +\w'Channel 'u +typedef struct Alt Alt; +struct Alt { + Channel *c; /* channel */ + void *v; /* pointer to value */ + ChanOp op; /* operation */ + char *err; /* did the op fail? */ + /* + * the next variables are used internally to alt + * they need not be initialized + */ + Channel **tag; /* pointer to rendez-vous tag */ + int entryno; /* entry number */ +}; +.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) +void threadintgrp(int group) +void 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, ...) +int chanclose(Channel *c); +int chanclosing(Channel *c); +.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 +The thread library provides parallel programming support similar to that +of the languages +Alef and Newsqueak. +.I Threads +and +.I 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 ). +.SS Creation +.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. +.SS Scheduling +The threads in a proc are coroutines, scheduled non-preemptively +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), +plus these from +.IR lock (2): +.IR qlock , +.IR rlock , +.IR wlock , +.IR rsleep . +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. +.SS Names and per-thread data +Primarily for debugging, +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. +.SS Executing new programs +.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, never returning. +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. +Note that the mount point +.B /mnt/temp +must exist; +.I procexec(l) +mount pipes there. +.PP +.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. +.SS Channels +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 CHANRCV +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 +.I Chanclose +prevents further elements being sent to the channel +.IR c . +After closing a channel, +.I send +and +.I recv +never block. +.I Send +always +returns \-1. +.I Recv +returns \-1 if the channel is empty. +.I Alt +may choose a +.B CHANSND +or +.B CHANRCV +that failed because the channel was closed. +In this case, the +.B err +field of the +.B Alt +entry points to an error string stating that the +channel was closed and the operation was completed +with failure. +If all entries have been selected and failed because +they were closed, +.I alt +returns \-1. +.SS Errors, notes and resources +Thread library functions do not return on failure; +if errors occur, the entire program is aborted. +.PP +.I Chanclosing +returns \-1 if no one called +.I closed +on the channel, and otherwise +the number of elements still in the channel. +.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 +.TF /sys/lib/acid/thread +.TP +.B /sys/lib/acid/thread +useful +.IR acid (1) +functions for debugging threaded programs. +.TP +.B /sys/src/libthread/example.c +a full example program. +.TP +.B /mnt/temp +a place for +.I procexec +to create pipes. +.SH SOURCE +.B /sys/src/libthread +.SH SEE ALSO +.IR intro (2), +.IR ioproc (2), +.IR lock (2) diff --git a/sys/man/2/time b/sys/man/2/time new file mode 100755 index 000000000..d2af5a5f4 --- /dev/null +++ b/sys/man/2/time @@ -0,0 +1,44 @@ +.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 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 cputime (2), +.IR cons (3) +.SH DIAGNOSTICS +Sets +.IR errstr . +.SH BUGS +These routines maintain a static file descriptor. diff --git a/sys/man/2/tmpfile b/sys/man/2/tmpfile new file mode 100755 index 000000000..390b2346c --- /dev/null +++ b/sys/man/2/tmpfile @@ -0,0 +1,60 @@ +.TH TMPFILE 2 +.SH NAME +tmpfile, tmpnam \- Stdio temporary files +.SH SYNOPSIS +.B #include +.br +.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/sys/man/2/usb b/sys/man/2/usb new file mode 100755 index 000000000..d6f949f98 --- /dev/null +++ b/sys/man/2/usb @@ -0,0 +1,460 @@ +.TH USB 2 +.SH NAME +usbcmd, +classname, +closedev, +configdev, +devctl, +finddevs, +loaddevstr, +matchdevcsp, +opendev, +opendevdata, +openep, +startdevs, +unstall, +class, +subclass, +proto, +CSP \- USB device driver library +.SH SYNOPSIS +.EX +.ta 8n +8n +8n +8n +8n +8n +8n +#include +#include +#include +#include "../lib/usb.h" +.sp 0.3v +struct Dev { + Ref; + char* dir; /* path for the endpoint dir */ + int id; /* usb id for device or ep. number */ + int dfd; /* descriptor for the data file */ + int cfd; /* descriptor for the control file */ + int maxpkt; /* cached from usb description */ + Usbdev* usb; /* USB description */ + void* aux; /* for the device driver */ + void (*free)(void*); /* idem. to release aux */ +}; +.sp 0.3v +struct Usbdev { + ulong csp; /* USB class/subclass/proto */ + int vid; /* vendor id */ + int did; /* product (device) id */ + int dno; /* device release number */ + char* vendor; + char* product; + char* serial; + int ls; /* low speed */ + int class; /* from descriptor */ + int nconf; /* from descriptor */ + Conf* conf[Nconf]; /* configurations */ + Ep* ep[Nep]; /* all endpoints in device */ + Desc* ddesc[Nddesc]; /* (raw) device specific descriptors */ +}; +.sp 0.3v +struct Ep { + uchar addr; /* endpt address */ + uchar dir; /* direction, Ein/Eout */ + uchar type; /* Econtrol, Eiso, Ebulk, Eintr */ + uchar isotype; /* Eunknown, Easync, Eadapt, Esync */ + int id; + int maxpkt; /* max. packet size */ + Conf* conf; /* the endpoint belongs to */ + Iface* iface; /* the endpoint belongs to */ +}; +.sp 0.3v +struct Altc { + int attrib; + int interval; + void* aux; /* for the driver program */ +}; +.sp 0.3v +struct Iface { + int id; /* interface number */ + ulong csp; /* USB class/subclass/proto */ + Altc* altc[Naltc]; + Ep* ep[Nep]; + void* aux; /* for the driver program */ +}; +.sp 0.3v +struct Conf { + int cval; /* value for set configuration */ + int attrib; + int milliamps; /* maximum power in this config. */ + Iface* iface[Niface]; /* up to 16 interfaces */ +}; +.sp 0.3v +struct Desc { + Conf* conf; /* where this descriptor was read */ + Iface* iface; /* last iface before desc in conf. */ + Ep* ep; /* last endpt before desc in conf. */ + Altc* altc; /* last alt.c. before desc in conf. */ + DDesc data; /* unparsed standard USB descriptor */ +}; +.sp 0.3v +struct DDesc { + uchar bLength; + uchar bDescriptorType; + uchar bbytes[1]; + /* extra bytes allocated here to keep the rest of it */ +}; +.sp 0.3v +#define Class(csp) ((csp)&0xff) +#define Subclass(csp) (((csp)>>8)&0xff) +#define Proto(csp) (((csp)>>16)&0xff) +#define CSP(c, s, p) ((c) | ((s)<<8) | ((p)<<16)) +#define GET2(p) ... +#define PUT2(p,v) ... +#define GET4(p) ... +#define PUT4(p,v) ... +#define dprint if(usbdebug)fprint +#define ddprint if(usbdebug > 1)fprint +.sp 0.3v +int Ufmt(Fmt *f); +char* classname(int c); +void closedev(Dev *d); +int configdev(Dev *d); +int devctl(Dev *dev, char *fmt, ...); +void* emallocz(ulong size, int zero); +char* estrdup(char *s); +int finddevs(int (*matchf)(char*,void*), void *farg, char** dirs, int ndirs); +char* hexstr(void *a, int n); +char* loaddevstr(Dev *d, int sid); +int matchdevcsp(char *info, void *a); +Dev* opendev(char *fn); +int opendevdata(Dev *d, int mode); +Dev* openep(Dev *d, int id); +void startdevs(char *args, char *argv[], int argc, + int (*mf)(char*,void*), void*ma, int (*df)(Dev*,int,char**)); +int unstall(Dev *dev, Dev *ep, int dir); +int usbcmd(Dev *d, int type, int req, + int value, int index, uchar *data, int count); +.sp 0.3v +extern int usbdebug; /* more messages for bigger values */ +.EE +.SH DESCRIPTION +This library provides convenience structures and functions to write +USB device drivers. +It is not intended for user programs using USB devices. +See +.IR usb (3) +for a description of the interfaces provided for that purpose. +For drivers that provide a file system and may be embedded into +.IR usbd , +the library includes a file system implementation toolkit described in +.IR usbfs (2). +.PP +Usb drivers rely on +.IR usb (3) +to perform I/O through USB as well as on +.IR usbd (4) +to perform the initial configuration for the device's setup endpoint. +The rest of the work is up to the driver and is where this library may help. +.PP +In most cases, a driver locates the devices of interest and configures them +by calling +.I startdevs +and +then sets up additional endpoints as needed (by calling +.IR openep ) +to finally perform I/O by reading and writing the +data files for the endpoints. +.PP +An endpoint as provided by +.IR usb (3) +is represented by a +.B Dev +data structure. +The setup endpoint for a +device represents the USB device, because it is the means to +configure and operate the device. +This structure is reference counted. +Functions creating +.B Devs +adjust the number of references to one, initially. +The driver is free to call +.IR incref +(in +.IR lock (2)) +to add references and +.I closedev +to drop references (and release resources when the last one vanishes). +As an aid to the driver, the field +.B aux +may keep driver-specific data and the function +.B free +will be called (if not null) to release the +.B aux +structure when the reference count goes down to zero. +.PP +.I Dev.dir +holds the path for the endpoint's directory. +.PP +The field +.B id +keeps the device number for setup endpoints and the endpoint number +for all other endpoints. +For example, it would be +.B 3 +for +.B /dev/usb/ep3.0 +and +.B 1 +for +.BR /dev/usb/ep3.1 . +It is easy to remember this because the former is created to operate +on the device, while the later has been created as a particular endpoint +to perform I/O. +.PP +Fields +.B dfd +and +.B cfd +keep the data and +control file descriptors, respectively. +When a +.B Dev +is created the control file is open, initially. +Opening the data +file requires calling +.I opendevdata +with the appropriate mode. +.PP +When the device configuration information has been loaded (see below), +.B maxpkt +holds the maximum packet size (in bytes) for the endpoint and +.B usb +keeps the rest of the USB information. +.PP +Most of the information in +.B usb +comes from parsing +various device and configuration descriptors provided by the device, +by calling one of the functions described later. +Only descriptors unknown +to the library are kept unparsed at +.B usb.ddesc +as an aid for the driver +(which should know how to parse them and what to do with the information). +.SS Configuration +.I Startdevs +is a wrapper that locates devices of interest, loads their configuration +information, and starts a +.IR thread (2)'s +.I proc +for each device located so that it executes +.I f +as its main entry point. The entry point is called with a pointer to +the +.B Dev +for the device it has to process, +.BR argc , +and +.BR argv . +Devices are located either from the arguments (after options) in +.IR argv , +if any, +or by calling the helper function +.I mf +with the argument +.I ma +to determine (for each device available) if the device belongs to +the driver or not. If the function returns -1 then the device is not for us. +.PP +In many cases, +.I matchdevcsp +may be supplied as +.I mf +along with a (null terminated) vector of CSP values supplied as +.IR ma . +This function returns 0 for any device with a CSP matching one in the +vector supplied as an argument and -1 otherwise. +In other cases (eg., when a particular vendor and device ids are the +ones identifying the device) the driver must include its own function +and supply it as an argument to +.IR startdevs . +The first argument of the function corresponds to the information +known about the device (the second line in its +.B ctl +file). +.I Openep +creates the endpoint number +.I id +for the device +.I d +and returns a +.B Dev +structure to operate on it (with just the control file open). +.PP +.I Opendev +creates a +.B Dev +for the endpoint with directory +.IR fn . +Usually, the endpoint is a setup endpoint representing a device. The endpoint +control file is open, but the data file is not. The USB description is void. +In most cases drivers call +.I startdevs +and +.I openep +and do not call this function directly. +.PP +.I Configdev +opens the data file for the device supplied and +loads and parses its configuration information. +After calling it, the device is ready for I/O and the USB description in +.B Dev.usb +is valid. +When using +.IR startdevs +it is not desirable to call this function (because +.IR startdevs +already calls it). +.PP +Control requests for an endpoint may be written by calling +.I devctl +in the style of +.IR print (2). +It is better not to call +.I print +directly because the control request should be issued as a single +.I write +system call. +See +.IR usb (3) +for a list of available control requests (not to be confused with +USB control transfers performed on a control endpoint). +.SS Input/Output +.I Opendevdata +opens the data file for the device according to the given +.IR mode . +The mode must match that of the endpoint, doing otherwise is considered +an error. +Actual I/O is performed by reading/writing the descriptor kept in the +.B dfd +field of +.BR Dev . +.PP +For control endpoints, +it is not necessary to call +.I read +and +.I write +directly. +Instead, +.I usbcmd +issues a USB control request to the device +.I d +(not to be confused with a +.IR usb (3) +control request sent to its control file). +.I Usbcmd +retries the control request several times upon failure because some devices +require it. +The format of requests is fixed per the USB standard: +.I type +is the type of request and +.I req +identifies the request. Arguments +.I value +and +.I index +are parameters to the request and the last two arguments, +.I data +and +.IR count , +are similar to +.I read +and +.I write +arguments. +However, +.I data +may be +.B nil +if no transfer (other than the control request) has to take place. +The library header file includes numerous symbols defined to help writing +the type and arguments for a request. +.PP +The return value from +.I usbcmd +is the number of bytes transferred, zero to indicate a stall and -1 +to indicate an error. +.PP +A common request is to unstall an endpoint that has been stalled +due to some reason by the device (eg., when read or write indicate +a count of zero bytes read or written on the endpoint). The function +.I unstall +does this. +It is given the device that stalled the endpoint, +.IR dev , +the +stalled endpoint, +.IR ep , +and the direction of the stall (one of +.B Ein +or +.BR Eout ). +The function takes care of notifying the device of the unstall as well +as notifying the kernel. +.SS Tools +.I Class +returns the class part of the number given, representing a CSP. +.I Subclass +does the same for the device subclass and +.I Proto +for the protocol. +The counterpart is +.IR CSP , +which builds a CSP from the device class, subclass, and protocol. +For some classes, +.I classname +knows the name (for those with constants in the library header file). +.PP +The macros +.I GET2 +and +.I PUT2 +get and put a (little-endian) two-byte value and are useful to +parse descriptors and replies for control requests. +.PP +Functions +.I emallocz +and +.I estrdup +are similar to +.I mallocz +and +.I strdup +but abort program operation upon failure. +.PP +The function +.I Ufmt +is a format routine suitable for +.IR fmtinstall (2) +to print a +.B Dev +data structure. +The auxiliary +.I hexstr +returns a string representing a dump (in hexadecimal) of +.I n +bytes starting at +.IR a . +The string is allocated using +.IR malloc (2) +and memory must be released by the caller. +.PP +.I Loaddevstr +returns the string obtained by reading the device string descriptor number +.IR sid . +.SH SOURCE +.B /sys/src/cmd/usb/lib +.SH "SEE ALSO" +.IR usbfs (2), +.IR usb (3), +.IR usb (4), +.IR usbd (4). +.SH BUGS +Not heavily exercised yet. diff --git a/sys/man/2/usbfs b/sys/man/2/usbfs new file mode 100755 index 000000000..6c76280a8 --- /dev/null +++ b/sys/man/2/usbfs @@ -0,0 +1,341 @@ +.TH USBFS 2 +.SH NAME +usbreadbuf, +usbfsadd, +usbfsdel, +usbdirread, +usbfsinit, +usbdirfs, +usbfs \- USB device driver file system library +.SH SYNOPSIS +.EX +.ta 8n +8n +8n +8n +8n +8n +8n +#include +#include +#include +#include "../lib/usb.h" +#include "../lib/usbfs.h" +.sp 0.3v +enum { + Hdrsize = 128, /* plenty of room for headers */ + Msgsize = 8 * 1024, + Bufsize = Hdrsize + Msgsize, + Namesz = 40, + Errmax = 128, + ONONE = ~0, /* omode in Fid when not open */ +}; +.sp 0.3v +struct Fid { + int fid; + Qid qid; + int omode; + Fid* next; + void* aux; +}; +.sp 0.3v +struct Usbfs { + char name[Namesz]; + uvlong qid; + Dev* dev; + void* aux; +.sp 0.3v + int (*walk)(Usbfs *fs, Fid *f, char *name); + void (*clone)(Usbfs *fs, Fid *of, Fid *nf); + void (*clunk)(Usbfs *fs, Fid *f); + int (*open)(Usbfs *fs, Fid *f, int mode); + long (*read)(Usbfs *fs, Fid *f, + void *data, long count, vlong offset); + long (*write)(Usbfs *fs, Fid*f, + void *data, long count, vlong offset); + int (*stat)(Usbfs *fs, Qid q, Dir *d); + void (*end)(Usbfs *fs); +}; +.sp 0.3v +typedef int (*Dirgen)(Usbfs*, Qid, int, Dir*, void*); +.sp 0.3v +long usbreadbuf(void *data, long count, + vlong offset, void *buf, long n); +void usbfsadd(Usbfs *dfs); +void usbfsdel(Usbfs *dfs); +int usbdirread(Usbfs*f, Qid q, char *data, long cnt, + vlong off, Dirgen gen, void *arg); +void usbfsinit(char* srv, char *mnt, Usbfs *f, int flag); +void usbfsdirdump(void); +.sp 0.3v +extern char Enotfound[], Etoosmall[], Eio[], Eperm[], Ebadcall[], + Ebadfid[], Einuse[], Eisopen[], Ebadctl[]; +.sp 0.3v +extern Usbfs usbdirfs; +extern int usbfsdebug; +.EE +.SH DESCRIPTION +This library provides an alternative to +.IR 9p (2) +for implementing a file server within a USB driver. +Drivers using this +library may be embedded into +.IR usbd (4). +It may be also desirable to use this library when drivers are +not embedded because it is tailored to work well with the +library for handling USB devices. +.PP +A USB file system is described by a +.I Usbfs +structure. +In most cases, the driver is not responsible for the root of the +file tree. +It is customary that a driver creates a file server +for each device handled and links all of them to a root directory +implemented by the +.I usbdirfs +file system implemented by the library. +This root directory is bound to +.B /dev +in most cases. +.PP +.I Usbdirfs +implements a root directory populated by named file trees, +each one described by a +.B Usbfs +structure. +.PP +The field +.B Usbfs.name +contains the name for the root directory of the file system, usually +a directory seen at +.BI /dev/ name +when the driver is embedded. +.PP +.B Usbfs.qid +maintains a value used to decorate qids for the file tree. +This may be ignored when +.I usbdirfs +is not used. +Otherwise, +.I usbdirfs +assigns a unique value kept at the high 32 bits of +.B Qid.path +for all files on each file tree bound to it. +Each +.I Usbfs +server must bitwise OR +.B Usbfs.qid +to all +.B Qid.path +values returned by its functions. +In the same way, +functions usually clear bits in +.B Usbfs.qid +before processing +.B Qid.path +values supplied as input. +.PP +The USB device handled by a file tree is referenced from +.B Usbfs.dev +(and a reference must be counted for it). +This permits the following functions to quickly locate the device of +interest, and also permits releasing the device when +no request is outstanding. +.PP +The field +.B Usbfs.aux +is for the device to use. +The rest of the fields implement the 9P protocol for the device. +Not all the operations need be implemented. +Only +.IR walk , +.IR open , +.IR read , +.IR write , +and +.IR stat , +must be implemented (and their corresponding fields in +.B Usbfs +may never be +.BR nil ). +These functions must return -1 upon failure +and set the error string to reflect the cause of a failure. +.PP +In all the functions, a 9P fid is represented by a +.B Fid +structure. +It contains the 9P +.IR fid , +the corresponding +.IR qid , +and an auxiliary pointer for the driver to use. +Open +.IR fid s +have a valid open mode in +.I omode +while others have +.B ONONE +to indicate that the +.I fid +is not open. +The library takes care of which +fids +exist and which ones do not. +.PP +.I Walk +must walk +.I f +to +.I name +(a single name, not a file path) +in the supplied +.IR fs . +Its implementation should update the qid in +.I f +to reflect the walk. +This function must bitwise OR any returned Qid with +.B Usbfs.qid , +if +.I usbdirfs +is used. +.PP +.I Clone +must clone fid +.I of +onto +.I nf +so that, +upon successful completion, +.I nf +also refers to the file that +.I f +refers to. +An implementation must update the Qid of the cloned +fid. +If this function is not supplied, the library copies the +.I aux +field to the cloned fid. +.PP +.I Clunk +clunks +.IR f . +It usually releases data kept in the +.I aux +field, but may be +set to +.B nil +otherwise. +.PP +.I Open +prepares the fid +.I f +for I/O according to +.IR mode . +The open mode in the fid is updated by the library upon return. +The library checks trivial cases like opening already-open fids. +The implementation performs most permission checking. +.PP +.I Read +reads up to +.I count +bytes into +.I data +starting at +.I offset +in the file referenced by +.IR f . +.I Write +is the counterpart. +To read from directories, +the function +.I usbdirread +may be called. +It returns the return value of +.I read +or -1. +.I usbdirread +calls +.I gen +to iterate through files as needed. +The +.B Dirgen +function will be called with index values of 0 +and up to ask for the first file and following files. +To read from data already in buffers, the function +.I usbreadbuf +may help. +It must be given the arguments supplied +by the user, plus the buffer and buffer size. +.PP +.I Stat +must fill +.I d +with the directory entry for the file identified by +.IR q. +As an aid, +.I d +is initialized to fake access and modification times, +and user and group ids. +Also, the field +.B name +in +.I d +is initialized to point to a 40-byte buffer. +If the file name fits, +it may be copied directly into +.B d->name +without allocating memory for that purpose. +Otherwise +.B d->name +must be initialized to point to static memory. +.PP +The function +.I end +is called upon termination of the file tree to +release resources. +.PP +Calling +.I usbfsinit +starts a file server for +.I f +that mounts itself at +.I mnt +and posts +.I srv +at +.IR srv (3). +In most cases, the file system supplied is +.IR usbdirfs . +The +.I flag +is used for +.IR mount +(see +.IR bind (2)). +Once +.I usbdirfs +is started, calls to +.IR usbfsadd +add a file tree implemented by +.I dfs +to the root directory of +.I usbdirfs +and +calls to +.I usbfsdel +remove that binding (and release resources including +the reference to the USB device). +.PP +Various error strings are declared as an aid. +The global +.B usbfsdebug +may be set to trigger diagnostics and protocol tracing. +.SH EXAMPLE +See +.B /sys/src/cmd/usb/disk +for an example driver that uses this library. +Looking at an example is strongly suggested +to see how reference counts for the USB device +and the file system are handled. +.SH SOURCE +.B /sys/src/cmd/usb/lib +.SH "SEE ALSO" +.IR usb (2), +.IR usb (3), +.IR usb (4), +.IR usbd (4) diff --git a/sys/man/2/venti b/sys/man/2/venti new file mode 100755 index 000000000..7fd292404 --- /dev/null +++ b/sys/man/2/venti @@ -0,0 +1,72 @@ +.TH VENTI 2 +.SH NAME +venti \- archival storage server +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.SH DESCRIPTION +The Venti library provides support for writing Venti servers and clients. +Other manual pages describe the library functions in detail. +.PP +.IR Venti-cache (2) +describes a simple in-memory block cache to help clients. +.PP +.IR Venti-conn (2) +describes routines for manipulating network connections +between Venti clients and servers. +.IR Venti-client (2) +and +.IR venti-server (2) +describe routines for writing clients +and servers on top of these. +.PP +.IR Venti-fcall (2) +describes the C representation of Venti protocol messages +and data structures. +It also describes routines that convert between the C representation +and the network and disk representations. +.PP +.IR Venti-file (2) +describes routines for writing clients that manipulate +Venti file trees +(see +.IR venti (6)). +.PP +.IR Venti-log (2) +describes routines to access in-memory log buffers +as well as the logging that is done automatically by +the library. +.PP +.IR Venti-mem (2) +describes wrappers around the canonical +.IR malloc (2) +routines that abort on error. +.PP +.IR Venti-packet (2) +describes routines for +manipulating zero-copy chains of +data buffers. +.PP +.IR Venti-zero (2) +describes routines to zero truncate and zero extend blocks +(see +.IR venti (6)). +.SH SOURCE +.B /sys/src/libventi +.SH SEE ALSO +.IR venti (1), +.IR venti-cache (2), +.IR venti-client (2), +.IR venti-fcall (2), +.IR venti-file (2) +.IR venti-log (2), +.IR venti-mem (2), +.IR venti-packet (2), +.IR venti-server (2), +.IR venti-zero (2), +.IR venti (6), +.IR venti (8) diff --git a/sys/man/2/venti-cache b/sys/man/2/venti-cache new file mode 100755 index 000000000..bca14bd7a --- /dev/null +++ b/sys/man/2/venti-cache @@ -0,0 +1,246 @@ +.TH VENTI-CACHE 2 +.SH NAME +VtBlock, VtCache, +vtblockcopy, +vtblockdirty, +vtblockduplock, +vtblockput, +vtblockwrite, +vtcachealloc, +vtcacheallocblock, +vtcacheblocksize, +vtcachefree, +vtcacheglobal, +vtcachelocal, +vtcachesetwrite, +vtglobaltolocal, +vtlocaltoglobal \- Venti block cache +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLxxxx 'u +.PP +.ft L +.nf +typedef struct VtBlock +{ + uchar *data; + uchar type; + uchar score[VtScoreSize]; + u32int addr; + ... +} VtBlock; +.ta +\w'\fLVtBlock* 'u +\w'\fLxxxxxxxx'u +.PP +.B +VtCache* vtcachealloc(VtConn *z, int blocksize, ulong nblocks); +.PP +.B +void vtcachefree(VtCache *c); +.PP +.B +u32int vtcacheblocksize(VtCache *c); +.PP +.B +u32int vtglobaltolocal(uchar score[VtScoreSize]) +.br +.B +void vtlocaltoglobal(u32int local, uchar score[VtScoreSize]) +.PP +.B +VtBlock* vtcacheallocblock(VtCache *c, int type); +.PP +.B +VtBlock* vtcachelocal(VtCache *c, u32int addr, int type); +.PP +.B +VtBlock* vtcacheglobal(VtCache *c, uchar[VtScoreSize], int type); +.PP +.B +void vtblockput(VtBlock *b); +.PP +.B +void vtblockduplock(VtBlock *b); +.PP +.B +int vtblockwrite(VtBlock *b); +.PP +.B +void vtcachesetwrite(VtCache *c, +.br +.B + int (*write)(VtConn*, uchar[VtScoreSize], uint, uchar*, int)); +.PP +.B +VtBlock* vtblockcopy(VtBlock *b); +.PP +.B +int vtblockdirty(VtBlock *b); +.SH DESCRIPTION +These functions provide access to a simple in-memory +cache of blocks already stored on a Venti server +and blocks that will eventually be stored on a Venti server. +.PP +A +.B VtBlock +represents a venti data block. +Blocks stored on a venti server, +called +.IR "global blocks" , +are named by the SHA1 hash of their contents. +This hash is recorded as the block's +.IR score . +Such blocks are immutable. +The cache also stores mutable blocks that have not yet been +written to a venti server. These blocks are called +.IR "local blocks" , +and have special scores that are 16 zero bytes +followed by a 4-byte big-endian +.IR address . +The address is an index into the internal set of cache blocks. +.PP +The user-visible contents of a +.B VtBlock +are +.BR data , +a pointer to the data; +.BR type , +the venti block type; +.BR score , +the block's score; +and +.BR addr , +the block's cache address. +.PP +.I Vtcachealloc +allocates a new cache using the client connection +.I z +(see +.IR venti-conn (2) +and +.IR venti-client (2)), +with room for +.I nblocks +of maximum block size +.I blocksize . +.PP +.I Vtcachefree +frees a cache and all the associated blocks. +.PP +.I Vtcacheblocksize +returns the cache's maximum block size. +.PP +.I Vtglobaltolocal +returns the local address corresponding to the given +local +.IR score . +If passed a global score, +.I vtglobaltolocal +returns the special constant +.B NilBlock +.RB ( ~0 ). +.I Vtlocaltoglobal +is the opposite, setting +.I score +to the local score for the cache address +.IR local . +.PP +.I Vtcacheallocblock +allocates a new local block with the given +.IR type . +.PP +.I Vtcachelocal +retrieves the local block at address +.I addr +from the cache. +The given +.I type +must match the type of the block found at +.IR addr . +.PP +.I Vtcacheglobal +retrieves the block with the given +.I score +and +.I dtype +from the cache, consulting the Venti server +if necessary. +If passed a local score, +.I vtcacheglobal +invokes +.I vtcachelocal +appropriately. +.PP +The block references returned by +.IR vtcacheallocblock , +.IR vtcachelocal , +and +.I vtcacheglobal +must be released when no longer needed. +.I Vtblockput +releases such a reference. +.PP +It is occasionally convenient to have multiple variables +refer to the same block. +.I Vtblockduplock +increments the block's reference count so that +an extra +.I vtblockput +will be required in order to release the block. +.PP +.I Vtblockwrite +writes a local block to the Venti server, +changing the block to a global block. +It calls the cache's +.I write +function +to write the block to the server. +The default +.I write +function is +.I vtwrite +(see +.IR venti-client (2)); +.I vtsetcachewrite +sets it. +.I Vtsetcachewrite +is used by clients to install replacement functions +that run writes in the background or perform other +additional processing. +.PP +.I Vtblockcopy +copies a block in preparation for modifying its contents. +The old block may be a local or global block, +but the new block will be a local block. +.PP +The cache only evicts global blocks. +Local blocks can only leave the cache via +.IR vtblockwrite , +which turns them into global blocks, making them candidates for +eviction. +.PP +If a new cache block must be allocated (for +.IR vtcacheallocblock , +.IR vtcachelocal , +.IR vtcacheglobal , +or +.IR vtblockcopy ), +but the cache is filled (with local blocks and blocks that +have not yet been released with +.IR vtblockput ), +the library prints the score and reference count of +every block in the cache and then aborts. +A full cache indicates either that the cache is too small, +or, more commonly, that cache blocks are being leaked. +.SH SOURCE +.B /sys/src/libventi +.SH SEE ALSO +.IR venti (2), +.IR venti-client (2), +.IR venti-conn (2), +.IR venti-file (2), +.IR venti (6) diff --git a/sys/man/2/venti-client b/sys/man/2/venti-client new file mode 100755 index 000000000..a77f63ca2 --- /dev/null +++ b/sys/man/2/venti-client @@ -0,0 +1,190 @@ +.TH VENTI-CLIENT 2 +.SH NAME +vtconnect, vthello, vtread, vtwrite, vtreadpacket, vtwritepacket, vtsync, vtping, vtrpc, ventidoublechecksha1 \- Venti client +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLPacket* 'u +\w'\fLxxxxxxxx'u +.PP +.B +Packet* vtrpc(VtConn *z, Packet *p) +.PP +.B +int vthello(VtConn *z) +.PP +.B +int vtconnect(VtConn *z) +.PP +.B +int vtread(VtConn *z, uchar score[VtScoreSize], +.br +.B + uint type, uchar *buf, int n) +.PP +.B +int vtwrite(VtConn *z, uchar score[VtScoreSize], +.br +.B + uint type, uchar *buf, int n) +.PP +.B +Packet* vtreadpacket(VtConn *z, uchar score[VtScoreSize], +.br +.B + uint type, int n) +.PP +.B +int vtwritepacket(VtConn *z, uchar score[VtScoreSize], +.br +.B + uint type, Packet *p) +.PP +.B +int vtsync(VtConn *z) +.PP +.B +int vtping(VtConn *z) +.PP +.B +extern int ventidoublechecksha1; /* default 1 */ +.SH DESCRIPTION +These routines execute the client side of the +.IR venti (6) +protocol. +.PP +.I Vtrpc +executes a single Venti RPC transaction, sending the request +packet +.IR p +and then waiting for and returning the response packet. +.I Vtrpc +will set the tag in the packet. +.I Vtrpc +frees +.IR p , +even on error. +.I Vtrpc +is typically called only indirectly, via the functions below. +.PP +.I Vthello +executes a +.B hello +transaction, setting +.IB z ->sid +to the name used by the server. +.I Vthello +is typically called only indirectly, via +.IR vtconnect . +.PP +.I Vtconnect +calls +.I vtversion +(see +.IR venti-conn (2)) +and +.IR vthello , +in that order, returning success only +if both succeed. +This sequence (calling +.I vtversion +and then +.IR vthello ) +must be done before the functions below can be called. +.PP +.I Vtread +reads the block with the given +.I score +and +.I type +from the server, +stores the returned data +in memory at +.IR buf , +and returns the number of bytes read. +If the server's block has size larger than +.IR n , +.I vtread +does not modify +.I buf +and +returns an error. +.PP +.I Vtwrite +writes the +.I n +bytes in +.I buf +as a block of the given +.IR type , +setting +.IR score . +.PP +.I Vtreadpacket +and +.I vtwritepacket +are like +.I vtread +and +.I vtwrite +but return or accept the block contents in the +form of a +.BR Packet . +They avoid making a copy of the data. +.PP +.I Vtsync +causes the server to flush all pending write requests +to disk before returning. +.PP +.I Vtping +executes a ping transaction with the server. +.PP +By default, +.I vtread +and +.I vtreadpacket +check that the SHA1 hash of the returned data +matches the requested +.IR score , +and +.I vtwrite +and +.I vtwritepacket +check that the returned +.I score +matches the SHA1 hash of the written data. +Setting +.I ventidoublechecksha1 +to zero disables these extra checks, +mainly for benchmarking purposes. +Doing so in production code is not recommended. +.PP +These functions can be called from multiple threads +or procs simultaneously to issue requests +in parallel. +Programs that issue requests from multiple threads +in the same proc should start separate procs running +.I vtsendproc +and +.I vtrecvproc +as described in +.IR venti-conn (2). +.SH SOURCE +.B /sys/src/libventi +.SH SEE ALSO +.IR venti (2), +.IR venti-conn (2), +.IR venti-packet (2), +.IR venti (6) +.SH DIAGNOSTICS +.I Vtrpc +and +.I vtpacket +return nil on error. +The other routines return \-1 on error. +.PP +.I Vtwrite +returns 0 on success: there are no partial writes. diff --git a/sys/man/2/venti-conn b/sys/man/2/venti-conn new file mode 100755 index 000000000..3e3d2eea2 --- /dev/null +++ b/sys/man/2/venti-conn @@ -0,0 +1,200 @@ +.TH VENTI-CONN 2 +.SH NAME +VtConn, vtconn, vtdial, vtfreeconn, vtsend, vtrecv, vtversion, +vtdebug, vthangup \- Venti network connections +.SH SYNOPSIS +.PP +.ft L +#include +.br +#include +.br +#include +.PP +.ft L +.nf +.ta +\w'\fL 'u +typedef struct VtConn { + int debug; + char *version; + char *uid; + char *sid; + char addr[256]; + ... +} VtConn; +.PP +.ta \w'\fLextern int 'u +.B +VtConn* vtconn(int infd, int outfd) +.PP +.B +VtConn* vtdial(char *addr) +.PP +.B +int vtversion(VtConn *z) +.PP +.B +int vtsend(VtConn *z, Packet *p) +.PP +.B +Packet* vtrecv(VtConn *z) +.PP +.B +void vtrecvproc(void *z) +.PP +.B +void vtsendproc(void *z) +.PP +.B +void vtdebug(VtConn *z, char *fmt, ...) +.PP +.B +void vthangup(VtConn *z) +.PP +.B +void vtfreeconn(VtConn *z) +.PP +.B +extern int chattyventi; /* default 0 */ +.SH DESCRIPTION +A +.B VtConn +structure represents a connection to a Venti server +(when used by a client) or to a client (when used by a server). +It contains the following user-visible fields: +.BR debug , +a flag enabling debugging prints; +.BR version , +the protocol version in use; +.BR uid , +the (unverified) name of the client; +.BR sid , +the (unverified) name of the server; +and +.BR addr , +the network address of the remote side. +.PP +.I Vtconn +initializes a new connection structure using file descriptors +.I infd +and +.I outfd +(which may be the same) +for reading and writing. +.I Vtdial +dials the given network address +(see +.IR dial (2)) +and returns a corresponding connection. +It returns nil if the connection cannot be established. +.PP +.I Vtversion +exchanges version information with the remote side +as described in +.IR venti (6). +The negotiated version is stored in +.IB z ->version \fR. +.PP +.I Vtsend +writes a packet +(see +.IR venti-packet (2)) +on the connection +.IR z . +The packet +.IR p +should be a formatted Venti message as might +be returned by +.IR vtfcallpack ; +.I vtsend +will add the two-byte length field +(see +.IR venti (6)) +at the begnning. +.I Vtsend +frees +.IR p , +even on error. +.PP +.I Vtrecv +reads a packet from the connection +.IR z . +Analogous to +.IR vtsend , +the data read from the connection must start with +a two-byte length, but the returned packet will omit them. +.PP +By default, +.I vtsend +and +.I vtrecv +block until the packet can be written or read from the network. +In a threaded program +(see +.IR thread (2)), +this may not be desirable. +If the caller arranges for +.IR vtsendproc +and +.IR vtrecvproc +to run in their own procs +(typically by calling +.IR proccreate ), +then +.I vtsend +and +.I vtrecv +will yield the proc in which they are run +to other threads when waiting on the network. +The +.B void* +argument to +.I vtsendproc +and +.I vtrecvproc +must be the connection structure +.IR z . +.PP +.I Vtdebug +prints the formatted message to standard error +when +.IB z ->debug +is set. Otherwise it is a no-op. +.PP +.I Vthangup +hangs up a connection. +It closes the associated file descriptors +and shuts down send and receive procs if they have been +started. +Future calls to +.IR vtrecv +or +.IR vtsend +will return errors. +Additional calls to +.I vthangup +will have no effect. +.PP +.I Vtfreeconn +frees the connection structure, hanging it up first +if necessary. +.PP +If the global variable +.I chattyventi +is set, the library prints all Venti RPCs to standard error +as they are sent or received. +.SH SOURCE +.B /sys/src/libventi +.SH SEE ALSO +.IR venti (1), +.IR venti (2), +.IR venti-client (2), +.IR venti-packet (2), +.IR venti-server (2), +.IR venti (6) +.SH DIAGNOSTICS +Routines that return pointers return nil on error. +Routines returning integers return 0 on success, \-1 on error. +All routines set +.I errstr +on error. diff --git a/sys/man/2/venti-fcall b/sys/man/2/venti-fcall new file mode 100755 index 000000000..148e49cdd --- /dev/null +++ b/sys/man/2/venti-fcall @@ -0,0 +1,275 @@ +.TH VENTI-FCALL 2 +.SH NAME +VtEntry, VtFcall, VtRoot, +vtentrypack, +vtentryunpack, +vtfcallclear, +vtfcallfmt, +vtfcallpack, +vtfcallunpack, +vtfromdisktype, +vttodisktype, +vtgetstring, +vtputstring, +vtrootpack, +vtrootunpack, +vtparsescore, +vtscorefmt \- venti data formats +.SH SYNOPSIS +.PP +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLxxxx'u +.PP +.ft L +.nf +enum +{ + VtEntrySize = 40, + VtRootSize = 300, + VtScoreSize = 20, +}; +.PP +.ft L +.nf +typedef struct VtEntry +{ + ulong gen; /* generation number */ + ushort psize; /* pointer block size */ + ushort dsize; /* data block size */ + uchar type; + uchar flags; + uvlong size; + uchar score[VtScoreSize]; +} VtEntry; +.PP +.ft L +.nf +typedef struct VtRoot +{ + char name[128]; + char type[128]; + uchar score[VtScoreSize]; /* to a Dir block */ + ushort blocksize; /* maximum block size */ + uchar prev[VtScoreSize]; /* previous root block */ +} VtRoot; +.ta +\w'\fLPacket* 'u +.PP +.B +void vtentrypack(VtEntry *e, uchar *buf, int index) +.br +.B +int vtentryunpack(VtEntry *e, uchar *buf, int index) +.PP +.B +Packet* vtfcallpack(VtFcall *f) +.br +.B +int vtfcallunpack(VtFcall *f, Packet *p) +.PP +.B +void vtfcallclear(VtFcall *f) +.PP +.B +uint vttodisktype(uint type) +.br +.B +uint vtfromdisktype(uint type) +.PP +.B +int vtputstring(Packet *p, char *s) +.br +.B +int vtgetstring(Packet *p, char **s) +.PP +.B +void vtrootpack(VtRoot *r, uchar *buf) +.br +.B +int vtrootunpack(VtRoot *r, uchar *buf) +.PP +.B +int vtparsescore(char *s, char **prefix, uchar score[VtScoreSize]) +.PP +.B +int vtfcallfmt(Fmt *fmt) +.B +int vtscorefmt(Fmt *fmt) +.SH DESCRIPTION +These routines convert between C representations of Venti +structures and serialized representations used on disk and +on the network. +.PP +.I Vtentrypack +converts a +.B VtEntry +structure describing a Venti file +(see +.IR venti (6)) +into a 40-byte +.RB ( VtEntrySize ) +structure at +.IB buf + index *40 \fR. +Vtentryunpack +does the reverse conversion. +.PP +.I Vtfcallpack +converts a +.B VtFcall +structure describing a Venti protocol message +(see +.IR venti (6)) +into a packet. +.I Vtfcallunpack +does the reverse conversion. +.PP +The fields in a +.B VtFcall +are named after the protocol fields described in +.IR venti (6), +except that the +.B type +field is renamed +.BR blocktype . +The +.B msgtype +field holds the one-byte message type: +.BR VtThello , +.BR VtRhello , +and so on. +.PP +.I Vtfcallclear +frees the strings +.IB f ->error \fR, +.IB f ->version \fR, +.IB f ->uid \fR, +.IB f ->sid \fR, +the buffers +.IB f ->crypto +and +.IB f ->codec \fR, +and the packet +.IB f ->data \fR. +.PP +The block type enumeration defined in +.B +(presented in +.IR venti (6)) +differs from the one used on disk and in the network +protocol. +The disk and network representation uses different +constants and does not distinguish between +.BI VtDataType+ n +and +.BI VtDirType+ n +blocks. +.I Vttodisktype +converts a +.B +enumeration value to the disk value; +.I vtfromdisktype +converts a disk value to the enumeration value, +always using the +.B VtDirType +pointers. +The +.B VtFcall +field +.B blocktype +is an enumeration value +.RI ( vtfcallpack +and +.I vtfcallunpack +convert to and from the disk values used in packets +automatically), +so most programs will not need to call these functions. +.PP +.I Vtputstring +appends the Venti protocol representation of the string +.I s +to the packet +.IR p . +.I Vtgetstring +reads a string from the packet, returning a pointer to a copy +of the string in +.BI * s \fR. +The copy must be freed by the caller. +These functions are used by +.I vtfcallpack +and +.IR vtfcallunpack ; +most programs will not need to call them directly. +.PP +.I Vtrootpack +converts a +.B VtRoot +structure describing a Venti file tree +into the 300-byte +.RB ( VtRootSize ) +buffer pointed to by +.IR buf . +.I Vtrootunpack does the reverse conversion. +.PP +.I Vtparsescore +parses the 40-digit hexadecimal string +.IR s , +writing its value +into +.IR score . +If the hexadecimal string is prefixed with +a text label followed by a colon, a copy of that +label is returned in +.BI * prefix \fR. +If +.I prefix +is nil, the label is ignored. +.PP +.I Vtfcallfmt +and +.I vtscorefmt +are +.IR print (2) +formatters to print +.B VtFcall +structures and scores. +.I Vtfcallfmt +assumes that +.I vtscorefmt +is installed as +.BR %V . +.SH SOURCE +.B /sys/src/libventi +.SH SEE ALSO +.IR venti (1), +.IR venti (2), +.IR venti (6) +.SH DIAGNOSTICS +.IR Vtentrypack , +.IR vtfcallpack , +.IR vtrootpack , +and +.I vtfcallclear +cannot fail. +.PP +.IR Vtentryunpack , +.IR vtrootunpack , +.IR vtputstring , +.IR vtgetstring , +and +.I vtparsescore +return 0 on success, \-1 on error. +.PP +.I Vtfcallpack +returns a packet on success, nil on error. +.PP +.I Vttodisktype +and +.I vtfromdisktype +return +.B VtCorruptType +(255) +when presented with invalid input. diff --git a/sys/man/2/venti-file b/sys/man/2/venti-file new file mode 100755 index 000000000..ab5f4d8c7 --- /dev/null +++ b/sys/man/2/venti-file @@ -0,0 +1,325 @@ +.TH VENTI-FILE 2 +.SH NAME +VtFile, +vtfileblock, +vtfileblockscore, +vtfileclose, +vtfilecreate, +vtfilecreateroot, +vtfileflush, +vtfileflushbefore, +vtfilegetdirsize, +vtfilegetentry, +vtfilegetsize, +vtfileincref, +vtfilelock, +vtfilelock2, +vtfileopen, +vtfileopenroot, +vtfileread, +vtfileremove, +vtfilesetdirsize, +vtfilesetentry, +vtfilesetsize, +vtfiletruncate, +vtfileunlock, +vtfilewrite \- Venti files +.SH SYNOPSIS +.ta +\w'\fLVtBlock* 'u +.PP +.B +VtFile* vtfilecreateroot(VtCache *c, int psize, int dsize, int type); +.PP +.B +VtFile* vtfileopenroot(VtCache *c, VtEntry *e); +.PP +.B +VtFile* vtfileopen(VtFile *f, u32int n, int mode); +.PP +.B +VtFile* vtfilecreate(VtFile *f, int psize, int dsize, int type); +.PP +.B +void vtfileincref(VtFile *f); +.PP +.B +void vtfileclose(VtFile *f); +.PP +.B +int vtfileremove(VtFile *f); +.PP +.B +VtBlock* vtfileblock(VtFile *f, u32int n, int mode); +.PP +.B +long vtfileread(VtFile *f, void *buf, long n, vlong offset); +.PP +.B +long vtfilewrite(VtFile *f, void *buf, long n, vlong offset); +.PP +.B +int vtfileflush(VtFile *f); +.PP +.B +int vtfileflushbefore(VtFile *f, vlong offset); +.PP +.B +int vtfiletruncate(VtFile *f); +.PP +.B +uvlong vtfilegetsize(VtFile *f); +.PP +.B +int vtfilesetsize(VtFile *f, vlong size); +.PP +.B +u32int vtfilegetdirsize(VtFile *f); +.PP +.B +int vtfilesetdirsize(VtFile *f, u32int size); +.PP +.B +int vtfilegetentry(VtFile *f, VtEntry *e); +.PP +.B +int vtfilesetentry(VtFile *f, VtEntry *e); +.PP +.B +int vtfileblockscore(VtFile *f, u32int n, + uchar score[VtScoreSize]); +.PP +.B +int vtfilelock(VtFile *f, int mode); +.PP +.B +int vtfilelock2(VtFile *f, VtFile *f, int mode); +.PP +.B +void vtfileunlock(VtFile *f); +.SH DESCRIPTION +These routines provide a simple interface to create and +manipulate Venti file trees (see +.IR venti (6)). +.PP +.I Vtfilecreateroot +creates a new Venti file. +.I Type +must be either +.B VtDataType +or +.BR VtDirType , +specifying a data or directory file. +.I Dsize +is the block size to use for leaf (data or directory) blocks in the hash tree; +.I psize +is the block size to use for internal (pointer) blocks. +.PP +.I Vtfileopenroot +opens an existing Venti file described by +.IR e . +.PP +.I Vtfileopen +opens the Venti file described by the +.IR n th +entry in the directory +.IR f . +.I Mode +should be one of +.BR VtOREAD , +.BR VtOWRITE , +or +.BR VtORDWR , +indicating how the returned file is to be used. +The +.BR VtOWRITE +and +.BR VtORDWR +modes can only be used if +.IR f +is open with mode +.BR VtORDWR . +.PP +.I Vtfilecreate +creates a new file in the directory +.I f +with block type +.I type +and block sizes +.I dsize +and +.I psize +(see +.I vtfilecreateroot +above). +.PP +Each file has an associated reference count +and holds a reference to its parent in the file tree. +.I Vtfileincref +increments this reference count. +.I Vtfileclose +decrements the reference count. +If there are no other references, +.I vtfileclose +releases the reference to +.IR f 's +parent and then frees the in-memory structure +.IR f . +The data stored in +.I f +is still accessible by reopening it. +.PP +.I Vtfileremove +removes the file +.I f +from its parent directory. +It also acts as +.IR vtfileclose , +releasing the reference to +.I f +and potentially freeing the structure. +.PP +.I Vtfileblock +returns the +.IR n th +block in the file +.IR f . +If there are not +.I n +blocks in the file and +.I mode +is +.BR VtOREAD , +.I vtfileblock +returns nil. +If the mode is +.B VtOWRITE +or +.BR VtORDWR , +.I vtfileblock +grows the file as needed and then returns the block. +.PP +.I Vtfileread +reads at most +.I n +bytes at offset +.I offset +from +.I f +into memory at +.IR buf . +It returns the number of bytes read. +.PP +.I Vtfilewrite +writes the +.I n +bytes in memory at +.I buf +into the file +.I f +at offset +.IR n . +It returns the number of bytes written, +or \-1 on error. +Writing fewer bytes than requested will only happen +if an error is encountered. +.PP +.I Vtfilewrite +writes to an in-memory copy of the data blocks +(see +.IR venti-cache (2)) +instead of writing directly to Venti. +.I Vtfileflush +writes all copied blocks associated with +.I f +to the Venti server. +.I Vtfileflushbefore +flushes only those blocks corresponding to data in the file before +byte +.IR offset . +Loops that +.I vtfilewrite +should call +.I vtfileflushbefore +regularly to avoid filling the block cache with unwritten blocks. +.PP +.I Vtfiletruncate +changes the file +.I f +to have zero length. +.PP +.I Vtfilegetsize +returns the length (in bytes) of file +.IR f . +.PP +.I Vtfilesetsize +sets the length (in bytes) of file +.IR f . +.PP +.I Vtfilegetdirsize +returns the length (in directory entries) +of the directory +.IR f . +.PP +.I Vtfilesetdirsize +sets the length (in directory entries) +of the directory +.IR f . +.PP +.I Vtfilegetentry +fills +.I e +with an entry that can be passed to +.IR vtfileopenroot +to reopen +.I f +at a later time. +.PP +.I Vtfilesetentry +sets the entry associated with +.I f +to be +.IR e . +.PP +.I Vtfileblockscore +returns in +.I score +the score of the +.IR n th +block in the file +.IR f . +.PP +Venti files are locked and unlocked +via +.I vtfilelock +and +.I vtfileunlock +to moderate concurrent access. +Only one thread at a time\(emthe one that has the file locked\(emcan +read or modify the file. +The functions that return files +.RI ( vtfilecreateroot , +.IR vtfileopenroot , +.IR vtfilecreate , +and +.IR vtfileopen ) +return them unlocked. +When files are passed to any of the functions documented in +this manual page, it is the caller's responsibility to ensure that +they are already locked. +.PP +Internally, a file is locked by locking the +block that contains its directory entry. +When two files in the same +directory both need to be locked, +.I vtfilelock2 +must be used. +It locks both its arguments, taking special care +not to deadlock if their entries are stored +in the same directory block. +.SH SOURCE +.B /sys/src/libventi/file.c +.SH SEE ALSO +.IR venti-cache (2), +.IR venti-conn (2), +.IR venti-client (2), +.IR venti (6) diff --git a/sys/man/2/venti-log b/sys/man/2/venti-log new file mode 100755 index 000000000..a8763202c --- /dev/null +++ b/sys/man/2/venti-log @@ -0,0 +1,136 @@ +.TH VENTI-LOG 2 +.SH NAME +VtLog, +VtLogChunk, +vtlog, +vtlogclose, +vtlogdump, +vtlognames, +vtlogopen, +vtlogprint, +vtlogremove, +vtlogopen, +ventilogging \- Venti logs +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLVtLog* 'u +.PP +.B +VtLog* vtlogopen(char *name, uint size); +.PP +.B +void vtlogprint(VtLog *log, char *fmt, ...); +.PP +.B +void vtlogclose(VtLog *log); +.PP +.B +void vtlog(char *name, char *fmt, ...); +.PP +.B +void vtlogremove(char *name); +.PP +.B +char** vtlognames(int *n); +.PP +.B +void vtlogdump(int fd, VtLog *log); +.PP +.B +extern int ventilogging; /* default 0 */ +.PP +.B +extern char *VtServerLog; /* "libventi/server" */ +.SH DESCRIPTION +These routines provide an in-memory circular log +structure used by the Venti library and the Venti server +to record events for debugging purposes. +The logs are named by UTF strings. +.PP +.I Vtlogopen +returns a reference to the log with the given +.I name . +If a log with that name does not exist and +.I size +is non-zero, +.I vtlogopen +creates a new log capable of holding at +least +.I size +bytes and returns it. +.I Vtlogclose +releases the reference returned by +.IR vtlogopen . +.PP +.I Vtlogprint +writes to +.IR log , +which must be open. +.PP +.I Vtlog +is a convenient packaging of +.I vtlogopen +followed by +.I vtlogprint +and +.IR vtlogclose . +.PP +.I Vtlogremove +removes the log with the given +.IR name , +freeing any associated storage. +.PP +.I Vtlognames +returns a list of the names of all the logs. +The length of the list is returned in +.BI * n \fR. +The list +should be freed +by calling +.I vtfree +on the returned pointer. +The strings in the list will be freed by this call as well. +(It is an error to call +.I vtfree +on any of the strings in the list.) +.PP +.I Vtlogdump +prints +.IR log , +which must be open, to the file descriptor +.IR fd . +.PP +If +.I ventilogging +is set to zero (the default), +.I vtlognames +and +.I vtlogdump +can inspect existing logs, but +.I vtlogopen +always returns nil +and +.I vtlog +is a no-op. +The other functions are no-ops when +passed nil log structures. +.PP +The server library +(see +.IR venti-conn (2) +and +.IR venti-server (2)) +writes debugging information to the log named +.IR VtServerLog , +which defaults to the string +.RB ` libventi/server '. +.SH SOURCE +.B /sys/src/libventi +.SH SEE ALSO +.IR venti (2), +.IR venti (8) diff --git a/sys/man/2/venti-mem b/sys/man/2/venti-mem new file mode 100755 index 000000000..8544807c1 --- /dev/null +++ b/sys/man/2/venti-mem @@ -0,0 +1,68 @@ +.TH VENTI-MEM 2 +.SH NAME +vtbrk, +vtmalloc, +vtmallocz, +vtrealloc, +vtstrdup, +vtfree \- error-checking memory allocators +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLvoid* 'u +.PP +.B +void* vtbrk(int size) +.PP +.B +void* vtmalloc(int size) +.PP +.B +void* vtmallocz(int size) +.PP +.B +void* vtrealloc(void *ptr, int size) +.PP +.B +char* vtstrdup(char *s) +.PP +.B +void vtfree(void *ptr) +.SH DESCRIPTION +These routines allocate and free memory. +On failure, they print an error message and call +.IR sysfatal +(from +.IR perror (2)). +They do not return. +.PP +.I Vtbrk +returns a pointer to a new, permanently allocated block of at least +.I size +bytes. +.PP +.IR Vtmalloc , +.IR vtrealloc , +and +.I vtstrdup +are like +.IR malloc , +.IR realloc , +and +.IR strdup , +but, as noted above, do not return on error. +.I Vtmallocz +is like +.I vtmalloc +but zeros the block before returning it. +Memory allocated with all four should be freed with +.I vtfree +when no longer needed. +.SH SOURCE +.B /sys/src/libventi +.SH SEE ALSO +.IR venti (2) diff --git a/sys/man/2/venti-packet b/sys/man/2/venti-packet new file mode 100755 index 000000000..53ada1eea --- /dev/null +++ b/sys/man/2/venti-packet @@ -0,0 +1,281 @@ +.TH VENTI-PACKET 2 +.SH NAME +Packet, +packetalloc, +packetappend, +packetasize, +packetcmp, +packetconcat, +packetconsume, +packetcopy, +packetdup, +packetforeign, +packetfragments, +packetfree, +packetheader, +packetpeek, +packetprefix, +packetsha1, +packetsize, +packetsplit, +packetstats, +packettrailer, +packettrim \- zero-copy network buffers +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLPacket* 'u +\w'\fLxxxx'u +.PP +.B +.PP +.B +Packet* packetalloc(void); +.PP +.B +void packetappend(Packet *p, uchar *buf, int n) +.PP +.B +uint packetasize(Packet *p) +.PP +.B +int packetcmp(Packet *p, Packet *q) +.PP +.B +void packetconcat(Packet *p, Packet *q) +.PP +.B +int packetconsume(Packet *p, uchar *buf, int n) +.PP +.B +int packetcopy(Packet *p, uchar *buf, int offset, int n) +.PP +.B +Packet* packetdup(Packet *p, int offset, int n) +.PP +.B +Packet* packetforeign(uchar *buf, int n, +.br +.B + void (*free)(void *a), void *a) +.PP +.B +int packetfragments(Packet *p, IOchunk *io, int nio, +.br +.B + int offset) +.PP +.B +void packetfree(Packet *p) +.PP +.B +uchar* packetheader(Packet *p, int n) +.PP +.B +uchar* packetpeek(Packet *p, uchar *buf, int offset, int n) +.PP +.B +void packetprefix(Packet *p, uchar *buf, int n) +.PP +.B +void packetsha1(Packet *p, uchar sha1[20]) +.PP +.B +uint packetsize(Packet *p) +.PP +.B +Packet* packetsplit(Packet *p, int n) +.PP +.B +void packetstats(void) +.PP +.B +uchar* packettrailer(Packet *p, int n) +.PP +.B +int packettrim(Packet *p, int offset, int n) +.SH DESCRIPTION +A +.B Packet +is a chain of blocks of data. +Each block, called a fragment, +is contiguous in memory, but the entire packet +may not be. +This representation helps avoid unnecessary memory copies. +.PP +.I Packetalloc +allocates an empty packet. +.PP +.I Packetappend +appends the +.I n +bytes at +.I buf +to the end of +.IR p . +.PP +.I Packetasize +returns the number of data bytes allocated to +.IR p . +This may be larger than the number of bytes stored +in +.IR p +because fragments may not be filled completely. +.PP +.I Packetcmp +compares the data sections of two packets as +.I memcmp +(see +.IR memory (2)) +would. +.PP +.I Packetconcat +removes all data from +.IR q , +appending it to +.IR p . +.PP +.I Packetconsume +removes +.I n +bytes from the beginning of +.IR p , +storing them into +.IR buf . +.PP +.I Packetcopy +copies +.I n +bytes at +.I offset +in +.I p +to +.IR buf . +.PP +.I Packetdup +creates a new packet initialized with +.I n +bytes from +.I offset +in +.IR p . +.PP +.I Packetforeign +allocates a packet containing `foreign' data: the +.I n +bytes pointed to by +.IR buf . +Once the bytes are no longer needed, they are freed by calling +.IB free ( a )\fR. +.PP +.I Packetfragments +initializes up to +.I nio +of the +.I io +structures with pointers to the data in +.IR p , +starting at +.IR offset . +It returns the total number of bytes represented +by the returned structures. +.I Packetfragments +initializes any unused +.I io +structures with nil pointer and zero length. +.PP +.I Packetfree +frees the packet +.IR p . +.PP +.I Packetheader +returns a pointer to the first +.I n +bytes of +.IR p , +making them contiguous in memory +if necessary. +.PP +.I Packetpeek +returns a pointer to the +.I n +bytes at +.I offset +in +.IR p . +If the requested bytes are already stored contiguously in memory, +the returned pointer points at the internal data storage for +.IR p . +Otherwise, the bytes are copied into +.IR buf , +and +.I packetpeek +returns +.IR buf . +.PP +.I Packetprefix +inserts a copy of the +.I n +bytes at +.I buf +at the beginning of +.IR p . +.PP +.I Packetsha1 +computes the SHA1 hash of the data contained in +.IR p . +.PP +.I Packetsize +returns the length, in bytes, of the data contained in +.IR p . +.PP +.I Packetsplit +returns a new packet initialized with +.I n +bytes removed from the beginning of +.IR p . +.PP +.I Packetstats +prints run-time statistics to standard output. +.PP +.I Packettrailer +returns a pointer to the last +.I n +bytes of +.IR p , +making them contiguous in memory +if necessary. +.PP +.I Packettrim +deletes all bytes from the packet +.I p +except the +.I n +bytes at offset +.IR offset . +.SH SOURCE +.B /sys/src/libventi +.SH SEE ALSO +.IR venti (2) +.SH DIAGNOSTICS +These functions return errors only when passed +invalid inputs, +.IR e.g. , +requests for data at negative offsets or beyond the end of a packet. +.PP +Functions returning pointers return nil on error; +functions returning integers return \-1 on error. +Most functions returning integers return 0 on success. +The exceptions are +.I packetfragments +and +.IR packetcmp , +whose return values are described above. +.PP +When these functions run out of memory, they +print error messages and call +.IR sysfatal . diff --git a/sys/man/2/venti-server b/sys/man/2/venti-server new file mode 100755 index 000000000..cd62381ca --- /dev/null +++ b/sys/man/2/venti-server @@ -0,0 +1,122 @@ +.TH VENTI-SERVER 2 +.SH NAME +vtsrvhello, vtlisten, vtgetreq, vtrespond \- Venti server +.SH SYNOPSIS +.PP +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLVtReq* 'u +.PP +.ft L +.nf +typedef struct VtReq +{ + VtFcall tx; + VtFcall rx; + ... +} VtReq; +.PP +.B +int vtsrvhello(VtConn *z) +.PP +.B +VtSrv* vtlisten(char *addr) +.PP +.B +VtReq* vtgetreq(VtSrv *srv) +.PP +.B +void vtrespond(VtReq *req) +.SH DESCRIPTION +These routines execute the server side of the +.IR venti (6) +protocol. +.PP +.I Vtsrvhello +executes the server side of the initial +.B hello +transaction. +It sets +.IB z -> uid +with the user name claimed by the other side. +Each new connection must be initialized by running +.I vtversion +and then +.IR vtsrvhello . +The framework below takes care of this detail automatically; +.I vtsrvhello +is provided for programs that do not use the functions below. +.PP +.IR Vtlisten , +.IR vtgetreq , +and +.I vtrespond +provide a simple framework for writing Venti servers. +.PP +.I Vtlisten +announces at the network address +.IR addr , +returning a fresh +.B VtSrv +structure representing the service. +.PP +.I Vtgetreq +waits for and returns +the next +.BR read , +.BR write , +.BR sync , +or +.B ping +request from any client connected to +the service +.IR srv . +.B Hello +and +.B goodbye +messages are handled internally and not returned to the client. +The interface does not distinguish between the +different clients that may be connected at any given time. +The request can be found in the +.I tx +field of the returned +.BR VtReq . +.PP +Once a request has been served and a response stored in +.IB r ->rx \fR, +the server should call +.IR vtrespond +to send the response to the client. +.I Vtrespond +frees the structure +.I r +as well as the packets +.IB r ->tx.data +and +.IB r ->rx.data \fR. +.SH EXAMPLE +.B /sys/src/cmd/venti +contains two simple Venti servers +.B ro.c +and +.B devnull.c +written using these routines. +.I Ro +is a read-only Venti proxy (it rejects +.B write +requests). +.I Devnull +is a dangerous write-only Venti server: it discards all +blocks written to it and returns error on all reads. +.SH SOURCE +.B /sys/src/libventi +.SH SEE ALSO +.IR venti (2), +.IR venti-conn (2), +.IR venti-packet (2), +.IR venti (6), +.IR venti (8) diff --git a/sys/man/2/venti-zero b/sys/man/2/venti-zero new file mode 100755 index 000000000..b0b810bcf --- /dev/null +++ b/sys/man/2/venti-zero @@ -0,0 +1,56 @@ +.TH VENTI-ZERO 2 +.SH NAME +vtzerotruncate, vtzeroextend, vtzeroscore \- Venti block truncation +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLuint 'u +.PP +.B +uint vtzerotruncate(int type, uchar *buf, uint size) +.PP +.B +void vtzeroextend(int type, uchar *buf, uint size, uint newsize) +.PP +.B +extern uchar vtzeroscore[VtScoreSize]; +.SH DESCRIPTION +These utility functions compute how to truncate or replace +trailing zeros (for data blocks) or trailing zero scores +(for pointer blocks) to canonicalize the blocks before +storing them to Venti. +.PP +.I Vtzerotruncate +returns the size of the +.IR size -byte +buffer pointed to by +.I buf +ignoring trailing zeros or zero scores, +according to the given +.IR type . +.PP +.I Vtzeroextend +pads +.I buf +with zeros or zero scores, +according to the given +.IR type , +to grow it from +.I size +bytes to +.I newsize +bytes. +.PP +.I Vtzeroscore +is the score of the zero-length block. +.SH SOURCE +.B /sys/src/libventi/zero.c +.br +.B /sys/src/libventi/zeroscore.c +.SH SEE ALSO +.IR venti (2), +.IR venti (6) diff --git a/sys/man/2/wait b/sys/man/2/wait new file mode 100755 index 000000000..b6d34fba9 --- /dev/null +++ b/sys/man/2/wait @@ -0,0 +1,122 @@ +.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. +.PP +If the calling process has no living children, +.I await +and +.I waitpid +return +.BR -1 . +.SH SOURCE +.B /sys/src/libc/9syscall +.br +.B /sys/src/libc/9sys +.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/sys/man/2/window b/sys/man/2/window new file mode 100755 index 000000000..5fe2b2bfe --- /dev/null +++ b/sys/man/2/window @@ -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/sys/man/3/0intro b/sys/man/3/0intro new file mode 100755 index 000000000..a1b301930 --- /dev/null +++ b/sys/man/3/0intro @@ -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/sys/man/3/INDEX b/sys/man/3/INDEX new file mode 100755 index 000000000..2197ada97 --- /dev/null +++ b/sys/man/3/INDEX @@ -0,0 +1,50 @@ +0intro 0intro +intro 0intro +aoe aoe +apm apm +arch arch +audio audio +bridge bridge +cap cap +cons cons +draw draw +dup dup +env env +ether ether +flash flash +floppy floppy +fs fs +i82365 i82365 +esp ip +gre ip +icmp ip +icmpv6 ip +ip ip +ipmux ip +rudp ip +tcp ip +udp ip +kbin kbin +kbmap kbmap +kprof kprof +loopback loopback +lpt lpt +mnt mnt +cursor mouse +mouse mouse +pipe pipe +pnp pnp +proc proc +root root +rtc rtc +sd sd +sdahci sdahci +sdaoe sdaoe +segment segment +srv srv +ssl ssl +tls tls +eia uart +uart uart +usb usb +vga vga diff --git a/sys/man/3/INDEX.html b/sys/man/3/INDEX.html new file mode 100755 index 000000000..31f6b0b75 --- /dev/null +++ b/sys/man/3/INDEX.html @@ -0,0 +1,165 @@ + +plan 9 man section 3 + + +[manual index] +

Plan 9 from Bell Labs - Section 3 - Devices

+
+
+
0intro +- introduction to the Plan 9 devices +
intro + +
aoe +- ATA-over-Ethernet (AoE) interface +
aoe + +
apm +- Advanced Power Management 1.2 BIOS interface +
apm + +
arch +- architecture-specific information and control +
arch + +
audio +- SoundBlaster or ESS1688 audio controller +
audio + +
bridge +- IPv4 Ethernet bridge +
bridge + +
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 + +
flash +- flash memory +
flash + +
floppy +- floppy disk interface +
floppy + +
fs +- file system devices +
fs + +
i82365 +- Personal Computer Memory Card Interface Association (PCMCIA) device +
i82365 + +
ip +- network protocols over IP +
ip, esp, gre, icmp, icmpv6, ipmux, rudp, tcp, udp + +
kbin +- external keyboard input +
kbin + +
kbmap +- keyboard map +
kbmap + +
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 + +
root +- the root file system +
root + +
rtc +- real-time clock and non-volatile RAM +
rtc + +
sd +- storage device interface +
sd + +
sdahci +- AHCI (Advanced Host Controller Interface) SATA (Serial ATA) storage device drivers +
sdahci + +
sdaoe +- ATA-over-Ethernet (AoE) storage device interface +
sdaoe + +
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/sys/man/3/aoe b/sys/man/3/aoe new file mode 100755 index 000000000..d6ae374f3 --- /dev/null +++ b/sys/man/3/aoe @@ -0,0 +1,290 @@ +.TH AOE 3 +.SH NAME +aoe \- ATA-over-Ethernet (AoE) interface +.SH SYNOPSIS +.nf +.B bind -a #æ /dev +.sp 0.3v +.B /dev/aoe/ctl +.B /dev/aoe/log +.BI /dev/aoe/ shelf . slot /config +.BI /dev/aoe/ shelf . slot /ctl +.BI /dev/aoe/ shelf . slot /devlink/0 +\&... +.BI /dev/aoe/ shelf . slot /devlink/ i +.BI /dev/aoe/ shelf . slot /ident +\&... +.fi +.SH DESCRIPTION +The AoE (ATA-over-Ethernet) interface serves a three-level +directory providing control and access to AoE targets. +The interface provided is primarily intended for low-level +control of the AoE initiator. See +.IR sdaoe (3) +for the standard interface. +.SS Top-level files +In order to access AoE targets, one or more Ethernet controllers +need to be bound to the AoE initiator. By default, the system +starts with no interfaces bound. For automatic binding of interfaces +on boot, the +.B aoeif +configuration variable is set in +.IR plan9.ini (8). +Ethernet interfaces are specified as +.BI ether n\fR, +not as +.BI #l n\fR. +To bind the first and second Ethernet devices on boot, add +.IP +.EX +aoeif=ether0 ether1 +.EE +.PP +To bind +.B ether1 +to a running system: +.IP +.EX +% echo bind '#l1/ether1' >/dev/aoe/ctl +.EE +.PP +And to unbind it +.IP +.EX +% echo unbind '#l1/ether1' >/dev/aoe/ctl +.EE +.PP +When an interface is unbound, targets depending +on that interface are removed. +.PP +Each local interface is called a +.IR netlink . +The mapping of +AoE targets to netlinks is called a +.IR devlink . +Each devlink may +see multiple interfaces per target. +For example, if the local +machine has one Ethernet address bound and the target has +two interfaces on the same Ethernet segment, this will result +in one netlink and one devlink with two Ethernet addresses. +AoE frames are sent in round-robin fashion. +Each successive +frame is sent on the next address available on the next available +devlink (local interface). +.PP +Normally the initiator automatically discovers and adds new +device directories on startup. New devices are not added +except as new interfaces are bound to the initiator. +Several messages can be written to +.B /dev/aoe/ctl +which alter this behavior: +.TP +.BI autodiscover\ toggle +If toggle is absent, +the state of +.B autodiscover +is toggled. If it is the string +.BR on , +it is turned on. Any other string turns +.B autodisover +off. +This option is not useful after Ethernet devices have been bound. +.TP +.BI discover\ shelf.slot +Attempt to find the named target on all bound interfaces. +.TP +.BI remove\ shelf.slot +The converse of +.BR discover : +remove the named target if it exists. +.TP +.BI rediscover\ toggle +Allow or disallow rediscovery. +This allows for automatic discovery of new targets. +Unfortunately, it also allows automatic modification +or loss of existing targets. This option is considered dangerous. +.br +.ne 4 +.PP +Reading +.B /dev/aoe/ctl +returns a list of colon-separated lines +with keywords and their values: +.TF rediscover +.PD +.TP +.BI debug +.PD 0 +.TP +.BI autodiscover +.TP +.B rediscover +Returns the current state of the variable named by the keyword. +Writing the variable's +name to the control file toggles the state of that variable. +.PD +.TP +.BI if "n path" +Path to +.IR n th +bound Ethernet device. +.TP +.BI if "n ea" +Ethernet address of this device. +.TP +.BI if "n flag" +A flag of ``Up'' indicates that this interface is available. +.TP +.BI if "n lostjumbo" +Number of consecutive lost jumbograms. +.TP +.BI if "n datamtu" +Incorrect and unused. +.SS Shelf-and-slot subdirectories +Once configured, each AoE target is accessed via files in the directory named +for its shelf and slot. For example, shelf 42, slot 0 would be +accessed through the path +.LR /dev/aoe/42.0 . +The +.B ident +file contains the read-only, verbatim result of the identify unit ATA command. +The +.B config +file contains the target's AoE configuration string. Writing to this file +sets the targets configuration string. +.PP +Reading a shelf and slot's +.B ctl +file returns a list of colon-separated lines +with the following keywords and values: +.TF firmware +.PD +.TP +.B state +``Up'' or ``down''. +.TP +.B nopen +Number of clients using this target. +.TP +.B nout +Number of outstanding AoE frames. +.TP +.B nmaxout +Maximum number of outstanding frames allowed. +.TP +.B nframes +Maximum number of outstanding frames. +.I Nframes +is greater than +.I nmaxout +when the initiator is reducing the number of in-flight +frames due to packet loss. It is assumed that packet +loss is due to an overwhelmed target and not poor +network conditions. +.TP +.BI maxbcount +Maximum number of data bytes per AoE frame. Using +standard frames, +.B maxbcount +is 1024 or two sectors. +AoE ATA headers are 36 bytes. +.TP +.B model +.PD 0 +.TP +.B serial +.TP +.B firmware +The respective fields from the ATA +.B identify unit +command. +.PD +.TP +.B flag +List of flags useful for debugging. The flag +.B jumbo +indicates that jumbo frames are accepted, not that +they are being used. +.I Maxbcount +should be consulted for this purpose. +.PP +The +.B data +file may be read or written like a normal file +except that reads and writes to this file are converted to +AoE commands to the target, so transfers should be 512 or 1024 bytes long +(or a larger multiple of 512 iff jumbo packets are in use). +The size of this file is the usable size of the target. +.PP +The +.B devlink +directory contains one file for each interface the target was +discovered on. The files are numbers from 0 to +.I n +and contain a list of colon-separated lines +with keywords and their values: +.TF mintimer +.PD +.TP +.B addr +A space-separated list of the target's Ethernet addresses visible from +this interface. +.TP +.B npkt +The number of frames sent on this interface. +.TP +.B resent +The number of frames re-sent. Frames are re-sent +when they have been outstanding twice the RTT average. +.TP +.B flag +``Up'' when the netlink is up. +.TP +.B rttavg +.PD 0 +.TP +.B mintimer +Minimum timer and RTT average as per +.IR "Congestion Avoidance and Control" . +.PD +.TP +.B nl path +Path of the Ethernet device. +.TP +.B nl ea +Ethernet address of the local Ethernet device. +.TP +.B nl flag +``Up'' if the local interface is up. +.TP +.B nl lostjumbo +Number of consecutive jumbograms lost. +.TP +.B nl datamtu +Unused. +.PP +.SH SOURCE +.B /sys/src/9/port/devaoe.c +.SH SEE ALSO +.\" .IR cec (1), +.\" .IR vblade (1), +.IR sd (3), +.IR sdaoe (3), +.IR aoesrv (8), +.IR snoopy (8) +.br +.BR http://www.coraid.com/documents/AoEr10.txt +.br +Van Jacobson and Michael J. Karels, +.IR "``Congestion Avoidance and Control''" , +ACM Computer Communication Review; +Proceedings of the Sigcomm '88 Symposium in Stanford, CA, August, 1988. +.SH BUGS +There is no +.B raw +file for executing arbitrary commands. +.PP +This is a fairly primitive interface; +.IR sdaoe (3) +is usually more suitable. diff --git a/sys/man/3/apm b/sys/man/3/apm new file mode 100755 index 000000000..36809ea56 --- /dev/null +++ b/sys/man/3/apm @@ -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/sys/man/3/arch b/sys/man/3/arch new file mode 100755 index 000000000..7cd5e82fb --- /dev/null +++ b/sys/man/3/arch @@ -0,0 +1,143 @@ +.TH ARCH 3 +.SH NAME +arch \- architecture-specific information and control +.SH SYNOPSIS +.nf +.B bind -a #P /dev +.sp 0.3v +.B /dev/archctl +.B /dev/cputype +.B /dev/ioalloc +.B /dev/iob +.B /dev/iol +.B /dev/iow +.B /dev/irqalloc +.SH DESCRIPTION +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 in MHz. +Reads from +.I archctl +yield at least data of this form: +.IP +.EX +cpu AMD64 2201 pge +pge on +coherence mfence +cmpswap cmpswap486 +i8253set on +cache default uc +cache 0x0 1073741824 wb +cache 0x3ff00000 1048576 uc +.EE +.LP +Where +.L AMD64 +is the processor type, +.L 2201 +is the processor speed in MHz, +and +.L pge +is present only if the `page global extension' capability is present; +the next line reflects its setting. +.L coherence +is followed by one of +.LR mb386 , +.LR mb586 , +.L mfence +or +.LR nop , +showing the form of memory barrier used by the kernel. +.L cmpswap +is followed by +.L cmpswap386 +or +.LR cmpswap486 , +reflecting the form of `compare and swap' used by the kernel. +.L i8253set +is a flag, indicating the need to explicitly set +the Intel 8253 or equivalent timer. +There may be lines starting with +.L cache +that reflect the state of memory caching via MTRRs +(memory-type region registers). +The second word on the line is +.L default +or a C-style number which is the base physical address of the region; +the third is a C-style length of the region; +and the fourth is one of +.LR uc +(for uncachable), +.LR wb +(write-back), +.LR wc +(write-combining), +.LR wp +(write-protected), +or +.LR wt +(write-through). +A region may be a subset of another region, and the smaller region +takes precedence. +This may be used to make I/O registers uncachable +in the midst of a write-combining region mostly used +for a video framebuffer, for example. +Control messages may be written to +.I archctl +and use the same syntax as the data read from +.IR archctl . +Known commands include +.LR cache , +.LR coherence , +.LR i8253set , +and +.LR pge . +. +.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(unsigned 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.4ux): %r", port); + return data; +} +.EE +.SH SOURCE +.B /sys/src/9/pc/devarch.c diff --git a/sys/man/3/audio b/sys/man/3/audio new file mode 100755 index 000000000..e95608c83 --- /dev/null +++ b/sys/man/3/audio @@ -0,0 +1,129 @@ +.TH AUDIO 3 +.SH NAME +audio \- SoundBlaster or ESS1688 audio controller +.SH SYNOPSIS +.nf +.B bind -a #A /dev +.sp 0.3v +.B /dev/audio +.B /dev/volume +.fi +.SH DESCRIPTION +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 +.IP +.B "bufsize \f2s\fP buffered \f2b\fP offset \f2o\fP time \f2t\fP +.PP +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. +.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 an +.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. +.TF "\fLspeaker in out" +.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. +.SH SOURCE +.B /sys/src/9/port/devaudio.c +.SH SEE ALSO +.IR usb (4) diff --git a/sys/man/3/bridge b/sys/man/3/bridge new file mode 100755 index 000000000..21f989457 --- /dev/null +++ b/sys/man/3/bridge @@ -0,0 +1,171 @@ +.TH BRIDGE 3 +.SH NAME +bridge \- IPv4 Ethernet bridge +.SH SYNOPSIS +.nf +.B bind -a #B\fIb\fP /net + +.B /net/bridge\fIb\fP/ctl +.B /net/bridge\fIb\fP/cache +.B /net/bridge\fIb\fP/log +.B /net/bridge\fIb\fP/stats +.BI /net/bridge\fIb\fP/ n +.BI /net/bridge\fIb\fP/ n /ctl +.BI /net/bridge\fIb\fP/ n /local +.BI /net/bridge\fIb\fP/ n /status +.fi +.SH DESCRIPTION +The +.I bridge +device bridges IPv4 packets amongst Ethernet interfaces. +The number +.I b +in the bind is optional and selects a particular bridge +(default 0). +.PP +The +.B /net/bridge0 +directory contains +.BR ctl , +.BR cache , +.BR log , +and +.B stats +files, and numbered subdirectories for each physical interface. +.PP +Opening the +.B ctl +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: +.TF cacheflush +.PD +.TP +.BI "bind ether " "name ownhash path" +Treat the device mounted at +.I path +(e.g., +.LR /net/ether0 ) +as an Ethernet medium carrying IPv4 and ARP packets +and associate it with this bridge (forward its packets to the +other interfaces associated with this bridge). +.I Ownhash +is an `owner hash'. +.TP +.BI "bind tunnel " "name ownhash path path2 +Treat the device mounted at +.I path +as a network tunnel carrying IPv4 and ARP packets, +the device mounted at +.I path2 +as an Ethernet medium carrying IPv4 and ARP packets +and associate them with this bridge +(forward its packets to the +other interfaces associated with this bridge). +Read packets from the +.I path +interface and write them to the +.I path2 +interface. +Such tunnels have an MTU of 1400 bytes. +.TP +.BI "unbind " "type address [ownhash]" +Disassociate the interface associated with +.I address +from this bridge. +.I Type +must be +.L ether +or +.LR tunnel . +.TP +.B cacheflush +Clear the cache of (destination MAC address, port) tuples. +.TP +.BI "delay " "delay0 delayn" +Set the +.I delay0 +and +.I delayn +parameters. +.I delay0 +is the constant microsecond delay per packet +and +.I delayn +is the microsecond delay per byte. +.TP +.BI "set " option +Set bridge +.IR option . +The only known option is +.LR tcpmss , +which limits the TCP Maximum Segment Size of +TCPv4 packets passing through to 1300 bytes. +.TP +.BI "clear " option +Clear bridge +.IR option . +.PP +Reading +.I stats +returns statistics about the bridge. +.PP +Reading the +.I log +file returns data from the bridge's log +and will block at end of file awaiting new data. +.PP +Reading the +.B cache +file prints the cache of (destination MAC address, port) tuples, +one entry per line. +The format is: +the destination MAC (e.g., Ethernet) address in hex, +port number, +count of packets from this address, +count of packets to this address, +expiry time in seconds since the epoch, +and +.L e +for expired entries or +.L v +for valid entries. +.PP +In a connection subdirectory, +.B ctl +and +.B local +don't do anything, +but +.B status +returns a one-line status summary. +.SH EXAMPLES +Set up a network bridge between two Ethernets +.RL ( #l0 +and +.LR #l1 ). +.IP +.EX +bind -a '#B' /net +bind -a '#l1' /net +echo 'bind ether outer 0 /net/ether0' >/net/bridge0/ctl +echo 'bind ether inner 0 /net/ether1' >/net/bridge0/ctl +.EE +.SH "SEE ALSO" +.IR ip (3) +.SH SOURCE +.B /sys/src/9/port/devbridge.c +.SH BUGS +Doesn't understand IPv6. diff --git a/sys/man/3/cap b/sys/man/3/cap new file mode 100755 index 000000000..1f526fa3e --- /dev/null +++ b/sys/man/3/cap @@ -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 SOURCE +.B /sys/src/9/port/devcap.c +.SH "SEE ALSO" +.IR sechash (2) +.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''. diff --git a/sys/man/3/cons b/sys/man/3/cons new file mode 100755 index 000000000..d87799716 --- /dev/null +++ b/sys/man/3/cons @@ -0,0 +1,376 @@ +.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/config +.B /dev/cons +.B /dev/consctl +.B /dev/cputime +.B /dev/drivers +.B /dev/hostdomain +.B /dev/hostowner +.B /dev/kmesg +.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, +.L ^U +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 config +file contains a copy of the kernel configuration file used to build the kernel. +.PP +The +.B kmesg +file holds the last 16 kilobytes of output written to the console +by the kernel's print statements or by processes writing to +.BR /dev/cons . +It is useful for retrieving boot messages once the boot +process is over. +.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 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 10 numbers: +processor number, context switches, interrupts, system calls, page faults, +TLB faults, TLB purges, load average, idle time and time spent servicing interrupts. +The load average is in units of milli-CPUs and is decayed over time; +idle time and interrupt time are percentage units; +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 text block giving memory usage statistics: +.IP +.EX +\fIn\fP memory +\fIn\fP pagesize +\fIn\fP kernel +\fIn\fP/\fIm\fP user +\fIn\fP/\fIm\fP swap +\fIn\fP/\fIm\fP kernel malloc +\fIn\fP/\fIm\fP kernel draw +.EE +.PP +These are total memory (bytes), system page size (bytes), +kernel memory (pages), user memory (pages), swap space (pages), +kernel malloced data (bytes), and kernel graphics data (bytes). +The expression +.IR n / m +indicates +.I n +used out of +.I m +available. +These numbers are not blank padded. +.PP +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/sys/man/3/draw b/sys/man/3/draw new file mode 100755 index 000000000..23ab0fcdf --- /dev/null +++ b/sys/man/3/draw @@ -0,0 +1,791 @@ +.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 O +.IR op [1] +.br +Set the compositing operator to +.I op +for the next draw operation. +(The default is +.BR SoverD ). +.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/sys/man/3/dup b/sys/man/3/dup new file mode 100755 index 000000000..6ce855e98 --- /dev/null +++ b/sys/man/3/dup @@ -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/sys/man/3/env b/sys/man/3/env new file mode 100755 index 000000000..2724f2ac4 --- /dev/null +++ b/sys/man/3/env @@ -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/sys/man/3/ether b/sys/man/3/ether new file mode 100755 index 000000000..e1d534b63 --- /dev/null +++ b/sys/man/3/ether @@ -0,0 +1,111 @@ +.TH ETHER 3 +.SH NAME +ether \- Ethernet device +.SH SYNOPSIS +.nf +.B bind -a #l\fIn\fP /net + +.BI /net/ether n /clone +.BI /net/ether n /addr +.BI /net/ether n /ifstats +.BI /net/ether n /stats +.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 +.BR clone , +.BR addr , +.BR ifstats , +and +.B stats +files. +.B stats +and +.B ifstats +are the same as in the subdirectories (see below). +Reading +.B addr +returns the MAC address of this interface in hex with no punctuation +and no trailing newline. +The number +.I n +(optional in the bind) +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/sys/man/3/flash b/sys/man/3/flash new file mode 100755 index 000000000..d445a4300 --- /dev/null +++ b/sys/man/3/flash @@ -0,0 +1,173 @@ +.TH FLASH 3 +.SH NAME +flash \- flash memory +.SH SYNOPSYS +.nf +.BI "bind -a #F" \fR[\fPn\fR]\fP " /dev" +.sp 0.3v +.B /dev/flash +.BI /dev/flash/ part +.BI /dev/flash/ part ctl +.fi +.SH DESCRIPTION +The flash memory device serves a two-level directory, +giving access to files representing part or all of a bank of flash memory. +A platform might have more than one bank of flash, numbered starting from 0. +The attach specifier +.I n +is a decimal integer that selects a particular bank of flash (default: 0). +Both NOR and NAND flash is supported. +For both types of flash, +the driver gives a read/write/erase interface to the raw flash device, +which can impose constraints on operations beyond those imposed by the driver. +Other drivers such as +.IR ftl (3) +or +.IR logfs (3) +implement any higher-level format required, +including ECC for NAND flash, for instance. +.PP +The top level directory contains a single directory named +.B flash +for bank 0, and +.BI flash n +for each other bank +.IR n . +It contains two files for each partition: +a data file +.I part +and an associated control file +.IB part ctl , +where +.I part +is the name of the partition. +Each partition represents a region of flash memory that starts and ends +on a flash segment (erase unit) boundary. +The system initially creates a single standard partition +.B flash +representing the whole of flash memory, and the corresponding control file +.BR flashctl . +Other partitions can be created by writing to +.B flashctl +as described below. +.PP +The data file +.I part +provides read and write access to the bytes on the system's flash memory. +Bytes can be read and written on any byte boundary: +the interface hides any alignment restrictions. +A read returns the value of the bytes at the current file offset, +where zero is the start of the partition. +A write reprograms the flash to the given byte values, at the current +file offset (relative to the start of the partition), using the physical +device's reprogramming algorithm. +An erased flash byte is logically +.B 0xFF +(regardless of the conventions of the physical flash device). +A write can change a bit with value 1 to a 0, +but cannot change a 0 bit to 1; +that can only be done by erasing one or more flash segments. +NAND flash typically has restrictions on the number of writes +allowed to a page before requiring a block erase. +.\" bad idea: +.\" Reads and writes are unbuffered. +.PP +The control file +.BI part ctl +can be read and written. +A read returns several lines containing decimal and hexadecimal numbers +(separated by white space) +revealing the characteristics of memory within the partition. +The first line gives the +the manufacturer ID, the flash device ID, the memory width in bytes, +and a string giving the flash type +(currently either +.B nor +or +.BR nand ). +Subsequent lines give characteristics of each group of erase units +within the partition, +where the erase units within a group have the same properties. +Each line gives the start and end (as byte addresses) +of the erase units in the region +that lie within the partition, +followed by the size in bytes of each erase unit, which is followed +for NAND flash by the size in bytes of a page. +The sizes for NAND flash include the extra bytes per page +typically used to hold an ECC and block status. +A write contains one of the following textual commands: +.TF "erase al" +.TP +.BI add " name start end" +Create a new partition that ranges from +.I start +to +.I end +within the current partition. +Each value must be numeric (decimal, octal or hexadecimal) +and a multiple of the erase unit size. +.I Name +must not be the name of an existing partition. +On success, new files +.I name +and +.IB name ctl +will appear in the parent +.B flash +directory. +.TP +.B erase all +Erase the whole flash partition, setting all bytes to +.BR 0xFF , +except those that are hardware write-protected. +.TP +.BI erase " offset" +Erase the segment that begins at the given +.I offset +within the partition, +setting all bytes to +.BR 0xFF , +except those that are hardware write-protected. +The +.I offset +is given in bytes, but must be a multiple +of the segment (erase unit) size. +.TP +.BR protectboot " [ " off " ]" +By default the system prevents erase unit 0 of the flash from being +erased or written, assuming it +contains the primary bootstrap. +Writing this command with parameter +.B off +removes that protection. +Writing +.B protectboot +with any other parameter (or none) restores the protection. +Note that a manufacturer might also have locked the flash in hardware, +and that protection must be removed in a device-dependent way. +.TP +.B sync +If the underlying device must buffer or cache (current devices do not), +flush the buffer(s). +.PD +.PP +The syntax of all numbers is that of +.I strtoul +(in +.IR atof (2)); +the default base is 10. +.SH SOURCE +.B /sys/src/*/devflash.c +.br +.B /sys/src/*/flash*.c +.SH SEE ALSO +.IR flashfs (4), +.IR paqfs (4) +.SH DIAGNOSTICS +A write will return an error if +an attempt is made to change a 0 bit to 1, +or if the flash memory fails to be programmed correctly. +.SH BUGS +The flash cannot be written if the kernel is executing directly from flash, +because the physical flash cannot be read during programming, +and the driver does not copy the programming code to DRAM. diff --git a/sys/man/3/floppy b/sys/man/3/floppy new file mode 100755 index 000000000..f1b354663 --- /dev/null +++ b/sys/man/3/floppy @@ -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/sys/man/3/fs b/sys/man/3/fs new file mode 100755 index 000000000..11365cad1 --- /dev/null +++ b/sys/man/3/fs @@ -0,0 +1,263 @@ +.TH FS 3 +.SH NAME +fs \- file system devices +.SH SYNOPSIS +.nf +.B bind -b #k /dev +.sp 0.3v +.B /dev/fs +.B /dev/fs/ctl +.B /dev/fs/... +.B /dev/\fInew\fP +.fi +.SH DESCRIPTION +The +.I fs +driver builds complex disk files out of simpler disk files. +Inspired by the Plan 9 file server kernel's configuration strings, +it provides device mirroring, partitioning, interleaving, and catenation +for disk-based services like +.IR fossil (4) +or +.IR venti (8). +.PP +The device is intended to be bound at +.B /dev +and initially contains a directory named +.BR fs , +which in turn contains a +.B ctl +file and one file per configured device. +.PP +Most control messages introduce a new device, here named +.IR new . +The +.I file +arguments are interpreted in the name space of the writing process. +.PP +The device name +.I new +may be a single filename component (containing no slashes); +in this case, the device is created under +.BR #k/fs . +If +.I new +instead has the format +.IB dir / file, +the device is made available at +.BI #k/ dir / file. +The directory +.I dir +goes away when the last device on it is removed with the +.B del +control message, +but +.B #k/fs +will never be removed. +.TF "del \fIold +.PD +.TP +.BI cat " new files" \fR... +The device +.I new +corresponds to the catenation of +.IR files . +.TP +.BI inter " new files" \fR... +The device +.I new +corresponds to the block interleaving of +.IR files ; +an 8192-byte block size is assumed. +.TP +.BI mirror " new files" \fR... +The device +.I new +corresponds to a RAID-1-like mirroring of +.IR files . +Writes to +.BI new +are handled by sequentially writing the same data to the +.I files +from right to left (the reverse of +the order in the control message). +A failed write causes an eventual error return +but does not prevent the rest of the writes +to the other devices of the mirror set. +Reads from +.BI new +are handled by sequentially reading from the +.I files +from left to right until one succeeds. +The length of the mirror device is the minimum of the lengths of the +.IR files . +.TP +.BI part " new file offset length" +.TP +.BI part " new offset end +In the first form, +the device +.I new +corresponds to the +.I length +units starting at +.I offset +in +.IR file . +If +.IR offset + length +reaches past the end of +.IR file , +.I length +is silently reduced to fit. +Units are bytes. +In the second form, +a previous +.B disk +request must have defined the source +.I file +for further requests and the end of the device +is determined by the +.I end +offset in the source file, and not by the device +length. Units are as defined in the previous +.B disk +request. This form is accepted for compatibility with +.IR fdisk +(in +.IR prep (8)) +and +.IR sd (3) +devices. +.TP +.BI del " old +Removes the device named +.IR old . +The device will still be seen while in use. +Further I/O attempts will fail with an error indication stating that +the device is gone. +When +.I old +is +.IB dir /*\fR, +all devices under +.I dir +are removed. +.TP +.BI disk " dir [ n file ] +makes +.I dir +implicit in new device names (i.e., it makes +.I new +mean +.IB dir / new +by default). +Optional argument +.I n +specifies the default unit (sector) size in bytes and the default source +.I file +for further partition devices. +Default values are restored when the control file is closed. +.TP +.B clear +Discard all +.I fs +device definitions. +.PD +.LP +If the variable +.B fsconfig +is set in +.IR plan9.ini (8), +.I fs +will read its configuration from the file +.B $fsconfig +on the first attach. +This is useful when the machine boots from a local file server that uses +.IR fs . +.SH EXAMPLES +Use a previously partitioned disk, +.BR /dev/sdC0 , +making +partition files available under +.BR /dev/sdC0parts : +.IP +.EX +{ + echo disk sdC0parts 512 /dev/sdC0/data + disk/fdisk -p /dev/sdC0/data + # now create plan 9 partitions + echo disk sdC0parts 512 /dev/sdC0parts/plan9 + disk/prep -p /dev/sdC0parts/plan9 +} > /dev/fs/ctl +.EE +.LP +Mirror the two disks +.B /dev/sdC0/data +and +.B /dev/sdD0/data +as +.BR /dev/fs/m0 ; +similarly, mirror +.B /dev/sdC1/data +and +.B /dev/sdD1/data +as +.BR /dev/fs/m1 : +.IP +.EX +echo mirror m0 /dev/sdC0/data /dev/sdD0/data >/dev/fs/ctl +echo mirror m1 /dev/sdC1/data /dev/sdD1/data >/dev/fs/ctl +.EE +.LP +Interleave the two mirrored disks to create +.BR /dev/fs/data : +.IP +.EX +echo inter data /dev/fs/m0 /dev/fs/m1 >/dev/fs/ctl +.EE +.LP +Run +.IR kfs (4) +on the interleaved device: +.IP +.EX +disk/kfs -f /dev/fs/data +.EE +.LP +Save the configuration: +.IP +.EX +cp /dev/fs/ctl /dev/fd0disk +.EE +.LP +To load the configuration automatically at boot time, +add this to +.IR plan9.ini : +.IP +.EX +fsconfig=/dev/fd0disk +.EE +.SH "SEE ALSO" +.I read +in +.IR cat (1), +.IR dd (1), +.IR sd (3), +.IR fossil (4), +.IR fs (8), +.IR plan9.ini (8), +.IR prep (8), +.IR venti (8) +.SH SOURCE +.B /sys/src/9/port/devfs.c +.SH BUGS +Mirrors are RAID-like but not RAID. +There is no fancy recovery mechanism and +no automatic initial copying from a master drive to its mirror drives. +.PP +Each +.I write +system call on +.B ctl +may transmit at most one command. diff --git a/sys/man/3/i82365 b/sys/man/3/i82365 new file mode 100755 index 000000000..d0e90d2ab --- /dev/null +++ b/sys/man/3/i82365 @@ -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/sys/man/3/ip b/sys/man/3/ip new file mode 100755 index 000000000..07df8d38a --- /dev/null +++ b/sys/man/3/ip @@ -0,0 +1,1269 @@ +.TH IP 3 +.SH NAME +ip, esp, gre, icmp, icmpv6, ipmux, rudp, tcp, udp \- network protocols over IP +.SH SYNOPSIS +.nf +.2C +.B bind -a #I\fIspec\fP /net +.sp 0.3v +.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 +\&... +.sp 0.3v +.B /net/arp +.B /net/bootp +.B /net/iproute +.B /net/ipselftab +.B /net/log +.B /net/ndb +.sp 0.3v +.B /net/esp +.B /net/gre +.B /net/icmp +.B /net/icmpv6 +.B /net/ipmux +.B /net/rudp +.B /net/tcp +.B /net/udp +.sp 0.3v +.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 +\&... +.1C +.fi +.SH DESCRIPTION +The +.I ip +device provides the interface to Internet Protocol stacks. +.I Spec +is an integer from 0 to 15 identifying a stack. +Each stack implements IPv4 and IPv6. +Each stack is 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. +IPv4 addresses are a subset of the IPv6 addresses and both standard +.SM ASCII +formats are accepted. +In binary representation, all v4 addresses start with the 12 bytes, in hex: +.IP +.EX +00 00 00 00 00 00 00 00 00 00 ff ff +.EE +. +.SS "Configuring interfaces +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 those described under +.B "Protocol directories" +below and these: +.TF "\fLbind loopback\fR" +.PD +. +.\" from devip.c +. +.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 IPv4 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. +. +.\" from ipifc.c +. +.TP +.B "unbind +Disassociate the physical device from an IP interface. +.TP +.BI add\ "local mask remote mtu " proxy +.PD 0 +.TP +.BI try\ "local mask remote mtu " proxy +.PD +Add a local IP address to the interface. +.I Try +adds the +.I local +address as a tentative address +if it's an IPv6 address. +The +.IR mask , +.IR remote , +.IR mtu , +and +.B proxy +arguments are all optional. +The default +.I mask +is the class mask for the local address. +The default +.I remote +address is +.I local +ANDed with +.IR mask . +The default +.I mtu +(maximum transmission unit) +is 1514 for Ethernet and 4096 for packet media. +The +.I mtu +is the size in bytes of the largest packet that this interface can send. +.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. +. +.\" remainder from netif.c (thus called from devether.c), +.\" except add6 and ra6 from ipifc.c +. +.TP +.B bridge +Enable bridging (see +.IR bridge (3)). +.TP +.B promiscuous +Set the interface into promiscuous mode, +which makes it accept all incoming packets, +whether addressed to it or not. +.TP +.BI "connect " type +marks the Ethernet packet +.I type +as being in use, if not already in use +on this interface. +A +.I type +of -1 means `all' but appears to be a no-op. +.TP +.BI addmulti\ Media-addr +Treat the multicast +.I Media-addr +on this interface as a local address. +.TP +.BI remmulti\ Media-addr +Remove the multicast address +.I Media-addr +from this interface. +.TP +.B scanbs +Make the wireless interface scan for base stations. +.TP +.B headersonly +Set the interface to pass only packet headers, not data too. +. +.\" remainder from ipifc.c; tedious, so put them last +. +.TP +.BI "add6 " "v6addr pfx-len [onlink auto validlt preflt]" +Add the local IPv6 address +.I v6addr +with prefix length +.I pfx-len +to this interface. +See RFC 2461 §6.2.1 for more detail. +The remaining arguments are optional: +.RS +.TF "\fIonlink\fR" +.TP +.I onlink +flag: address is `on-link' +.TP +.I auto +flag: autonomous +.TP +.I validlt +valid life-time in seconds +.TP +.I preflt +preferred life-time in seconds +.RE +.PD +.TP +.BI "ra6 " "keyword value ..." +Set IPv6 router advertisement (RA) parameter +.IR keyword 's +.IR value . +Known +.IR keyword s +and the meanings of their values follow. +See RFC 2461 §6.2.1 for more detail. +Flags are true iff non-zero. +.RS +.TF "\fLreachtime\fR" +.TP +.B recvra +flag: receive and process RAs. +.TP +.B sendra +flag: generate and send RAs. +.TP +.B mflag +flag: ``Managed address configuration'', +goes into RAs. +.TP +.B oflag +flag: ``Other stateful configuration'', +goes into RAs. +.TP +.B maxraint +``maximum time allowed between sending unsolicited multicast'' +RAs from the interface, in ms. +.TP +.B minraint +``minimum time allowed between sending unsolicited multicast'' +RAs from the interface, in ms. +.TP +.B linkmtu +``value to be placed in MTU options sent by the router.'' +Zero indicates none. +.TP +.B reachtime +sets the Reachable Time field in RAs sent by the router. +``Zero means unspecified (by this router).'' +.TP +.B rxmitra +sets the Retrans Timer field in RAs sent by the router. +``Zero means unspecified (by this router).'' +.TP +.B ttl +default value of the Cur Hop Limit field in RAs sent by the router. +Should be set to the ``current diameter of the Internet.'' +``Zero means unspecified (by this router).'' +.TP +.B routerlt +sets the Router Lifetime field of RAs sent from the interface, in ms. +Zero means the router is not to be used as a default router. +.PD +.RE +.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 +.I readipifc +in +.IR ip (2). +. +.SS "Routing +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: +.TF m +.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 +.PD +.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: +.TF "\fLtag \fIstring\fR" +.PD +.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 +The file +.B /net/arp +controls information about address resolution. +The kernel automatically updates the v4 ARP and v6 Neighbour Discovery +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: +.TF "\fLdel \fIIP-addr\fR" +.PD +.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. +.TP +.BI del\ "IP-addr" +Delete an individual entry. +.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 . +.br +.ne 3 +. +.SS "Debugging and stack information +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: +.TF "\fLclear \fIarglist\fR" +.PD +.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 icmp , +.BR udp , +.BR compress , +.BR gre , +.BR tcpwin , +.BR tcprxmt , +.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 to 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. +Note that the `IPv4 route' flag will never be set. +.br +.ne 3 +. +.SS "Protocol directories +The +.I ip +device +supports IP as well as several protocols that run over it: +TCP, UDP, RUDP, ICMP, GRE, and ESP. +TCP and UDP provide the standard Internet +protocols for reliable stream and unreliable datagram +communication. +RUDP is a locally-developed reliable datagram protocol based on UDP. +ICMP is IP's catch-all control protocol used to send +low level error messages and to implement +.IR ping (8). +GRE is a general encapsulation protocol. +ESP is the encapsulation protocol for IPsec. +IL provided a reliable datagram service for communication +between Plan 9 machines over IPv4, but is no longer part of the system. +.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: +.TF "\fLremmulti \fIip\fR" +.PD +.TP +.BI connect\ ip-address ! port "!r " local +Establish a connection to the remote +.I ip-address +and +.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. +.\" this is gone +.\" .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 . +.TP +.B ignoreadvice +Don't break (UDP) connections because of ICMP errors. +.TP +.BI addmulti\ "ifc-ip [ mcast-ip ]" +Treat +.I ifc-ip +on this multicast interface as a local address. +If +.I mcast-ip +is present, +use it as the interface's multicast address. +.TP +.BI remmulti\ ip +Remove the address +.I ip +from this multicast interface. +.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 +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: +.TF "\fLkeepalive\fI n\fR" +.PD +.TP +.B hangup +close down this TCP connection +.TP +.BI keepalive \ n +turn on keep alive messages. +.IR N , +if given, is the milliseconds between keepalives +(default 30000). +.TP +.BI checksum \ n +emit TCP checksums of zero if +.I n +is zero; otherwise, and by default, +TCP checksums are computed and sent normally. +.TP +.BI tcpporthogdefense \ onoff +.I onoff +of +.L on +enables the TCP port-hog defense for all TCP connections; +.I onoff +of +.L off +disables it. +The defense is a solution to hijacked systems staking out ports +as a form of denial-of-service attack. +To avoid stateless TCP conversation hogs, +.I ip +picks a TCP sequence number at random for keepalives. +If that number gets acked by the other end, +.I ip +shuts down the connection. +Some firewalls, +notably ones that perform stateful inspection, +discard such out-of-specification keepalives, +so connections through such firewalls +will be killed after five minutes +by the lack of keepalives. +. +.SS UDP +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 , +the message +.L headers +is written to +.BR ctl , +then all messages sent to the announced port +are received on the announced connection prefixed +with the corresponding structure, +declared in +.BR : +.IP +.EX +typedef struct Udphdr Udphdr; +struct Udphdr +{ + uchar raddr[16]; /* V6 remote address and port */ + uchar laddr[16]; /* V6 local address and port */ + uchar ifcaddr[16]; /* V6 interface address (receive only) */ + uchar rport[2]; /* remote port */ + uchar lport[2]; /* local port */ +}; +.EE +.PP +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 +read. +.PP +In this case (writing +.L headers +to the +.I ctl +file), +no +.I listen +nor +.I accept +is needed; +otherwise, +the usual sequence of +.IR announce , +.IR listen , +.I accept +must be executed before performing I/O on the corresponding +.I data +file. +. +.SS RUDP +RUDP is a reliable datagram protocol based on UDP, +currently only for IPv4. +Packets are delivered in order. +RUDP does not support +.BR listen . +One must write either +.L connect +or +.L announce +followed immediately by +.L headers +to +.BR ctl . +.PP +Unlike 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 contain 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. +.PP +RUDP +.I ctl +files accept the following messages: +.TF "\fLranddrop \fI[ percent ]\fR" +.TP +.B headers +Corresponds to the +.L headers +format of UDP. +.TP +.BI "hangup " "IP port" +Drop the connection to address +.I IP +and +.IR port . +.TP +.BI "randdrop " "[ percent ]" +Randomly drop +.I percent +of outgoing packets. +Default is 10%. +. +.SS ICMP +ICMP is a datagram protocol for IPv4 used to exchange control requests and +their responses with other machines' IP implementations. +ICMP is primarily a kernel-to-kernel protocol, but it is possible +to generate `echo request' and read `echo reply' packets from user programs. +. +.SS ICMPV6 +ICMPv6 is the IPv6 equivalent of ICMP. +If, after an +.BR announce , +the message +.L headers +is written to +.BR ctl , +then before a write, +a user must prefix each message with a corresponding structure, +declared in +.BR : +.IP +.EX +/* + * user level icmpv6 with control message "headers" + */ +typedef struct Icmp6hdr Icmp6hdr; +struct Icmp6hdr { + uchar unused[8]; + uchar laddr[IPaddrlen]; /* local address */ + uchar raddr[IPaddrlen]; /* remote address */ +}; +.EE +.PP +In this case (writing +.L headers +to the +.I ctl +file), +no +.I listen +nor +.I accept +is needed; +otherwise, +the usual sequence of +.IR announce , +.IR listen , +.I accept +must be executed before performing I/O on the corresponding +.I data +file. +. +.SS GRE +GRE is the encapsulation protocol used by PPTP. +The kernel implements just enough of the protocol +to multiplex it. +Our implementation encapsulates in IPv4, per RFC 1702. +.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. +.br +.ne 3 +. +.SS ESP +ESP is the Encapsulating Security Payload (RFC 1827, obsoleted by RFC 4303) +for IPsec (RFC 4301). +We currently implement only tunnel mode, not transport mode. +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 . +In the following, +.I secret +is the hexadecimal encoding of a key, +without a leading +.LR 0x . +The control messages are: +.TF "\fLesp \fIalg secret\fR" +.PD +.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 , +.BR des3_cbc , +and eventually +.BR aes_128_cbc , +and +.BR aes_ctr . +.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 , +.BR hmac_md5_96 , +and eventually +.BR aes_xcbc_mac_96 . +.TP +.B header +Turn on header mode. Every buffer read from +.B data +starts with 4 unused 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 +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: +.TF "\fLdata[\fIn\fL:\fIm\fL]=\fIexpr\fR " +.PD +.TP +.BI proto= n +the IP protocol number must be +.IR n . +.TP +.BI data[ n : m ]= expr +bytes +.I n +through +.I m +following the IP packet must match +.IR expr . +.TP +.BI iph[ n : m ]= expr +bytes +.I n +through +.I m +of the IP packet header 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 data , +.B iph +and +.BR proto , +both value and mask are strings of 2 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 +and 6to4 tunnelling. +.br +.ne 5 +. +.SS Statistics +The +.B stats +files are read only and contain statistics useful to network monitoring. +.br +.ne 12 +.PP +Reading +.B /net/ipifc/stats +returns a list of 19 tagged and newline-separated fields representing: +.EX +.ft 1 +.2C +.in +0.25i +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 +.in -0.25i +.1C +.ft +.EE +.br +.ne 16 +.PP +Reading +.B /net/icmp/stats +returns a list of 26 tagged and newline-separated fields representing: +.EX +.ft 1 +.2C +.in +0.25i +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 +.in -0.25i +.1C +.EE +.PP +Reading +.B /net/tcp/stats +returns a list of 11 tagged and newline-separated fields representing: +.EX +.ft 1 +.2C +.in +0.25i +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 +.in -0.25i +.1C +.EE +.PP +Reading +.B /net/udp/stats +returns a list of 4 tagged and newline-separated fields representing: +.EX +.ft 1 +.2C +.in +0.25i +datagrams received +datagrams received for bad ports +malformed datagrams received +datagrams sent +.in -0.25i +.1C +.EE +.PP +Reading +.B /net/gre/stats +returns a list of 1 tagged number representing: +.EX +.ft 1 +.in +0.25i +header length errors +.in -0.25i +.EE +.SH "SEE ALSO" +.IR dial (2), +.IR ip (2), +.IR bridge (3), +.\" .IR ike (4), +.IR ndb (6), +.IR listen (8) +.br +.PD 0 +.TF "\fL/lib/rfc/rfc2822" +.TP +.B /lib/rfc/rfc2460 +IPv6 +.TP +.B /lib/rfc/rfc4291 +IPv6 address architecture +.TP +.B /lib/rfc/rfc4443 +ICMPv6 +.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/sys/man/3/kbin b/sys/man/3/kbin new file mode 100755 index 000000000..ffc9c271d --- /dev/null +++ b/sys/man/3/kbin @@ -0,0 +1,36 @@ +.TH KBIN 3 +.SH NAME +kbin \- external keyboard input +.SH SYNOPSIS +.nf +.B bind -a #Ι /dev +.sp 0.3v +.B /dev/kbin +.fi +.SH DESCRIPTION +The +.I kbin +device is a PC driver that +serves a one-level directory containing a single file, +.BR kbin , +which can be used to send +keyboard scan codes to the kernel. +.PP +.I Kbin +is necessary for +.IR usb (4) +drivers that handle keyboards. +Keyboard input +is processed as described in +.IR cons (3). +The scan codes correspond to the PC keyboard used by the +.IR cons (3) +driver and can be translated by the +.IR kbmap (3) +device. +.SH "SEE ALSO" +.IR cons (3), +.IR kbmap (3), +.IR keyboard (6) +.SH SOURCE +.B /sys/src/9/pc/devkbin.c diff --git a/sys/man/3/kbmap b/sys/man/3/kbmap new file mode 100755 index 000000000..a3b9fad37 --- /dev/null +++ b/sys/man/3/kbmap @@ -0,0 +1,70 @@ +.TH KBMAP 3 +.SH NAME +kbmap \- keyboard map +.SH SYNOPSIS +.nf +.B bind -a #κ /dev + +.B /dev/kbmap +.fi +.SH DESCRIPTION +.PP +The +.I kbmap +device serves a one-level directory containing a single file, +.BR kbmap , +representing the kernel's mapping of +keyboard scan codes to Unicode characters +(see +.IR cons (3) +and +.IR keyboard (6)). +.PP +Reads return the current contents of the map. +Each entry is one line containing three 11 character numeric fields, each followed by a space: +a table number, an index into the table (scan code), and the decimal value +of the corresponding Unicode character (0 if none). +The table numbers are platform dependent; they typically distinguish +between unshifted and shifted keys. +The scan code values are hardware dependent and can vary +from keyboard to keyboard. +.PP +Writes to the file change the map. +Lines written to the file must contain three space-separated fields, +representing the table number, scan code index, and Unicode character. +Values are taken to be decimal unless they start with +.B 0x +(hexadecimal) or +.B 0 +(octal). +The Unicode character can also be represented as +.BI ' x +where +.I x +gives the UTF-8 representation of the character +(see +.IR utf (6)), +or as +.BI ^ X +to represent a control character. +.PP +The Unicode character can also be +.BI M n +to represent mouse button +.IR n . +The map +.B /sys/lib/kbmap/mouse-fn +maps the F1 through F5 keys to the three mouse buttons and the two +scroll wheel buttons. +Similarly, +.B mouse-csa +maps the left Control, Start, and Alt keys to the three mouse buttons. +These maps are useful on laptops without three-button mice. +.SH "SEE ALSO" +.IR cons (3), +.IR keyboard (6), +.IR utf (6) +.SH FILES +.B /sys/lib/kbmap/* +.SH SOURCE +.B /sys/src/9/port/devkbmap.c diff --git a/sys/man/3/kprof b/sys/man/3/kprof new file mode 100755 index 000000000..4d3f99992 --- /dev/null +++ b/sys/man/3/kprof @@ -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/sys/man/3/loopback b/sys/man/3/loopback new file mode 100755 index 000000000..066827a78 --- /dev/null +++ b/sys/man/3/loopback @@ -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/sys/man/3/lpt b/sys/man/3/lpt new file mode 100755 index 000000000..a8df37dd0 --- /dev/null +++ b/sys/man/3/lpt @@ -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/sys/man/3/mnt b/sys/man/3/mnt new file mode 100755 index 000000000..c92c4370b --- /dev/null +++ b/sys/man/3/mnt @@ -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/sys/man/3/mouse b/sys/man/3/mouse new file mode 100755 index 000000000..1ad9243c1 --- /dev/null +++ b/sys/man/3/mouse @@ -0,0 +1,212 @@ +.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 and may be opened +only by the host owner, 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\fP" +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\fI [n]\fP" +turns on mouse acceleration. +.I N +is an optional acceleration factor. +.TP +.B linear +turns off mouse acceleration. +.TP +.B "res\fI n\fR" +sets mouse resolution to a setting between 0 and +3 inclusive. +.TP +.B "hwaccel\fI on/off\fP" +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\fI xyz\fP" +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. diff --git a/sys/man/3/pipe b/sys/man/3/pipe new file mode 100755 index 000000000..bdbaeba8c --- /dev/null +++ b/sys/man/3/pipe @@ -0,0 +1,52 @@ +.TH PIPE 3 +.SH NAME +pipe \- two-way interprocess communication +.SH SYNOPSIS +.B bind #| +.I dir +.nf + +.IB dir /data +.IB dir /data1 +.fi +.SH DESCRIPTION +.PP +An +.IR attach (5) +of this device allocates two new cross-connected I/O streams, +.IB dir /data +and +.IB dir /data1\f1. +.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/sys/man/3/pnp b/sys/man/3/pnp new file mode 100755 index 000000000..c178feb97 --- /dev/null +++ b/sys/man/3/pnp @@ -0,0 +1,146 @@ +.TH PNP 3 +.SH NAME +pnp \- Plug 'n' Play ISA and PCI Interfaces +.SH SYNOPSIS +.nf +.B bind -a '#$' /dev +.sp 0.3v +.BI /dev/pci/ bus\fL.\fPdev\fL.\fPfn ctl +.BI /dev/pci/ bus\fL.\fPdev\fL.\fPfn raw +.sp 0.3v +.BI /dev/pnp/ctl +.BI /dev/pnp/csn n ctl +.BI /dev/pnp/csn n raw +\&... +.sp 0.3v +.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 used to read or write 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 SEE ALSO +.IR pci (8) +.SH BUGS +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/sys/man/3/proc b/sys/man/3/proc new file mode 100755 index 000000000..c5863dc73 --- /dev/null +++ b/sys/man/3/proc @@ -0,0 +1,507 @@ +.TH PROC 3 +.SH NAME +proc \- running processes +.SH SYNOPSIS +.nf +.B bind #p /proc +.sp 0.3v +.B /proc/trace +.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 the +.B trace +file (see below) and 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 +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. +.PP +The file +.B /proc/trace +can be opened once and read to see trace events from processes that have +had the string +.B trace +written to their +.B ctl +file. +Each event produces, in native machine format, the +.IR pid , +a +.IR type , +and a +.I "time stamp" +(see +.B /sys/include/trace.h +and +.BR /sys/src/cmd/trace.c ). +. +.SS Control messages +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 noswap +Don't allow this process to be swapped out. This should +be used carefully and sparingly or the system could run +out of memory. It is meant for processes that can't be +swapped, like the ones implementing the swap device and for +processes containing sensitive data. +.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 "wired\ \fIn +Wire the process to processor +.IR n . +.TP 10n +.B trace +Without an argument, toggle trace event generation for this process into +.B /proc/trace +(see below). +With a zero argument, tracing for the proc is turned off, with a non-zero numeric +argument, it is turned on. +.TP 10n +.B "period\ \fInu +Set the real-time scheduling period of the process to +.IR nu , +where +.I n +is an optionally signed number containing an optional decimal point and +.I u +is one of +.BR s , +.BR ms , +.BR us , +.BR µs , +.BR ns , +or +empty. The time is interpreted, respectively, as +.IR seconds , +.IR milliseconds , +.IR microseconds , +.IR microseconds , +.IR nanoseconds , +or, in the case of an absent units specifier, as +.IR nanoseconds . +If the time specifier is signed, it is interpreted as an increment or decrement +from a previously set value. See also the +.B admit +command below. +.TP 10n +.B "deadline\ \fInu +Set the real-time deadline interval of the process to +.IR nu , +where +.I n +and +.I u +are interpreted as for +.B period +above. +.TP 10n +.B "cost\ \fInu +Set the real-time cost (maximum CPU time per period) of the process to +.IR nu , +where +.I n +and +.I u +are interpreted as for +.B period +above. +.TP 10n +.B "sporadic +Use sporadic scheduling for the real-time process. The description of the +.B admit +command below contains further details. +.TP 10n +.B "yieldonblock +Make the real-time process yield on blocking I/O. + The description of the +.B admit +command below contains further details. +.TP 10n +.B "admit +Given real-time +.IR period , +.I deadline +and +.I cost +are set (an unset +.I deadline +will set +.I deadline +to +.IR period ), +perform a schedulability test and start scheduling the process as a real-time +process if the test succeeds. If the test fails, the +.B write +will fail with error set to the reason for failure. +.TP 10n +.B event +Add a user event to the +.B /proc/trace +file. +.PD +. +.SS Real-time scheduling +.I Real-time +processes are periodically +.IR released , +giving them a higher priority than non-real-time processes until they either +give up the processor voluntarily, they exhaust their CPU allocation, or they reach their +.IR deadline . +The moment of release is dictated by the +.I period +and whether the process is +.I sporadic +or not. +Non-sporadic processes are called +.I periodic +and they are released precisely at intervals of their period (but periods can be skipped +if the process blocks on I/O). +Sporadic processes are released whenever they become +runnable (after being blocked by +.IR sleep () +or I/O), but always at least an interval of +.I period +after the previous release. +.PP +The +.I deadline +of a real-time process specifies that the process must complete within the first +.I deadline +seconds of its +.IR period . +The dealine must be less than or equal to the period. +If it is not specified, it is set to the period. +.PP +The +.I cost +of a real-time process describes the maximum CPU time the process may use per period. +.PP +A real-time process can give up the CPU before its deadline is reached +or its allocation is exhausted. +It does this by calling +.IR sleep (0). +If +.I yieldonblock +is specified, it also does it by executing any blocking system call. +.I Yieldonblock +is assumed for +.I sporadic +processes. +.PP +Of the released processes, +the one with the earliest deadline has the highest priority. +Care should be taken using spin locks (see +.IR lock (2)) +because a real-time process spinning on a lock will not give up the processor until +its CPU allocation is exhausted; this is unlikely to be the desired behavior. +.PP +When a real-time process reaches its deadline or exhausts its CPU allocation, it remains +schedulable, but at a very low priority. +.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. +.SH FILES +.nf +.B /sys/src/9/*/mem.h +.B /sys/src/9/*/dat.h +.B /sys/include/trace.h +.fi +.SH SEE ALSO +.IR trace (1), +.IR debugger (2), +.IR mach (2), +.IR cons (3) +.SH SOURCE +.B /sys/src/9/port/devproc.c diff --git a/sys/man/3/root b/sys/man/3/root new file mode 100755 index 000000000..431ace960 --- /dev/null +++ b/sys/man/3/root @@ -0,0 +1,40 @@ +.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 contains +.B /boot/boot +and any files +.B /boot/boot +might need. +The kernel does an +.IR exec (2) +of +.B /boot/boot +when initializing. +.SH SOURCE +.B /sys/src/9/port/devroot.c diff --git a/sys/man/3/rtc b/sys/man/3/rtc new file mode 100755 index 000000000..da30231fe --- /dev/null +++ b/sys/man/3/rtc @@ -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/sys/man/3/sd b/sys/man/3/sd new file mode 100755 index 000000000..7de29617c --- /dev/null +++ b/sys/man/3/sd @@ -0,0 +1,254 @@ +.TH SD 3 +.SH NAME +sd \- storage device interface +.SH SYNOPSIS +.nf +.B bind #S /dev + +.B /dev/sdctl +.BI /dev/sd Cu /ctl +.BI /dev/sd Cu /raw +.BI /dev/sd Cu /data +\&... +.fi +.SH DESCRIPTION +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 taken to execute a command +.IP \- 3 +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. +.LP +Reading +.B /dev/sdctl +yields information about each controller, +one line per controller. +Writing `\fLconfig \fImessage\fR' to +.B /dev/sdctl +passes +.I message +to the legacy configuration machinery, +used to set attributes such as IRQ, port and size. +Writing `\fIctltype message\fR' to +.B /dev/sdctl +passes +.I message +to +.IR ctltype 's +.B wtopctl +function with a nil +.B sdev +argument, +where +.I ctltype +is a known controller type such as +.B ata +or +.BR scsi . +Writing `\c +.BI sd "ctlletter message\fR' +to +.B /dev/sdctl +passes +.I message +to +.BI sd ctlletter\fR's +.B wtopctl +function with an +.B sdev +argument corresponding to the named controller, +where +.I ctlletter +is a known controller letter such as +.B C +or +.BR 0 . +.SH SOURCE +.B /sys/src/9/port/devsd.c +.br +.B /sys/src/9/*/sd*.[hc] +.SH SEE ALSO +.IR scuzz (8) +.SH BUGS +LUNs (logical unit numbers) are not implemented. +For (S)ATA drives, +LUNs are not merely ignored but are actively +prevented from working except for INQUIRY commands. +.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/sys/man/3/sdahci b/sys/man/3/sdahci new file mode 100755 index 000000000..e76c3a5bb --- /dev/null +++ b/sys/man/3/sdahci @@ -0,0 +1,161 @@ +.TH SDAHCI 3 +.SH NAME +sdahci \- AHCI (Advanced Host Controller Interface) SATA (Serial ATA) storage device drivers +.SH SYNOPSIS +.nf +.B bind -a #S /dev +.sp 0.3v +.BI /dev/sdctl +.sp 0.3v +.BI /dev/sd En /ctl +.BI /dev/sd En /raw +.BI /dev/sd En /data +\&... +.fi +.SH DESCRIPTION +The +.I sdahci +driver provides access to AHCI devices via the +.IR sd (3) +interface. +The AHCI programming interface supports up to 32 +hot-swappable ATAPI or hard disk-like devices per controller. +The legacy IDE interface provided by +.B sdata.c +supports up to four drives which are not hot-swappable. +Controller drive letters are assigned from +.L E +onward. +.PP +AHCI controllers are detected automatically. +Currently Intel and AMD controllers are detected. +Intel controllers need to have AHCI enabled in the BIOS. +For +.L ich +parts this typically means enabling +enhanced mode and AHCI. +For ESB (Enterprise South Bridge) -based +parts, only enhanced mode needs to be enabled. +Intel +.BR ich9 -based +AHCI does not support hot swapping and +drives must be connected to the lowest-numbered free port. +.PP +The top level control file, +.BR /dev/sdctl , +supports the following control messages for +.IR sdahci : +.TF "\fLiahci idprint" +.TP +.B iahci debug +Toggle debug messages. Default is off. +.TP +.B iahci idprint +Toggle printing of drive identification messages. Default is on. +Prints short messages when a drive is identified or removed. +.TP +.B iahci aprint +Print verbose ATAPI debugging messages. Default is off. +.PD +.PP +The device-level +.B ctl +file supports: +.TF \fLsmartdisable +.TP +.B flushcache +Send the ATA/ATAPI +.B FLUSH CACHE +command +.RB ( 0xe7 +or +.BR 0xea ). +This command may take up to 60 seconds to complete. +.TP +.B identify +Send the ATA/ATAPI +.B IDENTIFY DEVICE +command +.RB ( 0xec ). +If device information has changed, the new size, +features and serial will be noted. +If changed, I/O on existing file +descriptors will result in the error string +.LR "media or partition has changed" . +.TP +.BI "mode " speed +Change the connection +.I speed +to one of +.BR auto , +.BR satai +or +.BR sataii . +.TP +.B nop +Send the ATA +.B NOP +command +.RB ( 0 ) +if the device supports it. Per standard, the result is always an error. +.TP +.B smart +Send the ATA/ATAPI +.B SMART RETURN STATUS +command +.RB ( 0xda ). +This will fail unless SMART is enabled on the drive. +.TP +.B smartdisable +Disable SMART on the drive. SMART is a persistent property of the drive. +.TP +.B smartenable +Enable SMART on the drive. +.TP +.BI "state " state +Force a transition to the named +.IR state . +The states are: +.RS +.TF portreset +.TP +.B null +ignored (may only be reached manually); +.TP +.B missing +not detected; +.TP +.B new +powered down or newly discovered; +.TP +.B ready +ready for commands; +.TP +.B reset +being reset gently; +.TP +.B portreset +being fully reset; +.TP +.B offline +device failed +.B portreset +(a port reset will be attempted periodically). +.RE +.PD +.PP +For devices present at boot, the transition is from state +.B new +to state +.BR ready . +.SH SOURCE +.B /sys/src/9/pc/sdiahci.c +.SH SEE ALSO +.IR sd (3), +.IR 9load (8) +.br +.BR http://download.intel.com/technology/serialata/pdf/rev1_2.pdf . +.SH BUGS +None of enclosure management, LED control and port multipliers are supported. +.PP +ATAPI devices may not be reset when they have outstanding commands. diff --git a/sys/man/3/sdaoe b/sys/man/3/sdaoe new file mode 100755 index 000000000..ebd95e936 --- /dev/null +++ b/sys/man/3/sdaoe @@ -0,0 +1,84 @@ +.TH SDAOE 3 +.SH NAME +sdaoe \- ATA-over-Ethernet (AoE) storage device interface +.SH SYNOPSIS +.nf +.B bind -a #S /dev +.BI "echo config switch on spec " l " type aoe//dev/aoe/" shelf\fB.\fPslot " >/dev/sdctl" +.BI "echo config switch off spec " l " >/dev/sdctl" +.sp 0.3v +.BI /dev/sd l 0/ctl +.BI /dev/sd l 0/raw +.BI /dev/sd l 0/data +\&... +.sp 0.3v +.fi +.B addaoe +.I letter +.I unit +.SH DESCRIPTION +.I Sdaoe +has a few quirks because +network-attached storage can't be enumerated as directly-attached storage can. +The default first controller letter for AoE devices is +.LR e . +Each +.B sdaoe +device must be configured explicitly. +.PP +.I Addaoe +packages up the +.L "switch on" +invocation as an +.I rc +script. +.PP +To boot from an AoE root, the +.B sd +device must be configured on boot by either PXE booting or +booting from directly-attached storage and adding two configuration lines to +.IR plan9.ini (8) +for +.BR aoeif , +listing the names of the Ethernet interface(s) to use, +and +.BI aoedev= letter !#æ/aoe/ lun. +.SH EXAMPLES +To configure target (LUN) +.B 42.0 +on +.BR #S/sde0 , +.IP +.EX +echo config switch on spec e type aoe//dev/aoe/42.0 >/dev/sdctl +.EE +.PP +To turn this device off, +.IP +.EX +echo config switch off spec e >/dev/sdctl +.EE +.PP +To boot using target +.B 42.0 +as +.B #S/sde0 +and as root, +over Ethernet interfaces 0 and 1, +.IP +.EX +aoeif=ether0 ether1 +aoedev=e!#æ/aoe/42.0 +.EE +.SH SOURCE +.B /sys/src/9/port/sdaoe.c +.SH SEE ALSO +.\" .IR vblade (1), +.IR aoe (3), +.IR sd (3), +.IR 9load (8), +.\" .IR cec (8), +.IR snoopy (8) +.SH BUGS +It is not currently possible to boot from an AoE target without an +external bootstrap like PXE. diff --git a/sys/man/3/segment b/sys/man/3/segment new file mode 100755 index 000000000..1a8e5e71e --- /dev/null +++ b/sys/man/3/segment @@ -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/sys/man/3/srv b/sys/man/3/srv new file mode 100755 index 000000000..820c849db --- /dev/null +++ b/sys/man/3/srv @@ -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/sys/man/3/ssl b/sys/man/3/ssl new file mode 100755 index 000000000..2b3944d14 --- /dev/null +++ b/sys/man/3/ssl @@ -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/sys/man/3/tls b/sys/man/3/tls new file mode 100755 index 000000000..99f470d90 --- /dev/null +++ b/sys/man/3/tls @@ -0,0 +1,273 @@ +.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), +.IR pushtls (2) +.SH SOURCE +.B /sys/src/9/port/devtls.c diff --git a/sys/man/3/twsi b/sys/man/3/twsi new file mode 100755 index 000000000..4fd311d4f --- /dev/null +++ b/sys/man/3/twsi @@ -0,0 +1,30 @@ +.TH TWSI 3 +.SH NAME +twsi - two-wire serial interface (TWSI) and inter-integrated circuit (I⁲C) interface +.SH SYNOPSIS +.B bind -a #⁲ /dev +.sp 0.3v +.B /dev/twsi* +.SH DESCRIPTION +The +.I twsi +device serves a one-level directory containing one file per TWSI or I⁲C bus. +Bytes written are transmitted on the bus; +bytes received from the bus are queued and delivered by reading. +Seeking to a given offset before reading or writing causes the +.I twsi +device to use that offset as a TWSI slave address for a subsequent +.IR read (2) +or +.IR write +call. +.SH FILES +.B #⁲/twsi* +.SH SOURCE +.B /sys/src/9/*/devtwsi.c +.SH BUGS +10-bit addressed devices are not supported. +.PP +No slave mode. +.PP +Setting the bus rate is not supported. diff --git a/sys/man/3/uart b/sys/man/3/uart new file mode 100755 index 000000000..f8eb38346 --- /dev/null +++ b/sys/man/3/uart @@ -0,0 +1,135 @@ +.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 c n +Set hangup on DCD if +.I n +is non-zero; else clear it. +.TP +.BI d n +Set DTR if +.I n +is non-zero; +else clear it. +.TP +.BI e n +Set hangup on DSR if +.I n +is non-zero; else clear it. +.TP +.B f +Flush output queue. +.TP +.B h +Close input and output queues. +.TP +.BI i n +Enable/disable the FIFOs. +If +.I n +is zero the FIFOs are disabled; +otherwise +.I n +is taken as a trigger level for the FIFOs. +The trigger levels supported are device dependant, +but usually include 1, 4 and 8. +An unrecognised, +but non-zero, +value of +.I n +causes the maximum-supported trigger level to be set. +.TP +.BI k n +Send a break lasting +.I n +milliseconds. +.TP +.BI l n +Set number of bits per byte to +.IR n . +Legal values are 5, 6, 7, or 8. +.TP +.BI m n +Obey modem CTS signal if +.I n +is non-zero; +else clear it. +.TP +.B n +Make writes non-blocking. +.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 q n +Set input and output queue limits to +.IR n . +.TP +.BI r n +Set RTS if +.I n +is non-zero; +else clear it. +.TP +.BI s n +Set number of stop bits to +.IR n . +Legal values are 1 or 2. +.TP +.BI w n +Set the uart clock timer to +n times 100us. +.IP +.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/sys/man/3/usb b/sys/man/3/usb new file mode 100755 index 000000000..a79132ba0 --- /dev/null +++ b/sys/man/3/usb @@ -0,0 +1,535 @@ +.TH USB 3 +.EQ +delim $$ +.EN +.SH NAME +usb \- USB Host Controller Interface +.SH SYNOPSIS +.nf +.B bind -a #u /dev +.PP +.nf +.B /dev/usb +.B /dev/usb/ctl +.BI /dev/usb/ep N . M +.BI /dev/usb/ep N . M /data +.BI /dev/usb/ep N . M /ctl +\&... +.fi +.SH DESCRIPTION +The Universal Serial Bus is a complex yet popular bus +for connecting all kind of devices to a computer. +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 . +Hubs provide ports where USB devices (also hubs) can be attached. +.PP +Most PCs have one or more USB controllers called +.I host +controllers. +Each one has a built-in hub called a +.I "root hub" +providing several ports. +In some cases, more hubs are built-in +and attached to a root hub port. +The topology of the network is a tree with at most +127 nodes, counting both internal and leaf nodes. +.PP +Host controllers come in four flavours: +UHCI and OHCI for USB 1 (up to 12 Mb/s), +EHCI for USB 2 (up to 480 Mb/s) +and +XHCI for USB 3 (up to 5 Gb/s). +We currently support all but XHCI, which is still quite new. +.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 +Devices may be added to or removed from the bus at any time. +When a device is attached, the host queries it to determine its type and 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 +Enumeration of the bus and initial configuration of devices is done +by a user level program, +.IR usbd (4). +Device drivers are implemented by separate user programs, although +some of them may be statically linked into +.IR usbd . +.PP +The kernel device described in this page is responsible for providing +I/O for using the devices through so called +.IR endpoints . +Access to the host controller is hidden from user programs, which see +just a set of endpoints. +After system initialization, some endpoints +are created by the device to permit I/O to root hubs. +All other devices must be configured by +.IR usbd . +.SS Devices and Endpoints +A device includes one or more functions (e.g., audio output, +volume control buttons, mouse input, etc.) +Communication with device functions is performed +by some combination of +issuing control requests to, sending data to, and receiving data from +device +.IR endpoints . +Endpoints can be understood as addresses in the bus. +There are several types: +.TF "\fIIsochronous +.TP +.I Control +Their main use is to configure devices. +Writing a message with a specific format +(specified in the USB specification) +issues a request to the device. +If the request implies a reply, +a read can be made next to retrieve the requested data (if the write succeeded). +.TP +.I Interrupt +Used to send and receive messages to or from a specific device function +(e.g., to read events from a mouse). +.TP +.I Bulk +Used to send and receive larger amounts of data through streams +(e.g., to write blocks to a disk). +.TP +.I Isochronous +Used to send and receive data in a timely manner +(e.g., to write audio samples to a speaker). +.PD +.PP +All USB devices include at least +a control endpoint to perform device configuration. +This is called the +.I setup +endpoint or +.IR "endpoint zero" . +After configuring a device, other endpoints may be created +as dictated by the device to perform actual I/O. +.SS Operation +Bus enumeration and device configuration is performed by +.IR usbd (4) +and not by this driver. +The driver provides an interface +to access existing endpoints (initially those for the built-in root hubs), +to create and configure other ones, and to perform I/O through them. +.PP +Each directory +.BI /dev/usb/ep N . M +represents an endpoint, where +.I N +is a number identifying a device and +.I M +is a number identifying one of its endpoints. +.PP +For each device attached to the bus, and configured by +.IR usbd (4), +an endpoint zero (a +.I setup +endpoint) +is provided at +.BI /dev/usb/ep N .0 +for configuring the device. +This is always a control endpoint and represents the device itself. +.PP +The device driver may use the setup endpoint +to issue control requests and perhaps to create more endpoints for the device. +Each new endpoint created has its own directory as said above. +For example, if the driver for the device +.BI /dev/usb/ep N . 0 +creates the endpoint number 3 for that device, a directory +.BI /dev/usb/ep N .3 +will be available to access that endpoint. +.PP +All endpoint directories contain two files: +.B data +and +.BR ctl . +The former has mode bit +.B DMEXCL +set and can be open by only one process at a time. +.SS data +.PP +The +.B data +file is used to perform actual I/O. +In general, reading from it retrieves +data from the endpoint and writing into it sends data to the endpoint. +For control endpoints, writing to this file issues a control request +(which may include data); if the request retrieves data from the device, +a following read on the file will provide such data. +.PP +USB errors reported by the endpoint upon I/O failures +are passed to the user process through the error string. +I/O stalls not resulting from an error, usually +an indication from the device, are reported by indicating that the +number of bytes transferred has been zero. +In most cases, the correct course of action after noticing the stall +is for the device driver to issue a `clear halt' request (see +.I unstall +in +.IR usb (2)) +to resume I/O. +The most common error is +.L crc/timeout +indicating problems in communication with the device (eg., a physical +detach of the device or a wiring problem). +.PP +For control and isochronous transfers, there is an implicit +timeout performed by the kernel and it is not necessary for applications +to place their own timers. +For other transfer types, the kernel will not time out any operation +by default +(but see the +.L timeout +control request). +.SS "ctl and status" +.PP +The +.B ctl +file can be read to learn about the endpoint. +It contains information that can be used +to locate a particular device (or endpoint). +It also accepts writes with textual control requests described later. +.PP +This may result from the read of an endpoint control file: +.IP +.EX +.I "(the first line is wrapped to make it fit here)" +.ft L +enabled control rw speed full maxpkt 64 pollival 0 + samplesz 0 hz 0 hub 1 port 3 busy +storage csp 0x500608 vid 0x951 did 0x1613 Kingston 'DT 101 II' +.ft +.EE +.LP +The first line contains status information. +The rest is information supplied by +.IR usbd (4) +as an aid to locate devices. +The status information includes: +.TF "\fREndpoint mode +.PD +.TP +Device state +One of +.BR config , +.BR enabled , +and +.BR detached . +An endpoint starts in the +.B config +state, and accepts control commands written to its +.B ctl +file to configure the endpoint. +When configured, the +state is +.B enabled +and the +.B data +file is used as described above (several control requests can still +be issued to its +.B ctl +file, but most will not be accepted from now on). +Upon severe errors, perhaps a physical +detachment from the bus, the endpoint enters the +.B detached +state and no further I/O is accepted on it. +Files for an endpoint (including its directory) +vanish when the device is detached and its files are no longer open. +Root hubs may not be detached. +.TP +Endpoint type +.BR control , +.BR iso , +.BR interrupt , +or +.BR bulk , +indicating the type of transfer supported by the endpoint. +.TP +Endpoint mode +One of +.BR r , +.BR w , +or +.BR rw , +depending on the direction of the endpoint (in, out, or inout). +.TP +Speed +.BR low +(1.5 Mb/s), +.BR full +(12 Mb/s), +or +.BR high +(480 Mb/s). +.TP +Maximum packet size +Used when performing I/O on the data file. +.TP +Polling interval +The polling period expressed as a number of µframes +(for high-speed endpoints) or frames (for low- and full-speed endpoints). +Note that a µframe takes 125 µs while a frame takes 1 ms. +This is only of relevance for interrupt and isochronous endpoints. +This value determines how often I/O happens. +Note that the control request adjusting the polling interval does +.I not +use these units, to make things easier for USB device drivers. +.TP +Sample size +Number of bytes per I/O sample (isochronous endpoints only). +.TP +Frequency +Number of samples per second (Hertz). +.TP +Hub address +Device address of the hub where the device is attached. +.TP +Port number +Port number (in the hub) where the device is attached. +.TP +Usage +.L busy +while the data file is open and +.L idle +otherwise. +This is useful to avoid disturbing endpoints already run +by a device driver. +.LP +The second line contains information describing the device: +.TF "\fRDevice strings +.PD +.TP +Class name +As provided by the device itself. +.TP +CSP +Class, Subclass, and Protocol for the device. +If the device contains different functions and has more CSPs, +all of them will be listed. +The first one is that of the device itself. +For example, +a mouse and keyboard combo may identify itself as a keyboard but +then include two CSPs, one for the keyboard and another one for the mouse. +.TP +Vid and Did +Vendor and device identifiers. +.TP +Device strings +Provided by the device and identifying the manufacturer and type of device. +.LP +For example, to find a mouse not yet in use by a driver, scan the +.B ctl +files for +.BR enabled , +.BR idle , +and +.BR "csp 0x020103" . +A mouse belongs to class 3 (in the least significant byte), +.IR "human interface device" , +subclass 1, +.IR boot , +protocol 2, +.I mouse +(protocol 1 would be the keyboard). +USB class, subclass and proto codes can be found at +.BR http://www.usb.org . +.SS Control requests +Endpoint control files accept the following requests. +In most cases +the driver does not issue them, leaving the task to either +.IR usbd (4) +or the usb driver library documented in +.IR usb (2). +.TF "\fLsamplehz\fI n +.TP +.B detach +Prevent further I/O on the device (delete the endpoint) +and remove its file interface as soon as no process is using their files. +.TP +.BI maxpkt " n" +Set the maximum packet size to +.I n +bytes. +.TP +.BI pollival " n" +Only for interrupt and isochronous endpoints. +Set the polling interval as a function of the value +.I n +given by the endpoint descriptor. +The interval value used is the period +.I n +in bus time units for low- and full-speed interrupt endpoints. +Otherwise, the actual interval is +$2 sup n$ +and not +.IR n . +Bus time units are 1 ms for low- and full-speed endpoints and 125 µs for +high-speed endpoints. +In most cases, the device driver may ignore +all this and issue the control request supplying the +polling interval value as found +in the endpoint descriptor. +The kernel adjusts the value according +to the endpoint configuration and converts it into the number of +frames or µframes between two consecutive polls. +.TP +.BI samplesz " n" +Use +.I n +as the number of bytes per sample. +.TP +.BI hz " n" +Use +.I n +as the number of samples per second. +.TP +.BI ntds " n" +Use +.I n +as the number of transactions per frame (or µframe), as reported +by the descriptor. +.TP +.B clrhalt +Clear the halt condition for an endpoint. +Used to recover from a stall caused by a device to signal its driver +(usually due to an unknown request or a failure to complete one). +.TP +.BI info " string" +Replaces description information in +.B ctl +with +.IR string . +.IR Usbd (4) +uses this to add device descriptions. +.TP +.B address +Tell this driver that the device has been given an address, +which causes the device to enter the +.I enabled +state. +.TP +.BI name " str" +Generates an additional file name, +.I str , +for the +.B data +file of the endpoint. +This file name appears in the root directory of the +.L #u +tree. +For example, this is used by the audio device +driver to make the +.B data +file also available as +.BR /dev/audio . +.TP +.BI debug " n" +Enable debugging of the endpoint. +.I N +is an integer; +larger values make diagnostics more verbose. +.L 0 +stops debugging diagnostics. +.L 1 +causes just problem reports. +Bigger values report almost everything. +.TP +.BI timeout " n" +Enable time-outs for the endpoint. +Transfers are timed out by the kernel after +.I n +ms. +This should not be used for control and isochronous endpoints, +which are always timed out. +.PD +.LP +Setup endpoints +(those represented by +.BI ep N .0 +directories) +also accept the following requests: +.TP +.BI new " n type mode" +Creates a new endpoint with number +.I n +of the given +.IR type +(\c +.BR ctl , +.BR bulk , +.BR intr , +or +.BR iso ). +.I Mode +may be +.BR r , +.BR w , +or +.BR rw , +which creates, respectively, an input, output, or input/output endpoint. +.TP +.B "speed {low|full|high} +Set the endpoint speed to full, low, or high, respectively. +.TP +.B hub +Tell this driver that the endpoint corresponds to a hub device. +.PD +.PP +Setup endpoints for hub devices also accept his request: +.TP +.B "newdev {low|full|high} \fIport\fP +Create a new setup endpoint to represent a new device. +The first argument is the device speed. +.I Port +is the port number where the device is attached +(the hub is implied by the endpoint where the control request is issued). +.PD +.PP +The file +.B /dev/usb/ctl +provides all the information provided by the various +.B ctl +files when read. +It accepts several requests that refer to +the entire driver and not to particular endpoints: +.TF "\fLdebug \fIn" +.TP +.B "debug \fIn\fP +Sets the global debug flag to +.IR n . +.TP +.B dump +Dumps data structures for inspection. +.SH FILES +.TF #u/usb +.TP +.B #u/usb +root of the USB interface +.SH SOURCE +.B /sys/src/9/pc/usb.h +.br +.B /sys/src/9/pc/devusb.c +.br +.B /sys/src/9/pc/usb?hci.c +.SH "SEE ALSO" +.IR usb (2), +.IR usb (4), +.IR usbd (4), +.IR plan9.ini (8) +.SH BUGS +USB controllers limit the speed of all their ports +to that of the slowest device connected to any one of them. +.PP +Isochronous input streams are not implemented for OHCI. +.PP +Some EHCI controllers drop completion interrupts and so must +be polled, which hurts throughput. diff --git a/sys/man/3/vga b/sys/man/3/vga new file mode 100755 index 000000000..3910f45ab --- /dev/null +++ b/sys/man/3/vga @@ -0,0 +1,254 @@ +.TH VGA 3 +.SH NAME +vga \- VGA controller device +.SH SYNOPSIS +.nf +.B bind #v /dev + +.B /dev/vgabios +.B /dev/vgactl +.B /dev/vgaovl +.B /dev/vgaovlctl +.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 +.B Vgabios +provides read-only access to the low 640kB of memory, +where the VGA and other BIOS ROMs are located. +.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 nvidia , +.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 nvidiahwgc , +.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. +.PP +Some VGA cards support overlay graphics. +Writing strings to +.B vgaovlctl +configures such cards. +The following are valid overlay control commands: +.TP +.BI openctl +opens the overlay device. +.TP +.BI configure " w h format" +allocates resources inside the driver to support an overlay area +of width +.I w +and height +.I h +pixels. Currently, the only supported +.I format +is +.B YUYV +packed. +In +.B YUYV +two pixels are encoded by their separate Y values +and their combined U and V values. +The size of the two pixels is 32 bits. +.TP +.BI enable " x y w h" +enables drawing data on the display through the overlay mode. The data +is drawn at position +.IR x , y +and has a width and height of +.IR w , h +respectively. +.TP +.BI closectl +terminates overlay control. +.PP +Overlay data can be written to +.BR vgaovl . +.SH EXAMPLES +The following disables hardware acceleration. +.IP +.EX +echo 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 +The hardware graphics cursor on the +.B et4000 +does not work in 2x8-bit mode. diff --git a/sys/man/4/0intro b/sys/man/4/0intro new file mode 100755 index 000000000..8a3a6a3dd --- /dev/null +++ b/sys/man/4/0intro @@ -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/sys/man/4/INDEX b/sys/man/4/INDEX new file mode 100755 index 000000000..cc3639010 --- /dev/null +++ b/sys/man/4/INDEX @@ -0,0 +1,91 @@ +0intro 0intro +intro 0intro +acme acme +archfs archfs +cddb cdfs +cdfs cdfs +cfs cfs +cifs cifs +C consolefs +clog consolefs +consolefs consolefs +cwfs cwfs +9660srv dossrv +9fat: dossrv +a: dossrv +b: dossrv +c: dossrv +d: dossrv +dosmnt dossrv +dossrv dossrv +eject dossrv +execnet execnet +exportfs exportfs +srvfs exportfs +ext2srv ext2srv +factotum factotum +fgui factotum +flashfs flashfs +flchk fossil +flfmt fossil +fossil fossil +fs fs +ftpfs ftpfs +httpfile httpfile +import import +iostats iostats +keyfs keyfs +warning keyfs +kfs kfs +lnfs lnfs +mntgen mntgen +namespace namespace +nfs nfs +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 +srvssh srv +32vfs tapefs +cpiofs tapefs +tapefs tapefs +tapfs tapefs +tarfs tapefs +tpfs tapefs +v10fs tapefs +v6fs tapefs +zipfs tapefs +fax telco +faxreceive telco +faxsend telco +telco telco +telcodata telco +telcofax telco +u9fs u9fs +upasfs upasfs +audio usb +ccid usb +disk usb +ether usb +kb usb +print usb +probe usb +serial usb +usb usb +usbeject usb +usbfat: usb +usbd usbd +vacfs vacfs +webcookies webcookies +webfs webfs +wikifs wikifs +wikipost wikifs diff --git a/sys/man/4/INDEX.html b/sys/man/4/INDEX.html new file mode 100755 index 000000000..36466a687 --- /dev/null +++ b/sys/man/4/INDEX.html @@ -0,0 +1,193 @@ + +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 +- optical disc (CD, DVD, BD) track reader and writer file system +
cdfs, cddb + +
cfs +- cache file system +
cfs + +
cifs +- Microsoft™ Windows network filesystem client +
cifs + +
consolefs +- file system for console access +
consolefs, C, clog + +
cwfs +- cached-worm file server, dump +
cwfs + +
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 + +
ext2srv +- ext2 file system +
ext2srv + +
factotum +- authentication agent +
factotum, fgui + +
flashfs +- journalling file system for flash memory +
flashfs + +
fossil +- archival file server +
fossil, flchk, flfmt + +
fs +- file server, dump +
fs + +
ftpfs +- file transfer protocol (FTP) file system +
ftpfs + +
httpfile +- serve a single web file +
httpfile + +
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 + +
mntgen +- automatically generate mount points for file systems +
mntgen + +
namespace +- structure of conventional file name space +
namespace + +
nfs +- Sun network file system client +
nfs + +
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, srvssh + +
tapefs +- mount archival file systems +
32vfs, cpiofs, tapfs, tarfs, tpfs, v6fs, v10fs, zipfs + +
telco +- telephone dialer network +
telco, faxreceive, faxsend, fax, telcofax, telcodata + +
u9fs +- serve 9P from Unix +
u9fs + +
upasfs +- mail file server +
upasfs + +
usb +- Universal Serial Bus device drivers +
audio, ccid, disk, ether, kb, print, probe, serial, usbeject, usbfat: + +
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/sys/man/4/acme b/sys/man/4/acme new file mode 100755 index 000000000..a2e68ddf1 --- /dev/null +++ b/sys/man/4/acme @@ -0,0 +1,458 @@ +.TH ACME 4 +.SH NAME +acme \- control files for text windows +.SH SYNOPSIS +.B acme +[ +.B -ab +] +[ +.B -c +.I ncol +] +[ +.B -f +.I varfont +] +[ +.B -F +.I fixfont +] +[ +.B -l +.I file +| +.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, formatted as 2 decimal numbers +.I m +and +.IR n , +each formatted in 11 characters plus a blank. +.I M +and +.I n +are the character (not byte) offsets of the +beginning and end of the address, +which would be expressed in +.I acme 's +input language as +.BI # m ,# n \fR. +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 three more fields: the width of the +window in pixels, the name of the font used in the window, +and the width of a tab character in pixels. +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 +.B menu +Maintain +.BR Undo , +.BR Redo , +and +.B Put +in the left half of the tag. +(This is the default for file windows.) +.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 nomenu +Do not maintain +.BR Undo , +.BR Redo , +and +.B Put +in the left half of the tag. +(This is the default for directory and error windows.) +.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 errors +Writing to the +.B errors +file appends to the body of the +.IB dir /+Errors +window, where +.I dir +is the directory currently named in the tag. +The window is created if necessary, +but not until text is actually written. +.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. +.TP +.B xdata +The +.B xdata +file like +.B data +except that reads stop at the end address. +.SH SOURCE +.B /sys/src/cmd/acme +.SH SEE ALSO +.IR rio (1), +.IR acme (1), +.IR cons (3). diff --git a/sys/man/4/archfs b/sys/man/4/archfs new file mode 100755 index 000000000..0ba744c58 --- /dev/null +++ b/sys/man/4/archfs @@ -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/sys/man/4/cdfs b/sys/man/4/cdfs new file mode 100755 index 000000000..b038f2f3c --- /dev/null +++ b/sys/man/4/cdfs @@ -0,0 +1,261 @@ +.TH CDFS 4 +.SH NAME +cdfs, cddb \- optical disc (CD, DVD, BD) track 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 +.br +.B aux/cddb +[ +.B -DTt +] [ +.B -s +.I server +] +.B query +.I diskid +.I ntracks +.I track0id +.I ... +.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 discs placed in the disc reader or writer +named by +.I sddev +(default +.BR /dev/sdD0 , +see +.IR sd (3)). +Any MMC-compliant compact disc (CD), DVD, +or Blu-ray disc (BD) drive should work. +On DVDs and BDs, access to data tracks only is implemented. +.PP +The top level directory contains one file +per disc 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 can write discs +and contains a writable disc, the top-level +directory also contains an empty directory +.B wd +and, for CDs only, +an empty directory +.BR wa . +Files created in these directories +appear in the top-level directory +as new data or audio tracks, respectively, 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 disc track is a quasi-real-time operation: +the disc writer should be kept saturated with +new data to avoid buffer underruns, +but modern drives will be told to cope with underruns transparently. +To ensure saturation, copying from a file system +stored on local disk or memory is recommended. +.PP +To fixate a disc (close a recordable disc by writing +its permanent table of contents), simply +remove the +.B wa +or +.B wd +directory. +The directory removed selects whether +the disc is fixated as an audio or data disc; +since each track carries its own type information, +very few readers care which fixation type was used. +Rewritable discs do not require fixation. +.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 format +Format the rewritable disc (\c +.B -RW +or +.BR -RE ) +in the drive +before initial use. +.TP +.B blank +Blank the entire rewritable disc in the drive. +.TP +.B quickblank +Blank only the table of contents on the rewritable +disc in the drive. +.\" .TP +.\" .B closetracks +.\" Close any open tracks on the current disc but do not finalize (fixate) the disc. +.TP +.B eject +Eject the disc in the drive. +.TP +.B ingest +Ingest a disc into the drive. +.TP +.B speed \fIkbps\fR +Set the reading and writing speed to use, +in units of 1,000-bytes-per-second. +A value of +.L best +requests the optimal speed for the current drive and disc. +CD +.L 1x +speed is 154; +DVD +.L 1x +speed is 1350; +BD +.L 1x +speed is 4608. +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 disc 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. +Additional lines may further describe the current disc. +.PP +.I Aux/cddb +takes 4 optional arguments. +The +.B -s +option makes +.I aux/cddb +use +.I server +for the query instead of +.LR freedb.freedb.org . +The +.B -D +option causes the raw database response from the server to be dumped +to standard output. +The +.B -t +option causes the time of each track to be appended to the normal output. +.B -T +is like +.B -t +but prints a final line with the total time. +.SH EXAMPLES +Backup to a BD-R disc: +.br +.ne 3 +.IP +.EX +9fs boot +cdfs +tar cf /mnt/cd/wd/x /n/boot +.EE +.br +.ne 3 +.PP +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 +.SH SOURCE +.B /sys/src/cmd/cdfs +.SH SEE ALSO +.IR sd (3), +.I 9660srv +(in +.IR dossrv (4)), +.IR mk9660 (8) +.PD 0 +.TF "\fLhttp://www.t10.org\fP" +.TP +.B http://www.t10.org +optical disc interface standards +.PD +.SH BUGS +Fixating a BD-R disc records only the first track in the disc's TOC. +Any other tracks are still there and their data accessible via +.IR sd (3). +There's no need to fixate data discs, except to prevent adding new tracks. +.PP +Closing a just-written DVD-R track can take minutes +while the drive burns the unused part of the track reservation +(for the whole disc). +Thus only a single DVD-R track can be written on a DVD-R disc; +use other media if you need more than one track per disc. +.PP +There are too many combinations of optical media, each with unique quirks, +approximately +the cross-product of these tuples: +(CD DVD- DVD+ BD), +(single-layer dual-layer), +(-ROM -R -RW). +.PP +Only MMC-compliant disc readers and writers +are supported, but it would be easy to add +support for early CD writers if desired. diff --git a/sys/man/4/cfs b/sys/man/4/cfs new file mode 100755 index 000000000..7d466e1e0 --- /dev/null +++ b/sys/man/4/cfs @@ -0,0 +1,124 @@ +.TH CFS 4 +.SH NAME +cfs \- cache file system +.SH SYNOPSIS +.B cfs +.B -s +.RB [ -dknrS ] +.RB [ -f +.IR partition ] +.PP +.B cfs +.B -a +.I netaddr +.RB [ -dknrS ] +.RB [ -f +.IR partition ] +.RI [ mtpt ] +.PP +.B cfs +.B -F +.I srvfile +.RB [ -dknrS ] +.RB [ -f +.IR partition ] +.RI [ mtpt ] +.SH DESCRIPTION +.I Cfs +is a user-level file server that caches data from 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: +.TF - +.PD +.TP +.BI "a " netaddr +dial the destination +.I netaddr +to connect to a remote file server. +Exclusive with +.BR -F . +.TP +.B d +turn on debugging. +.TP +.BI "f " partition +use file +.I partition +as the cache disk partition. +.TP +.BI "F " srvfile +open +.I srvfile +(often a file under +.BR /srv ) +to connect to a remote file server. +Exclusive with +.BR -a . +.TP +.B k +keep cache contents even if they might have come from a different server. +.I Cfs +will obey +.B -r +even if +.B -k +is given. +.TP +.B n +mount the remote file server without authentication; +often useful with +.BR -F . +.TP +.B r +reformat the cache disk partition. +.TP +.B s +the connection to the remote file server is on file +descriptors 0 and 1. +.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. +.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. +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/sys/man/4/cifs b/sys/man/4/cifs new file mode 100755 index 000000000..f53cf1f1b --- /dev/null +++ b/sys/man/4/cifs @@ -0,0 +1,188 @@ +.TH CIFS 4 +.SH NAME +cifs - Microsoft™ Windows network filesystem client +.SH SYNOPSIS +.B cifs +[ +.B -bdDiv +] [ +.B -a +.I auth-method +] [ +.B -s +.I srvname +] [ +.B -n +.I called-name +] [ +.B -k +.I keyparam +] [ +.B -m +.I mntpnt +] +.I host +[ +.I share ... +] +.SH DESCRIPTION +.I Cifs +translates between Microsoft's file-sharing protocol +(a.k.a. CIFS or SMB) and 9P, allowing Plan9 clients to mount file systems +(shares or trees in MS terminology) published by such servers. +.PP +The root of the mounted directory contains one subdirectory per share, +always named in lower case, and a few virtual files of mixed case which +give additional server, session, share, and user information. +The arguments are: +.TF "-a\fI auth-method" +.PD +.TP +.BI -a " auth-method" +.I Cifs +authenticates using +.L BNTLM +by default, but alternative strategies may be +selected using this option. +.I Cifs +eschews cleartext authentication, however +it may be enabled with the +.L plain +auth method. +The list of currently-supported methods is printed +if no method name is supplied. +.IP +.I "Windows server 2003" +requires the +.B BNTLMv2 +method by default, though it can be configured to be more flexible. +.TP +.B -b +Enable file ownership resolution in +.IR stat (2) +calls. +This requires an open and close per file and thus will slow +.I cifs +considerably; its use is not recommended. +.TP +.B -d +CIFS packet debug. +.TP +.B -D +9P request debug. +.TP +.BI -k " keyparam" +lists extra parameters which will be passed to +.IR factotum (4) +to select a specific key. +The remote servers's domain is always included in the keyspec, +under the assumption +that all servers in a Windows domain share an authentication domain; +thus +.I cifs +expects keys in +.I factotum +of the form: +.RS +.IP +.EX +key proto=pass dom=THEIR-DOMAIN service=cifs + user=MY-USERNAME !password=XYZZY +.EE +.RE +.TP +.BI -m " mntpnt" +set the mount point for the remote filesystem; +the default is +.BI /n/ host. +.TP +.BI -n " called-name" +The CIFS protocol requires clients to know the NetBios name of the +server they are attaching to, the +.IR Icalled-name . +If this is not specified on the command line, +.I cifs +attempts to discover this name from the remote server. +If this fails it will then try +.IR host , +and finally it will try the name +.LR *SMBSERVER . +.TP +.BI -s " srvname" +post the service as +.BI /srv/ srvname. +.TP +.I host +The address of the remote server to connect to. +.TP +.I share +A list of share names to attach on the remote server; if none is given, +.I cifs +will attempt to attach all shares published by the remote host. +.SS "Synthetic Files" +Several synthetic files appear in the root of the mounted filesystem: +.TF Workstations +.PD +.TP +.B Shares +Contains a list of the currently attached shares, +with fields giving the share name, disk free space / capacity, the share type, +and a descriptive comment from the server. +.TP +.B Connection +Contains the username used for authentication, +server's called name, server's domain, +server's OS, the time slip between the local host and the server, +the Maximum Transfer Unit (MTU) the server requested, and optionally a flag +indicating only guest access has been granted. +The second line contains a list of capabilities offered by the server which is +mainly of use for debugging +.IR cifs . +.TP +.B Users +Each line contains a user's name, the user's full name, +and a descriptive comment. +.TP +.B Groups +Each line gives a group's name, and a list of the names of the users who +are members of that group. +.TP +.B Sessions +Lists the users authenticated, the client machine's NetBios name or IP address, +the time since the connection was established, +and the time for which the connection has been idle. +.TP +.B Domains +One line per domain giving the domain name and a descriptive comment. +.TP +.B Workstations +One line per domain giving the domain name and a descriptive comment, +the version number of the OS it is running, and comma-separated list of flags +giving the features of that OS. +.TP +.B Dfsroot +Top level DFS routing giving the DFS link type, time to live of the data, +proximity of the server, the Netbios or DNS name and +a physical path or a machine that this maps to. +.IP +DNS paths are usually assigned dynamicially as a form of load balancing. +.SH SOURCE +.B /sys/src/cmd/cifs +.SH SEE ALSO +.IR factotum (4), +.IR aquarela (8) +.SH BUGS +NetApp Filer compatibility has not yet been tested; there may not be any. +.PP +DFS support is unfinished. +.PP +Kerberos authentication is unfinished. +.PP +NetBios name resolution is not supported, though it is now rarely used. +.PP +.I Cifs +has only been tested against +.IR aquarela (8), +Windows 95, NT4.0sp6, +Windows server 2003, WinXP pro, Samba 3.0, and Samba 2.0 (Pluto VideoSpace). +No support is attempted for servers predating NT 4.0. diff --git a/sys/man/4/consolefs b/sys/man/4/consolefs new file mode 100755 index 000000000..104da9021 --- /dev/null +++ b/sys/man/4/consolefs @@ -0,0 +1,253 @@ +.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 device +associated with it. +.I Consolefs +presents a single level directory with up to three files +per console: +.IR console , +.IB console ctl\f1, +and +.IB console stat\f1. +Writes of +.I console +are equivalent to writes of +.I dev +and reads and writes of +.IB console ctl +and +.IB console stat +are equivalent to reads and writes of +.IB dev ctl +and +.IB dev stat +respectively. +.IB Console ctl +and +.IB console stat +will not exist if the underlying +.I dev +does not provide them. +.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. +The +.I openondemand= +attribute causes the console device +.RI ( dev ) +to be opened only when the corresponding +.IB mntpt / console +file is open. +.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 +% cat /lib/ndb/consoledb +group=sys + uid=glenda +console=bootes dev=/dev/eia0 gid=sys +console=fornax dev=/dev/eia1 gid=sys +% 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 +.PP +The console server's default name space must +mount the consoles for +.I C +to import. +This can be arranged by adding +.IP +.EX +mount /srv/consoles /mnt/consoles +.EE +.LP +to +.BR /lib/namespace.$sysname . +.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 consolefs +is running +is detected by +.IR consolefs . +However, to add new consoles +one must restart +.IR consolefs . diff --git a/sys/man/4/cwfs b/sys/man/4/cwfs new file mode 100755 index 000000000..6bf6c7b27 --- /dev/null +++ b/sys/man/4/cwfs @@ -0,0 +1,317 @@ +.TH CWFS 4 +.SH NAME +cwfs \- cached-worm file server, dump +.SH SYNOPSIS +.B cwfs +[ +.B -cf +] [ +.B -a +.I announce-string +] ... [ +.B -m +.I device-map +] +.I config-device +.SH DESCRIPTION +.I Cwfs +is a cached-worm file server that runs +as a user-mode program and can +maintain file systems created by +.IR fs (4), +the original Plan 9 file server +that had its own kernel and operated +a standalone system with disks and +optical-disc jukebox attached. +Unlike +.IR fs (4), +which could only accept 9P connections over IL/IPv4 on Ethernets +(or over Datakit and Cyclones, long ago), +.I cwfs +accepts 9P connections over any network medium and protocol +that it can announce on, +by default TCP (over IPv4 or IPv6). +Given suitable 9P clients, +one could even run 9P over +.IR aan (8) +or +.IR tls (3). +.PP +The stock +.I cwfs +implements a 16K file system block size +and 32-bit disk addresses, +in order to be compatible with some existing file systems, notably +.IR emelie 's. +These parameters can be changed by recompilation. +.PP +.I Cwfs +expects to find the configuration block on +.IR config-device . +.PP +Options are: +.TF -m +.TP +.B -a +announce on +.I announce-string +instead of +.LR tcp!*!9fs . +.TP +.B -c +use a newer, faster, and incompatible cache-device layout. +To convert an old file system's cache to the new layout, +dump the file system, note the last superblock number, +halt +.IR cwfs , +restart +.I cwfs +with +.BR -cf , +.I recover +the file system, and start +.I cwfs +with +.B -c +thereafter. +.TP +.B -f +enter the file server's configuration mode +before starting normal operation. +.TP +.B -m +the file +.I device-map +contains a simple device name +(e.g., +.LR w9 ) +and a replacement per line. +The device name is in the usual +.I filsys +notation of +.IR fsconfig (8). +The replacement can be the name of an existing file +(which +.I cwfs +will not grow) +or another such device name. +For example, the file +.RS +.PD +.IP +.EX +w0 /tmp/w0 +h1 w2 +.EE +.PP +.PD 0.3v +would map accesses to device +.L w0 +to existing file +.LR /tmp/w0 +and accesses to device +.L h1 +to device +.LR w2 , +if no file named +.L w2 +exists. +.RE +.PD +.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. +.SS "Changes from fs(4)" +.IR fs (4)'s +IP configuration is ignored and the underlying system's is used. +.PP +Various other +.IR fs (4) +commands have been omitted since they (or equivalents) can now be +executed directly on the underlying CPU server, +notably +.I date +and +.I passwd +(see +.IR auth/wrkey ). +.PP +.IR fs (4)'s +device names +.L h +for IDE disks and +.L m +for Marvell SATA disks are not supported; use +.B -m +to map wren devices to appropriate names under +.BR /dev/sd* . +.PP +The file server kernel seems to have scanned PCI buses +in reverse order from the other Plan 9 kernels, +so systems with multiple SCSI cards may find controller +numbering reversed. +.B -m +can be used to compensate for this if you don't want to change +.I filsys +declarations. +.PP +The file server kernel's +.I config +field in NVRAM was overloaded in recent times to hold a +.IR secstore (1) +key for the CPU hostowner. +Since +.I cwfs +runs on a CPU kernel, +the location of its configuration block must be supplied on the command line. +.PP +Disk labels are now implemented for +.B l +devices. +At the first access of a side, +.I cwfs +will attempt to read the label and verify that it has the correct side +number and byte order; if either is wrong, it will issue a warning. +If the label cannot be read, +.I cwfs +will attempt to write a new label. +.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 +cwfs w0 +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 +.SH SOURCE +.B /sys/src/cmd/cwfs +.SH SEE ALSO +.IR yesterday (1), +.IR fs (3), +.IR sd (3), +.IR fossil (4), +.IR fs (4), +.IR srv (4), +.IR fs (8), +.IR fsconfig (8) +.br +Sean Quinlan, +``A Cached WORM File System'', +.I +Software \- Practice and Experience, +December, 1991 +.br +Ken Thompson, +Geoff Collyer, +``The 64-bit Standalone Plan 9 File Server'' +.SH BUGS +For the moment, +the file server serves both the old (9P1) and new (9P2000) versions of 9P, +deciding which to serve by sniffing the first packet on each connection. +.PP +File system block size and disk address size (32- or 64-bit) are fixed +at compilation time, and this is not easily changed. +.PP +.I Cwfs +is probably not the right choice of file server for new file systems. +It's intended to cope with existing file systems on optical jukeboxes +or images thereof. diff --git a/sys/man/4/dossrv b/sys/man/4/dossrv new file mode 100755 index 000000000..8bfbf5414 --- /dev/null +++ b/sys/man/4/dossrv @@ -0,0 +1,221 @@ +.TH DOSSRV 4 +.SH NAME +dossrv, 9660srv, a:, b:, c:, d:, 9fat:, dosmnt, eject \- DOS and ISO9660 file systems +.SH SYNOPSIS +.B dossrv +[ +.B -rsv +] [ +.B -f +.I file +] [ +.I service +] +.PP +.B 9660srv +[ +.B -9Jsv +] [ +.B -c +.I clusters +] [ +.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. +The +.B -c +option sets the size of the RAM cache to +.I clusters +clusters of 128KB. +The default +.I clusters +is 16, +but a value of 5600 will cache an entire CD incrementally. +.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/sys/man/4/execnet b/sys/man/4/execnet new file mode 100755 index 000000000..9375a14b0 --- /dev/null +++ b/sys/man/4/execnet @@ -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/sys/man/4/exportfs b/sys/man/4/exportfs new file mode 100755 index 000000000..649e0444b --- /dev/null +++ b/sys/man/4/exportfs @@ -0,0 +1,257 @@ +.TH EXPORTFS 4 +.SH NAME +exportfs, srvfs \- network file server plumbing +.SH SYNOPSIS +.B exportfs +[ +.I options +] +.PP +.B srvfs +[ +.B -dR +] +[ +.B -p +.I perm +] +[ +.B -P +.I patternfile +] [ +.B -e +.I exportprog +] +.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 options are: +.TF "-A \fIaddress" +.PD +.TP +.B -A \fIaddress +Use the network +.I address +to announce +.IR aan (8) +connections, +if requested by the initial protocol. +.TP +.B -a +Authenticate the user with the +.I p9any +protocol before running the regular +.I exportfs +session; used when +.I exportfs +is invoked to handle an incoming network connection. +.I Exportfs +creates a new name space for each connection, using +.B /lib/namespace +by default (see +.IR namespace (6)). +.TP +.B -B \fIaddress +Dial +.IR address , +authenticate as a +.I p9any +client, and then +serve that network connection. +Requires setting the root of the name space with +.B -r +or +.BR -s . +The remote system should run +.B import +.B -B +to handle the call. +See +.IR import (4) +for an example. +.TP +.B -d -f \fIdbgfile +Log all 9P traffic to +.I dbgfile +(default +.BR /tmp/exportdb ). +.TP +.B -e '\fIenc auth\fL' +Set the encryption and authentication algorithms to use for +encrypting the wire traffic (see +.IR ssl (3)). +The defaults are +.B rc4_256 +and +.BR sha1 . +.TP +.B -m \fImsize +Set the maximum message size that +.I exportfs +should offer to send (see +.IR version (5)); +this helps tunneled +9P connections to avoid unnecessary fragmentation. +.TP +.B -N \fInsfile +Serve the name space described by +.IR nsfile . +.TP +.B -n +Disallow mounts by user +.BR none . +.TP +.B -P \fIpatternfile +Restrict the set of exported files. +.I Patternfile +contains one regular expression per line, +to be matched against path names +relative to the current working directory +and starting with +.BR ./ . +For a file to be exported, all lines with a prefix +.B + +must match and all those with prefix +.B - +must not match. +.TP +.B -R +Make the served name space read only. +.TP +.B -r \fIroot +Bypass the initial protocol, serving the name space rooted at +.IR root . +.TP +.B -S \fIservice +bypass the initial protocol, serving 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)). +.TP +.B -s +equivalent to +.B -r +.BR / ; +kept for compatibility. +.PD +.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. +.PP +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). +The name space is the directory tree rooted at +.IR path . +The +.BR -d , +.BR -P , +and +.B -R +options, if present, are relayed to +.IR exportprog . +.SH EXAMPLES +To export the archive of one user for one month, except for secrets, +.IP +.EX +cd /n/dump +echo '+ ^\e.(/2003(/10..(/usr(/glenda/?)?)?)?)?' > /tmp/pattern +echo '- \e.(aes|pgp)$' >> /tmp/pattern +exportfs -P /tmp/pattern +.EE +.LP +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 +.LP +Use +.I srvfs +to spy on all accesses to a particular subtree: +.IP +.EX +srvfs -d spy / +tail -f /tmp/exportdb & +mount /srv/spy /n/spy +cd /n/spy; ls +.EE +.SH SOURCE +.B /sys/src/cmd/exportfs +.br +.B /sys/src/cmd/srvfs.c +.SH SEE ALSO +.IR dial (2), +.IR import (4), +.IR aan (8), +.IR listen (8) diff --git a/sys/man/4/ext2srv b/sys/man/4/ext2srv new file mode 100755 index 000000000..6dcb950fb --- /dev/null +++ b/sys/man/4/ext2srv @@ -0,0 +1,110 @@ +.TH EXT2SRV 4 +.SH NAME +ext2srv \- ext2 file system +.SH SYNOPSIS +.B ext2srv +[ +.B -vrs +] [ +.B -f +.I file +] [ +.B -p +.I passwd +] [ +.B -g +.I group +] [ +.I service +] +.SH DESCRIPTION +.I Ext2srv +is a file server that interprets the Linux Second Extended File System. +A single instance of +.I ext2srv +can provide access to multiple ext2 partitions simultaneously. +.PP +.I Ext2srv +posts a file descriptor named +.I service +(default +.BR ext2 ) +in the +.B /srv +directory. +To access an ext2 file system on a device, use +.B mount +with the +.I spec +argument +(see +.IR bind (1)) +the name of the file holding the raw ext2 file system, typically the disk or partition. +If +.I spec +is undefined in the +.BR mount , +.I ext2srv +will use +.I file +as the default name for the device holding the file system. +.PP +Normally +.I ext2srv +creates a pipe to act as the communications channel between +itself and its clients. +The +.B -s +flag instructs +.I ext2srv +to use its standard input and output instead. +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 (recommended) makes the file system read-only. +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 in the ext2 file system and the strings reported by Plan 9 status +inquiries. +.PP +There is no authentication or permission checking. +Anyone who can access the ext2 file system will have full access +to all its files, including write access if +.I ext2srv +is not started with the +.B -r +flag, irrespective of file ownership and permission flags. +.PP +Some file system state is cached in memory, and may +be flushed only when the file system is unmounted. +Therefore if +.I ext2srv +is stopped or the machine is rebooted while an ext2 file system +is still mounted, +the superblock on the device will have been marked `not valid' +(unless the +.B -r +flag was used), +and a +.I fsck +will be required before that file system may be mounted again. +.SH BUGS +There is no authentication or permission checking. +The implementation has not tracked any changes to the ext2 +specification since it was written. +There may be other bugs. +It is advisable to use +.I ext2srv +in read-only mode whenever possible. +.SH AUTHOR +Bodet Laurent (bl@mime.univ-paris8.fr), +with later updates by Russ Cox and Richard Miller. diff --git a/sys/man/4/factotum b/sys/man/4/factotum new file mode 100755 index 000000000..a66f19a4c --- /dev/null +++ b/sys/man/4/factotum @@ -0,0 +1,728 @@ +.TH FACTOTUM 4 +.SH NAME +factotum, fgui \- authentication agent +.SH SYNOPSIS +.B auth/factotum +[ +.B -DdknpuS +] [ +.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 +.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. +For secret attributes, only the attribute name follow by a +.L ? +is returned. +.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 mschap +.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 rsa +RSA public key decryption, used by SSH and TLS. +.TP +.B pass +passwords in the clear. +.TP +.B vnc +.IR vnc (1)'s +challenge/response. +.TP +.B wep +WEP passwords for wireless ethernet cards. +.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 p9sk1 +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. +.TP +.B \-p +causes the agent not to mark itself `private' +via +.IR proc (3), +so that it can be debugged. +It is implied by +.BR \-d . +.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 , +and +.BR mschap , +require a key with a +.B proto +attribute whose value matches the protocol, +in addition to +.BR server , +.BR user , +and +.B !password +attributes; +e.g. +.PP +.EX + proto=apop server=mit.edu user=rsc !password=nerdsRus +.EE +Vnc is similar but does not require a +.B user +attribute. +.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 Rsa +requires a key with +.B proto=rsa +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 . +By convention, programs using the RSA protocol also require a +.B service +attribute set to +.BR ssh , +.BR sshserve , +or +.BR tls . +.PP +.B Wep +requires a +.BR key1 , +.BR key2 , +or +.BR key3 +set to the password to be used. +Starting the protocol causes +.I factotum +to configure the wireless ethernet card +.B #l/ether0 +for WEP encryption with the given password. +.PP +All keys can have additional attributes that act either as comments +or as selectors to distinguish them in the +.IR auth (2) +library calls. +.PP +The factotum owner can use any key stored by factotum. +Any key may have one or more +.B owner +attributes listing the users who can use the key +as though they were the owner. +For example, the TLS and SSH host keys on a server +often have an attribute +.B owner=* +to allow any user (and in particular, +.LR none ) +to run the TLS or SSH server-side protocol. +.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 speakfor +for authenticating processes whose +user id does not match +.IR factotum 's. +.PP +If a key has a +.B disabled +attribute (with any value), the key is not used +during any protocols. Factotum automatically marks +keys with +.B disabled=by.factotum +when they fail during certain authentication +protocols (in particular, the Plan 9 ones). +.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 messages 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=rsa service=ssh 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 a verb, a single 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 attributes 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 precede 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 +.SH SOURCE +.B /sys/src/cmd/auth/factotum diff --git a/sys/man/4/flashfs b/sys/man/4/flashfs new file mode 100755 index 000000000..ee8f5dc21 --- /dev/null +++ b/sys/man/4/flashfs @@ -0,0 +1,74 @@ +.TH FLASHFS 4 +.SH NAME +flashfs \- journalling file system for flash memory +.SH SYNOPSIS +.B aux/flashfs +[ +.B -Dr +] [ +.B -n +.I nsect +] [ +.B -z +.I sectsize +] +[ +.B -f +.I file +] +[ +.B -m +.I mountpoint +] +.SH DESCRIPTION +.I Flashfs +interprets the journal-based file system created by +.IR mkflashfs (8) +and stored in +.I file +(default +.BR /dev/flash/fs ) +so that it can be mounted into a Plan 9 file system. +.I Flashfs +is typically used to create a stand alone file system from +a small persistent storage device, such as an erasable flash memory. +It does not authenticate its clients and assumes each group +has a single member with the same name. +.PP +The +.B -s +option causes +.I flashfs +to post its channel on +.BR #s/flashfs . +.I Flashfs +mounts itself on +.IR mountpoint +(default +.BR /n/brzr ). +The +.B -D +option turns on 9P debugging output. +The +.B -r +option makes the file system read-only. +.PP +The files and directory structure are divided into +.I sectsize +(default +.BR 4096 ) +byte blocks. +Larger blocks make large files more compact but take longer to access. +Supplying the +.B -n +option forces +.I file +to contain exactly +.I nsect +sectors. +.SH SOURCE +.B /sys/src/cmd/aux/flashfs +.SH "SEE ALSO" +.IR paqfs (4), +.IR sacfs (4), +.IR mkflashfs (8) diff --git a/sys/man/4/fossil b/sys/man/4/fossil new file mode 100755 index 000000000..602410a14 --- /dev/null +++ b/sys/man/4/fossil @@ -0,0 +1,506 @@ +.TH FOSSIL 4 +.SH NAME +fossil, flchk, flfmt \- archival file server +.SH SYNOPSIS +.B fossil/fossil +[ +.B -Dt +] +[ +.B -c +.I cmd +]... +[ +.B -f +.I file +] +[ +.B -m +.I free-memory% +] +.PP +.B fossil/flchk +[ +.B -f +] +[ +.B -c +.I ncache +] +[ +.B -h +.I host +] +.I file +.PP +.B fossil/flfmt +[ +.B -y +] +[ +.B -b +.I blocksize +] +[ +.B -h +.I host +] +[ +.B -l +.I label +] +[ +.B -v +.I score +] +.I file +.PP +.B fossil/conf +[ +.B -w +] +.I file +[ +.I config +] +.PP +.B fossil/last +.I file +.SH DESCRIPTION +.I Fossil +is the main file system for Plan 9. +Unlike the Plan 9 file servers of old, +.I fossil +is a collection of user-space programs that run on a standard Plan 9 kernel. +The name of the main fossil file server at Murray Hill is +.BR pie . +The Plan 9 distribution file server, +.BR sources , +is also a fossil server. +.PP +.I Fossil +is structured as a magnetic disk write buffer +optionally backed by a Venti server for archival storage. +It serves the Plan 9 protocol via TCP. +A +.I fossil +file server conventionally presents +three trees in the root directory of each file system: +.BR active , +.BR archive , +and +.BR snapshot . +.B /active +is the root of a conventional file system +whose blocks are stored in a disk file. +In a typical configuration, the file server periodically +marks the entire file system copy-on-write, effectively +taking a snapshot of the file system at that moment. +This snapshot is made available in a name +created from the date and time of the snapshot: +.BI /snapshot/ yyyy / mmdd / hhmm \fR, +where +.I yyyy +is the full year, +.I mm +is the month number, +.I dd +is the day number, +.I hh +is the hour, +and +.I mm +is the minute. +The snapshots in +.B /snapshot +are ephemeral: eventually they are deleted +to reclaim the disk space they occupy. +Long-lasting snapshots stored on a Venti server +are kept in +.B /archive +and also named from the date (though not the time) of the snapshot: +.BI /archive/ yyyy / mmdds \fR, +where +.IR yyyy , +.IR mm , +and +.I dd +are year, month, and day as before, +and +.I s +is a sequence number if more than one +archival snapshot is done in a day. +For the first snapshot, +.I s +is null. +For the subsequent snapshots, +.I s +is +.BR .1 , +.BR .2 , +.BR .3 , +etc. +The root of the main file system that is frozen +for the first archival snapshot of December 15, 2002 +will be named +.BR /archive/2002/1215/ . +.PP +The attach name used in +.I mount +(see +.IR bind (1), +.IR bind (2) +and +.IR attach (5)) +selects a file system to be served +and optionally a subtree, +in the format +.IB fs \fR[\fB/ dir \fR]. +An empty attach name selects +.BR main/active . +.PP +.I Fossil +normally requires all users except +.L none +to provide authentication tickets on each +.IR attach (5). +To keep just anyone from connecting, +.L none +is only allowed to attach after another user +has successfully attached on the same +connection. +The other user effectively acts as a chaperone +for +.LR none . +Authentication can be disabled using the +.B -A +flag to +.B open +or +.B srv +(see +.IR fossilcons (8)). +.PP +The groups called +.B noworld +and +.B write +are special on the file server. +Any user belonging to +.B noworld +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 and 0771 for directories. +The effect is to deny world access permissions to +.B noworld +users, except when walking into directories. +If the +.B write +group exists, then the file system appears read-only +to users not in the group. +This is used to make the Plan 9 distribution file server +.RI ( sources.cs.bell-labs.com ) +readable by the world but writable only to the developers. +.PP +.I Fossil +starts a new instance of the fossil file server. +It is configured mainly through console commands, +documented in +.IR fossilcons (8). +.PP +The options are: +.TP +.B -D +Toggle the debugging flag, which is initially off. +When the flag is set, information about authentication +and all protocol messages are written to standard error. +.TP +.B -t +Start a file server console on +.BR /dev/cons . +If this option is given, +.I fossil +does not fork itself into the background. +.TP +.BI -c " cmd +Execute the console command +.IR cmd . +This option may be repeated to give multiple +commands. +Typically the only commands given on the +command line are +.RB `` . \fIfile \fR,'' +which executes a file containing commands, +and +.RB `` "srv -p" \fIcons \fR,'' +which starts a file server console on +.BI /srv/ cons \fR. +See +.IR fossilcons (8) +for more information. +.TP +.BI -f " file +Read and execute console commands stored in the Fossil disk +.IR file . +.I Conf +.RI ( q.v. ) +reads and writes the command set stored in the disk. +.TP +.B -m +Allocate +.I free-memory% +percent of the available free RAM for buffers. +This overrides all other memory sizing parameters, +notably the +.B -c +option to +.BR open . +.PD +.PP +.I Flchk +checks the fossil file system stored in +.I file +for inconsistencies. +.I Flchk +is deprecated in favor of the console +.B check +command (see +.IR fossilcons (8)). +.I Flchk +prints +.I fossil +console commands that may be +executed to take care of +bad pointers +.RB ( clrp ), +bad entries +.RB ( clre ), +bad directory entries +.RB ( clri ), +unreachable blocks +.RB ( bfree ). +Console commands are interspersed with +more detailed commentary on the file system. +The commands are distinguished by being prefixed with +sharp signs. +Note that all proposed fixes are rather drastic: offending +pieces of file system are simply chopped off. +.PP +.I Flchk +does +.I not +modify the file system, so it is safe to +run concurrently with +.IR fossil , +though in this case +the list of unreachable +blocks and any inconsistencies involving the active file system +should be taken with a grain of salt. +.PP +The options are: +.TP +.B -f +Fast mode. +By default, +.I flchk +checks the entire file system image for consistency, +which includes all the archives to Venti +and can take a very long time. +In fast mode, +.I flchk +avoids walking in Venti blocks +whenever possible. +.TP +.BI -c " ncache +Keep a cache of +.I ncache +(by default, 1000) +file system blocks in memory during the check. +.TP +.BI -h " host +Use +.I host +as the Venti server. +.PD +.PP +.I Flfmt +prepares +.I file +as a new fossil file system. +The file system is initialized with three empty directories +.BR active , +.BR archive , +and +.BR snapshot , +as described above. +The options are: +.TP +.B -y +Yes mode. +By default, +.I flfmt +will prompt for confirmation before formatting +a file that already contains a fossil file system, +and before formatting a file that is not served +directly by a kernel device. +If the +.B -y +flag is given, no such checks are made. +.TP +.BI -b " blocksize +Set the file system block size (by default, 8192). +.TP +.BI -h " host +Use +.I host +as the Venti server. +.TP +.BI -l " label +Set the textual label on the file system to +.IR label . +The label is only a comment. +.TP +.BI -v " score +Initialize the file system using the vac file +system stored on Venti at +.IR score . +The score should have been generated by +.I fossil +rather than by +.IR vac (1), +so that the appropriate snapshot metadata is present. +.PD +.PP +.I Conf +reads or writes the configuration branded on the Fossil disk +.IR file . +By default, it reads the configuration from the disk and prints it to +standard output. +If the +.B -w +flag is given, +.I conf +reads a new configuration from +.I config +(or else from standard input) +and writes it to the disk. +Inside the configuration file, the argument +.L * +may be used to stand in for the name of the disk holding the configuration. +The Plan 9 kernel boot process runs +.RB `` fossil +.B -f +.IR disk '' +to start a Fossil file server. +The disk is just a convenient place to store configuration +information. +.PP +.I Last +prints the vac score that resulted after the most recent archival snapshot +of the fossil in +.I file. +.SH EXAMPLES +.PP +Place the root of the archive file system on +.B /n/dump +and show the modified times of the MIPS C compiler +over all dumps in December 2002: +.IP +.EX +9fs dump +ls -l /n/dump/2002/12*/mips/bin/vc +.EE +.PP +To get only one line of output for each version of the compiler: +.IP +.EX +ls -lp /n/dump/2002/12*/mips/bin/vc | uniq +.EE +.ne 14 +.PP +Initialize a new file system, start the server with permission +checking turned off, create a users file, and mount the server: +.IP +.EX +fossil/flfmt /dev/sdC0/fossil +fossil/conf -w /dev/sdC0/fossil <>/srv/fscons +.EE +.LP +A better strategy is to vet the output, +filter out any suggestions you're not comfortable with, +and then use the +.I sed +command to prepare the script. +.SH SOURCE +.B /sys/src/cmd/fossil +.SH SEE ALSO +.IR yesterday (1), +.IR fs (3), +.IR fs (4), +.IR srv (4), +.IR fossilcons (8), +.IR venti (8) +.SH BUGS +It is possible that the disk format (but not the Venti format) +will change in the future, to make the disk a full cache +rather than just a write buffer. +Changing to the new format will require reformatting +the disk as in the example above, +but note that this will preserve most of the file system +(all but +.BR /snapshot ) +with little effort. +.PP +The +.B -m +option currently assumes a block size of 8K bytes, +and a single file system per +.I fossil +instance. diff --git a/sys/man/4/fs b/sys/man/4/fs new file mode 100755 index 000000000..808dd9720 --- /dev/null +++ b/sys/man/4/fs @@ -0,0 +1,150 @@ +.TH FS 4 +.SH NAME +fs \- file server, dump +.SH SYNOPSIS +.I none +.SH DESCRIPTION +The file server was the main file system for Plan 9. +It was a stand-alone system that ran on +a separate computer. +It served the Plan 9 protocol via the IL/IP +protocols on Ethernets. +The name of the main file server at Murray Hill was +.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 cwfs (4), +.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. +.PP +Required IL, thus now deprecated. diff --git a/sys/man/4/ftpfs b/sys/man/4/ftpfs new file mode 100755 index 000000000..0a827b0ee --- /dev/null +++ b/sys/man/4/ftpfs @@ -0,0 +1,218 @@ +.TH FTPFS 4 +.SH NAME +ftpfs \- file transfer protocol (FTP) file system +.SH SYNOPSIS +.B ftpfs +[ +.B -/dqnt +] +[ +.B -m +.I mountpoint +] +[ +.B -a +.I password +] +[ +.B -e +.I ext +] +[ +.B -k +.I keyspec +] +[ +.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 via FTP to files on the remote machine. +.I Ftpfs +attempts to use FTP's `passive' mode +but falls back to using `active' mode if that fails. +If required by the remote machine, +.I ftpfs +will ask +.IR factotum (4) +for a key matching the pattern +.IP +.EX +proto=pass service=ftp server=\fIsystem\fP user? !password? \fIkeyspec\fP +.EE +.PP +(If +.I factotum +does not have such a key, +.I factotum +will prompt the user for one.) +.PP +The user names +.B ftp +and +.B anonymous +conventionally offer guest/read-only access to +machines. +Anonymous FTP may be called without using factotum +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 +The +.B -t +option causes +.I ftpfs +to negotiate TLS encryption with the server. +.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: +.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 +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. +Attempting to walk to +.IB directory /.flush.ftpfs +will flush +.I directory +from the cache, thus forcing +.I ftpfs +to re-read it. +.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. +.PP +.I Ftpfs +makes copies in +.B /tmp +of files being transferred, +so its effects might not be immediate. +If there is enough main memory, you might want to run +.IR ramfs (4) +first. +.PP +Filenames containing spaces will confuse +.I ftpfs +(and other FTP clients). diff --git a/sys/man/4/httpfile b/sys/man/4/httpfile new file mode 100755 index 000000000..8d3b428df --- /dev/null +++ b/sys/man/4/httpfile @@ -0,0 +1,86 @@ +.TH HTTPFILE 4 +.SH NAME +httpfile \- serve a single web file +.SH SYNOPSIS +.B httpfile +[ +.B -9d +] +[ +.B -c +.I count +] +[ +.B -f +.I file +] +[ +.B -m +.I mtpt +] +[ +.B -s +.I srvname +] +[ +.B -x +.I net +] +.I url +.SH DESCRIPTION +.I Httpfile +serves the web page specified by the URL +.I url +as a new file +.I file +in the directory +.IR mtpt . +The default +.I file +is the last path element of the URL, +and the default +.I mtpt +is the current directory. +.PP +.I Httpfile +does not download large files all at once. +Instead, it requests 64-kilobyte blocks as they are +needed to satisfy reads, caching a few blocks in memory at a time. +.PP +The +.B -D +and +.B -d +options enable a trace of the 9P traffic +and general debugging messages. +.PP +The +.B -s +option causes +.I httpfile +to post the 9P service as +.BI /srv/ srvname +and disables the default mount. +.PP +The +.B -x +option specifies an alternate network directory +.RI ( e.g., +.BR /net.alt ). +.PP +The +.B -c +option sets the number of file blocks kept cached in memory (default 32). +.SH EXAMPLE +Mount an ISO image on a web server: +.IP +.EX +ip/httpfile http://www.9grid.de/plan9/plan9.iso +9660srv +mount /srv/9660 /n/iso plan9.iso +.EE +.SH SOURCE +.B /sys/src/cmd/ip/httpfile.c +.SH "SEE ALSO +.IR hget (1), +.IR webfs (4) diff --git a/sys/man/4/import b/sys/man/4/import new file mode 100755 index 000000000..d8026c7af --- /dev/null +++ b/sys/man/4/import @@ -0,0 +1,202 @@ +.TH IMPORT 4 +.SH NAME +import \- import a name space from a remote system +.SH SYNOPSIS +.B import +[ +.I options +] +.I system +.I file +[ +.I mountpoint +] +.PP +.B import +.B -B +[ +.I options +] +.I mountpoint +[ +.I cmd +[ +.I args ... +] +] +.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. +The default port used is TCP 17007. +If +.I mountpoint +is omitted +.I import +uses the name of the remote +.I file +as the local mount point. +.PP +The options are: +.TF "-s namexxx" +.PD +.TP +.B -a -b -c -C +Control the construction of union directories, as in +.I mount +and +.IR bind (1). +Only valid when +.I file +is a directory. +.TP +.B -A +Skip the authentication protocol. +This is useful for connecting to foreign systems like Inferno. +.TP +.B -B +Run in ``backwards'' mode, described below. +.TP +.B -E \fIenc +Push an authentication protocol on its network connection. +The supported protocols are +.B clear +(the default, no protocol) +and +.BR ssl . +There are plans to make +.B tls +available. +.TP +.B -e '\fIenc auth\fR' +Specify the encryption and authentication algorithms to use for +encrypting the wire traffic +(see +.IR ssl (3)). +The defaults are +.B rc4_256 +and +.BR sha1 . +.TP +.B -k \fIkeypattern +Use +.I keypattern +to select a key to authenticate to the remote side +(see +.IR auth (2)). +.TP +.B -o -O +These equivalent flags run +.I import +in a pre-9P2000 compatibility mode to import from ancient servers. +.TP +.B -p +Push the +.IR aan (8) +filter onto the connection to protect against +temporary network outages. +.TP +.B -s \fIname +Post the connection's mountable file descriptor as +.BI /srv/ name\fR. +.PD +.PP +The +.B -B +option runs +.I import +in ``backwards'' mode. +In this mode, +.I import +runs a +.I p9any +authentication (as server) over its file descriptor 0 +(expected to be an incoming network connection from +.B exportfs +.BR -B ), +mounts the connection onto +.IR mntpt , +and optionally runs +.I cmd +.IR args . +.SH EXAMPLES +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 +.PP +Suppose that the machine +.B moscvax +has access to a private file server containing public web pages +that need to be served by the less-trusted server +.BR webvax . +.B Webvax +runs the following listener +(see +.IR listen (8)) +on TCP port 999: +.IP +.EX +#!/bin/rc +import -B -s rowebfs /usr/web /bin/restarthttpd +.EE +.PP +When +.B moscvax +boots, it runs +.IP +.EX +exportfs -R -r /usr/web -B tcp!webvax!999 +.EE +.PP +to serve a read-only copy of +.B /usr/web +to +.BR webvax . +When +.B webvax +gets the call, +.B import +mounts the served tree onto its own +.B /usr/web +and then runs +.B /bin/restarthttpd +to restart +.IR httpd (8). +.SH SOURCE +.B /sys/src/cmd/import.c +.SH SEE ALSO +.IR bind (1), +.IR ssl (3), +.IR exportfs (4), +.IR srv (4), +.IR aan (8), +.IR listen (8), +.B cs +in +.IR ndb (8) diff --git a/sys/man/4/iostats b/sys/man/4/iostats new file mode 100755 index 000000000..9472f20b5 --- /dev/null +++ b/sys/man/4/iostats @@ -0,0 +1,82 @@ +.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 EXAMPLE +Display summary of file I/O incurred by +.IR ls (1): +.IP +.EX +iostats ls +.EE +.PP +Start a new shell, displaying all 9P traffic caused by the shell or its children: +.IP +.EX +iostats -df /fd/1 rc +.EE +.SH SOURCE +.B /sys/src/cmd/iostats +.SH SEE ALSO +.IR dup (3) +.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, +or by the use of names of files with content that can vary by process (e.g., +.LR #d , +.LR /dev/cons ). diff --git a/sys/man/4/keyfs b/sys/man/4/keyfs new file mode 100755 index 000000000..c78e31df4 --- /dev/null +++ b/sys/man/4/keyfs @@ -0,0 +1,249 @@ +.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. +This number is not stored in +.IR keyfile , +and is initialized to 0 when +.I keyfs +starts. +When the number reaches a multiple of ten, +.I keyfs +temporarily disables the account for that many seconds. +Reads from the +.B key +or +.B secret +files during this time return the error +``user in purgatory.'' +.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/sys/man/4/kfs b/sys/man/4/kfs new file mode 100755 index 000000000..15a9514d1 --- /dev/null +++ b/sys/man/4/kfs @@ -0,0 +1,136 @@ +.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 an old, 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 +% disk/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 fossil (4), +.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. +.LP +.I Kfs +doesn't allow creating files with component names longer than 28 bytes. diff --git a/sys/man/4/lnfs b/sys/man/4/lnfs new file mode 100755 index 000000000..7f01698fa --- /dev/null +++ b/sys/man/4/lnfs @@ -0,0 +1,64 @@ +.TH LNFS 4 +.SH NAME +lnfs \- long name file system +.SH SYNOPSIS +.B lnfs +[ +.B -r +] +[ +.B -s +.I srvname +] +.I mountpoint +.br +.B unlnfs +.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. +.PP +.I Unlnfs +renames files with shortened names to their actual long names. +It is useful once you have moved to a file server with true long name support. +.SH FILES +.B .longnames +.SH SOURCE +.B /sys/src/cmd/lnfs.c +.PP +.B /sys/src/cmd/unlnfs.c +.SH BUGS +This exists only to shame us into getting a real long +name file server working. diff --git a/sys/man/4/mntgen b/sys/man/4/mntgen new file mode 100755 index 000000000..e4a7c56b1 --- /dev/null +++ b/sys/man/4/mntgen @@ -0,0 +1,30 @@ +.TH MNTGEN 4 +.SH NAME +mntgen \- automatically generate mount points for file systems +.SH SYNOPSIS +.B mntgen +[ +.B -s +.I service +] +[ +.I mnt +] +.SH DESCRIPTION +.I Mntgen +mounts itself on +.I mnt +(default +.BR /n ) +after the current contents, +creating subdirectories on demand as they are accessed. +It is intended to supply mount points automatically. +.PP +The +.B -s +option causes +.I mntgen +to post a 9P service file in +.BI /srv/ service \fR. +.SH SOURCE +.B /sys/src/cmd/mntgen.c diff --git a/sys/man/4/namespace b/sys/man/4/namespace new file mode 100755 index 000000000..8fd6e429c --- /dev/null +++ b/sys/man/4/namespace @@ -0,0 +1,404 @@ +.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. +.TP +.B /n +A directory containing mount points for file trees imported from +remote systems. +.TP +.B /386 +.TP +.B /68000 +.TP +.B /68020 +.TP +.B /alpha +.TP +.B /arm +.TP +.B /mips +.TP +.B /power +.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 or its bootstrap loader. +.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 /lib/rfc +Directory of Internet `Requests For Comments', +ranging from trivia to specifications. +.TP +.B /lib/rfc/grabrfc +Maintains RFC collection; usually run from +.IR cron +(see +.IR auth (8)). +.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 /usr +A directory containing home directories of users. +.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). +.TP +.BI /cfg/ system +.IR System -specific +files, often addenda to their namesakes, +notably +.BR cpurc , +.BR termrc , +.BR namespace , +and +.BR consoledb . +.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/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/factotum +Mount point for +.IR factotum (4). +.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/sys/man/4/nfs b/sys/man/4/nfs new file mode 100755 index 000000000..b1499bb3c --- /dev/null +++ b/sys/man/4/nfs @@ -0,0 +1,210 @@ +.TH NFS 4 +.SH NAME +nfs \- Sun network file system client +.SH SYNOPSIS +.B nfs +[ +.B -DRv +] +[ +.B -p +.I perm +] +[ +.B -s +.I srvname +] +[ +.B -u +.I passwd +.I group +] +.I addr1 +[ +.I addr2 +] +.PP +.B aux/portmap +[ +.B -R +] +.I host +.I cmd +... +.PP +.B aux/nfsmount +[ +.B -R +] +.I host +.I cmd +... +.SH DESCRIPTION +.I Nfs +translates between the Sun network file system protocol (NFS) +and 9P, allowing 9P clients to mount file systems on NFS servers. +NFS servers comprise two separate services: a mount service used to +obtain the initial file handle, and a file service used to perform +actual file system operations. +The Sun port mapper service is typically used to find these two services. +If one address is given, it is taken to be the address of a port mapper service; +.I nfs +queries the port mapper to find the addresses +of the NFS mount service and file service. +If two addresses are given, the port mapper is bypassed; +.I addr1 +is used as the address of the NFS mount service, +and +.I addr2 +is used as the address of the file service. +.PP +The options are: +.TP +.B -D +print all 9P messages. +.TP +.B -R +print all NFS messages. +.TP +.B -v +print verbose information about session startup. +.TP +.B -p \fIperm +set the posted service file to have mode +.IR perm , +which is assumed to be octal; +the default is +.BR 600 . +.TP +.B -s \fIsrvname +post the service as +.BI /srv/ srvname \fR; +the default is +.BI /srv/ addr1 \fR. +.TP +.B -u \fIpasswd\fR \fIgroup +translate user and group names using the +.I passwd +and +.I group +files, which are in the traditional Unix format. +The translation is used to present names for +user and group in +.IR stat (5) +and +.I wstat +messages. +The translation is also used to +choose the user and group credentials +to present for a user. +Without this option, users and groups are presented +as decimal numbers, and everyone attaches as uid \-1 +.RB ( nobody +on most Unix systems). +.PP +.I Portmap +and +.I nfsmount +are test programs to perform port mapper and NFS mount RPCs. +They +are useful mainly to help debug problems with +starting +.I nfs +itself. +The +.B -R +option causes them to print all RPC messages sent and received. +.PP +.I Portmap +queries a Sun RPC portmap server, which maps integer +(program, version, protocol) triples to port numbers. +Program and version are Sun RPC defined, while protocol +is typically TCP (6) or UDP (17). +The commands are: +.TP +.B null +a no-op +.TP +.B dump +print the entire map +.TP +.B set \fIprog\fP \fIvers\fP \fIproto\fP \fIport\fP +add an entry to (or replace an entry in) the map +.TP +.B unset \fIprog\fP \fIvers\fP \fIproto\fP \fIport\fP +remove an entry from the map +.TP +.B getport \fIprog\fP \fIvers\fP \fIproto\fP +look for an entry with \fIprog\fP, \fIvers\fP, \fIproto\fP +in the map, and return the corresponding port +.PD +The default command is +.BR dump . +For running NFS over UDP, there must be an entry +for the NFS v3 mount daemon (100005, 3, 17) and the +NFS v3 server itself (100003, 3, 17). +.PP +.I Nfsmount +queries a Sun NFS mount server, which authenticates (ha!) +connections and hands out file handles naming the root of +an exported file system. This handle is used as the basis +for a conversation with the NFS service daemon itself. +The commands are: +.TP +.B null +a no-op +.TP +.B export +dump the export table; +each line is a path followed by a list of machines or groups +allowed to mount that path +.TP +.B mnt \fIpath\fR +attempt to acquire a file handle for \fIpath\fR. +the request has user and group id 1001 and +.L gnot +as the system name. +.TP +.B umnt \fIpath\fR +notify the mount daemon that a particular path is being +unmounted by the requesting system +.TP +.B umntall +notify the mount daemon that all paths mounted by the +requesting system are being unmounted +.TP +.B dump +should also dump an export table, but typically +does nothing +.PD +.SH EXAMPLE +We use this in our +.B /rc/bin/9fs +script to mount all the home directories served by +.IR bopp : +.IP +.EX +case bopp + if(! test -f /srv/bopp) + nfs -p 666 -u /lib/ndb/1127.passwd /lib/ndb/1127.group bopp + unmount /n/bopp >[2]/dev/null + for(i in u0 u1 u2 u3 u4 u5 u6 u7 u8 u9) + mount -a /srv/bopp /n/bopp /$i +.EE +.SH SOURCE +.B /sys/src/cmd/nfs.c +.br +.B /sys/src/libsunrpc +.SH "SEE ALSO +.IR nfsserver (8), +.IR srv (4) +.SH BUGS +The authentication employed by NFS is laughable. +The server simply trusts the uid, gid, and group list +presented by the client. +.PP +.I Nfs +speaks only NFS version 3. +Older operating systems typically +have reasonable NFS version 2 servers +but crash when serving version 3. diff --git a/sys/man/4/nntpfs b/sys/man/4/nntpfs new file mode 100755 index 000000000..bb066289c --- /dev/null +++ b/sys/man/4/nntpfs @@ -0,0 +1,136 @@ +.TH NNTPFS 4 +.SH NAME +nntpfs \- network news transport protocol (NNTP) file system +.SH SYNOPSIS +.B nntpfs +[ +.B -a +] +[ +.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 +If the +.B -s +option is given, the file system is posted as +.BI /srv/ service \fR. +If the +.B -a +option is given, +.I nntpfs +authenticates to the system with a user name and password +obtained from +.IR factotum (4). +The key specifier is +.IP +.B +proto=pass service=nntp server=\fIserver\fR user? !password? +.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 EXAMPLE +Authenticate to a private news server: +.IP +.EX +% echo key proto=pass service=nntp server=nose.mit.edu \e + user=rsc !password=secret >/mnt/factotum/ctl +% nntpfs -a nose.mit.edu +.EE +.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/sys/man/4/paqfs b/sys/man/4/paqfs new file mode 100755 index 000000000..59fe6f99a --- /dev/null +++ b/sys/man/4/paqfs @@ -0,0 +1,102 @@ +.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 +] +[ +.B -S +.I srvname +] +.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 +Options to +.I paqfs +are: +.TP +.BI -c " cachesize +The number of file system blocks to cache in memory. The default is 20 blocks. +.TP +.BI -M " mesgsize +The maximum 9P message size. The default is sufficient for 8K byte read message. +.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 +.B -q +Suppress the output of the archive creation date and fingerprint to +.IR stderr . +.TP +.BI -m " mtpt +The location to mount the file system. The default is +.BR /n/paq . +.TP +.B -s +Post the 9P channel on +.BR #s/\fIsrvname\fR , +default +.BR #s/paqfs , +rather than +mounting it on +.IR mtpt . +.TP +.B -S +The name to post in +.BR #s . +The default is +.BR paqfs . +.TP +.B -p +Both post the 9P channel in +.B #s +and +mount the +.I paqfile +in to the filesystem. +.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/sys/man/4/plumber b/sys/man/4/plumber new file mode 100755 index 000000000..fbaebe419 --- /dev/null +++ b/sys/man/4/plumber @@ -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/sys/man/4/ramfs b/sys/man/4/ramfs new file mode 100755 index 000000000..94f69c519 --- /dev/null +++ b/sys/man/4/ramfs @@ -0,0 +1,89 @@ +.TH RAMFS 4 +.SH NAME +ramfs \- memory file system +.SH SYNOPSIS +.B ramfs +[ +.B -Dipsu +] +[ +.B -m +.I mountpoint +] +[ +.B -S +.I srvname +] +.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 -D +option enables a trace of general debugging messages. +.PP +The +.B -i +flag tells +.I ramfs +to use file descriptors 0 and 1 for its communication channel +rather than create a pipe. +This makes it possible to use +.I ramfs +as a file server on a remote machine: the file descriptors 0 +and 1 will be the network channel from +.I ramfs +to the client machine. +.PP +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 +The +.B -s +.RB ( -S ) +flag causes +.I ramfs +to post its channel on +.B /srv/ramfs +.RB ( /srv/ \fIsrvname\fR) +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 -u +option permits +.I ramfs +to consume as much memory as needed; +without it, +.I ramfs +will limit its consumption to some arbitrary amount, +currently 768MB (enough to hold a CD image). +.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/sys/man/4/ratfs b/sys/man/4/ratfs new file mode 100755 index 000000000..0820cf7c5 --- /dev/null +++ b/sys/man/4/ratfs @@ -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.ext ). +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/sys/man/4/rdbfs b/sys/man/4/rdbfs new file mode 100755 index 000000000..383dd26c7 --- /dev/null +++ b/sys/man/4/rdbfs @@ -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/sys/man/4/rio b/sys/man/4/rio new file mode 100755 index 000000000..1bcd94362 --- /dev/null +++ b/sys/man/4/rio @@ -0,0 +1,407 @@ +.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, while +.B -scroll +and +.B -noscroll +set the initial scrolling state of the window; the default is that of the main program. +.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 $wsys /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/sys/man/4/sacfs b/sys/man/4/sacfs new file mode 100755 index 000000000..9b9662816 --- /dev/null +++ b/sys/man/4/sacfs @@ -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/sys/man/4/snap b/sys/man/4/snap new file mode 100755 index 000000000..3db9914f4 --- /dev/null +++ b/sys/man/4/snap @@ -0,0 +1,106 @@ +.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 pid +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. +.PP +.I Pid +as a non-numeric string is unimplemented; it has to be a number. diff --git a/sys/man/4/srv b/sys/man/4/srv new file mode 100755 index 000000000..6770de13e --- /dev/null +++ b/sys/man/4/srv @@ -0,0 +1,338 @@ +.TH SRV 4 +.SH NAME +srv, srvold9p, 9fs, srvssh \- start network file service +.SH SYNOPSIS +.B srv +[ +.B -abcCemnq +] [ +.B -s +.I seconds +] +.RI [ net !] system\c +.RI [! service ] +[ +.I srvname +[ +.I mtpt +] ] +.PP +.B srvssh +[ +.B -r +] +[ +.B -R +] +[ +.B -s +] +[ +.B -u +.I u9fspath +] +.I system +[ +.I srvname +[ +.I mtpt +] ] +.PP +.B 9fs +.RI [ net !] system +.RI [ mountpoint ] +.PP +.in +0.5i +.ti -0.5i +.B srvold9p +[ +.B -abcCdF +] [ +.B -p +.I servicename +] [ +.B -s +| +.B -m +.I mountpoint +] [ +.B -u +.I user +] [ +.B -x +.I command +| +.B -n +.I network-addr +| +.B -f +.I file +] +.br +.in -0.5i +.SH DESCRIPTION +.I Srv +dials the given machine and initializes the connection to serve the +9P protocol. +By default, it connects to the +.L 9fs +(9P) +service, which for TCP is port 564. +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 +.I 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 , +.BR C , +and +.B n +options are used to control the mount flags as in +.I mount +(see +.IR bind (1)). +The +.B e +option causes +.I srv +to treat +.I system +as a shell command to be executed rather than +an address to be dialed. +The +.B s +option causes +.I srv +to sleep for the specified number of seconds +after establishing the connection +before posting and mounting it. +This is sometimes needed by +.IR srvssh . +.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 Srvssh +is an +.IR rc (1) +command that +connects to a remote Unix system via +.IR ssh (1) +and starts +.IR u9fs (4). +The +.B -u +option specifies the path to the +.B u9fs +binary on the remote system. +(By default, an unrooted path of +.B u9fs +is used; if the binary is in the path of +the remote SSH server, you don't need the +.B -u +option.) +For information about the other options, +see the introductory comment in +.BR /rc/bin/srvssh . +The arguments are the same as +.IR srv . +.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: +.TF "-x commandxx" +.PD +.TP +.B -d +Enable debugging. +.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. +.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. +.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 +.PP +To connect to an instance of the Unix server +.IR u9fs (4) +started via +.IR ssh (1): +.IP +.EX +srvssh unix +.EE +.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 +.B /rc/bin/srvssh +.br +.B /sys/src/cmd/srvold9p +.SH "SEE ALSO" +.IR bind (1), +.IR auth (2), +.IR dial (2), +.IR srv (3), +.IR exportfs (4), +.IR import (4), +.IR ftpfs (4), +.IR u9fs (4) +.SH BUGS +.I Srv +does not explicitly report failures of +.I auth_proxy +(see +.IR auth (2)); +.I mount +(see +.IR bind (1)) +does. diff --git a/sys/man/4/tapefs b/sys/man/4/tapefs new file mode 100755 index 000000000..26f2afa58 --- /dev/null +++ b/sys/man/4/tapefs @@ -0,0 +1,109 @@ +.TH TAPEFS 4 +.SH NAME +32vfs, cpiofs, tapfs, tarfs, tpfs, v6fs, v10fs, zipfs \- mount archival file systems +.SH SYNOPSIS +.B fs/32vfs +[ +.B -b +.I blocksize +] +[ +.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 +.B fs/zipfs +.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 (512 byte block size, the default), 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). +.PP +.I Zipfs +interprets zip archives (see +.IR gzip (1)). +.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 +.IR intro (5), +.IR ramfs (4). diff --git a/sys/man/4/telco b/sys/man/4/telco new file mode 100755 index 000000000..027541eec --- /dev/null +++ b/sys/man/4/telco @@ -0,0 +1,237 @@ +.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 +[ +.B -v +] +.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 reads 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 converts to G3 format +PostScript, G3, text, or other files acceptable to +.IR lp (1) +and queues the result +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 converted and sent. +The +.B -v +option invokes +.IR page (1) +on the generated G3 files +instead of transmitting them via FAX machine. +.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/sys/man/4/u9fs b/sys/man/4/u9fs new file mode 100755 index 000000000..f253d8fee --- /dev/null +++ b/sys/man/4/u9fs @@ -0,0 +1,289 @@ +.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 +] +.I fsroot +.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. +Characters in file and directory names unacceptable to Plan 9 are translated +into a three-character sequence: +.L \e +followed by two hexadecimal digits. +.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: +.TF "\fL-A \fIautharg" +.PD +.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 p9any . +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, or +.I srvssh +in +.IR srv (4)). +Specifying +.B p9any +uses the fourth 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 +and should be suitably protected. +This file must contain exactly three lines: +.I secret +(plaintext password), +.I u9fs-user +(user id), +and +.I plan9-auth.dom +(authentication domain). +.RS +.LP +Finally, +.I factotum +must be taught a key of the form: +.LP +.EX +.B +key proto=p9sk1 dom=\fIplan9-auth.dom\fP user=\fIu9fs-user\fP !password=\fIsecret\fP +.EE +.RE +.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. +.PP +If +.I fsroot +is specified, +.I u9fs +will serve only that tree; othwise, it will serve the entire Unix +file system. +.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 +By default, +.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 other network mechanisms; the script +.I srvssh +in +.IR srv (4) +provides this for the +.I ssh +protocol. +.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/sys/man/4/upasfs b/sys/man/4/upasfs new file mode 100755 index 000000000..d6a65041f --- /dev/null +++ b/sys/man/4/upasfs @@ -0,0 +1,351 @@ +.TH UPASFS 4 +.SH NAME +upasfs, startupasfs \- mail file server +.SH SYNOPSIS +.B upas/fs +[ +.B -f +.I mailbox +] [ +.B -bnps +] [ +.B -m +.I mntpoint +] +.PP +.B startupasfs +.SH DESCRIPTION +.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 +.I Startupasfs +is a shell script suitable for use in one's profile. +It runs +.B "fs -s" +for the invoking user if none is already running, +and always mounts the user's posted +.I fs +on +.BR /mail/fs . +.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. +.LP +.2C +.PD 0 +.LP +.TP 2i +.I "sender address +.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 +.LP +.1C +.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: +.TF "delete\fI mboxname number ...\fP +.TP +.BI open " path mboxname" +opens a new mailbox. +.I path +is the file to open, and +.I mboxname +is the name that appears under +.BR /mail/fs . +.TP +.BI close " mboxname" +close +.IR mboxname . +The close takes affect only after all files open under +.BI /mail/fs/ mboxname +have been closed. +.TP +.BI delete " mboxname number ..." +Delete the messages with the given numbers from +.IR mboxname. +.PD +.PP +The options are: +.TF "-f\fI 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 +.BI sender= "," +.BR filetype=mail , +.BR "mailtype=deleted\fI or \fPnew" , +and +.BI length= "." +The contents of the message is the full path +name of the directory representing the message. +.TP +.B -s +causes +.I fs +to post itself in +.B /srv +with a name of the form +.BI /srv/upasfs. user. +.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. +.PP +.I Fs +interprets mailbox file names of the form +.BI / proto / host / user +to mean access an account on +.I host +using the given protocol. +Authentication is delegated to +.IR factotum (4). +The final +.BI / user +may be omitted, in which case +the user name is gleaned from the key held by +.IR factotum . +The following protocols are supported: +.PP +.TF apoptls +.TP +.B pop +cleartext POP with password authentication +.TP +.B apop +cleartext POP with challenge-response (APOP) authentication +.TP +.B pops +.TP +.B poptls +TLS-encrypted POP with password authentication +.TP +.B apops +.TP +.B apoptls +TLS-encrypted POP with challenge-response (APOP) authentication +.TP +.B imap +cleartext IMAP +.TP +.B imaps +TLS-encrypted IMAP +.PD +.PP +The two IMAP protocols allow an optional fourth field +specifying a mailbox name, for example +.BR /imap/server/user/stored . +.PP +.B Poptls +and +.B apoptls +connect to port 110 in plaintext and start TLS using the POP +STLS command. +.B Pops +and +.B apops +connect to port 995 and start TLS before initiating the POP conversation. +.B Imaps +connects to port 993 and starts TLS before initiating the IMAP conversation. +There should probably be an +.B imaptls +protocol as well. +.RB ( Imaptls +would connect to port 143 in plaintext and start TLS using the IMAP +STARTTLS command. +(That's the nice thing about standards\(emthere's so many to choose from.)) +.SH FILES +.TF /mail/box/*/dead.letter +.TP +.B /mail/box/* +mail directories +.TP +.B /mail/box/*/mbox +mailbox files +.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 +.br +.ne 3 +.SH SOURCE +.B /sys/src/cmd/upas/fs +.br +.B /rc/bin/startupasfs +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR mail (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR upasfs (4) diff --git a/sys/man/4/usb b/sys/man/4/usb new file mode 100755 index 000000000..5df684c9e --- /dev/null +++ b/sys/man/4/usb @@ -0,0 +1,514 @@ +.TH USB 4 +.SH NAME +audio, +ccid, +disk, +ether, +kb, +print, +probe, +serial, +usbeject, +usbfat: +\- Universal Serial Bus device drivers +.SH SYNOPSIS +.B usb/kb +[ +.B -dkm +] [ +.B -a +.I accel +] [ +.I dev ... +] +.PP +.B usb/disk +[ +.B -Dd +] [ +.B -m +.I mnt +] [ +.B -s +.I srv +] [ +.I dev ... +] +.PP +.B usbfat: +[ +.I disk ... +] +.PP +.B usbeject +[ +.I disk ... +] +.PP +.B usb/audio +[ +.B -dpV +] [ +.B -m +.I mnt +] [ +.B -s +.I srv +] [ +.B -v +.I vol +] [ +.I dev +] +.PP +.B usb/ether +[ +.B -Dd +] [ +.B -m +.I mnt +] [ +.B -s +.I srv +] [ +.I dev ... +] +.PP +.B usb/serial +[ +.B -Dd +] [ +.B -m +.I mnt +] [ +.B -s +.I srv +] [ +.I dev ... +] +.PP +.B usb/print +[ +.B -d +] [ +.I dev ... +] +.PP +.B usb/ccid +[ +.B -d +] +.ig +.PP +.B usb/ibuddy +[ +.B -Dd +] [ +.B -m +.I mnt +] [ +.B -s +.I srv +] [ +.I dev ... +] +.. +.B usb/probe +.SH DESCRIPTION +These programs drive USB devices of specific classes via +.IR usb (3). +Usually they are started by +.IR usbd (4) +upon attachment of the device to the bus. +Less often, users start them manually, depending on +.IR usbd (4)'s +configuration. +Usually, +.I kb +and +.I disk +are started by +.I usbd +and other programs are started by hand. +.PP +Without arguments, the drivers handle all the devices (of +the appropriate USB class) found on the bus. +To make a driver handle only certain devices, supply as arguments +the paths for the directories of the devices +(actually of their zero endpoints). +.PP +Drivers that provide file systems accept options +.B -s +and +.B -m +to instruct them to post a 9P connection at +.IR srv (3) +with the given name and/or to mount themselves at +.IR mnt . +When embedded into +.IR usbd +these options may not be used. +In this case, +the file tree supplied by the device driver is +available through the file system provided by +.IR usbd , +usually mounted at +.B /dev +and reachable through the 9P connection posted at +.BR /srv/usb . +.PP +Options +.B -d +and +.B -D +present on most drivers trigger debug diagnostics and +file system debugging diagnostics. +Repeating any one of these may increase verbosity. +.PP +To help locate devices of interest, +.I probe +lists all the USB devices available, +including those with no driver started. +.SS Keyboards and mice +.I Kb +supports USB keyboards and mice either as separate USB devices +or as a single combined USB device. +Scan codes from the keyboard are sent to +.B /dev/kbin +to let the kernel process them. +Mouse events are sent to +.B /dev/mousein +in the same way. +.PP +The following options are understood: +.TF -k +.TP +.B \-a +Accelerate the mouse to level +.I n +(similar to the kernel mouse driver acceleration). +.TP +.B \-k +Serve just the keyboard (and not the mouse). +.TP +.B \-m +Serve just the mouse (and not the keyboard). +.SS Disks +.I Disk +configures and manages USB mass storage devices. It +provides a file system (usually seen at +.BR /dev ) +that includes one directory per storage device, named +.BI sdU N . M +in correspondence with the usb device number and the storage +unit number (or LUN). +For example, LUN number 2 on +.B /dev/usb/ep3.0 +can be accessed through +.BR /dev/sdU3.2 . +.PP +The storage device directory contains the usual files +served by +.IR sd (3): +.BR data , +.BR raw , +and +.BR ctl . +.PP +The +.B ctl +file supplies the device +geometry when read. +.PP +The script +.B usbfat: +mounts the FAT file systems in the DOS partitions of the named +.IR disk s; +if none, it mounts those file systems found at +.BR /dev/sdU*.*/data . +When more than one partition is found, a suffix is appended to +the disk name to identify the partition number. +The script +.B usbeject +undoes the effect. If no argument is given, it unmounts all USB +disks. An argument +.BI sdU N +unmounts all partitions from disk with USB target +.IR N . +.ig +An argument +.BI sdU N . M +or +.BI sdU N . M . P +.\" TODO: fill in missing words +.. +.SS Printers +.I Print +provides a single file can be written to print on a USB printer. +Options are similar to those of +.IR disk . +The file is also bound at +.B /dev/lp +as is customary. +.SS Ethernet adapters +.I Ether +provides a file interface similar to that of +.IR ether (3) +for each USB Ethernet adapter found. +The name of an Ethernet device is +.BI etherU N +where +.I N +is the device name. +When started manually, the file interface is mounted at +.B /net +as is customary. +. +.SS Serial and JTAG ports +.I Serial +provides a file system (usually mounted at +.BR /dev ) +that includes one directory per USB serial port, named +.BI eiaU N +or +.BI eiaU N . M. +In this directory there are two files, +.BR eiaU , +similar to +.BI eia N +in +.IR uart (3), +and +.BR eiaUctl , +which admits writes in the same format as +.BI eia N ctl +in +.IR uart (3). +Reading from +.B eiaUctl +gives the serial port's settings in the same format as +.BI eia N status +in +.IR uart (3). +Options are similar to those of +.IR disk . +.PP +JTAG ports are similar +but the files are named +.B jtag +and +.BR jtagctl . +. +.SS Audio devices +.I Usbaudio +configures and manages a USB audio device. +It implements a file system, +normally mounted on +.BI /dev , +but this can be changed with +.BR \-m , +containing files +.BR volume , +.BR audioctl , +.BR audio , +and +.BR audioin . +The names +.B volume +and +.B audio +maintain backward compatibility with the Soundblaster driver. +.PP +The +.B \-V +option (verbose) +causes +.I audio +to print information about the device on startup. +The +.B \-s +option specifies a name for a file descriptor to be posted in +.BR /srv . +The +.B \-v +options sets initial +.IR volume . +.PP +Reading +.B volume +or +.B audioctl +yields the device's settings. +The data format of +.B volume +is compatible with the Soundblaster and produces output in this +format: +.IP +.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 +.L out +may be omitted. +Settings are given as percentages of the range, +except for speed which is in Hz. +.PP +The file +.B 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 +.B audioctl +have been read, a zero-length buffer is returned +(the usual end-of-file indication). +A new +.I read +will then block until one of the settings changes, +then report its new value. +.PP +The file +.B audioctl +can be written like +.BR volume . +.PP +Audio data is written to +.B audio +and read from +.BR 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. +. +.SS Ccid +.I Ccid +discovers and configures SIM or SAM cards using the CCID standard. +It provides a file system (usually mounted at +.BR /dev ) +that includes three files, +.BI ctl , +.B raw +and +.BI rpc . +Reading from +.B ctl +a description of the smartcard reader capabilities is printed. +.B raw +is just intended for debugging. +Reads and writes to the +raw file send and receive raw CCID packets. +Smart cards identify themselves by giving out an ATR, +an array of characters describing the card uniquely. +Users of the driver write the ATR to the +.B rpc +file and are blocked until a card with that ATR is seen. +From then on they can do ICC RPCs using whatever +language the smart card speaks. A small write cancels +an outstanding RPC. +.PP +The driver takes care of powering the card adequately, based +on its ATR, and tunnelling the RPCs through the USB device. +Only slot 0 is supported. +.PP +When the smartcard disappears, +all reads and write fail until the file is reopened and +a new ATR is written to it. +. +.ig +.SS Ibuddy +.PP +Ibuddy supports a USB I-buddy toy, a little winged-demon. +The driver provides one directory per attached toy with a single +.BR ctl +file to control the device. +Directories are named +.BR ibuddyN , +being +.I N +the corresponding usb device number. +When read, the +.BR ctl +file provides the state of the device in this form: +.IP +.EX +hips right|left +wings open|close +red on|off +green on|off +blue on|off +heart on|off +.EE +.PP +Each line describes the status of one feature. +.IR Red , +.IR blue , +and +.IR green +are the different leds in the head of +the toy. +.IR Heart +represents the red led in the chest of +the toy. +.IR Wings +represents the status of the wings, which +can be closed or open. +.IR Hips +represents the orientation +of the toy (left or right, from the figure's point of view). +.PP +Lines can be written to the +.BR ctl +file to command the device. +Multiple lines (six at most) can be written +at once, with one action per line. +.. +.SH SOURCE +.B /sys/src/cmd/usb +.SH "SEE ALSO" +.IR kbin (3), +.IR mouse (3), +.IR sd (3), +.IR uart (3), +.IR usb (3), +.IR usbd (4), +.IR partfs (8) +.SH BUGS +The various device drivers are generic USB drivers and +may work only for certain devices on each class. +.PP +USB ATA storage devices are not supported. +.PP +The Ethernet device works only for certain ASIX-based cards and for CDC devices. +Both the Ethernet and printer drivers have not +been tested and it is likely they will fail. +.PP +The serial driver works only for the Prolific chip and Ftdi, +and control of the +.B dcd +and +.B dsr +signals and some of the extra features are unimplemented. +For Ftdi, only the Sheevaplug and Guruplug have been tried. +There is support for the EHCI debug port, but it loses bytes. diff --git a/sys/man/4/usbd b/sys/man/4/usbd new file mode 100755 index 000000000..c0d3ca6cd --- /dev/null +++ b/sys/man/4/usbd @@ -0,0 +1,245 @@ +.TH USBD 4 +.SH NAME +usbd \- Universal Serial Bus daemon +.SH SYNOPSIS +.B usbd +[ +.B -Dd +] +[ +.B -s +.I srv +] +[ +.B -m +.I mnt +] +[ +.I hub... +] +.SH DESCRIPTION +.I Usbd +complements +.IR usb (3) +to provide USB I/O for device drivers. +It enumerates the bus, polling +hub ports to detect device attachments and detachments, performs +initial configuration of setup endpoints, and writes extra information into +.IR usb (3) +endpoint control files, to ease device location. +.PP +By default, +.I usbd +opens all setup endpoints found at +.B #u/usb +(which correspond to built-in hubs initialized by the kernel during boot). +Paths to directories representing setup endpoints for hubs can be given +as arguments to restrict +.I usbd +operation to such hubs. +.PP +When a device is attached, +depending upon a configuration file compiled into +.I usbd , +the appropriate device driver may be started without +user intervention. +This mechanism can be used to statically link some USB device drivers into +.I usbd +itself. +Initial configuration for setup endpoints is performed independently +of this configuration. +.PP +.I Usbd +provides a file interface used to change debugging flags, and also used by +USB device drivers statically linked into +.IR usbd . +By default, the file system is mounted (after) at +.B /dev +and a 9P connection is posted at +.BR /srv/usb . +.PP +Besides files provided by device drivers, the file +.B usbdctl +is always present in the file interface. +It accepts these control requests: +.TF "fsdebug\fI n +.TP +.BI debug " n" +Sets the debugging level to +.IR n . +.TP +.BI fsdebug " n" +Sets the file system debugging level to +.IR n . +.TP +.B dump +Prints the list of devices and file systems known by +.IR usbd . +.PD +.PP +.I Usbd +recognizes the following options: +.TF "-m\fI mnt +.TP +.B -d +Print debugging diagnostics. +Repeating the option increases verbosity. +.TP +.B -D +Print debugging diagnostics for the file system interface. +.TP +.BI -m " mnt" +Mount the served file system at +.IR mnt . +.TP +.BI -s " srv" +Post a 9P connection at +.BI #s/ srv. +.PD +.SS Configuration +.PP +.I Usbd +can be configured to start drivers for devices matching one or more CSPs +(hex representation of USB class, subclass and protocol), class, +subclass, protocol, vendor id, or device id. +When a new device is attached, +.I usbd +scans the configuration and, if an entry matches the device descriptor, starts +the driver. +If no driver is configured, the setup endpoint for the device is left +configured to let the user start the driver by hand. +.PP +Configuration is via compilation +because one of the options is to embed (link) the driver into the +.I usbd +binary. +If the driver is embedded, +.I usbd +creates a process for it and calls its main entry point. +Otherwise, +.I usbd +tries to locate the driver binary in +.B /bin/usb +and creates a process to execute it. +.PP +The configuration file, +.BR usbdb , +has two sections: +.B embed +and +.BR auto . +Each section includes lines to configure particular drivers. +A driver may have more than one line if necessary. +Each line includes the name of the +driver (the base name of the binary) and one or more attributes of the form +.IP +.IR name = value +.PP +The following attributes exist: +.TF subclass +.TP +.B class +.I Value +may be the name of the class +or a number identifying the device class (using C syntax). +The following class names are known: +.BR audio , +.BR comms , +.BR hid , +.BR printer , +.BR storage , +.BR hub , +and +.BR data . +.TP +.B subclass +.I Value +is the number of the device subclass. +.TP +.B proto +.I Value +is the number of the device protocol. +.TP +.B csp +.I Value +is the hexadecimal number describing the CSP for the device. +.TP +.B vid +.I Value +is the vendor id. +.TP +.B did +.I Value +is the device id. +.TP +.B args +This must be the last field. +The value is the rest of the line, +and is supplied as arguments to the driver process. +.PD +.LP +Several environment variables can be used to alter the behaviour of +.IR usbd , +for example, for use in +.IR plan9.ini (8). +.B usbdebug +sets a debug level (zero for no diagnostics and positive +values for increasing verbosity). +.B kbargs +overrides the keyboard arguments as specified by the configuration file. +.B diskargs +overrides the disk arguments in the same way. +.SH EXAMPLE +This configuration file links +.B usb/kb +into +.I usbd +when it is compiled. +It arranges for the driver's entry point, +.B kbmain +in this case, +to be called for any device with CSPs matching either +.B 0x010103 +or +.BR 0x020103 . +Option +.B -d +will be supplied as command line arguments for +.BR kbmain . +This configuration also arranges for +.B /bin/usb/disk +to start (with no arguments) whenever a device of class +.B storage +is attached. +.IP +.EX +embed + kb csp=0x010103 csp=0x020103 args=-d +auto + disk class=storage args= +.EE +.SH FILES +.TF /srv/usb +.TP +.B /srv/usb +9P connection to the driver file system. +.TP +.B /dev +mount point for the driver file system. +.TP +.B /sys/src/cmd/usb/usbd/usbdb +Configuration file deciding which devices are included into +.I usbd +and which ones are started automatically. +.SH SOURCE +.B /sys/src/cmd/usb/usbd +.SH "SEE ALSO" +.IR usb (2), +.IR usb (3), +.IR usb (4) +.SH BUGS +.I Usbd +is not supposed to be restarted. +This is arguable. +.PP +Not heavily exercised yet. diff --git a/sys/man/4/vacfs b/sys/man/4/vacfs new file mode 100755 index 000000000..608fd2a29 --- /dev/null +++ b/sys/man/4/vacfs @@ -0,0 +1,90 @@ +.TH VACFS 4 +.SH NAME +vacfs \- a Venti-based file system +.SH SYNOPSIS +.B vacfs +[ +.B -dips +] +[ +.B -c +.I cachesize +] +[ +.B -h +.I host +] +[ +.B -m +.I mtpt +] +[ +.B -S +.I srvname +] +.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: +.TF "-c\fI cachesize" +.PD +.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 +.BI -p +Disables permission checking. +.TP +.B -s +Post the 9P channel in +.B /srv/vacfs +rather than +mounting it on +.IR mtpt . +.TP +.BI -S " srvname +Post the 9P channel in +.BI /srv/ srvname +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/sys/man/4/webcookies b/sys/man/4/webcookies new file mode 100755 index 000000000..63842e90f --- /dev/null +++ b/sys/man/4/webcookies @@ -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/sys/man/4/webfs b/sys/man/4/webfs new file mode 100755 index 000000000..5f0d40720 --- /dev/null +++ b/sys/man/4/webfs @@ -0,0 +1,308 @@ +.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 allocate 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 interpreted. +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 +.SH EXAMPLE +.B /sys/src/cmd/webfs/webget.c +is a simple client. +.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/sys/man/4/wikifs b/sys/man/4/wikifs new file mode 100755 index 000000000..2f19597f6 --- /dev/null +++ b/sys/man/4/wikifs @@ -0,0 +1,339 @@ +.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 +.PP +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/sys/man/5/0intro b/sys/man/5/0intro new file mode 100755 index 000000000..378393e56 --- /dev/null +++ b/sys/man/5/0intro @@ -0,0 +1,607 @@ +.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 uname [ s ] +.IR aname [ s ] +.br +.br +.IR size [4] +.B Rauth +.IR tag [2] +.IR aqid [13] +.IP +.ne 2v +.IR size [4] +.B Rerror +.IR tag [2] +.IR ename [ s ] +.IP +.ne 2v +.IR size [4] +.B Tflush +.IR tag [2] +.IR oldtag [2] +.br +.IR size [4] +.B Rflush +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tattach +.IR tag [2] +.IR fid [4] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.IR size [4] +.B Rattach +.IR tag [2] +.IR qid [13] +.IP +.ne 2v +.IR size [4] +.B Twalk +.IR tag [2] +.IR fid [4] +.IR newfid [4] +.IR nwname [2] +.IR nwname *( wname [ s ]) +.br +.IR size [4] +.B Rwalk +.IR tag [2] +.IR nwqid [2] +.IR nwqid *( wqid [13]) +.IP +.ne 2v +.IR size [4] +.B Topen +.IR tag [2] +.IR fid [4] +.IR mode [1] +.br +.IR size [4] +.B Ropen +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IP +.ne 2v +.IR size [4] +.B 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 four-byte qid +.IR version , +then the eight-byte qid +.IR path . +The path is an integer unique among all files in the hierarchy. +If a file is deleted and recreated with the +same name in the same directory, the old and new path components of the qids +should be different. +The version is a version number for a file; +typically, it is incremented every time the file is modified. +.PP +An existing file can be +.BR opened , +or a new file may be +.B created +in the current (directory) file. +I/O of a given number of bytes +at a given offset +on an open file is done by +.B read +and +.BR write . +.PP +A client should +.B clunk +any fid that is no longer needed. +The +.B remove +transaction deletes files. +.PP +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; +if bit 26 +.RB ( DMTMP ) +is set, the contents of the file (or directory) are not included in nightly archives. +(Bit 28 is skipped for historical reasons.) +These bits are reproduced, from the top bit down, in the type byte of the Qid: +.BR QTDIR , +.BR QTAPPEND , +.BR QTEXCL , +(skipping one bit) +.BR QTAUTH , +and +.BR QTTMP . +The name +.BR QTFILE , +defined to be zero, +identifies the value of the type for a plain file. diff --git a/sys/man/5/INDEX b/sys/man/5/INDEX new file mode 100755 index 000000000..a3b62ae88 --- /dev/null +++ b/sys/man/5/INDEX @@ -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/sys/man/5/INDEX.html b/sys/man/5/INDEX.html new file mode 100755 index 000000000..35d30ca76 --- /dev/null +++ b/sys/man/5/INDEX.html @@ -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/sys/man/5/attach b/sys/man/5/attach new file mode 100755 index 000000000..dd21c6b60 --- /dev/null +++ b/sys/man/5/attach @@ -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/sys/man/5/clunk b/sys/man/5/clunk new file mode 100755 index 000000000..6256b3c46 --- /dev/null +++ b/sys/man/5/clunk @@ -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/sys/man/5/error b/sys/man/5/error new file mode 100755 index 000000000..093108a6d --- /dev/null +++ b/sys/man/5/error @@ -0,0 +1,28 @@ +.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 +.B ERRMAX-1 +bytes; +.B ERRMAX +is defined in +.BR . diff --git a/sys/man/5/flush b/sys/man/5/flush new file mode 100755 index 000000000..2ab7809e8 --- /dev/null +++ b/sys/man/5/flush @@ -0,0 +1,99 @@ +.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 should answer the +.B flush +message immediately. +If it recognizes +.I oldtag +as the tag of a pending transaction, it should abort any pending response +and discard that tag. +In either case, it should respond with an +.B Rflush +echoing the +.I tag +(not +.IR oldtag ) +of the +.B Tflush +message. +A +.B Tflush +can never be responded to by an +.B Rerror +message. +.PP +The server may respond to the pending request before +responding to the +.BR Tflush . +It is possible for a client to send multiple +.B Tflush +messages for a particular pending request. Each +subsequent +.B Tflush +must contain as +.I oldtag +the tag of the pending request (not a previous +.BR Tflush ). +Should multiple +.BR Tflush es +be received for a pending request, they must be answered in +order. A +.B Rflush +for any of the multiple +.BR Tflush es +implies an answer for all previous ones. Therefore, should +a server receive a request and then multiple flushes for that +request, it need respond only to the last flush. +.PP +When the client sends a +.BR Tflush , +it must wait to receive the corresponding +.B Rflush +before reusing +.I oldtag +for subsequent messages. +If a response to the flushed request is received before the +.BR Rflush , +the client must honor the response +as if it had not been flushed, +since the completed request may signify a state change in the server. +For instance, +.B Tcreate +may have created a file and +.B Twalk +may have allocated a fid. +If no response is received before the +.BR Rflush , +the flushed transaction is considered to have been canceled, +and should be treated as though it had never been sent. +.PP +Several exceptional conditions are handled correctly by the above specification: +sending multiple flushes for a single tag, +flushing after a transaction is completed, +flushing a +.BR Tflush , +and flushing an invalid tag. diff --git a/sys/man/5/open b/sys/man/5/open new file mode 100755 index 000000000..6672c694f --- /dev/null +++ b/sys/man/5/open @@ -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/sys/man/5/read b/sys/man/5/read new file mode 100755 index 000000000..4438ee984 --- /dev/null +++ b/sys/man/5/read @@ -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/sys/man/5/remove b/sys/man/5/remove new file mode 100755 index 000000000..ccdc1b3dd --- /dev/null +++ b/sys/man/5/remove @@ -0,0 +1,49 @@ +.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. +.PP +If a file has been opened as multiple fids, +possibly on different connections, +and one fid is used to remove the file, +whether the other fids continue to provide access to the file +is implementation-defined. +The Plan 9 file servers (like +.IR fs (4)) +remove the file immediately: attempts to use the other fids +will yield a +``phase error.'' +.IR U9fs (4) +follows the semantics of the underlying Unix file system, +so other fids typically remain usable. +.SH ENTRY POINTS +.B Remove +messages are generated by +.IR remove . diff --git a/sys/man/5/stat b/sys/man/5/stat new file mode 100755 index 000000000..29c02011f --- /dev/null +++ b/sys/man/5/stat @@ -0,0 +1,298 @@ +.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), +.B 0x04000000 +.RB ( DMTMP , +temporary); +these are echoed in +.BR Qid.type . +Writes to append-only files always place their data at the +end of the file; the +.I offset +in the +.B write +message is ignored, as is the +.B OTRUNC +bit in an open. +Exclusive use files may be open for I/O by only one fid at a time +across all clients of the server. If a second open is attempted, +it draws an error. Servers may implement a timeout on the lock +on an exclusive use file: if the fid holding the file open has +been unused for an extended period (of order at least minutes), +it is reasonable to break the lock and deny the initial fid +further I/O. +Temporary files are not included in nightly archives +(see +.IR fossil (4)). +.PP +The two time fields are measured in seconds since the epoch +(Jan 1 00:00 1970 GMT). +The +.I mtime +field reflects the time of the last change of content (except when later changed by +.BR wstat ). +For a plain file, +.I mtime +is the time of the most recent +.BR create , +.B open +with truncation, +or +.BR write ; +for a directory it is the time of the most recent +.BR remove , +.BR create , +or +.B wstat +of a file in the directory. +Similarly, the +.I atime +field records the last +.B read +of the contents; +also it is set whenever +.I mtime +is set. +In addition, for a directory, it is set by +an +.BR attach , +.BR walk , +or +.BR create , +all whether successful or not. +.PP +The +.I muid +field names the user whose actions most recently changed the +.I mtime +of the file. +.PP +The +.I length +records the number of bytes in the file. +Directories and most files representing devices have a conventional +length of 0. +.PP +The +.B stat +request requires no special permissions. +.PP +The +.B wstat +request can change some of the file status information. +The +.I name +can be changed by anyone with write permission in the parent directory; +it is an error to change the name to that of an existing file. +The +.I length +can be changed (affecting the actual length of the file) by anyone with +write permission on the file. +It is an error to attempt to set the length of a directory to a non-zero value, +and servers may decide to reject length changes for other reasons. +The +.I mode +and +.I mtime +can be changed by the owner of the file or the group leader of the file's current +group. +The directory bit cannot be changed by a +.BR wstat ; +the other defined permission and mode bits can. +The +.I gid +can be changed: by the owner if also a member of the new group; or +by the group leader of the file's current group +if also leader of the new group +(see +.IR intro (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/sys/man/5/version b/sys/man/5/version new file mode 100755 index 000000000..c7236e2e7 --- /dev/null +++ b/sys/man/5/version @@ -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/sys/man/5/walk b/sys/man/5/walk new file mode 100755 index 000000000..61439459b --- /dev/null +++ b/sys/man/5/walk @@ -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/sys/man/6/0intro b/sys/man/6/0intro new file mode 100755 index 000000000..281f10b6e --- /dev/null +++ b/sys/man/6/0intro @@ -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/sys/man/6/INDEX b/sys/man/6/INDEX new file mode 100755 index 000000000..9d8e496d7 --- /dev/null +++ b/sys/man/6/INDEX @@ -0,0 +1,41 @@ +0intro 0intro +intro 0intro +a.out a.out +ar ar +authsrv authsrv +p9any authsrv +p9sk1 authsrv +p9sk2 authsrv +color color +face face +font font +subfont font +htmlroff htmlroff +image image +keyboard keyboard +keys.who keys.who +man man +map map +mhtml mhtml +mnihongo mnihongo +mpictures mpictures +ms ms +namespace namespace +ndb ndb +plot plot +plumb plumb +regexp regexp +rewrite rewrite +smtpd smtpd +snap snap +style style +thumbprint thumbprint +users users +ASCII utf +UTF utf +Unicode utf +rune utf +utf utf +venti venti +venti.conf venti.conf +vgadb vgadb diff --git a/sys/man/6/INDEX.html b/sys/man/6/INDEX.html new file mode 100755 index 000000000..816e636eb --- /dev/null +++ b/sys/man/6/INDEX.html @@ -0,0 +1,137 @@ + +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 protocols +
authsrv, p9any, p9sk1, p9sk2 + +
color +- representation of pixels and colors +
color + +
face +- face files +
face + +
font +- external format for fonts and subfonts +
font, subfont + +
htmlroff +- HTML formatting and typesetting +
htmlroff + +
image +- external format for images +
image + +
keyboard +- how to type characters +
keyboard + +
keys.who +- biographic information for key holders +
keys.who + +
man +- macros to typeset manual +
man + +
map +- digitized map formats +
map + +
mhtml +- macros for formatting HTML +
mhtml + +
mnihongo +- macros for typesetting Japanese +
mnihongo + +
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 + +
style +- Plan 9 coding conventions for C +
style + +
thumbprint +- public key thumbprints +
thumbprint + +
users +- file server user list format +
users + +
utf +- character set and format +
UTF, Unicode, ASCII, rune + +
venti +- archival storage server +
venti + +
venti.conf +- a venti configuration file +
venti.conf + +
vgadb +- VGA controller and monitor database +
vgadb + +
diff --git a/sys/man/6/a.out b/sys/man/6/a.out new file mode 100755 index 000000000..a4fa5db21 --- /dev/null +++ b/sys/man/6/a.out @@ -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/sys/man/6/ar b/sys/man/6/ar new file mode 100755 index 000000000..669be0739 --- /dev/null +++ b/sys/man/6/ar @@ -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/sys/man/6/authsrv b/sys/man/6/authsrv new file mode 100755 index 000000000..911b1f4b1 --- /dev/null +++ b/sys/man/6/authsrv @@ -0,0 +1,726 @@ +.TH AUTHSRV 6 +.SH NAME +authsrv, p9any, p9sk1, p9sk2 \- authentication protocols +.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, +.IR factotum (4) +prompts for user name and password. +The user name becomes the terminal's authentication ID. +The password is converted using +.I passtokey +(see +.IR authsrv (2)) +into a 56-bit DES key and saved in memory. +The authentication domain is set to the null string. +If possible, +.I factotum +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, +.I factotum +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 Ks +server's host ID's key +.TP +.I Kc +client's host ID's key +.TP +.I Kn +a nonce key created for a ticket +.RB ( key ) +.TP +.IR K { m } +message +.I m +encrypted with key +.I K +.TP +.I CHc +an 8-byte random challenge from a client +.RB ( chal ) +.TP +.I CHs +an 8-byte random challenge from a server +.RB ( chal ) +.TP +.I IDs +server's ID +.RB ( authid ) +.TP +.I DN +server's authentication domain name +.RB ( authdom ) +.TP +.I IDc +client's ID +.RB ( hostid , +.BR cuid ) +.TP +.I IDr +client's desired ID on server +.RB ( uid , +.BR suid ) +.PD +.PP +The parenthesized names are the ones used in the +.B Ticketreq +and +.B Ticket +structures in +.BR . +.PP +The message type constants +.IR AuthTreq , +.IR AuthChal , +.IR AuthPass , +.IR AuthOK , +.IR AuthErr , +.IR AuthMod , +.IR AuthApop , +.IR AuthOKvar , +.IR AuthChap , +.IR AuthMSchap , +.IR AuthCram , +and +.IR AuthVNC +.RB ( type ) +are defined in +.BR , +as are the encrypted message types +.IR AuthTs , +.IR AuthAs , +.IR AuthAc , +.IR AuthTp , +and +.IR AuthHr +.RB ( num ). +.SS "Ticket Service +When a client and server wish to authenticate to each other, +they do so using +.I tickets +issued by the AS. +Obtaining tickets from the AS +is the client's responsibility. +.PP +The protocol to obtain a ticket pair is: +.TP +.IR C \(-> A +.IR AuthTreq , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDc , +.IR IDr +.sp -\n(PDu +.TP +.IR A \(-> C +.IR AuthOK , +.IR Kc { AuthTc , +.IR CHs , +.IR IDc , +.IR IDr , +.IR Kn }, +.IR Ks { AuthTs , +.IR CHs , +.IR IDc , +.IR IDr , +.IR Kn } +.PP +The two tickets are identical except for their type fields +and the keys with which they are encrypted. +The client and server can each decrypt one of the tickets, +establishing a shared secret +.IR Kn . +.PP +The +tickets can be viewed as a statement by the +AS that +``a client possessing the +.I Kn +key is allowed to authenticate as +.IR IDr .'' +.PP +The presence of the server challenge +.I CHs +in the ticket allows the server to verify the freshness +of the ticket pair. +.PP +The AS sets the +.I IDr +in the tickets to the requested +.I IDr +only if +.I IDc +is allowed to +.I "speak for +.RI ( q.v. ) +.IR IDr . +If not, +the AS sets +.I IDr +to the empty string. +.PP +If the users +.I IDc +or +.I IDs +do not exist, +the AS silently generates one-time +random keys to use in place of +.I Kc +or +.IR Ks , +so that clients cannot probe the AS +to learn whether a user name is valid. +.SS "P9sk1 +The Plan 9 shared key protocol +.I p9sk1 +allows a client and server to authenticate each other. +The protocol is: +.TP +.IR C \(-> S +.I CHc +.br +The client starts by sending a random challenge to the server. +.TP +.IR S \(-> C +.IR AuthTreq , +.IR IDs , +.IR DN , +.IR CHs , +.IR \- , +.IR \- +.br +The server replies with a ticket request giving its +id and authentication domain along with its own +random challenge. +.TP +.IR C \(-> S +.IR Ks { AuthTs , +.IR CHs , +.IR IDc , +.IR IDr , +.IR Kn }, +.IR Kn { AuthAc , +.IR CHs } +.br +The client adds +.I IDc +and +.I IDr +to the ticket request and obtains a ticket pair +from the AS as described above. +The client relays the server's ticket along with +an +.IR authenticator , +the +.I AuthAc +message. +The authenticator proves to the server that the +client knows +.I Kn +and is therefore allowed to authenticate as +.IR IDr . +(The inclusion of +.IR CHs +in the authenticator avoids replay attacks.) +.TP +.IR S \(-> C +.IR Kn { AuthAs , +.IR CHc } +.br +The server replies with its own authenticator, +proving to the client that it also knows +.I Kn +and therefore +.I Ks . +.PD +.PP +.I P9sk2 +is an older variant of +.I p9sk1 +used only when connecting to pre-9P2000 remote +execution services. +It omits the first message and last +messages and therefore does not +authenticate the server to the client. +.SS "P9any +.I P9any +is the standard Plan 9 authentication protocol. +It consists of a negotiation to determine a common +protocol, followed by the agreed-upon protocol. +.PP +The negotiation protocol is: +.TP +.IR S \(-> C +.B v.2 +.IB proto@authdom +.IB proto@authdom +.I ... +.sp -\n(PDu +.TP +.IR C \(-> S +.I proto +.I dom +.sp -\n(PDu +.TP +.IR S \(-> C +.B OK +.PP +Each message is a NUL-terminated UTF string. +The server begins by sending a list of +.IR proto , +.I authdom +pairs it is willing to use. +The client +responds with its choice. +Requiring the client to wait for the final +.B OK +ensures that the client will not start +the chosen protocol until the server is ready. +.PP +The above is version 2 of the protocol. +Version 1, +no longer used, +omitted the first message's +.B v.2 +prefix +and the +.B OK +message. +.PP +The +.I p9any +protocol is the protocol used by all +Plan 9 services. +The file server runs it over special +authentication files +(see +.IR fauth (2) +and +.IR attach (5)). +Other services, such as +.IR cpu (1) +and +.IR exportfs (4), +run +.I p9any +over the network and then +use +.I Kn +to derive an +.IR ssl (3) +key to encrypt the rest of their communications. +.SS "Password Change +Users connect directly to the AS +to change their passwords. +The protocol is: +.TP +.IR C \(-> A +.IR AuthPass , +.IR IDc , +.IR DN , +.IR CHc , +.IR IDc , +.IR IDc +.br +The client sends a password change ticket request. +.TP +.IR A \(-> C +.IR Kc { AuthTp , +.IR CHc , +.IR IDc , +.IR IDc , +.IR Kn } +.br +The server responds with a ticket containing the key +.I Kn +encrypted with the client's key +.IR Kc +.TP +.IR C \(-> A +.IR Kn { AuthPass , +.IR old , +.IR new , +.IR changesecret , +.IR secret } +.br +The client decrypts the ticket using the old password +and then sends back an encrypted password request +.RB ( Passwordreq +structure) +containing the old password and the new password. +If +.I changesecret +is set, the AS also changes +the user's +.IR secret , +the password used for non-Plan 9 authentications. +.TP +.IR A \(-> C +.I AuthOK +or +.IR AuthErr , +64-byte error message +.br +The AS responds with simply +.I AuthOK +or with +.I AuthErr +followed by a 64-byte error message. +.SS "Authentication Database +An +.IR ndb (2) +database file +.B /lib/ndb/auth +exists for the AS. +This database maintains ``speaks for'' relationships, i.e., +it lists which users may speak for other users when +authtenticating. +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: +.PP +.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 . +This property is used heavily on CPU servers. +.SS "Foreign Protocols +The AS accepts ticket request +messages of types other than +.I AuthTreq +to allow users to +authenticate using non-Plan 9 protocols. +In these situations, the server communicates +directly with the AS. +Some protocols must begin without knowing the +client's name. They ignore the client name in the +ticket request. +All the protocols end +with the AS sending +an +.I AuthOK +message containing a server ticket and authenticator. +.PP +.I AuthOK +messages +always have a fixed but context-dependent size. +The occasional variable-length OK message starts with a +.I AuthOKvar +byte and a five-byte space-padded decimal length of the +data that follows. +.PP +Anywhere an +.I AuthOK +message is expected, a +.I AuthErr +message may be substituted. +.de Ok +.sp -\n(PDu +.TP +.IR A \(-> S +.IR AuthOK , +.IR Ks { \\$1 , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDs , +.IR IDc , +.IR Kn }, +.IR Kn { AuthTs , +.IR CHs } +.. +.PP +.TP +.IR S \(-> A +.IR AuthChal , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDs , +.IR IDc +.sp -\n(PDu +.TP +.IR A \(-> S +.IR AuthOK , +.IR challenge +.sp -\n(PDu +.TP +.IR S \(-> A +.IR response +.Ok AuthChal +.IP +This protocol allows the use of +handheld authenticators such as SecureNet +keys and SecureID tokens +in programs such as +.IR ssh (1) +and +.I ftpd +(see +.IR ipserv (8)). +.IP +.I Challenge +and +.I response +are text strings, +.SM NUL -padded +to 16 bytes +.RB ( NETCHLEN ). +The +.I challenge +is a random five-digit decimal number. +When using a SecureNet key or +.I netkey +(see +.IR passwd (1)), +the +.I response +is an eight-digit decimal or hexadecimal number +that is an encryption of the challenge +using the user's DES key. +.IP +When using a SecureID token, +the challenge is ignored. +The response is the user's PIN followed by +the six-digit number currently displayed +on the token. +In this case, the AS +queries an external RADIUS server +to check the response. +Use of a RADIUS server requires an entry in +the authentication database. For example: +.IP +.EX + radius=server-name secret=xyzzy + uid=howard rid=trickey + uid=sape rid=smullender +.EE +.IP +In this example, the secret +.B xyzzy +is the hash key used in talking to the RADIUS server. +The +.BR uid / rid +lines map from Plan 9 user ids to RADIUS ids. +Users not listed are assumed to have the +same id in both places. +.TP +.IR S \(-> A +AuthApop , +.IR IDs , +.IR DN , +.IR CHs , +.IR \- , +.IR \- +.sp -\n(PDu +.TP +.IR A \(-> S +.IR AuthOKvar , +.IR challenge +.sp -\n(PDu +.TP +.IR S \(-> A +AuthApop , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDc , +.IR IDc ; +hexadecimal MD5 checksum +.Ok AuthApop +.IP +This protocol implements APOP authentication +(see +.IR pop3 (8)). +After receiving a ticket request of type +.IR AuthApop , +the AS generates a random challenge +of the form +.BI < random @ domain >\fR. +The client then replies with a new ticket request +giving the user name +followed by the MD5 checksum of +the challenge concatenated with the user's secret. +If the response is correct, the authentication +server sends back a ticket +and authenticator. +If the response is incorrect, the client may repeat the +ticket request/MD5 checksum message to try again. +.IP +The +.I AuthCram +protocol runs identically to the +.I AuthApop +protocol, except that the expected MD5 checksum +is the keyed MD5 hash using the user's secret as the key +(see +.I hmac_md5 +in +.IR sechash (2)). +.TP +.IR S \(-> A +.IR AuthChap , +.IR IDs , +.IR DN , +.IR CHs , +.IR \- , +.IR \- +.sp -\n(PDu +.TP +.IR A \(-> S +.I challenge +.sp -\n(PDu +.TP +.IR S \(-> A +.IR pktid , +.IR IDc , +.IR response +.Ok AuthChap +.IP +This protocol implements CHAP authentication +(see +.IR ppp (8)). +The +.I challenge +is eight random bytes. +The response is a 16-byte MD5 checksum +over the packet id, user's secret, and challenge. +The reply packet is defined as +.B OChapreply +in +.BR . +.TP +.IR S \(-> A +.IR AuthMSchap , +.IR IDs , +.IR DN , +.IR CHs , +.IR \- , +.IR \- +.sp -\n(PDu +.TP +.IR A \(-> S +.I challenge +.sp -\n(PDu +.TP +.IR S \(-> A +.IR IDc , +.IR lm-response , +.IR nt-response +.Ok AuthMschap +.IP +This protocol implements Microsoft's MS-CHAP +authentication +(see +.IR ppp (8)). +The +.I challenge +is eight random bytes. +The two responses are Microsofts LM and NT hashes. +Only the NT hash may be used to authenticate, +as the LM hash is considered too weak. +The reply packet is defined as +.B OMSchapreply +in +.BR . +.TP +.IR S \(-> A +.IR AuthVNC , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDs , +.IR IDc +.sp -\n(PDu +.TP +.IR A \(-> S +.IR AuthOKvar , +.I challenge +.sp -\n(PDu +.TP +.IR S \(-> A +.I response +.Ok +.IP +This protocol implements VNC authentication +(see +.I vncs +in +.IR vnc (1)). +The challenge is 16 random bytes, and the response +is a DES ECB encryption of the challenge. +The method by which VNC converts the user's +secret into a DES key is weak, +considering only the first eight bytes of the secret. +.PD +.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/sys/man/6/color b/sys/man/6/color new file mode 100755 index 000000000..aedaee58d --- /dev/null +++ b/sys/man/6/color @@ -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/sys/man/6/face b/sys/man/6/face new file mode 100755 index 000000000..8820cec81 --- /dev/null +++ b/sys/man/6/face @@ -0,0 +1,116 @@ +.TH FACE 6 +.SH NAME +face \- face files +.SH DESCRIPTION +The directories +.B /usr/$user/lib/face +and +.B /lib/face +contain a hierarchy of images of people. +In those directories are subdirectories named by the sizes of +the corresponding image files: +.B 48x48x1 +(48 by 48 pixels, one bit per pixel); +.B 48x48x2 +(48 by 48 pixels, two (grey) bits per pixel); +.B 48x48x4 +(48 by 48 pixels, four (grey) bits per pixel); +.B 48x48x8 +(48 by 48 pixels, eight (color-mapped) bits per pixel); +.B 512x512x8 +(512 by 512 pixels, eight (color-mapped) bits per pixel); +.B 512x512x24 +(512 by 512 pixels, twenty-four bits per pixel (3 times 8 bits +per color)). +The large files serve no special purpose; they are stored +as images +(see +.IR image (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/sys/man/6/font b/sys/man/6/font new file mode 100755 index 000000000..c6263f66a --- /dev/null +++ b/sys/man/6/font @@ -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/sys/man/6/htmlroff b/sys/man/6/htmlroff new file mode 100755 index 000000000..96d974b88 --- /dev/null +++ b/sys/man/6/htmlroff @@ -0,0 +1,358 @@ +.TH HTMLROFF 6 +.SH NAME +htmlroff \- HTML formatting and typesetting +.SH DESCRIPTION +.IR Htmlroff (1) +accepts +.I troff +input with a few extensions and changes. +This manual describes the changes to the input language, +assuming a working knowledge of +.I troff +itself. +.SS Name lengths +.PP +Request, macro, string, and number names can be longer +than two letters, as in: +.IP +.EX +\&.html c
+\&.de footnote +Footnote here. +\&.. +\&.footnote +\&.ds string "hello +\&\e*[string] +\&.nr number 1 +\&\en[number] +.EE +.SS HTML output +.PP +Two new requests: +.IP +.EX +\&.html \fIid\fP \fR[ \fI\fP ]\fL +\&.ihtml \fIid\fP \fR[ \fI\fP ]\fL +.EE +.LP +.B .html +and +.B .ihtml +insert HTML into the output. +The requests are only for opening new HTML tags. +To close previously-opened tags, repeat the request +with the same +.IR id . +For example, the input: +.IP +.EX +\&.html t +\&.html td
Cell 1 +\&.html td Cell 2 +\&.html td +\&.html t +.EE +.LP +produces this output: +.IP +.EX +
Cell 1Cell 2
+.EE +.LP +The +.B .html +request is intended for block-level HTML constructs (those that can contain +.BR

) +and maintains the HTML tag stack automatically. +Intermediate tags need not be explicitly closed: +removing the final +.B \&.html t +line in the example above would produce the same output. +The special +.I id +.L - +closes the HTML tags immediately after printing them. +.PP +The +.B .ihtml +request is similar to +.B .html +but is intended for inline HTML constructs such as +.B +or +.B +(those that can be contained +within +.BR

). +Unlike +.BR .html , +.B .ihtml +treats the open HTML tags as a set rather than a stack: +each must be explicitly closed. +Although it treats the tags as a set, +.B .ihtml +treats nesting properly in the output, +closing and reopening tags as necessary. +For example, the input: +.IP +.EX +\&.ihtml style +\&.ihtml link +Bold +\&.ihtml style +and italic, still linked. +\&.ihtml link +Unlinked. +\&.ihtml style +.EE +.LP +produces this output: +.IP +.EX +Bold +and italic, still linked. +Unlinked. +.EE +.PP +Outside of +.B .html +and +.B .ihtml +requests, the characters +.LR < , +.LR > , +and +.L & +are treated as normal characters, not HTML markers, +and are translated to +.LR < , +.LR > , +and +.L & +on output. +To embed the raw HTML markers, use +.LR \e< , +.LR \e> , +and +.L \e@ +.RI [ sic ]. +.SS Font changes +.PP +.I Htmlroff +interprets the usual +.BR \ef , +.BR .ft , +.BR \es , +and +.B .ps +requests to change the font and point size. +After applying each such change to its internal registers, +.I htmlroff +invokes the +.B .font +macro to emit corresponding HTML. +The default definition of +.B .font +is: +.IP +.EX +\&.de font +\&.ihtml f1 +\&.ihtml f +\&.ihtml f +\&.if \\n(.f==2 .ihtml f1 +\&.if \\n(.f==3 .ihtml f1 +\&.if \\n(.f==4 .ihtml f1 +\&.if \\n(.f==5 .ihtml f1 +\&.if \\n(.f==6 .ihtml f1 +\&.. +.EE +.LP +Input files can redefine +.B .font +like any other request or macro. +.SS Paragraphs +.I Htmlroff +implements line height, text adjustment, and margins by +wrapping all output text in +.B

+tags. +This behavior can be disabled by setting the +.B .paragraph +number register to zero. +Setting the +.B .margin +register to zero +eliminates only the margin annotations. +.SS Subscripts and superscripts +.PP +.I Htmlroff +interprets the +.BR \eu , +.BR \ed , +and +.BR \ev +requests to move vertically during output. +It emits output vertically offset up the page inside +.B +tags and output vertically offset down the page +inside +.B +tags. +This heuristic handles simple equations formatted by +.IR eqn (1). +.SS Conditional input +.PP +To make it easier to write input files that can be formatted by both +.I troff +and +.IR htmlroff , +.I htmlroff +adds a new condition +.B h +which evaluates true in +.B .if +and +.B .ie +requests. +The +.B t +condition continues to evaluate true, to accomodate +input files trying to distinguish between +.I troff +and +.IR nroff . +To write a conditional matching +.I troff +alone, use +.RB ` ".if !h .if t" '. +.PP +.I Htmlroff 's +handling of conditional input does not match +.IR troff 's +exactly. +For example, +.IP +.EX +\&.if 0 \e{\e +\&.de xx +\&.. +\&.\e} +.EE +.LP +redefines the +.B xx +macro in +.I troff +but not in +.IR htmlroff . +Do not write files depending on this behavior, as this bug may be fixed +in the future. +.I Htmlroff +also mishandles +.B \e} +in some cases. To work around them, use +.B .\e} +on a line by itself, as in the last example. +.SS Diversions +.PP +Diversions in +.I htmlroff +use the alignment in effect at the time of the +diversion +when output. +In particular, +.IP +.EX +\&.di xx +Line here. +\&.di +\&.nf +\&.ce +\&.xx +.EE +.LP +produces a centered line in +.I troff +but not in +.IR htmlroff . +The solution is to center inside the diversion, as in +.IP +.EX +\&.di xx +\&.if h .ce 999 +Line here +\&.di +.EE +.SS Traps +.I Htmlroff +implements traps at vertical position 0, +which run when the first character is about +to be printed. +Other position traps are ignored. +Input traps are implemented. +.SS Input pipes +.PP +.I Htmlroff +adds a new request +.B .inputpipe +.I stop +.I cmd +that redirects +.IR htmlroff 's +input into a pipe to +.IR cmd . +The redirection stops on encountering the line +.IR stop , +optionally followed by white space and extra text. +This is a dangerous and clumsy request, as +.I htmlroff +stops interpreting its input during the redirection, so +.I stop +must be found in the input itself, not in a macro that +the input might appear to call. +Although clumsy, +.B .inputpipe +allows input files to invoke +.I troff +to handle complicated input. +For example, +.B tmac.html +redefines the +.B PS +macro that marks the beginning of a +.IR pic (1) +picture: +.IP +.EX +\&.nr png -1 1 +\&.de PS +\&.ds pngbase "\e\e*[basename] +\&.if '\e\e*[pngbase]'' .ds pngbase \e\en(.B +\&.ds pngfile \e\e*[pngbase]\e\en+[png].png +\&.html -

+\&.inputpipe .PE troff2png >\e\e*[pngfile] +\&.. +.EE +.LP +This macro invokes the shell script +.I troff2png +to run troff and convert the Postscript +output to a PNG image file. +Before starting the program, the macro creates +a new file name for the image and prints +HTML referring to it. +The +.B .B +register holds the final path element +(the base name) of the current input file. +.SS Unimplemented +Tabs are set every eight spaces and cannot be changed. +.PP +Some requests, such as +.BR .tl , +are unimplemented for lack of a good implementation. +Workarounds can be defined as necessary in input files. +.SH SEE ALSO +.IR htmlroff (1), +.IR mhtml (6) diff --git a/sys/man/6/image b/sys/man/6/image new file mode 100755 index 000000000..315608919 --- /dev/null +++ b/sys/man/6/image @@ -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/sys/man/6/keyboard b/sys/man/6/keyboard new file mode 100755 index 000000000..8c01eb0b3 --- /dev/null +++ b/sys/man/6/keyboard @@ -0,0 +1,195 @@ +.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. +.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/sys/man/6/keys.who b/sys/man/6/keys.who new file mode 100755 index 000000000..c7a768f23 --- /dev/null +++ b/sys/man/6/keys.who @@ -0,0 +1,45 @@ +.TH KEYS.WHO 6 +.SH NAME +keys.who \- biographic information for key holders +.SH DESCRIPTION +When +.I auth/changeuser +(see +.IR auth (8)) +creates or modifies an account, it writes a line of +biographical information to +.BR /adm/keys.who . +The line contains the following fields, separated by +.L | +characters: +.TP +.I name +login name +.TP +.I postid +company-wide user name +.TP +.I "full name +full name of the user +.TP +.I dept +department of the user +.TP +.I email... +one or more fields containing email addresses +to be notified when the key is about to expire +.PD +.PP +The program +.IR auth/warning , +which has fallen into disrepair, +once read +.I keys.who +and mailed expiry warnings. +.SH EXAMPLE +.EX +rsc|rscox|Russell S Cox|11276|rsc|dmr|rob +.EE +.SH "SEE ALSO +.IR keyfs (4), +.IR auth (8) diff --git a/sys/man/6/man b/sys/man/6/man new file mode 100755 index 000000000..09d5455f2 --- /dev/null +++ b/sys/man/6/man @@ -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/sys/man/6/map b/sys/man/6/map new file mode 100755 index 000000000..d767065a6 --- /dev/null +++ b/sys/man/6/map @@ -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/sys/man/6/mhtml b/sys/man/6/mhtml new file mode 100755 index 000000000..0aaf7608f --- /dev/null +++ b/sys/man/6/mhtml @@ -0,0 +1,105 @@ +.TH MHTML 6 +.SH NAME +mhtml \- macros for formatting HTML +.SH SYNOPSIS +.B pic +.B | +.B tbl +.B | +.B eqn +.B | +.B htmlroff +[ +.B -man +| +.B -ms +] +.B -mhtml +.I file +\&... +.SH DESCRIPTION +This package of +.IR htmlroff (1) +macro definitions provides convenient macros for formatting HTML. +It is usually used along with +.IR troff (1) +macro packages such as +.IR man (6) +and +.IR ms (6). +.I Mhtml +replaces some macros defined in the other packages, +so it should be listed after them on the +.I htmlroff +command line. +.PP +The following macros are defined: +.TP +.B .HTML \fItitle +Print an HTML header marking the output as +HTML 4.01 loose transitional encoded in UTF. +If given, the +.I title +is printed inside +.B +tags. +This macro opens the +.B <html> +tag, opens and closes the +.B <head> +section, and opens +.BR <body> . +It invokes the +.B .HEAD +macro inside the +.B <head> +section. +To add arbitrary lines to the header, +append to +.B .HEAD +before invoking +.BR .HTML . +.TP +.B .FS\fR, \fP.FE +Accumulate footnotes and print them at the end of the +document under a \fBNotes\fP heading. +These replace the macros in +.IR ms (6). +To emit the notes accumulated so far, invoke +.BR .NOTES . +.TP +.B .PS\fR, \fP.PE +Replace input bracketed +.B .PS +and +.B .PE +with a PNG image corresponding to the output of +running +.IR troff (1) +on the input. +.TP +.B .TS\fR, \fP.TE +Identical to +.B .PS +and +.BR .PE . +.TP +.B .B1 \fImargin\fP \fIwidth\fR, \fL.B2 +Format the input between +.B .B1 +and +.B .B2 +inside a box, with +.I margin +(default 10) +pixels between the box and the text. +The box is set to be +.I width +(default 60) +percent of the current output width. +.SH FILES +.B /sys/lib/tmac/tmac.html +.SH SEE ALSO +.IR htmlroff (1), +.IR htmlroff (6), +.IR ms (6) diff --git a/sys/man/6/mnihongo b/sys/man/6/mnihongo new file mode 100755 index 000000000..6ae8a1219 --- /dev/null +++ b/sys/man/6/mnihongo @@ -0,0 +1,30 @@ +.TH MNIHONGO 6 +.SH NAME +mnihongo \- macros for typesetting Japanese +.SH SYNOPSIS +.B troff -mnihongo +.I ... +.SH DESCRIPTION +.I Mnihongo +provides a simple +.IR troff (1) +post-processor that formats Unicode characters that +might be Japanese text. +It looks up the characters in the bitmap font +.B /lib/font/bit/pelm/unicode.9x24.font +and generates bitmap images embedded in the output. +.PP +During troff processing, widths of the Japanese characters +are taken from the troff font +.BR Jp , +which is at best a simple approximation to the truth. +.SH FILES +.B /bin/aux/mnihongo +.br +.B /sys/lib/tmac/tmac.nihongo +.br +.B /lib/font/bit/pelm/unicode.9x24.font +.SH SOURCE +.B /sys/src/cmd/aux/mnihongo +.SH SEE ALSO +.IR troff (1) diff --git a/sys/man/6/mpictures b/sys/man/6/mpictures new file mode 100755 index 000000000..7100118f3 --- /dev/null +++ b/sys/man/6/mpictures @@ -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/sys/man/6/ms b/sys/man/6/ms new file mode 100755 index 000000000..2a8047102 --- /dev/null +++ b/sys/man/6/ms @@ -0,0 +1,319 @@ +.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'.\fL.CW \fIx y z\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 z\fR no no Print +.I x +in boldface, append roman +.I y +and preface with +.IR z ; +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 z\fR no no Print +.I x +in bold italic, append roman +.I y +and preface with +.IR z ; +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 z\fR no no Constant width font for +.IR x , +append roman +.I y +and preface with +.IR z ; +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 z\fR no no Italicize +.IR x , +append roman +.I y +and preface with +.IR z ; +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). +If +.I n +is 0, reset the numbering. +.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/sys/man/6/namespace b/sys/man/6/namespace new file mode 100755 index 000000000..caf58b3dc --- /dev/null +++ b/sys/man/6/namespace @@ -0,0 +1,95 @@ +.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 +or +.I addns +subroutines +(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. +.TP +.BR clear +Clear the name space with +.BR rfork(RFCNAMEG) . +.TP +.BI . \ path +Execute the namespace file +.IR path . +Note that +.I path +must be present in the name space being built. +.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/sys/man/6/ndb b/sys/man/6/ndb new file mode 100755 index 000000000..f7b481f85 --- /dev/null +++ b/sys/man/6/ndb @@ -0,0 +1,351 @@ +.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 its +.B ip +and +.B ipmask +attributes. If the +.B ipmask +is missing, the relevant Class A, B or C one is used. +.LP +A search for an attribute associated with a network or host starts +at the lowest level, the entry for the host or network itself, +and works its way up, bit by bit, looking at entries for nets/subnets +that include the network or host. The search ends when the attribute +is found. +For example, consider the following entries: +.IP +.EX +ipnet=murray-hill ip=135.104.0.0 ipmask=255.255.0.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 . +Assume that we're searching for +.BR anna 's +.B NTP +and +.B SMTP +servers. +The search starts by looking for an entry with +.BR sys=anna . +We find the anna entry. Since it has an +.B smtp=smtp2.cs.bell-labs.com +pair, +we're done looking for that attribute. +To fulfill the NTP request, we continue by looking for networks +that include anna's IP address. +We lop off the right most one bit from anna's address and +look for an +.B ipnet= +entry with +.BR ip=135.104.9.4 . +Not finding one, we drop another bit and look for an +.B ipnet= +entry with +.BR ip=135.104.9.0 . +There is +such an entry and it has the pair, +.BR ntp=oncore.cs.bell-labs.com , +ending our search. +.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 dnsdomain +.TP +.B sys +system name (a short name) +.TP +.B dom +Internet fully-qualified domain name +.TP +.B ip +Internet address, +v4 or v6. +.TP +.B ipv6 +IPv6 Internet address. +For DNS, an +.L AAAA +record. +.TP +.B ether +Ethernet address +(must be lower-case hexadecimal). +Beware that for machines with multiple +.B ether +attributes, +.I dhcpd +may expect requests to come from the address in the first +.B ether +attribute. +.TP +.B bootf +file to download for initial bootstrap; +.B /386/9pxeload +to boot a PC via PXE. +.TP +.B ipnet +Internet network name +.TP +.B ipmask +Internet network mask +.TP +.B ipgw +Internet gateway +.TP +.B auth +authentication server to be used +.TP +.B authdom +authentication domain. Plan 9 supports multiple authentication +domains. To specify an authentication server for a particular domain, +add a tuple containing both +.B auth +and +.B authdom +attributes and values. +.TP +.B fs +file server to be used +.TP +.B tcp +a TCP service name +.TP +.B udp +a UDP service name +.TP +.B port +a TCP or UDP 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 +was needed by +.I cs +(see +.IR ndb (8)) +in tuples for hosts that supported 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); +also +.BR pref . +.TP +.B srv +service location (for DNS); +also +.BR pri , +.B weight +and +.BR port . +.TP +.B soa +start of area (for DNS) +.PD +.PP +.I Cs +defers to +.I dns +to translate dotted names to IP addresses, +only consulting the database files if +.I dns +cannot translate the name. +.PP +.I Cs +allows network entries with +.B sys +and +.B dom +attributes but no +.B ip +attribute. +Searches for the system name are resolved +by looking up the domain name with +.IR dns . +.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 +.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 +.TF /lib/ndb/local +.TP +.B /lib/ndb/local +first database file searched +.SH "SEE ALSO" +.IR con (1), +.IR dial (2), +.IR ndb (2), +.IR 9load (8), +.IR booting (8), +.IR dhcpd (8), +.IR ipconfig (8), +.IR ndb (8) diff --git a/sys/man/6/plot b/sys/man/6/plot new file mode 100755 index 000000000..73edcf0ed --- /dev/null +++ b/sys/man/6/plot @@ -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/sys/man/6/plumb b/sys/man/6/plumb new file mode 100755 index 000000000..bc58a5064 --- /dev/null +++ b/sys/man/6/plumb @@ -0,0 +1,417 @@ +.TH PLUMB 6 +.SH NAME +plumb \- format of plumb messages and rules +.SH SYNOPSIS +.B #include <plumb.h> +.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/sys/man/6/regexp b/sys/man/6/regexp new file mode 100755 index 000000000..58cc2ee1a --- /dev/null +++ b/sys/man/6/regexp @@ -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/sys/man/6/rewrite b/sys/man/6/rewrite new file mode 100755 index 000000000..c54032c32 --- /dev/null +++ b/sys/man/6/rewrite @@ -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/sys/man/6/smtpd b/sys/man/6/smtpd new file mode 100755 index 000000000..dcf16fbcc --- /dev/null +++ b/sys/man/6/smtpd @@ -0,0 +1,309 @@ +.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 +.I Smtpd +consults +.B /mail/ratify +(see +.IR ratfs (4)) +for a list of banned addresses. +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 +.B /mail/ratify +is mounted, +.I smtpd +will use it, even for connections 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 ratfs (4), +.IR scanmail (8) diff --git a/sys/man/6/snap b/sys/man/6/snap new file mode 100755 index 000000000..a7b1432d7 --- /dev/null +++ b/sys/man/6/snap @@ -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 at least 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/sys/man/6/style b/sys/man/6/style new file mode 100755 index 000000000..b0ae34d4a --- /dev/null +++ b/sys/man/6/style @@ -0,0 +1,109 @@ +.TH STYLE 6 +.SH NAME +style \- Plan 9 coding conventions for C +.SH DESCRIPTION +Plan 9 C code has its own conventions. +You would do well to follow them. +Here are a few: +.IP • 3 +don't use +.L // +comments; some old Plan 9 code does, but we're converting it as we touch it. +We do sometimes use +.L // +to comment-out a few lines of code. +.IP • +avoid +.BR goto s. +.IP • +no tabs expanded to spaces. +.IP • +surround a binary operator (particular a low precedence one) with spaces; +don't try to write the most compact code possible +but rather the most readable. +.IP • +parenthesize expressions involving arithmetic and bit-wise operators; +otherwise don't parenthesize heavily (e.g., as in Pascal). +.IP • +no white space before opening braces. +.IP • +no white space after the keywords +.LR if , +.LR for , +.LR while , +etc. +.IP • +no braces around single-line blocks (e.g., +.LR if , +.LR for , +and +.L while +bodies). +.IP • +integer-valued functions return -1 on error, 0 or positive on success. +.IP • +functions that return errors should set +.IR errstr (2). +.IP • +variable and function names are all lowercase, with no underscores. +.IP • +.B enum +or +.BR #define d +constants should be Uppercase (or UPPERCASE). +.IP • +.B struct +tags are Uppercase, with matching +.BR typedef s. +.IP • +automatic variables (local variables inside a function) are +never initialized at declaration. +.IP • +follow the standard idioms: use +.L "x < 0" +not +.LR "0 > x" , +etc. +.IP • +don't write +.L !strcmp +(nor +.LR !memcmp , +etc.) +nor +.LR "if(memcmp(a, b, c))" ; +always explicitly compare the result of string or memory +comparison with zero using a relational operator. +.PP +Ultimately, the goal is to write code that fits in with the other code +around it and the system as a whole. If the file you are editing +already deviates from these guidelines, do what it does. After you +edit a file, a reader should not be able to tell just from coding +style which parts you worked on. +.SS COMMENTS +If your code is readable, you shouldn't need many comments. A line or +two comment above a function explaining what it does is always welcome. +.PP +Comment any code you find yourself wondering about for more than 2 +seconds, even if it's to say that you don't understand what's going +on. Explain why. +.PP +Don't use commenting as an excuse for writing confusing code. Rewrite +the code to make it clear. +.SS EFFICIENCY +Do the simple thing. Don't optimize unless you've measured the code +and it is too slow. Fix the data structures and the algorithms +instead of going for little 5% tunings. +.SH SEE ALSO +``Notes on Programming in C'', Rob Pike, +.br +.B http://www.literateprogramming.com/pikestyle.pdf +.SH BUGS +Some programs use very different styles, for example, +.IR rc . +.PP +Some programs and programmers diverge from the above rules due to +habits formed long before these rules. +Notably, some programs have a single space after a keyword and +before an opening brace, +and some initialize automatic variables at declaration. diff --git a/sys/man/6/thumbprint b/sys/man/6/thumbprint new file mode 100755 index 000000000..63be911af --- /dev/null +++ b/sys/man/6/thumbprint @@ -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/sys/man/6/users b/sys/man/6/users new file mode 100755 index 000000000..6db15c98a --- /dev/null +++ b/sys/man/6/users @@ -0,0 +1,75 @@ +.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 id : name : leader :\fImembers\fP +.PP +where +.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 id +in a line is an identifier used in the on-disk structures maintained +by a file server; there should be no duplicate +.IR id s +in the file. +In +.IR fossil (4), +.IR id s +are arbitrary text strings, typically the same as +.IR name . +In older Plan 9 file servers, +.IR id s +are small decimal numbers. +In those, +a negative +.I id +is special: a user with a negative +.I id +cannot attach to the file server. +The file +.B /adm/users +itself is owned by user +.I adm +and write protected to others, +so it can only be changed via console commands. +.SH "SEE ALSO" +.IR intro (5), +.IR stat (5), +.IR fossilcons (8) diff --git a/sys/man/6/utf b/sys/man/6/utf new file mode 100755 index 000000000..92f7c9534 --- /dev/null +++ b/sys/man/6/utf @@ -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 FFFD. +.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/sys/man/6/venti b/sys/man/6/venti new file mode 100755 index 000000000..92296d506 --- /dev/null +++ b/sys/man/6/venti @@ -0,0 +1,451 @@ +.TH VENTI 6 +.SH NAME +venti \- archival storage server +.SH DESCRIPTION +Venti is a block storage server intended for archival 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 +This manual page documents the basic concepts of +block storage using Venti as well as the Venti network protocol. +.PP +.IR Venti (1) +documents some simple clients. +.IR Vac (1) +and +.IR vacfs (4) +are more complex clients. +.PP +.IR Venti (2) +describes a C library interface for accessing +Venti servers and manipulating Venti data structures. +.PP +.IR Venti (8) +describes the programs used to run a Venti server. +.PP +.SS "Scores +The SHA1 hash that identifies a block is called its +.IR score . +The score of the zero-length block is called the +.IR "zero score" . +.PP +Scores may have an optional +.IB label : +prefix, typically used to +describe the format of the data. +For example, +.IR vac (1) +uses a +.B vac: +prefix, while +.IR vbackup (8) +uses prefixes corresponding to the file system +types: +.BR ext2: , +.BR ffs: , +and so on. +.SS "Files and Directories +Venti accepts blocks up to 56 kilobytes in size. +By convention, Venti clients use hash trees of blocks to +represent arbitrary-size data +.IR files . +The data to be stored is split into fixed-size +blocks and written to the server, producing a list +of scores. +The resulting list of scores is split into fixed-size pointer +blocks (using only an integral number of scores per block) +and written to the server, producing a smaller list +of scores. +The process continues, eventually ending with the +score for the hash tree's top-most block. +Each file stored this way is summarized by +a +.B VtEntry +structure recording the top-most score, the depth +of the tree, the data block size, and the pointer block size. +One or more +.B VtEntry +structures can be concatenated +and stored as a special file called a +.IR directory . +In this +manner, arbitrary trees of files can be constructed +and stored. +.PP +Scores passed between programs conventionally refer +to +.B VtRoot +blocks, which contain descriptive information +as well as the score of a directory block containing a small number +of directory entries. +.PP +Conventionally, programs do not mix data and directory entries +in the same file. Instead, they keep two separate files, one with +directory entries and one with metadata referencing those +entries by position. +Keeping this parallel representation is a minor annoyance +but makes it possible for general programs like +.I venti/copy +(see +.IR venti (1)) +to traverse the block tree without knowing the specific details +of any particular program's data. +.SS "Block Types +To allow programs to traverse these structures without +needing to understand their higher-level meanings, +Venti tags each block with a type. The types are: +.PP +.nf +.ft L + VtDataType 000 \f1data\fL + VtDataType+1 001 \fRscores of \fPVtDataType\fR blocks\fL + VtDataType+2 002 \fRscores of \fPVtDataType+1\fR blocks\fL + \fR\&...\fL + VtDirType 010 VtEntry\fR structures\fL + VtDirType+1 011 \fRscores of \fLVtDirType\fR blocks\fL + VtDirType+2 012 \fRscores of \fLVtDirType+1\fR blocks\fL + \fR\&...\fL + VtRootType 020 VtRoot\fR structure\fL +.fi +.PP +The octal numbers listed are the type numbers used +by the commands below. +(For historical reasons, the type numbers used on +disk and on the wire are different from the above. +They do not distinguish +.BI VtDataType+ n +blocks from +.BI VtDirType+ n +blocks.) +.SS "Zero Truncation +To avoid storing the same short data blocks padded with +differing numbers of zeros, Venti clients working with fixed-size +blocks conventionally +`zero truncate' the blocks before writing them to the server. +For example, if a 1024-byte data block contains the +11-byte string +.RB ` hello " " world ' +followed by 1013 zero bytes, +a client would store only the 11-byte block. +When the client later read the block from the server, +it would append zero bytes to the end as necessary to +reach the expected size. +.PP +When truncating pointer blocks +.RB ( VtDataType+ \fIn +and +.BI VtDirType+ n +blocks), +trailing zero scores are removed +instead of trailing zero bytes. +.PP +Because of the truncation convention, +any file consisting entirely of zero bytes, +no matter what its length, will be represented by the zero score: +the data blocks contain all zeros and are thus truncated +to the empty block, and the pointer blocks contain all zero scores +and are thus also truncated to the empty block, +and so on up the hash tree. +.SS Network Protocol +A Venti session begins when a +.I client +connects to the network address served by a Venti +.IR server ; +the conventional address is +.BI tcp! server !venti +(the +.B venti +port is 17034). +Both client and server begin by sending a version +string of the form +.BI venti- versions - comment \en \fR. +The +.I versions +field is a list of acceptable versions separated by +colons. +The protocol described here is version +.BR 02 . +The client is responsible for choosing a common +version and sending it in the +.B VtThello +message, described below. +.PP +After the initial version exchange, the client transmits +.I requests +.RI ( T-messages ) +to the server, which subsequently returns +.I replies +.RI ( R-messages ) +to the client. +The combined act 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-byte fields hold unsigned integers represented +in big-endian order (most significant byte first). +Data items of variable lengths are represented by +a one-byte field specifying a count, +.IR n , +followed by +.I n +bytes of data. +Text strings are represented similarly, +using a two-byte count with +the text itself stored as a UTF-encoded sequence +of Unicode characters (see +.IR utf (6)). +Text strings are not +.SM NUL\c +-terminated: +.I n +counts the bytes of UTF data, which include no final +zero byte. +The +.SM NUL +character is illegal in text strings in the Venti protocol. +The maximum string length in Venti is 1024 bytes. +.PP +Each Venti message begins with a two-byte size field +specifying the length in bytes of the message, +not including the length field itself. +The next byte is the message type, one of the constants +in the enumeration in the include file +.BR <venti.h> . +The next byte is an identifying +.IR tag , +used to match responses to requests. +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 [1] +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. +The notation +.IR parameter [] +where +.I parameter +is the last field in the message represents a +variable-length field that comprises all remaining +bytes in the message. +.PP +All Venti RPC messages are prefixed with a field +.IR size [2] +giving the length of the message that follows +(not including the +.I size +field itself). +The message bodies are: +.ta \w'\fLVtTgoodbye 'u +.IP +.ne 2v +.B VtThello +.IR tag [1] +.IR version [ s ] +.IR uid [ s ] +.IR strength [1] +.IR crypto [ n ] +.IR codec [ n ] +.br +.B VtRhello +.IR tag [1] +.IR sid [ s ] +.IR rcrypto [1] +.IR rcodec [1] +.IP +.ne 2v +.B VtTping +.IR tag [1] +.br +.B VtRping +.IR tag [1] +.IP +.ne 2v +.B VtTread +.IR tag [1] +.IR score [20] +.IR type [1] +.IR pad [1] +.IR count [2] +.br +.B VtRead +.IR tag [1] +.IR data [] +.IP +.ne 2v +.B VtTwrite +.IR tag [1] +.IR type [1] +.IR pad [3] +.IR data [] +.br +.B VtRwrite +.IR tag [1] +.IR score [20] +.IP +.ne 2v +.B VtTsync +.IR tag [1] +.br +.B VtRsync +.IR tag [1] +.IP +.ne 2v +.B VtRerror +.IR tag [1] +.IR error [ s ] +.IP +.ne 2v +.B VtTgoodbye +.IR tag [1] +.PP +Each T-message has a one-byte +.I tag +field, chosen and used by the client to identify the message. +The server will echo the request's +.I tag +field in the reply. +Clients should arrange that no two outstanding +messages have the same tag field so that responses +can be distinguished. +.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 error +field contains a string describing the reason for failure. +.PP +Venti connections must begin with a +.B hello +transaction. +The +.B VtThello +message contains the protocol +.I version +that the client has chosen to use. +The fields +.IR strength , +.IR crypto , +and +.IR codec +could be used to add authentication, encryption, +and compression to the Venti session +but are currently ignored. +The +.IR rcrypto , +and +.I rcodec +fields in the +.B VtRhello +response are similarly ignored. +The +.IR uid +and +.IR sid +fields are intended to be the identity +of the client and server but, given the lack of +authentication, should be treated only as advisory. +The initial +.B hello +should be the only +.B hello +transaction during the session. +.PP +The +.B ping +message has no effect and +is used mainly for debugging. +Servers should respond immediately to pings. +.PP +The +.B read +message requests a block with the given +.I score +and +.IR type . +Use +.I vttodisktype +and +.I vtfromdisktype +(see +.IR venti (2)) +to convert a block type enumeration value +.RB ( VtDataType , +etc.) +to the +.I type +used on disk and in the protocol. +The +.I count +field specifies the maximum expected size +of the block. +The +.I data +in the reply is the block's contents. +.PP +The +.B write +message writes a new block of the given +.I type +with contents +.I data +to the server. +The response includes the +.I score +to use to read the block, +which should be the SHA1 hash of +.IR data . +.PP +The Venti server may buffer written blocks in memory, +waiting until after responding to the +.B write +message before writing them to +permanent storage. +The server will delay the response to a +.B sync +message until after all blocks in earlier +.B write +messages have been written to permanent storage. +.PP +The +.B goodbye +message ends a session. There is no +.BR VtRgoodbye : +upon receiving the +.BR VtTgoodbye +message, the server terminates up the connection. +.SH SEE ALSO +.IR venti (1), +.IR venti (2), +.IR venti (8) +.br +Sean Quinlan and Sean Dorward, +``Venti: a new approach to archival storage'', +.I "Usenix Conference on File and Storage Technologies" , +2002. diff --git a/sys/man/6/venti.conf b/sys/man/6/venti.conf new file mode 100755 index 000000000..7d5cdd3f9 --- /dev/null +++ b/sys/man/6/venti.conf @@ -0,0 +1,88 @@ +.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 +.I fmtarenas +or +.I fmtisect +(see +.IR venti-fmt (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 . +.TP +.BI isect " file +.I File +contains an index section, formatted using +.IR fmtisect . +.PP +After formatting a venti system using +.IR fmtindex , +the order of arenas and index sections should not be changed. +Additional arenas can be appended to the configuration. +.PP +The configuration file optionally holds configuration parameters +for the venti server itself. +These are: +.TP +.BI mem " cachesize +.TP +.BI bcmem " blockcachesize +.TP +.BI icmem " indexcachesize +.TP +.BI addr " ventiaddress +.TP +.BI httpaddr " httpaddress +.TP +.B queuewrites +.PD +See +.IR venti (8) +for descriptions of these variables. +.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 fs (3), +.IR venti (8), +.IR venti-fmt (8) diff --git a/sys/man/6/vgadb b/sys/man/6/vgadb new file mode 100755 index 000000000..a63357680 --- /dev/null +++ b/sys/man/6/vgadb @@ -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/sys/man/7/0intro b/sys/man/7/0intro new file mode 100755 index 000000000..754feac39 --- /dev/null +++ b/sys/man/7/0intro @@ -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/sys/man/7/INDEX b/sys/man/7/INDEX new file mode 100755 index 000000000..5433af637 --- /dev/null +++ b/sys/man/7/INDEX @@ -0,0 +1,9 @@ +0intro 0intro +intro 0intro +astro astro +dict dict +juke juke +map map +mapdemo map +playlistfs playlistfs +scat scat diff --git a/sys/man/7/INDEX.html b/sys/man/7/INDEX.html new file mode 100755 index 000000000..2b2d0399a --- /dev/null +++ b/sys/man/7/INDEX.html @@ -0,0 +1,37 @@ +<HEAD> +<TITLE>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 +- music jukebox +
juke + +
map +- draw maps on various projections +
map, mapdemo + +
playlistfs +- playlist file system +
playlistfs + +
scat +- sky catalogue and Digitized Sky Survey +
scat + +
diff --git a/sys/man/7/astro b/sys/man/7/astro new file mode 100755 index 000000000..9d19e81bc --- /dev/null +++ b/sys/man/7/astro @@ -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/sys/man/7/dict b/sys/man/7/dict new file mode 100755 index 000000000..5fc47634f --- /dev/null +++ b/sys/man/7/dict @@ -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/sys/man/7/juke b/sys/man/7/juke new file mode 100755 index 000000000..229c75a2a --- /dev/null +++ b/sys/man/7/juke @@ -0,0 +1,369 @@ +.TH JUKE 7 +.SH NAME +juke \- music jukebox +.SH SYNOPSIS +.B juke +[ +.B \-t +] +[ +.B \-w +] +[ +.B \-h +.I srvhost +] +[ +.B \-s +.I srvname +] +.ift .sp 0.5 +.ifn .sp +.B games/jukebox +[ +.B \-t +] +[ +.B \-w +] +.ift .sp 0.5 +.ifn .sp +.B games/jukefs +[ +.B \-m +.I mountpoint +] +[ +.B \-s +.I srvname +] +[ +.I mapfile +] +.SH DESCRIPTION +.I Jukebox +controls a playlist server +(see +.IR playlistfs (7)) +through a graphical user interface. It connects to a music database server which reads a set of +.I map +files that describe recordings and their location. Currently, there is +one set of maps, mostly for classical music, with some jazz and other stuff +thrown in. These are served by +.BR jukefs , +which presents a file system conventionally mounted at +.BR /mnt/juke . +The playlist, explained below, is managed by a file system implemented by +.IR playlistfs (7) +and normally mounted on +.BR /mnt . +.PP +.I Jukebox +is most easily started through the +.I juke +shell script. +.PP +.I Jukebox +has four windows, which can be selected by clicking the appropriate tab +at the top of the window. +.PP +Above the tab are nine buttons and a volume slider. The +.ift buttons, shown below, +.ifn buttons +are named, from left to right, +.IR Exit , +.IR Pause , +.IR Play , +.IR Halt , +.IR Back , +.IR Forward , +.IR Root , +.IR Delete , +and +.IR Help . +The buttons are +.I active +when they are displayed in dark green (or red). When they are pale blue +they are +.IR inactive . +The Exit button is always active; it exits the program (but leaves the playlist and music database +servers running). +.PP +The +.I browse +window is for browsing through the music and selecting music to play. +Browsing down in the music hierarchy is done by clicking button one on +an item. Clicking button three goes back up. +Clicking button two recursively adds all files below the selected item to +the +.IR "play list" . +.PP +The selected music is displayed in the +.I playlist +window. +The track currently playing is shown in the +.I playing +window. +.PP +The +.I Root +button browses back to the root. +.PP +The +.I Delete +button empties the playlist. +.PP +The +.I Help +displays a minimal on-line manual. +.PP +.I Play +starts playing at the beginning of the play list, or at the selected track in +the play list. +.PP +During play, +.IR Pause , +.IR Stop , +.IR Back , +and +.I Forward +are active. +.I Back +and +.I Forward +go back or forward a track at a time. The other buttons do the obvious thing. +.PP +The +.B \-t +flag chooses a tiny font, useful for handhelds. +.PP +The +.B \-w +flag creates the jukebox in a new window. Normally, the jukebox takes over +the window in which it is invoked. +.PP +The +.B \-s +flag specifies the name under which the file descriptors of the playlist and databse servers are posted +in /srv. This allows two or more play list servers to exist on one platform, e.g., when +there are several audio devices. The default value of the flag is +.B $\f2user\fP +for a playlist server at +.B /srv/playlistfs.$\f2user\fP +and a database server at +.BR /srv/jukefs.$\f2user\fP . +.sp +.LP +.B Jukefs +reads a set of +.I maps +describing the music data, builds an in-memory database, and provides +lookup service to +.IR jukebox . +The default map is +.BR /sys/lib/music/map . +It consists of a hierarchical set of +.IR objects . +Each object has a type, a value, zero or more attribute-value +pairs and zero or more subobjects. An object consists of the +type, followed by its contents between curly brackets. +Attribute value pairs consist +of a single line containing an attribute name, an equals sign, and +a value. +The value of an object is any text not containing curly brackets or equals +signs. Here is an example: +.EX +.ps -2 +.vs -2p +.sp +category { + composer = mahler + + Gustav Mahler + (1860 — 1911) + + work { + path {classic/mahler} + class = symphonic + orchestra = rfo + conductor = Waart,~Edo~de + + Symphony Nº 5 in c♯ (RFO, Vienna) + performance{ + Radio Filharmonisch Orkest Holland + Edo de Waart, conductor + + recorded: Musikverein, Vienna, May 6, 1996 + } + command {number} + track { + Trauermarsch (In gemessenem Schritt. Streng. Wie ein Kondukt) + time {13:55} + file {034.pac} + } + track { + Stürmisch bewegt, mit größter Vehemenz + time {15:34} + file {035.pac} + } + track { + Scherzo (Kräftig, nicht zu schnell) + time {18:54} + file {036.pac} + } + track { + Adagietto (Sehr Langsam) + time {10:01} + file {037.pac} + } + track { + Rondo–Finale (Allegro) + time {15:44} + file {038.pac} + } + } +} +.EE +.LP +This example shows a +.I category +object for the composer Gustav Mahler (the value consists of the two +lines `Gustav Mahler' and `(1860 — 1911)') with one subobject, a +.I work +object whose value is `Symphony Nº 5 in c♯ (RFO, Vienna)'. The work object +contains six subobjects: one +.I performance +object and five +.I track +objects. +.PP +.I Category +objects must contain exactly one attribute-value pair. The attribute +names a subobject of the root under which this category object will +be placed. Gustav Mahler, thus, will be placed in +Root→composer. +.IR Work , +.IR Recording , +.IR Part , +and +.IR Track , +objects all describe named containers for subunits. +A +.IR Lyrics , +.IR Performance , +or +.IR Soloists +object adds information to a +.IR Work , +.IR Recording , +.IR Part , +or +.IR Track , +object. It should only contain text. +The same is true for a +.I Time +object; however, it should only be used adjacent to +.I File +objects and it should contain the running time of that file (this +is for future use). +.PP +A +.I File +object specifies a file to be played. When the +.I Select +button is pressed, all file objects contained hierarchically in the +selected object are added to the playlist. +.PP +There are a number of pseudo objects: +.I Command +may contain either +.I sort +or +.IR number . +The +.I sort +command sorts the subobjects of the object it appears in by +.I key +or textual content. +The +.I number +commands prepends numbers to the texts of its subobjects +(e.g., for the parts in a symphony) +.PP +An +.I Include +object is replaced by the contents of the named file. +.PP +A +.I Key +object specifies a key for sorting subobjects. +.PP +Finally, a +.I Path +object specifies a path to be prepended to the files named in +hierarchically contained +.I File +objects. +.PP +The attribute-value value pairs arrange for entries to be made of the +current object in a +.I Category +object named by the attribute directly under the root. +.sp +.LP +The interface to the browsing database is through a file system +implemented by +.BR jukefs . +The file system synthesises a directory per object. Each directory contains a set of files +describing the object's attributes: +.TP +.B children +contains a new-line separated list of subobject names. For each name, +.I x +the directory +.BI /mnt/juke/ x +describes the subobject. +.TP +.B digest +contains a one-line summary of the object +.TP +.B files +is a new-line separated list of file objects contained in this object. +Each line consists of object name and file name. +.TP +.B fulltext +is the fulltextual value of the object. +.TP +.B key +contains the key by which objects are sorted +.TP +.B miniparentage +is a one-line summary of the objects and the path leading to it from the root. +This is the line displayed in the playlist and bottom browse windows of +.BR games/jukebox . +.TP +.B parent +is the object reference to the parent of this object. +.TP +.B parentage +is a full description of the path leading to this object and the object itself. +This is the string displayed in the top of the Browse and Playing windows +of +.BR games/jukebox . +.TP +.B text +is the text field of the object. +.TP +.B type +is the type of the object +.LP +.SH FILES +.BR /sys/lib/music/map : +Default map file +.BR /mnt/juke : +Default mount point for the music database. +.SH SOURCE +.B /sys/src/games/music +.SH SEE ALSO +.IR playlistfs (7), +.IR audio (7) diff --git a/sys/man/7/map b/sys/man/7/map new file mode 100755 index 000000000..2bed90e6e --- /dev/null +++ b/sys/man/7/map @@ -0,0 +1,675 @@ +.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) +.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/sys/man/7/playlistfs b/sys/man/7/playlistfs new file mode 100755 index 000000000..e3bd2e4a8 --- /dev/null +++ b/sys/man/7/playlistfs @@ -0,0 +1,156 @@ +.TH PLAYLISTFS 7 +.SH NAME +playlistfs \- playlist file system +.SH SYNOPSIS +.B games/playlistfs +[ +.B \-s +.I postname +] +[ +.B \-m +.I mountpoint +] +[ +.B \-a +] +.SH DESCRIPTION +.B Playlistfs +implements an audio player which plays files from a built-in play list. +The player is controlled through three files, usually mounted at +.BR /mnt . +The files are +.B /playctl +for controlling play: start, stop, pause, skip, etc.; +.B /playvol +for controlling the playout volume; and +.B /playlist +for controlling the play list itself. +.PP +All three files can be written to control the player and read to obtain player +status information. +.PP +When read, the files report the current status of the player, volume and playlist, +respectively. End of file is indicated by a read that returns zero bytes, as usual. +However, in all three files, subsequent read operations will block until the status +of the file changes and then report the changed state. When the changed state has +been read, another end-of-file indication is given, after which another read +can be issued to wait for state changes. +.PP +The +.B /playctl +file returns strings of the form `\f2cmd n\fP' +where +.I cmd +is one of +.IR stop , +.IR pause , +or +.I play +and +.I n +is an index (or offset) into the playlist; indices start at zero. +.PP +The commands that can be written to +.B /playctl +take the same form; however, the index is an optional argument. If the +index is omitted, the current value is used. The commands are +.IR play , +.IR stop , +.IR pause , +.IR resume , +and +.IR skip . +.I Play +starts playing at the index. +.I Stop +stops playing. If an index is given, the current index is set to it and +can be used in future commands. +.I Pause +and +.I Resume +interrupt and continue play, respectively. The index argument is always ignored and +the whole command is ignored if the state in which they occur does not +make sense. +.I Skip +adds the argument to the current index (adds one if no argument is given) +and starts play at that index, stopping current play, if necessary. +.PP +Reads of +.B /playvol +return strings of the form +.BR "`volume \f2n\fP'" , +where +.I n +is a number or, if there is more than one channel, a quoted set of numbers, between 0 +(minimum) and 100 (maximum). +Writes to +.B /playvol +take the same form. +.PP +The +.B /playlist +file is an append-only file which accepts lines with one or two fields +per line (parsed using +.BR tokenize ). +The first, compulsory, field is a file name, the optional second argument +may contain a reference to, or a description of, the item, for instance in a graphical +user interface. +.B /playlist +is append-only, individual lines cannot be removed. However, the playlist +can be cleared by opening the file with the +.B OTRUNC +flag. A process that has +.B /playlist +open while the file is truncated will receive an error on the next read with +.B errstr +set to +.IR "reading past eof" . +When this error occurs, clients can seek to the beginning of the file and reread its contents. +.PP +After starting up, +.B Playlistfs +puts itself in the background. When called with the +.B \-s +flag, it posts a mountable file descriptor in +.BR /srv/playlist.\f2postname\fP . +The +.B \-m +flag can be used to specify a mount point other than +.BR /mnt . +.PP +The files to be played are recognized by one of four extensions, and an appropriate +player is then selected to play them. Files without a recognized extension are played by the +.I pac +player: +.TP +\&.mp3 +/bin/games/mp3dec +.TP +\&.pac +/bin/games/pac4dec +.TP +\&.pcm +/bin/cp +.TP +\&.ogg +/bin/games/vorbisdec +.SH FILES +.BR /srv/playlistfs.\f2user\fP : +default +.B playlistfs +mountable file descriptor used by juke(7). +.br +.BR /mnt/playctl : +Control file +.br +.BR /mnt/playlist : +Playlist file +.br +.BR /mnt/playvol : +Volume control file +.SH SOURCE +.B /sys/src/games/music/playlistfs +.SH SEE ALSO +.IR juke (7), +.IR audio (7) diff --git a/sys/man/7/scat b/sys/man/7/scat new file mode 100755 index 000000000..d9bf8db80 --- /dev/null +++ b/sys/man/7/scat @@ -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/sys/man/8/0intro b/sys/man/8/0intro new file mode 100755 index 000000000..f96a521bf --- /dev/null +++ b/sys/man/8/0intro @@ -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/sys/man/8/6in4 b/sys/man/8/6in4 new file mode 100755 index 000000000..553116d05 --- /dev/null +++ b/sys/man/8/6in4 @@ -0,0 +1,140 @@ +.TH 6IN4 8 +.SH NAME +6in4 - configure and run automatic or manual 6to4 tunnel of IPv6 through IPv4 +.SH SYNOPSIS +.B ip/6in4 +[ +.B -ag +] [ +.B -x +.I netmtpt +] [ +.IB local6[ / mask] +[ +.I remote4 +[ +.I remote6 +] ] ] +.SH DESCRIPTION +.I 6in4 +sets up and maintains a tunnel of IPv6 traffic through an IPv4 connection. +.PP +.I Local6 +and +.I mask +define the IPv6 address and subnet of the near end of the tunnel +.RI ( mask +defaults to +.L /128 +for a single-host +tunnel). +If +.I local6 +is missing or +.LR - , +it defaults to +.IP +.BI 2002: aabb : ccdd ::1/48 +.PP +where +.IR aa , +.IR bb , +.I cc +and +.I dd +are the hexadecimal equivalents of the bytes +.IB a . b . c .\c +.I d +in this host's primary IPv4 address. +.PP +.I Remote4 +is the IPv4 address of the far end of the tunnel +(must be given explicitly for a configured tunnel, or +defaults to the anycast address 192.88.99.1 for +.IR 6to4 ). +.PP +.I Remote6 +is the IPv6 address of the far end of the tunnel +(used as the point-to-point destination for routing, and +defaults to a link-local address constructed from +.IR remote4 ). +.PP +.I 6in4 +forks a pair of background processes to copy packets to and from +the tunnel. +.PP +Options are: +.TF -x +.PD 0 +.TP +.B -a +permit any remote IPv4 address as the far end of a tunnel. +This is likely to be useful for the server side of a tunnel. +.TP +.B -g +use the tunnel as the default route for global IPv6 addresses +.TP +.B -x +use the network mounted at +.I netmtpt +instead of +.LR /net . +.PD +.SH EXAMPLES +If your primary IPv4 address is public, +you can start a +.I 6to4 +tunnel simply with +.IP +.EX +ip/6in4 -g +.EE +.PP +Similarly, you can start a server for +.I 6to4 +tunnels with +.IP +.EX +ip/6in4 -ag +.EE +.PP +If you use a tunnel broker at address +.LR 5.6.7.8 , +configured to give you a +.L /64 +subnet with address +.LR 2001:1122:3344:5566:: , +you can start the tunnel with +.IP +.EX +ip/6in4 -g 2001:1122:3344:5566::/64 5.6.7.8 +.EE +.SH FILES +.TF /net/ipmux +.PD 0 +.TP +.B /net/ipmux +access to IPv6-in-IPv4 packets +.TP +.B /net/ipifc +packet interface to IPv6 network +.SH SEE ALSO +.IR bridge (3), +.I ipmux +in +.IR ip (3), +.I linklocal +in +.IR ipconfig (8) +.br +.B /lib/rfc/rfc3056 +.br +.B /lib/rfc/rfc3068 +.SH BUGS +Needs a kernel with an +.I ipmux +driver. +.PP +The tunnel client filters addresses fairly conservatively in both directions. +However it's not watertight, +and may be flakey in other ways so don't put too much trust in it. diff --git a/sys/man/8/9load b/sys/man/8/9load new file mode 100755 index 000000000..a67b18ff4 --- /dev/null +++ b/sys/man/8/9load @@ -0,0 +1,486 @@ +.TH 9LOAD 8 +.SH NAME +9load, 9pxeload, 9loadusb, 9loadask, ld \- PC bootstrap program +.SH SYNOPSIS +.I "(Under MS-DOS) +.br +.RI [ drive\f(CW:\fP ][ path ] 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. +.I 9pxeload +is a version of +.I 9load +that can be booted using the PXE download (BOOTP/DHCP followed by TFTP) +found in some ethernet card BIOSes. +.I 9loadusb +is a version that will use only the BIOS's device drivers, +and thus can load from USB devices. +In contrast, +.I 9load +will +.I not +use BIOS device drivers. +.I 9loadask +is a version that asks on the console (too early for serial ports, alas) +if you want to use BIOS drivers to boot. +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 +.BR 0x7C00 . +In the case of a floppy, this is the PBS. +In the case of a hard disk, it is 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 virtual address +.B 0x80010000 +(64K) and +loads the +.I bootfile +at the entry address specified by the header, +usually virtual +.BR 0xF0100020 . +After loading, control is passed to the entry location. +.PP +In summary, +Plan 9 can be booted on a PC three different ways: +either by booting MS-DOS and using +.I ld +to start +.I 9load +in the appropriate directory, +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)), +or by using a PXE-capable BIOS to boot +.I 9pxeload +directly over the ethernet. +.SS Bootfile +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 +(see +.B "Kernel loading" +below). +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 +.PD +.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. +.TP +.B bios0 +(Not in +.IR 9pxeload .) +.I 9load +loads from a FAT file system on +the first LBA device +in the BIOS's list of devices to try to boot from, +using the BIOS INT 13 calls also used by +.IR pbslba . +It does not understand any form of partition table; +see the EXAMPLES in +.IR prep (8) +for how to format such a device. +This is mostly useful for booting from USB devices so far. +.TP +.B sdB0 +(Not in +.IR 9pxeload .) +A special case of +.BI sd Cn +that uses +.B bios0 +to read from a FAT file system. +Partitions are understood. +.SS Kernel loading +When +.I 9load +starts running at physical address +.BR 0x10000 , +it switches to 32-bit mode. +It then double maps the first 16Mb of physical memory to +virtual addresses +.B 0 +and +.BR 0x80000000 . +Physical memory from +.B 0x300000 +upwards is used as data space. +.PP +.I 9pxeload +differs slightly in operation from +.IR 9load . +It is initially loaded by the PXE BIOS at physical address +.BR 0x7C00 . +Only devices which can be automatically configured, +e.g. most PCI ethernet adapters, +will be recognised. +If the file +.BI /cfg/pxe/ XXXXXXXXXXXX +can be located via a DHCP server, +where +.I XXXXXXXXXXXX +is the MAC address of a recognised ethernet adapter, +the contents are obtained and used as a +.IR plan9.ini . +.PP +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 +.B 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. +.SS Other facilities and caveats +.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 fossil (4) +or +.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\f(CW:\fP ][ path ]\c +.B 9load +.br +.RI [ drive\f(CW:\fP ][ path ]\c +.B ld +.br +.IB "FAT-filesystem" :\eplan9\eplan9.ini +.br +.IB "FAT-filesystem" :\eplan9.ini +.TF /cfg/pxe +.TP +.BI /cfg/pxe +directory of +.I plan9.ini +files on your TFTP server +.SH SOURCE +.B /sys/src/boot/pc +.SH "SEE ALSO" +.IR booting (8), +.IR dhcpd (8), +.IR plan9.ini (8), +.IR prep (8) +.SH BUGS +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 . +.PP +BIOS bugs force some limitions on reading via the BIOS. +.B bios0 +and +.B sdB0 +only work on the first LBA device in the BIOS's list of boot devices. diff --git a/sys/man/8/9pcon b/sys/man/8/9pcon new file mode 100755 index 000000000..cb6249c62 --- /dev/null +++ b/sys/man/8/9pcon @@ -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 fid 101. +.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/sys/man/8/INDEX b/sys/man/8/INDEX new file mode 100755 index 000000000..89d5c4b76 --- /dev/null +++ b/sys/man/8/INDEX @@ -0,0 +1,215 @@ +0intro 0intro +intro 0intro +6in4 6in4 +9load 9load +9pxeload 9load +ld 9load +9pcon 9pcon +aan aan +aliasmail aliasmail +apm apm +aquarela aquarela +as auth +auth auth +authsrv auth +changeuser auth +convkeys auth +convkeys2 auth +debug auth +disable auth +enable auth +guard.srv auth +login auth +newns auth +none auth +printnetkey auth +status auth +wrkey auth +backup backup +dumparenas backup +restore backup +tobackup backup +boot boot +booting booting +cec cec +cpurc cpurc +cpurc.local cpurc +termrc cpurc +termrc.local cpurc +cron cron +dhcpd dhcpd +dhcpleases dhcpd +rarpd dhcpd +tftpd dhcpd +diskparts diskparts +dmaon diskparts +disksim disksim +drawterm drawterm +fossilcons fossilcons +exsort fs +fs fs +fsconfig fsconfig +fshalt fshalt +reboot fshalt +getflags getflags +usage getflags +gpsevermore gpsfs +gpsfs gpsfs +histogram histogram +httpd httpd +imagemap httpd +man2html httpd +save httpd +webls httpd +init init +ipconfig ipconfig +ipv6on ipconfig +linklocal ipconfig +rip ipconfig +ftpd ipserv +ipserv ipserv +rexexec ipserv +rlogind ipserv +telnetd ipserv +kfscmd kfscmd +ksync kfscmd +listen listen +listen1 listen +tcp110 listen +tcp113 listen +tcp143 listen +tcp17007 listen +tcp17008 listen +tcp17009 listen +tcp17010 listen +tcp17013 listen +tcp1723 listen +tcp19 listen +tcp21 listen +tcp22 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 +tcp995 listen +lp lp +dump9660 mk9660 +mk9660 mk9660 +mkflashfs mkflashfs +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 +dnstcp ndb +inform ndb +ipquery ndb +mkdb ndb +mkhash ndb +mkhosts ndb +ndb ndb +query ndb +newuser newuser +nfsserver nfsserver +pcnfsd nfsserver +portmapper nfsserver +partfs partfs +pci pci +pcmcia pcmcia +pem pem +pemdecode pem +pemencode pem +gping ping +hogports ping +ping ping +traceroute ping +plan9.ini plan9.ini +imap4d pop3 +pop3 pop3 +ppp ppp +pppoe ppp +pptp ppp +pptpd ppp +fdisk prep +format prep +mbr prep +prep prep +qer qer +runq qer +reboot reboot +applychanges replica +applylog replica +compactdb replica +replica replica +updatedb replica +asn12rsa rsa +rsa rsa +rsa2pub rsa +rsa2ssh rsa +rsa2x509 rsa +rsafill rsa +rsagen rsa +scanmail scanmail +testscan scanmail +screenlock screenlock +scuzz scuzz +secstore secstore +secstored secstore +secuser secstore +securenet securenet +send send +smtp smtp +smtpd smtp +snoopy snoopy +stats stats +statusbar statusbar +stub stub +swap swap +timesync timesync +tlsclient tlssrv +tlsclienttunnel tlssrv +tlssrv tlssrv +tlssrvtunnel tlssrv +trampoline trampoline +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 +rdarena venti-backup +venti-backup venti-backup +wrarena venti-backup +buildindex venti-fmt +checkarenas venti-fmt +checkindex venti-fmt +conf venti-fmt +fmtarenas venti-fmt +fmtbloom venti-fmt +fmtindex venti-fmt +fmtisect venti-fmt +syncindex venti-fmt +venti-fmt venti-fmt +vga vga +wol wol diff --git a/sys/man/8/INDEX.html b/sys/man/8/INDEX.html new file mode 100755 index 000000000..2f1b713a4 --- /dev/null +++ b/sys/man/8/INDEX.html @@ -0,0 +1,321 @@ + +plan 9 man section 8 + + +[manual index] +

Plan 9 from Bell Labs - Section 8 - System Administration

+
+
+
0intro +- introduction to system administration +
intro + +
6in4 +- configure and run automatic or manual 6to4 tunnel of IPv6 through IPv4 +
6in4 + +
9load +- PC bootstrap program +
9load, 9pxeload, ld + +
9pcon +- 9P to text translator +
9pcon + +
aan +- always available network +
aan + +
aliasmail +- expand system wide mail aliases +
aliasmail + +
apm +- Advanced Power Management 1.2 BIOS interface +
apm + +
aquarela +- CIFS server +
aquarela + +
auth +- maintain or query authentication databases +
changeuser, convkeys, convkeys2, printnetkey, status, enable, disable, authsrv, guard.srv, debug, wrkey, login, newns, none, as + +
backup +- backup venti arenas to blu-ray discs or restore from them +
backup, tobackup, dumparenas, restore + +
boot +- connect to the root file server +
boot + +
booting +- bootstrapping procedures +
booting + +
cec +- Coraid Ethernet Console +
cec + +
cpurc +- boot scripts +
cpurc, cpurc.local, termrc, termrc.local + +
cron +- clock daemon +
cron + +
dhcpd +- Internet booting +
dhcpd, dhcpleases, rarpd, tftpd + +
diskparts +- prepare disks for use +
diskparts, dmaon + +
disksim +- disk simulator +
disksim + +
drawterm +- connect to Plan 9 CPU servers from other operating systems +
drawterm + +
fossilcons +- fossil console commands +
fossilcons + +
fs +- file server maintenance +
fs, exsort + +
fsconfig +- configuring a file server +
fsconfig + +
fshalt +- halt any local file systems and optionally reboot the system +
fshalt, reboot + +
getflags +- command-line parsing for shell scripts +
getflags, usage + +
gpsfs +- GPS time and position service +
gpsfs, gpsevermore + +
histogram +- draw a histogram +
histogram + +
httpd +- HTTP server +
httpd, save, imagemap, man2html, webls + +
init +- initialize machine upon booting +
init + +
ipconfig +- Internet configuration and routing +
ipconfig, rip, linklocal, ipv6on + +
ipserv +- Internet remote access daemons +
telnetd, rlogind, rexexec, ftpd + +
kfscmd +- kfs administration +
kfscmd, ksync + +
listen +- listen for calls on a network device +
listen, listen1, tcp7, tcp9, tcp19, tcp21, tcp22, tcp23, tcp25, tcp53, tcp110, tcp113, tcp143, tcp513, tcp515, tcp564, tcp565, tcp566, tcp567, tcp993, tcp995, tcp1723, tcp17007, tcp17008, tcp17009, tcp17010, tcp17013 + +
lp +- PostScript preprocessors +
lp + +
mk9660 +- create an ISO-9660 CD image +
dump9660, mk9660 + +
mkflashfs +- make a journalling file system for flash memory +
mkflashfs + +
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, ipquery, mkhash, mkdb, mkhosts, cs, csquery, dns, dnstcp, dnsquery, dnsdebug, inform + +
newuser +- adding a new user +
newuser + +
nfsserver +- NFS service +
nfsserver, portmapper, pcnfsd + +
partfs +- serve file, with partitions +
partfs + +
pci +- print PCI bus configuration +
pci + +
pcmcia +- identify a PCMCIA card +
pcmcia + +
pem +- encode files in Privacy Enhanced Mail (PEM) format +
pemdecode, pemencode + +
ping +- probe the Internet +
ping, gping, traceroute, hogports + +
plan9.ini +- configuration file for PCs +
plan9.ini + +
pop3 +- Internet mail servers +
pop3, imap4d + +
ppp +- point-to-point protocol +
ppp, pppoe, pptp, pptpd + +
prep +- prepare disks, floppies and flashes +
prep, fdisk, format, mbr + +
qer +- queue management for spooled files +
qer, runq + +
reboot +- reboot the system upon loss of remote file server connection +
reboot + +
replica +- simple client-server replica management +
applychanges, applylog, compactdb, updatedb + +
rsa +- generate and format rsa keys +
rsagen, rsafill, asn12rsa, rsa2pub, rsa2ssh, rsa2x509 + +
scanmail +- spam filters +
scanmail, testscan + +
screenlock +- disable access to a terminal +
screenlock + +
scuzz +- SCSI target control +
scuzz + +
secstore +- secstore commands +
secstored, secuser + +
securenet +- Digital Pathways SecureNet Key remote authentication box +
securenet + +
send +- mail routing and delivery +
send + +
smtp +- mail transport +
smtp, smtpd + +
snoopy +- spy on network packets +
snoopy + +
stats +- display graphs of system activity +
stats + +
statusbar +- display a bar graph status window +
statusbar + +
stub +- provide mount point stubs +
stub + +
swap +- establish a swap file +
swap + +
timesync +- synchronize the system clock to a time source +
timesync + +
tlssrv +- TLS server and client +
tlssrv, tlsclient, tlssrvtunnel, tlsclienttunnel + +
trampoline +- forward incoming calls to another address +
trampoline + +
udpecho +- echo UDP packets +
udpecho + +
update +- administration for local file systems +
bootfloppy, bootplan9, bootwin9x, bootwinnt, personalize, setup.9fat, setup.disk, setup.kfs, update + +
venti +- archival storage server +
venti + +
venti-backup +- copy arenas between venti servers +
rdarena, wrarena + +
venti-fmt +- prepare and maintain a venti server +
buildindex, checkarenas, checkindex, conf, fmtarenas, fmtbloom, fmtindex, fmtisect, syncindex + +
vga +- configure a VGA card +
vga + +
wol +- send wake-on-lan Ethernet packet +
wol + +
diff --git a/sys/man/8/aan b/sys/man/8/aan new file mode 100755 index 000000000..43df4cfd1 --- /dev/null +++ b/sys/man/8/aan @@ -0,0 +1,99 @@ +.TH AAN 8 +.SH NAME +aan \- always available network +.SH SYNOPSIS +.B aan +.B -c +[ +.B -d +] +[ +.B -m maxto +] +.I dialstring +.br +.B aan +[ +.B -d +] +[ +.B -m maxto +] +.I netdir +.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 +.I 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 for connections in the +already-announced network directory +.IR netdir . +.PP +.I Aan +is usually run automatically through the +.B -p +option of +.IR import (4). +.SH EXAMPLE +Assume the server part of +.I aan +is encapsulated in +.I 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 astro6 / /mnt/term +.EE +.SH FILES +.TF /sys/log/aan +.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/sys/man/8/aliasmail b/sys/man/8/aliasmail new file mode 100755 index 000000000..fced57df2 --- /dev/null +++ b/sys/man/8/aliasmail @@ -0,0 +1,61 @@ +.TH ALIASMAIL 8 +.SH NAME +aliasmail \- expand system wide mail aliases +.SH SYNOPSIS +.B upas/aliasmail +.I arg ... +.SH DESCRIPTION +.PP +.I Aliasmail +expands mail aliases, its arguments, according to alias files. +.I Aliasmail +is normally invoked by a rule in the +upas rewrite file, +.IR rewrite (6). +.PP +If a line of an alias file begins with +.BR #include , +the line is replaced by the contents of the file whose name follows. +Other lines, beginning with +.B # +are ignored as comment. +.PP +Otherwise, lines begin 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 +The alias files are searched in the order they are +listed, one per line, in +.BR /mail/lib/namefiles . +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. +.SH FILES +.TF /mail/lib/namefiles +.TP +.B /mail/lib/namefiles +names of system alias files +.SH SOURCE +.TP +.B /sys/src/cmd/upas/alias +.SH "SEE ALSO" +.IR faces (1), +.IR filter (1), +.IR mail (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR smtp (8), +.IR upasfs (4) + diff --git a/sys/man/8/apm b/sys/man/8/apm new file mode 100755 index 000000000..23fdd6686 --- /dev/null +++ b/sys/man/8/apm @@ -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/sys/man/8/aquarela b/sys/man/8/aquarela new file mode 100755 index 000000000..68e57082d --- /dev/null +++ b/sys/man/8/aquarela @@ -0,0 +1,225 @@ +.TH AQUARELA 8 +.SH NAME +aquarela \- CIFS server +.SH SYNOPSIS +.B aquarela +[ +.B -np +] [ +.B -d +.I debug +] [ +.B -u +.I N +] [ +.B -w +.I workgroup +] +.SH DESCRIPTION +.I Aquarela +provides +.SM CIFS +(once known as +.SM SMB\c +) +access to Plan 9 file servers. +It announces and subsequently listens on +.B tcp!*!445 +for connections to the file hierarchies called `shares' by +.SM CIFS\c . +Users are authenticated with their +.SM APOP +secret (see +.IR auth (8)). +Each session is managed by a process running as the authenticated user. +Two persistent processes handle listening, session setup, and housekeeping. +.PP +An +.I aquarela +.SM CIFS +share corresponds to a directory under +.BR /n . +A client request for a specific share, say, +.BR share , +causes +.I aquarela +to attempt a +.I 9fs +(in +.IR srv (4)) +connection to the file server +.BR share . +If connection succeeds, a file hierarchy rooted at +.B /n/share +is presented to the client. +The client request fails otherwise. +Requests for the protocol equivalent of +.B / +are satisfied with a directory containing only the default share, +.BR local . +.PP +The options are: +.TF "-u " +.TP +.B -n +Enable limited +.SM NETBIOS +service. +.I Aquarela +will register with the `master browser' for +.I workgroup +and listen on +.B tcp!*!139 +and +.B udp!*!13[7-9] +for +.SM NETBIOS +name resolution and session requests. +This works in tandem with a complete +.SM NETBIOS +master name server, like that provided by Unix +\fInmbd\fR(8). +.SM NETBIOS +is not required for +.SM CIFS +file service. +.TP +.BI -u " N +Send Unicode. +For +.IR N , +.B 1 +enables, +.B 0 +disables Unicoding of file names and metadata. +There is no code page support, so +.I aquarela +emits +.SM UTF +if +.I N +is +.BR 0 . +.TP +.BI -w " workgroup +Set +.I workgroup +(or `primary domain') of server. +Default +.BR PLAN9 . +.PD +.SH EXAMPLE +To start +.SM CIFS +service on system +.BR plan9 : +.IP +.EX +% aquarela -u 1 & +.EE +.PP +To then make the +.B dump +filesystem available as drive +.B Y: +on a Windows machine: +.IP +.EX +C:\\>net use Y: \\\\plan9.example.com\\dump +.EE +.SH FILES +.TF /sys/log/aquarela +.TP +.B /n/local +Default +.SM CIFS +share +.TP +.B /sys/log/aquarela +Log file +.PD +.SH SOURCE +.B /sys/src/cmd/aquarela +.SH SEE ALSO +.IR auth (8), +.IR srv (4), +.IR utf (6) +.SH DIAGNOSTICS +Log messages are appended to +.B /sys/log/aquarela +if it exists. The +.B -p +option prints them on standard output as well. +The +.B -d +option adds verbose output about +.I debug +to the log messages, where +.I debug +is one of: +.TF any-smb-name +.TP +.B allcmds +All +.SM CIFS +requests and responses. +.TP +.B tids +Connections and disconnections per-share. +.TP +.B sids +Creation and deletion of search ids. +.TP +.B fids +Creation and deletion of file ids. +.TP +.B rap2 +.SM RAP +calls. +.TP +.B find +Transaction2 find commands. +.TP +.B query +Transaction2 query commands. +.TP +.B sharedfiles +All files opened. +.TP +.B poolparanoia +Draconian error checking in memory allocator. +.TP +.B sessions +Connections and disconnections on server. +.TP +.B rep +Regular expression conversions. +.TP +.B locks +Locking activity. +.TP +.I any-smb-name +Debug only +.B SMB_ +requests or +.B transaction2 +sub-requests +(e.g., +.B SMB_COM_SESSION_SETUP_ANDX +or +.BR SMB_TRANS2_FIND_FIRST2 ) +matching symbolic name +.I any-smb-name. +.TP +.BI 0x nn +Debug only messages with hexadecimal id +.BI 0x nn. +.PD +.SH BUGS +The first connection attempt to a share sometimes fails erroneously - try again. +The share disk space reported by some clients is inaccurate. +Some clients can't rename directories. +Write attempts without sufficient permissions fail (correctly), but appear on client to temporarily succeed. +.PP +This program should probably be named +.IR cifsserver . diff --git a/sys/man/8/auth b/sys/man/8/auth new file mode 100755 index 000000000..3a537262a --- /dev/null +++ b/sys/man/8/auth @@ -0,0 +1,292 @@ +.TH AUTH 8 +.SH NAME +changeuser, convkeys, convkeys2, printnetkey, status, enable, disable, authsrv, guard.srv, debug, wrkey, login, newns, none, as \- maintain or query authentication databases +.SH SYNOPSIS +.B auth/changeuser +.RB [ -np ] +.I user +.PP +.B auth/convkeys +.RB [ -p ] +.I keyfile +.PP +.B auth/convkeys2 +.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/authsrv +.PP +.B auth/guard.srv +.PP +.B auth/debug +.PP +.B auth/wrkey +.PP +.B auth/login +.I user +.PP +.B auth/newns +[ +.B -ad +] [ +.B -n +.I namespace +] +.I command +.I arg +\&... +.PP +.B auth/none +[ +.B -n +.I namespace +] +.I command +.I arg +\&... +.PP +.B auth/as +.I user +.I command +.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 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 NVRAM +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 Authsrv +is the program, run only on the authentication server, that handles ticket requests +on TCP port 567. +It is started +by an incoming call to the server +requesting a conversation ticket; its standard input and output +are the network connection. +.I Authsrv +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. +.SS Anywhere commands +.PP +The remaining commands need not be run on an authentication server. +.PP +.I Debug +attempts to authenticate using each +.B p9sk1 +key found in +.I factotum +and prints progress reports. +.PP +.I Wrkey +prompts for a machine key, host owner, and host domain and stores them in +local non-volatile RAM. +.PP +.I Login +allows a user to change his authenticated id to +.IR user . +.I Login +sets up a new namespace from +.BR /lib/namespace , +starts a +.IR factotum (4) +under the new id and +.IR exec s +.IR rc (1) +under the new id. +.PP +.I Newns +sets up a new namespace from +.I namespace +(default +.BR /lib/namespace ) +and +.IR exec s +its arguments. +If there are no arguments, it +.IR exec s +.BR /bin/rc . +Under +.BR -a , +.I newns +adds to the current namespace instead of constructing a new one. +The +.BR -d +option enables debugging output. +.PP +.I None +sets up a new namespace from +.I namespace +(default +.BR /lib/namespace ) +as the user +.I none +and +.IR exec s +its arguments under the new id. +If there are no arguments, it +.IR exec s +.BR /bin/rc . +It's an easy way to run a command as +.IR none . +.PP +.I As +executes +.I command +as +.IR user . +.I Command +is a single argument to +.IR rc , +containing an arbitrary +.I rc +command. +This only works for the hostowner and only if +.L #¤/caphash +still exists. +.SH FILES +.TF /sys/lib/httppasswords +.TP +.B /lib/ndb/auth +Speaksfor relationships and mappings for +RADIUS server id's. +.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 passwd (1), +.I readnvram +in +.IR authsrv (2), +.IR keyfs (4), +.IR securenet (8) +.SH BUGS +Only CPU kernels permit changing userid. diff --git a/sys/man/8/backup b/sys/man/8/backup new file mode 100755 index 000000000..6f45e2c38 --- /dev/null +++ b/sys/man/8/backup @@ -0,0 +1,176 @@ +.TH BACKUP 8 +.SH NAME +backup, tobackup, dumparenas, restore \- backup venti arenas to blu-ray discs or restore from them +.SH SYNOPSIS +.B backup +[ +.B -n +] [ +.B -d +.I dev +] [ +.B -s +.I set +] +.br +.B tobackup +[ +.I set +] +.br +.B dumparenas +.I dev +.I arena +\&... +.br +.B restore +.I arena-# +[ +.I dev +] +.SH DESCRIPTION +These programs reside in +.B /sys/lib/backup +and provide a means to backup +.IR venti (8) +storage to Blu-ray (or other large optical) discs, +while keeping track of which arenas have been written to which discs. +Multiple backup sets are supported, +as is (re)loading a +.I venti +store from a backup thus made. +.PP +The first time that +.I backup +is run, +it will dump all sealed +.I venti +arenas. +Thereafter, +it will append only those sealed arenas not already written to a disc +within the given backup set. +The +.B -s +option uses a backup +.I set +other than the default. +The +.B -d +option uses a disc burner +other than the default +.LR /dev/sdD0 . +The +.B -n +option goes through the motions but does not burn any tracks +on the Blu-ray disc. +As a side-effect, +.I backup +run on the default dump set, +.LR set1 , +will also print the last few +.I fossil +dump scores. +.PP +.I Tobackup +prints the names of all the sealed arenas not yet backed up to a disc +in the current +.IR set . +.PP +.I Dumparenas +copies the named +.IR arena s, +one per track, +to the device +.IR dev , +which is first mounted via +.IR cdfs (4). +.I Venti/rdarena +is used to extract each arena. +.PP +.I Tobackup +and +.I dumparenas +are invoked internally by +.IR backup . +.PP +.I Restore +copies each data track (assumed to be a saved arena) on +.I dev +(by default, +.LR /dev/sdC0 ) +into its appropriate place in the +.I venti +arenas partition +(locally, +.BR /dev/sde0/arenas ), +thus adding the arena to the current +.I venti +store. +The arena size of the arena partition must match the size of the arenas +on optical disc (except for ~60K of trailing debris on the optical disc arenas). +.PP +.I Arena-# +must be the number (starting from zero) +of the first arena slot in the arenas partition that +you wish to restore into from the current optical disc +.RI ( not +necessarily that of the first arena on the disc). +.I Restore +will prompt for confirmation that the first arena is the correct one, +after printing a summary of its arena header. +Typing +.L y +will proceed normally, +.L n +will abort all processing, +and +.L skip +will cause +.I restore +to proceed to the next track and ask for confirmation of it. +.PP +The arenas partition must be formatted +(see +.I fmtarenas +in +.IR venti-fmt (8)) +before restoring into it. +When all the arenas have been restored, +it will be necessary to build a new +.I venti +index, +the usual steps being to run +.IR checkarenas , +.IR fmtisect , +.IR fmtbloom , +.IR fmtindex , +and +.IR "buildindex -b" , +all from +.IR venti-fmt (8). +.SH FILES +.TF /sys/lib/backup +.TP +.B /sys/lib/backup +backup scripts and records +.TP +.B set1 +subdirectory containing records for default backup set +.TP +.B /sys/log +source of dump scores +.SH SOURCE +.B /sys/lib/backup +.SH SEE ALSO +.IR venti (1), +.IR cdfs (4), +.IR venti (8), +.IR venti-fmt (8), +.IR venti-backup (8) +.br +.IR "Venti Backup on Blu-Ray Discs" +.SH BUGS +Assumes a single arenas partition named +.LR arena0 . +Assumes that the file server's arenas are accessible on it as +.LR /dev/fs/arena0 . diff --git a/sys/man/8/boot b/sys/man/8/boot new file mode 100755 index 000000000..094bf83ec --- /dev/null +++ b/sys/man/8/boot @@ -0,0 +1,389 @@ +.TH BOOT 8 +.SH NAME +boot \- connect to the root file server +.SH SYNOPSIS +.B /boot/boot +[ +.B -fkm +] +[ +.BI -u username +] +[ +.IB method ! fs-addr +] +[ +.I args +] +.SH DESCRIPTION +.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/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 (tcp, local!#S/sdC0/fs)[tcp]: +.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 +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 . +If the environment variable +.B init +is set (via +.IR plan9.ini (8)), +it is used as a command line to exec instead. +.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 +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 +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 +.BR tcp +connect via Ethernet using the TCP protocol. +The +.I args +are passed to +.IR ipconfig (8) +when configuring the IP stack. +The +.IR plan9.ini (8) +variables +.B fs +and +.B auth +override the file server and authentication server IP addresses +obtained (if any) from DHCP during +.IR ipconfig (8). +.TP 8 +.B local +connect to the local file system. +The first argument is a disk holding a file system. +.I Boot +inspects the disk. +If the disk is a +.IR fossil (4) +file system, it invokes +.B /boot/fossil +to serve it. +If the +.B venti +environment variable (really, +.IR plan9.ini (8) +variable) is set, +.I boot +first arranges for fossil to be able to +contact the named +.IR venti (8) +server. +The variable's value can take the following forms: +.RS +.TP +.B /dev/sdC0/arenas +the file should be a venti partition with a configuration +stored on it using +.I venti/conf +(see +.IR venti-fmt (8)). +.I Boot +will start a loopback IP interface on 127.0.0.1 +and start +.I venti +announcing on +.B tcp!127.1!17034 +for venti service +and +.B tcp!127.1!8000 +for web service, +using the configuration stored in that partition. +.TP +.B /dev/sdC0/arenas tcp!*!17034 +same as the last but specify an alternate venti service address. +In this example, using +.B * +will announce on all available IP interfaces (even ones configured later) +rather than just the loopback device. +The loopback interface is still configured. +.TP +.B /dev/sdC0/arenas tcp!*!17034 tcp!*!80 +same as the last but specify alternate venti service and web addresses. +The loopback interface is still configured. +.TP +.B tcp!135.104.9.2!17034 \fR[ \fIargs\fR ] +the network address of a venti server running on a separate machine. +.I Boot +will configure the IP stack by passing +.IR args , +if any, to +.IR ipconfig (8). +.RE +.PP +If the disk is not a +.IR fossil (4) +partition, +.I boot +invokes +.BR /boot/kfs . +A variety of programs, like +.I 9660srv +and +.IR dossrv (4) +masquerade as +.I kfs +to allow booting from alternate media formats, +so as long as the disk is not a +.I fossil +disk, no check is made that the disk is in fact +a +.I kfs +disk. +The args are passed to +.IR kfs (4). +.PP +For the +.B tcp +method, +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 EXAMPLES +On PCs, the default arguments to boot are constructed using +the +.B bootargs +variable in +.IR plan9.ini (8). +.PP +Start +.IR kfs (4) +with extra disk buffers: +.IP +.EX +bootargs=local!#S/sdC0/fs -B 4096 +.EE +.LP +Use an IP stack on an alternate ethernet interface +with a static address and fixed file server and authentication +server addresses. +.IP +.EX +fs=192.168.0.2 +auth=192.168.0.3 +bootargs=tcp -g 192.168.0.1 ether /net/ether1 \e + 192.168.0.50 255.255.255.0 +.EE +.LP +(The +.B bootargs +line is split only for presentation; it is one line in the file.) +.SH FILES +.B #s/boot +.br +.B #//boot/boot +.SH SOURCE +.B /sys/src/9/boot +.SH "SEE ALSO" +.IR root (3), +.IR dhcpd (8), +.IR init (8) +.SH BUGS +The use of +.B bootargs +in general is odd. +The configuration specification +for fossil and venti servers +is particularly odd, but it does +cover the common cases well. diff --git a/sys/man/8/booting b/sys/man/8/booting new file mode 100755 index 000000000..288f4cc25 --- /dev/null +++ b/sys/man/8/booting @@ -0,0 +1,261 @@ +.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 +or +.B /386/9pxeload +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 +.B /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. +. +.SS ARM CPU Servers +All ARM systems are started by +.I U-boot +using similar commands. +The kernels +(and thus +.I ndb +.L bootf +parameters) +are +.L /arm/9gd +for the Marvell PXA168-based Guruplug Display, +.L /arm/9plug +for all Marvell Kirkwood plugs (Sheevaplug, Guruplug, Openrd, etc.), +and +.L /arm/9beagle +for TI OMAP3 boards (IGEPv2 from ISEE, Gumstix Overo). +In the following, +replace +.I MAC +with your board's MAC address without colons, +in lower case +(the format of the +.L ether +.I ndb +attribute). +.PP +First, establish a +.I /cfg/pxe +(\c +.IR plan9.ini ) +file for the new CPU server. +For Kirkwood plugs, +.IP +.EX +cd /cfg/pxe; cp example-kw \fIMAC +.EE +.PP +and edit +.L /cfg/pxe/\fIMAC +to taste. +For PXA plugs, replace +.L kw +with +.LR pxa ; +for OMAP boards, replace +.L kw +with +.LR omap +and +be sure to edit the line for +.L ether0 +to set +.IP +.EX +ea=\fIMAC +.EE +.PP +Second, +configure +.I U-boot +to load the appropriate kernel and +.I /cfg/pxe +file at suitable addresses and start the kernel. +For Sheevaplugs and Openrd boards, +type this at U-boot once: +.IP +.EX +setenv bootdelay 2 +# \fItype the next two lines as one\fP +setenv bootcmd 'bootp; bootp; tftp 0x1000 /cfg/pxe/\fIMAC\fP; bootp; + tftp 0x800000; go 0x800000' +saveenv +.EE +.PP +For Guruplugs Displays, +do the same but type this after +.L "setenv bootcmd" +instead: +.IP +.EX +\&'dhcp; tftpboot; tftpboot 0x1000 /cfg/pxe/\fIMAC\fP; bootz 0x500000' +.EE +.PP +For Kirkwood Guruplugs, +type this after +.LR "setenv bootcmd" : +.IP +.EX +\&'dhcp 0x800000; tftp 0x1000 /cfg/pxe/\fIMAC\fP; go 0x800000' +.EE +.PP +For IGEPv2 boards, +type this after +.LR "setenv bootcmd" : +.IP +.EX +\&'tftp 0x80300000 /cfg/pxe/\fIMAC\fP; dhcp 0x80310000; go 0x80310000' +.EE +.PP +For Gumstix Overo boards, +type this after +.LR "setenv bootcmd" : +.IP +.EX +\&'bootp 0x80310000; bootp 0x80300000 /cfg/pxe/\fIMAC\fP; go 0x80310000' +.EE +.PP +Thereafter, the boards will automatically boot via BOOTP and TFTP +when reset. +. +.SH "SEE ALSO" +.IR ndb (6), +.IR 9load (8), +.IR boot (8), +.IR init (8), +.IR plan9.ini (8) +.SH SOURCE +Sources for the various boot programs are under +.BR /sys/src/boot . diff --git a/sys/man/8/cec b/sys/man/8/cec new file mode 100755 index 000000000..60db3525c --- /dev/null +++ b/sys/man/8/cec @@ -0,0 +1,153 @@ +.TH CEC 8 +.SH NAME +cec \- Coraid Ethernet Console +.SH SYNOPSIS +.B cec +[ +.B -dp +] [ +.B -S +.I srv +] [ +.B -c +.I esc +] [ +.B -e +.I ea +] [ +.B -h +.I host +[ +.B -s +.I shelf +] [ +.I interface +] +.SH DESCRIPTION +.I Cec +uses raw Ethernet packets to connect to a CEC server for console access. +All clients share the same session. +Coraid appliances and Coraid Plan 9 kernels can currently be CEC servers. +.PP +.I Cec +starts by probing the specified network interface +for available CEC servers. The default is +.BR /net/ether0 . +Only one +.I cec +process may be run per Ethernet interface. +If the server is specified with the +.BR -b , +.BR -h , +or +.B -s +options, communication will +proceed immediately upon discovery of the first CEC server +with the specified address. +Otherwise, a selection prompt +will be displayed showing the discovered CEC servers +available for communication. Unless the +.B -p +option is specified, +.I cec +exits if no matching servers are found. +The selection prompt accepts +.LP +.TF "\fInumber " +.TP +.I number +Connect to server +.I number +(from the first column), +.TP +.B p +Probe the interface again, and +.TP +.B q +Quit. +.PD +.PP +Note the selection number is not the shelf address but the +.IR cec -generated +sequence number printed in the leftmost column. +.PP +Once connected to a CEC server, typing the escape character +will drop the user into an escape prompt where the user may type +.L q +to quit the connection, +.L i +to send the escape character +across the connection, or +.L . +to continue the connection. +.SS Options +.TP +.B -c +Set the escape character to +.RI control- esc . +The default setting is control-\e. +.TP +.B -d +Print debugging information. +.TP +.B -e +Connect to the server with Ethernet address +.IR ea ; +implies +.BR -p . +.TP +.B -h +Connect to the server +.IR host . +Note that this name might not be the same as the contents of +.L /dev/sysname +on the target system. +.TP +.B -p +Persist: continue trying to connect even if +there are no matching servers. This is useful when +connecting to a CPU server before it boots. +.TP +.B -s +Connect to the server at address +.IR shelf . +.TP +.B -S +Post the CEC connection as +.BI /srv/ srv +to allow sharing. +.PP +If the +.BR -e , +.BR -s , +or +.B -h +options are given, +.I cec +will exit upon closing the connection. +Otherwise, +.I cec +will return to the selection prompt upon connection close. +.SH EXAMPLES +.IP +.EX +; cec '#l1/ether1' + 0 1 003048679b89 +[#qp]: 0 + +SR shelf 1> +SR shelf 1> >>> q + 0 1 003048679b89 +[#qp]: q +; +.EE +.SH SOURCE +.B /sys/src/cmd/cec +.\" .SH "SEE ALSO" +.\" .IR cec (3) +.SH BUGS +The CEC protocol should be integrated with the console server. +The arbitration between the keyboard and network is suboptimal. +.PP +Early boot information and very late crash information from servers +may be lost due to timing quirks. diff --git a/sys/man/8/cpurc b/sys/man/8/cpurc new file mode 100755 index 000000000..9d7f2882f --- /dev/null +++ b/sys/man/8/cpurc @@ -0,0 +1,88 @@ +.TH CPURC 8 +.SH NAME +cpurc, cpurc.local, termrc, termrc.local \- boot scripts +.SH SYNOPSIS +.B cpurc +.br +.B cpurc.local +.PP +.B termrc +.br +.B termrc.local +.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 +If an executable file +.B /bin/termrc.local +exists, +.I termrc +will execute it. +If an executable file +.B /cfg/$sysname/termrc +exists for the machine named +.BR $sysname , +.I termrc +will execute it next. +Automatic initialization of the mouse and +VGA on a PC is suppressed, if the user is +.BR none . +These files should be edited by local installations +to reflect the configuration of their systems. +.PP +On CPU servers, read +.L cpurc +for +.L termrc +in the previous paragraph. +.SH FILES +.TF /cfg/$sysname/termrc +.TP +.B /cfg/$sysname/cpurc +machine-specific boot script for +.I cpurc +.TP +.B /cfg/$sysname/termrc +machine-specific boot script for +.I termrc +.SH SOURCE +.B /rc/bin/*rc +.br +.B /rc/bin/*rc.local +.br +.B /cfg/$sysname/*rc +.SH "SEE ALSO" +.IR srv (4), +.IR namespace (6), +.IR init (8), +.IR listen (8) diff --git a/sys/man/8/cron b/sys/man/8/cron new file mode 100755 index 000000000..0dbd27538 --- /dev/null +++ b/sys/man/8/cron @@ -0,0 +1,128 @@ +.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 . +If +.I host +is +set to +.BR local , +.I cron +will run the command as +.I user +on the local machine without using +.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 FILES +.TF /cron/lock +.TP +.B /cron/lock +lock file to prevent multiple +.IR cron s +running +.SH SOURCE +.B /sys/src/cmd/auth/cron.c +.SH "SEE ALSO" +.IR con (1), +.IR rc (1) diff --git a/sys/man/8/dhcpd b/sys/man/8/dhcpd new file mode 100755 index 000000000..6e4102913 --- /dev/null +++ b/sys/man/8/dhcpd @@ -0,0 +1,299 @@ +.TH DHCPD 8 +.SH NAME +dhcpd, dhcpleases, rarpd, tftpd \- Internet booting +.SH SYNOPSIS +.PP +.B ip/dhcpd +.RB [ -dmnprsSZ ] +.RB [ -f +.IR ndb-file ] +.RB [ -M +.IR secs ] +.RB [ -x +.IR netmtpt ] +.RB [ -Z +.IR secs ] +[ +.I address +.I n +] ... +.PP +.B ip/dhcpleases +.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 if 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; +see +.IR ndb (6) +.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 f +Specify a file other than +.B /lib/ndb/local +as the network database. +.TP +.B m +Mute: don't reply to requests, just log them and what +.I dhcpd +would have done. +.TP +.B M +Use +.I secs +as the minimum lease time for dynamic addresses. +.TP +.B n +Don't answer +.SM BOOTP +requests. +.TP +.B p +Answer +.SM DHCP +requests from +.SM PPTP +clients only. +.TP +.B r +Mute static addresses: don't reply to requests for static addresses, +just log them and what +.I dhcpd +would have done. +.TP +.B s +Sleep 2 seconds before answering requests for static addresses. +This is used to make a server be a backup only. +.TP +.B S +Sleep 2 seconds before answering requests for dynamic addresses. +.TP +.B x +The IP stack to use is mounted at +.IR netmtpt . +The default is +.BR /net . +.TP +.B Z +Use +.I secs +as the minimum lease time for static addresses. +.PD +.PP +.I Dhcpleases +prints out the currently valid DHCP leases found in the +.B /lib/ndb/dhcp +directory. +.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), +.IR 9load (8), +.IR booting (8) diff --git a/sys/man/8/diskparts b/sys/man/8/diskparts new file mode 100755 index 000000000..7b0e9d5b9 --- /dev/null +++ b/sys/man/8/diskparts @@ -0,0 +1,44 @@ +.TH DISKPARTS 8 +.SH NAME +diskparts, dmaon \- prepare disks for use +.SH SYNOPSIS +.B diskparts +.br +.B dmaon +.SH DESCRIPTION +.I Diskparts +configures FDISK and Plan 9 partitions on any disks named +.BR /dev/sd* , +then configures +.IR fs (3) +by copying +.BR /cfg/$sysname/fsconfig , +if present, to +.BR /dev/fs/ctl , +if present, +one line at a time. +If +.B #S +or +.B #k +are not bound to +.B /dev +yet, they are first bound after the current contents. +.PP +.I Dmaon +enables +.SM DMA +for all attached +.SM IDE +devices that claim to support it. +.SH FILES +.TF /dev/sd[C-H]?/ctl +.TP +.B /dev/sd[C-H]?/ctl +storage interface control files for IDE devices +.PD +.SH SOURCE +.B /rc/bin +.SH SEE ALSO +.IR sd (3), +.IR partfs (8) diff --git a/sys/man/8/disksim b/sys/man/8/disksim new file mode 100755 index 000000000..cd76609e6 --- /dev/null +++ b/sys/man/8/disksim @@ -0,0 +1,99 @@ +.TH DISKSIM 8 +.SH NAME +disksim \- disk simulator +.SH SYNOPSIS +.B aux/disksim +[ +.B -r +] +[ +.B -f +.I file +] +[ +.B -s +.I srvname +] +[ +.B -m +.I mtpt +] +[ +.I diskname +] +.SH DESCRIPTION +.I Disksim +presents an in-memory disk in the manner of the +.IR sd (3) +device on +.IB mtpt / diskname +(default +.BR /dev/sdXX ). +The disk is initialized to zeros; +non-zeroed blocks written to the disk are kept in memory. +.PP +When setting disk geometry with the +.B geometry +control message, +the arguments are +sectors, sector size, cylinders, heads, and sectors per track. +The last three may be zero for LBA disk simulations, +but must be present. +.PP +The +.B -f +option causes +.I disksim +to use +.I file +as the initial contents of the disk rather than a zeroed image. +Changes made to the disk are written back to +.I file +unless the +.B -r +option is given. +.PP +The +.B -s +option causes +.I disksim +to post its 9P service at +.BI /srv/ service \fR. +.SH EXAMPLES +.I Disksim +can be used to test programs such as +.I fdisk +and +.IR prep (8) +that expect +.IR sd (3) +disks: +.IP +.EX +aux/disksim +echo geometry 40000 512 0 0 0 >/dev/sdXX/ctl # 20MB +disk/mbr /dev/sdXX/data +disk/fdisk -baw /dev/sdXX/data +disk/prep /dev/sdXX/plan9 +.EE +.PP +.I Disksim +is useful for creating very large but mostly zeroed files +for testing other programs. +Test +.IR tar (1)'s +handling of large files: +.IP +.EX +for(i in sdXX sdYY sdZZ) aux/disksim $i +echo geometry 40000000 512 0 0 0 >/dev/sdXX/ctl # 20GB +echo geometry 10000000 512 0 0 0 >/dev/sdYY/ctl # 5GB +echo geometry 20000000 512 0 0 0 >/dev/sdZZ/ctl # 10GB +tar cf /dev/sdXX/data /dev/sdYY/data /dev/sdZZ/data +tar tvf /dev/sdXX/data +.EE +.SH SOURCE +.B /sys/src/cmd/aux/disksim.c +.SH SEE ALSO +.IR sd (3), +.IR prep (8) diff --git a/sys/man/8/drawterm b/sys/man/8/drawterm new file mode 100755 index 000000000..5dadc385c --- /dev/null +++ b/sys/man/8/drawterm @@ -0,0 +1,117 @@ +.TH DRAWTERM 8 +.SH NAME +drawterm \- connect to Plan 9 CPU servers from other operating systems +.SH SYNOPSIS +.B drawterm +[ +.B -d +] +[ +.B -a +.I authaddr +] +[ +.B -c +.I cpuaddr +] +[ +.B -e +.I encryption-hash-algs +] +[ +.B -k +.I keypattern +] +[ +.B -s +.I secstoreaddr +] +[ +.B -u +.I user +] +[ +.B -C +.I cmd args ... +] +.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 $cpu +or +.BR cpu . +and the authentication server +.B $auth +or +.BR auth . +The +.BR -a , +.BR -c , +and +.B -s +options specify alternate authentication, CPU and +.I secstore +servers, +respectively. +(Edit the source to set appropriate local defaults.) +.PP +.I Cmd +is a command to be executed remotely. +Options +.LR e , +.LR k , +and +.L u +have the same meaning as in +.IR cpu (1). +.PP +Drawterm has been ported to +FreeBSD, +Irix, +Linux, +NetBSD, +and +Windows. +Binaries can be downloaded from +.BR http://swtch.com/drawterm/ . +.SH SOURCE +.B /sys/src/cmd/unix/drawterm +.SH DIAGNOSTICS +Drawterm prints most diagnostics in its own window. +.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/sys/man/8/fossilcons b/sys/man/8/fossilcons new file mode 100755 index 000000000..64fd26085 --- /dev/null +++ b/sys/man/8/fossilcons @@ -0,0 +1,1180 @@ +.TH FOSSILCONS 8 +.SH NAME +fossilcons \- fossil console commands +.SH SYNOPSIS +.B +con /srv/fscons +.PP +.PD 0.1 +.B . +.I file +.PP +.B 9p +.I T-message +... +.PP +.B bind +[ +.B -b|-a|-c|-bc|-ac +] +.I new +.I old +.PP +.B dflag +.PP +.B echo +[ +.B -n +] +[ +.I arg +... +] +.PP +.B listen +[ +.B -INd +] +[ +.I address +] +.PP +.B msg +[ +.B -m +.I nmsg +] +[ +.B -p +.I nproc +] +.PP +.B printconfig +.PP +.B srv +[ +.B -APWdp +] +.I name +.PP +.B uname +.I name +[ +.I id +| +.BI : id +| +.BI % newname +| +.BI = leader +| +.BI + member +| +.BI - member +] +.PP +.B users +[ +.B -d +| +.B -r +.I file +] +[ +.B -w +] +.PP +.B who +.sp +.PP +.B fsys +.I name +.PP +.B fsys +.I name +.B config +.I device +.PP +.B fsys +.I name +.B venti +[ +.I host +] +.PP +.B fsys +.I name +.B open +[ +.B -APVWr +] +[ +.B -c +.I ncache +] +.PP +[ +.B fsys +.I name +] +.B close +.PP +.B fsys +.I name +.B unconfig +.sp +.PP +[ +.B fsys +.I name +] +.B bfree +.I addr +.PP +[ +.B fsys +.I name +] +.B block +.I addr +.I offset +[ +.I count +[ +.I data +]] +.PP +.in +1i +.ti -1i +[ +.B fsys +.I name +] +.B check +[ +.B pblock +] [ +.B pdir +] [ +.B pfile +] [ +.B bclose +] [ +.B clri +] [ +.B clre +] [ +.B clrp +] [ +.B fix +] [ +.B venti +] [ +.B snapshot +] +.PP +[ +.B fsys +.I name +] +.B clre +.I addr +.I offsets +\&... +.PP +[ +.B fsys +.I name +] +.B clri +.I files +\&... +.PP +[ +.B fsys +.I name +] +.B clrp +.I addr +.I offset +\&... +.PP +[ +.B fsys +.I name +] +.B create +.I path +.I uid +.I gid +.I perm +.PP +[ +.B fsys +.I name +] +.B df +.PP +[ +.B fsys +.I name +] +.B epoch +[[ +.B -ry +] +.I n +] +.PP +[ +.B fsys +.I name +] +.B halt +.PP +[ +.B fsys +.I name +] +.B label +.I addr +[ +.I type +.I state +.I epoch +.I epochclose +.I tag +] +.PP +[ +.B fsys +.I name +] +.B remove +.I files +\&... +.PP +[ +.B fsys +.I name +] +.B snap +[ +.B -a +] +[ +.B -s +.I src +] +[ +.B -d +.I dst +] +.PP +[ +.B fsys +.I name +] +.B snapclean +[ +.I timeout +] +.PP +[ +.B fsys +.I name +] +.B snaptime +[ +.B -a +.I hhmm +] +[ +.B -s +.I interval +] +[ +.B -t +.I timeout +] +.PP +[ +.B fsys +.I name +] +.B stat +.IR files ... +.PP +[ +.B fsys +.I name +] +.B sync +.PP +[ +.B fsys +.I name +] +.B unhalt +.PP +[ +.B fsys +.I name +] +.B vac +.I dir +.PP +[ +.B fsys +.I name +] +.B wstat +.I file +.I elem +.I uid +.I gid +.I perm +.I length +.SH DESCRIPTION +These are configuration and maintenance commands +executed at the console of a +.IR fossil (4) +file server. +The commands are split into three groups above: +file server configuration, +file system configuration, +and file system maintenance. +This manual page is split in the same way. +.SS File server configuration +.PP +The +dot +.RI ( . ) +command +reads +.IR file , +treating each line as a command to be executed. +Blank lines and lines beginning with a +.L # +character are ignored. +Errors during execution are printed but do not stop the script. +Note that +.I file +is a file in the name space in which +.I fossil +was started, +.I not +a file in any file system served by +.IR fossil . +.PP +.I 9p +executes a 9P transaction; the arguments +are in the same format used by +.IR 9pcon (8). +.PP +.I Bind +behaves similarly to +.IR bind (1). +It is useful when fossil +is started without devices it needs configured +into its namespace. +.PP +.I Dflag +toggles the debug flag and prints the new setting. +When the debug flag is set, all protocol messages +and information about authentication is printed to +standard error. +.PP +.I Echo +behaves identically to +.IR echo (1), +writing to the console. +.PP +.I Listen +manages the network addresses at which +fossil is listening. +With no arguments, +.I listen +prints the current list of addresses and their network directories. +With one argument, listen +.I address +starts a new listener at +.IR address ; +the +.B -d +flag causes +.I listen +to remove the listener +at the given address. +By default, the user +.I none +is only allowed to attach on a connection after +at least one other user has successfully attached. +The +.B -N +flag allows connections from +.I none +at any time. +The +.B -I +flag causes +.I fossil +to check the IP address of incoming connections +against +.BR /mnt/ipok , +rejecting attaches from disallowed addresses. +This mechanism is not intended for general use. +The server +.I sources.cs.bell-labs.com +uses it to comply with U.S. crytography +export regulations. +.PP +.I Msg +prints the maximum internal 9P message queue size +and the maximum number of 9P processes to +allocate for serving the queue. +The +.B -m +and +.B -p +options set the two variables. +.PP +.I Printconfig +prints the +.B config +line for each configured file system +and prints the +.B venti +line, if any, used to configure this file server. +.PP +.I Srv +behaves like listen but uses +.BI /srv/ name +rather than a network address. +With the +.B -p +flag, +.I srv +edits a list of console services rather than 9P services. +With no arguments, +.I srv +prints the current list of services. +With one argument, srv +.I name +starts a new service at +.IR /srv/name ; +the +.B -d +flag causes +.I srv +to remove the named service. +See the +.I [fsys] open +command below for a description of the +.B -APW +options. +.PP +.I Uname +manipulates entries in the user table. +There is no distinction between users and groups: +a user is a group with one member. +For each user, the user table records: +.TP +.I id +the string used to represent this user in the on-disk structures +.TP +.I name +the string used to represent this user in the 9P protocol +.TP +.I leader +the group's leader (see +.IR stat (5) +for a description of the special privileges held by a group leader) +.TP +.I members +a comma-separated list of members in this group +.PP +The +.I id +and +.I name +are usually the same string, but need not be. +Once an +.I id +is used in file system structures archived to Venti, +it is impossible to change those disk structures, +and thus impossible to rename the +.IR id . +The translation from +.I name +to +.I id +allows the appearance of renaming the user even +though the on-disk structures still record the old name. +(In a conventional Unix file system, the +.I id +is stored as a small integer rather than a string.) +.I Leader +and +.I members +are names, not ids. +.PP +The first argument to +.I uname +is the +.I name +of a user. +The second argument is a verb, one of: +.TP +.I id +create a user with name +.RI ` name ' +and id +.RI ` id ;' +also create a home directory +.BI /active/usr/ uname \fR +.TP +.BI : id +create a user with name +.RI ` name ' +and id +.RI ` id ,' +but do not create a home directory +.TP +.BI % newname +rename user +.RI ` name ' +to +.RI ` newname ,' +throughout the user table +.TP +.BI = leader +set +.IR name 's +group leader +to +.IR leader . +.TP +.BI = +remove +.IR name 's +group leader; then all members will be +considered leaders +.TP +.BI + member +add +.I member +to +.IR name 's +list of members +.TP +.BI - member +remove +.I member +from +.IR name 's +list of members +.LP +If the verb is omitted, the entire entry for +.I name +is printed, in the form +`\fIid\fL:\fIname\fL:\fIleader\fL:\fImembers\fR.' +.LP +The end of this manual page gives examples. +.PP +.I Users +manipulates the user table. +The user table is a list of lines in the form printed +by the +.I uname +command. +The +.B -d +flag resets the user table with the default: +.IP +.EX +adm:adm:adm:sys +none:none:: +noworld:noworld:: +sys:sys:: +glenda:glenda:glenda: +.EE +.PP +Except +.BR glenda , +these users are mandatory: they must appear in all user +files and cannot be renamed. +.PP +The +.B -r +flag reads a user table from the named +.I file +in file system +.BR main . +The +.B -w +flag writes the table to +.B /active/adm/users +on the file system +.BR main . +.B /active/adm +and +.B /active/adm/users +will be created if they do not exist. +.PP +.I Users +.B -r +.B /active/adm/users +is automatically executed when the file system +.B main +is opened. +.PP +.I Users +.B -w +is automatically executed after each change to the user +table by the +.I uname +command. +.PP +.I Who +prints a list of users attached to each active connection. +.SS File system configuration +.I Fsys +sets the current file system to +.IR name , +which must be configured and open (q.v.). +The current file system name is +displayed as the file server prompt. +The special name +.B all +stands for all file systems; +commands applied to +.B all +are applied to each file system in turn. +The commands +.BR config , +.BR open , +.BR venti , +and +.B close +cannot be applied to +.BR all . +.PP +.I Fsys +takes as an optional argument +(after +.BR name ) +a command to execute on the named file system. +Most commands require that the named file system +be configured and open; these commands can be invoked +without the +.BI fsys " name +prefix, in which case the current file system is used. +A few commands +.RB ( config , +.BR open , +and +.BR unconfig ) +operate on unopened file systems; they require the prefix. +.PP +.I Config +creates a new file system named +.I name +using disk file +.I device . +This just adds an entry to fossil's internal table. +.PP +.I Venti +establishes a connection to the Venti server +.I host +(by default, the environment variable +.B $venti +or the network variable +.BR $venti ) +for use by the named file system. +If no +.I venti +command is issued before +.IR open , +the default Venti server will be used. +If the file system is open, +and was not opened with the +.B -V +flag, +the command redials the Venti server. +This can be used to reestablish broken connections. +It is not a good idea to use the command to switch +between Venti servers, since Fossil does not keep track +of which blocks are stored on which servers. +.PP +.I Open +opens the file system, reading the +root and super blocks and allocating an in-memory +cache for disk and Venti blocks. +The options are: +.TP +.B -A +run with no authentication +.TP +.B -P +run with no permission checking +.TP +.B -V +do not attempt to connect to a Venti server +.TP +.B -W +allow wstat to make arbitrary changes to the user and group fields +.TP +.B -r +open the file system read-only +.TP +.BI -c " ncache +allocate an in-memory cache of +.I ncache +(by default, 1000) +blocks +.PP +The +.I -APW +settings can be overridden on a per-connection basis +by the +.I srv +command above. +.PP +.I Close +flushes all dirty file system blocks to disk +and then closes the device file. +.PP +.I Unconfig +removes the named file system (which must be closed) +from fossil's internal table. +.SS File system maintenance +.I Bfree +marks the block at disk address +.I addr +as available for allocation. +Before doing so, it prints a +.I label +command (q.v.) +that can be used to restore the block to its previous state. +.PP +.I Block +displays (in hexadecimal) +the contents of the block at disk address +.IR addr , +starting at +.I offset +and continuing for +.I count +bytes or until the end of the block. +If +.I data +(also hexadecimal) +is given, the contents in that range are +replaced with data. +When writing to a block, +.I block +prints the old and new contents, +so that the change is easily undone. +Editing blocks is discouraged. +.PP +.I Clre +zeros an entry from a disk block. +Before doing so, it prints a +.I block +command that can be used +to restore the entry. +.PP +.I Clri +removes 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 +.I flchk +(see +.IR fossil (4)) +will identify the abandoned storage so it can be reclaimed with +.I bfree +commands. +.PP +.I Clrp +zeros a pointer in a disk block. +Before doing so, it prints a +.I block +command that can be used to restore the entry. +.PP +.I Check +checks the file system for various inconsistencies. +If the file system is not already halted, it is halted for +the duration of the check. +If the archiver is currently sending a snapshot to Venti, +the check will refuse to run; the only recourse is to wait +for the archiver to finish. +.PP +A list of keyword options control the check. +The +.BR pblock , +.BR pdir , +and +.B pfile +options cause +.I check +to print the name of each block, directory, or file encountered. +.PP +By default, +.I check +reports errors but does not fix them. +The +.BR bclose , +.BR clri , +.BR clre , +and +.B clrp +options specify correcting actions that may be taken: +closing leaked blocks, clearing bad file directory entries, +clearing bad pointers, and clearing bad entries. +The +.B fix +option enables all of these; it is equivalent to +.B bclose +.B clri +.B clre +.BR clrp . +.PP +By default, +.I check +scans the portion of the active file system held in the write buffer, +avoiding blocks stored on Venti or used only in snapshots. +The +.B venti +option causes +.I check +to scan the portion of the file system stored on Venti, +and the +.B snapshot +option causes +.I check +to scan old snapshots. +Specifying +.B snapshot +causes +.I check +to take a long time; +specifying +.B venti +or +(worse) +.B venti +.B snapshot +causes +.I check +to take a very long time. +.PP +.I Create +creates a file on the current file system. +.I Uid +and +.I gid +are uids +.RI ( not +unames; +see the discussion above, in the description +of the +.I uname +command). +.I Perm +is the low 9 bits of the permission mode of the file, +in octal. +The +.BR a , +.BR d , +and +.B l +mode prefixes +set the append-only, directory, and lock bits. +The +.I perm +is formatted as described in the +.I stat +command; +creating files or directories with the +.BR snapshot (s) +bit set is not allowed. +.PP +.I Df +prints the amount of used disk space in the write buffer. +.PP +.I Epoch +sets the low file system epoch. +Snapshots in the file system are given increasing epoch numbers. +The file system maintains a low and a high epoch number, +and only allows access to snapshots in that range. +The low epoch number can be moved forward to discard old snapshots +and reclaim the disk space they occupy. +(The high epoch number is always the epoch of the currently +active file system.) +.PP +With no argument +.I epoch +reports the current low and high epoch numbers. +The command +``\fLepoch\fI n''\fR +is used to propose changing the low epoch to +.IR n . +In response, +.I fossil +scans +.B /archive +and +.B /snapshot +for snapshots that would be discarded, printing their +epoch numbers and the +.I clri +commands necessary to remove them. +The epoch is changed only if no such paths are found. +The usual sequence of commands is (1) run epoch to +print the snapshots and their epochs, (2) clri some snapshots, +(3) run epoch again. +If the file system is completely full (there are no free blocks), +.I clri +may fail because it needs to allocate blocks. +For this situation, +the +.B -y +flag to epoch forces the epoch change even when +it means discarding currently accessible snapshots. +Note that when there are still snapshots in +.BR /archive , +the archiver should take care +of those snapshots (moving the blocks from disk to Venti) +if you give it more time. +.PP +The +.B -r +flag to epoch causes it to remove any now-inaccessible +snapshot directories once it has changed the epoch. +This flag only makes sense in conjunction with the +.B -y +flag. +.PP +.I Epoch +is a very low-level way to retire snapshots. +The preferred way is by setting an automatic timer +with +.IR snaptime . +.PP +.I Halt +suspends all file system activity; +.I unhalt +resumes activity. +.PP +.I Label +displays and edits the label associated with a block. +When editing, a parameter of +.B - +means leave that field unchanged. +Editing labels is discouraged. +.PP +.I Remove +removes +.IR files . +.PP +.I Snap +takes a temporary snapshot of the current file system, +recording it in +.BI /snapshot/ yyyy / mmdd / hhmm \fR, +as described in +.IR fossil (4). +The +.B -a +flag causes +.I snap +to take an archival snapshot, recording it in +.BI /archive/ yyyy / mmdd \fR, +also described in +.IR fossil (4). +By default the snapshot is taken of +.BR /active , +the root of the active file system. +The +.B -s +flag specifies a different source path. +The +.B -d +flag specifies a different destination path. +These two flags are useful together for moving snapshots into +the archive tree. +.PP +.I Snapclean +immediately discards all snapshots that are more than +.I timeout +minutes old. +The default timeout is the one set by the +.I snaptime +command. +The discarding is a one-time event rather than +a recurring event as in +.IR snaptime . +.PP +.I Snaptime +displays and edits the times at which snapshots are automatically +taken. +An archival snapshot is taken once a day, at +.IR hhmm , +while temporary snapshots are taken at multiples of +.I interval +minutes. +Temporary snapshots are discarded after they are +.I timeout +minutes old. +The snapshot cleanup runs every +.I timeout +minutes or once a day, whichever is more frequent, +so snapshots may grow to an age of almost twice the timeout +before actually being discarded. +With no arguments, +.I snaptime +prints the current snapshot times. +The +.B -a +and +.B -s +options set the archive and snapshot times. +An +.I hhmm +or +.I interval +of +.L none +can be used to disable that kind of automatic snapshot. +The +.B -t +option sets the snapshot timeout. +If +.I timeout +is +.LR none , +temporary snapshots are not automatically discarded. +By default, all three times are set to +.LR none . +.PP +.I Stat +displays metadata for each of the named +.IR files , +in the form: +.IP +.EX +stat \fIfile elem uid gid perm length +.EE +.LP +(Replacing +.B stat +with +.B wstat +yields a valid command.) +The +.I perm +is an octal number less than or equal to 777, +prefixed with any of the following letters +to indicate additional bits. +.IP +.EX +.ta +4n +a \fRappend only +d \fRdirectory +l \fRexclusive use +s \fRis the root of a snapshot +t \fRtemporary bit +A \fRMS-DOS archive bit +G \fRsetgid +H \fRMS-DOS hidden bit +L \fRsymbolic link +S \fRMS-DOS system bit +U \fRsetuid +Y \fRsticky +.EE +.PP +The bits denoted by capital letters are included +to support non-Plan 9 systems. +They are not made visible by the 9P protocol. +.PP +.I Sync +writes dirty blocks in memory to the disk. +.PP +.I Vac +prints the Venti score for a +.IR vac (1) +archive containing the tree rooted +at +.IR dir , +which must already be archived to Venti +(typically +.IR dir +is a directory in the +.B /archive +tree). +.PP +.I Wstat +changes the metadata of the named +.IR file . +Specifying +.B - +for any of the fields means ``don't change.'' +Attempts to change the +.B d +or +.B s +bits in the +.I perm +are silently ignored. +.SH EXAMPLES +.IR Sources , +the Plan 9 distribution file server, +uses the following configuration file: +.IP +.EX +srv -p fscons.sources +srv -p fscons.sources.adduserd +srv sources +fsys main config /dev/sdC0/fossil.outside +fsys main open -c 25600 +fsys main +users /active/adm/users +listen tcp!*!564 +msg -m 40 -p 10 +snaptime -a 0000 -s 15 +.EE +.LP +The second console is used by the daemon +that creates new accounts. +.PP +To add a new user with +.I name +and +.I id +.B rob +and create his home directory: +.IP +.EX +uname rob rob +.EE +.PP +To create a new group +.B sys +(with no home directory) +and add +.B rob +to it: +.IP +.EX +uname sys :sys +uname sys +rob +.EE +.PP +To save an old (but not yet discarded) snapshot into the archive tree: +.IP +.EX +snap -a -s /snapshot/2003/1220/0700 -d /archive/2003/1220 +.EE diff --git a/sys/man/8/fs b/sys/man/8/fs new file mode 100755 index 000000000..6889739b3 --- /dev/null +++ b/sys/man/8/fs @@ -0,0 +1,826 @@ +.TH FS 8 +.SH NAME +fs, exsort \- file server maintenance +.SH SYNOPSIS +.PD 0 +.B help +[ +.I command ... +] +.PP +.B allow +.PP +.B arp +.I subcommand +.PP +.B cfs +.I filesystem +.PP +.B check +.RI [ options ] +.PP +.B clean +.I file +[ +.I bno +[ +.I addr +] ] +.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 disallow +.PP +.B duallow +.RI [ uid ] +.PP +.B dump +[ +.I filesystem +] +.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 printconf +.PP +.B profile +.RB [ 01 ] +.PP +.B remove +.RI [ files ...] +.PP +.B route +.I subcommand +.PP +.B "sntp kick" +.PP +.BR stat [ admiesw ] +.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 +] +.PP +.B wormoffline +.I drive +.PP +.B wormonline +.I drive +.PP +.B wormreset +.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 Allow +disables permission checking and allows +.BR wstat . +This may help in initializing a file system. +Use this with caution. +.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 clean , +.BR clri , +.BR create , +.BR cwcmd , +.BR dump , +.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. +.TP +.B trim +reduces the file system's +.I fsize +to fit the device containing the file system. +This is useful after copying a partially-full file system +into a slightly smaller device. +Running +.B "check free" +afterward will construct a new free list that contains no +blocks outside the new, smaller file system. +.PP +.I Clean +prints the block numbers in +.IR file 's +directory entry (direct, indirect and doubly indirect) +and checks the tags of the blocks cited. +If +.I bno +is supplied, the +.IR bno 'th +block number (using zero origin) +is set to +.I addr +(defaults to zero). +Note that only the block numbers in the directory entry itself +are examined; +.I clean +does not recurse through indirect blocks. +.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, +specifically the current file system. +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] [\fIback-flag\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 +.I back-flag +is supplied and is non-zero). +.TP +.BR searchtag " [\fIstart\fP] [\fItag\fP] [\fIblocks\fP] +Reads the WORM device starting at block +.I start +and proceeding for +.I blocks +blocks (default 1000) +until it finds a block with numeric tag +.IR tag . +.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 side +.I dskno +(zero-origin), +read the block from WORM to the cache. +If +.I dskno +is not supplied, all blocks in +.B /adm/cache +are read. +.TP +.BR morecache " dskno [\fIcount\fP] +Read +.I count +blocks from the beginning of WORM disk side +.I dskno +to the cache. +If no count is given, +read all of side +.IR dskno +into the cache. +.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 +.BR blockcmp " [\fIwbno\fP] [\fIcbno\fP] +Compares the WORM block +.I wbno +with the cache block +.I cbno +and prints the first 10 differences, if any. +.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 Disallow +restores permission checking back to normal after a file system +has been initialized. +.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 +the named filesystem, +or the current filesystem if none is named. +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 authdisablexx +.TP +.B allchans +Print channels in +.I who +output. +.TP +.B arp +Report ARP activity. +.TP +.B attach +Report as connections are made to the file server. +.TP +.B authdebug +Report authentications. +.TP +.B authdisable +Disable authentication. +.TP +.B chat +(Very noisy.) Print all 9P messages to and from the server. +.TP +.B error +Report 9P errors. +.TP +.B il +Report IL errors. +.TP +.B route +Report received RIP packets. +.TP +.B ro +Report I/O on the WORM device. +.TP +.B sntp +Report SNTP activity. +.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 Printconf +prints the system configuration information. +.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 +.I Sntp +.I kick +queries the SNTP server +(see +.IR fsconfig (8)) +and sets the time with its response. +.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 i , +IDE/ATA targets; +.BR m , +Marvell SATA targets; +.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 +of the first jukebox to the output shelf. +.PP +.I Wormingest +moves the WORM disk from the input shelf of the first jukebox to slot +.IR tunit . +.PP +.I Wormoffline +takes +.I drive +of the first jukebox out of service; +.I wormonline +puts it back in service. +.PP +.I Wormreset +put discs back where the jukebox thinks they belong, +and does this for all jukeboxes. +.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 SEE ALSO +.IR fs (4) +.br +Ken Thompson, +``The Plan 9 File Server''. +.SH SOURCE +.B /sys/src/fs +.br +.B /sys/src/cmd/disk/exsort.c +.SH BUGS +The +.B worm* +commands should accept an argument identifying a jukebox. diff --git a/sys/man/8/fsconfig b/sys/man/8/fsconfig new file mode 100755 index 000000000..e5a0c6748 --- /dev/null +++ b/sys/man/8/fsconfig @@ -0,0 +1,431 @@ +.TH FSCONFIG 8 +.SH NAME +fsconfig \- configuring a file server +.SH SYNOPSIS +.B service +.I name +.PP +.B config +.I device +.PP +.B nvram +.I device +.PP +.B filsys +.I name +.I device +.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 ream +.I name +.PP +.B recover +.I name +.PP +.B allow +.PP +.B readonly +.PP +.B noauth +.PP +.B noattach +.PP +.B copyworm +.PP +.B copydev +.I from-dev +.I to-dev +.PP +.B halt +.PP +.B end +.SH DESCRIPTION +When an +.IR fs (4) +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. +.SS Syntax +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 +Defines a SCSI disk on target (unit) id +.IR n2 , +controller (host adapter) +.IR n1 , +and LUN (logical unit number) +.IR n3 . +A single number specifies a target, while two numbers specify +.IB target . lun\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. +.I M +may be greater than +.IR n . +For example, +.B (w<1-4>) +is the concatenation of SCSI targets 1 through 4. +.TP +.BI h n1 . n2 . n3 +.I H +is similar to +.IR w , +but for IDE or ATA disks, +and the controllers must be specified in +.BR plan9.ini . +.I Lun +is ignored. +.I Target +0 is an IDE master +and 1 is a slave. +Instead of specifying +.I controller +and +.IR target +separately, +one may omit the +.I controller +and specify a target of +.IB controller-number *2 +.B + +.IR target-number , +thus +.B h2 +is equivalent to +.B h1.0.0 +(second IDE controller, master drive). +.TP +.BI m n1 . n2 . n3 +.I M +is similar to +.IR h , +but for SATA drives connected to Marvell +88SX[56]0[48][01] controllers. +There is no need to specify the controllers in +.B plan9.ini +as they are autodiscovered. +Hot-swapping drives is not currently supported. +Similar target naming rules apply as for IDE controllers. +However the controller-number is multiplied by the number of +drives the controller supports rather than 2. +Thus +.B m9 +is equivalent to +.B m1.1.0 +(second controller, second drive), +if the first controller supports 8 drives. +.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. +Only +.I n2 +is really of interest, +and refers to a side of a WORM disc. +These 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 { device... } +A pseudo-device formed from the mirroring of the first +.I device +in the list onto all the others. +The size of the result is the size of the smallest device. +One might think of this as RAID 1, +and +.B [ +.B ] +as RAID 0, +though neither includes any fancy recovery mechanisms. +Each block is written to all the devices, +starting with the rightmost in the list and working leftward. +A block is read from the first device that provides it without error, +starting with the leftmost in the list and working rightward. +.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 +.BI x device +A pseudo-device that contains the byte-swapped contents of +.IR device . +Since the file server writes integers to disk in its native byte order, +it can be necessary to use this device to read file systems written +by processors of the other byte order. +.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 most-recently defined cached WORM file system. +.SS Configuration +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 +and +.B nvram +commands identify the +.I device +on which the information is recorded. +The +.B config +command also erases any previous configuration. +.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 +.B main +is the one attached to if the specifier is null; see +.IR attach (5)). +.PP +The rest of the configuration 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 +.RI ( ipsntp ). +.I Ipauth +is no longer used. +If the server has more than one network interface, +a digit may be appended to the keywords +.BR ip , +.B ipgw +and +.B ipmask +to indicate the interface number; +zero is the default. +.SS "One-time actions" +.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 +.I Allow +turns off all permission checking; use with caution. +.PP +.I Readonly +disables all writing to all devices. +This is useful for trying dangerous experiments. +.PP +.I Noauth +disables authentication. +.PP +.I Noattach +prevents attachs. +.PP +.I Copyworm +will copy a file system named +.I main +to one named +.IR output , +block by block, +and loop. +It knows how to read a fake worm file system. +.PP +.I Copydev +will copy the device +.I from-dev +to the device +.IR to-dev . +block by block, +and panic. +.PP +.I Halt +will cause the server to +.I immediately +exit and reboot. +.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 +.PP +A complete and complex example: +initialize a file server +.I fsb +with a single SCSI disk on target 0 for a scratch file system, +a cached WORM file system with cache disk on target 2 and +an optical-disc jukebox on targets 4 (robotics) and 5 (one optical drive), +and another cached WORM file system with cache disk on target 3 +and another optical-disc jukebox on a second SCSI bus at targets 3 and 4. +Both jukeboxes contain 16 slots of optical discs. +It has two Ethernet interfaces and can reach an SNTP server on the first one. +.IP +.EX +service fsb +config w0 +filsys main cw2j(w4w5)(l<0-31>) +filsys dump o +filsys hp40fx cw3j(w1.<3-4>.0)(l<0-31>) +filsys hp40fxdump o +filsys other w0 +ipauth 0.0.0.0 +ipsntp 10.9.0.3 +ip0 10.9.0.2 +ipgw0 10.9.0.3 +ipmask0 255.255.0.0 +ip1 10.0.0.2 +ipgw1 10.0.0.1 +ipmask1 255.255.0.0 +ream main +ream hp40fx +ream other +end +.EE +.SH SOURCE +.BR /sys/src/fs/port/config.c +.SH "SEE ALSO +Ken Thompson, +``The Plan 9 File Server''. diff --git a/sys/man/8/fshalt b/sys/man/8/fshalt new file mode 100755 index 000000000..d01537830 --- /dev/null +++ b/sys/man/8/fshalt @@ -0,0 +1,48 @@ +.TH FSHALT 8 +.SH NAME +fshalt, reboot \- halt any local file systems and optionally reboot the system +.SH SYNOPSIS +.B fshalt +[ +.B -r +] +.br +.B reboot +.SH DESCRIPTION +.I Fshalt +syncs all local +.IR fossil (4), +.IR venti (8), +and +.IR kfs (4) +servers, +then halts all local +.IR fossil +and +.IR kfs +servers. +If given +.BR -r , +.I fshalt +will then reboot the machine. +The halting and rebooting is done by copying all necessary +commands into a +.IR ramfs (4) +file system and changing directory there before attempting to halt +file systems, +so this will work even on standalone machines with their roots on +local file systems. +.PP +.I Reboot +restarts the machine it is invoked on. +.SH SOURCE +.B /rc/bin/fshalt +.br +.B /rc/bin/reboot +.SH SEE ALSO +.IR cons (3), +.IR reboot (8) +.SH BUGS +On standalone machines, it will be impossible to do anything +after invoking bare +.LR fshalt . diff --git a/sys/man/8/getflags b/sys/man/8/getflags new file mode 100755 index 000000000..84ef31d3a --- /dev/null +++ b/sys/man/8/getflags @@ -0,0 +1,72 @@ +.TH GETFLAGS 8 +.SH NAME +getflags, usage \- command-line parsing for shell scripts +.SH SYNOPSIS +.B aux/getflags $* +.PP +.B aux/usage +.SH DESCRIPTION +.I Getflags +parses the options in its command-line arguments +according to the environment variable +.BR $flagfmt . +This variable should be a list of comma-separated options. +Each option can be a single letter, indicating that it does +not take arguments, or a letter followed by the space-separated +names of its arguments. +.I Getflags +prints an +.IR rc (1) +script on standard output which initializes the +environment variable +.BI $flag x +for every option mentioned in +.BR $flagfmt . +If the option is not present on the command-line, the script +sets that option's flag variable to an empty list. +Otherwise, the script sets that option's flag variable with +a list containing the option's arguments or, +if the option takes no arguments, +with the string +.BR 1 . +The script also sets the variable +.B $* +to the list of arguments following the options. +The final line in the script sets the +.B $status +variable, to the empty string on success +and to the string +.B usage +when there is an error parsing the command line. +.PP +.I Usage +prints a usage message to standard error. +It creates the message using +.BR $flagfmt , +as described above, +.BR $args , +which should contain the string to be printed explaining +non-option arguments, +and +.BR $0 , +the program name +(see +.IR rc (1)). +.SH EXAMPLE +Parse the arguments for +.IR leak (1): +.IP +.EX +flagfmt='b,s,f binary,r res,x width' +args='name | pid list' +if(! ifs=() eval `{aux/getflags $*} || ~ $#* 0){ + aux/usage + exit usage +} +.EE +.SH SOURCE +.B /sys/src/cmd/aux/getflags.c +.br +.B /sys/src/cmd/aux/usage.c +.SH SEE ALSO +.IR arg (2) diff --git a/sys/man/8/gpsfs b/sys/man/8/gpsfs new file mode 100755 index 000000000..d5498ca67 --- /dev/null +++ b/sys/man/8/gpsfs @@ -0,0 +1,269 @@ +.TH GPSFS 8 +.SH NAME +gpsfs, gpsevermore \- GPS time and position service +.SH SYNOPSIS +.B aux/gpsfs +[ +.B -d +.I device +] +[ +.B -b +.I baud +] +[ +.B -s +.I srvname +] +[ +.B -m +.I mntpt +] +.PP +.B aux/gpsevermore +[ +.B -d +.I device +] +[ +.B -b +.I baud +] +[ +.B -n +.I baud +] +[ +.B -l +.I location +] +.SH DESCRIPTION +.B Aux/gpsfs +reads an NMEA-compatible serial GPS (Global Positioning System) +device and provides time and position +through a file system, by default mounted on +.B /mnt +and implementing +.BR /mnt/gps . +.PP +It implements four files in the +.B gps +directory: +.BR position , +.BR time , +.BR satellites , +and +.BR raw . +.PP +The read-only +.B position +file contains one line of information in 9 tab-separated fields: +.TF "\fImagnetic deviation +.PD +.TP +.I "fix quality +0 means position data invalid, 1 means a 2D position is available, 2 means a 3D position is available. +The value is 8, 9, or 10, respectively, when the fix data comes from a file rather than an actual GPS. +.TP +.I "zulu time +universal coordinated time encoded as hhmmss followed by the character 'Z'. +.TP +.I "system time +time and date converted to the format of +.IR time (2). +.TP +.I longitude +in degrees, east of Greenwich is positive, west negative. +.TP +.I latitude +in degrees, positive is north, negative south of the equator. +.TP +.I altitude +above sea level, in meters. +.TP +.I course +degrees, clockwise from true north. +.TP +.I "ground speed +in km/h +.TP +.I "magnetic deviation +(not provided by all GPSs), in degrees, positive is westerly, negative easterly. +.PP +The read-only +.B time +file contains one line of information in 4 tab-separated fields: +.TF "\fIsystem time +.PD +.TP +.I "gps time +in +.IR time (2) +format. +.TP +.I "gps time +in +.I nsec +(see +.IR time (2)) +format (ms accuracy). +.TP +.I "system time +in +.I nsec +format. This is the system time at the time of the +.I "gps time +sample. The difference between this and the previous field is used in clock +synchronization. See +.IR timesync (8). +.TP +.I validity +the character +.B A +meaning sample valid and usable for clock synchronization. The other values are +not usable for clock sync: +.B B +means valid sample from file playback, +.B V +means invalid sample, and +.B W +means invalid playback sample. +.PP +The read-only +.B satellites +file contains information about the current satellite constellation. It consists +of one line of general information, followed by zero or more lines, one for each satellite in use. +The first line contains two fields: +.TF "\fIsatellites in view +.PD +.TP +.I "fix quality +same as in the +.B position +file. +.TP +.I "satellites in view +number of satellites above the horizon +.PP +Subsequent lines have four fields: +.TF "\fIelevation +.PD +.TP +.I prn +satellite ID +.TP +.I elevation +above the horizon, degrees. +.TP +.I azimuth +direction, degrees from true north +.TP +.I snr +Signal to noise ratio, 0 - 99 dB +.PP +The contents of these files are refreshed once per second when reading from an actual GPS, +and once per 100 ms (giving a speed up of a factor 10) when playing back from file. +.PP +The read-only +.B raw +file can be read to obtain a copy of the raw NMEA GPS output. +.I Gpsfs +keeps an internal buffer of 8KB, so the reader must keep up with the output +(typically 500 or so bytes per second). +.PP +The +.B \-d +flag establishes the device the GPS samples are read from. If the device file is not +a serial interface, +.I gpsfs +assumes playback from file and modifies quality parameters as such. +.PP +The +.B \-b +flag specifies the baud rate of the serial line. The standard baud rate for NMEA +GPS is 4800 baud, but many device allow changing to higher speeds. +.PP +The +.B \-s +flag specifies the name under which the +.I gpsfs +service is posted in +.BR /srv . +.PP +The +.B \-m +flag specifies a mount mount other than +.BR /mnt . +.SS Evermore +.B Aux/gpsevermore +is used to configure GPSs using an Evermore chipset. +.PP +The +.B \-d +flag specifies the serial device to the GPS. +.PP +The +.B \-b +flag specifies the baud rate of the serial line. The standard baud rate for NMEA +GPS is 4800 baud, but many device allow changing to higher speeds. +.PP +The +.B \-n +flag specifies the speed to set the GPS to. When the command finishes, the +GPS should be read (and configured) at the new speed. +.PP +The +.B \-l +flag is sued to specify the location to initialize the GPS to. The format is +.B dd:mm:ssX +or +.B dd:mm.mmmX +or +.BR dd.dddX , +where +.B dd +stands for degrees (one or more digits), +.B mm +for minutes and +.B ss +for seconds of arc. +.B X +is one of +.BR W , +.BR E , +.B N +or +.BR S . +Longitudes come with +.B W +or +.BR E , +latitudes with +.B N +or +.BR S . +The +.B \-l +flag is followed by two such fields, one for longitude, one for latitude. They may be +given in a single argument (separated by white space), or in two arguments, in either order. +Initialization time is taken from +.IR time (2). +.SH "SEE ALSO +.IR timesync (8), +.IR time (2) +.SH FILES +.TF /mnt/gps/satellites +.TP +.B /mnt/gps/position +position, time, speed and heading +.TP +.B /mnt/gps/satellites +satellites in view +.TP +.B /mnt/gps/time +GPS time (millisecond accuracy) +.TP +.B /dev/eia0 +default GPS device +.SH SOURCE +.B /sys/src/cmd/aux/gps diff --git a/sys/man/8/histogram b/sys/man/8/histogram new file mode 100755 index 000000000..5c06f7858 --- /dev/null +++ b/sys/man/8/histogram @@ -0,0 +1,90 @@ +.TH HISTOGRAM 8 +.SH NAME +histogram \- draw a histogram +.SH SYNOPSIS +.B histogram +[ +.B -h +] +[ +.B -c +.I index +] +[ +.B -r +.I minx,miny,maxx,maxy +] +[ +.B -s +.I scale +] +[ +.B -t +.I title +] +[ +.B -v +.I maxv +] +.SH DESCRIPTION +.I Histogram +reads numbers, one per line, from its standard input +and draws them as bars in a histogram. +.PP +Use +.B -c +to set the color +.I index +for the graph. +A modulus operation on the value keeps the color index within the available range. +.PP +Unless +.B -h +.RI ( hold ) +is given, +.I histogram +will exit when it reaches the end-of-file. +It will exit immediately if it is interrupted +or if the +.I exit +menu option is chosen. +.PP +.B -r +sets the initial window +.I rectangle +coordinates. +.PP +.B -s +sets the +.I scaling +factor. +.PP +.B -t +sets the +.I title +displayed on a line above the histogram. +The last value read is displayed to the right of the title. +.PP +.B -v +sets the maximum +.I value +that can be expected. +.SH EXAMPLE +Plot a sine wave: +.IP +.EX +hoc -e 'for(i=0.0;i<20*PI;i=i+0.1) print (10+10*sin(i)), "\\n"'| + histogram -t 'sin(t), 0 ≤ t ≤ 20π' -v 20 -h +.EE +.PP +Show the Dow Jones adjusted daily closing price back to January 1, 2000: +.IP +.EX +site=http://ichart.finance.yahoo.com +hget $site'/table.csv?s=^DJI&a=00&b=1&c=2000' | + awk -F, '{print $NF}' | histogram -t DJI -v 15000 -h +.EE +.SH SOURCE +.B /sys/src/cmd/histogram.c +.SH SEE ALSO +.IR statusbar (8) diff --git a/sys/man/8/httpd b/sys/man/8/httpd new file mode 100755 index 000000000..0933d7f1a --- /dev/null +++ b/sys/man/8/httpd @@ -0,0 +1,336 @@ +.TH HTTPD 8 +.SH NAME +httpd, save, imagemap, man2html, webls \- HTTP server +.SH SYNOPSIS +.B ip/httpd/httpd +.RB [ -a +.IR srvaddr ] +.RB [ -c +.I cert +.RB [ -C +.IR certchain ]] +.RB [ -d +.IR domain ] +.RB [ -n +.IR namespace ] +.RB [ -w +.IR webroot ] +.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 ] +.br +.B ip/httpd/imagemap +.I ... +.br +.B ip/httpd/man2html +.I ... +.br +.B ip/httpd/webls +.I ... +.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. +If an X.509 certificate is supplied with the +.B -c +option, then the service is instead +.BR tcp!*!https . +There should already be a factotum +holding the corresponding private key. +If the specified certificate has been signed +by a certificate authority, the +.B -C +option may be used to specify a file +containing a chain of signed certificates. +.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 +.BR application/octet-stream ) +and Content-encoding +(default +.BR binary ) +of a file are determined by looking for suffixes of the file name in +.BR /sys/lib/mimetype . +.SS Redirection +.PP +Each requested URI is looked up in a redirection table, read from +.BR /sys/lib/httpd.rewrite . +Fields are separated by spaces and tabs. +Anything following a +.L # +is ignored. +The first field of each line is a URI; +the second a replacement path. +If a prefix of the URI matches a redirection path, +the URI is rewritten using the corresponding replacement path +instead of the prefix, +and a temporary 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. +The prefix can either be a domain root like +.B http://system/ +(which matches that URL only) +or a path like +.B /who/rob +(which matches that path no matter what +the requested server), +but not both: +.B http://system/who/rob +will never match a request. +If the first field ends in a slash, this is an exact match; +otherwise it is a prefix match. +The first field is a literal string, matched against +each file prefix of each URL. +The most specific, i.e., longest, +pattern wins, and is applied once (there is no rescanning), +except for the following exceptions. +.I Httpd +matches only the prefix and not subordinate pages +if a replacement is prefixed with +.LR > . +.I Httpd +omits the unmatched part of the original URI +from the rewritten URI if the replacement is prefixed with +.LR * . +This permits many-to-one mappings; for example, +to send all references to an old subtree to a single error page. +.PP +.I Httpd +handles replacements prefixed with +.L @ +internally, +treating the request as if it were for the replacement +(without the +.BR @ ) +but not informing the client of the rewritten name. +Replacement URLs prefixed with +.L = +generate a permanent redirection instead of a temporary one. +.I Httpd +checks to see if this file has changed once every 50 new TCP connections. +HTTP 1.1 persistent connection implies many pages +may come in one browser connection, so to kick-start +.IR httpd , +try +.IP +.EX +for(i in `{seq 50}) hget http://www.your-domain.com/ >/dev/null +.EE +.SS "Access Control" +.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 matching 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. +.br +.ne 3 +.SS "Auxiliaries (magic)" +.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. +All the auxiliaries take the same arguments. +.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 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 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. +.PP +.I Webls +produces directory listings on the fly, with +output in the style of +.IR ls (1). +.B /sys/lib/webls.allowed +and +.B /sys/lib/webls.denied +contain regular expressions describing +what parts of +.I httpd's +namespace may and may not be listed, respectively. +.B Webls.denied +is first searched to see if access is by default +denied. If so +.B webls.allowed +is then searched to see if access is explicitly allowed. +Thus one can have very general expressions in the +denied list (like +.BR .* ), +yet still allow exceptions. If +.B webls.denied +does not exist or is unreadable, +all accesses are assumed to be denied unless +explicitly allowed in +.B webls.allowed. +.PP +Other sites will note that if neither +.B webls.denied +nor +.B webls.allowed +exist, any portion of +.I httpd's +namespace can be listed (however, +.I webls +will always endeavor to prevent listing of `.' and `..'). +If +.B webls.allowed +exists but +.B webls.denied +does not, any directory to be listed must be described +by a regular expression in +.BR webls.allowed . +Similarly, if +.B webls.denied +exists but +.B webls.allowed +does not, any directory to be listed must +.I not +be described by a regular expression in +.BR webls.denied . +If both exist, a directory is listable if either +it doesn't appear in +.BR webls.denied , +or it appears in both +.B webls.denied +and +.BR webls.allowed . +In other words, +.B webls.allowed +overrides +.BR webls.denied . +If a listing for a directory is requested and access +is denied, or another error occurs, a simple error +page is returned. +.SH EXAMPLES +These are all examples of how to use +.BR httpd.rewrite . +.PP +A local redirection: +.RS +.EX +/netlib/c++/idioms/index.html.Z /netlib/c++/idioms/index.html +.EE +.RE +.PP +Redirection to another site: +.RS +.EX +/netlib/lapack/lawns =http://netlib.org/lapack/lawns +http://inferno.bell-labs.com =http://www.vitanuova.com +.EE +.RE +.PP +Root directory for virtual host: +.RS +.EX +http://www.ampl.com /cm/cs/what/ampl +.EE +.RE +.SH FILES +.TF /sys/lib/httpd.rewrite +.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 +.TP +.B /sys/lib/webls.allowed +regular expressions describing explicitly listable pathnames; overrides +.B webls.denied +.TP +.B /sys/lib/webls.denied +regular expressions describing explicitly unlistable pathnames +.SH SOURCE +.B /sys/src/cmd/ip/httpd +.SH "SEE ALSO" +.I newns +in +.IR auth (2), +.IR listen (8), +.IR rsa (8) diff --git a/sys/man/8/init b/sys/man/8/init new file mode 100755 index 000000000..94c3a4654 --- /dev/null +++ b/sys/man/8/init @@ -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/sys/man/8/ipconfig b/sys/man/8/ipconfig new file mode 100755 index 000000000..5028455f1 --- /dev/null +++ b/sys/man/8/ipconfig @@ -0,0 +1,395 @@ +.TH IPCONFIG 8 +.SH NAME +ipconfig, rip, linklocal, ipv6on \- Internet configuration and routing +.SH SYNOPSIS +.in +0.25i +.ti -0.25i +.B ip/ipconfig +.RB [ -6DGNOPdnpruX ] +.RB [ -b +.IR baud ] +.RB [ -c +.IR ctl ] +.RB [ -g +.IR gateway ] +.RB [ -h +.IR host ] +.RB [ -m +.IR mtu ] +.RB [ -o +.IR dhcp-opt ] +.RB [ -x +.IR netmtpt ] +[ +.I type +[ +.I device +]\|] +.RI [ verb ] +[ +.I local +[ +.I mask +[ +.I remote +[ +.I file-server +[ +.I auth +]\|]\|]\|]\|] +.PP +.B ip/rip +.RB [ -bdr ] +.RB [ -x +.IR netmtpt ] +.PP +.B ip/linklocal +[ +.B -t +.I gwipv4 +] +.I mac +\&... +.PP +.B ipv6on +[ +.I netmtpt +.I ndbfile +[ +.I gwv4 +]\|] +.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 and optionally +a mask, a remote address, a file server and an authentication server 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 non-loopback +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 gbe , +.BR ppp , +.BR pkt , +or +.BR loopback . +The +.B gbe +type is equivalent to +.B ether +except that it allows jumbo packets (up to ~9KB). +The +.B pkt +interface passes all IP packets to and from a user program. +For +.B ppp +the device can be any byte stream device. +.PP +The verb (default +.IR add ) +determines the action performed. The usual verbs are: +.TF remove +.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. +.PD +.PP +The IPv6-specific verbs, which take different arguments, are: +.TP +.BI "add6 " "prefix pfx-len onlink auto validlt preflt" +sets the named IPv6 parameters; see +.IR ip (3) +for more detail. +.TP +.BI "ra6 " "[ keyword value ] ..." +sets IPv6 router advertisement parameter +.IR keyword 's +.IR value . +See +.IR ip (3) +for more detail. +Setting +.I recvra +non-zero also forks a process to +receive and process router advertisements. +Setting +.I sendra +non-zero also +enables IP routing on the interface, +forks a process to send router advertisements, +and if no +.I recvra +process is running, forks one. +.PD +.PP +The options are: +.TF M +.PD +.TP +.B 6 +if adding an address (the default action), +add the IPv6 link-local address. +.TP +.B b +the baud rate to use on a serial line +when configuring +.BR PPP . +.TP +.B c +write the control string +.I ctl +to the ethernet device control file before starting to configure it. +May be repeated to specify multiple control writes. +.TP +.B d +use DHCP to determine any unspecified configuration parameters. +.TP +.B D +turn on debugging. +.TP +.B g +the default gateway. +.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 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 m +the maximum IP packet size to use on this interface. +.TP +.B n +determine parameters but don't configure the interface. +.TP +.B N +look in +.B /lib/ndb +for the IP parameters. This only works if the +interface is an ethernet. It uses the ethernet address to find +a matching entry. +.TP +.B O +addresses specified on the command line override those obtained via DHCP. +A command line address of 0 implies no override. +.TP +.B p +write configuration information to +.BR /net/ndb , +even if other network interfaces are already configured +.TP +.B P +do not write configuration information to +.BR /net/ndb , +even if this is the first network interface to be configured +.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 u +disable IPv6 duplicate discovery detection, +which removes any existing ARP table entry for one of our IPv6 addresses +before adding new ones. +.TP +.B x +use the IP stack mounted at +.I netmtpt +instead of at +.BR /net . +.TP +.B X +don't fork a process to keep the DHCP lease alive. +.TP +.B o +adds +.I dhcpoption +to the list of paramters requested of the DHCP server. The +result will appear in +.B /net/ndb +should this be the first interface. The known options are: +.RS +.LP +.ft L +arptimeout, baddr, bflen, bootfile, clientid, cookie, discovermask, +discoverrouter, dns, dom, dumpfile, etherencap, extpath, finger, +homeagent, impress, ipaddr, ipforward, ipgw, ipmask, irc, lease, log, +lpr, maxdatagram, maxmsg, message, mtu, name, netbiosdds, netbiosns, +netbiosscope, netbiostype, ni, nisdomain, nisplus, nisplusdomain, +nntp, nonlocal, ntp, overload, params, pathplateau, pathtimeout, +policyfilter, pop3, rebindingtime, renewaltime, rl, rootpath, rs, +serverid, smtp, st, staticroutes, stdar, subnetslocal, supplymask, +swap, sys, tcpka, tcpkag, tcpttl, tftp, time, timeoff, trailerencap, +ttl, type, vendorclass, www, xdispmanager, xfont +.RE +.IP +The options +.BR ipmask , +.BR ipgw , +.BR dns , +.BR sys , +and +.B ntp +are always requested. +.TF M +.PD +.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: +.TF M +.PD +.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 +.I Linklocal +prints the IPv6 link-local address corresponding to the given +.I mac +address. +Given +.BR -t , +.I linklocal +instead prints the +.I 6to4 +EUI-64-based IPv6 address corresponding to +.I mac +and +.I 6to4 +gateway +.IR gwipv4 . +.PP +.I Ipv6on +uses the network database at +.I ndbfile +to configure the network mounted on +.I netmtpt +with a link-local address (derived from its MAC address) +and attempts to add a default IPv6 route to the local +IPv4 gateway's IPv6 address. +If +.I gwv4 +is supplied, it will be used as the gateway IPv4 address. +.SH EXAMPLES +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 Bell Labs, 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 +.EE +.PP +Get all addresses via DHCP. +Configure the IPv6 link-local address automatically +and listen for router announcements. +.IP +.EX +ip/ipconfig -6 +ip/ipconfig ra6 recvra 1 +.EE +.SH FILES +.B /sys/log/v6routeradv +.SH SOURCE +.B /sys/src/cmd/ip/ipconfig +.br +.B /sys/src/cmd/ip/rip.c +.br +.B /sys/src/cmd/ip/linklocal.c +.br +.B /rc/bin/ipv6on +.SH "SEE ALSO" +.IR ether (3), +.IR ip (3), +.IR loopback (3), +.IR ndb (6), +.IR 6in4 (8), +.IR dhcpd (8), +.IR ppp (8) +.br +.B /lib/rfc/rfc2373 +for IPv6's modified EUI-64 diff --git a/sys/man/8/ipserv b/sys/man/8/ipserv new file mode 100755 index 000000000..45889e21d --- /dev/null +++ b/sys/man/8/ipserv @@ -0,0 +1,195 @@ +.TH IPSERV 8 +.SH NAME +telnetd, rlogind, rexexec, ftpd \- Internet remote access daemons +.SH SYNOPSIS +.B ip/telnetd +.RB [ -adnptN ] +.RB [ -u +.IR user ] +.PP +.B ip/rlogind +.PP +.B ip/rexexec +.PP +.B ip/ftpd +.RB [ -aAde ] +.RB [ -n +.IR namepace-file ] +.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 anonymo +.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 +.IR Telnetd 's +options are: +.TP 4 +.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 anonymo +.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 +.IR Ftpd 's +options are: +.TP 4 +.B a +allow anonymous access +.TP +.B A +allow +.I only +anonymous access +.TP +.B d +write debugging output to standard error +.TP +.B e +treat any user as anonymous +.TP +.B n +the namespace for anonymous users (default +.BR /lib/namespace.ftp ) +.PP +To preserve intended protections in shared file trees, +any directory containing a file +.I .httplogin +is locked by +.IR ftpd; +see +.IR httpd (8). +.PP +.SH FILES +.B /lib/namepace +.br +.BI /usr/ username /lib/namespace.ftp +.br +.B /lib/namespace.world +.br +.B /lib/namespace.ftp +.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 +.SH "SEE ALSO" +.IR ftpfs (4), +.IR pop3 (8) diff --git a/sys/man/8/kfscmd b/sys/man/8/kfscmd new file mode 100755 index 000000000..4580c52b8 --- /dev/null +++ b/sys/man/8/kfscmd @@ -0,0 +1,221 @@ +.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 +.B nowritegroup +Each time +.I kfs +rereads +.BR /adm/users , +it looks for a group named +.BR write . +If such a group exists, then the entire file system +will appear read-only to users not in the group. +If a write group exists but no one is in it, +it will be impossible to edit +.B /adm/users +to correct the problem. +To resolve this, the +.B nowritegroup +command turns off write group checking until the next +time +.B /adm/users +is reread. +.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 [cdfpPqrtw] +Check the file system and print summary information. +The options are +.PD 0 +.RS +.TP +.B c +fix bad tags and clear the contents of the block. +.TP +.B d +delete redundant references to a block, fix bad UTF filenames. +.TP +.B f +rebuild the list of free blocks. +.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 q +quiet mode: report errors, but suppress summary information +.TP +.B r +read all of the data blocks and check the tags. +.TP +.B t +fix bad tags. +.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 tcp!*!564 . +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/sys/man/8/listen b/sys/man/8/listen new file mode 100755 index 000000000..3406f3a48 --- /dev/null +++ b/sys/man/8/listen @@ -0,0 +1,238 @@ +.TH LISTEN 8 +.SH NAME +listen, listen1, tcp7, tcp9, tcp19, tcp21, tcp22, tcp23, tcp25, tcp53, tcp110, tcp113, tcp143, tcp513, tcp515, tcp564, tcp565, tcp566, tcp567, tcp993, tcp995, tcp1723, tcp17007, tcp17008, tcp17009, tcp17010, tcp17013 \- listen for calls on a network device +.SH SYNOPSIS +.B aux/listen +.RB [ -iq ] +.RB [ -d +.IR srvdir ] +.RB [ -t +.IR trustsrvdir ] +.RB [ -n +.IR namespace ] +.RI [ net ] +.PP +.B aux/listen1 +[ +.B -tv +] +.I addr +.I cmd +[ +.I args... +] +.SH DESCRIPTION +.I listen +listens on a network for inbound calls to local services. +.I Net +is the network protocol on which to listen, by default +.BR /net/tcp . +The services available are executable, non-empty 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 +are executed as the user who started +.IR listen . +When changing user to +.BR none , +a new namespace is created, +usually by executing +.BR /lib/namespace , +but +.B -n +selects an alternate +.IR namespace . +Option +.B -q +suppresses affirmative log information. +Option +.B -i +suppresses the periodic scan of the service directories for changes. +.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 +At least the following services are available in +.BR /bin/service . +.TF \ tcp0000 +.TP +.B tcp564 +serve a piece of the name space using the Plan 9 file system protocol, +with authentication via +.I Tauth +(in +.IR attach (5)), +no encryption, +and multiplex multiple users on a single connection +(used by +.IR srv (4), +and also by Unix systems to see Plan 9 files). +.TP +.B tcp17007 +serve a piece of the name space using the Plan 9 file system protocol, +with authentication at the start, +optional SSL encryption, +and no multiplexing of users +(typically used by +.IR cpu (1) +and +.IR import (4)). +Not usable by user +.IR none . +.TP +.B tcp17008 +like +.BR tcp17007 , +but serves the root of the tree, +forgoing the negotiation for which subtree to serve. +.TP +.B tcp17009 +.I rx +remote execution. +.TP +.B tcp17010 +server for +.IR cpu (1) +command. +.TP +.B tcp17013 +server for old +.IR cpu (1) +command for compatibility with old clients. +.TP +.B tcp7 +echo any bytes received (bit mirror) +.TP +.B tcp9 +consume any bytes received (bit bucket) +.TP +.B tcp19 +.B chargen +service. +.TP +.B tcp21 +FTP daemon +.TP +.B tcp22 +.IR ssh (1) +`secure shell' encrypted terminal connection or file transfer. +.TP +.B tcp23 +.B telnet +terminal connection. +.TP +.B tcp25 +mail delivery. +.TP +.B tcp53 +TCP port for DNS. +.TP +.B tcp110 +POP3 port. +.TP +.B tcp113 +.B Ident +port (always reports +.BR none ). +.TP +.B tcp143 +IMAP4rev1 port. +.TP +.B tcp513 +.B rlogin +terminal connection. +.TP +.B tcp515 +LP daemon; see +.IR lp (8). +.TP +.B tcp565 +report the address of the incoming call. +.TP +.B tcp993 +Secure IMAP4rev1 port. +.TP +.B tcp995 +Secure POP3 port. +.TP +.B tcp1723 +PPTP (point-to-point tunnelling protocol) service. +.PD +.PP +At least the following services are available in +.BR /bin/service.auth , +the usual +.IR trustsrvdir . +.TF \ tcp0000 +.TP +.B tcp566 +validate a SecureNet box. +.TP +.B tcp567 +Plan 9 authentication-ticket service. +.PD +.PP +.I Listen1 +is a lightweight listener intended for personal use, +modeled from Inferno's +.\" write out this way so automatic programs +.\" don't try to make it into a real man page reference. +\fIlisten\fR(1). +announces on +.IR address , +running +.I cmd +.I args... +for each incoming connection; +the network directory is passed in the environment +as +.BR $net . +Option +.B -t +causes +.I listen1 +to run as the invoking user; the default +is to become +.B none +before listening. +Option +.B -v +causes verbose logging on standard output. +See +.B /rc/bin/tlssrvtunnel +for an example. +.SH FILES +.TF /env/sysname +.TP +.B /net/tcp +by convention, TCP device bind point +.SH SOURCE +.B /sys/src/cmd/aux/listen*.c +.br +.B /rc/bin/service* +.SH "SEE ALSO" +.IR authsrv (6), +.IR dial (2) +.SH BUGS +.IR Srvdir , +.IR trustsrvdir +and +.I namespace +must all be absolute path names. diff --git a/sys/man/8/lp b/sys/man/8/lp new file mode 100755 index 000000000..cb74f92e1 --- /dev/null +++ b/sys/man/8/lp @@ -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 \fIp9bitpos\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/sys/man/8/mk9660 b/sys/man/8/mk9660 new file mode 100755 index 000000000..543fdd7e9 --- /dev/null +++ b/sys/man/8/mk9660 @@ -0,0 +1,245 @@ +.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 -B +.I bootfile +] +[ +.B -p +.I proto +] +[ +.B -s +src +] +[ +.B -v +volume +] +.I image +.PP +.B disk/dump9660 +[ +.B -:D +] +[ +.B -9cjr +] +[ +.B -p +.I proto +] +[ +.B -s +src +] +[ +.B -v +volume +] +[ +.B -m +.I maxsize +] +[ +.B -n +.I now +] +.I image +.SH DESCRIPTION +.I Mk9660 +writes to the random access file +.I image +an ISO-9660 CD image containing the +files named in +.I proto +(by default, +.BR /sys/lib/sysconfig/proto/portproto ) +from the file tree +.I src +(by default, +the current directory). +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 +also added. +This second tree can contain long Unicode file names, +and can be read by +.I 9660srv +as well as most versions of Windows +and many Unix clones. +The characters +.BR * , +.BR : , +.BR ; , +.BR ? , +and +.B \e +are allowed in Plan 9 file names but not in Joliet file names; +non-conforming file names are translated +and a +.B _CONFORM.MAP +file written +as in the case of the +.B -c +option. +.PP +If the +.B -r +flag is given, Rock Ridge extensions are written in the +format of the system use sharing protocol; +this format provides Posix-style file metadata and is +common on Unix platforms. +.PP +The options +.BR -c , +.BR -9 , +.BR -j , +and +.B -r +may be mixed freely with the exception that +.B -9 +and +.B -r +are mutually exclusive. +.PP +The +.B -v +flag sets the volume title; +if unspecified, the base name of +.I proto +is used. +.PP +The +.B -: +flag causes +.B mk9660 +to replace colons in scanned file names with spaces; +this is the inverse of the map applied by +.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 +option just creates a pointer to it. +.PP +The +.B -B +option is similar to +.B -b +but the created CD image is marked as having a non-floppy-emulation +boot block. +This gives the program in the boot block full (ATA) LBA access +to the CD filesystem, not just the initial blocks that would fit on a floppy. +.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 /sys/src \e + -p /sys/lib/sysconfig/proto/allproto 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/sys/man/8/mkflashfs b/sys/man/8/mkflashfs new file mode 100755 index 000000000..b867932e7 --- /dev/null +++ b/sys/man/8/mkflashfs @@ -0,0 +1,39 @@ +.TH MKFLASHFS 8 +.SH NAME +mkflashfs \- make a journalling file system for flash memory +.SH SYNOPSIS +.B aux/mkflashfs +[ +.B -n +.I nsect +] [ +.B -z +.I sectsize +] +.I file +.SH DESCRIPTION +.I Mkflashfs +creates an empty journalling file system in +.IR file , +typically +.BR /dev/flash/flash . +.PP +The files and directory structure are divided into +.I sectsize +(default +.BR 4096 ) +byte blocks. +Larger blocks make large files more compact but take longer to access. +Supplying the +.B -n +option forces +.I file +to contain exactly +.I nsect +sectors. +.SH SOURCE +.B /sys/src/cmd/aux/flashfs/mkflashfs.c +.SH "SEE ALSO" +.IR flashfs (4), +.IR paqfs (4), +.IR sacfs (4) diff --git a/sys/man/8/mkfs b/sys/man/8/mkfs new file mode 100755 index 000000000..7079e50a8 --- /dev/null +++ b/sys/man/8/mkfs @@ -0,0 +1,191 @@ +.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 ] +.RB [ -T ] +.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 . +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 options are: +.TP +.B d +specifies a directory (default +.BR / ) +to serve as the root of the unpacked file system. +.TP +.B u +sets the owners of the files created to correspond to +those in the archive and restores the modification times of the files. +.TP +.B T +restores only the modification times of the files. +.TP +.B v +prints the names and sizes of files as they are extracted. +.TP +.B h +prints headers for the files on standard output +instead of unpacking the files. +.PD +.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 newfs +mount -c /srv/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), +.IR tar (1) diff --git a/sys/man/8/mkpaqfs b/sys/man/8/mkpaqfs new file mode 100755 index 000000000..c9d8b391c --- /dev/null +++ b/sys/man/8/mkpaqfs @@ -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 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/sys/man/8/mksacfs b/sys/man/8/mksacfs new file mode 100755 index 000000000..fbeb11c2a --- /dev/null +++ b/sys/man/8/mksacfs @@ -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/sys/man/8/mouse b/sys/man/8/mouse new file mode 100755 index 000000000..a3bb52eaf --- /dev/null +++ b/sys/man/8/mouse @@ -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/sys/man/8/na b/sys/man/8/na new file mode 100755 index 000000000..eb0a111ef --- /dev/null +++ b/sys/man/8/na @@ -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/sys/man/8/ndb b/sys/man/8/ndb new file mode 100755 index 000000000..699f98ca2 --- /dev/null +++ b/sys/man/8/ndb @@ -0,0 +1,793 @@ +.TH NDB 8 +.SH NAME +query, ipquery, mkhash, mkdb, mkhosts, cs, csquery, dns, dnstcp, dnsquery, dnsdebug, inform \- network database +.SH SYNOPSIS +.B ndb/query +[ +.B -am +] [ +.B -f +.I dbfile +] +.I "attr value" +[ +.I rattr +.\" [ +.\" .I reps +.\" ] +] +.br +.B ndb/ipquery +.I "attr value" +.I rattr... +.br +.B ndb/mkhash +.I "file attr" +.br +.B ndb/mkdb +.br +.B ndb/mkhosts +[ +.I domain +[ +.I dbfile +] ] +.br +.B ndb/cs +[ +.B -4n +] [ +.B -f +.I dbfile +] [ +.B -x +.I netmtpt +] +.br +.B ndb/csquery +[ +.B -s +] +[ +.I server +[ +.I addr... +] +] +.br +.B ndb/dns +[ +.B -norRs +] [ +.B -a +.I maxage +] [ +.B -f +.I dbfile +] [ +.B -N +.I target +] [ +.B -x +.I netmtpt +] [ +.B -z +.I program +] +.br +.B ndb/dnstcp +[ +.B -rR +] [ +.B -f +.I dbfile +] [ +.B -x +.I netmtpt +] [ +.I conn-dir +] +.br +.B ndb/dnsquery +.br +.B ndb/dnsdebug +[ +.B -rx +] [ +.B -f +.I dbfile +] [ [ +.BI @ server +] +.I domain-name +[ +.I type +] ] +.br +.B ndb/inform +[ +.B -x +.I netmtpt +] +.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 +.I dbfile +.RB ( /lib/ndb/local +by default) +for an attribute of type +.I attr +and value +.IR value . +If +.I rattr +is not specified, all entries matched by the search are printed. +If +.I rattr +is specified, the value of the first pair with attribute +.I rattr +of all the matched entries normally is printed. +Under +.B -m +and +.IR rattr , +the values of all pairs with a +.I rattr +attribute within the first matching entry are printed. +Under +.B -a +and +.IR rattr , +all values of pairs with a +.I rattr +attribute within all entries are printed. +.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/inform +sends an RFC2136 DNS +.I inform +packet to a nameserver to associate the host's IPv4 address with its DNS name. +This is required if the domain's nameserver is +a Microsoft Windows Active Directory controller. +.SS "Database maintenance" +.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/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 . +.SS "Connection service" +.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: +.TF -n +.TP +.B -4 +Only look up IPv4 addresses (A records) when consulting DNS. +The default is to also look up v6 addresses (AAAA records). +Writing +.L ipv6 +to +.B /net/cs +will toggle IP v6 look-ups. +.TP +.B -f +supplies the name of the data base file to use, +default +.BR /lib/ndb/local . +.TP +.B -n +causes cs to do nothing but set the system name. +.TP +.B -x +specifies the mount point of the +network. +.PD +.PP +.I Ndb/csquery +queries +.I ndb/cs +to see how it resolves addresses. +.I Ndb/csquery +prompts for addresses and prints 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. +.br +.ne 4 +.SS "Domain name service" +.I Ndb/dns +serves +.I ndb/cs +and remote systems by translating Internet domain names. +.I Ndb/dns +is started at boot time. +By default +.I dns +serves only requests written to +.BR /net/dns . +Programs must +.I seek +to offset 0 before reading or writing +.B /net/dns +or +.BR /net/cs . +The options are: +.TF -n +.TP +.B -a +sets the maximum time in seconds that an unreferenced +domain name will remain cached. +The default is one hour (3600). +.TP +.B -f +supplies the name of the data base file to use, +default +.BR /lib/ndb/local . +.TP +.B -n +whenever a DNS zone that we serve changes, send UDP NOTIFY +messages to any dns slaves for that zone +(see the +.L dnsslave +attribute below). +.TP +.B -N +sets the goal for the number of domain names cached to +.I target +rather than the default of 8,000. +.TP +.B -o +used with +.BR -s , +.B -o +causes +.I dns +to assume that it straddles inside and outside networks +and that the outside network is mounted on +.BR /net.alt . +Queries for inside addresses will be sent via +.B /net/udp +(or +.B /net/tcp +in response to truncated replies) +and those for outside addresses via +.B /net.alt/udp +(or +.BR /net.alt/tcp ). +This makes +.I dns +suitable for serving non-Plan-9 systems in an organization with +firewalls, DNS proxies, etc., +particularly if they don't work very well. +See `Straddling Server' below for details. +.TP +.B -r +act as a resolver only: +send `recursive' queries, asking the other servers +to complete lookups. +If present, +.B /env/DNSSERVER +must be a space-separated list of such DNS servers' IP addresses, +otherwise optional +.IR ndb (6) +.B dns +attributes name DNS servers to forward queries to. +.TP +.B -R +ignore the `recursive' bit on incoming requests. +Do not complete lookups on behalf of remote systems. +.TP +.B -s +also answer domain requests sent to UDP port 53. +.TP +.B -x +specifies the mount point of the +network. +.TP +.B -z +whenever we receive a UDP NOTIFY message, run +.I program +with the domain name of the area as its argument. +.PD +.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 +will resolve requests for systems on the network +.IR mh-net : +.IP +.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 +.LP +The server for a domain is indicated by a database entry containing +both a +.I dom +and a +.I ns +attribute. +.IP +.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 +.LP +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. +.SS "Authoritative Name Servers" +You can also serve a subtree of the domain name space from the local +database. You indicate subtrees that you would like to serve by adding an +.B soa= +attribute to the root entry. +For example, the Bell Labs CS research domain is: +.IP +.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 + dnsslave=nslocum.cs.bell-labs.com + dnsslave=vex.cs.bell-labs.com +.EE +.LP +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. +The +.B dnsslave +entries specify slave DNS servers that should be notified +when the domain changes. The notification also requires +the +.B -n +flag. +. +.SS "Reverse Domains" +You can also serve reverse lookups (returning the name that +goes with an IP address) by adding an +.B soa= +attribute to the entry defining the root of the reverse space. +.PP +For example, to provide reverse lookup for all addresses in +starting with +.L 135.104 +or +.LR fd00:: , +.I ndb +must contain a record like: +.IP +.EX +dom=104.135.in-addr.arpa soa= + dom=d.f.ip6.arpa soa= # special case, rfc 4193 + refresh=3600 ttl=3600 + ns=plan9.bell-labs.com + ns=ns1.cs.bell-labs.com + ns=ns2.cs.bell-labs.com +.EE +.LP +Notice the form of the reverse address. +For IPv4, it's the bytes of the address range you are serving reversed +and expressed in decimal, and with +.L .in-addr.arpa +appended. +For IPv6, it's the nibbles (4-bit fields) of the address range you are serving +reversed and expressed in hexadecimal, and with +.L .ip6.arpa +appended. +These are the standard forms for a domain name in a PTR record. +.PP +If such an +.B soa +entry exists in the database, reverse addresses will +automatically be generated from any IP addresses in the database +that are under this root. For example +.IP +.EX +dom=ns1.cs.bell-labs.com ip=135.104.1.11 +.EE +.LP +will automatically create both forward and reverse entries for +.BR ns1.cs.bell-labs.com . +Unlike other DNS servers, there's no way to generate +inconsistent forward and reverse entries. +.SS "Classless reverse delegation" +Following RFC 2317, it is possible to serve reverse DNS data +for IPv4 subnets smaller than /24. +Declare the non-/24 subnet, the reverse domain and the individual systems. +.PP +For example, +this is how to serve RFC-2317 +.B ptr +records for the subnet +.LR 65.14.39.128/123 . +.IP +.EX +ipnet=our-t1 ip=65.14.39.128 ipmask=/123 +dom=128.39.14.65.in-addr.arpa soa= + refresh=3600 ttl=3600 + ns=ns1.our-domain.com + ns=ns2.our-domain.com +ip=65.14.39.129 dom=router.our-domain.com +.EE +. +.SS "Delegating Name Service Authority" +Delegation of a further subtree to another set of name servers +is indicated by an +.B soa=delegated +attribute. +.IP +.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 +.LP +Nameservers within the delegated domain (as in this example) +must have their IP addresses listed elsewhere in +.I ndb +files. +. +.SS "Wildcards, MX and CNAME records" +Wild-carded domain names can also be used. +For example, to specify a mail forwarder for all Bell Labs research systems: +.IP +.EX +dom=*.research.bell-labs.com + mx=research.bell-labs.com +.EE +.LP +`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. +.IP +.EX +cname=anna.cs.bell-labs.com dom=www.cs.bell-labs.com +.EE +.PP +makes +.BI www. ... +a synonym for the canonical name +.BI anna. ... . +.SS "Straddling Server" +Many companies have an inside network +protected from outside access with firewalls. +They usually provide internal `root' DNS servers +(of varying reliability and correctness) +that serve internal domains and pass on DNS queries for +outside domains to the outside, relaying the results +back and caching them for future use. +Some companies don't even let DNS queries nor replies through +their firewalls at all, in either direction. +.PP +In such a situation, running +.B "dns -so" +on a machine that imports access to the outside network via +.B /net.alt +from a machine that straddles the firewalls, +or that straddles the firewalls itself, +will let internal machines query such a machine +and receive answers from outside nameservers for outside addresses +and inside nameservers for inside addresses, giving the appearance +of a unified domain name space, +while bypassing the corporate DNS proxies or firewalls. +This is different from running +.B "dns -s" +and +.B "dns -sRx /net.alt -f /lib/ndb/external" +on the same machine, +which keeps the inside and outside namespaces entirely separate. +.PP +Under +.BR -o , +several +.I sys +names are significant: +.BR inside-dom , +.BR inside-ns , +and +.BR outside-ns . +.I Inside-dom +should contain a series of +.B dom +pairs naming domains internal to the organization. +.I Inside-ns +should contain a series of +.B ip +pairs naming the internal DNS `root' servers. +.I Outside-ns +should contain a series of +.B ip +pairs naming the external DNS servers to consult. +.SS "Zone Transfers and TCP" +.I Dnstcp +is invoked, +usually from +.BR /rc/bin/service/tcp53 , +to answer DNS queries with long answers via TCP, +notably to transfer a zone within the database +.I dbfile +(default +.BR /lib/ndb/local ) +to its invoker on the network at +.I netmtpt +(default +.BR /net ). +Standard input will be read for DNS requests and the DNS answers +will appear on standard output. +Recursion is disabled by +.BR -R ; +acting as a pure resolver is enabled by +.BR -r . +If +.I conn-dir +is provided, it is assumed to be a directory within +.IB netmtpt /tcp +and is used to find the caller's address. +.SS "DNS Queries and Debugging" +.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 ipv6 , +.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 +if necessary. +.PP +.I Ndb/dnsdebug +is like +.I ndb/dnsquery +but bypasses the local server. +It communicates via UDP (and sometimes TCP) 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 -f +option supplies the name of the data base file to use. +The +.B -r +option is the same as for +.IR ndb/dns . +The +.B -x +option directs +.I dnsdebug +to use the +.B /net.alt +interface and +.B /lib/ndb/external +database file. +.SH EXAMPLES +Look up +.B helix +in +.IR ndb . +.IP +.EX +% ndb/query sys helix +sys=helix dom=helix.research.bell-labs.com bootf=/mips/9powerboot + ip=135.104.117.31 ether=080069020427 +.EE +.br +.ne 8 +.LP +Look up +.B plan9.bell-labs.com +and its IP address in the DNS. +.IP +.EX +% 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 +.LP +Print the names of all systems that boot via PXE. +.IP +.EX +% ndb/query -a bootf /386/9pxeload sys +.EE +.SH FILES +.TF /lib/ndb/local.*xxx +.TP +.B /env/DNSSERVER +resolver's DNS servers' IP addresses. +.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) +.SH BUGS +.I Ndb +databases are case-sensitive; +ethernet addresses must be in lower-case hexadecimal. diff --git a/sys/man/8/newuser b/sys/man/8/newuser new file mode 100755 index 000000000..07d3d8548 --- /dev/null +++ b/sys/man/8/newuser @@ -0,0 +1,118 @@ +.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 to +.B /adm/users +by running the +.I uname +command on the console of the file server +(see +.IR users (6) +and +.IR fossilcons (8)). +Next, give the user a password using +.I auth/changeuser +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 +.BR /usr/$user , +create +.BR /mail/box/$user/mbox , +.BR /cron/$user/cron , +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 + wsys = /mnt/term^`{cat /mnt/term/env/wsys} + 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 + auth/factotum + plumber + 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. +.SH "SEE ALSO" +.IR passwd (1), +.IR rio (1), +.IR namespace (4), +.IR fossil (4), +.IR users (6), +.IR auth (8), +.IR fossilcons (8). diff --git a/sys/man/8/nfsserver b/sys/man/8/nfsserver new file mode 100755 index 000000000..04348eb51 --- /dev/null +++ b/sys/man/8/nfsserver @@ -0,0 +1,183 @@ +.TH NFSSERVER 8 +.SH NAME +nfsserver, portmapper, pcnfsd \- 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 . +Currently only NFS version 2 is served. +.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 +(default and mandatory). +.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). +.TP +.B -s +Expect a network connection on file descriptor 1 +instead of listening for incoming calls. +.TP +.B -t +Listen for incoming TCP calls, rather than UDP calls. +.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 tcp!pie -a tcp!yoshimi -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:pie /n/pie +/etc/mount -o soft,intr eduardo:yoshimi /n/yoshimi +.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 +.IR nfs (4) +.br +RFC1057, +.I "RPC: Remote Procedure Call Protocol Specification, Version 2," +describes Sun's RPC protocol. +.br +RFC1094, +.I "NFS: Network File System Protocol Specification," +describes NFS version 2. +.br +RFC1813, +.I "NFS Version 3 Protocol Specification." +.br +RFC3530, +.I "Network File System (NFS) version 4 Protocol." diff --git a/sys/man/8/partfs b/sys/man/8/partfs new file mode 100755 index 000000000..c22b8d4b8 --- /dev/null +++ b/sys/man/8/partfs @@ -0,0 +1,65 @@ +.TH PARTFS 8 +.SH NAME +partfs \- serve file, with partitions +.SH SYNOPSIS +.B disk/partfs +[ +.B -Dr +] +[ +.B -d +.I diskname +] +[ +.B -m +.I mtpt +] +[ +.B -s +.I srvname +] +.I diskimage +.SH DESCRIPTION +.I Partfs +presents the file +.I diskimage +in the manner of +.IR sd (3) +on +.IB mtpt / diskname +(default +.BR /dev/sdXX ). +Changes made to the disk are written through to +.I diskimage +unless the +.B -r +option is given. +.PP +When setting disk geometry with the +.B geometry +control message, +the arguments are +sectors and sector size. +.PP +The +.B -s +option causes +.I partfs +to post its 9P service at +.BI /srv/ service \fR. +.SH EXAMPLES +Partition a USB flash device: +.IP +.EX +usb/disk +disk/partfs /n/disk/0/data +disk/mbr -m /386/mbr /dev/sdXX/data +disk/fdisk -baw /dev/sdXX/data +disk/prep /dev/sdXX/plan9 +.EE +.SH SOURCE +.B /sys/src/cmd/disk/partfs.c +.SH SEE ALSO +.IR sd (3), +.IR disksim (8), +.IR prep (8) diff --git a/sys/man/8/pci b/sys/man/8/pci new file mode 100755 index 000000000..e351df0f7 --- /dev/null +++ b/sys/man/8/pci @@ -0,0 +1,38 @@ +.TH PCI 8 +.SH NAME +pci \- print PCI bus configuration +.SH SYNOPSIS +.B pci +[ +.B -bv +] +.SH DESCRIPTION +.I Pci +normally prints one line per device found on the local PCI bus +described by +.BR #$/pci . +The fields are +.IB bus . device . function , +class, +class code, +.IB vendor / device +ids , +IRQ (interrupt), +followed by the configuration registers in pairs of +.IB index : address +and +.IR size . +The +.B -b +option suppresses output for PCI bridges. +The +.B -v +option adds a second line per device, containing an English description +obtained from +.BR /lib/pci . +.SH FILES +.B /lib/pci +.SH SOURCE +.B /rc/bin/pci +.SH SEE ALSO +.IR pnp (3) diff --git a/sys/man/8/pcmcia b/sys/man/8/pcmcia new file mode 100755 index 000000000..027a7f999 --- /dev/null +++ b/sys/man/8/pcmcia @@ -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/sys/man/8/pem b/sys/man/8/pem new file mode 100755 index 000000000..69df8ffe9 --- /dev/null +++ b/sys/man/8/pem @@ -0,0 +1,65 @@ +.TH PEM 8 +.SH NAME +pemdecode, pemencode \- encode files in Privacy Enhanced Mail (PEM) format +.SH SYNOPSIS +.PP +.B auth/pemdecode +.I section +[ +.I file +] +.PP +.B auth/pemencode +.I section +[ +.I file +] +.SH DESCRIPTION +PEM is a textual encoding for binary data originally used by the +Privacy Enhanced Mail program but now commonly used for +other applications, notably TLS. +PEM encodes data in base 64 +(see +.IR encode (2)) +between lines of the form: +.IP +.EX +-----BEGIN SECTION----- +-----END SECTION----- +.EE +.LP +where +.B SECTION +may be any string describing the encoded data. +The most common use of PEM format on Plan 9 is for encoding +X.509 certificates; see +.IR rsa (8). +.PP +.I Pemdecode +extracts the named +.I section +and writes the decoded data to standard output. +.PP +.I Pemencode +encodes its standard input, labels it as a +.IR section , +and writes it to standard output. +.SH EXAMPLES +Encode and decode a simple greeting: +.IP +.EX +% echo hello world | + auth/pemencode GREETING +-----BEGIN GREETING----- +aGVsbG8gd29ybGQK +-----END GREETING----- +% echo hello world | + auth/pemencode GREETING | + auth/pemdecode GREETING +hello world +% +.EE +.SH SOURCE +.B /sys/src/cmd/auth +.SH "SEE ALSO +.IR rsa (8) diff --git a/sys/man/8/ping b/sys/man/8/ping new file mode 100755 index 000000000..3b0877261 --- /dev/null +++ b/sys/man/8/ping @@ -0,0 +1,204 @@ +.TH PING 8 +.SH NAME +ping, gping, traceroute, hogports \- probe the Internet +.SH SYNOPSIS +.B ip/ping +[ +.B -6aflqr +] [ +.B -i +.I interval +] [ +.B -n +.I count +] [ +.B -s +.I size +] [ +.B -w +.I waittime +] +.I destination +.PP +.B ip/gping +[ +.B -r +] [ +.B -l +] [ +.B -i +.I interval +] +.I destination +[ +.I destination +\&... ] +.PP +.B ip/traceroute +[ +.B -dn +][ +.B -a +.I n +][ +.B -h +.I nbuck +][ +.B -t +.I sttl +] +.I dest +.PP +.B ip/hogports +.B [\fImtpt\fP/]\fIproto\fP!\fIaddress\fP!\fIstartport\fP[-\fIendport\fP] +.SH DESCRIPTION +.I Ping +sends ICMP echo request messages to a system. +It can be used to determine the network delay +and whether or not the destination is up. +By default, a line is written to standard output for +each request. +If a reply is received the line contains the request +id (starting at 0 and incrementing), the round trip time +for this request, the average round trip time, and the time +to live in the reply packet. If no reply is received the line +contains the word "lost", the request id, and the average round +trip time. +.PP +If a reply is received for each request, +.I ping +returns successfully. Otherwise it returns an error status of +"lost messages". +.PP +The options are: +.TP +.B 6 +force the use of IPv6's ICMP, +.BR icmpv6 , +instead of IPv4's ICMP. +.I Ping +tries to determine which version of IP to use automatically. +.TP +.B a +adds the IP source and destination addresses to each report. +.TP +.B f +send messages as fast as possible (flood). +.TP +.B i +sets the time between messages +to be +.I interval +milliseconds, default 1000 ms. +.TP +.B l +causes only lost messages to be reported. +.TP +.B n +requests that a total of +.I count +messages be sent, default 32. +.TP +.B q +suppresses any output (i.e. be quiet). +.TP +.B r +randomizes the delay with a minimum extra delay of 0 ms and a +maximum extra delay of the selected interval. +.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 w +sets the additional time in milliseconds to wait +after all packets are sent. +.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 a +make +.I n +attempts at each TTL value (default 3). +.TP +.B t +set the starting TTL value to +.I sttl +(default 1). +.TP +.B h +print out a histogram of times from request +to response at each TTL value. The histogram +contains +.I nbuck +buckets. +.PD +.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 +.SH SEE ALSO +.IR ip (3) diff --git a/sys/man/8/plan9.ini b/sys/man/8/plan9.ini new file mode 100755 index 000000000..381652fe2 --- /dev/null +++ b/sys/man/8/plan9.ini @@ -0,0 +1,1000 @@ +.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 +.IP +.EX +name=\f2value\fP +.EE +.LP +each of which defines a kernel or device parameter. +.PP +Blank lines and +Carriage Returns +.IB ( \er ) +are ignored. +.B # +comments are ignored, but are only recognised if +.L # +appears at the start of a line. +.PP +For devices, the generic format of +.I value +is +.IP +.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 ETHERNET +.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. +For debugging purposes, automatic probing can +be disabled by specifying the line +.BR *noetherprobe= . +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 +.IR TYPE s +are +.\" .TF ga620 +.TF vt6102 +.PD +.TP +.B igbe +The Intel 8254X Gigabit Ethernet controllers, +as found on the Intel PRO/1000 adapters for copper (not fiber). +Completely configurable. +.TP +.B igbepcie +The Intel 8256[36], 8257[12], and 82573[ev] Gigabit Ethernet +PCI-Express controllers. +Completely configurable. +.TP +.B rtl8169 +The Realtek 8169 Gigabit Ethernet controller. +Completely configurable. +.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 dp83820 +National Semiconductor DP83820-based Gigabit Ethernet adapters, notably +the D-Link DGE-500T. +Completely configurable. +.TP +.B vgbe +The VIA Velocity Gigabit Ethernet controller. +Known to drive the VIA8237 (ABIT AV8), but at 100Mb/s full-duplex only. +.TP +.B m10g +The Myricom 10-Gigabit Ethernet 10G-PCIE-8A controller. +Completely configurable. +Can't boot through these due to enormous firmware loads. +.TP +.B i82598 +The Intel 8259[89] 10-Gigabit Ethernet PCI-Express controllers. +Completely configurable. +Can't boot through these due to lack of a +.I 9load +driver. +.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 . +Completely configurable. +.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 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. +Completely configurable. +.TP +.B rtl8139 +The Realtek 8139 Fast Ethernet controller. +Completely configurable. +.TP +.B vt6102 +The VIA VT6102 Fast Ethernet Controller (Rhine II). +.TP +.B smc91cxx +SMC 91cXX chip-based PCMCIA adapters, notably the SMC EtherEZ card. +.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 ne2000 +Not software configurable iff ISA; +PCI clones or supersets are software configurable; +includes the Realtek 8029 clone used by Parallels. +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 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. +.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. +.IP +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. +.IP +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). +There are two formats for +.I string +which depend on the length of the string. +If it is exactly 5 or 13 characters long it is assumed +to be an alphanumeric key; if it is exactly 10 or 26 characters +long the key is assumed to be in hex format (without a leading +.IR 0x ). +The lengths are checked, +as is the format of a hex key. +.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. +.IP +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 key1=afish key2=calledraawaru +.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 1d8f65c9a52d83c8e4b43f94af' >/net/ether0/0/ctl +.EE +.IP +Card-specific power management may be enabled/disabled by +.EX + pm=[on, off] +.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. +. +.SS DISKS, TAPES +(S)ATA controllers are autodetected. +.SS \fLusbX=type=uhci\fP +.SS \fLusbX=type=ohci\fP +This specifies the settings for a USB UHCI or OHCI 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. +Also like the Ethernet controllers, USB autoprobing can be +disabled by specifying the line +.BR *nousbprobe= . +.SS \fLscsiX=value\fP +This defines a SCSI interface which cannot be automatically detected +by the kernel. +.PP +Known +.IR TYPE s +are +.TP +.B aha1542 +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 \fLaoeif=\fP\fIlist\fP +This specifies a space-separated +.I list +of Ethernet interfaces to be bound at boot to the ATA-over-Ethernet driver, +.IR aoe (3). +For example, +.LR "aoeif=ether0 ether1" . +Only interfaces on this list will initially be accessible via AoE. +.SS \fLaoedev=e!#æ/aoe/\fIshelf\fL.\fIslot\fR +This specifies an ATA-over-Ethernet device accessible via the interfaces +named in +.IR aoeif +on AoE +.I shelf +and +.I slot +to use as a root device for bootstrapping. +.SS AUDIO +.SS \fLaudioX=value\fP +This defines a sound interface. +.PP +Known types are +.TF ess1688 +.PD +.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 +.IP +.EX +port=0x220 irq=7 dma=5 +.EE +.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: +.IP +.EX +eia\fIX\fP=disabled +.EE +.LP +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 +.TP +.B 1 +for COM2 +.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 \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, +.IP +.EX +console=0 b19200 po +.EE +.LP +would use COM1 at 19,200 baud +with odd parity. +.SS "PC CARD" +.SS \fLpccard0=disabled\fP +Disable probing for and automatic configuration of PC card controllers. +.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 \fLpcmcia0=disabled\fP +Disable probing for and automatic configuration of PCMCIA controllers. +.SS BOOTING +.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. +It is typically used to specify additional arguments to +pass to +.IR kfs (4) +or +.IR ipconfig (8). +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 . +See +.IR boot (8) +for more. +.SS \fLnobootprompt=value\fP +Suppress the +.L "root from" +prompt and use +.I value +as the answer instead. +.SS \fLuser=value\fP +Suppress the +.L "user" +prompt and use +.I value +as the answer instead. +.SS \fLdebugfactotum=\fP +Causes +.IR boot (8) +to start +.I factotum +with the +.B -p +option, so that it can be debugged. +.SS \fLfactotumopts=options\fP +Causes +.IR boot (8) +to start +.I factotum +with the given +.IR options , +which must be a single word (i.e., contain no whitespace). +.SS \fLventi=value\fP +When booting from a local fossil server backed by a local +or remote venti server, +this variable specifies how to establish the connection to the +venti server. +See +.IR boot (8) +for more. +.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 \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. +.SS PROCESSOR +.SS \fL*norealmode=\fP +The PC kernel switches the processor to 16-bit real mode +to run BIOS interrupts, for example to find the memory map or to enable VESA. +This variable disables such switches. +.SS \fL*noe820scan=\fP +When available, the PC kernel uses the BIOS E820 memory map +to size memory. This variable disables the scan. +.SS \fL*maxmem=value\fP +This defines the maximum physical address that the system will scan when sizing memory. +By default the PC operating system will scan up to 3.75 gigabytes +(0xF0000000, the base of kernel virtual address space), but setting +.B *maxmem +will limit the scan. +.B *maxmem +must be less than 3.75 gigabytes. +This variable is not consulted if using the E820 memory map. +.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=\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 7). +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*nopcirouting=\fP +Disable pci routing during boot. May solve interrupt routing +problems on certain machines. +.SS \fL*nodumpstack=\fP +Disable printing a stack dump on panic. +Useful if there is only a limited cga screen available, +otherwise the textual information about the panic may scroll off. +.\" .SS \fL*nobios=\fP +.\" what does this do? something with pci +.SS \fLioexclude=value\fP +Specifies a list of ranges of 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 \fLumbexclude=value\fP +Specifies a list of ranges of UMB to exclude from use by drivers. +Ranges are inclusive on both ends and separated by commas. +For example: +.EX + umbexclude=0xD1800-0xD3FFF +.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 VIDEO +.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 NVRAM +.SS \fLnvram=file\fP +.SS \fLnvrlen=length\fP +.SS \fLnvroff=offset\fP +This is used to specify an nvram device and optionally the length of the ram +and read/write offset to use. +These values are consulted by +.I readnvram +(see +.IR authsrv (2)). +The most common use of the nvram is to hold a +.IR secstore (1) +password for use by +.IR factotum (4). +.SS \fLnvr=value\fP +This is used by the WORM 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. +.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/sys/man/8/pop3 b/sys/man/8/pop3 new file mode 100755 index 000000000..d2da836d8 --- /dev/null +++ b/sys/man/8/pop3 @@ -0,0 +1,168 @@ +.TH POP3 8 +.SH NAME +pop3, imap4d \- Internet mail servers +.SH SYNOPSIS +.PP +.B upas/pop3 +[ +.B -d +.I debugfile +][ +.B -a +.I mailbox +][ +.B -r +.I peeraddr +][ +.B -t +.I tlscertfile +][ +.B -p +] +.PP +.B ip/imap4d +.RB [ -acpv ] +.RB [ -d +.IR smtpdomain ] +.RB [ -s +.IR servername ] +.SH DESCRIPTION +These programs support remote access to mail 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 Pop3 +provides access to a user's mailboxes via the POP3 protocol. +The options are: +.TP 4 +.B -d +create +.I debugfile +and write debugging output to it +.TP +.B -a +causes pop3 to assume that it it already authenticated +and to read +.I mailbox +immediately +.TP +.B -r +causes +.I pop3 +to create the file +.B /mail/ratify/trusted/\fIpeeraddr\fP#32 +to allow subsequent SMTP sessions from that +address. See +.IR ratfs (4) +for details. +.TP +.B -t +get the local TLS certificate from the file +.IR tlscertfile . +.TP +.B -p +allow passwords in the clear for authenticating the connection +.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 +.IR Imap4d 's +options are: +.TP 4 +.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 c +Allow plan 9 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 v +Turn on verbose output to the debug file. +.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. +.PP +For both +.I imap4d +and +.IR pop3 , +the password used to authenticate the connection is the APOP +secret held by +.IR keyfs (4) +running on the authentication server. +.SH FILES +.TF /mail/box/username/imap.subscrib +.TP +.B /sys/log/imap4d +debugging output +.TP +.BI /mail/box/ username / mailbox +.TP +.BI /mail/box/ username / mailbox .imp +.TP +.BI /mail/box/ username /imap.subscribed +.SH SOURCE +.B /sys/src/cmd/upas/pop3 +.br +.B /sys/src/cmd/ip/imap4d +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR mail (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR upasfs (4) +.SH BUGS +Usually messages flagged for deletion with +.B DELE +are not actually deleted until the client sends a +.B QUIT +command to end the conversation. +.I Pop3 +implements a non-standard command +.B SYNC +that deletes messages flagged for deletion +without ending the conversation. diff --git a/sys/man/8/ppp b/sys/man/8/ppp new file mode 100755 index 000000000..d8595983e --- /dev/null +++ b/sys/man/8/ppp @@ -0,0 +1,281 @@ +.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 -k +.I keyspec +] [ +.B -m +.I mtu +] [ +.B -M +.I chatfile +] [ +.B -p +.I dev +] [ +.B -x +.I netmntpt +] [ +.B -t +.I modemcmd +] [ +.I local +[ +.I remote +] ] +.PP +.B ip/pppoe +[ +.B -Pd +] +[ +.B -A +.I acname +] +[ +.B -S +.I srvname +] +[ +.B -k +.I keyspec +] +[ +.B -m +.I mtu +] +[ +.B -x +.I pppnetmntpt +] +[ +.I ether +] +.PP +.B ip/pptp +[ +.B -dP +] +[ +.B -k +.I keyspec +] +[ +.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 +in IPv4 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 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 k +add +.I keyspec +to the +.IR factotum (4) +key pattern when looking for a user name and password +for authentication; the default key pattern is +.B "proto=pass" "service=ppp" +.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 its configuration +to +.B /net/ndb +.TP +.B p +communicate over +.I dev +instead of standard I/O +.TP +.B u +before starting the PPP protocol 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 S +run as a server +.TP +.B t +before starting the PPP protocol, write +.I modemcmd +to the device +.TP +.B x +use the IP stack mounted at +.I netmntpt +.TP +.B M +chat with the modem as specified in the chat file. Each line in +the chat file contains a string that is transmitted to the modem +and the response expected (e.g. 'AT' 'OK') +.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 +.I pppoe -specific +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 +.PD +.PP +The other options are relayed to +.IR ppp . +.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 +.SH SEE ALSO +.I gre +in +.IR ip (3) +.SH BUGS +.I Ppp +should use factotum to execute +the client side of the challenge-reponse +protocol, but instead it reads a password +from factotum and runs the protocol itself. diff --git a/sys/man/8/prep b/sys/man/8/prep new file mode 100755 index 000000000..68f92a267 --- /dev/null +++ b/sys/man/8/prep @@ -0,0 +1,769 @@ +.TH PREP 8 +.SH NAME +prep, fdisk, format, mbr \- prepare disks, floppies and flashes +.SH SYNOPSIS +.B disk/prep +[ +.B -bcfnprw +] +[ +.B -a +.I name +]... +[ +.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 -9 +] +[ +.B -m +.I mbrfile +] +.I disk +.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 arenas +.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 arenas +A +.IR venti (8) +arenas partition. +.TP +.B bloom +A +.IR venti (8) +bloom-filter partition. +.TP +.B cache +A +.IR cfs (4) +file system cache. +.TP +.B fossil +A +.IR fossil (4) +file system. +.TP +.B fs +A +.IR kfs (4) +file system. +.TP +.B fscfg +A one-sector partition used to store an +.IR fs (3) +configuration. +.TP +.B isect +A +.IR venti (8) +index section. +.TP +.B nvram +A one-sector partition used to simulate non-volatile RAM on PCs. +.TP +.B other +A non-archived +.IR fossil (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: +.TF -a +.PD +.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. +.IR Prep 's +.B -a +flag takes the name of a partition to create. +(See the list above for partition names.) +It can be repeated to specify a list of partitions to create. +If the disk is currently unpartitioned, +.I prep +will create the named partitions on the disk, +attempting to use the entire disk in a sensible manner. +The partition names must be from the list given above. +.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 . +.TF ".\fI newdot +.PD +.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. +In +.IR fdisk , +the newly created partition has type +.RB `` PLAN9 ;'' +to set a different type, use the +.B t +command (q.v.). +.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. +Numeric constants followed by +.LR k , +.LR m , +.LR g , +or +.LR t +(or upper-case equivalents) +are scaled to the respective size in kilo-, mega-, giga-, or tera-bytes. +Finally, the expression +.IB n % +evaluates to +.RI ( n × disksize )/100. +As examples, +.L "a . .+20%" +creates a new partition starting at +.B . +that takes up a fifth of the disk, +.L "a . .+21G" +creates a new partition starting at +.B . +that takes up 21 gigabytes (21×2\u\s-130\s0\d bytes), +and +.L "a 1000 $" +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. +.TF "t \fR[\fI type \fR] +.PD +.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. +.TP +.BI t " \fR[\fI type \fR] +Set the partition type. If it is not given, +.I fdisk +will display a list of choices and then prompt for it. +.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 first sector of the +root directory into address 0x7E00, and looks for +a directory entry named +.BR 9LOAD . +If it finds such an entry, +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 older 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 . +If +.I mbrfile +contains more than one sector of `boot block', +the rest will be copied into the first track of the +disk, if it fits. +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. +The +.B -9 +option initialises the partition table to consist of one +.BR plan9 +partition which spans the entire disc starting at the end of the +first track. +.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 \e + /386/9load /tmp/plan9.ini /386/9pcf.gz +.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 -bw -a^(9fat nvram fossil cache swap) /dev/sdC0/plan9 +disk/format -b /386/pbslba -d -r 2 /dev/sdC0/9fat \e + /386/9load /386/9pcf /tmp/plan9.ini +.EE +.PP +Create a bootable USB disk or flash-memory device to be booted +via the BIOS and containing only a FAT Plan 9 partition. +.IP +.EX +mount /srv/usb /n/usb +ls -d /n/usb/sdU* # note the name, normally sdU0.0 +disk/partfs /n/usb/sdU0.0/data +cd /dev/sdXX +disk/mbr -m /386/mbr data +disk/fdisk -baw data +disk/prep -bw -a^(9fat nvram fossil) plan9 +cp /386/9loadusb /tmp/9load # force format to use the name `9load' +disk/format -b /386/pbslba -d -r 2 9fat /tmp/9load \e + /386/9pccpuf /tmp/plan9.ini +.EE +.SH FILES +.TF /386/mbr.bootmgr +.TP +.B /386/mbr +.TP +.B /386/mbr.bootmgr +self-configuring `smart boot manager' +.SH SOURCE +.TF /sys/src/cmd/disk/prep +.TP +.B /sys/src/cmd/disk/prep +.TP +.B /sys/src/boot/pc +.TP +.B /n/sources/extra/bootmgr.tgz +source for +.BR /386/mbr.bootmgr ; +compilable on (l)unix +.SH SEE ALSO +.IR floppy (3), +.IR sd (3), +.IR usb (4), +.IR 9load (8), +.IR partfs (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. +.PP +If +.L "prep -p" +doesn't find a Plan 9 partition table, +it will emit commands to delete +.I all +extant partitions. +Similarly, +.L "fdisk -p" +will delete all partitions, +including +.LR data , +if there are no partitions defined in the MBR. diff --git a/sys/man/8/qer b/sys/man/8/qer new file mode 100755 index 000000000..0dba5e023 --- /dev/null +++ b/sys/man/8/qer @@ -0,0 +1,233 @@ +.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 -adsER +] +[ +.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 -R +flag instructs +.I runq +never to give up on a failed queue job, instead leaving +it in the queue to be retried. +.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/sys/man/8/reboot b/sys/man/8/reboot new file mode 100755 index 000000000..b65ee27f1 --- /dev/null +++ b/sys/man/8/reboot @@ -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/lib , +once every five minutes. If the stat fails, rather than timing 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/sys/man/8/replica b/sys/man/8/replica new file mode 100755 index 000000000..c7c32d361 --- /dev/null +++ b/sys/man/8/replica @@ -0,0 +1,316 @@ +.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 -nuv +] +[ +.B -c +.I name +]... +[ +.B -s +.I name +]... +.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 +.ift .sp 0.5 +.ifn .sp +\h'0.25i' +.I path +.I mode +.I uid +.I gid +.I mtime +.I length +.ift .sp 0.5 +.ifn .sp +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: +.ift .sp 0.5 +.ifn .sp +\h'0.25i' +.I time +.I gen +.I verb +.I path +.I serverpath +.I mode +.I uid +.I gid +.I mtime +.I length +.ift .sp 0.5 +.ifn .sp +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 applylog +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 applylog +still takes no action for files beginning with the given names, +but does so silently and will not +report the conflicts in the future. +(The conflict is resolved in favor of the client.) +The +.B -s +is similar but causes +.I applylog +to overwrite 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/sys/man/8/rsa b/sys/man/8/rsa new file mode 100755 index 000000000..cc0ca8af0 --- /dev/null +++ b/sys/man/8/rsa @@ -0,0 +1,242 @@ +.TH RSA 8 +.SH NAME +rsagen, rsafill, asn12rsa, rsa2pub, rsa2ssh, rsa2x509 \- generate and format rsa keys +.SH SYNOPSIS +.B rsagen +[ +.B -b +.I nbits +] +[ +.B -t +.I tag +] +.PP +.B rsafill +[ +.I file +] +.PP +.B asn12rsa +[ +.B -t +.I tag +] +[ +.I file +] +.PP +.B rsa2pub +[ +.I file +] +.PP +.B rsa2ssh +[ +.I file +] +.PP +.B rsa2x509 +[ +.B -e +.I expiretime +] +.I certinfo +[ +.I file +] +.SH DESCRIPTION +Plan 9 represents an RSA key as an attribute-value pair list +prefixed with the string +.BR key ; +this is the generic key format used by +.IR factotum (4). +A full RSA private key has the following attributes: +.TF proto +.PD +.TP +.B proto +must be +.B rsa +.TP +.B size +the number of significant bits in +.B n +.TP +.B ek +the encryption exponent +.TP +.B n +the product of +.B !p +and +.B !q +.TP +.B !dk +the decryption exponent +.TP +.B !p +a large prime +.TP +.B !q +another large prime +.TP +.B "!kp\fR, \fL!kq\fR, \fL!c2 +parameters derived from the other attributes, cached to speed decryption +.PD +.LP +All the numbers are in hexadecimal except +.I size , +which is decimal. +An RSA public key omits the attributes beginning with +.L ! . +A key may have other attributes as well (for example, a +.B service +attribute identifying how this key is typically used), +but to these utilities such attributes are merely comments. +.PP +For example, a very small (and thus insecure) private key and corresponding +public key might be: +.IP +.EX +key proto=rsa size=8 ek=7 n=8F !dk=67 !p=B !q=D !kp=3 !kq=7 !c2=6 +key proto=rsa size=8 ek=7 n=8F +.EE +.LP +Note that the order of the attributes does not matter. +.PP +.I Rsagen +prints a randomly generated RSA private key +whose +.B n +has exactly +.I nbits +(default 1024) +significant bits. +If +.I tag +is specified, it is printed between +.B key +and +.BR proto=rsa ; +typically, +.I tag +is a sequence of attribute-value comments describing the key. +.PP +.I Rsafill +reads a private key, +recomputes the +.BR !kp , +.BR !kq , +and +.BR !c2 +attributes if they are missing, +and prints a full key. +.PP +.I Asn12rsa +reads an RSA private key stored as ASN.1 +encoded in the binary Distinguished Encoding Rules (DER) +and prints a Plan 9 RSA key, +inserting +.I tag +exactly as +.I rsagen +does. +ASN.1/DER is a popular key format on Unix and Windows; +it is often encoded in text form using the Privacy Enhanced Mail (PEM) format +in a section labeled as an +.RB `` RSA +.B PRIVATE +.BR KEY .'' +The command: +.IP +.EX +auth/pemdecode 'RSA PRIVATE KEY' | auth/asn12rsa +.EE +.LP +extracts the key section from a textual ASN.1/DER/PEM key +into binary ASN.1/DER format and then +converts it to a Plan 9 RSA key. +.PP +.I Rsa2pub +reads a Plan 9 RSA public or private key, +removes the private attributes, and prints the resulting public key. +Comment attributes are preserved. +.PP +.I Rsa2ssh +reads a Plan 9 RSA public or private key and prints the public portion +in the format used by SSH: three space-separated decimal numbers +.BR size , +.BR ek , +and +.BR n . +For compatibility with external SSH implementations, the public keys in +.B /sys/lib/ssh/keyring +and +.B $home/lib/keyring +are stored in this format. +.PP +.I Rsa2x509 +reads a Plan 9 RSA private key and writes a self-signed X.509 certificate +encoded in ASN.1/DER format to standard output. +(Note that ASN.1/DER X.509 certificates are different from ASN.1/DER private keys). +The certificate uses the current time as its start time and expires +.I expiretime +seconds +(default 3 years) +later. +It contains the public half of the key +and includes +.I certinfo +as the issuer/subject string (also known as a ``Distinguished Name''). +This info is typically in the form: +.IP +.EX +C=US ST=NJ L=07974 O=Lucent OU='Bell Labs' CN=G.R.Emlin +.EE +.LP +The X.509 ASN.1/DER format is often encoded in text using a PEM section +labeled as a +.RB `` CERTIFICATE .'' +The command: +.IP +.EX +auth/rsa2x509 'C=US OU=''Bell Labs''' file | +auth/pemencode CERTIFICATE +.EE +.LP +generates such a textual certificate. +Applications that serve TLS-encrypted sessions (for example, +.IR httpd (8), +.IR pop3 (8), +and +.IR tlssrv (8)) +expect certificates in ASN.1/DER/PEM format. +.SH EXAMPLES +Generate a fresh key and use it to start a TLS-enabled web server: +.IP +.EX +auth/rsagen -t 'service=tls owner=*' >key +auth/rsa2x509 'C=US CN=*.cs.bell-labs.com' key | + auth/pemencode CERTIFICATE >cert +cat key >/mnt/factotum/ctl +ip/httpd/httpd -c cert +.EE +.PP +Generate a fresh key and configure a remote Unix system to +allow use of that key for logins: +.IP +.EX +auth/rsagen -t 'service=ssh' >key +auth/rsa2ssh key | ssh unix 'cat >>.ssh/authorized_keys' +cat key >/mnt/factotum/ctl +ssh unix +.EE +.SH SOURCE +.B /sys/src/cmd/auth +.SH "SEE ALSO +.IR factotum (4), +.IR pem (8), +.IR ssh (1) +.SH BUGS +There are too many key formats. diff --git a/sys/man/8/scanmail b/sys/man/8/scanmail new file mode 100755 index 000000000..ce639f72a --- /dev/null +++ b/sys/man/8/scanmail @@ -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/sys/man/8/screenlock b/sys/man/8/screenlock new file mode 100755 index 000000000..7137f0534 --- /dev/null +++ b/sys/man/8/screenlock @@ -0,0 +1,20 @@ +.TH SCREENLOCK 8 +.SH NAME +screenlock \- disable access to a terminal +.SH SYNOPSIS +.B screenlock +.SH DESCRIPTION +.I Screenlock +grabs the screen, keyboard, and mouse devices +to disable access to the Plan 9 terminal on which it is run. +The screen can be unlocked by typing the invoking user's Plan 9 password +and a newline. +.SH FILES +.TF /lib/bunny.bit +.TP +.B /lib/bunny.bit +the image displayed while the terminal is locked +.SH SOURCE +.B /sys/src/cmd/screenlock.c +.SH BUGS +Use of this program on communal terminals is anti-social. diff --git a/sys/man/8/scuzz b/sys/man/8/scuzz new file mode 100755 index 000000000..b21213bca --- /dev/null +++ b/sys/man/8/scuzz @@ -0,0 +1,413 @@ +.TH SCUZZ 8 +.SH NAME +scuzz \- SCSI target control +.SH SYNOPSIS +.B scuzz +[ +.B -6eq +] [ +.B -m +.I max-xfer +] [ +[ +.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. +.LP +The +.B -6 +forces the use of 6-byte SCSI commands rather than 10-byte ones. +Some older devices require this, though +.I scuzz +attempts to adapt automatically. +The +.B -e +makes +.I scuzz +more willing to retry I/O errors but less tolerant of other errors +and implies +.BR -6 . +This option is often needed to read Exabyte 8mm tapes. +The +.B -m +option sets the maximum I/O transfer size to +.IR max-xfer . +Exabyte drives often require this to be 1024 or the exact tape block size +and some 4mm drives require this to be the exact tape block size or larger. +.SS Commands +.TF "inquiry" +.PD +.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. +.TF "inquiry" +.PD +.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. +.TF "inquiry" +.PD +.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. +.TF "inquiry" +.PD +.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. +.TF "inquiry" +.PD +.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 10-byte commands, though they are the default. +.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 . +.LP +The +.I max-xfer +value is currently limited to 245760 +to limit kernel memory consumption. +.LP +It may be necessary to set +.I max-xfer +to exactly the block size used to write a tape +in order to read it on some drives. diff --git a/sys/man/8/secstore b/sys/man/8/secstore new file mode 100755 index 000000000..74c846a7c --- /dev/null +++ b/sys/man/8/secstore @@ -0,0 +1,107 @@ +.TH SECSTORE 8 +.SH NAME +secstored, secuser \- secstore commands +.SH SYNOPSIS +.br +.B auth/secstored +.RB [ -R ] +[ +.BI -S " servername" +] [ +.BI -s " address" +] [ +.BI -x " network" +] [ +.B -v +] +.PP +.B auth/secuser +[ +.B -v +] +.I username +.SH DESCRIPTION +.I Secstored +serves requests from +.IR secstore (1). +By default it listens on port +.BR tcp!*!5356 ; +the +.B -s +option specifies an alternative +.IR address . +In the connection protocol, +.I secstored +describes itself as service +.BR secstore , +but the +.B -S +option can specify a different +.IR servername . +The +.B -R +option supplements the password check with a +call to a RADIUS server, for checking hardware +tokens or other validation. +The +.B -x +option specifies an alternative +.I network +to the default +.BR /net . +By default, +.I secstored +puts itself into the background; +the +.B -v +option enables a verbose debugging mode that suppresses that. +.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 +.BI /adm/secstore/who/ user +for a given secstore +.IR user . +The directory +.B /adm/secstore +should be created mode 770 with owner or group allowing access to the user +that runs +.IR secstored . +The +.B -v +option makes the command chattier. +.PP +By default, +.I secstored +warns the client if no account exists. +If you prefer to obscure this information, use +.I secuser +to create an account +.BR FICTITIOUS . +.SH FILES +.TF /adm/secstore/store/user/ +.TP +.BI /adm/secstore/who/ user +.I secstore +account name, expiration date, verifier +.TP +.BI /adm/secstore/store/ user / +.I user 's +file storage +.TP +.B /lib/ndb/auth +for mapping local userid to RADIUS userid +.TP +.B /sys/log/secstore +log file (if it does not exist, +.I secstored +logs to +.BR /dev/cons ) +.SH SOURCE +.B /sys/src/cmd/auth/secstore +.SH SEE ALSO +.IR secstore (1) diff --git a/sys/man/8/securenet b/sys/man/8/securenet new file mode 100755 index 000000000..cdd4f23d2 --- /dev/null +++ b/sys/man/8/securenet @@ -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/sys/man/8/send b/sys/man/8/send new file mode 100755 index 000000000..f43d956fc --- /dev/null +++ b/sys/man/8/send @@ -0,0 +1,127 @@ +.TH SEND 8 +.SH NAME +send \- mail routing and delivery +.SH SYNOPSIS +.PP +.B upas/send +[ +.B -b +] [ +.B -i +] [ +.B -r +] [ +.B -x +] [ +.B -# +] [ +.I mailaddr ... +] +.SH DESCRIPTION +.I Send +is not normally run directly by the user. Instead, mail protocol +agents like +.I smtpd +(see +.IR smtp (8)) +and mail preparers like +.IR marshal (1) +fork and execute +.IR send . +.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. +.PD +.PP +.I Send +uses the login name as the reply address. +.SH FILES +.TF /mail/box/*/dead.letter +.TP +.B /sys/log/mail +mail log file +.TP +.B /mail/box/*/dead.letter +unmailable text +.TP +.B /mail/lib/rewrite +rules for handling addresses +.TP +.B /mail/box/*/names +personal alias files +.TP +.B /mail/lib/namefiles +lists names of files containing system aliases +.SH SOURCE +.TP +.B /sys/src/cmd/upas/send +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR mail (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR smtp (8), +.IR upasfs (4) diff --git a/sys/man/8/smtp b/sys/man/8/smtp new file mode 100755 index 000000000..f0facf1bd --- /dev/null +++ b/sys/man/8/smtp @@ -0,0 +1,260 @@ +.TH SMTP 8 +.SH NAME +smtp, smtpd \- mail transport +.SH SYNOPSIS +.in +0.5i +.ti -0.5i +.B upas/smtp +[ +.B -aAdfips +] [ +.B -b +.I busted-mx +] ... [ +.B -g +.I gateway +] [ +.B -h +.I host +] [ +.B -u +.I user +] [ +.BI . domain +] +.I destaddr +.I sender +.I rcpt-list +.in -0.5i +.PP +.in +0.5i +.ti -0.5i +.B upas/smtpd +[ +.B -adDfrg +] [ +.B -c +.I certfile +] [ +.B -h +.I mydom +] [ +.B -k +.I evilipaddr +] [ +.B -m +.I mailer +] [ +.B -n +.I netdir +] +.in -0.5i +.SH DESCRIPTION +.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 options are: +.TF - +.PD +.TP +.B -a +if the server supports PLAIN or LOGIN authentication, +authenticate to the server using a password from +.IR factotum (4). +See RFCs 3207 and 2554. +This option implies +.BR -s . +.TP +.B -A +autistic server: don't wait for an SMTP greeting banner +but immediately send a +.L NOOP +command to provoke the server into responding. +.TP +.B -b +ignore +.I busted-mx +when trying MX hosts. +May be repeated. +.TP +.B -d +turn on debugging to standard error. +.TP +.B -f +just filter the converted message to standard +output rather than sending it. +.TP +.B -g +makes +.I gateway +the system to pass the message to if +.I smtp +can't find an address nor MX entry for the destination system. +.TP +.B -h +use +.I host +as the local system name; +it may be fully-qualified or not. If not +specified, it will default to the contents of +.BR /dev/sysname . +.TP +.B -i +under +.BR -a , +authenticate even if we can't start TLS. +.TP +.B -p +ping: just verify that the users named in the +.I rcpt-list +are valid users at +.IR destaddr ; +don't send any mail. +.TP +.B -s +if the server supports the ESMTP extension to use TLS encryption, turn it on for +this session. See RFC3207 for details. +.TP +.B -u +specify a user name to be used in authentication. The default name is +the current login id. +.PD +.PP +Finally if +.I .domain +is given, it is appended to the end of any unqualified system names +in the envelope or header. +. +.PP +.I Smtpd +receives a message using the Simple Mail Transfer Protocol. +Standard input and output are the protocol connection. +SMTP authentication by +.I login +and +.I cram-md5 +protocols is supported; authenticated connections are permitted to relay. +.PP +The options are: +.TF - +.PD +.TP +.B -a +requires that all clients authenticate to be able to send mail. +.TP +.B -c +specifies a certificate to use for TLS. Without this +option, the capability to start TLS will not be advertised. +.TP +.B -d +turns on debugging output, +with each connection's output going to a uniquely-named file in +.BR /sys/log/smtpdb . +.TP +.B -D +sleeps for 15 seconds usually at the start of the SMTP dialogue; +this deters some spammers. +Connections from Class A networks frequented by spammers will incur +a longer delay. +.TP +.B -f +prevents relaying from non-trusted networks. +It also tags messages from non-trusted sites when they deliver mail +from an address in a domain we believe we represent. +.TP +.B -g +turns on grey/white list processing. All mail is rejected (with a +retry code) unless the sender's IP address is on the whitelist, +.BR /mail/grey/whitelist , +an append only file. +Addresses can be added to the whitelist by the administrator. However, +the usual way for addresses to be added is by +.I smtpd +itself. +Whenever a message is received and the sender's address isn't on the whitelist, +.I smtpd +first looks for the file +.BI /mail\%/grey\%/tmp\%/\| local\% /\| remote\% /\| recipient\fP, +where +.I local +and +.I remote +are IP addresses of the local and remote systems, respectively. +If it exists and was created more than a few minutes go, +the remote address is added to the whitelist. +If not, the file is created and the mail is rejected with a `try again' code. +The expectation is that spammers will not retry for more than a few minutes +and that others will. +.TP +.B -h +specifies the receiving domain. If this flag is not specified, the +receiving domain is inferred from the host name. +.TP +.B -k +causes connections from the host at +the IP address, +.IR evilipaddr , +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. +.TP +.B -m +set the +.I mailer +to which +.I smtpd +passes a received message. +The default is +.BR /bin/upas/send . +.TP +.B -n +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 -p +permits clients to authenticate using protocols which transfer +the password in the clear, e.g. +.I login +protocol. This should only be used if the connection has +previously encrypted using e.g. +.IR tlssrv (8). +.TP +.B -r +turns on forward DNS validation of non-trusted sender address. +.TP +.B -s +causes copies of blocked messages to be saved in a sub-directory of +.BR /mail/queue.dump . +.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 . +.SH SOURCE +.TP +.B /sys/src/cmd/upas/smtp +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR mail (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR tlssrv (8), +.IR upasfs (4) diff --git a/sys/man/8/snoopy b/sys/man/8/snoopy new file mode 100755 index 000000000..72d2f1023 --- /dev/null +++ b/sys/man/8/snoopy @@ -0,0 +1,215 @@ +.TH SNOOPY 8 +.SH NAME +snoopy \- spy on network packets +.SH SYNOPSIS +.B snoopy +[ +.B -CDdpst +] [ +.B -M +.I m +] [ +.B -N +.I n +] [ +.B -f +.I filter-expression +] [ +.B -h +.I first-header +] [ +.I packet-source +] +.PP +.B snoopy +.B -? +[ +.I proto... +] +.SH DESCRIPTION +.I Snoopy +reads packets from a +.I 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 later read by +.IR snoopy . +.I Packet-source +can be the name of an Ethernet +(e.g., +.BR /net/ether0 ), +an interface +(e.g., +.BR /net/ipifc/0 ), +or a file of captured packets. +.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: +.IP +.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: +.IP +.EX +\fIexpr\fP: \fIprotocol\fP + | \fIfield\fP '=' \fIvalue\fP + | \fIfield\fP '!=' \fIvalue\fP + | \fIprotocol\fP '(' \fIexpr\fP ')' + | '(' \fIexpr\fP ')' + | \fIexpr\fP '||' \fIexpr\fP + | \fIexpr\fP '&&' \fIexpr\fP + | '!' \fIexpr\fP +.EE +.PP +The values for +.I protocol +and +.I field +can +be obtained using the +.B -? +option. With no arguments, it lists the known protocols. +Otherwise it prints, for each protocol specified, +which subprotocols it can multiplex to, +and which fields can be used for filtering. +For example, the listing for ethernet is currently: +.IP +.EX +ether's filter attributes: + s - source address + d - destination address + a - source|destination address + sd - source|destination address + t - type +ether's subprotos: + 0x0800 ip 0x8863 pppoe_disc + 0x0806 arp 0x8864 pppoe_sess + 0x0806 rarp 0x888e eapol + 0x86dd ip6 +.EE +.PP +The format of +.I value +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 -C +compute the correct checksum for each packet; +on mismatch, add a field +.B !ck=\fIxxxx\fP +where +.I xxxx +is the correct checksum. +.TP +.B -D +output will be a binary trace file in Unix pcap format. +.TP +.B -d +output will be a binary trace file. +.TP +.B -t +input is a binary trace file as generated with the +.B -d +option. +.TP +.B -p +do not enter promiscuous mode. Only packets to +this interface will be seen. +.TP +.B -s +force one output line per packet. The +default is multiline. +.TP +.B -M +discard all but the first +.I m +bytes of each packet. The default is to keep the entire packet. +This option is most useful when writing packets to a file with the +.B -d +option. +.TP +.B -N +dump +.I n +data bytes per packet. The default is 32. +.TP +.B -f +use +.I filter-expression +to filter the packet stream. The default is +to match all packets. +.TP +.B -h +assume the first header per packet to be of the +.I first-header +protocol. +The default is +.LR ether . +.SH EXAMPLES +To display only +.SM BOOTP +and +.SM ARP +packets: +.IP +.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: +.IP +.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/ether0 +Ethernet device +.SH SOURCE +.B /sys/src/cmd/ip/snoopy +.SH BUGS +.I Snoopy +only dumps ethernet packets, because there's +no device to get IP packets without a media header. diff --git a/sys/man/8/stats b/sys/man/8/stats new file mode 100755 index 000000000..b5d5adc53 --- /dev/null +++ b/sys/man/8/stats @@ -0,0 +1,160 @@ +.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 "I idle +system load, % time in idle, and % time in interrupts. +The last two are averaged over all processors on a +multiprocessor. +.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*sleepsecs, +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, +system load, which displays a number between 0 and 1000, +idle and intr, which display percentages 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 -T " sleepsecs +Set the number of seconds between samples to +.I sleepsecs +(default one second). +.I Sleepsecs +may be a floating-point number. +.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/sys/man/8/statusbar b/sys/man/8/statusbar new file mode 100755 index 000000000..f79e1b64b --- /dev/null +++ b/sys/man/8/statusbar @@ -0,0 +1,71 @@ +.TH STATUSBAR 8 +.SH NAME +statusbar \- display a bar graph status window +.SH SYNOPSIS +.B aux/statusbar +[ +.B -kt +] +[ +.B -w +.I minx,miny,maxx,maxy +] +.I title +.SH DESCRIPTION +.I Aux/statusbar +reads textual status lines +from standard input, converting them into a +continuously updated bar graph displayed in a new window +on the screen. +The +.I title +is displayed on a line above the bar graph. +Each input line is two space-separated decimal numbers: +the numerator and denominator of a fraction. +.PP +.I Statusbar +exits when it reaches end-of-file on standard input. +Typing +.SM DEL +or control-C +will also cause it to exit. +.PP +The options are: +.TP +.B -k +do not allow typing to cause +.I statusbar +to exit +.TP +.B -t +print an ASCII status bar to standard output, using +backspace to redraw it +.TP +.B -w +set the coordinates of the statusbar window created +.PD +.SH EXAMPLE +The +.B -v +option to +.IR hget (1) +.\" and the +.\" .B -d +.\" option to +.\" .IR venti/fmtarenas +.\" and +.\" .I venti/fmtisect +.\" (see +.\" .IR venti-fmt (8)) +causes it to print status lines suitable for +input to +.IR statusbar . +.PP +Monitor a long download: +.IP +.EX +hget -v -o bigfile http://server.com/bigfile |[2] + aux/statusbar 'big file download' +.EE +.SH SOURCE +.B /sys/src/cmd/aux/statusbar.c diff --git a/sys/man/8/stub b/sys/man/8/stub new file mode 100755 index 000000000..8c2114236 --- /dev/null +++ b/sys/man/8/stub @@ -0,0 +1,53 @@ +.TH STUB 8 +.SH NAME +stub \- provide mount point stubs +.SH SYNOPSIS +.B aux/stub +[ +.B -Dd +] +.I path/name +.SH DESCRIPTION +.I Aux/stub +union mounts itself before +.I path +in the name space. +It serves a file system containing a single entry, +.IR name , +with file mode 0. +The intent is to provide a place to bind or mount other resources. +The options are: +.TP +.B -D +print all 9P messages +.TP +.B -d +make +.I name +a directory; by default it is a file +.PD +.SH EXAMPLE +Use +.I stub +and +.I sshnet +(see +.IR ssh (1)) +to create a new network protocol +.RB `` mit '' +that is actually TCP tunneled via SSH to a machine +at MIT: +.IP +.EX +% sshnet -m /net.alt amsterdam.lcs.mit.edu +% aux/stub -d /net/mit +% bind /net.alt/tcp /net/mit +% con -l mit!plan9.bell-labs.com!whoami +connected to mit!plan9.bell-labs.com!whoami on /net/mit/0 +i am 204.178.31.2 sysname achille you are 18.26.4.9 port 1248 +% +.EE +.SH SOURCE +.B /sys/src/cmd/aux/stub.c +.SH SEE ALSO +.IR mntgen (4) diff --git a/sys/man/8/swap b/sys/man/8/swap new file mode 100755 index 000000000..e905d8f45 --- /dev/null +++ b/sys/man/8/swap @@ -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 local user-level process, such as +.IR kfs (4), +can lead to deadlock; use raw devices or remote files instead. diff --git a/sys/man/8/timesync b/sys/man/8/timesync new file mode 100755 index 000000000..c1272f715 --- /dev/null +++ b/sys/man/8/timesync @@ -0,0 +1,110 @@ +.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 stratum +] +[ +.B -s +.I netroot +] +[ +.B -frnDdLilG +] +[ +.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 -G +causes +.I timesync +to use a gps server (see +.IR gpsfs (8)) +as a time source. +.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 -S +sets the stratum number to +.IR stratum . +.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/sys/man/8/tlssrv b/sys/man/8/tlssrv new file mode 100755 index 000000000..bbc74d3c8 --- /dev/null +++ b/sys/man/8/tlssrv @@ -0,0 +1,152 @@ +.TH TLSSRV 8 +.SH NAME +tlssrv, tlsclient, tlssrvtunnel, tlsclienttunnel \- TLS server and client +.SH SYNOPSIS +.PP +.B tlssrv +[ +.B -c +.I cert.pem +] +[ +.B -l +.I +logfile +] +[ +.B -r +.I remotesys +] +.I cmd +[ +.I args ... +] +.PP +.B tlsclient +[ +.B -t +.I trustedkeys +] +[ +.B -x +.I excludedkeys +] +.I address +.PP +.B tlssrvtunnel +.I plain-addr +.I crypt-addr +.I cert.pem +.PP +.B tlsclienttunnel +.I crypt-addr +.I plain-addr +.I trustedkeys +.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 +.I cmd +.IR args ; +a typical command might start the IMAP or HTTP server. +.I Cert.pem +is the server certificate; +.IR factotum (4) +should hold the corresponding private key. +The specified +.I logfile +is by convention the same as for the target server. +.I Remotesys +is mainly used for logging. +.PP +.I Tlsclient +is the reverse of +.IR tlssrv : +it dials +.IR address , +starts TLS, +and then relays +between the network connection +and standard input and output. +If the +.B -t +flag +(and, optionally, the +.B -x +flag) +is given, the remote server must present a key +whose SHA1 hash is listed in +the file +.I trustedkeys +but not in the file +.IR excludedkeys . +See +.IR thumbprint (6) +for more information. +.PP +.I Tlssrvtunnel +and +.I tlsclienttunnel +use these tools and +.I listen1 +(see +.IR listen (8)) +to provide TLS network tunnels, allowing legacy +application to take advantage of TLS encryption. +.SH EXAMPLES +Listen for TLS-encrypted IMAP by creating a server certificate +.B /sys/lib/tls/imap.pem +and a listener script +.B /bin/service.auth/tcp993 +containing: +.IP +.EX +#!/bin/rc +exec tlssrv -c/sys/lib/tls/imap.pem -limap4d -r`{cat $3/remote} \e + /bin/ip/imap4d -p -dyourdomain -r`{cat $3/remote} \e + >[2]/sys/log/imap4d +.EE +.PP +Interact with the server, putting the appropriate hash into +.B /sys/lib/tls/mail +and running: +.IP +.EX +tlsclient -t /sys/lib/tls/mail tcp!server!imaps +.EE +.PP +Create a TLS-encrypted VNC connection from a client on +.B kremvax +to a server on +.BR moscvax : +.IP +.EX +mosc% vncs -d :3 +mosc% tlssrvtunnel tcp!moscvax!5903 tcp!*!12345 \e + /usr/you/lib/cert.pem +krem% tlsclienttunnel tcp!moscvax!12345 tcp!*!5905 \e + /usr/you/lib/cert.thumb +krem% vncv kremvax:5 +.EE +.LP +(The port numbers passed to the VNC tools are offset by 5900 from the +actual TCP port numbers.) +.SH FILES +.TP +.B /sys/lib/tls +.SH SOURCE +.B /sys/src/cmd/tlssrv.c +.br +.B /sys/src/cmd/tlsclient.c +.br +.B /rc/bin/tlssrvtunnel +.br +.B /rc/bin/tlsclienttunnel +.SH "SEE ALSO" +.IR factotum (4), +.IR listen (8), +.IR rsa (8) +.br +Unix's +.I stunnel diff --git a/sys/man/8/trampoline b/sys/man/8/trampoline new file mode 100755 index 000000000..3060e0a26 --- /dev/null +++ b/sys/man/8/trampoline @@ -0,0 +1,68 @@ +.TH TRAMPOLINE 8 +.SH NAME +trampoline \- forward incoming calls to another address +.SH SYNOPSIS +.B aux/trampoline +[ +.B -9 +] +[ +.B -a +.I altaddr +] +[ +.B -m +.I netdir +] +.I addr +.SH DESCRIPTION +.I Trampoline +can be used in a service file (see +.IR listen (8)) +to link an incoming call to +another address that provides the service, typically on another machine. +.PP +.I Trampoline +dials +.I addr +and copies data between that connection +and its own standard input and output. +.PP +The options are: +.TP +.B -9 +The connection carries only 9P messages. In this case +.I trampoline +will relay whole messages at a time. +.TP +.BI -a " altaddr +Dial +.I altaddr +and relay between the two network connections, +ignoring standard input and output. +.TP +.BI -m " netdir +Restrict forwarding to particular machines. +.I Netdir +must be the incoming call directory. +.I Trampoline +finds the caller's MAC address +.I m +and checks that +.IR ndb (6) +contains an entry with +.BI ether= m +and the attribute +.BR trampok . +If no such entry is found, the call is rejected. +.PD +.SH FILES +.TF /sys/log/trampoline +.TP +.B /sys/log/trampoline +logs rejected calls +.SH SOURCE +.B /sys/src/cmd/aux/trampoline.c +.SH SEE ALSO +.IR dial (2), +.IR listen (8) diff --git a/sys/man/8/udpecho b/sys/man/8/udpecho new file mode 100755 index 000000000..601179747 --- /dev/null +++ b/sys/man/8/udpecho @@ -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/sys/man/8/update b/sys/man/8/update new file mode 100755 index 000000000..2519f213b --- /dev/null +++ b/sys/man/8/update @@ -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/sys/man/8/venti b/sys/man/8/venti new file mode 100755 index 000000000..8574708e6 --- /dev/null +++ b/sys/man/8/venti @@ -0,0 +1,512 @@ +.TH VENTI 8 +.SH NAME +venti \- archival storage server +.SH SYNOPSIS +.in +0.25i +.ti -0.25i +.B venti/venti +[ +.B -Ldrs +] +[ +.B -a +.I address +] +[ +.B -B +.I blockcachesize +] +[ +.B -c +.I config +] +[ +.B -C +.I lumpcachesize +] +[ +.B -h +.I httpaddress +] +[ +.B -I +.I indexcachesize +] +[ +.B -m +.I free-memory% +] +[ +.B -W +.I webroot +] +.SH DESCRIPTION +.I Venti +is a SHA1-addressed archival storage server. +See +.IR venti (6) +for a full introduction to the system. +This page documents the structure and operation of the server. +.PP +A venti server requires multiple disks or disk partitions, +each of which must be properly formatted before the server +can be run. +.SS Disk +The venti server maintains three disk structures, typically +stored on raw disk partitions: +the append-only +.IR "data log" , +which holds, in sequential order, +the contents of every block written to the server; +the +.IR index , +which helps locate a block in the data log given its score; +and optionally the +.IR "bloom filter" , +a concise summary of which scores are present in the index. +The data log is the primary storage. +To improve the robustness, it should be stored on +a device that provides RAID functionality. +The index and the bloom filter are optimizations +employed to access the data log efficiently and can be rebuilt +if lost or damaged. +.PP +The data log is logically split into sections called +.IR arenas , +typically sized for easy offline backup +(e.g., 500MB). +A data log may comprise many disks, each storing +one or more arenas. +Such disks are called +.IR "arena partitions" . +Arena partitions are filled in the order given in the configuration. +.PP +The index is logically split into block-sized pieces called +.IR buckets , +each of which is responsible for a particular range of scores. +An index may be split across many disks, each storing many buckets. +Such disks are called +.IR "index sections" . +.PP +The index must be sized so that no bucket is full. +When a bucket fills, the server must be shut down and +the index made larger. +Since scores appear random, each bucket will contain +approximately the same number of entries. +Index entries are 40 bytes long. Assuming that a typical block +being written to the server is 8192 bytes and compresses to 4096 +bytes, the active index is expected to be about 1% of +the active data log. +Storing smaller blocks increases the relative index footprint; +storing larger blocks decreases it. +To allow variation in both block size and the random distribution +of scores to buckets, the suggested index size is 5% of +the active data log. +.PP +The (optional) bloom filter is a large bitmap that is stored on disk but +also kept completely in memory while the venti server runs. +It helps the venti server efficiently detect scores that are +.I not +already stored in the index. +The bloom filter starts out zeroed. +Each score recorded in the bloom filter is hashed to choose +.I nhash +bits to set in the bloom filter. +A score is definitely not stored in the index of any of its +.I nhash +bits are not set. +The bloom filter thus has two parameters: +.I nhash +(maximum 32) +and the total bitmap size +(maximum 512MB, 2\s-2\u32\d\s+2 bits). +.PP +The bloom filter should be sized so that +.I nhash +\(mu +.I nblock +\(<= +0.7 \(mu +.IR b , +where +.I nblock +is the expected number of blocks stored on the server +and +.I b +is the bitmap size in bits. +The false positive rate of the bloom filter when sized +this way is approximately 2\s-2\u\-\fInblock\fR\d\s+2. +.I Nhash +less than 10 are not very useful; +.I nhash +greater than 24 are probably a waste of memory. +.I Fmtbloom +(see +.IR venti-fmt (8)) +can be given either +.I nhash +or +.IR nblock ; +if given +.IR nblock , +it will derive an appropriate +.IR nhash . +.SS Memory +Venti can make effective use of large amounts of memory +for various caches. +.PP +The +.I "lump cache +holds recently-accessed venti data blocks, which the server refers to as +.IR lumps . +The lump cache should be at least 1MB but can profitably be much larger. +The lump cache can be thought of as the level-1 cache: +read requests handled by the lump cache can +be served instantly. +.PP +The +.I "block cache +holds recently-accessed +.I disk +blocks from the arena partitions. +The block cache needs to be able to simultaneously hold two blocks +from each arena plus four blocks for the currently-filling arena. +The block cache can be thought of as the level-2 cache: +read requests handled by the block cache are slower than those +handled by the lump cache, since the lump data must be extracted +from the raw disk blocks and possibly decompressed, but no +disk accesses are necessary. +.PP +The +.I "index cache +holds recently-accessed or prefetched +index entries. +The index cache needs to be able to hold index entries +for three or four arenas, at least, in order for prefetching +to work properly. Each index entry is 50 bytes. +Assuming 500MB arenas of +128,000 blocks that are 4096 bytes each after compression, +the minimum index cache size is about 6MB. +The index cache can be thought of as the level-3 cache: +read requests handled by the index cache must still go +to disk to fetch the arena blocks, but the costly random +access to the index is avoided. +.PP +The size of the index cache determines how long venti +can sustain its `burst' write throughput, during which time +the only disk accesses on the critical path +are sequential writes to the arena partitions. +For example, if you want to be able to sustain 10MB/s +for an hour, you need enough index cache to hold entries +for 36GB of blocks. Assuming 8192-byte blocks, +you need room for almost five million index entries. +Since index entries are 50 bytes each, you need 250MB +of index cache. +If the background index update process can make a single +pass through the index in an hour, which is possible, +then you can sustain the 10MB/s indefinitely (at least until +the arenas are all filled). +.PP +The +.I "bloom filter +requires memory equal to its size on disk, +as discussed above. +.PP +A reasonable starting allocation is to +divide memory equally (in thirds) between +the bloom filter, the index cache, and the lump and block caches; +the third of memory allocated to the lump and block caches +should be split unevenly, with more (say, two thirds) +going to the block cache. +.SS Network +The venti server announces two network services, one +(conventionally TCP port +.BR venti , +17034) serving +the venti protocol as described in +.IR venti (6), +and one serving HTTP +(conventionally TCP port +.BR http , +80). +.PP +The venti web server provides the following +URLs for accessing status information: +.TF "\fL/storage" +.PD +.TP +.B /index +A summary of the usage of the arenas and index sections. +.TP +.B /xindex +An XML version of +.BR /index . +.TP +.B /storage +Brief storage totals. +.TP +.BI /set/ variable +The current integer value of +.IR variable . +Variables are: +.BR compress , +whether or not to compress blocks +(for debugging); +.BR logging , +whether to write entries to the debugging logs; +.BR stats , +whether to collect run-time statistics; +.BR icachesleeptime , +the time in milliseconds between successive updates +of megabytes of the index cache; +.BR arenasumsleeptime , +the time in milliseconds between reads while +checksumming an arena in the background. +The two sleep times should be (but are not) managed by venti; +they exist to provide more experience with their effects. +The other variables exist only for debugging and +performance measurement. +.TP +.BI /set/ variable / value +Set +.I variable +to +.IR value . +.TP +.BI /graph/ name / param / param / \fR... +A PNG image graphing the named run-time statistic over time. +The details of names and parameters are undocumented; +see +.B httpd.c +in the venti sources. +.TP +.B /log +A list of all debugging logs present in the server's memory. +.TP +.BI /log/ name +The contents of the debugging log with the given +.IR name . +.TP +.B /flushicache +Force venti to begin flushing the index cache to disk. +The request response will not be sent until the flush +has completed. +.TP +.B /flushdcache +Force venti to begin flushing the arena block cache to disk. +The request response will not be sent until the flush +has completed. +.PD +.PP +Requests for other files are served by consulting a +directory named in the configuration file +(see +.B webroot +below). +.SS Configuration File +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 +.I fmtarenas +or +.I fmtisect +(see +.IR venti-fmt (8)). +In particular, only the configuration needs to be +changed if a component is moved to a different file. +.PP +The configuration file consists of lines in the form described below. +Lines starting with +.B # +are comments. +.TF "\fLindex\fI name " +.PD +.TP +.BI index " name +Names the index for the system. +.TP +.BI arenas " file +.I File +is an arena partition, formatted using +.IR fmtarenas . +.TP +.BI isect " file +.I File +is an index section, formatted using +.IR fmtisect . +.TP +.BI bloom " file +.I File +is a bloom filter, formatted using +.IR fmtbloom . +.PD +.PP +After formatting a venti system using +.IR fmtindex , +the order of arenas and index sections should not be changed. +Additional arenas can be appended to the configuration; +run +.I fmtindex +with the +.B -a +flag to update the index. +.PP +The configuration file also holds configuration parameters +for the venti server itself. +These are: +.TF "\fLhttpaddr\fI netaddr " +.TP +.BI mem " size +lump cache size +.TP +.BI bcmem " size +block cache size +.TP +.BI icmem " size +index cache size +.TP +.BI addr " netaddr +network address to announce venti service +(default +.BR tcp!*!venti ) +.TP +.BI httpaddr " netaddr +network address to announce HTTP service +(default +.BR tcp!*!http ) +.TP +.B queuewrites +queue writes in memory +(default is not to queue) +.TP +.BI webroot " dir +directory tree containing files for +.IR venti 's +internal HTTP server to consult for unrecognized URLs +.PD +.PP +The units for the various cache sizes above can be specified by appending a +.LR k , +.LR m , +or +.LR g +(case-insensitive) +to indicate kilobytes, megabytes, or gigabytes respectively. +.PP +The +.I file +name in the configuration lines above can be of the form +.IB file : lo - hi +to specify a range of the file. +.I Lo +and +.I hi +are specified in bytes but can have the usual +.BI k , +.BI m , +or +.B g +suffixes. +Either +.I lo +or +.I hi +may be omitted. +This notation eliminates the need to +partition raw disks on non-Plan 9 systems. +.SS Command Line +Many of the options to Venti duplicate parameters that +can be specified in the configuration file. +The command line options override those found in a +configuration file. +Additional options are: +.TF "\fL-c\fI config" +.PD +.TP +.BI -c " config +The server configuration file +(default +.BR venti.conf ) +.TP +.B -d +Produce various debugging information on standard error. +Implies +.BR -s . +.TP +.B -L +Enable logging. By default all logging is disabled. +Logging slows server operation considerably. +.TP +.B -m +Allocate +.I free-memory% +percent of the available free RAM, and partition it +per the guidelines in the +.B Memory +subsection. +This percentage should be large enough to include the entire bloom filter. +This overrides all other memory sizing parameters, +including those on the command line and in the configuration file. +.TP +.B -r +Allow only read access to the venti data. +.TP +.B -s +Do not run in the background. +Normally, +the foreground process will exit once the Venti server +is initialized and ready for connections. +.PD +.SH EXAMPLE +A simple configuration: +.IP +.EX +% cat venti.conf +index main +isect /tmp/disks/isect0 +isect /tmp/disks/isect1 +arenas /tmp/disks/arenas +bloom /tmp/disks/bloom +% +.EE +.PP +Format the index sections, the arena partition, +the bloom filter, and +finally the main index: +.IP +.EX +% venti/fmtisect isect0. /tmp/disks/isect0 +% venti/fmtisect isect1. /tmp/disks/isect1 +% venti/fmtarenas arenas0. /tmp/disks/arenas & +% venti/fmtbloom /tmp/disks/bloom & +% wait +% venti/fmtindex venti.conf +% +.EE +.PP +Start the server and check the storage statistics: +.IP +.EX +% venti/venti +% hget http://$sysname/storage +.EE +.SH SOURCE +.B /sys/src/cmd/venti/srv +.SH "SEE ALSO" +.IR venti (1), +.IR venti (2), +.IR venti (6), +.IR venti-backup (8), +.IR venti-fmt (8) +.br +Sean Quinlan and Sean Dorward, +``Venti: a new approach to archival storage'', +.I "Usenix Conference on File and Storage Technologies" , +2002. +.SH BUGS +Setting up a venti server is too complicated. diff --git a/sys/man/8/venti-backup b/sys/man/8/venti-backup new file mode 100755 index 000000000..599a6d01a --- /dev/null +++ b/sys/man/8/venti-backup @@ -0,0 +1,112 @@ +.TH VENTI-BACKUP 8 +.SH NAME +rdarena, wrarena \- copy arenas between venti servers +.SH SYNOPSIS +.PP +.B venti/rdarena +[ +.B -qv +] +.I arenapart +.I arenaname +.PP +.B venti/wrarena +[ +.B -o +.I fileoffset +] +[ +.B -h +.I host +] +.I arenafile +[ +.I clumpoffset +] +.SH DESCRIPTION +.PP +.I Rdarena +extracts the named +.I arena +from the arena partition +.I arenapart +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; +.B -q +generates only errors on standard error. +.PP +.I Wrarena +writes the blocks contained in the arena +.I arenafile +(typically, the output of +.IR rdarena ) +to a Venti server. +It is typically used to reinitialize a Venti server from backups of the arenas. +For example, +.IP +.EX +venti/rdarena /dev/sdC0/arenas arena.0 >external.media +venti/wrarena -h venti2 external.media +.EE +.LP +writes the blocks contained in +.B arena.0 +to the Venti server +.B venti2 +(typically not the one using +.BR /dev/sdC0/arenas ). +.PP +The +.B -o +option specifies that the arena starts at byte +.I fileoffset +(default +.BR 0 ) +in +.I arenafile . +This is useful for reading directly from +the Venti arena partition: +.IP +.EX +venti/wrarena -h venti2 -o 335872 /dev/sdC0/arenas +.EE +.LP +(In this example, 335872 is the offset shown in the Venti +server's index list (344064) minus one block (8192). +You will need to substitute your own arena offsets +and block size.) +.PP +Finally, the optional +.I offset +argument specifies that the writing should begin with the +clump starting at +.I offset +within the arena. +.I Wrarena +prints the offset it stopped at (because there were no more data blocks). +This could be used to incrementally back up a Venti server +to another Venti server: +.IP +.EX +last=`{cat last} +venti/wrarena -h venti2 -o 335872 /dev/sdC0/arenas $last >output +awk '/^end offset/ { print $3 }' offset >last +.EE +.LP +Of course, one would need to add wrapper code to keep track +of which arenas have been processed. +See +.B /sys/src/cmd/venti/words/backup.example +for a version that does this. +.SH SOURCE +.B /sys/src/cmd/venti/srv +.SH SEE ALSO +.IR venti (6), +.IR venti (8) +.SH BUGS +.I Wrarena +can't read a pipe or network connection containing an arena; +it needs a file already containing the entire arena. diff --git a/sys/man/8/venti-fmt b/sys/man/8/venti-fmt new file mode 100755 index 000000000..656a4aca0 --- /dev/null +++ b/sys/man/8/venti-fmt @@ -0,0 +1,408 @@ +.TH VENTI-FMT 8 +.SH NAME +buildindex, +checkarenas, +checkindex, +conf, +fmtarenas, +fmtbloom, +fmtindex, +fmtisect, +syncindex \- prepare and maintain a venti server +.SH SYNOPSIS +.PP +.B venti/fmtarenas +[ +.B -Z +] +[ +.B -a +.I arenasize +] +[ +.B -b +.I blocksize +] +.I name +.I file +.PP +.B venti/fmtisect +[ +.B -1Z +] +[ +.B -b +.I blocksize +] +.I name +.I file +.PP +.B venti/fmtbloom +[ +.B -n +.I nblocks +| +.B -N +.I nhash +] +[ +.B -s +.I size +] +.I file +.PP +.B venti/fmtindex +[ +.B -a +] +.I venti.conf +.PP +.B venti/conf +[ +.B -w +] +.I partition +[ +.I configfile +] +.if t .sp 0.5 +.PP +.B venti/buildindex +[ +.B -bd +] [ +.B -i +.I isect +] ... [ +.B -M +.I imemsize +] +.I venti.conf +.PP +.B venti/checkindex +[ +.B -f +] +[ +.B -B +.I blockcachesize +] +.I venti.conf +.I tmp +.PP +.B venti/checkarenas +[ +.B -afv +] +.I file +.SH DESCRIPTION +These commands aid in the setup, maintenance, and debugging of +venti servers. +See +.IR venti (6) +for an overview of the venti system and +.IR venti (8) +for an overview of the data structures used by the venti server. +.PP +Note that the units for the various sizes in the following +commands can be specified by appending +.LR k , +.LR m , +or +.LR g +to indicate kilobytes, megabytes, or gigabytes respectively. +.SS Formatting +To prepare a server for its initial use, the arena partitions and +the index sections must be formatted individually, with +.I fmtarenas +and +.IR fmtisect . +Then the +collection of index sections must be combined into a venti +index with +.IR fmtindex . +.PP +.I Fmtarenas +formats the given +.IR file , +typically a disk partition, into an arena partition. +The arenas in the partition are given names of the form +.IR name%d , +where +.I %d +is replaced with a sequential number starting at 0. +.PP +Options to +.I fmtarenas +are: +.TP +.BI -a " arenasize +The arenas are of +.I arenasize +bytes. The default is +.BR 512M , +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 +.BR 8k . +.TP +.B -4 +Create a `version 4' arena partition for backwards compatibility with old servers. +The default is version 5, used by the current venti server. +.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. +(Version 4 only; version 5 sections are not and do not need to be zeroed.) +.PD +.PP +.I Fmtisect +formats the given +.IR file , +typically a disk partition, as a venti index section with the specified +.IR name . +Each of the index sections in a venti configuration must have a unique name. +.PP +Options to +.I fmtisect +are: +.TP +.BI -b " bucketsize +The size of an index bucket, in bytes. +All the index sections within a index must have the same bucket size. +The default is +.BR 8k . +.TP +.B -1 +Create a `version 1' index section for backwards compatibility with old servers. +The default is version 2, used by the current venti server. +.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. +(Version 1 only; version 2 sections are not and do not need to be zeroed.) +.PD +.PP +.I Fmtbloom +formats the given +.I file +as a Bloom filter +(see +.IR venti (6)). +The options are: +.TF "\fL-s\fI size" +.PD +.TP +.BI -n " nblock \fR| " -N " nhash +The number of blocks expected to be indexed by the filter +or the number of hash functions to use. +If the +.B -n +option +is given, it is used, along with the total size of the filter, +to compute an appropriate +.IR nhash . +.TP +.BI -s " size +The size of the Bloom filter. The default is the total size of the file. +In either case, +.I size +is rounded down to a power of two. +.PD +.PP +The +.I file +argument in the commands above can be of the form +.IB file : lo - hi +to specify a range of the file. +.I Lo +and +.I hi +are specified in bytes but can have the usual +.BI k , +.BI m , +or +.B g +suffixes. +Either +.I lo +or +.I hi +may be omitted. +This notation eliminates the need to +partition raw disks on non-Plan 9 systems. +.PP +.I Fmtindex +reads the configuration file +.I venti.conf +and initializes the index sections to form a usable index structure. +The arena files and index sections must have previously been formatted +using +.I fmtarenas +and +.I fmtisect +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 percentage depends both on the +index block size and the compressed size of blocks stored. +See the discussion in +.IR venti (8) +for more. +.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.conf +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 +.I buildindex +to restore a single index section without rebuilding the entire index. +.PP +To make it easier to bootstrap servers, the configuration +file can be stored in otherwise empty space +at the beginning of any venti partitions using +.IR conf . +A partition so branded with a configuration file can +be used in place of a configuration file when invoking any +of the venti commands. +By default, +.I conf +prints the configuration stored in +.IR partition . +When invoked with the +.B -w +flag, +.I conf +reads a configuration file from +.I configfile +(or else standard input) +and stores it in +.IR partition . +.SS Checking and Rebuilding +.PP +.I Buildindex +populates the index for the Venti system described in +.IR venti.conf . +The index must have previously been formatted using +.IR fmtindex . +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 , +but +.I checkindex +requires a large temporary workspace and +.I buildindex +does not. +.PP +Options to +.I buildindex +are: +.TF "\fL-M\fI imemsize" +.PD +.TP +.B -b +Reinitialise the Bloom filter, if any. +.TP +.B -d +`Dumb' mode; run all three passes. +.TP +.BI -i " isect +Only rebuild index section +.IR isect ; +may be repeated to rebuild multiple sections. +The name +.L none +is special and just reads the arenas. +.TP +.BI -M " imemsize +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 usual suffices apply. +The default is 256M. +.PD +.PP +.I Checkindex +examines the Venti index described in +.IR venti.conf . +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 +Options 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. +.TP +.B -f +Attempt to fix any errors that are found. +.PD +.PP +.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 +Options 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. +.PD +.SH SOURCE +.B /sys/src/cmd/venti/srv +.SH SEE ALSO +.IR venti (6), +.IR venti (8) +.SH BUGS +.I Buildindex +should allow an individual index section to be rebuilt. diff --git a/sys/man/8/vga b/sys/man/8/vga new file mode 100755 index 000000000..15d7ef618 --- /dev/null +++ b/sys/man/8/vga @@ -0,0 +1,217 @@ +.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 +.I 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 ), +.I 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. +.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 +.BI -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. +.PP +Using the monitor name +.B vesa +instructs +.I vga +to use VESA BIOS calls to configure the display. +Also, if our VGA controller can't be found in +.IR vgadb , +.I vga +will try the VESA calls. +There are no entries for the +.B vesa +monitor in +.IR vgadb . +For a list of available VESA modes, use +.IP +.EX +aux/vga -m vesa -p +.EE +.PP +Loading the special mode +.BR text : +.IP +.EX +aux/vga -l text +.EE +.PP +switches out of graphics mode back into text mode. +It uses the VESA BIOS. +.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. diff --git a/sys/man/8/wol b/sys/man/8/wol new file mode 100755 index 000000000..7cfffdb9c --- /dev/null +++ b/sys/man/8/wol @@ -0,0 +1,42 @@ +.TH WOL 8 +.SH NAME +wol \- send wake-on-lan Ethernet packet +.SH SYNOPSIS +.B ip/wol +[ +.B -v +] [ +.B -a +.I dialstr +] [ +.B -c +.I password +] +.I macaddr +.SH DESCRIPTION +.I Wol +sends a magic wake-on-lan Ethernet packet to +.IR dialstr +(default +.BR udp!255.255.255.255!0 , +the IPv4 broadcast address), +intended to wake up the machine with an Ethernet interface with the MAC +address +.IR macaddr . +.I Macaddr +is not used to route the packet, but is inserted into the magic packet +as required by the wake-on-lan protocol. +.PP +An optional +.I password +of at most six bytes can be sent. +The option +.B -v +prints verbose information about the packet sent. +.SH "SEE ALSO" +.IR dial (2), +.I parseether +in +.IR ip (2) +.br +.B http://en.wikipedia.org/wiki/Wake-on-LAN diff --git a/sys/man/fonts b/sys/man/fonts new file mode 100755 index 000000000..238145da0 --- /dev/null +++ b/sys/man/fonts @@ -0,0 +1,10 @@ +# mkfile rules to get fonts in Lucida Sans. +# if you want to use Times, change these next lines to +# MAN=mantimes +# FONTS='' +MAN=man +FONTS='.fp 1 R LucidaSans +.fp 2 I LucidaSansI +.fp 3 B LucidaSansB +.fp 5 L LucidaCW +' diff --git a/sys/man/index.html b/sys/man/index.html new file mode 100755 index 000000000..26e92fdae --- /dev/null +++ b/sys/man/index.html @@ -0,0 +1,59 @@ + +Plan 9 Manual - Volume 1 + + +

Preface

+Preface +
+Preface to the 3rd Edition +
+Preface to the 2nd Edition (1995) + +

Plan 9 Manual in printable form

+ +
1PostScript +
1Gzipped PostScript +
2PDF +
+ +

Plan 9 Manual Section by Section in HTML

+ +
1Commands +
2System and library calls +
3Devices +
4File servers +
5Plan 9 File Protocol, 9P +
6File formats, misc +
7Databases +
8System administration +
+ +

Keyword search

+

+(The search is for the conjunction of the space +separated keywords.) + +

+ + + + + +
+ +

Look up a specific man page

+
+ + + + +
diff --git a/sys/man/mkfile b/sys/man/mkfile new file mode 100755 index 000000000..b9a146cf2 --- /dev/null +++ b/sys/man/mkfile @@ -0,0 +1,110 @@ +< /sys/man/fonts + +LIB=/sys/lib/man + +default:V: check + +indices:V: + for (i in [0-8]){ + $LIB/secindex $i > $i/INDEX + $LIB/mkhtmlindex $i > $i/INDEX.html + } + mk lookindex + $LIB/mksearchindex > searchindex # index for man2html searches + +permind:V: + rm -f /sys/lib/man/permind/toc + { + echo .am TH + echo .tm '\\$1' '\\$2' '\\n%' + echo .. + for (i in [0-8]){ + builtin cd $i + for(j in [a-z0-9]*) + switch($i/$j){ + case 1/tbl + tbl $j + case 1/eqn 3/realtime 6/auth + eqn $j + case 1/pic + pic $j + case 1/grap + grap $j | pic + case * + cat $j + } + builtin cd .. + } + } | troff -$MAN > /dev/null >[2] /sys/lib/man/permind/toc + builtin cd $LIB/permind + rm -f out + mk out > /dev/null >[2] /dev/null + +old-check:V: checksource + awk -f $LIB/checkman.awk [0-8]/* | sed '/\/(cda|av|midi|pub|weather|service\.9net|isdn)(\/|\))/d' + +punccheck: + grep -n '^\.[IB][^PRIB].+[.;,:]$' [0-9]/* | grep -v '\.\.\.' + +check:V: indices checksource + awk -f $LIB/checkman.awk [0-8]/* + +checksource:QV: + sam -d >[2]/dev/null <<'!' + f input + < cat [0-8]/[0-9a-z]* + B output + b input + ,x/^\.SH SOURCE/ .,/^\.SH/ x g/^\.B/t "output + b output + ,x/^\.B.? / d + ,x/ .*/d + ,s/.+/if(! test -f & \&\& ! test -d &) echo no such SOURCE file '&'/g + ,>rc + ! + +lookindex:V: + builtin cd $LIB/lookman + mkindex + + +print.out:V: permind + { + {echo -n $FONTS; cat $LIB/title} | troff + {echo -n $FONTS; cat $LIB/trademarks} | troff -ms + {echo -n $FONTS; echo ' '} | troff + {echo -n $FONTS; cat $LIB/preface4} | troff -ms + {echo -n $FONTS; echo ' '} | troff + {echo -n $FONTS; cat $LIB/preface3} | troff -ms + {echo -n $FONTS; echo ' '} | troff + {echo -n $FONTS; cat $LIB/preface} | troff -ms + {echo -n $FONTS; echo ' '} | troff + { + for (i in [0-8]){ + builtin cd $i + for(j in [a-z0-9]*) + switch($i/$j){ + case 1/tbl + tbl $j + case 1/eqn 6/auth + eqn $j + case 1/pic + pic $j + case 1/grap + grap $j | pic + case * + cat $j + } + builtin cd .. + } + } | troff -$MAN + {echo -n $FONTS; echo ' '} | troff + {echo -n $FONTS; echo ' '} | troff + cat $LIB/permind/out + {echo -n $FONTS; echo ' '} | troff + {echo -n $FONTS; echo ' '} | troff + {echo -n $FONTS; cat $LIB/colophon} | troff + } > print.out + +clean:V: + rm -f man.out diff --git a/sys/man/preface.html b/sys/man/preface.html new file mode 100755 index 000000000..50d3619fc --- /dev/null +++ b/sys/man/preface.html @@ -0,0 +1,116 @@ + + +preface + + +

Preface to the Second (1995) Edition +

+

+Plan 9 was born in the same lab where Unix began. +Old Unix hands will recognize the cultural heritage in this manual, +where venerable Unix commands live on, +described in the classic Unix style. Underneath, though, lies +a new kind of system, organized around communication and +naming rather than files and processes. +

+

+In Plan 9, distributed computing is a central premise, +not an evolutionary add-on. The system relies on a +uniform protocol to refer to and communicate +with objects, whether they be data or processes, and whether or +not they live on the same machine or even similar machines. +A single paradigm (writing to named places) unifies +all kinds of control and interprocess signaling. +

+

+Name spaces can be built arbitrarily. In particular all +programs available to a given user are customarily united +in a single logical directory. +Temporary files and +untrusted activities can be confined in isolated spaces. +When a portable machine connects to the +central, archival file system, the machine's local +name space is joined smoothly to that of the archival file system. +The architecture affords other unusual abilities, including: +

+
+
+Objects in name spaces imported from other machines (even from +foreign systems such as MS-DOS) are transparently accessible. +
+Windows appear in name spaces on a par with files and processes. +
+A historical file system allows one to navigate +the archival file system in time as well as in space; +backup files are always at hand. +
+A debugger can handle simultaneously active processes +on disparate kinds of hardware. +
+

+The character set of Plan 9 is Unicode, which +covers most of the world's major scripts. +The system has its own programming languages: +a dialect of C with simple inheritance, a simplified shell, +and a CSP-like concurrent language, Alef. +An ANSI-POSIX emulator (APE) admits unreconstructed Unix code. +

+

+Plan 9 is the work of many people. +The protocol was begun by Ken Thompson; naming +was integrated by Rob Pike and networking by Dave Presotto. +Phil Winterbottom simplified the management of name spaces +and re-engineered the system. +They were joined by Tom Killian, Jim McKie, and Howard Trickey in +bringing the system up on various machines and making +device drivers. +Thompson made the C compiler; +Pike, window systems; +Tom Duff, the shell and raster graphics; +Winterbottom, Alef; +Trickey, Duff, and Andrew Hume, APE. +Bob Flandrena ported a myriad of +programs to Plan 9. +Other contributors include +Alan Berenbaum, +Lorinda Cherry, +Bill Cheswick, +Sean Dorward, +David Gay, +Paul Glick, +Eric Grosse, +John Hobby, +Gerard Holzmann, +Brian Kernighan, +Bart Locanthi, +Doug McIlroy, +Judy Paone, +Sean Quinlan, +Bob Restrick, +Dennis Ritchie, +Bjarne Stroustrup, +and +Cliff Young. +

+

+Plan 9 is made available as is, without formal support, but +substantial comments or contributions may be communicated to +the authors. +

+

+
+
+
+
+
+
+
+Doug McIlroy +
+March, 1995 + +

+

+ +Copyright © 2000 Lucent Technologies Inc. All rights reserved. + diff --git a/sys/man/preface3.html b/sys/man/preface3.html new file mode 100755 index 000000000..16fabe421 --- /dev/null +++ b/sys/man/preface3.html @@ -0,0 +1,84 @@ + + +preface3 + + +

Preface to the Third (2000) Edition +

+

+A great deal has happened to Plan 9 in the five years since its last release. +Although much of the system will seem familiar, hardly any aspect +of it is unchanged. +The kernel has been heavily reworked; +the graphical environment completely rewritten; +many commands added, deleted, or replaced; +and the libraries greatly expanded. +Underneath, though, the same approach to computing remains: +a distributed system that uses file-like naming to access and +control resources both local and remote. +

+Some of the changes are sweeping: +
+
+Alef is gone, a casualty of the cost of maintaining multiple languages, compilers, +and libraries in a diverse world, +but its model for processes, tasks, and communication lives on +in a new thread library for C. +
+Support for color displays is much more general, building on a new +alpha-blending graphical operator called +draw +that replaces the old +bitblt. +Plan 9 screens are now, discreetly, colorful. +
+A new mechanism called plumbing connects applications together +in a variety of ways, most obviously in the support of multimedia. +
+The interfaces to the panoply of rotating storage devices have been +unified and extended, +while providing better support for having Plan 9 coexist with other +operating systems on a single disk. +
+Perhaps most important, this release of the system is being done under +an open source agreement, providing cost-free source-level access to the +software. +
+

+Plan 9 continues to be the work of many people. +Besides those mentioned in the old preface, +these people deserve particular note: +Russ Cox did much of the work updating the graphics +and creating the new disk and bootstrap model +as well as providing a number of new commands; +David Hogan ported Plan 9 to the Dec Alpha; +and +Sape Mullender wrote the new thread library. +

+Other new contributors include +Bruce Ellis, +Charles Forsyth, +Eric Van Hensbergen, +and +Tad Hunt. +

+
+
+
+
+
+
+
+
+Bell Labs +
+Computing Science Research Center +
+Murray Hill NJ +
+June, 2000 + +

+ +Copyright © 2000 Lucent Technologies Inc. All rights reserved. + diff --git a/sys/man/preface4.html b/sys/man/preface4.html new file mode 100755 index 000000000..c924ecd30 --- /dev/null +++ b/sys/man/preface4.html @@ -0,0 +1,78 @@ + + +preface4 + + +

Preface to the Fourth (2002) Edition +

+

+Plan 9 continues to grow and adapt. +The fourth major release of the system +incorporates a number of changes, but the most central +is the conversion to a new version of the 9P file system +protocol. +This new version was motivated by a desire to support +files with name elements longer than 27 bytes (the old +NAMELEN), +but the opportunity was taken to change a number of other things +about the protocol, +making it more efficient, more flexible, and easier to encapsulate. +One simple but indispensable new feature made possible by the protocol +change is that the system now records the user who last modified a file; +try +ls +-m +to identify the culprit. +

+Many aspects of system security have been improved. +The new security agent +factotum(4) +maintains user passwords, while +secstore(8) +keeps them safe and enables single sign-on to multiple domains and machines +using a variety of secure protocols and services. +

+Throughout the system, components have been rewritten and interfaces +modified to eliminate restrictions, improve performance, and clarify design. +The full list is too long to include here, but significant changes have occurred +in a number of system calls +(wait(2), +stat(2), +mount(2), +and +errstr(2)), +the thread library +(thread(2)), +formatted printing +(print(2) +and +fmtinstall(2)), +security +(many pages in section 2, including +auth(2), +authsrv(2)), +and many others. +

+The changes are sweeping and are accompanied by many new programs, tools, +services, +and libraries. +See the manual pages and the accompanying documents for more information. +

+

+
+
+
+
+
+
+Bell Labs +
+Computing Science Research Center +
+Murray Hill NJ +
+April, 2002 +

+ +Copyright © 2002 Lucent Technologies Inc. All rights reserved. + diff --git a/sys/man/searchindex b/sys/man/searchindex new file mode 100755 index 000000000..ed62c62e1 --- /dev/null +++ b/sys/man/searchindex @@ -0,0 +1,566 @@ + 00000000.0bbbbbbb 00000bbb.bbbbbbbb 0bbbbbbb 10bbbbbb 110bbbbb 1110bbbb ascii backward based bbbbbbbb.bbbbbbbb binary bit bits byte bytes character characters compatible conversion conversions convert converted deal described descriptions designed encode encoding except external ff fffd files format graphic hexadecimal higher incorrect independent input interface internally inverse iso keyboard letting lib machine manifestation manual mapping multibyte non perform plan presented processing programs properly proposed provides quantity represent representation representing represents rune runes semantic sequences shortened shortest spans standard store stream streams suitable support table tcs textual throughout transformation unicode uninterpreted universal utf value valued values ways wide written utf 6/utf + 0000929b1b54 0152415320704e7266238ebf01030 0x86dd 0x888e 217e5f27 add address addresses arp assume attributes binary bootp bugs bytes canonical captured cddpst checksum ck clientid cmd comparisons complete completed compute consists contained contains context correct data decimal default depends destination device df dhcp digits discard display dump dumps e.g eapol enter entered entire ether ether's ether0 ethernet expr expression expressions ffffffffffff fields file files fill filter filtering filters fl format frag generated grammar header headers hex hl hp ht id indented input interface interrupt ip ip6 ipifc keyboard length lines listing lists ln match matches matching media milliseconds mismatch mode ms msb multiline multiplex nanosecond necessary net network obtained ones optimize option options output packet packets pcap port ports pppoe_disc pppoe_sess pr prints promiscuous proto protocol protocols quux ramfs rarp read readable reads redundant remove req request save sd sec shows snoopy source specific specifying spy src standard started stream string subprotocols subprotos sys tab tcp tf there's time tmp trace traced type udp unix using value values writes writing xid xxxx snoopy 8/snoopy + 034.pac 035.pac 036.pac 037.pac 038.pac active adagietto added adds adjacent allegro allows arrange attribute attributes audio bewegt blue bottom brackets browse browses browsing builds button buttons category chooses class classic classical clicking composer conductor connects consist consists contained containers contains content controls conventionally creates curly current dark data database databse de default delete describe describes describing descriptors devices digest directly directory displayed displays e.g easily edo ein empties entries equals exactly exist exit exits explained file files filharmonisch finale finally flag font forward full fulltext fulltextual future games gemessenem goes graphical green größter gustav halt handhelds hierarchical hierarchically hierarchy holland inactive include interface invoked item jazz juke jukebox jukefs key kondukt kräftig langsam leading leaves lib lines list location lookup lyrics mahler managed manual map mapfile maps memory minimal miniparentage mit mnt mostly mount mounted mountpoint music musikverein names nicht nine object object's objects obvious orchestra orkest pair pairs pale parent parentage parts path pause performance platform play played playing playlist playlistfs posted prepended prepends presents pressed provides pseudo radio reads recorded recording recordings recursively red reference replaced rfo rondo root root→composer running scherzo schnell schritt script sehr select selected selecting served server servers shell shown shows sign signs six slider soloists sort sorted sorting sorts source sp specifies src srv srvhost srvname started starts stop streng string stuff stürmisch subobject subobjects subunits summary symphonic symphony synthesises sys tab takes text texts textual thrown time tiny track trauermarsch type user value vehemenz vienna volume waart wie window windows zu juke 7/juke + 0:0:0:0:0:0:ffff 0xffff addr address addresses addressing addressses adv advertisement assigned backwards bit bits broadcast buffer byte bytes char chars checksum cksum class colons compatibility complement concession configured contains convert converts data decimal default defined defmask described describing dev device digits dir eaddr eipfmt elided embedded endian equal equivalent equivip equivip4 equivip6 errin errors errout ethernet exactly ffff:0:0:0:0:0:0:1111 ffff::1111 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ff00 file fit fmt format formatter freed hdr hex hexadecimal hnputl hnputs hnputv ifc include includes index indicates int integer integers interface interfaces internet interval invoked ip ip.h ipaddr ipaddr1 ipaddr2 ipaddrlen ipallbits ipifc iplifc ipnoaddr ipv4 ipv4allrouter ipv4allsys ipv4bcast ipv6 ipv6rp isv4 leading len libc.h libip lifc lifetime linked linkmtu list manipulate mask maskip masks max maxraint mflag min minraint mount mtu multicast multipoint myetheraddr myipaddr negative net network nhgetl nhgets nhgetv non notation null oflag one's operates packets params parseether parseip parseipmask parses particular pctlbsum periods physical pktin pktout places plan pointed points preferred prefix preflt print programs protocol protocols ptclbsum puts quantities rcv reachtime read readipifc reads recvra6 remote representation return returned returns rooted route router routerlt routers routines rp rxmitra send sendra6 slash source space src stack standard starts store stored str string strings struct structure structures superset sys systems third transfer ttl typedef typically u.h uchar uint ulong unit unsigned ushort using uvlong v4ip v4parsecidr v4parseip v4prefix v4tov6 v6ip v6tov4 valid validlt value verb vlong void wise write written ip 2/ip + 0:alen 0:blen abs addition adds alen allocate allocated allocation allow architecture arithmetic array arrays ascii assembler assume base bases basic basis betomp bit bits blen btomp buf buffer bufp byte bytes char character check chinese common compares computations computes computing consecutive constants conventional conversions convert converted converting converts copy cover cputype cre creates crepre crt crtin crtout crtpre crtprefree crtres crtresfree defaults defined denominator dependent deposited destination diff digit digits dividend divisor doesn't dynamically encountering endian equal except explicitly exponentiation extended factors fails faster fill filled fit flags fmt fmtinstall former freed frees fromo gcd gen generator greater greatest grow grows hexadecimal i.e ignores include includes increases indicated input int integer inverse itomp largest latter leading length letomp libc.h libmp list location low magnitudes mathematical mod modulo modulus mp mp.h mpadd mpassign mpbits mpcmp mpcopy mpdigdiv mpdigit mpdiv mpexp mpextendedgcd mpfmt mpfmt,mptoa mpfree mpint mpinverse mpinvert mpleft mplowbits0 mpmagadd mpmagcmp mpmagsub mpmod mpmul mpnew mpnorm mpone mprand mpright mpsetminbits mpsignif mpsub mptoa mptobe mptoi mptole mptoui mptouv mptov mptwo mpvecadd mpveccmp mpvecdigmuladd mpvecdigmulsub mpvecmul mpvecsub mpzero multiplication multiplicative multiplies necessary needed negative newly nfactors nil non normalized normalizes operations parameter parameters parse perform pointed pointer points portable positive pragma preallocated precision precomputes prime print prod product provides pterminates quotient random refers remainder remaining representation representations required res residue residues rest restrict results return returned returns rewritten routines rptr saves scalar scan shift sign significant size skips smaller source spaces specifies src stops stored string strtomp struct structure structures subtracts sum supported sys tabs takes theorem times trimming type typedef types u.h uchar uchar's uint uitomp unless unsigned using uvlong uvtomp valid value values verb version vlong void vtomp whatever writing yourself mp 2/mp + 0:none:adm 10000:sys 10001:map:map 10002:doc 10003:upas:upas 10004:font 10005:bootes:bootes 1:adm:adm 1:tor:tor abandoned abandons aborts absolute accept accounting acct activity acts actual actually add addr address addresses adds adjusted adm admiesw advanced affected afterward allchans allocate allocated allow allows altered anywhere appearing append apply arcane arp assumes ata attach attached authdebug authdisable authdisablexx authentication authentications background backwards bad becomes behavior belong bits block blockcmp blocks bno boot boots bucket buffer bugs builds buy byte cache cached caused caution cbno cfs chain channel channels character characters chat check checking checks cited clean clear clearacct cleared clears clri clunks cmd compares compiled conclusion config configuration connected connection connections consequence consistency console construct contained contains controllers controls convention copied copy copying count cpu create creates current cwcmd data date default defaults delete dest determined device diagnostic differences direct directories directory dirty disable disables disallow disasters discover discredited discs disk display don't doubly drive dskno du duallow dump dump1 dumped dumping duplicate enable enables endian endianness enter enters entries entry error errors ethernet examined except execute existing explicitly exsort exsort.c fids file files filesystem filled final finds fit fix flag flags flush flushes format formatted forward freelist fs fsconfig fsize fstat full functional garbage gate gateway gid gmt groups guesses halt halts hangup hit holes ide idea identified identifying ignores ignoring il incomplete incorrect incorrectly indirect initialize initialized initializing initially input integers internal internally ip jan jukebox jukeboxes ken key kick knee kprof kprofdata lad leader leaderxx leaves limits list loadcache locked locks longwords looking looks lot low machine machine's magnetic main maintains maintenance marvell mask megabytes member memory menus message messages minimal minus missing mode modified modify morecache moves mvstate names native necessary newname newuser noattach noisy non none note numbered numeric octal operating option optional options origin output outside overall overwrites owned packets parameters partially particular passwd password path pdir percent perm permission permissions pfile plan platter pointer prchain previously print printconf printed prints proc proceeding process processes prof profile profiling puts qid queries queue quiescent ram range rdall read readable reads reallocated ream rebooted rebuild received recently reclaim records recover recurse reduces referenced reflect regular remembered remove removes removing rename report reported reports representation required requires response restart restores resumes retried returning rip ripoff ripon ro rom roots route routing rules run running sanity sata savecache scanned scsi search searchtag seconds selects server server's shelf short sign size slightly slot slots smaller sntp sorted sorts source space specifically src stack startdump starts stat stata state1 state2 static statistics stats status stop stops storage string structure subcommand subcommands subnet successful summary superblock superblocks suspend suspended suspends sync sys system's systems table tag tags takes targets th therein thinks thompson time times toggles touch touchsb trace traceback tree trim trims try tunit type typed uid unaffected units updated usage user users using usr usual utilization valid verifies verify version volatile wbno wiser working worm wormeject wormingest wormoffline wormonline wormreset write writes wstat wuid fs 8/fs + 0ctl 1ctl bind control corresponds ctl current decimal descriptor devdup.c device directory discover dup dups fd file files format identical length level longer mode names note operation points port proc process properties read reading results returned returns serves source src stat sys target writing dup 3/dup + 0ics accessed accumulated addresses addressing allow allows applies arm arwe assist assumptions binaries binary breakpoints bugs cache caches cancels cmd code compared compatible compilers complete continuation controls conversions copy count counts cpu's cycle data db debugger delay detailed disassembly discussion distribution enable environment equality equals etc except execute execution existing extended extra faster fills floating formats frequency gatherer generated hundred id instruction instructions interface interpret interpreting itsp ki level load location loss machine machine's main memory mips mirrors mmipsco mmu mnemonics monitor nm offers optimization options performed pid plan powerpc precision print printing prints process produced profile programs qi read reference refers report rfork run running session similar simulate simulated simulates simulation simulators size slower source sparc src statistics stepping sun support supported sys textfile times tlb tracing traps triggered unimplemented unusual value vi working written vi 1/vi + 0intro 9fs abnormal access accessed accessible accessing acid acme acting address administering affairs aid alike allows alpha apc appeared architecture arm arriving aspects assembled axp backspace backup backups bapc belongs bin bind binding bindings binds bit boot booted booting bootstrapped bound bourne broke broken builds built causing character characters chess child cleans clue command's compiling complete completely compute computing con connected connections connects cons consctl control convention conventionally copies cp cpu cpu's cputype created creation current customary customized daily database databases db debugging deepthought default defaults del delete dependent descendent described desired details determined dev devices diagnostics dialog dies differences digit directories directory display distributed doc draw dump dumps e.g editor editors en encodes enters env environment error etc euro.9.font exec executed execution exit exits extra faces facility failure file files flag flags font fork formats fs full generic glue goes graphical graphics happen hardware heavy hierarchically historical holds independently index init initially instructions integrated intent interface interpreter interrupt intro introduction january june kernel kernel's keyboard keyboards kill kremvax letter level lib library lines lingers list loads locally login machine machines macro mail manipulating manual mapping member middle mips mnt month mount moving names namespace navigate net network newly news non note noticeable notification object objects objtype operating operations ordered outside overridden papers password path pc pelm pentium perform permits permuted personal pid plan plumber powered prefixed proc proceeds process processes processing profile programming programs prompt protocol provides publicly quick raster rc read reading reasons recover referenced related reminiscent remote replace replaces reports represents requests research reset resident respond retrieved returns rfork rio root run running runs rx sam saying searched searches section sends server servers services setting shell sign sometimes space spaces sparc specifies specify srv standard starts status stop storage string structured subdirectories subtrees successful switch sys system's systems tab tabstop tail tcp telnet term terminal terminal's terminals termination third time tmp tour tree type typed typical typically typing union unioned unix upas user user's using usr value values variable variables variant various version via visible volume ways window windows works writing written wsys yesterday 0intro 1/0intro + 0sa1 account add altered arbitrary array base bases bc bracketed bugs calculator character clear cmd compare constructions current dc dc.c decimal depth desk determines diagnostics digit digits distinguish divide dividend division divisor dsa duplicate entries error exceeds execute executed executing execution existing exit exponent exponentiate exponentiation factor file fractional further greater headers hexadecimal hoc input integer integers interaction internal interpret interprets kept la1 larger length letter level levels lower lyx main maintained max min multiplication multiply negative nested nesting non notation obey octal onto operand operates operation operations ordinarily output overall pla10 places points polish pop popped precision print printed prints push pushed quotient reasonable recognized recursion register registers relation remainder remains removes replace rest results reverse root s,sa s,sa,sb sa sa,sb sb scale scales shell sign source specify square src stack stacking standard stated store string structure subtract sy sys ten terminal text time treat truncated unbroken unchanged underscore unimplemented value values dc 1/dc + 0th accept access active additional age agefont ages allocimage array ascent attached baseline bigger bits bottom cache cachechars cached cachefont cachefonts cacheimage cacheinfo caches cachesubf caching calculated candidates cf char character characters chars clears collection common connects consists contains contiguous cooperate cooperation copy corresponds counter current data described describing destroying details device diagnostics display displayed draw draw.h draws edge emitted emitting entry error exist extent extents fields file fill fills font fontchar fontchars fonts freefont full graphics guarantees height hold horizontal ht image image;interline images include inclusive increased increasing indicate indices info initdraw int internally length libc.h libdraw library list load loadchar loaded loadfont loading loads lru maintain maintaining maintains max maximum memory min missing ncache needs nil noclr non nsub nsubf offset openfont overall owns p.x p.y parts permitting pixels plus pointed pointers posn proceed processed programs progress purposes range ranges read recently record rectangle replacement represent resets resize return returns routines rows rune runes scan schar selection server sfname short simultaneously size slot smaller solve source space src stored string stringwidth struct structures sub subf subfont subfontname subfonts success sufficient sum support sys tells time total translates typedef u.h uchar ulong unable unless updates updating ushort utf utilities value variable void widest widp width cachechars 2/cachechars + 0ul active attribute authorization authpass authuser bin bodylen buf buffer bugs byte char character chunked client clients closeit configuration connection connections continue contlen creating current custom data descriptor desirability details encoding entity enum etag expect expectcont expectfail expectother experimental extern fd file float fmt fresh_have fresh_thresh generic halloc hbodypush hbuflen hbufsize hcheckcontent hclose hconnect hcontent hcontents hdate2sec hdatefmt header headers hend herr hetag hf hfail hfields hflush hgetc hgethead hh hin hinit hio hiserror hload hlower hmkcontent hmkhfields hmkmimeboundary hmkspairs hmoved hmydomain hnone hokheaders host hout hparseheaders hparsequery hparsereq hpos hprint hputc hrange hread hreadbuf hredirected hreqcleanup hrevhfields hrevspairs hsize hspairs hstop hstrdup htmlesc http http1.1 http11 httpd httpd.h httpfmt httphead httpreq httpunesc hunallowed hungetc hunload hurlfmt hurlunesc hversion hvprint hwrite hxferenc ifmatch ifmodsince ifnomatch ifrangedate ifrangeetag ifunmodsince implementation include included info initialization input int io layer len length libc.h libhttpd library lines list lower max message meth mxb nil okchar okencode oklang oktype optional pairs parameters params particular persist persistent pos private range ranges reads reject remaining replog reply req reqtime request requests rough routines rune search seek sent server size source sp specific src stop string strings struct submission suffix supports sys tag tags te time timeout tokens transenc transfer transferring type typedef u.h uchar uchars ulong uri urihost va_list val value vermaj vermin void vsave weak worthless xferbuf xferenc httpd 2/httpd + 0x000000ff 0x000055ff 0x000099ff 0x0000bbff 0x0000ffff 0x005dbbff 0x008888ff 0x00ff00ff 0x00ffffff 0x448844ff 0x4993ddff 0x55aaaaff 0x7f 0x7f00007f 0x8888ccff 0x88cc88ff 0x99994cff 0x9eeeeeff 0xaaffaaff 0xaaffffff 0xeeee9eff 0xff00007f 0xff0000ff 0xff00ffff 0xffff00ff 0xffffaaff 0xffffff00 0xffffffff access accommodate aligned allocate allocated allocating allocimage allocimagemix alpha applications array background bit bits black block blue bugs byte bytes bytesperline cache chan channel channels char clip cloadimage cmap8 col color colored colors components compressed comprising computation contained convenient coordinate copied correspond creates data dblack dblue dbluegreen dcyan ddarkblue ddarkgreen ddarkyellow deal depth described descriptor dev dgreen dgreyblue dgreygreen diagnostics display displays divisor dmagenta dmedblue dmedgreen dnofill dnotacolor dolock dopaque dpaleblue dpalebluegreen dpalegreen dpalegreyblue dpalegreygreen dpaleyellow dpurpleblue draw draw.h dred dtransparent due dwhite dyellow dyellowgreen enum equals error errstr exchange execute external extracted failure false fd file files filled fixed flag format freeimage freeing frees getwindow graphics green grey1 grey2 groups horizontal id identifying ignoring illumination image image's images include increases initialization insufficient int integer leave leaving leftmost length libc.h libdraw loadimage mapped mechanism memory mixing mod moving multiplying multithreaded namedimage nameimage ndata necessary non obtained occupied offset onto opaque opening overall packed paint partially particular performs permit pixel pixels pointer predefined premultiplied presented processed programs provide publication published publishes range ratio readimage reading reads rect rectangle red reference regardless region remaining repl replaces replicated replication representative resources return returned returns rgb rgb16 rgb24 rgba32 routines run scan server setalpha share sharing significant similarly simulates source space specifies src starts storage synchronized sys threaded tightly time tones transparent u.h uchar ulong unloadimage unrelated user using value values void wider withdrawn wordsperline writeimage writes writing allocimage 2/allocimage + 0x000016f5 0x0000a988 0x0000bf1b 8.out abcds acid acidleak acidleak.c additional address algorithm allocated allocation allocations allocator ansi ape arenas aux bin binaries binary block blocks blue bright bss bugs bytes cmd code color combined comment comments completely consume contains count counting created dark data decreasing decribed default depend depends determine directed echoes editing environment es examined examines extended faster fields file fill finding fragmentation freed generated getcallerpc graphic graphically headers i.e id ids image images indicate inspect inspecting instance internal kernel kmem leak leaked leaks leaky lens lib libc list longer looking lost magnifying malloc mark memory names necessary nr ones option options output overall padding page pid pixel pixels plan pointers points pool pool.acid pool.c port posix print prints process process's processes programs rc reachable realloc red registers representing represents require requires res rio root running sed segment segments sending setmalloctag seven shared sharing shell site size sort sorted source space specifies speedy src started string stripped structure style summarizes summarizing summary sweep sys tags textfile total umem unless usage view width window yellow leak 1/leak + 0x0000f8cc 0x14,r29 0x16c8,r29 0x7fffd7c4 0x7fffeeac 8.out accessed acid acidinit active add address addresses addsrcdir adjacent admit allocation allow alpha append architecture args argv argv0 array asm assignments assume attached attaching attributed automatically bin binary block blocks bpdel bpset bptab breakpoint breakpoints bsrc bugs built builtin bytes casts char character clears cmd codes commas complete complex conflict consecutive cont continue convert core counted counter cpu creating ctl current data db debug debugged debugger debugging declared default defined definition definitions defn defunct delete dependent determined diagnostics directories directory disassemble display distinguishing dump e.g edt enabled env escape est etc examining except executable execute executed executing execution exits expr expression expressions extant facilities false file filepc files finished float floating floats fmt forcing forks format formats fpr func further gpr halt hard headstr higher id ignores image indirection inferred input inspect instruction instructions intb integer integers invoked kernel kill kqw language level lib libraries library linenumber lines linked list listed lists load loaded loop ls ls:386 lstk machine magic main main:argv manual manufacturer mar mem memory mips mipsco mk modified movw near nearest newproc nonempty notable notation note objtype obtained obtains operand operator operators option options output outside override overriding partial pcfile pcline phil pick pid plan pointer port pread prefixed prefixing previously print prints proc process processes processors profile progargs program's programmable prompt proposed provide pwrite qualified r31,0x0 rc redirect registers regs renamings repeated repeatedly replaceable reported require resume return returns rob run running rw s.next s.val sam scaffolding segment select selection sequences setproc setting share shell signs source sourcefile space spr src stack standard startup stat statement statements step stepping stk stop stopped stopping stops store str string strings structures subscript subscripts sunsparc surrounded symbolic symbols sys tail termination text textfile timezone trace tracing trump truss truth type types unary untrump untruss user using val value values variable variables wait whatis win window winterbottom yield acid 1/acid + 0x003e 0x1bb0 48x48x1 48x48x2 48x48x4 48x48x8 512x512x24 512x512x8 astro bell bill bill.1 bit bits blanks character chooses color com comma commas constants contains correspondence deep depths dict directories directory display displayed distinguish divided domain eight endian entries entry equal exist expression faces file files finally firstly forgiving format further gates grey hexadecimal hierarchy highest historical hold icons image images joy labs letter lib list log machine machinelist machines mail map mapped maps message microsoft.com names odd pairs pixel pixels programs purpose read recorded regular research running scan seemail sending serve shorthand size sizes somewhat stored subdirectories subdirectory sys text times tweak twenty typically user users usr various ver face 6/face + 0x00ff a','b','c',0 a._b a.u abc accommodate add added adds allows anonymous anonymously ansi ansitize applies arg array arrays ascii assignment assumes au becomes bugs cast casted casts cd char character characters checking cmd comments compile compiler compilers complain conf configuration confuse constants constructs contains context control conversion ctype.h d','e','f',0 data declaration declared def default define defined definition derived described dialect dir directed directories discussed displays endif environment equivalent equivalents etc expecting explicit expressions extra features file files flow format formatting fortune full grammar greek handled header hexadecimal i.ansi identifiers ifdef ignores include initialize initializer input inserts inside int integer introduce isalpha isdigit kinds l'a l_abc letters libc.h library libregexp limiting lines list lists macros main mainly names necessary option options overeager overridden pairs parameters parser particular passes pike places plan pointer pointers pragma preload preserving print process processing produce productions programs promotions provided pt read reading recognizes reconstruct references reflect regexp regexp.h regexp.h.ansi reinst.u reinst.u1 removes rename renaming replaces replacing require requires restricts resub.u resub.u1 rewrite rewrites rewriting rob rune running searched separately short signed silence source src standard statically stops string strings struct structure structures sys tag test third toupper transformation translate translates translating translation type types u.h uchar uintptr unicode union unions unix unix's unsigned unused using va_arg value values varargck void warnings wide wider written xxxx ansitize 1/ansitize + 0x0a 0x0d 0x7f abbreviations accent acme acts additional ae alt alternate arrow ascii asterisk backspace backward bishop bit block capital caps carriage character characters chess co compose comprising cons contained control convenience crlfs currency cyrillic del delete denominator design difference digits digraph digraphs dollar e.g enter escape eschews exactly extreme feed file files format forward fraction full generally generated generates gnot graph greek grep guiding hexadecimal idiosyncratic illustrated interpret intro key keyboard keyboards keys king knight labeled latin letter letters lib lie ligature list lock looks lower machines magnum main mathematical micron mnemonic names near newline note num numerator obvious operator operators option ordinary pad pair particular pawn pc pg piece pieces plan programs queen regular related repeat repeated return rio rook rules rune runes sam script scroll scrolls sequences shorthands sign slc sloppy sometimes somewhere sorted sparcstation ss suitable superimposition superscript superscripts symbol symbols tab table tcs terminals type typed typing typists unicode upper using usual utf value variant view windows wk ya yields keyboard 6/keyboard + 0x1f 0x7e 0x7f 0xa 0xb 0xc 0xd alphanumeric ascii bugs carriage centric character classification classify coded control converts ctype ctype.c ctype.h defined delete digit eof exclamation false fopen formfeed hexadecimal horizontal include ing integer isalnum isalpha isalpharune isascii iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit letter libc libc.h lookup lower macro macros newline non ordinary original port predicate printing punctuation range rest return returning returns similar source space src sys tab table tables tilde toascii tolower toupper u.h upper value values version vertical visible ctype 2/ctype + 0x1f accept accepting access adding addpt adjacent affected algebra aliased aliasing aligned alignment aligns allows alpha ambiguities analogous angle angles anti applications arc arcop array arrow arrowhead assume atan atan2 axis background barb basic behaves behavior bezier bezierop bezspline bezsplineop bezsplinepts bg bgp bits black block blue boolean border bugs building built bytes calculation caller captures cases centered chan channel channels chantodepth char character characters clear clip clipping clipr clips closed color combine complementary compositing computer conceptually conditions control convenience coordinates coords corresponds cos cosine cosp counterclockwise cover covered created cubic curve data datops debugging default define defined defines defining deg degrees depends depth described descriptor despite destination determined diagnostics diameter differ differently digital dins direction disc discussion display distance douts dovers draw draw.h drawing drawn drawop drawrepl drawreplxy draws drawsetdebug dst duff dxors dynamically edge ellipse ellipseop encode encoded end0 end1 endarrow enddisc ending endmask endpoint ends endsquare enum equal equivalent error errors except explicit extant extended extending extent extra false fatal fields fill fillarc fillarcop fillbezier fillbezierop fillbezspline fillbezsplineop filled fillellipse fillellipseop fillpoly fillpolyop fills flag font fonts format formats forms freeing frequently further gendraw gendrawop geometric geometrical goes graphics greyscale height higher holding horizontal horizontally icossin icossin2 id identical identically ignores image images implementation implicitly include independent inside int intact integer integers interior intersect intersected intersecting intersection interval involved joining joins leaving len length level libc.h libdraw limit lineop lines list listed location longer macro majority management mask masks max measured memory methods min modification modifications modified modifies mp names ncomp necessary needed negative non notifies np npt ntsc nul null objects odd op opaque operation operations operator operators outline outlined outlining output outside parameter parameters particular periodic permits perpendicular perpendicularly phi picture pictures pixel pixel's pixels plane points poly polygon polygon's polyop porter portion positioned positive pp primitives proc procedure proceeds produced produces promoted proper provided pt purposes q.v quadratic radius read rectangle rectangles rectangular region regular repclipr repl replaced replaces replclipr replicate replicated replicates replicating replication representing requires resolves responsible restricted resulting returns routine routines rule rune runes runestring runestringbg runestringbgop runestringn runestringnbg runestringnbgop runestringnop runestringop satopd scaled screen sector self semiaxes serial series server shape shapes siggraph similar simply sin sind sine sinp sizes smaller smooth source soutd soverd sp specify specifying spline src standard stored stores string stringbg stringbgop stringn stringnbg stringnbgop stringnop stringop stringsize struct structure structure's styles subtracting suffices sufficient suffix sxord sys takes terminates terms text thick thickness tile tiled tiling tip touches translate translating transparent truncated turns type typedef u.h ulong undefined using usual utf value values variant variants various vast vertical vertically void width wind winding window windows write draw 2/draw + 0x2f8 0x337,0x430 0x3e8 0x3f8 0x43f 0xd0000 0xd1800 0xd3fff 0xf0000000 100base 100basefx 100basetx 100mb 100mbit 1024x768x8 10base 10base2 10baset 1600x1200x8 16mb 1d8f65c9a52d83c8e4b43f94af 3com 53c8xx 91cxx 9load a.b.c.d ability abit able access accessible accton acenic actions ad adaptec adapter adapters added adding additional address addresses adhoc advanced afish agp aha1542 aid allocation alphanumeric alteon am79c970 amd amd79c970 answer aoe aoedev aoeif apm apm0 appropriately armpit assumed asterisk async ata attach attached attribute audio audio0 audiox aui auth authentication authsrv autodetected autoexec.bat automatic automatically autoprobing av8 avanstar backed base based battery baud bed behavior bin bind bios bit blank blanking blaster block blocks boards boot bootargs bootdisk bootfile booting bootstrap bootstrapping bound bridging bt bug bugs built bus buslogic bytes cache calledraawaru can't capable card cards carriage cases cat cfs cga channel characters check checked chip chips chipset clear clone clones com com1 com2 com2:96,n,8,1,p combo command.com commas comments common compatible completely concentrators config.sys configurability configurable configuration configurations configure configured configures connecting connection consist console consulted consults contained contains controller controllers converted copper correct correctly cpu cpurc crypt ctl dance debugfactotum debugged debugging dec decided default defaults defined defines definition degpa degrees delay dell depend deprecated describe described desired detected determined dev device device's devices dge dhcp differing digital dir direct directed directory disable disabled disables discards disconcerting disk disks display distributions dma dos dos;c dp83815 dp83820 dpms draw drive driver drivers due dummy dummyrr dump duplex e.g ea ec2t echo eia eia0 eia1 elite elnk3 en2216 enable enabled enables encryption ends enormous entries entry environment equipment error ess1688 essid establish etc ether ether0 ether1 etherexpress etherez etherfast etherlink ethernet ethernetcard ethernets etherpair etherx ev exactly examine exceptions exclude experiment experimental express extending fa310 fa311 fa312 fa410tx factory factotum factotumopts fast fast16 fast4 fast8 fd feature fiber file files firmware flag flags force100 format formats fossil fs full fullduplex further fx fxfd ga620 ga620t gate generates generic gigabit gigabytes graphic hard hardware hd hex hoc hold holding i.e id idea identified identifier identifies identify identifying ieee iff igbe igbepcie ii iii images include included includes inclusion inclusive increasing initialization initially input instant integrated intel intelligent intellimouse intended interactively interesting interface interfaces interrupt interrupts intersil ioexclude ip ipconfig irq irq3 irq4 isa item iteration kernel kernel's kernelpercent kernels key key1 key2 keyboard kfs lack lan laptops latter leading length lengths level levels lies limit limited lines link linksys list listed live load loads locate logic longer looks lost lsi lucent m10g machine machines main maintains managed management map mapped marginally match maximum maxmem maxsd53c8xx media mem memories memory menu menuconsole menudefault menuitem messages mga4xx mii minimum mode models modem modemport monitor monotonically motherboard mount mounting mouse mouseport ms multimaster multiprocessor multisync135 mylex myricom names naming ncpu ncr ne2000 near necessary needed needs negotiate negotiated net netgear network newer nobootprompt nodummyrr nodumpstack noe820scan noetherprobe nomce nomp none nopcirouting norealmode noscsireset notably notice nousbprobe novga null numeric nvr nvram nvrlen nvroff odd offset ohci omitted ones operating operation option optional optionally options origins orinoco override packets panic parallels parameter params parity partition partitioning pass password path pc pccard0 pci pcie pcimaxbno pcimaxdno pcm100 pcmcia pcmcia0 pcmciax pcmpc100 pcnet pcs percentage perle physical picks places plan plan9.ini plan9.nvr pm pn pnic pnic2 po pool port ports prefixed presented printed printing prism pro probed probing procedure process processed processes processor processors programming programs prompt prompted properly provide provided ps2 ps2intellimouse purposes puts ram range ranges rarely read readnvram reads real realtek receives reception recognised reconfiguration relevant remainder remaining remote representative require reserved reset resets resident response restricts returns reuse rhine root rootdir rootspec routing rtl8139 rtl8169 run sa saving sb16 scan scanning screen script scripts scroll scsi scsix sdc0 searches seconds secstore sections sector select selected selecting selection selections selects semiconductor sensitive sent separator serial serial0 series server servers services setting settings setup sgi shelf shell sic sign similarly simpler sink sis sis900 size sizing slot slots smc smc91cxx software solve sound space spec specific specifier specifies specify specifying sta stack standard standby star startup station stats stop stops string subsequently suffice superseded supersets support supported suppress suspect suspend switch switches symbios syntax systems table tag tapes temp terminals termrc test tested textual tfd third tightly time timeout tmp traditional transmit tried troublesome truemobile ttc turns tx txfd txkey type types typical typically uart uarts uhci ultra umb umbexclude unencrypted unique unit unless unlike unspecified usb usbx user using value values variable variables variant various varying velocity venti vesa vestige vga vgasize vgbe via via8237 video virtual vmware vt6102 watch wavelan wavelanpci wd8003 wd8013 whitespace wireless works worm write writing xxx plan9.ini 8/plan9.ini + 0x3bc bind communicating control correspond corresponds data dev devices devlpt.c dlr drive driver file files fine interface interfaces latch lpt lpt?data lpt?dlr lpt?pcr lpt?psr parallel pc pc's pcr port ports printer printers programs provides psr reading register sends source specifiers src status sufficient sys write writing lpt 3/lpt + 0x3ff ability access adding additional address addressed algorithm alternatively arbitration assign assigned base bind bios bit bits boot bugs bus card card's cards cat chosen class colon configurable configuration configured configuring conflict conflicts contains control csn ctl data decimal describe determine dev device devices devpnp.c digit digits directory disabled discovered driver echo enabled enumerate enumerated enumerates enumeration existing expressed fields file files fixed fn formatted grep hex hexadecimal id identification identifying idstring index instance intended intention interface interfaces interrupt isa letters limited list logically lost manufacturer mapped mechanism memory needs note obtain particular pci periods plan9.ini play plug pnp pnp0 port programming provided provides range raw read reading regions register registers remainder representing reset resolve resources returns sending serial served serves settings size slash source space specifying src strings sub substring summary sys text textual textually third time traversing type typically unique unlock upper user using valid value values various vendor via video write written yields pnp 3/pnp + 0x3ff00000 4.4ux accessed address allows alpha amd64 arch archctl architecture assigned barrier base bind bit byte cache caching capability class clock cmpswap cmpswap386 cmpswap486 code coherence combining compare contains control cpu cputype data dec default descriptor determined dev devarch.c device enabled equivalent explicitly extension fields file flag fourth framebuffer global hardware hexadecimal i8253set include indicating inportb intel interrupt interrupts ioalloc iob iobfd iol iow irq irqalloc kernel length level lines machines mb386 mb586 memory messages mfence mhz midst mostly mtrrs nop offset ordwr page pc pge physical port ports precedence presents processor protected range ranges rate read reads recover reflect reflecting reflects region registers requests return seek setting showing sizeof smaller source space specific speed src style subset swap syntax sys sysfatal takes textual third timer trap type uc uchar uncachable unsigned user using via video wb wc wide wp write writes written wt yield arch 3/arch + 0x7c00 0x7e00 3½dd 3½hd 5¼dd 5¼hd 8.5gb 9fat 9load 9loadusb 9pccpuf 9pcf 9pcf.gz abfprw absence accepted access active add added address addressing adds allocated appending arbitrarily architecture archived arenas arithmetic assigns assumed attempt attempting attribute automatically based baw bcfnprw bfile bios bioses blank block blocks bloom boot bootable bootblock booted booting bootmgr.tgz bootstrap bring bugs bw bytes cache cd cfs chained chains check checks choices chosen cluster cmd collisions common compilable configuration configuring confused conjunction considerations consist consists constants contains contiguous contiguously convention conventionally copied cp create created creates creating csize ctl cylinder cylinders data date debugging default defined delete density described descriptions detects dev device device's df dfvx directory disabled disc discussion disk disk's diskette disks disksize display distinguishes divided division doesn't doing dos dos.1 dos.2 dossrv double drive driver due e.g editor edits emit ending ends enter entire entries entry equivalents etc evaluates evaluating exceed executes exist exists exit explaining explicitly expression expressions extant extended extending extents extra fail fails fat fat12 fat16 fat32 fd0disk fdisk fifth file files filter finally finds fits fixed flag flags flash flashes floppies floppy format formatted formatting former fossil fs fscfg gets giga gigabytes goes hard highest hold i.e ignoring image include index inform initialises initialize install installed installs interactive invoked isect jump jumps keeps kept kernel kernels kfs kilo label larger largest lba lines linux linuxswap list listed listing load loaded loads logical looks ls manager manner mark marks master maximum mbr mbr.bootmgr mbrfile mega memory message mistakes mode modified modifying mount ms names neither newdot newly non nor note nresrv ntfs numbered numeric nvram offset older omitted op operates operating operators option options output overlap overlaps parameter partfs particular partition partition's partitions pass pbs pbslba pc pcs physical physically places plan plan9 plan9.ini plan9.nvr plan9partition plus prefixed prep prepare prepared prepares previously primary print printed prints programs prompt pseudovariables q.v quit ram raw read reads record refuse refuses regardless regions regular remaining repeated reserved resolves respective rest restore root running runs scaled scans sd sdc0 sdu sdu0.0 sdxx secondary section sector sectors sectorsize self sensible sent share similar similarly simulate size slots smart source sources space spans specific specify src srv starts store stored subpartitions suffix suitable supported swap synopses sys systems table takes tera test textual time tmp total track translate type types typically typing unique units unix unless unnamed unpartitioned unused upper usb using valid value variable venti via volatile warning windows works write written prep 8/prep + 0x7c00 0xf0100020 16mb 2gb 8.5gb 9fat 9load 9loadask 9loadusb 9pxeload active acts adapter adapters address addresses addressing alas allocated alt appended appropriately asks attempt attempts auto automatically baud bios bios's bios0 bioses bit block boot booted bootfile booting bootp bootstrap bugs capable card caveats cfg character choices chooses chs cn code com commercial common compatibility compiled compressed configuration configured considerations console constraints contains contiguously contrast control convention copies copy cpurc ctrl cylinder data de default defaulting del described details detects determine determined determining device devices dhcp dhcpd differs directed directly directory disk disks display dos dossrv double download drive drivers due duplicated e.g encountering ensuring enter entered enters entries entry error ether ethern ethernet executable execution extended extensive facilities fat fat16 fd fd0 fdisk file files filesystem finds fits floppy follow format fossil further gzip hard hardware header host initialize initially input install installed int interfaces kept kernel keyboard kfs knows larger lba ld ld.com leaving lib limitions linear list load loaded loaders loading loads located location mac machine machine's manager manual maps master mbr mbrs medium memory menu mode modulo mostly mounted ms ndb network networks non numerical obtained omitted operate operating operation option options overridden parses particular partition partitioning partitions path pathname pbs pbslba pbss pc pci perform physical plan plan9 plan9.ini ports prep prepared prints prioritized probing procedures proceeding proceeds profusion programs prompt prone pxe rate read reading recognised recognized record refers required reset reside resides response root run running safer sd sdb0 search searches searching seconds sector sectors select sequences serial server size slightly source space specifiers specifies src starts stops stripped suitable summary supported supports switches sys systems table tables technique termrc tftp time transfers try type typed typically understand understood unfortunate units unless upwards usb user using version via virtual ways xxxxxxxxxxxx 9load 8/9load + 0x7fffffff 0xffffffff a.out access accessing addr address addresses adjusted allocated allocation applicable application architecture architectures associating asstype assumed attached attachproc base based beswab beswal beswav bio.h bit buf build byte bytes char class code comprises construct constructs contained contains corefd crackhdr creates current data default dependent described describing descriptor determines diagnostics differs disassembler dynamically eight endian error errstr executable executing existing extends extern fails fd fhdr file files findseg floating foffset former fp fpregs generic get1 get2 get4 get8 global header highest id images implies include independent index indicated indicates initializes instruction int interface interprets invokes kernel kflag latter leswab leswal leswav level libc.h libmach library list load loaded loadmap loads location logical lowest mach mach.h machbyname machbytype machdata machine map mapped mapping maps marks matches maximum mem memory modification multi names necessary negative newmap non object offset offsets opened opening overlapping parameter parameters parses performs pid pointed pointers points proc process processor programs proper provide put1 put2 put4 put8 quantities quantity range read readable references reflects register registers regs related remain representation resized resulting retrieve retrieves return returned returns routines running section seg segment segments selection selects sequences setmap similar size source space specific src stack static stored structure structures supported swapped symbol sys tables target text transferred transfers translate translated type u.h uchar ulong unable unaffected unused unusemap user ushort using val valid value values variable variables virtual vlong void writable write written mach 2/mach + 0xc0000 0xc0068 0xc0076 0xc0090 0xc0200 0xnnnnn 1024x768i 135mhz 31.5khz 35.5khz 48.4khz 50khz 60hz 6200mx 640x480x 64kb 65mhz 87hz 9gxe64 9gxepro 9load accelerated acceleration accelerator accordingly achieve actually add adding addition address alias allowable anywhere ark2000pv ark200pvhwgc ati att20c490 att20c491 att20c492 att21c498 attr attribute attributes aux bandwidth baseline basic beyond bios bit blanking block book boot bt485 bt485hwgc bugs builds bus bytes card card's cards cases ch9294 character characters chip chips chipset chipsets chooses clgd542x clgd542xhwgc clgd546xhwgc clock clocking clocks code combination comments common commonly complex components comprises consists constraints contains continue controller controllers conventionally copies cpd create ct65540 ct65545 ct65545hwgc ctlr current cursor cyber938x cyber938xhwgc data database default defaultclock defined depths described describing desired details determine dev display dot doubler duplication dynamite edition ega ehb entire entries entry env equivalent et4000 existing expected explained extension extensions fairly ferraro file files fills formalizes fortunately frequency generator generic grade graphics gui guide handle handles hardware height hercules highest hiqvideo hiqvideohwgc historic horizontal hsync ht hwgc i.e ibm8514 icd2061a ics2494 ics2494a identification identifier identifies identify inc include included indicates initialization initialize initialized input integrated interact interconnected interesting interlace interlaced internal internally kernel laboratories laptop lib limit linear lines link loaded lucky mach mach32 mach64 mach64lp mach64xx mach64xxhwgc manual match matching maximum meaningful megabytes membw memory mga2164w mga2164whwgc mhz mmmmm mode modern modes monitor monitors multi multiplexing multisync multisync65 ndb nec necessary needed neomagic neomagichwgc nnnnn non note numbered occurring offset overwritten page pairs parameter parameters parsed particular particularly parts pci performance pixel pixels polarity previously printed pro programmed programming properties provide provided ramdac range rate reasonable recognized rectangle refresh registers remainder replacing representing required requires resolution rgb524hwgc rgb524mn richard s3clock s3hwgc save sc15025 scope searched selected serial shb sheets shifted shown similarly simply sometimes sony space speed starts steps stg1702 straightforward stream string subsystem subtype super support supports sync t2r4 t2r4hwgc table technology third timing total trio64 tseng tvp3020 tvp3020hwgc tvp3025 tvp3025clock tvp3026 tvp3026clock tvp3026hwgc type types unit unless unspecified v8.00n value values variety versa vertical vga vgactl vgadb vgasize video virge vision864 vision964 vision968 vl vre vrs vsync vt w30c516 w32p width window worked writing vgadb 6/vgadb + 0xc0045 1024x768x 1280x1024x 1376x1024x8 1600x1200x8 640x480x 640x480x1 640x480x8 800x600x 9load actions aux bail bcdilpvv bios boot bugs can't card cases caused cmd color configuration configure configures confusing confusion controller controllers current cursor database default depth depths desired devices disable display displays don't dram dump e.g effort encounters entries entry env error especially exit expected file files fingertips follow graphics hardware height hex identifying include indicates instructs interlaced ip laptops lib list load loaded loading looking memory message mode modes monitor monitors mouse operation options output override palette pan pc performed physical plan9.ini playing points prevent print printing provided read redirect register registers resolution screen screens setting size sizes source specifying src standard stealth string strings switches sys text tmp trace try trying type using usual valid value values various verbose verify vers vesa vga vgadb via virtual whatever width wrong vga 8/vga + 0xda 0xe7 0xea 0xec 9load access advanced ahci amd aprint assigned ata atapi attempted auto automatically based bind bios boot bridge bugs cache complete connected connection control controller controllers ctl data debug debugging default descriptors detected dev device devices disable discovered disk download.intel.com drive driver drivers drives en enable enabled enabling enclosure enhanced enterprise error esb existing fail failed features file flush flushcache fully gently hard host hot http iahci ich ich9 ide identification identified identify idprint intel interface led legacy letters level lowest management manually media messages missing mode multipliers needs newly none nop noted null numbered offline onward outstanding partition parts pc pdf periodically persistent port portreset powered print printing prints programming property provided provides raw reached ready removed reset return rev1_2.pdf sata satai sataii sd sdahci sdata.c sdctl sdiahci.c seconds send serial serialata short size smart smartdisable smartenable source speed src standard status storage string support supported supports swappable swapping sys technology toggle transition typically unless verbose via sdahci 3/sdahci + 0xe000 accepts access actions affect ambiguities ambiguous amount analyzer argc argv arising assigned associate besides break bugs char cmd code codes compile compiled compiler conflicts context converts couple create declared default define defined described diagnostic differences direct edition effects environment error errors essentially file files finally fits full generated generator grammar hall handling higher implement include incorporate inner input int interface interpreter johnson kernighan lex lexical lib libc libc.h loaded longer lr main manual mentioned messages missing names non option options output parser parsing pike precedence prefix prentice preprocessor print produce programmer's programming programs prototype recursive reductions references regulated relevant reports research return returned reverses rob routine routines rules sethi short sort source specification src statement statements stdio stdio.h stem structure symbol sys tables temporary tenth terminals text token tokens transitions translation translator undocumented unix user using utf value values version void volume workings write writes y.acts y.debug y.output y.tab.c y.tab.h y.tmp yacc yacc.c yaccpar yaccpars yydebug yyerror yylex yyparse yacc 1/yacc + 0xf1000000 0xf7000000 0xf9000000 0xf90012345 access addresses adjacent adjusted aggregate align aligned alignment alloc allocate allocated allocation allocator allotted amount arena arenas assumed attempt attempts behavior bit block block's blocks bookkeeping boundary brk byte bytes caller callers calling carrying char coarser combat common complete constant constraints convey corruption crashes created curalloc curfree cursize dangling debugging defragment defragments dereferenced detected diagnose distinguish doing double e.g ease easier enables encompass entire entry enum equal error exceed exclusive external extra facility fills finished flags forgetting format fragmentation freed frees garbage grows happened i.e include innards int interface internal kernel's lastcompact leak leaks legal lesser libc libc.h lock locked locking logging logstack looking magnitude malloc malloc.c manage management markings maxsize mechanism memory merge mergeable message minarena minblock modifying modulo move moved moves moving multiprocess newly nfree nil non notice notification notifies nsize nul obtains offset op or'ed orders output panic pointer pointers pool pool.c pool.h pool_antagonism pool_debugging pool_logging pool_noreuse pool_paranoia pool_tolerance pool_verbosity poolalloc poolallocalign poolblockcheck poolcheck poolcompact pooldump poolfree poolmsize poolrealloc pools port possibly previously print printed prints private programs protected provide provides ptr quantum receipt recognizing related releasing remains request requested requests resize retried retrieved return returned returns reuse rounded rounding routine routines runtime safely satisfied sbrk search setting setup size sizes slows smallest source space span specifically specifies src strict strings struct structure style successful summary surrounding suspect sys tickles time total try tweaks typedef u.h ulong unallocated unchanged unlock unlocked unlocking unspecified unused user using valid validate value varies various vector via void volatile walk ways whenever wish written xalloc pool 2/pool + 0xff abort actual add additional addr address adjust aid allocated alt.c altc argc args argv attrib aux auxiliary bbytes bdescriptortype belongs bigger blength bugs builds byte bytes cached caller calling care cases cfd char class classes classname closedev cmd comes common conf config configdev configuration configurations configure configures confused considered constants control convenience corresponds count counted counterpart created creates creating csp ctl cval data ddesc ddprint define defined desc described descriptor descriptors desirable determine dev dev.dir dev.usb devctl device device's devices devs df dfd dir direction directly directory dirs dno doing dprint driver drivers drop due dump eadapt easy easync ebulk econtrol eg ein eintr eiso emallocz embedded endian endpoint endpoint's endpoints endpt entry eout ep ep3.0 ep3.1 error estrdup esync eunknown executes exercised extern extra failure farg fields file files finally finddevs fixed fmt fmtinstall fn format former fprint get2 get4 goes header heavily helper hexadecimal hexstr holds id idem identifies identifying ids iface implementation include includes incref index indicate info initially input int int,char intended interface interfaces interval isotype issued issues keeps kept kernel knows lib libc.h library list loaddevstr loaded loads located locates lock low ls ma macros main malloc mallocz match matchdevcsp matchf matching max maximum maxpkt memory messages mf milliamps mode naltc nconf nddesc ndirs necessary needed nep niface nil notifying null numerous obtained ones opendev opendevdata openep opening opens operate operation options output p,v packet parameters parse parses parsing particular path perform performed pointer print proc process product programs proto protocol provide provided provides purpose put2 put4 raw read reading ready ref reference references release released rely remember replies representing represents req request requests require requires resources rest retries return returns routine sent serial setup sid similar size source specific speed src stall stalled standard startdevs starts strdup string struct structure structures style subclass suitable supply symbols sys takes thread thread.h times toolkit tools transfer transferred transfers type u.h uchar ufmt ulong unknown unparsed unstall usb usb.ddesc usb.h usbcmd usbd usbdebug usbdev usbfs user using valid value values vanishes various vector vendor vid void wrapper write writing written usb 2/usb + 0xff access add addresses al algorithm alignment assuming atof attach attempt bank base beyond bind bit block bootstrap boundary buffer bugs byte bytes cache characteristics code constraints contains control conventions copy correctly create created creates ctl current data decimal default dependent described dev devflash.c device device's devices diagnostics directly directory dram driver drivers ecc ends erase erased erasing error except executing existing extra fails file files flash flashctl flashfs flush format ftl hardware hexadecimal hides higher hold id implement impose imposed include initially instance integer interface kernel level lie lines locked logfs logically manufacturer memory nand none nor note numbered numeric octal offset operations page paqfs parameter parent particular partition partitions physical platform prevents primary programmed programming properties protectboot protected protection provides ranges raw read regardless region relative removed removes representing represents reprogramming reprograms required requiring restores restrictions return returns revealing segment segments selects serves setting size sizes source space specifier src standard starts status string strtoul success supported sync synopsys syntax sys system's textual type types typically underlying unit units using value values width write writes writing written flash 3/flash + 0xfffd analogous arrived beyond byte bytes char chartorune chr coded complete considered contains conversion convert copied copies count decoded defined differs encoding es1 exactly format full fullrune guarantee include includes incompletely input int legal length libc libc.h maximum none nul null obtain occur occurrence original pointed pointer port programs represent required return returned returns routine routines rune rune.c runeerror runelen runenlen runes runetochar sequences source src str stream string substituted substring sys tcs time u.h utf utfecpy utflen utfmax utfnlen utfrrune utfrune utfrune.c utfutf writes rune 2/rune + 0xfffd arabic ascii atari big5 bit central character characters chinese cmd continues conversion convert converted converts correctly cp cyrillic czech date default deprecated described diagnostic dutch encoded encoding encodings error errors euc european file finnish forces format gb gb2312 generates gost greek guesses hebrew hku html ibm ics independent input interprets iso japanese jis jp jx kanji koi koi8 latin list lists lv microsoft ms msdos ocs option original output particular pc plan plus portuguese prevents print processing recognizes reporting rune runeerror runes russian scandinavian shift slcv slovak source src st standard stream substituted summary supported supports sys tcs thai tis translate turkish ujis unicode unknown utf utf1 value variety various verbose version tcs 1/tcs + 0xffffffff accessed accesses acid activated active addition address addressed addresses advance advanced advancing alignment allocated allow allows alpha alternate append approximate architecture architectures argc ascii assigned associative assume assumed assumes asynchronously attach automatic backtrace bad base becomes beware binding bit bitwise breakpoint breakpointing breakpoints bss bugs byte bytes c'th calculate calculated caused causing character characters closed cmd code compared compiler complement condition conjunction consisting consists contained contains contexts continue continued continuing control controlled convention copy correspondence count counts cpu cputype create created ctl current data db debug debugged debugger debugging decimal decremented default define defining delay delete dependent diagnostics digit digits directory disassembling disassembly disjoint disjunction display division don't dot double due dumps dyadic e.g eight elided enclosed entered entire entirely entry environment equal error escape established evaluated examine examined examining except executable executed executing execution exist exit exp expression expressions extant external failed fetch fetched file files finding fire flag floating format fraction frame frames further halt heap hexadecimal i.e id identical image import impossible include incompatibilities increment incremented indicated initialized initially input instruction instructions integer integers interpretation ints kernel kremvax length letters limit lines list loaded location locations lower machine machines magic main main.argc manage management manufacturer's manufacturers map mapped mapping maps mask masked match matched matches mem memfile memory mipsco miscellaneous model modifier modifiers modify monadic motorola moves multi multiplication names nearest necessary negation newline nm non note notes null octal offset oh omitted operators optimization optimized option options output overlap page pair parameters parse parse:b path pc pending permitted pid plan plus precision prefixes print printable printed printing prints proc procedure process processes processor produces program's programs provide purpose quadruples radix range rc reached read reading received recently recorded refer region register registers relative released remainder remaining remote remotely repeat repeated repetitions represent reproduce requests reside resolves responses rest results returned returning returns rounded routine routine.name run rune runes running saved scheduled section segment segments select selecting sent series signed similar similarly simulate sixteen size skipping slots sometimes source sp space specifies specify src stack standard statement static status step stepped stop stopping stops stored stream string style subprocess subtraction sunsparc supports suppressed symbol symbolic symbols syntax sys tab table tabs terminal termination terminator test text textfile threaded times total translated translation type typed ublock unaffected unchanged undefined underscores unless unnecessary unsigned update upper using utf valid value values variable variables various via width write write:b writing xnn db 1/db + 100ms 9sys access atomic atomically attempt attempts avoid awakened blocking blocks buffered bugs callers calling canlock canqlock canrlock canwlock carelessly chan channel common condition contains context counts cpu current data deadlocks decref decremented decrements discouraged discussed distinct easily empty.l ensures error especially except execution expensive fork full full.l generate granted grants guard handles happen haveval heuristics holding holds implement implementation include incref incremented increments initialized instructions int intended interface libc libc.h library libthread limitations lock lock.c locking locks longer mallocz manage memory missed mkchan moreover non note obtain obtained operation periods pointer points port prevent primitive proc process processes programs protected protecting protects puts qlock qlock.c qlocks queueing qunlock reacquire read reader readers recv ref ref.c reference regular release released releases rendez rendezes rendezvous replaces resulting resuming return returning returns rfork rlock routines rsleep runlock rwakeup rwakeupall rwlock rwlocks send shared sharing simultaneous sizeof sleep sleeping sleeps source spin src strictly struct structure successful suspend suspends switches synchronize synchronized sys task tasks thousand thread thread.h threaded threadrendezvous threads time tries tying typedef types u.h unlock unlocked unsuccessful using val value versions void wakes wakeups wlock write writer writers wunlock yield lock 2/lock + 100us accepts access accessed baud bind bits block blocking break byte clear clock communication configures control ctl cts data dcd dependant dev device devices devuart.c directory disable disabled dsr dtr eia eia0 eia0ctl eia0status eia1 eia1ctl eia1status enable fifos file files flush format hangup include input lasting legal level levels limits maximum milliseconds modem non obey odd output parity port ports queue queues rate read reads representation rts send serial serve signal source src status stop supported sys textual timer times trigger uart unrecognised value values writes uart 3/uart + 104.135.in 128.39.14.65.in 2.31.178.204.in 9powerboot 9pxeload a.root access acting active add adding addition addr addr.arpa address addresses addrs administrative alias aliases am ampl.com anna anna.cs.bell anna.cs.research.bell answer answers appearance appended asking associate assume assumed astro.txt attached attr attribute attributes authoritative authority automatically awk b.root base behalf bell bignose.cs.research.bell bin bit boot bootf bsd bugs bypasses bypassing bytes c.root cached caching caller's canonical carded classless clone cmd cname communicates companies complete con concert configured conn connection consult control controller convert corporate correctness create creates cron cs cs.bell csquery d.f.ip6.arpa daily data database databases dbfile debugging decimal declare default defaults define defining delegated delegating delegation details dev dhcpd dial dir directed direction directory directs disabled displays dj.cs.research.bell dns dnsdebug dnsquery dnsserver dnsslave dnstcp dom domain domain's domain.com domains don't efficient elsewhere enabled entirely entries entry env established etc ether ethernet exchangers exists exit exits expressed external fd00 fields figure file files finally finds firewalls flag forms forward forwarder frequent further future generate generated generates gets goal goes hash helix helix.research.bell hexadecimal hill hint holds host host's hosts hosts.1127 hosts.equiv hosts.txt hour ignore imports incoming inconsistent indicate indicated inform input inside interface internal internet interval inverse invoked invoker ip ip6.arpa ipconfig ipmask ipnet ipquery ipv4 ipv6 it's keeps labs labs.com learned lib library lines list listed looking lookup lookups lower machine machines mail mail.research.bell maintenance mapping matched matching maxage maximum mb message messages mh microsoft minimum mips mkdb mkhash mkhosts modified mount mounted murray mx names nameserver nameservers namespaces naming ndb ndbipinfo necessary net net.alt net1 net2 netmtpt network networks nibbles nil non nonetheless nor norrs notably notice notification notified notify ns ns1.cs.bell ns1.our ns2.cs.bell ns2.our nslocum.cs.bell offset option optional options organization output outside owning packet packets pair pairs particular particularly pass person plan plan9.bell port postmaster pref presotto print printed printing prints profitable programs prompted prompts properly protected provide provided proxies ptr pure pxe queries query range rattr rc read reading real reasons receive received record records recursion recursive refresh relaying reliability remain remote replies request requests required requires research research.bell resolution resolve resolved resolver resolver's resolves response responsible restricted results returning returns reverse reversed rfc rfc2136 rfcs root router.our routines rr run running rx scripts search searched searches seconds seek send sends sensitive sent series serve server servers servers.net serves serving severely significant situation slave slaves smaller soa sometimes source space specific specifies specify src srv srx standard started starts status straddles straddling style subnet subnets subtree subtrees successfully suitable superseded supplies synonym sys sysname systems tack target tcp tcp53 there's time track transfer transfers translate translated translating translations truncated ttl type udp underfoot unified unlike unreferenced uucp value values varying vex.cs.bell via whatever whenever wild wildcards windows writing written www www.cs.bell xxx zone ndb 8/ndb + 10gb 20gb 20mb 5gb aux baw blocks cf cmd control creating ctl cylinders data default dev device disk diskname disks disksim disksim.c echo expect fdisk file files geometry handling heads image initialized kept lba manner mbr memory message mostly mtpt non option plan9 post prep presents programs sd sdxx sdyy sdzz sector sectors setting simulations simulator size source src srv srvname sys tar test testing track tvf unless written zeroed disksim 8/disksim + 10mb 1mb 250mb 36gb 500mb 512mb 6mb able access accessed accesses accessing active additional addr address addressed allocate allocated allocation allow amounts announce announces append appended appending approach approximately archival arena arenas arenas0 arenasumsleeptime assigned assuming avoided background backup bcmem bitmap bits block blockcachesize blocks bloom brief bucket buckets bugs burst byte bytes cache caches cat check checksumming choose cmd collect comments completed completely complicated component components compress compresses compression comprise concise conference config configuration connections considerably consists constitute consult consulting conventionally costly critical current damaged data debugging decompressed decreases default definitely derive described details detect determines device dir directory disabled discussed disk disks distribution divide documents dorward duplicate e.g easy effective effects efficiently eliminates employed enable entire entries entry enumerates equal equally error exist exit expected extracted false fetch file files filled filling fills filter finally flag flush flushdcache flushicache flushing fmt fmtarenas fmtbloom fmtindex fmtisect footprint foreground format formatted formatting full functionality gigabytes graph graphing greater guidelines handled hashed helps hget hi hold holds hour http httpaddr httpaddress httpd.c icachesleeptime icmem image implies improve include increases indefinitely index indexcachesize indicate indicated initialized insensitive instantly integer internal internally introduction isect isect0 isect1 kept kilobytes larger ldrs level lines list lo locate location log logging logically logs lost lump lumpcachesize lumps main maintains managed maximum measurement megabytes mem memory million milliseconds minimum moved names nblock necessary needs netaddr network nhash non notation offline omitted operation optimizations optional optionally options override overrides page param parameters particular partition partitions pass path percent percentage performance pieces plan plus png port positive possibly prefetched prefetching primary process produce profitably properly protocol provide provides queue queuewrites quinlan raid ram random range rate raw read reads ready reasonable rebuilt recently recorded refers relative request requests requires reside response responsible robustness run runs score scores sean section sections sent sequential served server server's services serving setting sha1 shut simultaneously size sized sizes sizing sleep slower slows smaller source sources specify split src srv standard starts statistic statistics stats status storage stored storing structure structures subsection successive suffixes suggested summary sustain sys sysname systems tcp technologies third thirds throughput time times tmp total totals tree typical typically undocumented unevenly units unrecognized update updates urls usage usenix using usual value variable variables variation various venti venti.conf version wait waste web webroot write writes written xindex xml zeroed venti 8/venti + 1127.group 1127.passwd 9fs acquire actual add addr1 addr2 address addresses allowing assumed attaches attempt authenticates authentication aux basis bin bopp bugs bypassed choose client clients cmd comprise connections conversation crash credentials daemon debug decimal default defined dev directories drv dump employed entire entry everyone export exported file files format getport gid gnot groups ha handle handles host id integer laughable lib libsunrpc list machines mainly map mapper maps messages mnt mode mount mounted names naming ndb network nfs nfs.c nfsmount nfsserver nobody notify null obtain octal older op operating operations option options particular passwd path paths perform perm port portmap post posted pp presented print prog programs proto protocol queries rc reasonable received remove replace request requesting return root rpc rpcs running script sent served server servers services serving session sh simply source speaks src srv srvname startup stat sun sys systems table tcp test traditional translate translates translation triples trusts typically udp uid umnt umntall unix unmount unmounted unset user users using verbose vers version wstat nfs 4/nfs + 128kb 16khz 256kb 32kb 44.1khz abr add additional adds allow ath athonly audio autoconvert average based behemoth bit bitrate bits blocktypes break bugs byte cbr cdfs channels compresses constant conv copyright crc create cutoff data dd de deal default defaults desired disable display don't emp emphasis encode encoded encoder encoders encoding error exact experimental fhg file files fixed foo.mp3 foo.wav forces frame frames frequency games generates gnu highest histogram histograms hprv http i.e informational input iso it's juke kb khz largest lightly lowest mark masking maximum mid minimum mode mono mp3 mp3dec mp3enc mp3input nohist non oint ono options orce original output pcm playback playlistfs print produces progress protection quality rate raw rehabilitated report resample routines sampling setting sfb sfreq silly smallest source src standard stereo stream streaming swab swapping sys tag tereo undocumented variable vbr via voice wav www.sulaco.org xing zillions mp3enc 1/mp3enc + 128kb 9660srv 9fat 9jsv access accessible actually allocated allocates allows arrange attempt attempts attribute attributes bin bind bit bits block boot booting bugs cache caused cd cds channel characters choice clients clusters cmd communications component concept confusing contains contiguous contiguously corresponds creates creation debugging default describing descriptor dev device directly directory disk disks dmappend dmexcl dos dosmnt dossrv drive drives eject ejection entire except exclusive execute explicit explicitly fail fat fd0disk fields file file's files fills flag flags floppy guarantee helps holding ignore incrementally input instance instructs interprets iso9660 joliet kernels kfs laid map merit microsoft mode motor mount mounting mtpt names non null operating option output overloading partition permission permissions pipe plan posts prep prevents provide provides ram raw rc read removing restricted rom rsv script scripts semantics server setting shell shorthand sierra similar simultaneously size source spec specification spit src srv standard stat stored succeeding succeeds sys systems th therefore third treatment tree trees try typically undefined unicode unless unmount user value verbose via write wstat dossrv 4/dossrv + 12h34m 9fs abbreviations abell abell1701 add alcyone alllabel alpha altitude angles appended approximately arc arcseconds ascension ast asterism astro astronomical astrophysical atlas azimuth becomes betelgeuse bit black blank block box brief bright brighter brightest brightness catalog catalogs catalogue catalogues cd center centered centers chart circles class classes cluster clusters cmd code collect collects color comet compact complement constellation constellations constelnames converting coordinates copyright corporation correct cost cover covered cross crts cull current data database dec declination decsize default defect degree degrees depth descriptions designations designed details digitized dim discover disk disks display displayed displays distance distributed double draw drawn drop dx dy e.g earth's eclipse ellipses except executing execution expand extent externally eye files finally finder flat flatten flattening flattens flight format formats full galactic galaxies galaxy gamma gb getmap globular goddard greater greek grey gx hardware hd holds horizontal ic1234 identified identifies identifying images implements improving index inferior input insensitive installed institute's interface it's item items juke keeping keyed knot kt labels larger latitude lcd leading legibility lesser letter letters lib lines listed listings location locations longitude looks lookup lower lunar magnitude magnitudes manipulations map mapped mars maximum meager megaparsecs member messier messier's minutes moon motion multiplicity naked names nasa nb nearest nebula nebulosity nebulous necessary negative ngc ngc1234 ngc1300 ngc2000.0 nogrey nogrid nolabel non nonexistent nonstellar notation object objects oc omitted option options ori orientation orients orion output outside partial patch patches pd penumbra permission phase photographic pixel pixels pl planet's planetary planetarynebula planets plate plates pleiades plot plotted plotting popular population positions positive precisions prefix pretty print prints proper provided provides publishing q.v quotes ra radius range ranges rasize read refer references region remember representative represents richness rom roms run running sao sao12345 scale scat science screen section series shadow shown size sizes sky smithsonian solar source space specific spectral spelled square src standard star stars stippled stored sufficient suitable sun superior suppresses survey symbols sys telescope tenth thin time times touching translated triangle triple trouble try type types umi uncertain understood unknown unlabeled unverified upper uranus usual value values variability variable vertical visibility visual wider window zenithup zwicky scat 7/scat + 15cf 15ff 16cr 38fr 38fr11 access adm administration affligem antwerp arend aria belkin configuration configured connections coraid corporate cs9000 delirium dns doom duvel eth0 eth2 ether0 ether1 ether2 firewall gloom gorka's host infrastructure intel interfaces internal intranet isolated kapellen kijkuit koninck kvm leffe low mac machine macromate net net.alt netgear network networks npe's omniswitch outside panel patch patchpanel perle plan port ports realtec running sape's servers soekris switch typically uplink wiring network 9/network + 197.pdf a.k.a advanced aes aes_decrypt aes_encrypt aesbsize aescbc aescbcdecrypt aescbcencrypt aesctrdecrypt aesctrencrypt aesstate aesxcbcmac authentication block block_cipher blowfish bugs bytes chaining cipher ciphering ciphers counter cryptographically csrc.nist.gov ct des dsa elgamal encryption fips fips197 http identical implement include initialization int ivec key keybytes len libc.h libsec libsec.h message mode mp mp.h nr operations performed preferred prime pt publications rand random rc4 replaced reused rfc rijndael rk rsa running sechash secstore setupaesstate setupaesxcbcstate source src standard strongly sys test u.h uchar ulong unlikely unpredictable vector vectors verified void xcbc aes 2/aes + 1kb 32vfs 4kb archival archives attached berkeley block blocksize byte ca cmd constructed cpio cpiofs data default derive disk edition era ffs fifth file files flag flags format formats fs fs.c gzip highly id images inquiries interpret interprets intro introduces mapping media mount mountpoint numeric optional passwd password plan pre ramfs raw read reported research seventh sixth size source specify src status stereotyped stored strings substantially sys systems tap tape tapefs tapes tapfs tar tarfs tenth tp tpfs traditional unix user using util.c v10fs v6fs vax zip zipfs tapefs 4/tapefs + 1mb access address arg buf buffer bytes cmd connected constant data detail diagnostics entries entry error errstr exit extra file formats fstat hello hexadecimal input integer interprets invokes literal lqm ls manual message modify null options osx output pointer print printed prints read return returns section similar source src standard stat status strictly string style succeeds sys syscall test times unknown valid value write syscall 1/syscall + 1pub abbreviation able access accessing actual adaptable additional appended applications applies assignment augments author based basic befored behavior bin built bytecode cast category caught checked class cleanup clear colons combines comp.lang.python comp.lang.python.announce compilation compiled complete conditions connected constants contains control controlled controls converted core dates debugging default defaulting defined depend dependent described describes detail developer developing device digit directories directory disable discarded disclaimer displayed distributed distribution division doc docstrings documentation documents documnetation dos dynamically ecommended eeded embedding entails enter entire environment eof equivalent error except exception exec_prefix executable execute executed executes executing existant existing exit exits explained explicitly expressed extended extension extensions favor fields file filename files finally fixdiv.py float format front ftp ftp.python.org full fully generally generate global guido hack hints http i.e ignore import imported include indentation initialization initialized input insensitive inserted inside inspect installation installed int integer intended interactive interface internal internet interpreter interrupt introduction invalid ioerror issue issued keyboardinterrupt language leading lib libraries library license licensing list loaded located location locations loop mail main manipulated manipulations manual match matches matching message messages mixes mode modify module modules newlines newsgroups non note nterpreter object objects occurs omitted operator optimizations option options oriented output packages parnassus parsed parser path pathnames pep performed prefix primary print printed printing prints programming project prompt prompts provides pub pyc pydoc pyo python python's python.org pythondebug pythonhome pythoninspect pythonoptimize pythonpath pythonrc.py pythonstartup pythonunbuffered pythonverbose pythony2k qualification qualified quits raise raises read readable reads reference referred remaining remarkable repeatedly replaces repository request require resembles resources return returns rossum rules running script scripts search searched searching section semantics sensitive session shell shell's showing signal signals significant sigpipe silently simplest site skip sometimes source sourceforge.net space spaces specific specify specifying stack standard starship.python.net statement statements stderr stdin stdout string strings subclass syntax sys sys.argv sys.path sys.ps1 sys.ps2 sys.stderr systems tab tabs terminates terms test thereafter thousands time times tools totally trace triggered tty tutorial twice types typical unbuffered unhandled unique unix usage user using usr value values van variable variables version via viewed warn warnall warning warnings warranties website whitespace wizards worth written www.python.org www.vex.net python 1pub/python + 2.out aa accept access acid ansi ape assembly bugs characteristic checking cmd code comments compilation compiled compiler compilers compiles compiling complain concept constant contains conversion cpp db declared def default define defined definition definitions dependent described dir directories directory doesn't don't driver echo effective enable ending environment etc examining except executable executed exist fails file files handlers header howard ids ieee include included independent insert interface iso language leave lib libap.a libraries library limited link linking links loaded loader loaders loading loads locale machine manipulation messages minimal minimally mk names nm object objtype omit omitted operating optimize option options output pcc pcc.c phase phases plan portable posix posix_source pragma preprocessed preprocessing preprocessor print prof profiling programs prototypes related routines send setting signal sought source src standard structures support sys terminal trickey type undef undefine user using v.out vararg variable version void warning warnings pcc 1/pcc + 2.out accumulated active annotating arg automatically based brief buffer calling clock cmd code collect collected compressed continue controlled correlated counter counts ctl current cycle data decreasing default dev device display dr dynamic echo elapsed elided enable entries entry environment etc exec execute executing file files fills fn forked forks formatted frequency full graph hold hz image indented initializes instruction intended interprets interrupt kernel kernel's kpdata kprof kprof.c linker loaded loader measured measures milliseconds mode modern multiprocess ncall objtype operating option options output parent pcs percentage pid powerpc presents printed prints proc process processes produced producing prof prof.c prof.out profile profiled profiling profsize proftype programs provided read recorded recursive recursively returns routine run running sample sampling seconds setting share similar size source spaces spent src stored symbol symbol:time sys table target text time times tprof typically user using variable prof 1/prof + 200909.la 9fans accept accepted acdnor achieved acme ad add added adding additional admin aid aon appended applies arch archive archived archives archiving ask asking asks attach attachment attachments attempts automatically aware balle based basic behaves blank box browse browsing button cache cached cd clean cleanup cleared click cmd comming composition considered considers contains convenience convenient convention conventions converted cooperate copy copying corderoy correspond corresponds create created creates cron cse.psu.edu current customize date dates dealt debug debugging december declared decoded default delete deleted deleting deletion deliver delivered delivering delmesg described destination determine dho diagnostics diet difference digest digests dir directly directories directory diretories discarded display displays dmexcl dmtemp dupplicate e.g edit edited editing editor edits enables encouraged entire events execute executed executing exist existing expected expression faces facilities fco file files flag flags folder folders format former fs full further generate generates grep guide handle handling header headers hi hierarchy honoring ids immediatelly inbox include includes index indicated indicating inline input inputplus.co.uk inserting interface juan kept la language latter letter letters lines list listed listens listing listings lists live locate locking longname ls mail mail's mail2fs mailbox mailplumb main maintain manuel march mark marking marshal martin mbox mdir mention message messages mg mime mlist modified month monthdir move moved msgs msgs.nemo mspool names necessary needs nemo newbie newfolder non note notify obtaining octopus oldmbox olive omsgs ones operates operation option optional original out.3452 outgoing output pam panel panels parse parsed parsimonious particular path paths pdf permission permit pipeto places plan plumb plumber ports possibly post prefix prepare print process processed processing produce produces programs provide questions quickly ralph random randomized raquel raw re read reader reading ready refer reference refreshed regarding regexp relative remove removed renames replied replies reply replying reprensenting respectivelly retrieve reunion rm run rune runes sam save script scripts se search section seem select selected selecting send sender sending sends sent september seq serial series server shared showing shown silently similar simply somewhere source spam specifies spools src standard stated store stored storing strictly subdirectory subject sys takes text therefore time tmp today's tool toolkit tools tries uncertain understands unix unless unread upas upasfs update user user's users using usual versions virtual window working write writes writing msgs 1/msgs + 20kbs agui append artist audio bandwidth bell binds button buttons caveat cds clicking collection communal computer contains conversion converter created current database decoder decompresses def define demonstrations described device digital directory encoder equipped especially execs exercise expand fair fast fetch file files format games gbytes graphical gui identities interface isolate jukebox keyboard labs larger lib library license licensing list lists match mechanism menu mips mouse oct oked options pac pac4dec pacenc performance places play played pointing pool private queues rawmap real recall research runs saves script search seek shell song songs source src string structure sys text time title tmp tool totaling toy typing user walk audio 7/audio + 20name 25addr absolute addresses alcatel alphanumeric ascii attribute attributes backslash backspace based bin blanks braces capitalize carriage character characters cmd concatenated connects consisting consult consults contact contacted copied corporate create curly database debug default defined delete described detail detailed diagnostic diagnostics directory dispatch employee employees error escape;meaning escapes ev ex except existing exits fewer file files flag flags format formatted formatting formfeed ft full greatly handles htel implicit improved incoming independent index indexed input integer internal interpretation irdb jersey justification justify letter letters lf lib libpq list listen lists literally liz location login lookups lucid marker match matches maximum meant minimum modules necessary newline nj obtained octal omits ooo operations option optional options output outputs padded pathname port post pq pqgen pqsrv prevent print prints queries query quoting range rc read recognized record records regarding relational relative requests required rerun results return returned returns run separator server shell similar skip source specifies speed src standard status string strings substitutions successful superset suppress syntax sys tab table tcp tcp411 telephone texas text time truncated tx typical typically value values verbose vertical width yielding zip pq 1/pq + 20th beware bugs cal cal.c calendar century christian cmd colonies considered current england era historically january larger letter lower month months naive omitted prefix print printed prints produced refers sep source src sys try twelve cal 1/cal + 22nd cmd copies file files input interprets lines newline option output p.c page paginate pass quit rest shell source src standard stopping sys user wait waiting p 1/p + 26e522ade2bbb2a229 accomplished account actions acts actual add addition additional address agent allow allows answer anyone apop append asaddr attack attempt attr attribute attributes auth auth_challenge auth_proxy authenticate authenticating authentication authinfo authsrv automatically avayalabs.com boot boyd by.factotum bytes callee caller card cards challenge channel chap checks chosen clear client cmd collection comments communicate configure confiming confirm confirmation confirmed confirming conjunction connection consist consists contains control convention cpu cram create cryptographic ctl data database ddknpus debug debugged debugging decryption default defining delete delimited delkey denied depend depends describe described determines dev dictionary directory disabled distinguish dk does.it.matter doesn't dom domain don't e.g ek embodied encryption ending entering error ether0 ethernet exactly exclamation exclusive execution exist exists exit extend external factotum fail failed fails fetch fgui fields file finally follow format formats forth further generated graphic haveai hex hexadecimal hides host hostowner i.e id identify identifying identity implied inbound include independent indicates input interface interleaved isn't kept kernel key key1 key2 key3 keypair keys kp kq length level lib library list listing lists log looks lucent mail maintaining management managing mark marks marshaled match matches matching maximun message messages metaprotocol microsoft missing mit.edu mnt mount mschap mtpt mutual mutually ndb necessary needed needkey needs negotiate negotiation nerdsrus network non none null nvram ok ones opened opening option options ordered outbound owner p9any p9cr p9sk1 p9sk2 pair pairs particular party pass password passwords performed phase plan pop3 possessing ppp pptp precede presents presotto private proc proceed process processes programs prompt prompting prompts proof proprietary proto protocol protocols prove provided provides query querying random read reader reading readnvram reads remain remote replace replies reply represents request requests require required requires response responses restarted restricting retrieve retrieved retry return returned returns role routines rpc rpc's rsa rsc run running runs secret secstore section sections secureid select selectors send server servers setting shared short shuttling similar size sometimes source space speak speakfor specifies specify specifying src srv srvname ssh ssh_genkey sshserve standard started starts stored strictly string strong structure subsequently succeeded successful supplies supports sys tag tagno tb template templates time tls toggle tokens toosmall total tracing tuple tuples turns typically unchanged unformatted unhides uniquely usage user users using val valid validating value values variant verb verbs via vnc waits wep whenever window wireless write writes writing written x.com xxx yes factotum 4/factotum + 2abcx advances ansi arrow background backup bar black bottom buffer bugs button care carriage character clear cmd color colors columns communicating con connecting cooked cr crnl dec display echo emulate emulation emulator enter entries environments equivalent escape exit expected file fills font foreign forward fresh hold host input instance interpretation key leave linefeed lines log menu menus middle mode modes monochrome move names necessary newline nl nlcr non options page pause plan poor potentially print proceeding processing provide raw rc receiving recovered replaces reset resize return rich right_key rio rows running scheme screen screenful scroll send sending sequences session setting shell snarf sort source src ssh starts substitute sys systems terminal text typed unix using via visible vt wait window xterm vt 1/vt + 3440ct 3480ct accupoint accupoint.c add approximation automated automatically aux baud behavior bin bugs button buttons click cmd communication compatible configuration configure configured configures cons control converting cpurc cursor default dependent determine dev device difficult dr due e.g effectual enable events exited extra fail fast flag generate generates ii initialization intellimouse interface keypad knows laptops lib limitations logitech mice microsoft mouse mouse.c mouseport option overcomes peculiar pipefile plan9.ini pointing port portégé process processes produce profile properties provides ps2 ps2intellimouse queries rate reasonable regular release released repeat reports restart rio running script scroll scrolling serial setting simulation simulations slow source src string sys termrc time toshiba type types user usr wait wheel mouse 8/mouse + 386proto 9fat 9load 9pcdisk active administration autoexec.bat autoexec.p9 backed backup bin boot boot.ini boot.p9 bootfloppy bootplan9 bootstrap bootwin9x bootwinnt byte config.p9 config.sys contained copies copying creates current dev directory disk distribution drive edits environment exist fat file files fileserver floppy floppydisk formats initialize installing kernel kfs lib loader machine main maintain menu minimal mkfs mounted msdos.p9 msdos.sys nt option partition partition's partitions pc personalize plan plan9.ini plan9.nvr prep prepare private programs proto prototype provide rc removes runs scripts sd sdxx server setup.9fat setup.disk setup.kfs source sys sysconfig systems time update updates user usr variable various ways windows zeroed update 8/update + 39cdeffkjrtv 39cdektv accept adjacent alpha animated animation appearance assemble attaching automatically avoids behavior bits black bmp bugs button capability card channel character click clicking clumsy cmd color comment compression control convert converted converts creates current cursor debugging decompression default defined del diffusion disable display displayed displaying displays doc driven en.wikipedia.org error exit exits extra fast fields file files floyd forever format formats frames friendly full gamma gif gif89a.txt glory graphics grey height http ico icon icon's icons image images improve index input interface invokes items itu jpeg jpg lets list lml loop loopcount mapped mask masks menu merge milliseconds motion move movie msec navigation negative netpbm.sourceforge.net offers option options originally output page panning particularly pause picture pictures piped pixel plan playing png pops ppm ppm.html primarily process processing produce programs read reads rec rendered represent representation representing resulting rgb rgbv saves scale scrolling selecting share sight source space spec specifies src standard steinberg stop suppress sys t81.pdf takes time times togif toico topng toppm tr transindex translates transparency typically typing uncompressed undertaking user using value video view width wiki window windows windows_bitmap write writing written www.w3.org yields yuv jpg 1/jpg + 3d12h abc accessible append arithmetically binary bugs character check circuit cmd combined comparisons compatibility complain concatenate condition cons construct current default deprecated descriptor dev directory dubious echo enclosed epoch eq equal evaluates evaluation exclusive execute exists exit expr expression extraneous false fildes file flags ge greater grouping gt higher hours identical inefficient integer integers le length letter letters lt match meaningful minus minutes mixed modified months ne negation newer non nonstandard notice nt null ok older operator operators option ot parentheses permission plain posix precedence primaries primitives process purported quotes rc readable recognized represents return seconds short signs size source specific src statement status string strings switch sys temporary test test.c time twelve unary understands units unprocessed value won't writable wrong test 1/test + 3des accept add address adm agent allocated allow allows args attempted attempts attributes auth authenticate authenticated authentication authlist authsrv aux blowfish bruce bugs capability carriage cfiimpprrw challenge channel character choice cipher cipherlist ciphers client clients cmd colon con confirmations connect connection connections cons control controlling convince cooked copy ctl daemon daemon's data decipher default defined deprecated des described descriptor details dev differentiates dir disable disconnecting discussion domain doubtful echo enable encrypted encrypting encryption error escape establishes except execute executed exit extract factotum favor file files flag forwarding full functionality gathered generate grep grounded hold host hostname hosts identified input insecure interact interactive ip key keyring keys legitimate lib list listed login looks lu machine mandatory manner matches menu method methods mnt mode moderate mounted mtpt namespace namespace.noworld necessary net netkey network non none notify noworld offers option optionally options ordered outgoing output password passwords perform personal plan posting preferred presents presumably printing programs prompt prompts proto protocol protocols provide pseudoterminal pseudoterminals raw rc4 read received rejected remote reports request requests requires response responses return returns rfc rfc425 rfcs ring rings rsa rsa2ssh rsagen run running runs satisfied schneier's scp screen secure securid sends server server's servers services session shell sides size somewhat source space spaces specify src srv ssh ssh's sshnet sshserve stack standard started strip style support syntax sys systems takes tcp time tis tis_authentication toggle token tradition triple try unix unlike unrecognized usage user users using usr valid variation version via whenever window ssh 1/ssh + 3des_ede_cbc accepted active alert alerting alertno alerts algorithm algorithms allocated anti application authentication automatically base based behavior bind boundaries buffer bytes canceled categories category changecipher channel channels clear client clone closed code comes communicated communications configured connection contains control controlled converted correspondence ctl current data datain dataout datum decoding describing descriptor descriptors device devtls devtls.c dial digest digesting directory divided enable enc encalg encalgs encin encode encoded encout encrypt encrypting encryption error errored established exactly exchange executed extra fail fatal fd fields file files filter filters follow format further future halted handin handout handshake handshaking hash hashalg hashalgs hashin hashing hashout headers hexadecimal hungup implement implementations implements include incoming initialization initially inserted integral interrupted isclient issued key keys layer length level lines list listen localclosed mapped maximal maximum md5 message messages mutual names net newencin newencout newhashin newhashout newly non notify numbered offending opened opening operation operations optional outgoing outside packed padding pass pending populate port potentially precede protocol protocols providing pushtls rc4_128 read reading reads ready receipt received reclaimed record records remoteclosed renegotiation reserves responsible return returned returns secret secretdata secrets secure security selected send sends sent server session sha1 significant similarly size sockets source space src ssl3 sslv3.0 sslv3.01 stats status string stripped subdirectories successful supported synchronize sys tag tagged tags tampering terminate text textual time times tls tls1 tlsv1.0 trailers transport traveling tries underlying unless user using valid value vectors vers version versions visible write writes writing tls 3/tls + 3½dd 3½hd 5¼dd 5¼hd accepted access bind control ctl data density describing dev devfloppy.c directory disk drive drives eject factor fd0ctl fd0disk fd1ctl fd1disk fd2ctl fd2disk fd3ctl fd3disk file floppy format formatted include interface level messages partitions prep read reset returns serves source src string sys type floppy 3/floppy + 48x48x access active address addresses aliasmail altering answer answered answering append appended arg auto automatic bin box caught cc chmod contained create created default delivery destination details directories e.g es everyone exclusion exclusive executable existing exists faces file files filter flag forward forwarded forwarding go.fishing gone gone.addrs gone.fishing gone.msg gremlin header helper icons incoming invoke invokes l.mbox l.reading lib list lists lock log loops machine machinery mail mailbox mailboxes marshal mbox message mlmgr mode mutual nedmail none option options pages path piped pipeto pipeto.lib preparer processing qer rc readable reader readers recipients remove resolved responder responses return rewrite run script seemail send senders sends sent shell smtp source spam spool stop sys tagged truncate unless upasfs user user's username using vacation writable mail 1/mail + 4gb 500gb access address affligem alone antwerp arend attached audio authentication backed boots box cabinet classical commissioned configured console coraid corporate cpu cron cs9000 daemon daemons delayed delirium device dhcp disk diskless doom drives duvel enclosure enclosures experiments file files firewall flash floor fossil imap independent inside intel it's jukebox kapellen kijkuit koninck lab leffe linux located lockable machine mail main micron mostly network opened outside pair pairs partition pc perle plan port ports printer purpose rack redirects replace requests runs serial server servers serves shares soekris specialty sr1520ml stand static storage supply switch systems tempirarily temporary tftp ticket update usb various venti via virtualization xen servers 9/servers + 4mm 6eq 8mm accepted accessed adapt addressing ansi applied applies ata attempts audio automatically backwards basic bench betrays blank blanking block blocks brief bugs byte bytes capacity cd cdload cdpause cdplay cdresume cdstatus cdstop cdunload changer check checks class classes cmd code complete completion comprise computer concerning condition constants consumption control coverage current data default descriptions destination details determine dev device devices directory disk disks documents drive driver drives effort einit eject ejection endl engineering entire erase error errors estatus exabyte exact exactly exception executed exercising file filemark filemarks files fixed forces format forwards further global groups host howmany identifies implies incomplete ingest initialize input inquiry integer intended interactive interface internal internally interpretation invert investigate issued issues jukebox kernel larger lba length lengths level limit limited limits load logical low luns maintains manipulate manipulates manual max maximum mechanism media medium memory message method missing mmc mmove mode modeselect modeselect6 modesense modesense6 move multimedia nbytes necessary needed negative note notion odd offset ok older ones opened optical option options origins page pages parameters particular partition pause performs pi plain play playback pma positioned positions powered printed prints probe processing product provides publications purpose quoted raw rblimits rc rdiscinfo read reads ready recoded reference regardless remaining report reports reqsense request requests require respond response results resume retrieves retry returned rewind rezero rotating rough rtoc rtrackinfo rudimentary rw scsi scuzz sd sdc0 sddev sdxx seek seeking select ses session shuffling size slot smc source space spacing specific specification specifies specify spelled spelling spin src standard starts status stop style subset successful supported supports suppresses synonyms sys table tables tape tapes target targets test time toc tolerant track transfer transferred transfers transport type types typically unit units unless unload value values variable version whence willing write writes writing wtrack www.t10.org x3t9.2 xfer scuzz 8/scuzz + 5am 9fs aan accept accepts access accessed accesses added address addresses anded announce appended aside attach attached attempt attenuated auth authentication background based belonging bin bit bits block blocks bugs buses byte cache cached cards cf checking choice clients cmd collyer combination compatible compensate compilation compiler config configuration connection connections contains continued controller convert cope copied correct cpu created cwfs cyclones daily datakit date dd december deciding declarations default deny dev device devices directly directories disabled disc disk disks don't dump dumped dumps e.g easily effective emelie enter equivalents etc ethernets except executed existing exists expects faster february file file's files filsys fixed fossil frozen fs fsconfig full geoff grow halt halted hold holds hostowner ide il images implements incompatible intended ip ipv4 ipv6 issue it's jukebox jukeboxes ken kernel kernel's kernels key kfs label labels layout location lp ls magneto main maintain maintains map march marvell medium minimal mips mirrored mm mmdds mode modified month names network newer newly noauth non none notably notation note noworld null numbered numbering nvram occasionally omitted operated operation optical options original output overcome overloaded packet parameters passwd pci permission permissions plan portion practice privileges process property protocol provide quinlan read recent recently recompilation recover relabeled replacement requires restart reverse reversed root run runs sata scanned scsi sd sean secstore serve server server's serves similar size sniffing software source specifically speed src srv standalone stock string subdirectory suitable superblock supported sys system's systems tcp thereafter thereof thompson tickets time times tls tmp traffic underlying uniq unlike unwritten user user's users using usual various vc verify version versions walking warning worm wren write wrkey wrong yesterday yyyy cwfs 4/cwfs + 5am 9fs access accessed added alone anded appended aside attach attenuated authentication background based belonging bin bits blocks boot bugs cache cached checking combination compiler computer configuration connection continued copied created cwfs daily date dd december deciding deny deprecated directories directory disabled disk disks dump dumped dumps edition effective emelie emelieother etc ethernets except february file file's files fourth frozen fs fsconfig full halted hill holds il ip kfs lp ls magneto main maintains march minimal mips mirrored mm mmdds modified month mount murray newly noauth non none noworld null numbered occasionally optical output overcome packet permission permissions plan portion practice privileges process property protocol protocols provide quinlan ran read recently relabeled required requires root sean serve served server serves similar sniffing software source specifically speed src srv stand subdirectory sys systems third tickets time times traffic uniq unwritten user user's users using vc version versions via walking worm write yesterday yyyy fs 4/fs + 640kb acceleration access accommodate actualsize align aligned alignment allocates allows aperture appropriately arch ark200pv ark200pvhwgc attach bind bios bit bits black blank blanking blanks blanktime boundary bt485hwgc bugs byte cards chan chip chips clgd542x clgd542xhwgc clgd546x clgd546xhwgc closectl color combined compliant configuration configure configures consists control controller controllers ct65545 ct65545hwgc ctlr current cursor cyber938x cyber938xhwgc data default depth described dev device devvga.c disable disabled disables display displayed displays dpms drawing drawinit drawn driver echo enable enables encoded engine et4000 filling follow format full gc graphics hardware height higher hiqvideo hiqvideohwgc hsync hwaccel hwblank hwgc image implement inactivity includes indicate initialize inside larger level linear list located low mach64xx mach64xxhwgc map memory message mga2164w mga2164whwgc minutes mode monitors mouse moving neomagic neomagichwgc note nvidia nvidiahwgc openctl opens optional overlay packed palette palettedepth pan panning particular pc performed physical pixel pixels port portion precision properties provided provides read reading recognize rectangle registers require resources returns rgb524hwgc roms s3hwgc screen screen's sent setting settings setup signals size software source src strings support supported sys t2r4 t2r4hwgc terminates timeout tvp3020hwgc tvp3026hwgc type unblanked valid value values vesa vga vgabios vgactl vgaovl vgaovlctl virtual vision864 vision964 vsync wide width writing written yuyv vga 3/vga + 6aflqr added additional address addresses adds announces anyone attempts automatically average buckets button bytes clicking cmd considered contains count datapoint debugging default delay dest destination determine display displays dn don't dropped echo endport error expires exponentially extra fast flood gping gping.c graphical graphs header headers histogram hogports hogports.c i.e icmp icmpv6 id included increasing incrementing internet interval ip ipv4's ipv6's larger length live lost machine maximum menu message messages milliseconds minimum mounted ms mtpt names nbuck net.alt network options output packet packets percentage ping ping.c ports presents print probe processes proto quiet randomizes range received recorded replied replies reply report reported request requests response returns round router routers run seconds selected send sending sends sent size smaller source src standard startport status sttl successfully suppresses sys tcp time times total traceroute traceroute.c tries trip try ttl using value version visible vncserver wait waittime warning weighted written ping 8/ping + 6dgnopdnprux 6in4 6to4 9kb access add add6 adding address addresses adds advertisement advertisements alive allows announcements answer arp arptimeout attempts auth authentication auto automatically aux background baddr based baud bdr bell bflen bin bind bindings binds bootfile bound broadcasts byte class clientid cmd comcast company's configuration configure configured configures configuring confusing connected connection control cookie correct cputype creates cs ctl database debug debugging default derived detail detection determine determines device dhcp dhcpd dhcpoption directly directs disable discovermask discoverrouter discovery dns doesn't dom don't dumpfile duplicate enables entry equivalent ether ether0 ether1 etherencap ethernet eui except existing exits external extpath file files finger firewall forever fork forked forks gateway gateway's gateways gathers gbe generic gwipv4 gwv4 homeagent host hostname implies impress inside interface interfaces internal internet interpret ip ipaddr ipconfig ipforward ipgw ipmask ipv4 ipv6 ipv6's ipv6on irc jumbo keeps kernel keyword labs lease len lib link linklocal linklocal.c list listen listens log loopback lpr mac mask matching maxdatagram maximum maxmsg message modified mounted mtu ndb ndbfile net net.alt netbiosdds netbiosns netbiosscope netbiostype netmtpt network networks ni nisdomain nisplus nisplusdomain nntp non nonlocal note ntp obtain obtained ones onlink onto opt option optionally options outside overload override packet packets parameter parameters params paramters passes pathplateau pathtimeout performed pfx pkt plan plan9_ policyfilter pop3 ppp prefix preflt prevents primary prints process protected protocol ra6 rate rc rebindingtime receive recvra remote remove removes renew renewaltime repeated replies request requested requests resolver respond rfc rfc2373 rip rip.c rl rootpath route router routing rs run running runs seconds send sendra serial server serverid servers service.alt setting size smtp source specific specify src st stack staticroutes stdar stream string subnetslocal supplymask swap sx sys table tables tcp tcpka tcpkag tcpttl tftp time timeoff trailerencap trying ttl type unbind unless unspecified updates user usual v6routeradv validlt value vendor vendorclass verb verbs via voluminous works write writes written www xdispmanager xfont ipconfig 8/ipconfig + 6in4 6to4 aa aabb access address addresses ag anycast automatic background bb bridge broker bugs bytes cc ccdd client configure configured connection conservatively constructed copy dd default defaults define destination directions don't driver equivalents explicitly fairly files filters flakey forks global hexadecimal host host's interface ip ipconfig ipifc ipmux ipv4 ipv6 it's kernel lib likely link linklocal local6 maintains manual mask missing mounted near needs net netmtpt network options packet packets pair permit primary processes remote remote4 remote6 rfc rfc3056 rfc3068 route routing run server similarly simply subnet traffic trust tunnel tunnels watertight ways 6in4 8/6in4 + 6to4 accept accepted acked actively actually add add6 added additional addmulti addr address addressed addresses adds administers advertisement aes_128_cbc aes_ctr aes_xcbc_mac_96 ah alg algorithm algorithms alive allocate allocated allow alters anded announce announced answer ape appends applies apply arbitrary architecture arglist arp arrives ascii aspects assigned associate association assume attack auto automatically autonomous avoid bad base based binary bind bit block bootp break bridge bridging broadcast bsd buffer bugs built byte bytes cache carry carrying catch character checked checksum checksums chosen class clear client clone closing combination coming communication communications compared comparison compress computed configuration configured configuring connect connected connection connections considered contains control controlled controls conversation copying corresponds count created cs ctl cur current data datagram datagrams debug debugging decimal declared decrypted default defense defined del delete delimiters delivered denial dependent des3_cbc des_56_cbc describe described describes descriptor destination detail details detected determined developed device dial diameter digits directories directory disable disables disallow disappear disassociate discard discarded discarding discovery dns doesn't don't dot drop dropped dst easy echo emit emulation enable enables encapsulates encapsulating encapsulation encoded encoding encrypt encrypted encrypts ends entries entry eof eproto equals equivalent err error errors esp establish established establishes ether ethernet eventually exceededs exchange exec executed existing exists experimental explicitly expr failed fails failures favor ff fields file files fills filter filters firewalls fit flag flags flush follow format formats formatted forwarded forwarding fragmentations fragments fs future generally generate generating gets goes gre hangup hash header headers headersonly heavily hex hexadecimal higher hijacked hmac_md5_96 hmac_sha1_96 hog hogs holding hop icmp icmp6hdr icmpv6 identifier identifying ifc ifcaddr iff ignoreadvice il implement implementation implementations implementing implements incoming independent indicate indicates inferno ing initiate input inspection integer intended interface interface's interfaces internet ip ip's ip.h ipaddrlen ipconfig iph ipifc ipmsg ipmux iproute iprouting ipsec ipselftab ipv4 ipv6 isn't it's items keepalive keepalives kernel key keyword killed lack laddr largest leading leave len length level lib libraries lifetime limit link linkmtu list listen listens live locally log login longer longest looks loopback looped lost low lower lport lru mac mac's machine machines malformed managed marks mask match matches matching maximum maxraint mcast mean meanings media mediate medium merged message messages mflag milliseconds minimum minraint minutes missing mode monitoring mount mounted ms mtu multicast multiplex ndb needed neighbour net netdev network networks newline newly nexthop noheader non none nor notably note null numbered obsoleted offsets oflag ok older ones onlink onoff onto op opened opening optional options originated ospf outgoing output overridden overrides packet packets pair pairs parameter pass passively path payload pcc percent perform performing pfx physical picks ping pkt plan points policy port portion ports ppp pptp preferred prefix prefixed prefixes preflt primarily procedure process programs promiscuous proto protocol protocols provide provided provides proxy quenches queue queued queues ra ra6 raddr randdrop random randomly range ras reachable reachtime read reading readipifc reads reassemble reassemblies reassembly reboot rebooted receive received receiving recvra redirects relation relations relatively relevant reliable remaining remmulti remote remove replace replacement replies reply report representation representing represents request requested requester requests reserves reset resolution responds responses restrict restricted resulting resume resumes retrans retransmit retransmitted retransmitting return returned returns rfc rfc2460 rfc2822 rfc4291 rfc4443 route routed router routerlt routes routing rport rudp rules run rxmitra scan scanbs seconds secret security segments semantics semicolon send sending sendra sent server services shorter shuts sic similar six size sockets solution source space spec specific specification specifies spi src stack stacks staking standard starts stateful stateless stations statistics stats status stream streams string strings struct structure subdirectories subdirectory subset successful support supported supports sys systems table tag tagged talking target tcp tcpporthogdefense tcprxmt tcpwin tentative text time timed timeouts timer times timestamp timestamps tos total traditional transfer transmission transmit transmitted transport treat tree try ttl tunnel tunnelling type typedef uchar udp udphdr udpmsg unacknowledged unbind unicast unit unix unknown unlike unordered unreachables unreliable unsolicited unspecified unsuccessful unused update updated updates usage user using usual v6addr valid validlt value values version via wait whenever wireless write writes writing written younger ip 3/ip + 768mb access accessible amount arbitrary authenticate bind cd channel client clients cmd communication consume consumption create data debugging default descriptors dipsu dir enables enabling file files flag groups hold image implementation implements initially interface keeping level limit machine mainly memory messages mounting mountpoint mounts needed network option performance permits pipe post precious private proc process provide ramfs ramfs.c remote rooted server simplistic source src srv srvname starts sys tells temporary tmp trace tree user write ramfs 4/ramfs + 80105ac6 80105bc1 80140bb4 8048e16c acid bugs cmd consists correct debugged dump dumps edited examining fields hexadecimal interested interpret interrupt interrupts kernel kernels ktrace ktrace.c lines link location locations machine memory mips option pasted path pc points printed prompts provide rdbfs readable register resulting screen series shell source sp src stack sys topmost trace translates values window ktrace 1/ktrace + 88sx accept actions adapter address addresses allow appended apply archive ata attach attached attachs authentication autodiscovered blank block blocks box bus byte cache cached caution checking clears comma complete complex complicated concatenation config config.c configuration configures configuring connect connected constants contains controller controllers copy copydev copyworm cp creates cw2j cw3j dangerous data databases default defaulting defined defines demountable described dev device device1 device1device2 device2 device3 devices digit directory disables disc discs disk disks drive drives dump effectively enable enters equivalent erased erases error establish ethernet exit exits experiments explicit fake fancy file files filsys formed fourth fresh fs fsb fsconfig gateway's gets greater halt host hot hp40fx hp40fxdump id ide identify includes inclusive indicate initialization initialize initializes initializing integers interface interfaces interleave interleaved interleaving ip ip0 ip1 ipaddr ipauth ipgw ipgw0 ipgw1 ipmask ipmask0 ipmask1 ipsntp juke jukebox jukeboxes ken keywords kgbsun knows kremvax label leaving leftmost leftward length letter list logical longer loop lun magnetic main marvell mask master mechanisms messages mirroring missing mkfs mode multiplied naming native necessary neither network noattach noauth non null nvram omit onto optical output overwrites owner panic parenthesize partition partitioned perform periods permission plan plan9.ini platters port prevents processors proper provides pseudo quarter quarters raid ram reach read readonly ream reboot recently record recorded recover recovery recreate refers relevant replaced represent represents request required resetting rest rightmost rightward robotics root rules run running sata scratch scsi separately server server's similar size slave slots smallest sntp source space specifier specifies specify specifying src stat stored string subnet supported supports swapped swapping syntax sys systems target targets text textual therefore third thompson time times trying turns typically unit unless valid values various volatile w4w5 whatever wise working worm write writes writing written wstat fsconfig 8/fsconfig + 8cnt alphabet's ambiguity appearance ascii ascii.c avoid base character characters cmd codes contains control conversion convert converted converting converts current decimal default descriptions dox encoding extensions file files flag font forces goes greek hex hexadecimal hexmax hexmin included insert interpret iso latin lib lower mathematical miscellaneous mnemonics newlines numeric octal opposite option options output print printed prints range representations running settable similar sorted source specially specifies src standard string suitable symbols sys table tcs text translates treats unhelpful unicode unicode.c unless unlike utf valid value values versa vice ascii 1/ascii + 8fe472d31b360a8303cd29f92bd734813cbd923c applications attr attribute attributes authentication authorities based binary calling certificate check checksum cn comments comparing comprises convention cs.bell file files hex include key keys labs.com lib lines list lists maintained okthumbprint pairs permissions pki plan playing policies protected pushtls remote role server servers sha1 side's stored sys systems thereby thumbprint thumbprints tls tlsclient trusted value web thumbprint 6/thumbprint + 8kb accuracy actual allow altitude arc assumes aux azimuth baud buffer bytes character chipset clock clockwise cmd comes compatible configure configured consists constellation contains converted coordinated copy current data date db dd dd.dddx dd:mm.mmmx dd:mm:ssx default degrees dev deviation device difference digits direction directory east easterly eia0 elevation encoded equator establishes evermore factor fields file files finishes fix flag format global gps gpsevermore gpsfs gpss greenwich ground heading hhmmss higher horizon id implementing implements initialization initialize interface internal invalid keeps km latitude latitudes level lines location longitude longitudes magnetic meters millisecond minutes mm mnt mntpt modifies mount mounted ms negative nmea noise north nsec obtain output parameters playback playing positioning positive posted prn provided provides quality rate ratio raw read reader reading reads refreshed sample samples satellite satellites sea seconds serial signal snr source space specifies specify speed speeds src srv srvname ss standard stands sued sync synchronization sys tab time timesync typically universal usable using valid validity value values view westerly zulu gpsfs 8/gpsfs + 9660srv 9cj 9cjr access added additional allproto amounts applied ata backup base based bios block blocks boot bootable booted bootfile cd cdfs cdimage cds character characters clones cmd colons common conform conform.map conformant conforming create created creates current data debugging default described digits directories directory disk dossrv dump dump9660 ease emulation entry error exception exclusive exit extensions fat fields file file's files filesystem fit flag floppy format formatted freely fs full grow image images immense imposed inverse iso january joliet key larger lba length letters lib listed loaded map maximum maxsize metadata microsoft mixed mk9660 mkfs mode mutually names naming nnnnnn non option options output owner path plan platforms pointer pointers populated portproto posix process proto protocol provides random read relative replace restrictions reverse rewritten ridge rock root scanned seconds sharing similar size source spaces specification specifies src standard status stored style sys sysconfig systems time title translated tree underscore unicode unix unspecified updates usual utf versions volume windows writes writing written mk9660 8/mk9660 + 9660srv 9dos able accesses actual addr address addresses aid allow alternate announce announcing arenas args arranges arrow attach auth authdom authentication authid automatic automatically behaves beyond binary bind binds boot bootargs bootes booting bootp brackets break buffers bugs built cache caches cases cfs challenged check clients common compiled complete completes conf configuration configure configured configuring connect connected connection connects console constructed contact control cover cpu cputype crafts ctrl data default depend depends describe determine dev device devices dhcp dhcpd dial directly discussion disk domain dos dossrv dumb encryption env environment ether ether1 ethernet except exec exists extra fields file files fixed fkm flag fmt formats forms fossil fs holder holding id identify ing init initializes insert inspects interactions interface interfaces invokes ip ipconfig items kernel key kfs labs.com lets level list listed lists loaded loading loopback machine machines masquerade mechanics media memory method methods modem mount mounts mutual namespace needed net network newline none numeric nvram objtype obtained odd ones onto option override owner owning particularly partition pass passing password pc pc's pcs performs picks plan plan9.ini presentation prints process processes processor programs prompt prompted protocol read reboot reformat remote research.bell responses rom root run running sd sdc0 seconds send serial serve server servers setting simulates simulating sole source specific specification specifier specify split src stack started starts static stops store stored structures sys tcp terminal type typed types typically unit user user's username using valid value variable variable's variables varied variety vendor venti via view web xx boot 8/boot + 9660srv 9fs access accessible add adding additional appended approximately audio aux avoid backup bd bds blank blu boot buffer bugs burns bytes care carries cd cddb cdfs cds cf character closing cmd cnnn combinations compact compliant contains control cope copy copying cp created cross ctl current data database default describe desired dev device directories directory disc disc's discs disk diskid dossrv drive drives dtt dual dumped dvd dvds easy echoed eject ensure entire except file files final fixate fixated fixating fixation format freedb.freedb.org further grep http ingest inserted interface internet kbps kept layer level lines maximum media memory messages minutes mk9660 mkdir mmc mnt modern mounted mtpt nnn note ntracks onto operation optical optimal option optional output permanent prefix prevent prints product provides quasi query quickblank quirks raw ray rc re read reader readers reading real recommended recordable records regardless remove removed requests require reservation reset response rewritable rm rom round run rw saturated saturation sd sd05 sdd0 sddev selects separately server serves simply songs source speed speeds src standard standards stored support supported sys table takes tar there's time tmp toc total track track0id tracks transparently tuples type underruns unique units unused value via wa wd writable write writer writers writing written www.t10.org yields cdfs 4/cdfs + 9660srv alternate blocks cached caching cmd count current debugging default directory disables download e.g enable file files hget http httpfile httpfile.c image ip iso kept kilobyte memory messages mount mtpt needed net net.alt network option options page path plan9 plan9.iso post reads requests satisfy serve server serves source specifies src srv srvname sys time trace traffic url web webfs www.9grid.de httpfile 4/httpfile + 9apc 9apccpu 9beagle 9ch 9fat 9gd 9load 9pccpu 9pccpudisk 9plug 9pxeload address addresses alpha arc arm attribute automatically based behaves bell board's boards boot boot_file boot_reset bootalphapc bootcmd bootdef_dev bootdelay booted bootf bootfile booting bootp bootstrap bootstrapping bootz cd cfg challenge collects colons conf configuration configure console control cp cpu default described details device dhcp dhcpd disk diskless display displays dos download downloaded ea edit establish etc ether ether0 ethernet ewa0 ewa0_inet_init ewa0_protocols expected fat16 file files firmware floppy format generic gumstix guruplug guruplugs happens http igepv2 incantations init installation ip isee kernel kernels kirkwood kw labs lib lines load loaded loads locates lower mac machine machines manual marvell memory mentioned methods mips monitor multi multiprocessor ndb necessary none obtained omap omap3 omitted openrd overo page parameter parameters particular partition pc pcs plan plan9.ini plugs powered prep prepared procedures proceed programs prompts protocol protocols pxa pxa168 pxe reach read rebooting reboots replace request required reset rom root run running saveenv secondary server servers services setenv sgi sheevaplug sheevaplugs similar source sources specific src srm started stored string substituting suitable sys system:file systems t's taste template terminal terminals tftp tftpboot thereafter ti type typing understand unix user using value variable various via ways www.compaq.com booting 8/booting + 9bitsy backlight bin bitsy bitsy's bitsyload boot boots button calibrate calibrates calibration center characters clicking cmd compaq configure consistent copies cpurc creates crosses default del destination dev dimmest direction display displays doesn't drawing echo editor erases esc eval exit file flag flash format grep input inputs intensity ipaq kernel key keyboard keys load loader loops maximum memory mousectl mp opposite option optional pad parameters params partition pencal pressing prompter prompting ramdisk ramfs rc required rio run screen scribble section selects source specific src standard starts stylus suppresses sys tapping text tmp tmpparams touch touches typing unless updated user using utilities value values variables virtual write writes writing bitsyload 1/bitsyload + 9fans ability accepted accepts accumulated actions actually added additionally administrative aggressive algorithm allows amount analysis applied applies args ascii assembles automatic avd backslash based block blocking border bugs cancels canonical canonicalization canonicalized cases character characters cmd collecting combine comment commonly compile compiles complete confined consecutive contains continuation continue continues control conversion convert converts copies copy counting criteria cse.psu.edu data date debug debugging decreasing default define delayed delete deleted deleting deliver deliverable delivered delivery desirable destination detecting determined dev directives directories directory disabled discarded dispatches domain double dump dumped efficient elided enable enclosed engine entry enumerate equivalents error escape essex.com exactly except excluding executed expression expressions facilities fields file filename files filter filtering filters finally finds further gateway generally generic harmful header highest hold holdroot href html ideally img implementing inadvertently included incoming indicates indicator input insignificant inspection instances introduced introduces keyword lasex.com layers leading leaving legitimate letters lib likely limiting lines list lists loff log logged loops lower mail mailing manual manually match matched matcher matches matching material meshes message messages mime missing mode newline none notified occasionally occurs optimization option optional options ordering override overrides owner parameters pass patfile pattern patterns personal phrases pipeline pipeto portion potentially print prints priority process processed processing programs provide q.v qer qmail queue queue.dump queue.hold queued queues queuing quote randomly rc rcpt read recipient regexp regime regular repetitive replaced replaces report results review root runq salvaged save saved scanmail script searches section selects semi sender senders sending seq sequences sex.com sharing similar size smtpd source space spaces spam spec specific specification specify src standard stored strategy string strings structure stuck style subdirectories subdirectory subjected successfully supported supporting sussex.com swept syntax sys sysex.com systems tabs test testing testscan time times tool trigger type unaware undesirable unique unlike unlikely unwanted upas updating user user's using utility vacation version viruses wiser write written scanmail 8/scanmail + 9fat accessible ad alphas anamelen answer array asgetresp asgetticket asrdresp attribute auth authdial authdom authdomsum authentication authenticator authenticators authid authid's authidsum authkey authsrv authsrv.h authsum bootes buf bytes char character checksum commonly communicating config configlen configsum configuration connection cons contains conva2m convert converted converts convm2a convm2pr convm2t convm2tr convpr2m convt2m convtr2m cs cs.bell decrypting default des deskeylen device diagnostics dial dialed dials dns dom domain domlen dos drive e.g encrypting entry environment error errstr fails fd fields file finds flag floppy former full holding include int integer key labs.com len libauthsrv libc.h machines machkey machsum match mem message messages mips msg ndb neither net netroot network nil non nv nvcsum nvram nvrsafe nvwrite nvwritemem nvwriteonerr opens p9auth partition passtokey passwd password passwordreq plan9.ini plan9.nvr pr precedence prompt queried ram readnvram reads received receives reception recieve request requests respective return returned returns rooted routine routines sd00 sdc0 secstore sends server server's servers sgi source sparc specifies src stopping storage stores string struct structure structures succeed successful successively sys tbuf ticket ticketreq tickets tr transmission transmittable trbuf tries u.h uchar userid value valued values variable via void volatile write x86s zeroed authsrv 2/authsrv + 9fs 9load 9powerboot 9pxeload aaaa add address addresses adds allows anna anna's anna.cs.bell assume astro attr attribute attributes auth authdom authentication authsrv aware beware bind bit boot bootes.research.bell bootf booting bootstrap class comments common composed comprise con connect consider consists consulting continue cpu cs database decide declares default defers describing dhcp dhcpd dial dialstring directly dns dnsdomain doing dom domain domains dotted download drop ending ends entries entry ether ethernet exchanger exists expect file files finding flat floor fs fulfill fully gateway global hexadecimal hill host hosts identified identifies il impose include included indirectly installation internet ip ipconfig ipgw ipmask ipnet ipv6 knowledge labs.com level lib lines location looking looks lop lower lowest machines mail mappings mask meaningful metaname metanames mh mips missing multi murray mx names ndb ndbipinfo needed net nets network networks ntp ntp.cs.bell numbered oncore.cs.bell onto ordering p9auth.research.bell pair pairs particular pc perform plan plan9 port ports pref pri programs proto protocol publicly pxe qualified r70.research.bell record redefine relative relevant request requests reserved resolved restricted rexec root routine routines running search searched searches searching server servers short smtp smtp1.cs.bell smtp2.cs.bell soa sometimes space speak specific specify spindle spindle.research.bell srv starts structure subnet subnets subnetted supported supports sys sysmon tcp third tighter time times translate tuple tuples udp uniquely unix unrooted users using value values via we're weight windows wins works ndb 6/ndb + 9fs 9nfs access addr address allow answer assuming auth_tooweak authentication authorizes aux bin blank bugs cache caching chat class clears client clients cmd collectively completely configuration connection contains cpu cpurc creates credentials cvrd daemon database debug debugging deduced default describes descriptor detail dynamically echoed echoing edu eduardo eduardo:pie eduardo:yoshimi entry error etc executed expect expression fields file files flag format gid hall hour id's incoming instance intended internal ip ivy level lib lines list listen listening log low lower machine machines mandatory map mapped maps messages mount ndb network nfs nfsserver nfsserver.chat nice none notation note options passwd password pc pcnfsd pie plan portmapper privileges procedure programs protocol provide query rc read regardless regexp regular reject remote repeated reply requests returning rfc1057 rfc1094 rfc1813 rfc3530 rpc run security served server server's servers soft,intr source space specification src srv started startup subsequently sun's sys systems tcp toy trusted typical typically udp uid unix user users using verbose version via yoshimi zz nfsserver 8/nfsserver + 9fs ab absolute accepts acme acme's acme.dump acmeaddr acquire actions added address adds adjusted adm affected alphanumerics alternate analogous angle anywhere append appended appends applications applied apply applying appropriately arrange arranged assumed attention autoindent automatic automatically awd awd.c backspacing bar based behaves behavior believes bin binaries bind binds bit black blank bottom bound box brackets buffer bugs built builtin button buttons capital cd center character characters checking chord chords click clicked clicking clicks cmd colon column columnated columns combine common compilers complement completely complex components contained contains context continues control convention conventionally conventions copies copy corner cputype create created creates current cursor cut data date default defined definition del delcol delete deleting delivered described diagnostics dies directly directories directory dirtiness dirty discussed display distinct documentation double drags dump e.g easier echo edit edited editing efficient employ en enclosed ends entire environment error errors esc etc euro.8.font evaluated evaluates except exception execute executed executes executing exist existent existing exit expands expansion expected experimental explicitly expressions external extra feature file file.c file.c:27 filename files final fix fixed fixfont fn font full fully further future grows guide hiding highlighted hold holding holds id idea identical identified image implicitly import incl include includes indent indicate indicated indicates indicating informal inherited initiated input ins instructs intended interactive interactively interface interpreting intervals investigate invoke it's key keyboard keys kill killed label labeled language largely largest layout leading leaves leaving letter lexicographical lib list lists literal live load loaded loadfile loads locate longer lost ls lucidasans lucm main mainly maintained maintains manages masse match matches mc meaningless mips mk mode modified motion mouse moved moves moving multi names ncol near necessary needed needs newcol newline newly non none note null numeral objtype occurrence occurrences occurs op opening operations option original output outputs overridden particularly parts paste path pike piping pitch placement plain plumb plumbing pointed pointing possibly pre prefixed prepared pressed pressing print prints produce produced producing programmers programs proportional provides purely putall pwd q.v qualified rate rc read readme real receives recently recognized records recreation redo refers regexp regular related release released relevant repaired repeatedly replace replaced replacing required rerun reside restore restricted resulting return rio rob rule rules run running runs sam sam.c sample scratch scroll scrolling search searched searches select selected selecting selection selects send sent served shell similar slash slightly slowly snarf sort source space spaced specific speeds src srv standard starts stops store stored string strings style subdirectories subdirectory succeed sufficient suffix suffixed suit superseded supplementary support sweep sweeping sys sysname tab tabstop tag tags takes template temporarily text textual textually treat turning type typed typically typing unaffected undirtied undo undoes unexpectedly unicode.9.font uniformly units unless upper usefully user users using usual valid value var varfont variable variables versa vertical vice visible warning whenever width widths win window window's windows winid write written zerox acme 1/acme + 9fs abccdf abccemnq access addr address allow apply auth auth_proxy authenticate authentication automatically bin binary bind blanks boundaries bugs calling characters cmd commandxx comment compatibilty complaints connect connecting connection connections connects contains control conventions cpu creates debugging deepthought deepthought's default dial dialed dials directly directs don't dump edition enable establish establishing examine executed existing exists explicitly exportfs failures file files filter flags fourth ftpfs hack hhgttg il import initializes input insert instance internal introductory kernels kgbsun kremvax kremvax's likeliest log machine maintain mentioned message messages mount mounted mounting mountpoint mtpt names necessary needed net network non none older omitted ones onto option options output path performs plan port ports post posted posting process protocol provided quoted rc received recognizes remote report run script seconds serve server servers servicename services shell sleep sometimes source specifies src srv srv.c srvname srvold9p srvssh ssh standard started starts string suppresses sys systems tcp translation treat typically u9fs u9fspath underlying unix unrooted user users value variant version via windows srv 4/srv + 9fs accept access active acts adm allocate anded anyone archival archive archives assumes attach attached attenuated authentication avoids awp b9b3...5559 backed background bad belonging bfree bin bind bits blindly block blocks blocksize boot branded buffer buffers bugs bytes cache care chaperone check checking checks chopped clre clri clrp cmd collection comfortable comment commentary compiler concurrently conf config configuration configured confirmation connecting connection cons consistency console contains convenient conventional conventionally copy corrupted create created date dd debugging december default deleted deny deprecated described detailed dev developers device dir directly directories directory disabled discussion disk distinguished distribution documented drastic dt dump dumps effectively effort entire entries eof ephemeral error etc eventually except execute executed executes exists fast favor file file's files filter fixes flag flchk flfmt fork format formatting fossil fossilcons frozen fs fscons fsys full future generated grain groups hh hhmm hill holding host hour image includes inconsistencies initialize initialized initially input inside instance interspersed involving kept kernel label labs.com lasting list lost lp ls magnetic main mainly marks memory messages metadata minute mips mm mmdd mmdds mode modified modify month mount murray ncache none notably note noworld null occupy offending option optionally options output overrides parameters percent periodically permission permissions pie pieces plan pointers prefixed prepare prepares prescribed presents preserve printed prints privileges process programs prompt proposed protocol provide q.v ram read readable reads recent reclaim recommended reformatting repeated replaced require requires restored resulted root run runs safe salt score script sdc0 sed selects served server servers serves sharp signs simply size sizing snapshot snapshots source sources sources.cs.bell space specifically src srv stand standard starts storage store stored strategy structured subtree successfully suggestions sys table taking tcp textual tickets time times toggle trees typical typically uname uniq unlike unreachable user user's users using vac vc venti version vet via walking whenever writable write writes written yes yesterday you're yyyy fossil 4/fossil + 9fs accept access add address altogether ansi assumes atomicity attach attaches auth.dom autharg authenticate authentication authtype binary bind block box bug bugs cases character characters chatty clients cmd coming compile compiler connected connection connects consulted controlled copy data debugging default descriptions determine device devices diagnostics digit digits directory discouraged dnz dom domain due edition editions effective enables entire entries etc ethernet exactly except execnet factotum file files finally flag forbids fourth fs fsroot greater hard hexadecimal hosts.equiv id identical implementation inetd inetd.conf input install intro invoked ip key kremvax library lines listeners log logfile login machine machines mainly match maximum mechanisms message messages method mount msize multiplexes names network networks nfsserver none nowait onlyuser option options othwise output p9any p9sk1 password permits plaintext plan plan9 port procedure process processing produce protected proto protocol provide provides remote remove reported requests results rhosts root run running runs ruserok script secret semantics serve serves services signals size software source space specifier specifies specify specifying src srv srvssh ssh standard started startup stream suitably sys systems taught tcp thinking third threaded time tmp translated treat tree truncate try turns typically u9fs u9fs.key u9fs.log uid uids unacceptable unix unpredictable unpredictably unsatisfactory user users using usr usual via wire write wstat u9fs 4/u9fs + 9fs access activity adds allcmds allocator announces apop appended aquarela attempt attempts auth authenticated browser bugs can't checking cifs cifsserver client clients cmd code complete connection connections conversions correctly corresponds creation debug default deletion diagnostics directories directory disables disconnections disk domain draconian drive dump e.g emits enable enables equivalent erroneously error exists expression fail fails fids file files filesystem handle hexadecimal hierarchies hierarchy housekeeping id ids inaccurate limited listen listening listens locking locks log machine managed master matching memory messages metadata names net netbios nmbd nn np opened option options output page permissions persistent plan plan9 plan9.example.com poolparanoia presented primary prints process processes protocol provided provides query rap rap2 register regular rename rep reported request requests required resolution responses rooted running satisfied search secret send server servers session sessions setup share sharedfiles shares sids smb smb_ smb_com_session_setup_andx smb_trans2_find_first2 sometimes source space specific src srv standard sub subsequently succeed succeeds sufficient support symbolic sys tandem tcp temporarily tids transaction2 try udp unicode unicoding unix user users utf verbose windows workgroup works write aquarela 8/aquarela + 9fs acme acme's add addr alias arg ascii attr aux awk band bell bin bugs build button cd characters chosen client clunky cmd connect conspire conswdir conswdir.c copies ctl current data default described dev dir directory echo edit editor environment esac escape execute executed file full generate handle hard hostname include informed informs input inside isfile label login looking machine maintain matches mechanism message messages middle mount mounted names none output path paths plumb plumbable plumber plumber's plumbing printed printf processing profile prog pwd rc relative remote remotesys removed rio rooted rule run runs rwd sed sent session sessions shell source space src srv ssh standard stdio.h stream suffixed sys system's systems text time title type unix using usr variable wdir win window windows working writes xterm you're za rwd 1/rwd + 9fs actions actually addition appends applicability applying assumed based bell bin bind careful carried carry central check client client's clientdb clientexclude clientlog clientmount clientproto clientroot clients configuration configured conflict conflicts connected connection copied copies copy cpu cpurc database define deleted deletion described describes describing details detected developers dials dir directory dist distribution doing edition entries event events except exclude fast file file's files flag fn fourth gid glenda ignore inner inserted installation installations instant instruct interface internet intervening keeps kept kfs knowledge labs laptop length level lib list locally log logged looks low machine maintained management manually mean mechanism merely metadata mode mount mounts mtime network notice nv one's operation options path paths plan plan9 plan9.db plan9.log plan9.proto polished potentially primarily print prints programs proto provide pull push pushed rc reading relative repeat repeated replica replicas replicated report reported require rescan rescans resolved returns root run running runs scan scans script scripts server server's serverdb serverlog servermount serverpath serverproto serverroot serverupdate shell simply simultaneous source sources sp space specifies stat status structure successfully summary synchronization synchronize termrc tools typical typically uid update using usr variables verb wider workings written replica 1/replica + 9fs activity actual addition additions annulled annuls appending applies applychanges applylog assume assumed atomically attempt based bin bugs character cl cli.portproto.db client client's clientdb clientroot clients collectively combined compactdb conflict conflicts connect connection consider copied copy copying cpu creation current database databases date db decimal default deleted deletion deletions described describes describing detect detects developers dir directory distribution enables entries equivalent error essentially event events excluded excludes facilitate favor fields fifth file file's files flag flags fs full further future gen gid ignoring incremental incrementing indicator input intended interface invoke kept kfs length lib listed listing log maintain management manual manually metadata mode mtime mv names necessary network noting nuv omits omitted ones operates opposite option optional ordering outdated output overwrite page path plan polished portproto prints process propagate properties proto provide providing rc read readable reads records remote removed repl replica replicated report reported resolve resolved resulting root rooted run scan scans scripts server serverpath serverroot shell silently similar similarly sorted sp specify speed srv.portproto.db srv.portproto.log standard stat string structure subsequently summary supersede sync sys sysconfig takes textual time times tmp tools typically uid uids update updatedb updating using verb version writes writing replica 8/replica + 9fs.org array assembled assembler assembles author aux cmd code control controllers defines device driver enums file guide included instructions language loadable logic microcode na ngr nigel operation patches pci processors programming roles scripts scsi sd53c8xx.c sd53c8xx.n series source src sym53c8xx symbios sys version written na 8/na + 9load access actions address addresses allow answer answering architecture associate attribute attributes auth authentication backup boot booted bootf booting bootp clients cmd comes common configuration contains coordinate correctly database debugging default dhcp dhcpd dhcpleases directory directs dmnprssz dns dom domain don't dr dynamic entry etherdev ethernet everything exception exist exists extra fails file files fs gateway global hex homedir honored identifier inclusive internet ip ipgw ipinfo ipmask kernel lease leases lib list listed log looks machine mail maintains mask minimum mode mounted mute names ndb net netbios netmtpt network non none ntp obtain octet options originating output pairs particular performs permission piece plan pop3 pptp precedence print prints programs protocol protocols proxy rarpd read readable record reply request requester requesting requests resolution responds restricts return reverse rooted run runs seconds secs served server servers sleep smtp source sparc specifically specify src stack standard static subnet subnetwork suns support supports sys systems targeted tftpd time transfer transfers translating user using valid value web wide wins www xxxxxxxx xxxxxxxx.sunyy yy dhcpd 8/dhcpd + 9load addaoe adding aoe aoedev aoeif ata attached bind boot booting bootstrap bugs can't config configuration configure configured controller ctl data default dev device devices directly echo enumerated ether0 ether1 ethernet explicitly external interface interfaces invocation letter lines listing lun names network packages plan9.ini port pxe quirks raw rc root script sd sdaoe sdaoe.c sdctl sde0 shelf slot snoopy source spec src storage switch sys target type unit using sdaoe 3/sdaoe + 9p.h 9pcmdbuf array buf bytes caller's cb char cmd cmdbuf cmdtab control ctab data dev distributed driver entries entry equal error exactly fcall.h fields fmt formatted getfields holding include index int interface kernel lib9p libc.h lifted longer looking lookupcmd matches matching message messages narg needed nf nil ntab nul parse.c parsecmd parsed parsing plan pointer pointers provide reconstruction req request resoponds respondcmderror responsibility returns servers simply source splits src string struct structure structures sys tab textual thread.h tokenize treats typedef u.h using utf void walks whenever wrong 9pcmdbuf 2/9pcmdbuf + 9p.h 9pfid 9pfile abort accept active actually additional addr address afid allocate allocated allow alternate amount analogous announce appropriately arbitrary archfs arg argbegin argv0 arrange arranged arranging arrive asynchronously attach attempt auth authentication aux auxiliary avoid avoided bad behaves behavior block buffer bugs bytes caller calling cancelled care cdfs chance char chatty9p check checked child clean cleanup client client's clients clone closed clunked common conditions connections consider considered constraints consult consulted consulting consults contained convention conversation convert copies copy copying count create createfile creating creation data debugging decoding default delay demands depends described desired destroy destroyfid destroyreq detects differences dir direct directories directory dirgen dirread9p discussion dispatching dispose draw drops e.g easily elsewhere emalloc9p endsrv enforce entire entry erealloc9p error errors errstr estrdup9p etc exception executes exists exit exits expected explicit extant extern fail fails fcall.h fd fid fids file files fill filled filling fills final finished flag flags flush forcing fork freed fresh freshly full further future gen generated gracefully gratuitous greater handle handled handles handling helper highly hurried i.e idea ifcall ifcall.oldtag implementation implementations implementing include incoming increment independent indirectly infd info initialize initialized initializes initializing int interface internal internally interrupted intricate intro kept lib9p libc.h library link listens listensrv lock locks loop machine maintained maintaining malloc mark measures memory message metadata minus mtpt multithreaded necessary newfid nil nntpfs non nopipe note nqid nsrc numeric nwname obtain occurs ofcall ofcall.qid ofcall.stat offset oldfid oldreq opened operations opportunity option optionally ought outfd outgoing outlined output outstanding palm parameter parameters parent path's permissible permissions perror pilot pipe pleases pointer pointers post postfd postmountsrv printed proc process processes procrfork programs prohibited promise prone provide provided provides prudent qid ramfs ramfs.c reached read readbuf reading reads readstr realloc reclaim record reference referenced references referring remove removed removefile reply representation req request requested requester requests required respond responded responderror response responses results return returned returning returns reuse rffdg rflush rfmem rfnameg rfnoteg rfork root routine rule run runs satisfied satisfies satisfy satisfying sending sent serial serve server servers serves session setting shares sharing short signal signalled similar similarly simply simultaneously snap source space src srv srvfd srvname ssh sshnet standard stat stored strdup string struct structure structured structures success successful successfully suggested switch synchronization sys sysfatal terminate terminates th thread thread.h threaded threadlistensrv threadpostmountsrv tidy time transactions transcript tree tree's trees typedef typically u.h ulong uncompleted unlike unmounted unspecified updated updating user using variable via void wait walk walk1 walkandclone webfs wire wname wrappers write writes writing written wstat 9p 2/9p + 9p.h 9pfid 9pfile active addition afid allocated allocfid allocfidpool allocreq allocreqpool analogous authentication aux based chan char cleanup client closefid closereq connection contains count counted create creates creating derives described destroy destroys destruction due equivalent exception extant fcall fcall.h fid fidpool fids file flags freefidpool freereqpool hold ifcall ignore include increment integer intended involving kernel lib9p libc.h lingering longer lookupfid lookupreq loop management mean member mode necessary needed newfid note ofcall oldreq omode omode&omask opened operate ordwr oread owrite parameter particular perform permissible plan points pool primarily provide qid read reference references regarding removed removefid removereq removes represent req reqpool request return returned returning returns routines server source specific src struct structure structures successful sys tag thread.h tracking transaction tree typedef u.h uid ulong using values various void walk whatever 9pfid 2/9pfid + 9p.h 9pfid access accidentally added adjustments allocmap anticipation arbitrary caller calling caninsertkey concurrent count counted counts creates creation current data dec decremented deleted deletekey destroys entries entry external fcall.h fidpool freed freemap id implement inc include increment inserted inserting insertion insertkey inserts int integer integers intmap intmap.c key lib9p libc.h library lock lookupkey maintain map mapping maps moderated non nor pointer pointers protected qlock rationale reclaim reference removes reqpool responsibility return returning returns safe similarly source src storage stored structure structures sys thread.h time transfers typically u.h ulong val value via void intmap 2/intmap + 9p.h 9pfile additional aexec alloctree allow aread assumes attempts automatically aux awrite bits bitwise buf buffers bugs calculate calling care char checking checks cleanup client clients closedirfile closefile code complex concurrent consider consume copying correct correctly count counted counting create created createfile creates creating cumbersome described destroy destroys dir directories directory elem elementwise entry error evaluates exist explicitly fcall.h file file.c files finished foo freed freeing freetree gid groups handles hasperm hierarchy implementation include incref independent inherited int integral intended intermediate lib9p libc.h link lock machine memory mode necessary nf nil nls non note obtain opendirfile owned owner path permissible permission permissions pointer pointers provide rdir read readdir readdirfile reading ref reference references related relative removal removed removefile removes removing resulting return returning returns root server servers simplistic slash source src standard stat storage struct structure structure's structures success sys thread.h tree trees typedef u.h uchar uid ulong update user using void walkfile walking written yield yielding 9pfile 2/9pfile + 9pc acid cmd console consolefs control copy db debugged debuggers debugging default dev device directly eia0 enter file files kernel kernels lines mode panics pid port presented presents proc process protocol provided rdb.c rdbfs rdbfs.c remote remotely serial serving source src substituted suspended sys td text textual typing using rdbfs 4/rdbfs + 9pc acquired address addresses administrative advantageous allocate allocation application arranged array ascii att attr attribute attributes attrs aware base binding bio.h bootf bound buffer bugs byte cached calling chain char check circular closes cname comprising computes concatenates connection consider consistent copy corresponds create csgetval csgetvalue csipinfo data database databases db db1 db2 defaults deprecated dept described describing diagnostics directly directory dns dns.big.com dnsquery dom domain domainname entries entry errstr es exchanger exchangers excluded existed expect expiration expire failure file files fill finally fixed freed frees hash hlen identified implement include int internet ip ipattr ipmask ipnet isn't length levels lib libc.h libndb lie lines link linked list logically looking looks mail malloc malloced manipulating match matched matching minimum mounted mx nattr ndb ndb.h ndbalen ndbcat ndbchanged ndbclose ndbconcatenate ndbdiscard ndbfindattr ndbfree ndbgetipaddr ndbgetval ndbgetvalue ndbhash ndbipinfo ndblookval ndblookvalue ndbopen ndbparse ndbreopen ndbreorder ndbs ndbsearch ndbsetmalloctag ndbsnext ndbsubstitute ndbtuple ndbtuple's ndbvlen net netroot network networks nickname nil non none ns nul null offset opened opens operate pair pairs parse parses particular periodically pointed pointer pointers points pref preference primary programs protocol provide provided ptr queries query rattr read reads real record refresh relevant removes reopens reorders replaces represent representing resolved retry return returned returns reverse root routine routines search searched searches seconds sequential serial server servers setmalloctag short smtp smtp.big.com smtp1.big.com soa source specifies src starts storage string struct structure structures submits subnets subnetwork successful successive sys system's table tables tag takes throws tighter time tp ttl tuple tuples type typedef u.h uintptr ulong using val valbuf valid value values versions view void wraps x.big.com ndb 2/ndb + 9pcdisk accumulated accumulates array base bind byte clock controls count counter counts data depends dev device devkprof.c echo endian file formats hold holds integers kernel kpctl kpdata kprof message occurred operating port presentation prof profiling provides range rc recording reports rest restarts results running runs runtest script size source src startclr stop string sys terminates test text tick ticks total writing zeroing kprof 3/kprof + 9pcon 9pcon.c absent added address afid aname arrive attempts automatically aux binary bugs byte carry cmd cn connection conventional conversation count data default descriptors dial dir ease easy established exceptions expanded facilitate fid fields file flag getfields gid id inferred input integer interface interpret interprets intro length lines message messages mirrors mode msize mtime network newfid note nwname offset oldtag opaque opened parsed pass perm prints prompt provides recognizes responses run scripting section sends server source specifying src standard strings syntax sys tags tattach tauth tclunk tcreate text textual tflush tokenize topen translator tread tremove tstat tversion twalk twrite twstat typed uid uname version wait wname wnames wstat 9pcon 8/9pcon + 9pcon abandoned abandons ac access accessible accounts actions active activity actually add additional addr address addresses adds adm adm:adm:adm:sys age allocate allocating allocation allow allows amount appearance append applied apvwr apw apwdp arbitrary archival archive archived archiver arg attach attached attaches attempt attempts authentication automatic automatically avoiding bad basis bc bclose behaves bfree bind bit bits blank block blocks broken buffer bytes cache capital care character check checking checks cleanup clearing closed closes closing clre clri clrp comma completely comply con config configuration configure configured conjunction connect connection connections considered console continuing control conventional correcting count create created creates creating crytography current daemon data debug default denoted described destination dev device devices df dflag dir directories directory dirty disable disallowed discard discarded discarding discards discouraged discussion disk displayed displays distinction distribution doing don't dos dot dst duration easily echo editing edits elem enables entire entries entry environment epoch epochclose epochs equal equivalent error errors establishes event except exclusive execute executed executes execution exist export fail fields file files finish fix flag flags flchk flushes forces format formatted forward fossil fossil's fossil.outside fossilcons frequent fscons fscons.sources fscons.sources.adduserd fsys full gid glenda glenda:glenda:glenda group's groups grow halt halted hexadecimal hhmm hidden host id idea identically identify ids ignores impossible inaccessible included incoming inconsistencies increasing ind indicate integer intended internal interval invoked ip ipok issued keyword label labels labs.com leader leaders leaked leave length letters level lines link list listen listener listening lock low main maintains maintenance manages mandatory manipulates manual marks maximum mechanism member memory message messages metadata minutes mmdd mnt mode moved moving ms msg multiples names namespace ncache necessary needs network newname nmsg non none none:none note noworld:noworld nproc occupy octal offset offsets omitted opened opens operate option optional options overridden page parameter path paths pblock pdir perm permission pfile plan pointer pointers portion pp preferred prefix prefixed prefixes print printconfig printed printing prints privileges processes prompt propose protocol q.v queue range read reading reads reclaim reclaimed record recording records recourse recurring redials reestablish refuse regulations rejecting remove removes removing rename renamed renaming replaced replacing reports represent require resets response restore resumes retire rob root rooted rules run runs ry sanity save scan scans score script sdc0 sending served server servers services serving setgid setting settings setuid silently similarly situation size snap snapclean snapshot snapshots snaptime source sources sources.cs.bell space specifies specify specifying split src srv standard stands started starts stat sticky stop storage stored string structures successfully super support suspends switch symbolic sync sys sys:sys systems table tag takes tcp temporary throughout time timeout timer times toggles track transaction translation treating tree twice type typically u.s uid uids uname unames unchanged unconfig undone unhalt unix unopened user users using usr usual vac valid variable variables various venti verb visible wait whichever worse write writes writing wstat yields yyyy fossilcons 8/fossilcons + 9sys 9syscall able affect ancestors becomes bss built child clean closed collect copied copy created current data default dereferencing descriptor descriptors diagnostics disallowed dissociated env environment errstr exclusive exit explicitly file files flags fork fork.c forking id ids include inherits initialized int integer intro invoker's invoking isolated kept leave libc libc.h logical manipulate maximum member member's mount mounts mutually necessary note notepg notes parent parent's particular pathnames permits proc process processes range receive regardless rendezvous required resources return returned rfcenvg rfcfdg rfcnameg rfenvg rffdg rfmem rfnameg rfnomnt rfnoteg rfnowait rfork rfproc rfrend segment segments selects share shared shares sharing sleep source space src stack starts subset sys table tags types u.h unable unaffected value values variables void wait waitmsg written fork 2/fork + 9sys 9syscall access accessed accessing allocated anyone append associate atime attachment attributes beware bit bit16sz bits blocking buffer bytes care char check communicated comparing connections constants content conversions copied count counterparts current data deal defined described descriptor dev device diagnostics dir directories directory dirfstat dirfwstat dirread dirstat dirwstat dmappend dmdir dmexcl dmexec dmread dmwrite doing don't e.g edir entries epoch equal error errstr except exclusive execute fcall fd fields file file's files format freeing frees fstat fwstat gid gmt groups guaranteed id identifies include includes independent indicate initialize initializes int integer integral intended intro jan kernel knows leader leading length libc libc.h list locked machine malloc maximum measured member mismatches mode modified modifier modify mtime muid names necessary nedir network nil non nulldir operate operation owner parent passing path permanent permission permissions pipes plus pointer prefixed process provided qid read resides responsibility responsible retrieve retrying return returned routine routines says search seconds selects server servers setting short similar similarly size source src stat status storage streams string strings struct structure structures subtype succeed success successful symmetry sys time type typedef u.h uchar uid uint ulong unique unsigned user users using value values vers vlong void whenever write wstat stat 2/stat + 9sys 9syscall allocated appending array await blank blocking buffer byte bytes calling char child child's code colon contains data descendants diagnostics discarded discards elapsed errstr exit exited exiting exits fields file filled fills fit fork formatted freed getfields holding id include int length libc libc.h living longer loved malloc message milliseconds msg necessary nil nul parsed pid prefixed proc process programs properly real remainder representation rest resulting return returns routines source spent src string struct structure sys terminal textual time times tokenize truncated typedef u.h ulong underlying units user using value void wait waitmsg waitpid wait 2/wait + 9sys 9syscall array boundary buffer bytes char character defined describing diagnostics discarded err errmax error errstr exchange fails fit fmt format generated include int intro libc libc.h libraries mechanism modify nerr nul null outputs pass perror print process property provided provides reads records recover rerrstr return returned returns silently source src string style swaps sys takes truncated u.h uint user utf value verb void werrstr werrstr.c write errstr 2/errstr + 9sys a.d accordingly alternate anyway applies ascii asctime assumes aug boot broken bugs byte char clock constant consults contains content convert converts corrects ctime data date daylight delta determine difference directly edt env environment epoch equipped est fields gmt gmtime greenwich handle hemisphere hour hours ignores include init int libc libc.h list localtime mday mean min minutes mon month newline non overwritten pairs pointer pointers provincial range remainder requested return returned returns routines savings sec seconds sic source southern src static string struct structures sunday sys text time times timezone tm tm2sec typedef tzoff u.h values variable wday wed width yday zone ctime 2/ctime + 9sys abort abort.c access broken causing current debugger enter fault generate include inspected libc libc.h process source src sys u.h void abort 2/abort + 9sys accept accepts accessing acfd actual addr address addresses adir aid allocated allows announce announcing appended asterisk attempt attribute auth authentication avoided base bekremvax binding break buf buffer bytes caller callkremvax can't cfdp char closely closing common communicate communications complements completely conndir connection connections contains control conventions conversion copied copies cs ctl data default defnet defservice descriptor destination determined dfd diagnostics dial dialauth dialing dir directory dns domain e.g echo echoing eof establishes existing exists exits fail fails fd fd2path file files forcing forever fork forking freed freenetconninfo getnetconninfo guaranteed hang hangup holding host include indicate int ip ipconfig kremvax laddr lcfd ldir length libc libc.h listed listen loop lserv lsys merge messages meta mount multiplexed ndb net netaddr netconninfo netmkaddr network networks newdir nil non obsolete obtained opened ordwr pair parameter path performing perror pointed pointer points port pre process raddr read reading received receiving refuses reject remote replaced return returns root routine routines rserv rsys send sent server setnetmtpt simply sizeof slash source spec specifying src stands static string struct structure succeeds successful succession suitable switch sys takes tcp token tolen try typedef u.h udp using value variable void write writing written dial 2/dial + 9sys accept algorithms allocate allocated alternatively application arranged association attach authenticated authentication authority base buffer bugs byte bytes caller calling cert cert.pem certificate certificates certlen certs.pem chain channel char check checked client communication communications comprises compute confirms conn connect connection constant convenient conversation copied copy creation crl data decode defined described descriptor desired device diagnostics dial digest digesting dir directory doing ed encalg encoded encoding encrypted encrypting encryption ends establish evidence executes exits extra factotum failure fd file filename files fmt freed freethumbprints freshly full generation guaranteed handshake hash hash,table hashalg hashes higher id implementations include initialize initthumbprints input int intermediate interoperate isclient kernel key keys layer lcfd ldir length level lib libc libc.h libsec libsec.h linked list listen loaded malloc mallocz message mp.h nearly needs negotiate negotiated nil non note ok okthumbprint ongoing opt optionally options output parameters particular path pcertlen pem pemchain pemlen pointer points port previously private protocol protocols provide pushtls pushtls.c rc4_128 read readcert readcertchain record remote remote's required resume return returned returns revoked root rsa run salting secret secrets security server services session sessionconst sessionid sessionidlen sessionids sessionkey sessionkeylen sessiontype setting sha1 sha1dlen sizeof software source speak src ssl ssl3 standard storage store stored struct structures supported suspect sys table thumbprint thumbprints tls tls.h tls1 tlsclient tlsconn tlsserver trace transport trust trusted ttls type typedef u.h uchar user void whenever written pushtls 2/pushtls + 9sys access access.c accessibility aexec aexist aread awrite bugs char check checked client defines desired determine diagnostics directories errstr evaluates exec executable execute exist existence expected fail file format include int leading libc libc.h merely mode permission permissions permit permitted proper read returned searches server source src stat sys u.h unless write access 2/access + 9sys access allocated char creates diagnostics env environment errstr exists file getenv include int libc libc.h malloc memory pointer putenv reads returned returns source src string sys terminates u.h val value variables writes written getenv 2/getenv + 9sys accessed added addr address allocation alternate break brk bss bytes data defined diagnostics dynamic error errstr exec execution growing highest idea include incr int intro libc libc.h location locations lowest malloc memory occurs ordinarily pointer program's programs return returned returns rounded rounding sbrk sbrk.c segattach segbrk segment source space src stack storage sys system's therefore u.h ulong via violation void brk 2/brk + 9sys actually address advanced allocated array buf bytes complete constant contrast data decodes define dependent diagnostics dir directory dirmax dirread dirread.c dirreadall entire entries entry equivalent error errstr exactly fd file filled format freed hold impunity include independent int integral intro layout length libc libc.h limit machine malloc maximum necessary negative nil occupy offset pointer read reads return returned returns size sizeof source src stat statmax steps structure structures subdirectory successful sys time u.h unpacks upper value variable dirread 2/dirread + 9sys additive algorithm bits buf buffer bugs bytes calling cons descriptor dev double due fastrand fastrand.c feedback file fill fills frand generate generator generators genrandom genrandom.c hundred include initialize initialized int integer libc libc.h libsec libsec.h lnrand lrand maintain mantissa mod mp mp.h mprand native nature nbytes nfastrand nrand ntruerand port prng prng.c produce pseudo rand rand.c random read reproducible return returns seed seeded significant source srand src static stream sys testing time truerand truerand.c truly twice u.h uchar ulong uniform unsigned val value void whatever rand 2/rand + 9sys addr analogous analogy array buffer buffers bugs build bytes collected data diagnostics errstr facilities fd future gather implementations implicitly include int intro io iochunk len libc libc.h malloc nio offset operations placeholders preadv pwritev read reads readv readv.c received returns routines scatter seeks source src standard stored storing struct structures successive supplement sys total typedef u.h ulong vlong void write writev writev.c readv 2/readv + 9sys afid amount analogous aname ap aqid assumes bit bit16sz bit32sz bit64sz bit8sz brethren buf buffer buffers byte bytes char checks comments complete constant convd2m convenient conversion convert converts convm2d convm2s convs2m copied copy correct count data define defined described dir directory dirfmt dirmodefmt effective ename encoding entire entry enumerated equal error etc exactly except exception exchange extract fcall fcall.h fcallfmt fd fid fields file fill fmt fmtinstall format formatted formatting full gbit16 gbit32 gbit64 gbit8 greater handling header holds include includes incorrectly independent installed int interface internal intro iohdrsz iounit length letter libc libc.h locations machine macro macros maxwelem message messages minus mode msize nap nbuf necessary needed negotiated newfid nil nstat nwname nwqid occupied offset oldtag packing partial pbit16 pbit32 pbit64 pbit8 perm plan plus pointer pointers portion precedes produced properly protocol qid quantities rattach rauth rcreate read read9pmsg related reports representation representations required rerror reserve resulting retrieve return returned returning returns reverse ropen routine routines rread rstat rversion rwalk section selectively short size sized sized2m sizes sizes2m source src stat statcheck storage store stored storing string strings strs struct structure successful successive suitable sum sys ta tag takes tattach tauth tcreate test tflush therefore times topen translation tread turning tversion twalk twrite twstat type typedef types u.h u32int uchar uint ulong uname union ushort valid validity validly value values verifies version vlong void wname wqid wstat fcall 2/fcall + 9sys alg algorithms attach authenticated authentication cfd channel char communication communications connects control data descriptor device diagnostics dial directions encrypted encryption failure fd file include int keys libc libc.h message nil non opened opens pushssl return returned returns secin secout source space src ssl starts sys u.h version written pushssl 2/pushssl + 9sys allocated data exec include legal libc libc.h location management nil pointer privalloc privalloc.c private privfree process processes releases returns segments share shared slots source src storage sys u.h void privalloc 2/privalloc + 9sys amd64 architectures bugs calling child code cons converted counter counters cpu cputime cs cyclep cycles dev double earlier elapsed exec execute file fills illegal include instruction int libc libc.h milliseconds non null opening pentium process processes processor's processors read reads real reset returns running seconds source spent src store stores sum supported sys time times timestamp u.h user via vlong void cputime 2/cputime + 9sys amounts atomic breaking broken bytes data descriptor descriptors devices diagnostics discover dup error fd file files include int interface intro involving iounit libc libc.h maximum occurs operating operations particularly pieces protocol read reads records return returns routine size smaller source specific src sys transfer transmitted u.h unit unknown unspecified using value writes written iounit 2/iounit + 9sys answer bintime bugs cons cputime descriptor dev diagnostics epoch errstr file former gmt include jan latter libc libc.h maintain nanoseconds nsec nsec.c opening reading return routines seconds source src static sys time time.c tp u.h value vlong void time 2/time + 9sys append arg argv0 bugs char colon cons console date described describing directory error errstr exist exits fields file final fmt format formatted holdover include int interface intro libc libc.h log logname logs machine message messages multi newline nil null opened perror perror.c port preferred print printed prints process produces program's programs running safely short slashes source space src standard string suppressed sys sysfatal sysfatal.c syslog syslog.c threaded time u.h value void writing perror 2/perror + 9sys buf buffer bugs bytes char consulted current diagnostics directory error errstr fd2path fills getwd getwd.c guaranteed include incorrect int libc libc.h null path places provided pwd reach representing returned returns size source space src string sys u.h underfoot getwd 2/getwd + 9sys calling char delivered diagnostics errstr include int intro libc libc.h note notepg notify pid pngroup pnproc postnote postnote.c proc process returned send sends source src successful sys target u.h write writing written postnote 2/postnote + 9sys cons converts current dev diagnostics errstr exec executing getpid getppid guaranteed id ids include int intro libc libc.h machine parent pid ppid proc process processes reads returns running source src sys u.h unique unsuccessful void getpid 2/getpid + 9syscall a.out accepting accessible accurate address allow allowing apply architecture argc argment argv array attributes beyond bin binary bugs bytes calling carried cell char clock constant contains controls convention conventions copy counter counts current cycle cyclefreq cycles data defined dependent diagnostics directory e.g entry env environment errstr except exec exec'ed execl execl.c execute executed extern fail fast file files finally finite follow frequency global handler holds honors hz id image include int interface interpret intro kcycles keeping kernel libc libc.h limit list lost lower ls machine main mc measured milliseconds mode naming newly notification notify nprivates null ocexec opened or'd original overlay parameters particular pcycles permissions pid pointed pointer pointers points port private privates process process's processes processor prof profiler profiling programs rate raw rc reading register remain return rfork script segments share shell size source space spent src stack stat storage struct structure successful sys time tos tos.h transfer tstksiz typedef typically u.h ulong updated user uvlong valid vlong void working zeroth exec 2/exec + 9syscall accept amount auth bind buffer bufsize char commonly connection constraints default defaults defined determines diagnostics directly errstr fauth fd final fversion highest include initialize int interpretation intro kernel length level libc libc.h lower manner mount negotiate negotiated negotiation nversion overwritten performed possibly presented protocol rare read receive represents requests return returned sensible server size source src stage string strings subject sufficient support sys text therefore total u.h value values version fversion 2/fversion + 9syscall access actually addition allows anded append applications asking atomic automatically bind bit char client closed closes constituent copy create created creates creating defined depends described descriptor descriptors details diagnostics directory dmappend dmdir dmexcl doesn't error errstr evaluated everyone exclusive exec execl execute exist existing exists extended fails fd file files final guaranteed identical implicit include int intro invalid length libc libc.h mechanism mode necessary ocexec oexcl oexec omode opening opens operation orclose ordwr oread ored otrunc owner owrite path perm permission permissions permit prepares process provided purpose read reading remain remove requested require returned returns reused rewrite says source src stat structure succeed succeeds sys termination time truncate truncated u.h ulong unchanged union unlike user userid valid values write writing open 2/open + 9syscall access addr address adds allocation allow allows arg assembly attached attaching attr attributes belong bit bltz boundary bounds bss btas buffers bugs build byte bytes caching calling char choose class classes contains control cop3 creates data default dependent detached device devices diagnostics draws equal error errstr exec exec'ed executable fails failure file filled fixed fork fp frame free'd freed greater hardware helps implement implements include inherited initialized instruction instructions int interface interfaces kernel language leaves len libc libc.h limit lock locks low lowest machine machines map mapped maximum memory method mfc3 mips movb movw multiprocessors nearest negative nop nor operating outside overlap overlaps page particular permit physical plain points portion proc process process's provide provided read referenced release remain removes ret return returns rounded save sb segattach segbrk segdetach segflush segfree segment segment's segments sema semaphore series sg_cexec sg_ronly sgi shared size software source space span specific specifies specify src stack succeeds success suitable support sys systems tas tells test text trap trapped try type typically u.h ulong uncached unknown unmap untouched va valid vary virtual void segattach 2/segattach + 9syscall access afd amount aname attach auth auth_proxy authentication authsrv bind char commonly connection conventionally current descriptor diagnostics directly entry error errstr establish fauth fauth_proxy fd file include int libc libc.h mount negotiate particularly protocol rare require resources return returns server source src subsequently successful sys ticket typically u.h user using value fauth 2/fauth + 9syscall access bind boundary buf bytes char character component described descriptor diagnostics directory error errstr executing fd fd2path file getwd include indeed int intro kernel libc libc.h longer nbuf ns null occurs opening original path proc rebound refer removed renamed resulting return returned returns rooted silently source space src stored stores sys therefore truncated typically u.h underlying unless update utf value fd2path 2/fd2path + 9syscall accessible add addition afd alias amount aname attached attempt attempts auth authenticated authentication automatically becomes bind binding bound bugs cache cached caching char chooses client closed condition connection consisting constituent controls create created currency current data default defined definition described descriptor details device diagnostics directories directory doesn't doing effects enabled errstr evaluated evaluating evaluation everything except exist existing fails failure fauth fcall fd file files final finally flag flags fork goes happens henceforth hide include int integer intro kernel libc libc.h machine mafter mbefore mcache mcreate messages mnt modification modify mount mounted mounting mrepl names network null object operations or'd original originally particular particularly path pipe positive possibly prepared process processes read reading refer refers replace requests required respond retrieved return root routines satisfy searched section selects served server serving source space src srv string subsequently success successful successfully sys time translated translation tree trees turns u.h unbound undone union unique unmount unmounted valid value verified visible writing bind 2/bind + 9syscall actions address alarm ansi ape arrival asynchronous atnotify atnotify.c awakens bad behavior breakpoint broken bugs bytes calling cancel cancels char characters child clears closed common communicate condition connection correctly counter current debugged debugger debugging default defined defines del dependent depends described designed discards discouraged divide dividing due e.g elsewhere emulation enabling environment errlen erroneous error except exception exceptional exceptions exec executed exiting exits expired external externally file finish floating fork format fp fppc fptrap further generated handle handler handlers hangup id identical improve include includes incomplete instruction instructs int interrupt interrupted intro jump key kill layout leaves libc libc.h limited longer machine modifying ncont ndflt needed neither non note noted notejmp notepg notes notification notified notify nrstr nsave nul null objtype odd offending operating operations origin original overridden parameter parent pc perform pipe pointer port portions posix posted posts prefixed presence printed proc process process's programs provided puts raises range read receipt receive received receiving recognized recorded recover regardless register registered registers registration replaces reported resolved restores restoring resume resumes return returns saved setjmp signals source specific src stack standard starts stopped string structure suffixed suicide suspended syntax sys terminal trampoline trap traps truncated types typically u.h unaligned undefined ureg ureg.h user using values void vulnerability window write writing notify 2/notify + 9syscall actual alarm amount ask clears clock cpu current delay delayed diagnostics errstr include int interrupted intro invoking libc libc.h milliseconds millisecs note notify previously process remaining requested reset return returning returns run sent sleep source src successive suspends suspension sys time u.h unsigned value waiting sleep 2/sleep + 9syscall actually advanced atomic buf bytes characters closely combining concurrent console conventionally count data descriptor diagnostics dirread dup equivalent error errstr event execute fd file guaranteed include int interference intro libc libc.h match memory multiprocess nbytes non offset operations permit pipe port positive pread programs protocol pwrite read readn readn.c reads readv refers regarded requested return returned returns seek source src successive sys u.h value vlong void write writes written read 2/read + 9syscall addr address allocation allow altered brk bss bugs bytes control data defined diagnostics error errstr fully idea identified include length libc libc.h location lowest memory overlapping page particular prevent proc re return returns rounded saddr segattach segbrk segflush segfree segment segments size source src stack subsuming sys system's text typically u.h unused valid void segbrk 2/segbrk + 9syscall address allows arrive arrives awakened common communication conjunction control diagnostics enables errstr exchange exchanged execution fork forks include inherited interrupted level libc libc.h lock meets memory parallel process processes programs rendezvous respective return returned rfork rfrend scheduling segattach share shared source space src succeeds suspends synchronization synchronize sys tag typically u.h unless user value values void wishing rendezvous 2/rendezvous + 9syscall address architecture boundary bytes cache caches contained correct correctly data depends diagnostics errstr flush flushed include instruction int invalidates len length libc libc.h machine memory nearest page pages proc referenced rounded segattach segbrk segflush segment segments source specific specifies src straddles sys u.h ulong understanding va void works writes segflush 2/segflush + 9syscall allocated chooses closing descriptor descriptors diagnostics dup duplicate dynamically errstr file greater growth highest include int intro libc libc.h lowest newfd oldfd prevent referring requires returns source src sys table u.h unwarranted dup 2/dup + 9syscall boots char chdir diagnostics directory dirname errstr evaluating explained file include int intro invoking libc libc.h names plan process source src sys u.h working chdir 2/chdir + 9syscall boundaries buffer buffered bugs byte bytes channel closed comes communication contiguous cooperating create created creates data descriptors diagnostics dirfstat errstr established exited explicit fd file fork fstat full generate include indistinguishable int interprocess interrupted intro length libc libc.h note pass pipe preserved processes read reader reading reported return returned returns source src stat sys terminates transferred u.h unknown whichever write writer writes writing written pipe 2/pipe + 9syscall bytes current diagnostics directory errstr fd file include int intro libc libc.h location offset op pipe plus pointer returned seek seeking size source src sys type u.h value vlong seek 2/seek + 9syscall char diagnostics directory discards errstr file include int intro libc libc.h orclose permission remove removes source src sys u.h user write remove 2/remove + a,a absolute accent accented accepts addr address addresses advances assumed bell bit browser bugs byte characters cmd coverage current default described dict dictionaries dictionary dictname distributed doesn't edition english entries entry equivalents etc exact execute executes expression expressions files folded folding font format headword headwords i.e implicit index integer interactive key labs latin leading letter letters lib list literal lower mapped match matched matching mode necessarily non oed oed2 oed2index offset option options outside oxford pairs pattern patterns pelm print printed prints pronunciation quit raw re regexp regular repeatedly resets results setting sorted source src standard syntax sys takes th time translating try unicode unicode.9.font upper variants version wide wrapping dict 7/dict + a.c a.e a.ne a.s a.se accepts alone apply arc arcrad arcs arg1 arg2 arranged arrow arrowhead arrowht arrowwid assumed atan2 attribute attributes backslash balanced bare block bot box boxht boxwid built center centered centerline chop circle circle.nw circlerad cmd code commandline comments compass consists contained contains context continued coordinate copy corner cos current dashed dashwid default defaults define definition determined diam dimensions direction divided doctype dotted drawing edition eigh eight ellipse ellipseht ellipsewid enclosed ending entering entry etc eter evaluated except existent exit exiting exp expr expr,expr expressions extreme figures file files fill filled floating font format generally geometrical grammar grap graph graphics height ht implies inches independently input int internally introduced invis invoked irrelevant item items ius kernighan keyword language letter lineht lines linewid list ljust log lower macro manual max mentioned min missing motion motions move moveht moves movewid names ne newline newlines non nr nth null nw object objects occurrences ones op opt optional ordinal output pair pe permitted pf pic picture pictures placename points positioning preprocessor preprocessors primitive primitives print printing process produces programmer's proportion ps qualified rad rand refer refers regardless remain removes replaced replacement representing requests research reset restored retain revert rjust saved scale scaled se semicolons sh silently sin size source sp spline splines sprintf sqrt src stand statement statements strings sw synonym sys tenth tex text textht textwid th thru time tpic troff typesetter typesetting ultimately undef unit unix unless upper value values var variable variables vertically volume ways wid wide width x,y pic 1/pic + a.c abs access actions acts added aggregate aggregates alarm alloc alltarget ambiguous ampersand andrew ar arbitrary arc architecture archives arg1 arg2 assignment assignments assume attr attribute attributes augmented automatically b.c backquoted backslash bar bin blank blanks bob bquote break bugs build building builtins caused cc cd cflags character characters clause cmd cmp colon comments compilation compile computed conditions conjunction considered consists contains content continue control copy correct cp cpus current date deal debugging default define defined deleted depend dependency depends derive described determine determines dhz differently distinct distinguished don't draws egp elided environment erroneous erroneously error errors evaluating everything exactly except execute executed executing execution exist existing exit exits expand expanded expanding explain exported expression expressions extracts fashion file file's files flag flandrena folded foo formed gram.y grammars graph hume id identical identifies implicit includes increasing initially input inserting intermediate interpreting intro invoked ld ldflags learn legal length lex lex.c libc.a library lines list literal machine main maintain maintaining master match matched matches maximal member membername meta missing mk mk's mkargs mkfile mkfiles mkflags modification modified modify modifying names needed newer newline newmember newprereq non nonempty nonexistent nproc null o:r obj objtype occurrence occurrences older omitted option optional options output override overrides parallel parentheses parsed parsing pattern percent pid places plan possibly potential precedence preceding prereq prereq1 prereq2 prerequisite prerequisites pretend print printed printing prior process processed produce prog propagated quoted quotes rc read recent recipe recipes recognizable recommended refer reference references reflect regexp regular related rely remade replaced reports respect respects restrictions return returning rule rules run runs sam satisfies script seemingly separating sequentially settings sign simultaneously slash slot sometimes source space specially specify src stamp stamps standard static status stem stem.2 stem.c stem0 stem1 stem2.c stem9 string strings subexpressions substitute substituted substituting substitution successor supplying supported surrounding sys tail takes target target's target1 target2 targets terminate text time touch treatment triggered trust types unless unquoted update updated updates updating using value values var variable variables virtual visible what's x.tab.h x.tab.h:pcmp y.tab.c y.tab.h yacc mk 1/mk + a.i accurate bin bugs chapter chapter.0 chapter.1 deduce dev doctype document eqn eval examines file files formatting grap guesses input inspired intuit invokes lp macro mm ms nroff option output packages pic preprocessors prints rc recognizes related source standard style tbl text troff typeset doctype 1/doctype + a.k.a access additional address allowing alternative aquarela assigned assumption attach attached attaching attempt attempted attempts auth authenticated authenticates authentication balancing bddiv bntlm bntlmv2 bugs capabilities capacity cifs cleartext client clients cmd comma comment compatibility configured connect connection considerably contains data debug debugging default descriptive dfs dfsroot directory discover disk dns dom domain domains dynamicially enable enabled eschews established expects extra factotum fails features fields file filer files filesystem finally flag flags flexible full granted group's groups guest host icalled idle included indicating ip kerberos key keyparam keys keyspec level link list lists live load lower machine machine's mainly maps maximum method methods microsoft's microsoft™ mixed mntpnt mount mounted ms mtu names netapp netbios network none nt nt4.0sp6 offered option optionally os ownership packet parameters pass password path paths physical plain plan9 pluto post predating printed pro proto protocol proximity published rarely recommended remote request requested requires resolution root routing running samba select selected server server's servers servers's session sessions share shares sharing slip slow smb smbserver source space specific src srv srvname stat strategies subdirectory support supported synthetic sys systems terminology tested time transfer translates trees try type unfinished unit user user's username users using version videospace virtual windows winxp workstations xyzzy cifs 4/cifs + a.out a.out.h a_magic absolute acid added address adjustment algorithm alpha amd architectures arm array associates assumed att automatic automatically base binary bit brk bss bugs byte bytes char characters clustered compiled compiler compilers component components computed consists constant contains conversion core correspond counts current d_magic data db dec dedicating define defined dependent describe described directives discover downwards dsp e.g e_magic encoded encoding endian entries entry exec executable executed expressed extended extension facilitate file files finally flags format forming frame growing header highest hold i_magic image implement include included initialized instruction integer integers intel interpret interpreting j_magic k_magic l_magic laid le leaf length location locations m_magic mach machine magic main mc68020 mc680x0 memory mips moreover multiplied n_magic names newlines nm nul null object occupies occupying offset operations page parameter path pc pcsz plan pointer pop possibly powerpc pre preceding preprocessed printed produce q_magic quantum recorded recover reduced register remaining represent represents rounded run scan section sections segment segments setting sign similar six size sizes slash slashes source sp sparc specify spsz stack starts static stream strip struct structure subtracted symbol symbols syms table text type typedef types uchar uninitialized unique using v_magic value values variable virtual x_magic a.out 6/a.out + a.out a.out.h access actually addr address adjusted allow applied arbitrary architecture array ascending base bss buf bytes caller caller's calling char code comments compiler's component components contains counting creates current data decide default defined defines described descriptor details dev diagnostics driver dynamically dynfindsym dynfindysm dynfreeimport dynimport dynld dynld.h dynloadfd dynloadgen dynobj dynobjfree dynsym dyntabsize entry equal err error errstr executable executing export exported exports exporttab extern external extra fd fields file format frees further global image import imported include int internal invoked item kernel length libc.h limited linkage linked list listing lists load loadable loaded loader loaders loading loads longer looks mach marks match maxsize module module's modules names nbytes necessary needed needs nexport nil nimport non note noted nsym obj object offset operator option parameter particular pointer pointers points process produced provided provides read reading reference references reflect relative relocation representing represents requested required responsibility resulting return returns sections seek sig signature signof size sizes sorted source space string struct structure success symbol symbol's symbols syms table table's tables text total transferred type typedef u.h uchar ulong using value values variant vlong vlong,int void werrstr wishes xxxdevtab dynld 2/dynld + a.out absolute access accessible adding additional addr address addresses application applied applies approach architecture architectures array assigns automatic base basepc basic beyond bio.h boundaries bounding bounds buf buffer bytes calculated cany cauto cdata char character class code compiler components constant contained contains conversion converts count counter cparam crackhdr ctext current data defined derived describe described describes describing descriptor desired device dummy e.g encname encoded entries entry equal equivalent error errstr executable executing exists fd fhdr file file2pc file:line fileelem fileline files filesym filled fills findlocal findsym fixed fn fnbound fp frame getauto getsym global globalsym handle header higher identify image impose inaccurate include increasing independent index instruction int interface internally invoke latter length level libc.h libmach library limits line2addr loads localsym located location longs lookup mach mach.h machine matching memory message names near nearest non nsyms null object occupy occurs offset opening operate operation optimized ordered original owning pair parameter parameters particular pass path pc pc2line pc2sp penalty pid places pointer pointers points popular pre prior private proc process processing produce proper provide range raw read recalculate receive receiving reference relative resolves results retrieval retrievals retrieved return returned returns riding search searched searches segment selected selects source space specification specifies specify speed src stack stacks startup statement stored str string struct structure structures success sym symbase symbol symbols syminit sys table tables target text textseg textsym th type typedef u.h uchar ulong uniquely unless unsigned using value values var variable variables vary via void symbol 2/symbol + a.out access adding additional address application architecture archive bio bio.h biobuf bp buf buffer built char characters code constructs contains current data decoded decoding defining definitions describe described describing destroys diagnostics difference directory dummy encoded errstr exactly executable executing extra extracted extracts file files formal generic header identical images include independent indicate indicates indicating input int intermediate interpretation interpreting invocation invoked isar leaves libc.h libmach library loaded loader mach mach.h machine malformed member missing negative nextar non object objtraverse objtype offset operates organization pointer pointing positioned previously processing produced provide readar readobj reads references relative representation requires resolved resulting return returned returns rewound routines sarname scans size source specifying src stored string structure structures sym symbol symbols sys table type u.h value vector void yields object 2/object + a.out acid address aghnstu alphabetically ar archive automatic blanks bss cmd components data db defined don't executable file global headers hexadecimal leaf letters lines list nm nm.c object offset options output parameter prefix print printed prints segment signature sort sorted source src static symbol symbol's symbols sys table text type undefined user value variable nm 1/nm + a.out binary cmd directory executable file files flag input ofile permission remove removes requires rewriting segments source src strip strip.c stripped stripping symbol symbols sys table unchanged write written strip 1/strip + a.out bsssize bytes cmd datasize default executable file files format print prints segments size size.c source src sys textsize total v.out size 1/size + aa accept accepted acid adjusts allows alpha amd64 ansi append apx architecture architectures argpos arithmetic arm array assembler assembly assignment attempt automatic based bin bit brackets bugs calculated cc char character check checking cmd code comment compatibles compilations compile compiler compilers compiling complete completely concurrently conflict conformance constant context convention conventionally cpp current db declared declaring dedicated def default define defined definition definitions dependent differs digital dir directives directories directory discussion disturbed division divison dname double dynld e.g eleven em64t emulated enable enabled enclosed endian entities environment equal equality error etc examining except explicitly expression expressions extensions extern external fails features fields file files finally flag format formatted formed forms full fully fvw generate generating generation global handle handles handling header identifies identify identifying ifdef ifndef implementation imported include included includes incomplete independent indices initializers initializes input int intel interrupts invoke kc language lax legal letter lib libbio.a libraries library lines list loaded loader loaders location machine machine's main.2 main.c manipulates mc68000 mc68020 mechanism messages mips mk mkfile modules modulus motorola names necessary needs nm non notation notes nproc obj object objtype obviate off_ on_ opaque operations operator operators optimization option options outer output parent partial particular parties pass pc pcc pentium permits pike places plan pointer pointers pragma pragmas preconditioning prefix preprocessing preprocessor presence print processes produce prog programs promotes prototype provided qc quotes records referenced register registerization reject related represents requires resolution retired rob routines run running says search searching separately shorter sign signature signatures signedness signof slash software sought source sparc specify spim square src standard standardly statement static string strip struct structure structures style sub.2 sub.c subsequently substructure substructures subunions sun support supported suppress switch sys systems tag tagname tells tenth third time type typedef typedefs types typically undef union unnamed unsigned unspecified unused using uvlong value values varargck variable variables vc verb version visible vlong void warning 2c 1/2c + aa add addition address addresses adds alias aliases aliasmail allows alter append attachment attachments automatically bin boris box builds cc cmd conformant contained content copyaddr dead.letter delivery determined direct directing directory directs display disposition edited envelope environment esc exist exists exit expands explicitly faces file files filter format formatting freely full header headers hit hold id inline input intentionally invokes key kremvax.com lines login mail mailaddr mailbox marshal match message mime mlmgr mode msg names natasha nedmail non nrx option options overriden passes personal pipefrom prefixed puts qer read reader recipient recipients reply replying replymsg required return rewrite rfc rio running send sending sent smtp somehow source squirrel.com src standard subject sys tells transmission type unless upas upasfs upasname user username using value variable window xr marshal 1/marshal + aaa.bbb.ccc.ddd abusive accept accepted accepting account accumulate additional address addresses allocation allow appended applicable asks assumed authorized banished banned bits block blocked blocking capabilities capability card care character characters checks cidr class code commas comments configuration conform connections consist consisting consults contact contains continuation convention copies covered cursory daemon date default defaultdomain defines delegation deny depends described describes describing destination detecting detection dial differs directories discarded discussion dns domain domains easier enabled entire enumerate equivalent error escaped example.com exercise exists exposed external facilities file files finally flag format friendly further gateway generally generated hostdomain identical implements inadvertently include incoming input insensitive internal ip lacking larger legitimate length lengths lib limited lines list listener loops low lower mail mask matches matching mechanisms message messages missing modem mounted names necessary negates network networks norelay notation notice numeric octet octets omitted option options ourdomains ournets override overriding parameters pattern port ports postmaster precede processed processing prohibited protected protocol provide qualification queue.dump random randomly range ratfs ratify receive received rejected rejection rejects relay relayed relaying remaining require restated rfc safety saveblockedmsg saved saying scanmail security seldom select selects sender sender's senders sending series served server setting significant similarly slash slave smtp smtpd smtpd.conf software source space spam specifications specifies specify specifying standard stuck style sub subdirectories sufficient supported synonym systems tcp test token tokens traffic treatment trusted unauthorized unreturnable user users uucp values verb verbs verifies verifysenderdom wild works xx smtpd 6/smtpd + aade access account adm adnptn allow allows anonymo anonymous authenticate authentication authenticator authsrv bin bsd challenge character clear client cmd codes completing connection connections control daemons debugging default defines direction directory don't echoing encrypt encrypting error execs executes exist expect file files ftpd ftpd.c ftpfs handheld handshake httpd httplogin imply incoming input intended internet ip ipserv lib listen locally locked log login logs machines namepace namespace namespace.ftp namespace.noworld namespace.world netkey network none noworld nu option options originate output passwd password permit plan pop3 preserve print printed programs protections protocol rc remote require requires response returning rexexec rexexec.c rlogind rlogind.c runs scripts securenet shared source src standard started store subtree support sys telnet telnetd telnetd.c transfer treat trees trusted types user username users using usr via write ipserv 8/ipserv + aadfips able added addfrg address addresses administrator advertised aliasmail append appended assigned attacks authenticate authenticated authentication autistic banner believe bin blocked broken busted can't capability carefully certfile certificate class clear clients cmd code configuration connect connection connection's connections continually conveniently converted copies cram created current debugging default delay deliver denial destaddr destination details determine determined deters dev dialogue directory dns domain don't dropped e.g effects encrypted encryption entry envelope error esmtp evilipaddr exists expectation extension faces factotum file filter finally flag forward frequented fully gateway greeting grey header host hosts id ignore implies incoming incur inferred input intended ip isn't lessen lib list listen listener log logged login longer looks mail mailer mailers marshal md5 message messages minutes mlmgr mx mydom names nedmail netdir network networks non noop nor notified option options output pass passes password peer permits permitted ping plain prevents previously processing protocol protocols provoke qer qualified queue.dump rcpt received receives receiving recipient rejected relay relaying remote repeated represent requires responding retry rewrite rfc3207 rfcs run saved seconds send sender sender's sending sends server session sites sleeps smtp smtpd smtpd.conf smtpdb source spammers specifies specify src standard startup stored sub supported supports sys sysname systems tags tls tlssrv tmp transfer transport trusted try trying turns uniquely unless unqualified upas upasfs user users using usual valid validation verify via wait whenever whitelist smtp 8/smtp + aan aan.c announced assume astro6 automatically aux break breaks broken client client's cmd connection connections data default dialstring directory due e.g echo encapsulated establishes exec exits exportfs file files import imported ip listen listens log lost machine maxto mnt netdir network networking networks option persistent protocol re reconnection redialing retransmits roaming run seconds sed server sob source space src started sys term traffic tunnels unacknowledged unique unreliable using voluntarily aan 8/aan + aan access accesses acts address aes algorithms allows announce appearance arbitrary archive attach auth authenticate authentication aux avoid bin boot broke broken bypass cd client cmd compatibility compute connection connections contains copy correctly corresponds cpu create created creates current dbgfile debug default defaults described device dial directly directory disallow disallows dr dump e.g echo enable enc encrypting encryption equivalent establishes except executed export exportdb exported exportfs exporting exportprog expression file files fragmentation ftp ftpfs glenda handle helps import imported incoming invoked invokes kept kernel level lib lines listen listener log ls machine manipulated match matched maximum message mnt mode month mount mountable mounted mounting mounts msize names namespace network networks nfs.boot nfsserver none nsfile obtain offer operations options p9any particular path pattern patternfile perm permitting person pgp pieces pipes plan plumbing portions posts prefix proc process protocol publish rc4_256 read reads regular relative relay relayed remote requested requires restrict results returned rio root rooted run running secrets send serve served server servers serving session setting sha1 simulate size source space spy src srv srvfs srvfs.c ssl started subtree sys systems tail term terminal tmp traffic tree tunneled typically unnecessary user users using usr version windows wire working writes exportfs 4/exportfs + aan access algorithms allows ancient arbitrary args assume auth authenticate authentication authority backwards bin bind boots clear cmd compatibility complete connecting connection connection's construction control copy cs default defaults described descriptor directories directory enc encrypting encryption equivalent expected exportfs file filter flags foreign gets global httpd import import.c imported incoming inferno inside interfaces internet intranet ip key keypattern kremvax listen listener machine mntpt mode moscvax mount mountable mounted mountpoint mounts namexxx ndb net net.alt network omitted onto option optionally options outages p9any pages perform plans port post pre private process protect protocol protocols push rc rc4_256 read remote restart restarthttpd rowebfs run runs select serve served server servers sha1 skip source space specify src srv ssl started supported suppose sys systems tcp telnet temporary tls traffic tree trusted ucbvax union user using usr valid web webvax wire import 4/import + ab abstract acceptable ae ai append attached au author author's automatic automatically bell bi block blocked bold boldface bottom box boxed bp br break bt btl bx canned centered column conjunction constant copies cover ct cw da date de default defined definitions display displayed document documents ds e.g edition eg en enclosed engineer's ens eq eqn equation equations except explanation extension facility fe file files filling float floating font foot footer footnote format formats formatting fp fs full grap graphs hanging heading height hill ho holmdel ih illinois implies impunity inches indent indentation indented initials input insert institution internal invoked ip italic italicize jersey justified ke keeping kept kf ks laboratories larger lesk letter letterhead letters level lg lib list location lp ls lt lucent lucidasans macro macros manual manuscripts margin margins material measured memorandum mf mh moved ms murray na naperville nd neqn nh nical nl non note notes notice nroff numbering omit optional options output package page pages paper papers paragraph pe pf pic picture pictures piscataway positions pp precede preface preprocessors print produced produces programmer's provides ps py qe qp qs quoted re record redefined reference registered relative released repeated report request requests research reset restore roman rp rs section sg sh sheet signature size sm smaller sp space straight subsection suppressed switch sys ta table tables tabs tag tbl te tech technical telephone tenth text th third title tl tm tmac tmac.s tr trademark troff ts typing typist ul underline unix unsafe using ux value various verbatim vertical volume wh whippany width yes ms 6/ms + ab accepts access accessed accessing acme actions actually addr address addressed addresses affect analogous appended appends applied automatic bar behave bit bitwise blank bound built button buttons byte cancel character characters chorded chosen clean cleartag cmd colon compatibility complete compound conjunction cons consctl console context control controlling count created creates ctl current cut data dealing decimal decimally default del delete deleted described describing determined dev diagnostic dir directories directory dirty discovered display distinct dot dump dumpdir echo elided environment equivalent error errors etc evaluated event exactly examine except expansion expected explicitly expressed expression extra fields file files final fixed fixfont flag follow font format formatted fourth fully guarantee holding holds id ids immediate included index indicated indicating indirectly individually input inserted interactive interface interpret keyboard label labeled language limit lines literal loading location maintain mark marking mentioned menu message messages mnt modification modified mount mounted mouse ncol necessary needed newline newlines nomark nomenu non noscroll null numbered occur offset offsets omitted opened operations opposite optional origin originated output partial particular paste permit pixels plain plus post q.v qualified random read reader reading reads recently recognized recover recreate redirected redo regular related relevant remove replaces reported reporting restricts returned returning returns rio run runes running scroll scrolling searches sees selected selection sent sequentially serves services source specific src standard starts stop string style subdirectory supply sys tab tag terminal text textual third type underlying understood undo undone unique unlike unwritable user user's usual value varfont variety versions vertical virtual visible wherein width win window window's windows writable write writes writing written wsys xdata zeroxed acme 4/acme + abaco absent acme alternate appearance bin browse browser browsers bugs button character charset clicking closed cmd columns default displaying error features files finally giant imports lightweight link mnt mount mouse mtpt ncols necessary network opens outside page prevents progress rc readweb selects source src standard starts subshells sys url vnc web webcookies webfs wide window abaco 1/abaco + abandoned aes algorithm awkward basic bit bits block block_cipher blocks blowfish book breaking broken brute buffer buffers bugs byte bytes cbc chain chained chaining characters cipher code compatible contains convert converting created data decrypting decryption depend depends des des3 des3cbcdecrypt des3cbcencrypt des3ecbdecrypt des3ecbencrypt des3state des56to64 des64to56 des_key_setup descbcdecrypt descbcencrypt desecbdecrypt desecbencrypt desstate digital directly dsa ecb ede eight electronic elgamal encoded encrypt encrypted encrypting encryption ende ensure equivalent except expanded_key flag format formats forth foundation frontier hence include indicating initialization int ivec key key_setup keys larger len libc.h libsec libsec.h mode modes mp mp.h o'reilly parity plan pointer prime rand rarely rc4 realistically rest routines rsa schedule sechash secure setupdes3state setupdesstate shared short source src standard stream structure substitution successful symmetric sys takes text track triple triple_block_cipher u.h uchar ulong using vector void we've works des 2/des + abbreviate aes aesdlen algorithms anyone bits blowfish bounded buf buffer buffers chain char check constants copy cryptographically data define des differ differently difficult digest digests digeststate dlen drowssap ds elgamal fd final hash hashed hashes hmac hmac_aes hmac_md5 hmac_sha1 hmac_sha2_ hmac_sha2_224 hmac_sha2_256 hmac_sha2_384 hmac_sha2_512 hmac_x include int integrity intended internally key keyed klen len length lengths lib libc.h libsec libsec.h list malloc marshal md4 md4dlen md5 md5dlen md5pickle md5state md5unpickle mp.h newly nil non object obvious ones output parameter password pickled pointer possessing predict produced rc4 read rehashing require resulting return returns rfc rfc2104 routine routines rsa sechash secret secure security sha sha1 sha1dlen sha1pickle sha1state sha1unpickle sha2_ sha2_224 sha2_224dlen sha2_256 sha2_256dlen sha2_384 sha2_384dlen sha2_512 sha2_512dlen size slightly source specification src support sys therefore transmission u.h uchar ulong underscore unmarshal usage using wd xlen ym sechash 2/sechash + abbreviated abbreviations accept accepts access addition additional assumed attribute attributes audio audiostat bass bind bit blaster buffered bufsize byte bytes calculate cd complement connected connection control controller controls converter converters data decrease default defaults degenerates depend dev devaudio.c device devices directory dma duplex endian ess1688 existent expressed file format greater hz i.e implementations increase input integer internal khz latency length level lines loud mcd mic microphone midi minimum monaural non offset operations output particular playback played player port ports possibly provides quiet ranging rate reached read reads record recorded reporting represents reset return returned returns sample samples sampling serves shared shown size sound soundblaster source sources speaker speed src stat stereo string support synth synthesizer sys time timing tone treb treble two's usb using valid value values volume writes writing written audio 3/audio + abbreviated abcefmnrw affected agreement algorithm applying ascertain backward basename behavior blanks bring bugs circumstances cmd cmp comm comparator compare compared consisting contains context contexts convert creating debate diagnostics diff difference differences differential differing directories directory displays distinguish easier ed editing editor entire equal equally error except exchanging exit file file1 file2 files finds flag flagged former forms identical idiff includes input inserts letters lines listing merging method mixed mode n1,n2 n3,n4 naive names notion opposite option oriented output overlap pairs pertain post prefixes prints process processing processor produced produces range rare reading recreate recursively removed resemble running script scripts similar similarly smallest source space spaces src status stream string strings subdirectories sufficient sys tabs tells text tmp trouble verbs diff 1/diff + abbreviated absolute access accessed accessing address addressable adjustment adjustments advance affect affects algorithm allocated allocates alter altered ansi arbitrarily arbitrary architecture archive ascii attributes auth.h automatically base basic belongs bidirectional bind bio.h bit bits block bring broken bss buffered calling capable cases channel channels char character characters chdir chicanery child collected collection commonly communicating communication completes comprise concatenations confound confused connected consist contains continues control convenient convention conventions copies coroutine create created creates current data dates declarations declares define defined defines definitions deleted dependent depends describes describing descriptor descriptors design desired details dev device's diagnostics dir directly directories directory directs dirfstat dirfwstat dirstat dirwstat divided dot draw draw.h dup dynamically employ emptive enable entries entry error errors errstr etc evaluated evaluation events except exception exec execute executing execution existing exits faults fcall.h fd2path file files filled flags floating fork frame.h friends fstat fwstat getfcr getwd graphics handler header hierarchical hierarchy id identical identifies implementation include includes independent independently indexed indicating indices initialized input instruction integer integers integral interface intro introduction ioproc jmp_buf kernel latin layout ldraw leading level lexical lib libbio libc libc.h libdraw.a libraries library libstdio limit listed listing loader lock locks longjmp lowest mach.h machine macros main maintained maintains malloc math mechanism memory messages method mount mouse multi multiprocess multithreading names namespace nan ndb.h necessary needs nm notably notification notify ns objtype occur occurred occurs offset opened operating ordinary organization output outside ownership pages pair parent particular passing path paths permissible permission permits pick pipe plan plus pointer points possibility practice pragma pre prefixing prerequisite presents preserved print printable prints proc process process's processes programs proper properly properties protect provides purposes rarely reachable reached read reassigned record records recovers regexp.h register regular related removals remove renamings repeat replace report reported representable representation request resident retrieved return rfmem rfork rfproc root route routines rune running schar scheduled scheduling searched section seek segattach segment segments selecting send sequential sequentially serve setjmp shared sharing shouldn't signed similar slash slashes sleep source space spaces specific stack standard starts stat status stdarg.h stdio.h step stored string stripped strlen structure structures subroutines support switching synchronization synchronize table telling terminate terminates text therefore thread thread.h threads time translated translation translations tree type types u.h u16int u32int u64int u8int uchar uint uintptr ulong unaware undefined understood unexpectedly unicode union unique unsigned unused user ushort using uvlong va_arg valid value values variadic various via visible vlong wait whenever width widths working works write writing written wstat yield 0intro 2/0intro + abbreviates add add3 add4 affine alpha amongst arith3 arithmetic assume assumption can't closept3 closest component compute convert converting coordinates cross cross3 cryptic dealing dist3 distance div3 divide division dot dot3 double draw.h duality eps eqpt3 equality euclidean exact extra fff2p3 geometry.h homogeneous identically ignoring include indicate int interpolation intersection joining len3 length lerp3 libgeometry linear matrix midpoint midpt3 mul3 multiply names nearseg3 neg3 negate operate operations ordinary origin p.w p.x p.y p.z parallel passing pdiv4 perpendicular perspective plane planes pldist3 pn2f3 point3 points ppp2f3 pq product projective q.w q.x q.y q.z reflect3 reflection remainder reminds representations results returns roundoff routines scalar segment smaller source space src struct sub3 sub4 subtract sys takes test testp type typedef unit unit3 units various vdiv3 vector vectors vrem3 we're whenever x,y,z arith3 2/arith3 + abbreviation airport bell bin conditions defaults designating ewr exclusive forecast hill identifier identifiers insensitive labs letter location murray mutually near neither newark nj print prints rc recently report reported seven source st table weather weather 1/weather + abbreviations acceleration accurate add astronomical atm au avogadro's belgiumfranc brgallon britainpound british bugs catenation centigrade charge circumference cm cmd combination complete compound constants conversion conversions convert converts counterparts currency database denoted diameter differ divide ds e.g electron entire equivalents etc exotica exponentiation expressed fahrenheit familiar fashion file files flag floating generous gravity grouping height inch interactively in² kelvin leavening lib lightyear list mass metric mole multiplicative multiply names nature operators pi pound pounds precedence prefixed prefixes pressure print quantities quantity rankine ratio recognized run scale scales someone source specifies speed src standard subtract sys time unit units units.y updated various works units 1/units + abc abcc addns attach auth bind blank built cd character clear construct describe dir directory environment escapes everything execute expanded file files host import init lines machine missing mount mounted mountpoint namespace newns non note operation operations options path performed quotes recognized remotepath rfcnameg rfork scratch servename server space spaces spec specifies string subroutines tabs typically unmount utf variables working namespace 6/namespace + abcc arch archfile archfs archfs.c archive bind cmd control default file flag flags format mkfs mnt mount mounts mtpt presenting produced source src style sys archfs 4/archfs + abccdds abcefmnrw acme adiff adm archived behavior bin binary bind bugs compare copy correctly current date day's daysago dd default diff differ diffy digits dump dumps existing file files format frequently fs guarantee hard hhmm implementation it's lib libc libc.a library loaded march mips mk mmdd morning names occur option options path port presented print prints prior rc recent represents rm run runs select selected selects singing snapshot snapshots source src string sys temporarily today's tree users v.out vc version yesterday yesterday's yymmdd yyyy yyyymmdd yesterday 1/yesterday + abcdef address adjustment aggregate alternate applied applies arg args array asterisk base behavior bio blank bugs bytes calling cast char character characters code consecutive contains control conversion conversions convert converted converting copied dd ddd decimal default defined depends described digit digits double ell ensure equal error except excess exhausted expanded explicit explicitly exponent fetching fewer file flag flags follow fopen format formatted fprintf fractional friends fscanf function's greater hexadecimal implementation implies include increases indicated indicates indication infinite int integer integral introduced introducing invalid justified leading letters libstdio list maximum meanings minimum missing modify negative non nonexistent notation null objects octal omitted optional output pad padded padding performed places plain plan pointer points portion positive precision prefixed print printed printf printing produces promoted promotions reached remain removed responsibility resulting results returns routines rune short sign signed significant simply snprintf source space spaces specification specifications specifier specifies specifying sprintf src standard stdio.h stdout storage stream string style supplies sys takes transmitted truncation type types u.h undefined union unsigned user's using va_list value vfprintf void vprintf vsnprintf vsprintf wide wider width writes written wrong yields fprintf 2/fprintf + abcemnw adjacent adm backwards bootesdump check ches cmd continue current dabcemnw date dates debugging described diff disallowed dump dumpfilesystem edt enables exist exists file files finally forces fs functionality fuv gmt history.c intermittently logged looking main modifier names option options output pair path presented print printed printout prints produces recent replaced run search selects sizes source src stored sys time times tmp tree user users usr ut verbose versions yesterday yyyymmdd history 1/history + abilities access accesses accessible allow ampl announces application applied assumed auth authority auxiliaries bin binary browser bytes cern cert certchain certificate certificates chain checks client clients cm cmd connection connections considered contains content control converts cs current data default defaults delimited denied described describing details determined dev directory doesn't domain domain.com encoding endeavor ends entries error etc exact except exceptions executed executes exist existing exists explicit explicitly expression expressions factotum fields file files finish fly format generate handles headers hget holding host html http httpd httpd's httpd.h httpd.rewrite httplogin https i.e idioms image imagemap implies inbuf includes incoming index.html index.html.z inferno.bell informing internally ip key kick labs.com lapack lawns lib libhttpd.a library list listable listed listen listens listing listings literal locked longest looking looks ls magic man2html manual manuals map mappings match matched matches matching method methods mimetype namespace namespace.httpd ncsa neither netdir netlib netlib.org network newline newns nor note null occurs octet omits opening option original output overrides page pages pair pairs parsing parts password path pathnames pattern permanent permits persistent portion possibly post prefix prefixed presented prevent private processes processing produces programs protocol query quotes read received record redirect redirection references regular remaining remoteip replacement replacements request requested rescanning rest returned returns rewritten rob root routines rsa save saved search searched send sent seq server serves servicing signed similarly site sites slash source space spaces specific specify src srvaddr stream string style submissions subordinate subtree succeed suffixes support supported supports sys table tabs tcp temporary time tokens treating try type unless unlistable unmatched unreadable uri url urls user using usr valid version virtual web webls webls.allowed webls.denied webroot wins writes www.ampl.com www.vitanuova.com www.your httpd 8/httpd + ability abnormal absent access active acts addition additional address addresses agrees allows alphanumerics answer applied apply arbitrarily asks assumed attribute autoindent automatically backslash backslashes backward backwards becomes begun behaves behavior bin bit blank block border boundaries brace braces bracketed buffer buffers button catenated catenation cd character characters class clean click clicking cmd communication complete composed compound computed conditionals contains continuing controls copies copy create created creates current cursors cut cycle dark debugging deeply default defaults defining delete deleted deleting deletion delimited delimiter delimiters demarcated dev digit direction directory disjoint display distinguishable dot double download downloaded ed edit edited editing editor editor's elided elisions enabled enclosing entered entering entry equivalent error esc escape etc evaluated examined except exception exchange executable executed existing explicit expressed expression expressions extended extends external file file's filename files finds formally format forms forward forwards full further generated gets grep grouped grouping hangup highlighted hit host i.e identifies idioms independent indicate indicated indicates indicating ineffective input insert insertion insertions inserts instance interface invocation invoking key language leading leftmost level lib lies lines list listed listens literal literally load locally locates longest looking loops low machine malformed manipulating mark match matched matches meaningful mechanism member menu message miscellany missing mode modified modifies mouse move multi names necessarily necessary negative nested newline newlines nnnn non none null occur occurrence omitted opening operating operation operations operators option optional options ordinary original output paragraph parenthesis passive paste path pattern pike pipe plan plumb plumbing pointing port potentially precedence preceding prefixed print printable printed prompt prompted provides quit quote quoted quotes range raster rc re read recent recently rectangle redoes refers regexp region regular remote remotely replace replaces represent representing represents required resize resulting reverse reversed rio rmachine rob run running sam sam.err sam.save samsave samterm save saved saves screen search searching sed selected selecting selection selections selects semantically send sent separates sequentially setting shell simultaneous simultaneously skips slashes snarf sole source space src srv standard stands starts stderr stdout straddle string strings structural sub subexpression substitute substituted substring substrings succeed successive sweeping sys takes terminal terminates termination text th thereby time tmp type typed unaffected unassigned unchanged undo undoing unique unless unnecessarily unpack unread updated user using usual value visible whatever whereupon whichever window windows working write writing written zerox sam 1/sam + ability access accesses actually advisable affect allocation allows appended authentication authsrv average backspace belongs binary bind bintime bit bits blank blanks block boot bootfile buffer buffered bugs build byte bytes care character characters clock clocks closed closing complete config configuration configured cons consctl console contains context control controls copy counts cpus cputime current data debugger debugging decayed decimal delete delta descendants descriptor dev devcons.c device devices digit directory display domain draw drivers e.g ec echoed elapsed enable encoding endian ends epoch erase erases erasing etc except exited expression fails faster faults file files fits fixed format formats formatted freq frequency generate generated generators graphics greater holds host hostdomain hostowner hundred idle ids image include incrementing indicates inefficient infinite input integers interface interpreting interrupt interrupts kernel kernel's kernelpath keyboard kill killing kills kilobytes kmesg kprint kremvax largest leading leaves length letter level listing load loads loops low machine machine's malloc malloced manage memory message messages milli milliseconds miscellaneous mode mostly multiprocessor nanoseconds newline non null numeric offset opened operating ordinary osversion output owner owns padded page pages pagesize parameters parent's percentage permissions pgrpid pid port ppid preserving print printed prints priority process processes processing processor processors produce produces producing protocol provides pseudo purges putting q.v queue random rate raw rawoff rawon read reading reads real reboot rebooted receive reentered remainder remains removes representation representing reread reset resets rest restart restarts retrieving return returns rio run runes sampled screen seconds seed seek sent serial served serves servicing shutdown six size soon source space specially spent src stack started starts statements statistics stream string strings sufficiently swap swapping switches sys sysname sysstat system's t's td terminals text textual therefore throws tick ticks time tk tlb toggles total totaling tp tq tr translated trim ts tx typed typing units unlike usage user utf valued variable version via wait write writes writing written cons 3/cons + ability access accesses add additional address afv aid allow amount appending applications apply arena arenas arenasize assumption attempt attempts backwards balance basic bd becomes block blockcachesize blocks blocksize bloom bootstrap branded bucket bucketsize bugs build buildindex bytes caching cds checkarenas checkindex checking cmd collection combined compatibility composed compressed compute computes conditions conf configfile configuration contained contains copies copy create created current data debugging default depends described detects determined determines discussion disk disks dumb duplicate easier eliminates enable entire entries error errors exact examined examines exist existing expected external failure feature file files filter fingerprint fix fixed flag fmt fmtarenas fmtbloom fmtindex fmtisect formats formatted formatting generated gigabytes hash header hi imemsize implementation increase index indexed indicate individually initializes input invoked invoking isect kilobytes linear lo location maintain maintenance map mapping mappings media megabytes memory merge mode names nblock nblocks nhash non none notation note omitted operations option optionally options output overflow overview partition partitions passes percentage perform plan populates prepare previously prints property provide range rarely raw read reading reads rebuild rebuilding rebuilt recordable recorded reduces reinitialise repeated replaced requested requires restore rounded run running scan section sections selected sequential server servers setup sha1 size sizes sort source sp space specify src srv standard store stored stores structure structures suffices sufficiently suffixes syncindex sys systems tapes temporary time tmp total typically unique units usable using usual values various venti venti.conf verbosity version workspace write zeroed venti-fmt 8/venti-fmt + ability access addition affect algorithm allow allows append asks atomic attempt behavior bind bit bits breaking bytes calling check checked client clunked create created creation described determines dir dir.perm directories directory discovered dmdir doesn't draw entry error exclusive execute existing exists fail failed fails fid file files finally further generate generates granted guaranteed id illegal implied iounit issues issuing kernel libc.h maximum mean message messages mode names newly oexcl oexec opened opens orclose ordwr oread otrunc owner owrite perm permission permissions points prepare process product programs qid race rcreate read regular rejected remove removed reply represent request requires return returned ropen send sent server setting size stat succeeds successful tag tcreate time topen transfer truncate truncated truncation try type union user value walk write written open 5/open + ability access additional adds adobe aladdin allow alternate alternatives anywhere applications apply arg1 array automatically basic benefit bind bugs built bypass caching character cmd colon compressed current d.xyz dbatch ddeviceheight ddevicewidth ddevicexresolution ddeviceyresolution ddiskfonts debugging def default define defined definition definitions deletefile described designated desirable device devices dictionaries directly directories directory directs disables disk dname dnobind dnocache dnodisplay dnopause doc document doesn't doing dquiet driving dsafer dwritesystemdict e.g enabling environment environments equivalent etc exactly executes executing exit exits expense fd file filename files finishes font font2c fonts foo foo1.xyz foo2.xyz format forth fprintf fragment further ghostscript goes gs gs_ gs_device gs_init.ps gs_lib height highest image include initialization input interpreter invocation invoke language languages leaves lib library list listing loaded loading loads looking looks lowest lp manual messages mode names necessary non note null number1 number2 opened opens operator operators option options outlines output page parameters path pause pcharstr pdf pipe pipeline plan9 postscript precede precedence printers printf processed produces programming programs prompt protection ps ps2pdf quiet quit quit.ps ram read reads receive recognizes related remaining renamefile rendering represents requires resolutions run running scratch sdevice search selectdevice selected selects send sensitive sent separately series setting shell similar slash slower sname source soutputfile space specification specifying spoolers src standard startup string strings subdirectories suitable superseded support suppress suppresses switch switches syntactic sys systemdict systems thereafter time token treatment userdict usual utilities utility value values variable viewing whereas width windows writable writing xyz gs 1/gs + abirprvvw abort absence adobe's arrow backspace basename bit bitmap bottom boundaries bounding box browse bugs button channel claim cleanly clockwise clumsy cmd code color comments common compressed computable conform conforming contains control conventions conversion convert converted correctly create created current cursor debugging default degrees described destructive determining device diagnostics display displayed displays document documents draw ellipsis enables enter entire errors exactly exit exits expanded extra facilitate fax faxes file file's filename files fit fits fly format formats graphic graphics grow gs guess height holding icons image images inch independent inferno input interface jpg keyboard leaves library listen listens load lost manual menu messages minus mistransmitted modifications mouse multipage necessary needed newly non nor ones operations option orig original output page pagenum pages pan panning particular pdf permits pixels plan plumber plumbing postscript ppi pressing prev preview processing programs prompts proportionally purpose raises raster read reading reads rectangle references removes resize resizes resolution respect restores reverse reverses rotate rotates rounding runs screen selected selecting sent simply size skeptical slightly slower soon source space specific src standard started structuring supports sweep sys tex tiger.eps time toggles transformations troff trouble try turns type typesetter typing unchanged unfortunately unsatisfactory upside user usr valid variety various version via view viewed viewer viewing window working write writes writing zerox zoom page 1/page + able access acme actual add addition address addresses allow announce announces appeared append author base bell black c2.com canonical capital cgi character client cmd coexist comes compare conflicting contains conversation current data date decimal default described descriptor diff.html differences dir directories directory discussion distribution dm domain due easy edit edit.html edited editing entry epoch error except existed expects explicitly facilitates fail fails fields file files final finally flag format formatting forms generated grey guide helper hidden hist historical history.html history.txt holds html http httpd inbuf includes index.html index.txt instances interface ip l.map labs length letter level lib lines links listing listings lock looks map mapping mark message metadata method mnt mode mount mounted mounting mounts mtpt names namespace.httpd netdir network none notice noting obtain occurred oldpage.html oldpage.txt option options original page page's page.html page.txt pages peacefully perm permission plan plan9 post posted prefixed presented presents process provides raw read reading reads rejected remoteip representing request requests response rest return returned returns revised run running sample saved search seconds served server services showing similar slashes someone source space spaces specifies specifying src srv stamp stamps standard started stored subdirectories submission submitted succeeds sys takes tcp templates text textual time title titles transcript type types typically underscores unique update updated uri urls user users usr usual version versions via viewed wants web webroot werror.html wiki wiki.plan9 wiki?wikiwikiweb wikifs wikipost wikipost.c writable write writes writing written wikifs 4/wikifs + able accessed accesses active add address adl adm administration allow allowoff anyone append atime atimes attach authenticated authentication authsrv bad behavior bin block blocks booting cache casual cdfppqrtw cfs chaperone chat check checked checking clear clri cmd connections console convenience correct couple create creates data default delete described dial directories directory dirty disable disallow disk duplicate duplicated edit encouraged entire errors except exclusive executes exist exists facilitate feature file filenames files filsys fix fs full halt impossible initialize intended kfs kfscmd kfscmd.c ksync laptops level list listen listener listening looks machines main memory messages mkfs mode names needed needs network networks newuser noauth non none noneattach note nowritegroup nvram objtype octal opposite option options owner path performance permission plan possibly prep prevents print processes production quiet quoted rc re read readable reading readnvram rebuild reduce redundant references remove rename report reread rereads resolve restart retrieved sd serve server servers simplify simulated situation someone source src standard statistics stats stop strongly summary suppress sync sys tags tcp terminal time toggle toggles touched tracing transmits turns updated updates user users utf write kfscmd 8/kfscmd + able actions adds analysis analyzer asteroid blanks bugs cmd code compile compilers converts copies default dinosaur edition executed executes expression expressions file files generated generates generator handle input kill lesk lex lex.yy.c lexical lib lines lower manual meanings native ncform opposite options orbit output portions print programmer's programs putchar recognized regular removes replaces research run schmidt searched sed source src standard statistics summary sys template tenth text tvn9 unix unrecognized upper utf volume written yacc yytext lex 1/lex + able add amount apply background bit black blue border bugs chandesc channel cmd color combined compressed compression constant convert converted converting coordinate coordinates crop crop.c cropped crops cut default depths described descriptor diffusion dithering draw dx dy edge edges error exact extra file fill floyd format frame generate geometry green grey iconv image image's imagefile input insets larger mapped maximal maxx maxy minx miny monochrome negative option options original outer output outside picture pink pixel pixels processing reads rectangle rectangular red remove resulting run scale similar source space specifies specify src standard steinberg step strip sys takes ten translated triplet turns tx ty unchanged value ways writes crop 1/crop + able adjustments algs alternate args auth authaddr authentication binaries bugs cmd connect connections cpu cpuaddr default defaults delicate devices diagnostics difference downloaded drawterm edit encryption establish executed explicitly freebsd graphical hash http illusion improved irix keyboard keypattern lib linux mnt mounts mouse netbsd nice non operating options plan ported prints profile programs provide real recompiling remote remotely resident rio run screen secstore secstoreaddr seem server servers serves shell source space specify src starts swtch.com sys systems term terminal typically unix user users using usr via window windows drawterm 8/drawterm + able algorithms arithmetic automatic avoid binary bit blocks bodies brace braces bugs clear code coding comment commenting comments compact compare comparison confusing constants conventions converting data declaration define deviates diverge don't due e.g edit editing efficiency enum error errors errstr etc excuse expanded explain explaining explicitly expressions file fits fix follow formed goal goto guidelines habits heavily http idioms initialize initialized inside integer involving it's keyword keywords lines low lowercase matching measured memcmp memory names nor notably notes opening operator operators optimize parenthesize particular parts pascal pike pikestyle.pdf plan positive precedence programmers programming programs rc readable reader relational return rewrite rob rules seconds shouldn't slow sometimes space spaces standard strcmp string struct structures style styles success surround tabs tags touch try tunings typedef ultimately underscores understand unless uppercase using valued variable variables we're welcome what's wise wondering worked write writing www.literateprogramming.com you've yourself style 6/style + abnormally answer array automatically bugs char characters closed copied created creates defined executed existing exits fclose file files fopen generates include l_tmpnam libstdio mode names non opened overwritten particular pointer removed return returns source src stdio stdio.h string sys template temporary terminates tf000000000000 tmp tmpfile tmpnam tn000000000000 u.h update valid value void tmpfile 2/tmpfile + abort access archival automatically block blocks buffers cache canonical chains client clients conn connections convert copy data describe describes detail disk error extend fcall file include libc.h library libventi log logging malloc manipulate manipulating manual mem memory messages network packet pages protocol provides representation representations routines server servers source src storage structures support sys trees truncate u.h venti venti.h wrappers writing venti 2/venti + abort accessed actually allows ambiguity attach attaching attempts authentication author authors auto bugs build cannonical changelog checked con contains cpu creates cvs cvsfs cvsroot cycle data date ddabv debug default delay demand designed directories directory disconnect display documented dump e.g endeavour error ext extra factotum fatal february file file's files filesystem filled flushed generated gserver gssapi handled host indexed kerberos key keyp keyparam knowledge level liable listed locker machine metadata method methods mins mntpnt module mount none onto option options owner parameters parsing path posix presented protocol pserver publish published read readable read→idle→reread reconnect refuses relies rembembers remote remove repository request resend rlog root rx sent server servers signal similar sourceforge srv srvname ssh startup stats stored string support supported tag tested tree unlocked unnecessarily user username v1.11.1p1 venti ver version versions view viewer views cvsfs 4/cvsfs + abort accessible adding append arena arena0 arenas ask assumed assumes backed backup blu bugs build buildindex burn burner cdfs checkarenas confirmation copies correct current data debris default dev device disc discs dump dumparenas except extract file files fmt fmtarenas fmtbloom fmtindex fmtisect formatted fossil fs goes header index internally invoked keeping lib loading locally log match motions mounted names necessarily necessary optical option partition print printing prints proceed processing programs prompt provide ray rdarena re records reside restore restored restoring run saved scores scripts sdc0 sdd0 sde0 sealed server's set1 size skip slot source steps storage store subdirectory summary supported sys thereafter time tobackup track tracks typing usual venti via wish written backup 8/backup + abort accumulated actually adding addition allocated allocation ansi append associates attached attempted attempts automatically binary bio buf buffer buffered buffering bufsiz bugs char character characters clearerr closes closing compatibility computed constant consume corrupt create creates current data deal declared default defined delay delivering described descriptive descriptor designate designates device diagnostics distinction earlier empties eof error errors errstr except exception exec exits extensions external failed fails faster fclose fd fdopen feof ferror fflush fgetc fgetpos file filename fileno files fill filling flushed flushes flushing fopen fprintf frees freopen fscanf fseek fsetpos ftell full fully further host identify ignores implement implementation include indicate indicator initialized input int integer interactive iofbf iolbf ionbf length libstdio maintained malloc measured memory method mode necessary newline non null object obtains occurs offers offset older opened opens operations output package pages plan pointed pointer pointers pointing pos prevent process read reading receipt related returned returns reuses rewind runes says sclose seek_cur seek_end seek_set seeking setbuf setvbuf simpler size smaller somewhere sopenr sopenw source src standard starts stderr stdin stdio stdio.h stdout stores stream streams string strings success support supports sys takes text tmpfile transactions trouble truncate type u.h unbuffered uniformly unintelligible unless unwritten update using utf value valued values void whence write writing written fopen 2/fopen + abort acid active address align aligned alignment allocated allocates allocating allocation allocator arena array behaves beyond bizarre block blocks boundary bounds brk bugs byte bytes calloc clr combine common contraints convention corrupt corruption custom data detect diagnostics directly elsize encompass equal errors errstr examined except execution extra fields flags freed freeing frees further gaffes getcallerpc getmalloctag getrealloctag grows include inconsistencies initialized int leak legal lesser libc libc.h library likely mainmem maintains malloc malloc.c mallocalign malloctopoolblock mallocz meanings memory modulo moved msize nelem newly non null object obtain obtained offset op package passing pc pointed pointer pointers pool pool.h pool_noreuse poolcheck port possibly previously properly provide ptr realloc reallocate reallocated respecting return returned returns routines scan setmalloctag setrealloctag setting size sized sizes sometimes source space span specification src storage storing suitably sys tag tags takes traces trump type u.h ulong unchanged undefined unused user valid value void wrapper writes written zeroed malloc 2/malloc + abort allocated answer answered arriving canceled client completed conditions considered correctly created depends discard doing echoing es exceptional fid file flush flushed flushes flushing handled honor identified implies instance interrupts invalid longer message messages needed oldtag ones particular pending process purge read receive received recognizes request rerror respond responded responding response reusing rflush semantics send sending sends sent server signify size specification tag tcreate tflush therefore transaction twalk user wait flush 5/flush + abort ansi arrays assembly behave bounded bugs byte bytes bytewise check comes compares comparison copied copies copy count dependent destination efficiently equal except greater guaranteed handed handle identically implementations include int integer language lexicographically libc libc.h looking machine memccpy memchr memcmp memcpy memmove memory memset negative objtype occur occurrence operate operations overflow overlap overlapping plan pointer port portable receiving require returns routines source src stopping strcat sys u.h ulong unsigned value void whichever works memory 2/memory + abort arg arg1 arg2 argbegin argc argend argf args argv argv0 assume badflag bffile1 break cases char character characters code conventionally copy current default doesn't eargf exec executed exits extern file1 file2 getflags include int integer letters libc.h list macro macros main names nil option options output pointer points print process processing prog remaining requires rest returning returns rune running runs scope source string surround switch sys typical u.h usage value void arg 2/arg + abort assert assert.c char check cond define false include invariants libc libc.h macro message port preprocessor prints source src sys u.h via void assert 2/assert + aborted aborts access accessed acts additional advisory afid agent allow allows aname append aqid arbitrary archives arrange arrives attach attached attempts attributes auth authentication based besides bidirectional bind bit bits brackets byte bytes cases character characters choose chosen client clients clunk combined communication complete components confusingly connection consists constant constants consulted contains convention convert convey copied count counts create created current data defined delay deleted deletes demand dependent described describes describing descriptions descriptors device directly directories directory dmappend dmauth dmdir dmexcl dmtmp dot driver eight ename encoded endian entry enumeration error established establishing etc events everyone examined except exception exchange exchanging excluded exclusive execute executing existing explicit explicitly external failed failure fcall fcall.h fid fids fields file file's files final fit flush forming generate gets grant greater group's groups handle hence hexadecimal hierarchical hierarchy historical hold id identification identifications identified identifies identify identifying illegal implicit include included includes incremented independence indicates indicating initializes inside integer integers interim intro introduction iounit items kept kernel keyboard larger latter leader legal length lengths library literal longer low machine maintains managing manipulated matching maximum media member message messages mnt mode modification modified modify mount msize names navigate navigates necessary needed negotiable negotiated newfid nightly notag notation nul nwname nwqid offset oldtag ones opened operating operation original outside outstanding override owner parameter parameters parent particular path perm permanent permission permissions permit plain plan pointing possibility prepared presented printable privileges proc process processes programs properties protocol prototypical proven provides providing qid qids qtappend qtauth qtdir qtexcl qtfile qttmp rattach rauth rclunk rcreate read reading reads reasons receives receiving recreated reduce refer refers regarded remaining remove replied replies reply represents reproduced request requested requests rerror respond responds response responses restricted restriction resulting retrieves returns reused rflush root ropen routines rread rremove rstat rversion rwalk rwrite rwstat says send served server server's servers session share sharing shorthand significant situation size sizes skipped skipping slash slashes someone sometimes somewhat space specify specifying stat stored stores string strings structure structures subdirectories subsequently supply support syntactic synthesize synthesizes systems tag tags tattach tauth tclunk tcreate text textual tflush therefore thirteen time times topen transaction translated transmits transmitted transmitting transported tread tree trees tremove truncated truncating tstat tversion twalk twrite twstat type typically uname unicode unique unless unlikely unsigned user users ushort using utf valid value variable version wait waiting walk walks wname wqid write writes writing wstat 0intro 5/0intro + aborted access acid actions address alef allocated allocates alt alts analogues arbitrary arg argc args argv array atnotify aware behave block blocked blocking blocks buffer buffered calling cases chanclose chanclosing chancreate chanend chanfree chaninit channel channels channoblk channop chanop chanprint chanrcv chansnd char choose chosen closed closing communicating communication completed contains continue control cooperatively coroutines cpid create created creates creation current data debugging declare default delayed delivered depends describes descriptions descriptors desired die directed discarded distinguish e.g eight elsize entire entries entry entryno enum environment err error errors eventually example.c exec exec'ed execl executed executes executing execution exist exit exits explicitly external fail failed failure fashion fields file files finishes fixed flags fmt fn fork formats freed freeing frees full further global holding id identical identified identifying ids include index inherits initialized initializes inside int integer internally interrupted interrupts intro invoke invoked ioproc item kills kilobytes languages lib libc.h library libthread list listed lock longer main mainstacksize malloc manage management manner marks memory mentioned messages mnt modified mount names namespace nbrecv nbrecvp nbrecvul nbsend nbsendp nbsendul nel newly newsqueak non note notes notify null occupy occur occurs op operating operation operations parallel pass perror pid pipes plan plus pointed pointer pointers points potential preempt preemptively prevents primarily print proc proccreate procdata proceed process processes processor procexec procexecl procrfork procs programming programs provides qlock qlocks queue random read receipt receive received receiver receives recv recvp recvul related relinquish relinquishes rendez rendezvous replace resources response return returned returning returns reused rfcenvg rfcfdg rfenvg rffdg rfmem rfnameg rfnoteg rfnowait rfork rforkflag rfproc rfrend rlock robin round rsleep run running safe safely scheduled scheduling selected send sender sending sendp sends sendul sent shared similar similarly size source sp space src stack stacks stacksize started stating status storage stores string struct structure structures success support synchronize synchronizing sys sysfatal tag temp terminate terminates therefore thread thread's thread.h threadcreate threaddata threaded threadexits threadexitsall threadgetgrp threadgetname threadgrp threadid threadint threadintgrp threadkill threadkillgrp threadmain threadnotify threadpid threads threadsetgrp threadsetname threadwaitchan typedef u.h uint ulong unblocks unbuffered unique unsigned using valid value variable variables varying versa via vice void vous wait waitmsg ways wlock yield thread 2/thread + aborted active automatically bytes characters client client's clunked communication connection contains count data defined defines digits earlier entry enveloping equal excludes expect extending fauth fids freed further fversion generate generated honor identifies identifying includes initializes issue length level limit maximum message messages mount msize negotiate negotiates nnnn notag outstanding points protocol protocols receive received reply request requests required rerror respond responds response rversion sent server server's session sides size string strings stripping substring successful suffix suggests tag thenceforth transport tversion understand uninitialized unknown ushort value version version 5/version + aborts access additional addr address allocated allocates appropriately background block block's blocks blocksize byte bytes cache cache's candidates client clients commonly conn connection constant consulting convenient copies count data default dtype endian eventually eviction evicts extra file filled frees full global hash immutable include increments index indicates install int internal invokes leaked leave libc.h library libventi longer match maximum memory modifying mutable nblocks necessary needed nilblock occasionally opposite perform pointer preparation prints processing provide recorded refer reference references release released releases replacement represents required retrieves returned returns run score scores server setting sha1 size source src stored stores struct sys turns type typedef u.h u32int uchar uint ulong user using variables venti venti.h via visible void vtblock vtblockcopy vtblockdirty vtblockduplock vtblockput vtblockwrite vtcache vtcachealloc vtcacheallocblock vtcacheblocksize vtcachefree vtcacheglobal vtcachelocal vtcachesetwrite vtconn vtglobaltolocal vtlocaltoglobal vtscoresize vtsetcachewrite vtwrite write writes written venti-cache 2/venti-cache + aborts bin choice cpu delete deleted deletes delkey disables factotum files key keys listing matching mnt option pattern prompt prompting rc response run server server's shows skips source stored term terminal's typing user delkey 1/delkey + abound accuracy aes algorithm algorithms alpha bit blowfish checks computation confirm count des divides divisibility divisible dsa dsaprimes elgamal factor generate generates generation generator genprime gensafegprime gensafeprime genstrongprime include int integers key libc.h libsec libsec.h miller mod mp.h mpint multiplicative nist non nrep patient primality prime primes probability probably_prime properties rabin random recommended repetition returned returns routines rsa seed sha1dlen skeptics slow smallprimetest source src sys test therefore u.h uchar using void prime 2/prime + abs abs.c absolute diagnostics fabs floor include int integer labs libc libc.h negative port return returns source src sys u.h unrepresentable value values abs 2/abs + abs absolute ceil ceiling double fabs floor fmod frexp greater include integer iy largest libc libc.h port remainder returns sign smallest source src sys u.h value floor 2/floor + abs acos allows appeared arithmetic asin assignments atan backslash basic bc braces bugs built cmd consists constants contains control cos cosh dc decreasing definitions deg degrees ends environment eof equivalent error evaluated exp explicitly exponentiation expression expressions file files floating flow formed func gamma gcd grouping hall hello hoc imperfect include input int interactive interprets introduced kernighan language level list listed log log10 names newline operators option output phi pi pike precedence predefined prentice print printed prints proc procedure procedures produce programming radian read reads recovery results return returns sin sinh source space sqrt src standard statement statements string syntax sys tan tanh temp typically unix unless usual value variable variables hoc 1/hoc + abscissa abscissas actually applies automatic automatically axes axis bcgkmrwy blanks bounds break bugs character characters choosing cmd colors connected connecting curves cycle default determined devices disconnect disconnected display distinguishable draw dropped encoded equal exceeds filters fraction frame full grap graph graphics grid height horizontal input integers label labels legend letter limit limits lines log logarithmic lower mode move newlines nonnumeric option optional options ordinate ordinates output overlay page pairs pen plot plotting points printed quantities quotes ranges recognized reversed rotates run save scale scales scaling screen segments similarly source space spacing src standard straight string style styles successive superposed supply surrounded sys takes third ticks title transpose unless upper value values vertical width windowed graph 1/graph + abscissae add addition additive adjust aid arrow automatic automatically base bentley blank blanks bot bottom bottommost bullet capitalized category character characters circle cmd comment computation conditionals contains continue coord coordinate coords copied copy cos current dash dashed data debugging default define defined defines definitions discarded disconnect dot dotted draw drawing e.g edition error etc evaluate everything exist exists exp explicitly expr expression file files formatting frame generated grap grap.defines graph graphs grid grids happy ht inches include included independently input instructions int invis irrelevant iterator iterators justified kernighan label labels language leading leave lib linedesc list ljust log loops macro macros mandatory manual maps margin marks max min mode modify mostly multiplicative newlines non omitted op operators optional optionally optname output override overrides pass perpendicular pic plot plotted plotting plus preprocessor previously print printf processing programmer's provided provides ps qualified rand random range ranges remainder removed requested research rest returns rjust scaled scaling sh shell shift sides silly sin size solid source sqrt src standard star steps stop str string strings style styles suppress surrounded sw symbols sys tenth text thing1.se thing2 thru tick ticks transformations treating troff typesetter typesetting unix value var verbatim volume whatever wid width works x,y1 x,y2 grap 1/grap + absence accesses adding addition aitoff albers aligned allow angle arc arccos arising arranges aux axis azequalarea azequidistant azimuth azimuthal bank based bearing betrays bicentric bilateral bin bonne border borders boundaries boundary bounds breaks bugs bureau canada canal canals cap census center centered centers central charts chauvinism circle circles circular classified clipped closing cmd coarse coincides colatitude comment compass computing concatenated concentric cone cones conformal conformally conic connected consider contains convention convex coordinate coordinates corners counted counterclockwise counties courses covering cross crystallography curved customary cylequalarea cylinder cylindrical dashed data date default define defined degree degrees described descriptions designated detailed developed diagnostics diagonal diagonally directory display displayed disputed dist distance distances dlat dlon dot dotted doubly draw drawing drawn driver dropped earth earth's eastern edge edges ellipse elliptic encompassing environment equal equally equator equatorial equilateral except excessively exist extend extent factor fall falls fan faster feature features file files filled filter filters finally fisheye fit forced gall gazing geodetic gilbert glacier globe globular gnomonic grid gridded guyou harrison height hemisphere hemispheres hex hexagon higher homalographic homing horizontal iceshelf ii ilake image imagine include indefinite independent index indexes infinity input inside intermittent inversely invisible iriver irrigation islands label labels lagrange lakes lambert lat lat,angle lat0 lat1 latitude latitudes laue lesser lib likely limb limited limiting limits lines list lists log lon lon0 lon1 longitude longitudes looking lower lune map mapd mapdemo mapdir mapped mapping maps mecca medium menu mercator meridian meridians middle mile miles minor miscellaneous missing mollweide move names newline newyorker nominal nonstandard north northern numbered numerical oblique observer omit ones onto opening operations opposite option optional options orient orientation orientations orthogonal orthographic orthographically output outputs outside overlay overrides page pairs parallel parallels pathnames pedestal performed periodic perspective plane plot plotted plotting points polar pole poles polyconic polygon positioned positioning positive prefixed prepares presenting prime produced project projected projection projections properly provinces quality ra radial radii radius range ranked ranks ray rectangle rectangular reef refined refractive res resemble resolution response retroazimuthal reverse river rivers rot rotate rotated runs saltpan scale scaled scaling scene seacoasts segments setting sheet shore shore1 shorelines short shows simpleconic sinusoidal size solid source southern sp_albers sp_mercator spaced spacing spacings speed sphere spheroid square src standard star stereographic stereographically straight stretched string strings style suitable superpose support supports suppress suppressed survey switch symbol symmetric symmetry sys tan tangent tetra tetrahedron textured th tilt tilted time times track tracks transparent trapezoidal triangle triangles tries twist unbroken underlying unfolded unknown unprefixed vandergrinten variables varies various verso vertical vertically vertices view viewed viewing views visibility western width window windows wise yankee yorker ±lon0 map 7/map + absence add adds adequate angle ansi blank brackets cmd comments compilers cpp debugging def default dependencies dependent described dir directives directories directory environment except extra files generate ifile include independent inhibit input insert interprets language linenumber lines list listed machine macro mk numbering objtype ofile option options original output path plan preprocessor print processed read reads search searched source source's specifying sprinkled src standard substitution suitable superfluous sys text twice understand variable cpp 1/cpp + absence affect applicable assumed bin bjc bjc240l bugs canon canonbjc240l check cmd comma commas connected convert copies cw.11 cycle daemon de default degrees desired deskjet dest destination destinations dev device devices doc.ps double dsafari dstdout duplex entry environment eqn equations fcw.8 feed file files font generalized generic ghostscript glick gs guide header horizontal hp hpdeskjet i.e image inches include input invoked jobs kill landscape lib lines list logical lp lpdest lpt1data machine magnification manual measured mode ms names noproc offset option options output page pages paper physical port postscript pr print printer printers printing proc processing processor queue range ranges rc regular remaining restarts reverse running safari select sided simplex slot source spooler src standard status stdout stops supported suppress syntax sys tex text tray tries troff typeset user using variable vertical wedged window windows lp 1/lp + absence audio behemoth bit bugs data decode decodes default dev error file files games gnu http hz input it's juke layers lightly linear mad match mp3dec mp3enc mpeg opens option outfile pcm playback playlistfs prints products rate reads sample source src standard stereo stream sys tamed volume warning writing www.underbit.com mp3dec 1/mp3dec + absent accel accelerate acceleration accept accessed actually adapter adapters adequately admits appended applicable arbitrary array asix ata atr attached attachment audio audioctl audioin backward based bass block blocked blue bound buddy buffer bugs bus bytes cancels capabilities card cards care ccid cdc channel characters chest chip class classes closed cmd codes columns combined compatibility compatible compiled configuration configures connection contains continuously control correspondence ctl current customary data dcd dd debug debugging demon describes describing descriptor dev device device's devices diagnostics directories directory disappears discovers discrete disk disks dkm dos dpv drive driver drivers dsr ehci eia eiau eiauctl embedded endian endpoints entire ep3.0 ether ethernet etheru events except extra fail fat feature features fields figure's file files fixed format frequency ftdi generic geometry green guruplug handle heart hips hz ibuddy ibuddyn icc identify implements includes increase indication instruct integral intended interface jtag jtagctl kb kbin kernel keyboard keyboards keyword language led leds length level likely lines list lists locate loses lp lun maintain manages manually mass maxima maximum mice minimum mnt mount mounted mounts mouse mousein names net none occupy omitted operations option options ordered orientation output outstanding packets partfs partition partitions paths percentages port port's ports post posted potentially powering primarily print printed printer printers probe process produces programs prolific provide provided provides range raw reachable read reader reading reads receive red reopened repeating report reported represents resolution returned rpc rpcs sam samples sampling scan script sd sdu sdu3.2 secondarily send sent serial serve served settable settings sheevaplug signals sim similar six size slot smart smartcard soundblaster source speaks specific specifies speed src srv standard started startup status storage suffix supplies supply support supported supports syntax sys systems takes target tested therefore time toy treb tree tried trigger tunnelling uart understood undoes unimplemented uniquely unit universal unmounts unreliable usb usbaudio usbd usbeject usbfat users using usual value values variable various verbose verbosity via view vol volume whatever winged wings working works write writes written yields usb 4/usb + absent accepted access accessed acm add added addr address addresses adds allow allows alter aoe aoeif aoer10.txt aoesrv arbitrary assumed ata attempt august autodiscover autodisover automatic automatically average avoidance behavior bind binding boot bound bugs bytes ca clients colon communication computer conditions config configuration configured congestion consecutive considered consulted contains control controllers converse converted ctl current dangerous data datamtu debug debugging default dev devaoe.c device devices devlink directories directory disallow discover discovered discovers discovery documents due ea echo ether ether0 ether1 ethernet except executing existing exists fairly fashion fields file files firmware flag flags flight frame frames greater headers http ident identify iff incorrect indicates initiator intended interface interfaces jacobson jumbo jumbograms karels keyword keywords larger level lines list log loss lost lostjumbo low machine mapping maxbcount maximum messages michael minimum mintimer model modification netlink netlinks network nframes nl nmaxout nopen nout npkt option outstanding overwhelmed packet packets path plan9.ini poor port primarily primitive proceedings provided providing purpose raw re read reading reads rediscover rediscovery reducing remove removed resent respective returns review robin round rtt rttavg running sd sdaoe sectors segment sent serial serves shelf shelf.slot sigcomm size slot slot's snoopy source space src standard stanford starts startup string subdirectories successive suitable symposium sys target target's targets th timer toggle toggled toggles transfers turns twice unbind unbound unfortunately unit unused usable using values van variable variable's verbatim via visible writes writing written www.coraid.com aoe 3/aoe + absent accepted accessed accesses add address addresses admit affect allocated allocation allow amount args assembled assumed attached attempt attempts auth await base based behavior bind bit block blocked blocking blocks boundary bss bytes calling can't care carefully cd character characters clear cleared closefiles cmd complete completes cons contains contiguous control cost count counter cpu cputime created crosses ctl current dat.h data deadline dealine debugger debugging decimal decrement delivered delivery dependent describes descriptor descriptors desired details device devproc.c dictated directly directories directory display doing don't draw earliest ending enter equal errlen error etc event events except exec executed executing execution exhaust exhausted exhausts exists exited exiting exits explicitly extant fail fails failure fd fields file files flags floating fork format fpregs frequency further generation getfields gleaned hang hexadecimal higher highest hold identifies identifying image implementing impossible inaccessible include increment inherit inherited instruction integer interrupt interval intervals iounit justified kernel kill kregs letter level lines list lists live living lock locks low lowered mach machine main maximum meant mem mem.h memory message messages microseconds milliseconds mode ms multilevel multiprocess names namespace nanoseconds native newns nohang non noswap note noteid notepg notify ns nu nul numbered numeric offset oldest ones opened optional optionally owned parent's particular pending perform periodic periodically periods permitted pid pids piece plan port posted precisely prevent previously pri priorities priority private proc process process's processes processor produces prof profile profiling program's property provided ps pseudonym putting qid quoted rc reach reached reaches read real rearranged receive records recover reference registers regs release released remains renamed representation representations representing require reserved resettable resume resumed retrieve return returning rfnoteg run runnable running rw sampling saved schedulability schedulable scheduler scheduling seconds segment segments sensitive serves signed similar similarly six skipped sleep source space sparingly specifier specifies spin spinning sporadic src stack stamp startstop status stop stopped string strings structure subsequently succeeds suitable suspend swap swapped symbol sys table target test text textual time toggle tokenize tprof trace trace.c trace.h tracing transferred twelve type unit units unless unlikely unset user using valid value virtual voluntarily wait waitstop whenever wire wired working write writes writing written yield yieldonblock proc 3/proc + absent accesses addition arbitrary bytes calling cmd contains copied data date debugging denoting destination dhv environment error fetch file ftp ftpfs header headers hget hget.c http httpproxy incomplete ip length lines missing modified mount mounted net netmntpt ofile option output page performed post posted printed progress proxy retrieve retrieves sends server source specify src stack standard sync sys total transferred turns type types url variable web writes written hget 1/hget + absolute abuts accurate acme actions add addr analyze append application applications applied arg assignment attr attribute attributes basic behavior bit blank block browser built bytes cases character characters check click client commentary component components consist constructed contains convention conventional count cp current data declares default defined defines definitions delete deleted delimited describe described describes destination detail determined dir directory discarded dispatch dispose dollar domain dst e.g edit editor embedded emits emitted enable encoded ending ends entire equal error etc evaluated eventually exactly examined exception executing existing expand expression expressions extract extracts fails fields file fileaddr files fires follow format formatted formed ftp generally generating gif gopher horse.gif horse.gift https identical identified identify image implicitly include indicate intended interpreting interprets isdir isfile jpe?g jpeg largest leading leftmost lib library lines list location longest macro mailto maintains match matched matches matching message messages misinterpreted missing mnt modest mount mouse ndata newline newlines news nntp none object objects occur optional page pair pairs parenthesized path pattern patterns pdf permanent picture piece plumb plumb.h plumber plumbing plumbmsg pointed port portion ports possibly pre predicates processes produced properties protocol ps quote quoted quoting rc received receives refer refers reformats regarded regexp regular reports representation representative requires response rest resulting retrieve rewrite rewritings rule rules run sam sees select selection send sender sending sent shell sign signs skipped space specific specification specifies specify src statement statements string strings structure style subexpression subset substitutes substitutions succeed successful supported supposition syntactically sys tagged telnet terminates text textual transmission triggered type typically unchanged unless unlike update urls user using usr usual value variable variables verb verbs wais wdir web webbrowser window wins working write za plumb 6/plumb + absolute accept acceptable accepted accepts accumulate acquire acquired actions activate activation active adapting add added adding addition addressed adds affect affected affects aggregator aid aim align alignment alignments allocate allocated allow allows alphabetical alt altogether anywhere appearance appearances append applications appropriately arbitrary argc args argv ascii assembles assembling assign assigned associate association attach automatic automatically avoid background backspace bad bar behave behaves behavior bindings bit bitsy black boldlatin1.6.font border bordercolor borders borderwidth bot bottom bounding box boxbox boxboxes boxes boxname brief bring buffer bugs button buttonname buttons calculate calling candidate caps carriage catch caveat center centered centerleft centerright ch chan chancreate channel channels chanprint char character characters choices clamp clamped clear clears click clicking clicktotype client closecontrol closecontrolset clumsy cname co collection collections collects colon color colors column columns combines common complete composed computes configuration configurations configured connect connecting consists constituent contains continue control control's control.h controlcalled controlled controls controlset controlwire convenient coordinates copies correct correctly correspond count couples coupling covered create createbox createboxbox createbutton createcolumn created createentry createkeyboard createlabel createmenu createradiobutton createrow creates createscribble createslider createstack createtab createtext createtextbutton creation cross cs ctl ctldeletequits ctlerror ctlmalloc ctlprint ctlrealloc ctlrunestrdup ctlstrdup current cursor data deactivate dealing debugging decimal decreases default defaults defined defines del delete deletes delivered delivers delivery described describes descriptions design destination destroyed detail details determined determines devices dir direction directly disable disabled display displayed displaying displays document documented don't downwards dragging draw draw.h drawing drawn dx dy easiest easy echoed edit editable edited enable enabled encodes encounters encouraged enlarged enter entry entryname equivalent error established establishes etc event events eventually exactly examining existing exists exits experimenting explicitly extra fail failed fatal features fields file final finally finds fine fingers fit fixed flag fmt focus font font's fonts format formats formatted formatting frame freectlfont freectlimage freed frees further generated generates geometry getfields getwindow global globally goal goes graphical graphics greater grouping groups guarantee handled handles height heights hello helper hexadecimal hidden hide hiding hierachy hierarchies hierarchy highlight hits honored hor horizontal identified ignore ignores illuminates image images implement implementation implements include increases independently index indexed indicate indicates indicating indicator indicatorcolor indicia initcontrols initdraw initialization initialize initkeyboard initmouse input inset insetrect install int integer integral interactive interchanged interline interpretations interprets invisible justified kc key keyboard keyboard.h keyboardname keys keystroke keystrokes label labels largest lay layed layout lays level lib libc.h libcontrol library linecolor lines linked located lock log lost low lowercenter lowerleft lowerright lucidasans lucm maintained malloc manages managing manipulated manipulates manner mask masks match matches matters max maximum maxx maxy maxΔx maxΔy mc meaningful mechanism member memory mentioned menu menu's menuname menus message messages method min minimum minx miny minΔx minΔy missing modified moreover mouse mouse.h moved msec multi multiline multiplexing name1 name2 namectlfont namectlimage names naming nbot necessary needed needs neither nelem newcontrolset newline newlines nil nn non none note ntop nul numbered numeric numerical object obvious occurred ommitted ones onto opaque operation operations opposite optional organized orient orientation origin other's output overlayed packagings packed page paint paleyellow palmtop paradigm parses particularly pass passwd.9.font passwords pastes permits piece pixels placement plain plan plans pointer pop portion positioned precede presented presents press pressed pressedtextcolor primitive print printed prints processed processes processing programs properly proportional proposal provided provides q.v quotation quote quoted quotefmtinstall quotes quoting r1.max.y r1.min.y r2.max.y r2.min.y radio radiobottuns radiobutton radiobuttonname range rc re react reader reading rearrangement reasonable reassign reassigned receive receives receiving recipient recognized reconnect rect rectangle recvp red redraw refbackup refer referenced refers refnone refresh refreshed refreshes region regular released remove removed removes render repetition replace reported reports representation representing request requested rerouting resize resizecontrolset resized respects respond responsive rest resume return returns reveal revealed revealing rewiring richer roles row rows rules runes screen scrib scribble scroll secret section sections select selectcolor selected selection selections selectmode selects selecttextcolor send sender sending sends sensible sent separation separator serve setting setup share shared sharing shift shown shows significant simply simulated situations size sizeof sizes slide slider slider's slidername sliders snarf source space spaces spacing specific specifies specify squared src stack stacks standard static strcmp strict string strings strokes struct structure structures subject supremum sync synchronization syntax synthesizing sys sysfatal tab tabbed tabs takes tears terminator text textbutton textbuttonname textbuttons textcolor textname textual th tha thread thread.h threadexitsall threadmain threads tightly time toggle toggled toggles tokenize topline touch transmitted transparent trigger triggered triggers trivial turns type type1 type2 typed typedef types typically typing u.h uint unadorned unicode unicode.6.font unimplemented unique unless unmodified unpredictable unquoted unselected unusual uppercenter upperleft upperright user using usual utf valid value valued values variable variant various ver verb vertical vertically via vis visibility visible visual void volume whenever width widths window windows wise works write writing yellow yield control 2/control + absolute accept acceptcookies actual address agent allocate allows arrives associate assumed attr attribute attributes baseurl bell bugs chatty9p clear client clone closed cmd comment comprises conform confusingly connection connections consistent contains content contenttype controls cookie cookiedebug cookiefile cookies ctl current data debug debugging decimal default defaults described descriptor determine directories directory discussed discussion domain dot edited editing effort epoch equal equivalent error ether executed expire expires explicitdomain explicitpath fetch file files finally flag flags format fragment fsdebug ftp ftptype global header hget hierarchies host hosts http https included index.html inferred infinite initialized initiates instance instances interface internal ip it's italics keeping labs.com level lib library loop maintain message mime mnt module mounts mtpt names netscape netscapestyle network numbered opening ordinary output page pairs parameters parsed parses parsing particular password path pattern persistent pieces plan post postbody posted presented presenting presents prints private profiles protocol query read reading reallocated redirect redirecting redirectlimit redirects relationship relative remote request requests respond resulting retrieved retrieving rfc2109 root's scheme schemedata seconds secure sendcookies sends sent server servers share source specification src srv standard stored string strings style suffix suggestive synonymous syntaxes sys text time traces type unimplemented url urldebug urls user useragent value values variable variables version via web webcookies webfs webget.c whim wide writing written www.bell www.lucent.com www.not www.research.bell yields webfs 4/webfs + absolute actions actual added addition additional adds albaseline albottom alcenter alchar align alignment alignments alink aljustify alleft allocate allocated allocates allocation almiddle alnone alright alternative altop altrep analogous anchor anchorid anchors animated application array ascent assigned attribute attributes automatically auxiliary availw background backgrounditem bar bars base baseline belonging bind bit bits blank bold border break buf buffer bugs builds bytes caller caph caption caption_lay caption_place cases cell cellid cellpadding cells cellspacing center char character characters check checking chset class clear cleared client col collection color cols colspan column columns combination complex components composed comprise considered consists consortium contained contains content control conventional conversion converted converts coordinates coords corner correct correspond correspondingly created ctlid current data datalen dbgbuild dbglex debugging default deffnt defined defines definition describe described describes describing desired destanchor destination destinations dests detail details dimen dimenkind dimension dimensional dimenspec directly displacement display displayed dnone doc docinfo docinfo.anchors docinfo.dests docinfo.forms docinfo.images docinfo.kidinfo docinfo.maps docinfo.tables doctitle document document's documents don't dpercent dpixels draw drelative emalloc embedded encapsulates encoded encodes ensures entire enum enumerated equiv erealloc error event events everything except expanded expects extracted fails fbutton fcheckbox ffchecked ffile ffmultiple fg fhidden fieldid fields fill fimage finally finds finished fit flags float floats flows fmt fnt fntb fnti fntr fntt font forced foregound form's format formatted formfield formid forms fpassword fradio frame framebd frameborder frameid frames frameset framesets freed freedocinfo freeitems freset frhscroll frhscrollauto frnoresize frnoscroll fromstr frvscroll frvscrollauto fselect fsubmit ftblank ftext ftextarea ftparent ftself fttop ftype genattr generic gets global grid halign handles handling hang hangs hasn't hasscripts headed header headers height hget highlighting holds horizontal hpost href hspace hspec html html.h http hyperlink hyperlinks hypertext id ids ifbrk ifbrksp ifcjust ifcleft ifcright ifhang ifhangmask ifindentmask ifindentshift ifloat ifloattag ifnobrk iformfield iformfieldtag ifrjust ifsmap ifwrap ignore iimage iimagetag image images imheight implement implements imsrc imwidth include includes indent index indicate indicates indicating indices infloats info initially input inside installed int integer intended intermediate internal internally interpret interpretted irule iruletag isframeset iso_8859_1 ispacer ispacertag ispgeneral isphspace ispnull ispvline itable itabletag italic item items itext itexttag justified kept kidinfo kidinfos kindspec laid lay layout leaves length lexer libc.h libhtml library lines link linked list lists loaded low malformed malloc map map's mapped mapping maps margin marginh marginheight marginw marginwidth markers maxlength maxw measures media mediatype memory meta method minw msg mtype names ncell ncol ncols ncoords needed negative nested newly nextfloat nextframeset nextimage nextinrow nfields nil non noresize noshade note nowrap nrow nrows null numfnt numsize occur offset ok option optional options or'd original pad padding page parameters parsed parsehtml parser parses parsing particular parts pdi pending percentage permanent permitted pertaining piece pixels placing pointer pointers points portion pos predefines print printed printitems process provide provided provides purposes realloc referenced reflects refresh relative remaining represent representation represents requested required reserved resize respond retrieved return returned returns rgb role roman routines row rows rowspan rule rune screen script scripted scripting scripts scripttype scroll scrollbar section sections selected send seonblur seonchange seonclick seondblclick seonfocus seonkeypress seonkeyup seonload seonmousedown seonmousemove seonmouseout seonmouseover seonmouseup seonreset seonselect seonsubmit seonunload serial server sevent shaded shape shcircle shpoly shrect similarly size smaller solid source space spacer span spanned spans spec specific specification specifications specifiers spkind src standard sticks stops store stored strike string strings struct structure structures stuff style styles submitted subsidiary substructure subtract successor suggested sys tab table table.cells table.grid tablecell tablecol tableid tablerow tablerow.cells tables tabletok tabstop tag tagged tags takes target targetid targetname targid td tenths terminate text texthtml textjavascript textplain tfisth tfnowrap tfparsing th times tiny title token tostr total toth totw track traverses type typedef types typewriter typical typically u.h uchar ul ulmid ulnone ulunder underline underlying unicode unique unnamed unsupported unvisited url us_ascii user using utf_8 valid validitems valign value values variable variant variety various verb vertical verylarge via visited vlink voff voffbias void vspace w3c warn warning web weight whenever whereas wide width wrap wrapped wspec html 2/html + absolute actually add addison adjust affect al alternatives angle angles anywhere apart ar arc assignments asterisk aux auxiliary auxname axis b:c base bbl becomes behaves behavior bib bibinputs bibliography bibliographystyle bibtex bin bit bitmap bitmapfonts bitmaps bizarre bk black braces bst bugs building center chapter character chatter circular cite clipping clockwise cmd colon colons commas common compress configuration conjunction constrained consulting contains controlsequence convert converts coordinate count count0 count1 count9 created creates creating cross current da dashed dashes default defined degrees delatex deroff described describes descriptions dev device diameter directly directories directory distill distilling dlen doc document documentation documents doing don't dot dots dotted downward draw drawing drawn dt dvi dvifile dvips dviselect ed edition editor elliptical emitted enable endpoints entire environment equal error especially et everything execute executed exist expand explicitly extend extended extension extract fair file files fill finally first:last flush fly font fonts format formats formatting forming fp friends gather generate goes graphics grey guide headers hierarchy hoffset hscale hsize illustration inches include included includes independent index indicated infile input installations installed interspersed invoked jobname key keys knuth lamport landscape lar latex leading leave length level lib list listed listing lists loaded locally log looks lp ls macro macros manner manual matrix measured medium mem mentioned messages metafont metapost metric mf mfinputs midpoints milli miscellaneous mktexlsr mode modified mp mpinputs names necessary needed negative notation numeric object objtype offsets omitted openin option optional options organized origin outfile output outputs overridden pa packages page pages pairs paper paper.tex path paths pdf pen periods pic pieces pk pkfonts pn points polygonal pool portable positive possibly postscript preloaded preparation print printed printers processes processing produces programmer's programs proof properly ps psfile psfonts psvf quadratic quick quickly radii range ranges rc reads referencing replaced research reset resulting reverse reversing rooted rotate run runs runtime scale search searched searches searching section segments select selector selectors selects sending separately seventh sh shading sign simulates sit sites size sized sizes slen slitex sought source sp space specials specify specifying spelled spline src standard started straight string strings style supporting switch sys table takes template ten tenth testfont.tex tex texbook texedit texformats texinputs texmf texmf.cnf texpool texput text texvfonts tfm tfmfonts thebibliography third time tpic transformation translate tree trickey troff truncated twice typesetting typically underscore understands units unix user using usr value values variables varied various verbose version versions vffonts viewgraphs virtual voffset volume vscale vsize walk walking web2c wesley wh wherever width wildcard write writes writing written x,y xr yr tex 1pub/tex + absolute addr address affirmative alternate announces args attach authentication authsrv aux bin bind bit box bucket bugs bytes chargen clients cmd compatibility concatenating connection consume convention cpu created daemon default delivery device dial directories directory dns echo encrypted encryption env environment executable executed executes executing execution file files forgoing ftp ident imap4rev1 import inbound incoming inferno's intended invoking iq lib lightweight listen listen1 listener listening listens log logging looks lp mail mirror modeled multiplex multiplexing names namespace negotiation neither net network non none nor option optional output path periodic personal piece plan pop3 port pptp protocol rc received remote report reports rlogin root run running rx scan secure securenet selects serve server serves service.auth services shell source space src srv srvdir ssh ssl standard started subtree suppresses sys sysname systems tauth tcp tcp0000 tcp110 tcp113 tcp143 tcp17007 tcp17008 tcp17009 tcp17010 tcp17013 tcp1723 tcp19 tcp21 tcp22 tcp23 tcp25 tcp513 tcp515 tcp53 tcp564 tcp565 tcp566 tcp567 tcp7 tcp9 tcp993 tcp995 telnet terminal ticket tlssrvtunnel transfer tree trustsrvdir tunnelling tv typically unix usable user users using usual validate verbose via listen 8/listen + absolutely access add append assign bits chmod chmod.c cmd combination constructed default directory exclusive execute existing file file's leader letter letters ls mode modes octal omitted op owner permission permissions read reset search source src stands stat symbolic sys temporary ugo user's write chmod 1/chmod + abstractions acquired addr adds arrange atomically block channels coordinate correct count decrements diagnostics directly e.g efficient error errstr facilitate flag fork higher include int integer intended interrupted level libc.h lock locks memory pointed points port positive process processes rendezvous replacements return returns rfmem rfork scheduling segattach semacquire semaphore semaphore's semaphores semrelease share sharing source src sys sysproc.c thread threads typically u.h user using value waiting waits semacquire 2/semacquire + abutting accesses accident actually adding addpt allocate allocation allocimage alphabet application applications appropriately approximately archaic arranged arranges arrays ascenders ascent ascii assume automated automatically backing bad baseline beyond bit bits black border bottom buffer buffered bufimage bugs buildfont builds bytes cachechars can't chan channel chantodepth chantostr char character characters client client's clients closedisplay clr color common concatenated connect connection connects cons contains contiguous convention convert coordinate coordinates copied core create created creates current cursor cursor.h data default defaultfont defaultsubfont defined defining definition desc descenders described describing descriptor desiring detail detailed details dev devdir device diagnostics directories directory disconnects display displayed displays distance doing draw draw.h drawerror drawing driver dx dy edges emoveto endian environment errfun error errstr esetcursor establish etc euro european event excluded exist extern extra failed fails failure fatal fd fields file files flush flushes flushimage fmt font fonts format formats frame freefont frees fresh full further gengetwindow geninitdraw getdefont getenv getwindow global graphics height hence hidden hide hierarchy highest historical holding identify image images immaterial imports include includes increasing independent indexed indication initdisplay initdraw initialize input inside installs int interactive interline internal international interrelated ip label languages latin1 letters lib libc.h libdraw library library's location lockdisplay locked locking looking lower lowest map marks mask max max.x max.y maximum mechanisms memory message messages method min min.x min.y minimal mount mouse mousedir moveto mrepl msg multi namedimage names naming needed negotiates newly newwindow nil nine non none notify null occupy offset opaque openfont opening operating operations ordwr organized oriental overall overloading overwrites overwritten package parses particular path pending pfmt phonetic pixel pixels pointed pointer pointers points portion presented print printing private process programs protected protocol provides punctuation range raster reading reads reconnect rectangle rectangles rectangular ref refnone refresh reminders representation representing represents reside resize resizing resources restore resulting return returning returns rfmt rfnameg rfork rio root routine routines row rows run runes running screen screen2 send sent setcursor similar size sized soft sophisticated source sp space spacing specifies src srvwsys starts store str string strings strtochan struct structure structures subfont subfonts subwindows success sys sysfatal sytem text time tmp transparent typedef u.h uchar ulong unfortunate unicode unlockdisplay upper using utf values variable variables various vis visible void win windir window window's windows winname wish writes writing written wsys graphics 2/graphics + accelerated acceleration application arrow binary bind bit bitmask bits blank blocks bugs button buttonmap buttons byte bytes characters clears clients clr configures consist controlling controls coordinates cope current cursor cursors decimal default delta described details dev device devices devmouse.c displayed don't endian equivalent event events except exclusive external extra factor fewer fields file files format generated generates graphics hardware host hwaccel ibm idempotent illusion image implement inclusive intellimouse intended interface interpret kernel key laptops letter level linear managed map message messages mice microsoft middle milliseconds mouse mouse's mousectl mousein move msec multiplexed notably note notification offset omitted opened ops optional owner pointing port pressed private processed provides ps2 ps2intellimouse read reading res reset resize resolution rest restores returns rio screen semantics serial setting shift software source space specifying src stamp status strings swap swaps sys thinkpad time turns units unlike usb user using usual via wheel wide window write writes writing written xyz mouse 3/mouse + accelerated add adding adm auth authentication bin bind bit bootstrap box brings build built cat changeuser chosen con cons consctl console cpu cputype create cron dev directories drawterm echo env environment establish established euro.9.font exec exists factotum file fn font fossil fossilcons fs label latin1.8.font lib looks mail mbox mnt mousectl namespace necessary news newuser passwd password pelm plan plumber plumbing profile prompt properties prudent rc reasonable reboot reflect res rio rules run running runs script sensible server sites step switch sys sysname term terminal test tmp type uname upas user user's users using usr wsys newuser 8/newuser + acceleration actual added adding addpt advantage align aligned alignment allocages allocated allocator allocd allocmemimage allocmemimaged allocmemsubfont allocsubfont allows alpha analogues arc ascent attaching bad base basis bdata bit bitmap bits bounding box buf buffer bugs byte byteaddr bytes calculates calculations calling chan channel channels char chunks clients clipped clipping clipr clips cloadmemimage cmap color compact compressed congruent conservative consumed contains coordinate coords corners cover cp creadmemimage creating cs current data debugging defines depends depth dereference described descriptions descriptor destination determine dev differ directly display dr draw draw.h drawclip drawdebug drawing drawop driver dst ellipse end0 end1 enum error exactly except explicit extra falpha fbytes fcmap fd fgrey file fillpoly fills flags fmt font fontchar format formats freememimage freememsubfont frees freesubfont frepl fresh fsimple gendraw getdefont getmemdefont global graphics grey hardware height hierarchy holds horizontally hwdraw identical image images imref include info initializes instance int integer integral involved iprint kernel layer length libc.h libmemdraw library loadmemimage machine malloc'd manipulate manipulated mask memarc memblack memdata memdraw memdraw.h memdrawparam memellipse memfillcolor memfillpoly memimage memimagedraw memimageinit memimageline memimagemove memimages memimagestring memlayer memlinebbox memlineendsize memopaque memory mempoly memsetchan memsubfont memsubfontwidth memtransparent memwhite method methods move moves mp nbuf nchan nil non note np obvious offset ones op openfont openmemsubfont operate operation origin output overridden param parameter parameters particular perform phi pictures pixel pixels pointed pointer pointers points poly pool precomputed print prints programs purpose radius readmemimage reads reasons rectangle rectangles rectangular ref referring region repl replace replicated representation request request's resident retrieves return returned returning returns routines rpcs satisfy scan screen serial similar similarly solid source sp sr src static storage store string stringsize strsubfontwidth strtochan struct structure structures stubs style styles subfont subsumes success sys systems tables takes thick translated type typedef u.h uchar ulong uncompressed unloadmemimage unusual updates upper user using utf values variable various void width wind wordaddr works writememimage writes yield memdraw 2/memdraw + accented adm affected alphabetical arithmetic ascii assume attached bugs bytes capitalized character characters check choice cmd cmumbdf colon comments compare compared comparison comparisons conditions confused consisting dates decimal default defines diagnostics differ digits dir directory discovered disorder e.g earlier ending entire equal etc except exits exponents external feb fields file files flag flags fold folded format further generated global globally grep hopelessly ignore independently input inputs inrwt instance internally invalid jan key keys leading letters lexicographic lines list longer low lower mbdfginr meanings merge minus missing month months non notation null numeric onto option optional optionally options ordered ordering ordinal origin original output outside override participate phone pid plus pos1 pos2 posix precedes predictable print provincial range representative restricts reverse rules runes sed separating sign significant skip sort sort.c sorted sorts source space spaces spellings src stable standard status string strings style sub suppress sys tab tabs tells temporary tmp trouble um umm uncapitalized understood uniq unique unless upper user users value various writes sort 1/sort + accentuate achieve affects allows alternative alternatively ascii awk behave black blank blue bugs button center clicking cmd color comes consecutive contains coordinate coordinates counter cyan default defaults delete delimited denote deviates deviations digit display displayed displays dkgreen dkred dkyellow double drawing drawings drawn editing edits enabled equal essentially etc everything exit explained extra factors feature file files finally fit fits flavor format generate generates goes graph gray green gview gview.c halfway horizontal i.e input interactive interactively interface intuitive invoked invoking label labels legal lets letter lieu linear lines lists log logfile ltblue magenta manner menu move mp multi names newline operations option optional optionally options orange output overlay pair parallelogram perform pink pipe plots points polygonal polygons polyline polyline's polylines positive print quotes read reads recenter recolor rectangle red reflects restack restores rotate scale scatter scheme screen script select selected selecting selection selects shrinks similar sin slant slants source space spaces square src standard straight strangely string sweeping swept sys tail takes tells text th thick thickness thin third type undelete undesirable undo undoes unnecessary unslant unslanted unzoom user value versions vertex vertical vertices viewer viewing views violet virtually whichever window write x,sin yellow zoom gview 1/gview + accept accepted accepting added addition address addressed addresses addressing affected allow alone ampersand appearing append appended applies assume assumed automatic backslash backslashes backspace backward blank bounding browse buffer character characters cmd collected comma compatibility confirming consequence considered constructed copy correspond counting counts created cumulative current customarily decimal default defaults del delete deleted delimit described desired determined diagnostics differs digit digits direction discards discussed displayed dot double e.g earlier ed ed's ed.c ed.hup edit edited editing editor enclosed enclosing ends entire equivalent error errors everyone exact except execute executed exist existing expression expressions fail fd file filename files folded format forms forward generally global hangs hexadecimal inaccessible included indented indicated indicator initially input insert insufficient intermediate interrupt join legal letter level lines list literal lower maintain mark matched matches matching mean merely metacharacters minus missing mode modified moreover move moved multi necessary nested newline newlines non none notation nul occurrence occurrences omitted operates optional options ordinary output overflow overflows overwriting page pagesize parameters parentheses parenthesized perform permitted piping placement pln plus portion possibly precedes preceding prefixing presence print printed printing prints queries quit rc read readable reading recognized refers regard regexp regular remainder remembered replace replaced replacement reposition require requires resides resp respect restore resulting returns reverses rule sam saved search searching sed semicolon send sent shell shown sic sign signal simulates slashes source space specifies specify src standard stepping stop stopping string structure sub subexpression subexpressions substitute substituted substitution subtracted subtraction successful successor supports suppress synonym sys tab temporary terminal text th third time tmp transfer typed typically typing unambiguous unchanged unconditional unconditionally understand understood undo venerable versions wraps writable write writing written ed 1/ed + accept accepted accepts access actual add added additional address addresses adjusting adjusts aid amounts applications attached audio avoid belongs bigger bind bit blocks boot branching bugs built bulk bus busy buttons byte bytes cases caused class classes clear clrhalt codes combination combo common communication complete completion complex computer condition config configuration configure configured configuring connecting consecutive contains continues control controlled controller controllers converts correct corresponds counting crc create created creates csp csps ctl data debug debugging default delete described describing descriptions descriptor detach detached detachment determine determines dev device devices devusb.c diagnostics dictated direction directories directory disk disturbing dmexcl documented driver drivers drop dt due dump dumps e.g easier eg ehci enable enabled endpoint endpoints enter enters entire enumeration ep error errors etc events everything exercised existing explored expressed failure failures file files fit flag flavours format former frame frames frequency full fully further gb generates global halt happens heavily hertz hidden host http hub hubs hurts hz identifiers identify identifying idle ignore ii implicit implied implies include includes indicating indication info initialization initially inout input inspection integer interface internal interrupt interrupts interval intr iso isochronous issue issued issues issuing kernel keyboard keyboards kingston larger leaf learn leaving level library limited linked listed locate longer low main manner manufacturer maximum maxpkt mb merely message messages mice mode mouse ms necessary network newdev nodes note noticing ntds ohci ones operation output outs packet page particular passive pc pcs perform performed performing permit physical plan9.ini points poll polled polling pollival polls popular port ports prevent process programs proto protocol provide provided provides providing queries querying read reading receive receiving recover refer relevance remove removed replaces reply report reported reports represent represents request requested requests responsible rest resulting resume retrieve retrieves root route run rw sample samplehz samples samplesz scan send sending sends serial setup severe shaped signal significant size somewhat soon source speaker specialization specialized specific specification speed src stall stalls standardized starts statically status stops storage str streams string strings structures subclass subclasses subsubclasses succeeded supplying support supported sys takes task textual throughput time timed timely timeout timers topology transactions transfer transferred transfers tree type types uhci understood units universal unknown unstall usage usb usb.h usb?hci.c usbd user using value values vanish various vendor verbose vid volume wire wiring wrapped write writes writing written www.usb.org xhci µframe µframes usb 3/usb + accept accepts access affected appearance application attach automatically bar bind blanks block blocks bottom buffer button catenation cd character characters chdir choose clients closing cmd cons consctl constructed contains continue control controlled controlling controls convenient coordinates corner create created creation current cursor data dealing decimal default defined del deliver depth describing dev device digits directories directory disable display draw dx dx100 dy echo edge editing enable entire entries environment establish etc event except executed extra features file files fill finally font format formatted full fully generated generates geometry getwindow graphics hangup hangups height hi hidden hide hold holdoff holdon horizontal id idea identified identifies image initially inner input instance integers interpretation interrupt introduced invisible invocation item keyboard label lead leaves located location lower lp main maintains managing maxx maxy mediate mentioned menu menus message messages minus minx miny mnt mode modes mount mounted mouse move moved movements moves multiplexed multiplexes necessary neither newly nor noscroll notcurrent note notes obscuring opening operations option optional options outside parameters parent partially particular pid pipe placement places plain plumb possibly posts pressed print printed process processes programs properties provide q.v raster raw rawoff rawon rc re read reading receive receiving recipient recursively released reporting representing resize resized restore returns revert rio run running sam screen scroll scrolling section selected send server serves services shell sign similarly size sized snarf source space spaces specific specifier src srv standard string strings style subdirectory supplies supply syntax sys tag terminal text tmp totally turns unaware unchangeable uncompressed underlying unhide unique update upper user using usual variable variety version versions virtual visible wctl wdir whom width window window's windows winid working writable write writing written wsys rio 4/rio + accept accepts add address addresses addressfile addressfiles adds aliasmail allow allows append appended archives attachment attachment's attachments automatic avoid bat behavior bh bin bound box build bulk check checker checks cmd com combined contained contains content conventions copy created creating current date default delete deliver delivered delivers depends described determine determines dev directory directs discard discards doesh't entire error exactly exe executable executables execution exist exists exit expression expressions extension extensions extra faces fifth file filename files filter filtering filterkit flag flags forms fromfile gets gunzip gzip header headers image implement include includes incoming input insensitive key kit lib lines list locking log logging mail mailbox marshal match matched matches matching maybe mbox message message's messages microsoft mime mimetype mlmgr names nedmail non none null obeys onto option outgoing output pairs particular pass pattern patternfile patterns pipefrom pipefrom.sample pipeto pipeto.sample precedence prints profile provided provides qer rc rcvr read readable readers recipient recipient's regexp regular reject rejected rejecting rejects remaining returns rewrite rewriting rule runs safety sample sanitize sanitizes savefile scr script searches send sender sender's shell smtp source specifies src standard status string successfully suspect sys takes tested text token tokenfile tokens type types unaltered unique upas upasfs user user's username using validateattachment verbs vf virus viruses wrapped writable x.tar x.tar.gz yes zip filter 1/filter + accept access actual address associate assumed attr attributes bell bugs clear client clients cmd comment comprises conform confusingly connecting connections contains cookie cookiefile cookiefs cookies data decides decimal default descriptor directory domain dot edited epoch exists expire expires explicitdomain explicitpath file files flag full header headers hget hostname http https included indication inferred intended ip it's labs.com lib lines manage manager manages mnt mounts mtpt netscape netscapestyle opening outlined pairs particular path pattern persistent post presented presenting profiles reading reads relationship remote representation request requests response rfc2109 save seconds section secure sent server servers serves sites source specification src srv standard style suffix sys textual time url urls user value values version web webcookies webcookies.c webfs write writing written www.bell www.research.bell yield webcookies 4/webcookies + accept actively alg algorithm allocated announce approximately auth authentication bind choices cipher ciphering clone comp compresses compression connect connection connections contains control controlled ctl data datagram de debugging decrypting des_56_cbc descriptor device devsdp.c dial directory drop encrypted encrypting encrypts errors established file firewalls hmac_md5_96 hmac_sha1_96 identifying implementing incoming independent initiate insecret integer interface ip level listen log machines message messages mount net network networks newly null numbered opened opening outgoing output outsecret packets passively permil port programs protocol provides proxy randomly rc4_128 rc4_256 read reading receive representing reserves returned returns rstats sdp sec secret secure services simulating source spec src stack stacks stats status string strings subdirectories supported sys text thwack transfer typically udp un using via writing written sdp 3/sdp + accept add allocate allocates allows arg array background backing backup basic belongs buf build built bytes clear client col color component compressed connects coordinate coordinates coords corner couple create created data defined definition deleted deletes delta display displayed dnofill doing draw draw.h drawing drawn drawop dst due efficient entry establish expects extend fields fill flag fn format frees front frontmost fully geometry goes graphical graphics holds ia identical image images implement include initialized int interface internal interpretation iscompressed kernel layer layers leaving libc.h libmemlayer library loadmemimage location log logical losing main maintain management mask memdraw memdraw.h memimage memimagedraw memimageline memimages memlalloc memlayer memlayer.h memlayer.save memlayers memldelete memlexpose memlfree memlhide memline memlnorefresh memload memlorigin memlsetrefresh memltofront memltofrontn memltorear memltorearn memory memscreen memunload method methods min modified mp nil non obscured op operation origin outside overlapping paint painting parts performed permitting phys physical picture pointer points portion portions predefined presented provide provided pulled pulls push r.min rear rearmost receives recorded rectangle recursively reducing refresh refreshed refreshfn refreshptr regardless repainting represent resident restore restores restoring routine routines save savvy screen screenr setting signatures similarly size smaller source sp specifies src stack store stringsize struct structure structures subdivide sys systems temporary type typedef u.h uchar ulong ultimately unaffected uncovered underlying unlinking unloadmemimage upper using valid versa versions vice visible void window window's windows memlayer 2/memlayer + accept added admissible applied args array ascii assigned assignment assignments atof automatically base behave behavior brace bracket brackets bugs calling char character characters circumflex complete completion composed comprise comprising condition conflicting consumed contains control conversion converted count ctype current decimal defined defines described detailed determinable differing differs directive directives directly double due earlier ell ends eof error evaluated event except excess executed executes execution exhausted expected fails failure failures fewer fgetc file finally float floating fopen format formatted fprintf fscanf function's hexadecimal implementation inappropriate include includes increment indicated indicating input insufficient int integer interpretation introduced invalid isspace item items leading length libstdio list literal longest matched matches matching maximum newline non nonempty nor nul object objects occurs octal offending optional optionally ordinary permitted plan pointed pointer pointers prevented produced provided range read reading reads receive received receiving remain remains return returned returns routines scan scanf scanlist scanset sequences short sic signed similarly size skipped source space specification specifier specifiers specifies src sscanf stdin stdio.h steps stream string strtod strtol strtoul subject subsequence success suppressed suppressing suppression sys terminates type u.h unavailability undefined unless unread unsigned using utf valid value vfscanf via void width written fscanf 2/fscanf + accept addpt analogous array bit bytes cachechars char character characters component compute diagnostics directory display draw draw.h drawn dynamically encoded error extent files font fonts generate geometrical graphical graphics image include int lib libc.h libdraw loaded lower nul produce representing returns routines rune runes runestringnwidth runestringsize runestringwidth server size source src straightforward string stringnwidth strings stringsize stringwidth subfont sys u.h upper utf vector width stringsize 2/stringsize + accept addr address arriving assigned bind boundaries broadcast bytes card cards clone closed connect connection connections constant contains control copies copy ctl data decimal demultiplexed destination devether.c device directory distinct enables ether ethernet extra ff:ff:ff:ff:ff:ff file files header hex identifying ifstats incoming independent index inserted integer interface interfaces mac machine net network newline opening optional options packet packets permitting plan9.ini promiscuous punctuation read reading reads receive receives remains returns send sent source specific src statistics stats status string subdirectories supply sys terminate type types unique value wavelan write writing written ether 3/ether + accept ansi atof atoi atol atoll base behave bugs calling char character characters charstod constant continuation contrary convert converted decimal described diagnostics digit digits double ends escapes floating fscanf gets hexadecimal include indicators input int integer integral interpret interpretable interprets leading legal letters libc libc.h manner necessary nptr octal optional optionally pointed port recognize recognizes representation returned rptr scan sign signed similarly source spaces specification src stream string strtod strtol strtoll strtoul strtoull style successive suffixed sys tabs terminates text therefore type u.h ulong understood unrecognized updated uvlong value vlong void atof 2/atof + accept avoid benchmarking block buf bytes calling check checks client code conn copy data default described diagnostics disables disk doing error execute executes extern extra flush frees hash hello include indirectly int issue larger libc.h libventi mainly matches memory modify nil packet parallel partial pending ping proc procs production programs protocol purposes read reads recommended request requested requests response return returned returning returns routines rpc running score sending server server's setting sha1 sid simultaneously size source src stores succeed success sys tag threads transaction type typically u.h uchar uint venti venti.h ventidoublechecksha1 via vtconn vtconnect vthello vtpacket vtping vtread vtreadpacket vtrecvproc vtrpc vtscoresize vtsendproc vtsync vtversion vtwrite vtwritepacket waiting write writes written venti-client 2/venti-client + acceptable accepts accessing accidental acts add addition address advisory allow annoyance append approach arbitrary archival arrange authentication avoid basic block block's blocks bodies brackets buffer byte bytes character characters choosing chosen client clients coalesced codec colons combined comment common complex compression comprises concatenated concepts conference connection connections connects consisting consists constant constants constructed consumption contains continues convention conventional conventionally convert copies copy count counts crypto data debugging delay depth describe described describes describing descriptions descriptive destruction details differing directories directory disk distinguish distinguished documents dorward duplicate earlier echo encoded encryption endian ending ends enforces entirely entries enumeration error etc eventually exchange expected ext2 failed failure ffs fields file files final fixed format forming goodbye greater hash hello higher historical hold identifier identifies identify identifying identity illegal implementation include includes indicating integers integral intended interface items keeping kilobytes knowing label lack latter length lengths level library list listed literal mainly malicious manipulating manner manual match maximum meanings memory message messages metadata minor mix necessary needing network notation nul octal operations optional outstanding pad padded page parallel parameter parameters particular permanent ping pings pointer policy port prefix prefixed prefixes preventing process producing program's programs protocol quinlan rcodec rcrypto reach read reasons receiving recording reducing refer referencing remaining removed replies reply represent representation represents request request's requests rerror respond responding response responses responsible resulting returns rpc run score scores sean sending served server servers session sha1 short shorthand sid significant similarly simplifying size sizes smaller specific specifies specifying split storage store stored storing strength string strings structure structures subsequently summarized sync tag tags tcp technologies terminates text transaction transmits transmitting traverse tree tree's trees truncate truncated truncating truncation type types typically uid understand unicode unsigned usenix using utf vac vacfs value variable vbackup venti venti.h version versions vtdatatype vtdirtype vtentry vtfromdisktype vtread vtrerror vtrgoodbye vtrhello vtroot vtroottype vtrping vtrsync vtrwrite vttgoodbye vtthello vttodisktype vttping vttread vttsync vttwrite waiting wire working write writes writing written venti 6/venti + acceptable added address addresses answers assumed att14400 aux baud baudrate bin bugs built caller ccitt class cmd commas communications compatible compress compression computers con connection connections control converted converts cover data decimal default derived destination dev devs dial dialer dialers dialing dir directory e.g edited eia1 encoded facsimile fax faxqueue faxreceive faxreceive's faxrecipients faxsend file files follow format generated h.ps hayes highest id images incoming input insert interface interfaces invokes ip kept lib list log lp machine mail match message modem modems modifiable mt1432 mt2834 multitech's names needs negotiable net network notification option options outgoing output page page1 pages passing pauses pc phone portable postscript process programs provided provides pulse queues rate rc reads receiverc receiving recipient recipients representing require safaris scheme script sends sent server sheet shell source specific specify spool spools src standard started starts string subset success supported sys telco telcodata telcofax telephone telno text transfers transmits transmitted transmitting type types user using verbose via vocal write telco 4/telco + accepted access accessed actual adjacent align aligned aligns allocate alpha ambiguities angles application arc arrow ascent associate association attach background backing bgid bglong bgshort binary bind bit bits blank blending blue bottom bp bplong bpshort brackets buf buffer bugs byte bytes cache cacheid caches calculations calpha catenation cblue cells center centered cgreen cgrey chan channel channels character characters cignore client clipped clipping clipr closed cmap color colormap combine common complementary compositing compressed conceptually confined congruent connection connects consists constants contains control coordinate coordinates corner correctly correspond corresponds count cred ctl current data debugging debugon decimal default defined definitions degree deleted dependent described describing descriptor details detected dev devdraw.c device diagnostics dictated dimensions directory disable disc discussion display displays distance distinction dp draw draw.h drawing drawn draws dst dstid dstr ellipse enable end0 end1 endings ends entries entry equivalent erroneous error errors errstr exist facilities failure fetched fields file files fill filled fillid filling fills flush font fontid fonts format formatted freed fully further graphics green highest horizontal id identified identifier identifiers ignore ignoring image image's imageid images immutable implementation include independent index indices initially inside insufficient integer integers interface interior internal intersecting introduce involving joining joins length letter level libmemdraw lines list load log logical low lowest macros maintain maintaining map mask maskid maskp max max.x max.y message messages method min min.x min.y mishandled moved multibyte necessary needs negative nibble non note object occur odd op opening operation operator outlining output outside overrides owned parameter parameters particular phi pixel pixels points polygon polygon's port portions private process processes protocol provides providing publicscreen purposes q.v r.min read reading recovered rectangle rectangles red refbackup reference refmesg refnone refresh refreshed remaining repainted repl replace replicate report reporting requests resolves resources response retrieve return returns rounded rule scr screen screenid screens sector segments self semiaxes send sent separately series server serves settings signed simultaneously smooth soft source soverd sp space spacing specifically specifies specify specifying square src srcid srcp stack storage store string strings subfonts sys text thick thickness translated transmitted treat type u.h uchar ulong uncompressed uncovered undefined upper ushort using values version vertical via void whatever wide width wind winding window windows write writing written yields draw 3/draw + accepted add additions address applied applies apply assume backup backups base behaviour bell bin bug byte canonical clearly cmd code coding commented conflict consisting context copies copy create created creates creation current dash data definitely developers diff diffs directory displays distribution don't dot email encouraging errors explain explaining explanation externally fd feature file files fix follow gratuitous guarantee guidelines host.dom how_to_contribute http identical input inspect intended labs labs.com larger letters list listed listing locally lowercase mail manual messages modified none nor note notes notification obvious original page patch patched patches pending pie plan plan9 plan9.bell please pointers possibly preparing print propose provide pull pwd pwd.c rationale rc reading rejected replaced replica report restore resubmit root run saved scripts sending sent shows source sources src standard stored style submission suggested supposed sys test tracking tree tree's underscore undo update user verbatim verify viewing visible welcome wiki works patch 1/patch + accepted add assumed attach attempts automatic automatically based bind block boot boots bound bugs builds byte bytes cat catenation clear closed compatibility complex component configuration configured contains control copying corresponds cp create created ctl data dd default defined definitions del determined dev devfs.c device devices dir directory discard disk disks drive driver drives echo error eventual fail failed fancy fd0disk fdisk file filename files fit format fossil fs fsconfig further goes gone handled i.e implicit indication initially inspired intended inter interleave interleaved interleaving introduce kernel's kfs length lengths load machine master mean mechanism message messages minimum mirror mirrored mirroring mirrors names offset optional partition partitioned partitioning partitions plan plan9 plan9.ini port prep prevent previously process provides raid reaches read reading reads recovery reduced removed removes request requests rest restored return reverse run save sd sdc0 sdc0parts sdc1 sdd0 sdd1 sector sequentially server services silently similarly simpler size slashes source space specifies src stating strings succeeds sys time transmit unit units values variable venti write writes writing fs 3/fs + accepted ahead apr april attempt calendar calendar.c cmd comparisons cron current date dates debugging default digits dy enables events file files flag formats forms friday insensitive lib lines listed mailed match monday monthly non output performs personal print printed processing reads recognized repeatable represent saturday source space src standard sys thereof third today's tomorrow's tuesday upcoming user usr wednesday weekly writes calendar 1/calendar + accepted algorithm auth authenticate authentication batteries binary box bugs button bytes calculator california carried challenge clumsy compared compares computed confirm confused connections consists copy corresponds current decimal delicate des described digit digital digits display displays easily ed eight encrypt encrypted encryption ent enter entered entering ep fill follow foreign generated greater hexadecimal instructions internally kept key letters looks lose machine match memory mistake mountain netcrypt numerical octal pathways performs pin plain plan pocket press pressing print printed prints procedure prompt prompts protected ranging recommended remote removed reprogram requires reset respond response return retyping routine securenet server stored string succession terminal text time times twice type unauthorized unix user using view wear wrong securenet 8/securenet + accepting acid allocating allows arg attempts author bugs bytes caller cancel cancellation chan channel char condition create creates debugging diagnostics error errors event execute exited files finds future handle include incoming incremented int interrupted lib libc.h library libworker management mullender nanoseconds none nsec nworker operation operations outsanding plan pointer programs provided queued race receive recvt recycled request requests requeue return returns reused sape send sendt servers signalling source src stack struct structure succeeded succeeds sys thread thread.h threads time timed timeouts timerdispatch timerrecall typedef typical u.h ulong uncaught version vlong void waiting worker worker.h workerdispatch wstack worker 2/worker + accepting adm auth behavior boot booting class cmd console correspond cpu cpurc cputype ctm decide env environment establishes incoming init init.c initialize initializes interactive invoked machine machine's namespace newns objtype option options password profile rc regardless requires run runs server shell source space src starts sys terminal termrc timezone user user's value variable variables init 8/init + accepts access address allow appliances arbitration boot boots bugs cec character clients closing cmd column communication connect connected connecting connection console continue control coraid cpu crash debugging default dev discovered discovery displayed dp drop due ea esc escape ether0 ether1 ethernet exit exits generated host implies integrated interface kernels keyboard late leftmost lost matching net network note option options packets persist plan post print printed probe probing proceed process prompt protocol qp quirks quit raw return run selection send server servers session setting share sharing shelf showing source sr src srv starts suboptimal sys sysname target timing trying type typing unless user cec 8/cec + accepts accomodate adds adjustment alignment allows alone amp annotations applying assuming automatically base basename behavior block bold bug cases ce cell center centered character characters closed closes closing clumsy cmd complicated condition conditional constructs contained continues convert creates current dangerous de default defined definition describes di disabled distinguish diversion diversions ds easier eight eliminates embed emit emits encountering eqn equations evaluate evaluates exactly explicitly extensions extra file files final fixed font footnote formatted formatting ft future gt handle handles handling height hello heuristic holds href html htmlroff id ie ihtml image img implementation implements inline input inputpipe insert inside intended intermediate internal interpreting interprets invoke invokes italic knowledge lack language lengths letters level link link.html linked longer lt macro maintains manual margin margins markers marks match matching mhtml mishandles move names necessary nesting nf nr nroff offset opened opening optionally output outside page paragraph paragraphs particular path pe pic picture pipe pipes png pngbase pngfile postscript previously printed printing prints produce produces properly ps raw redefine redefines redirection redirects referring register registers removing reopening repeat request requests run script setting shell sic similar size solution space spaces span src stack stop stops string style sub subscripts sup superscripts table tabs tag tags td text time tl tmac.html tr translated traps treats troff troff2png trying tt typesetting unimplemented unlike unlinked usual vertical vertically workarounds working wrapping write xx htmlroff 6/htmlroff + accepts account accounts address addresses allow attempt bind bits block blocked blocking blocks category check cidr classification closes cmd configuration contains control corresponds creates ctl debug debugging default delay deny described determine dial direct directories directory dirfstat entries entry expression expressions fail falls file files formats fstat gre i.e imap4d instance ip ipserv level lib list mail mapping match matched matches matching mountpoint mounts multimegabyte names network nodebug opening ournet output parse particular persistent pop3 process range ranges ratfs ratification ratify read regular reload remaining represent representation represents reread rereads scanmail semantics sends serves similar smtpd smtpd.conf.ext someone's source spam src starts stat string strings succeed succeeds sufficient sys trusted try turns typically whenever write ratfs 4/ratfs + accepts acrobat's adding adobe bad bin bitmap bugs cases competitive convert cure dcompatibilitylevel default direct distiller dlanguagelevel embedded emits file generation ghostscript gs hints input invoking level neither nor option options output page pdf pdf2ps pdfwrite postscript produces ps2pdf rc read similarly smaller sometimes source standard topostscript translation unaltered version write written ps2pdf 1/ps2pdf + accepts add addition affix allowing animation arrange arrow autogenerate background backgrounds bar bell bin bksp blocked blocking board's boards boxes buffer bugs bureaucratic button buttons chance check choose clear click clicking color column complete completed completely consider consulted contains control covered current cursor default degrees del delay deselect destination diagrams difficulty digit digits disable disappear display drawterm drop easy employees en eqn equations esc exit feature festoon file files fill filled finding finishes flip format full fully game games generate generates gibberish glenda goal gone guide happen hard hide hint holes http image images indicate inferring initially input interesting invented invokes involved japan jong juggle juggling key keyboard keys labs layout lets level levels lib library lines list load loaded logo looking lucent mahjongg mark match memo memorize memu menu message mm mode modes mouse move moves moving multi neighbouring non nonsensical nouns obscures official offline option optional options outlined outside partial partially pattern pebble pebbles percent pet pic pictures placement play points pops positions prefer presents pressing pretty print push pushed pushes pushing puzzle quit quits random reach red remove repeat report restart restarts resume resumed rotate row rows rules save saved score scores seehuhn.de select selected selecting selects sentences slow sokoban solution solve solving source space speed sprites square squares src startfile step sudoku suitable suspend switch sys tables tbl technologies theory.html thicker tile tiles tileset time tmp toggle tries troff try trying undo using utterly various varying view walk wall walls warped warping wasters win window ywusqomkigeca games 1/games + accepts adds adm agreed allow allows alone anywhere apop ask assumed attach attacks attribute auth authac authapop authas authchal authchap authcram authdom authenticate authenticating authentication authentications authenticator authenticators autherr authhr authid authmod authmschap authok authokvar authorize authpass authsrv authsrv.h authtc authtenticating authtp authtreq authts authvnc avoids becomes bit bootes boots byte bytes chal challenge changesecret chap chc check checksum choice chosen chs client client's clients common communicates communications concatenated confirm connect connecting connections cons considered considering consists constants contains context converted converts correct cpu created cuid data database databases decimal decrypt decrypts defined definitions dependent derive des describe described describes descriptions desired details determine dhcpd digit directly displayed dn dom domain ecb eight encrypt encrypted encryption ensures entry error establishing except execution exist exists expected exportfs external factotum fauth fields file files final fixed foreign freshness ftpd generates handheld hash hashes heavily hexadecimal hmac_md5 holds host host's hostid howard i.e id id's idc identical identically identifies identify identities idr ids ignore implements inclusion incorrect internet intervention ipserv issued kc kernel key keyed keys kn knowing knows ks learn length lib lines list listed lists lm longer machine machines maintain maintains manual map md5 memory message message's messages method microsoft's microsofts mixed ms names ndb negotiation netchlen netkey network non nonce nt nul null nullx num obtain obtaining obtains occasional ochapreply ok older omits omitted omschapreply ones operator owner p9any p9sk1 p9sk2 packet padded page pair pairs parenthesized particular passtokey passwd password passwordreq passwords pin pktid places plan pop3 possessing ppp pre prefix presence probe programs prompts property proto protocol protocols proves provides proving q.v queries radius ram random reads ready reboot receiving relationships relays remote repeat replay replies reply request requested requires requiring responds response responses responsibility responsible rest rid run running runs sape saved saving sechash secret secureid securenet semantics sending sends server server's servers services shared silently simply situations six size smullender space speak speaks ssh ssl stand standard starts statement string strings structure structures substituted suid sys talking terminal terminal's text therefore ticket ticketreq tickets time token tokens trickey try type types uid user user's users using utf valid validates value values variable variant verify version viewed vnc vncs volatile wait weak willing wish xxx xyzzy authsrv 6/authsrv + accepts adds append audio background bin block built bytes channel cleared clients cmd compulsory continue control controlled controlling cp current default descriptor eof error errstr etc extension extensions fields file files flag future games graphical implements index indicated indication indices instance interface interrupt issued item juke lines list maximum minimum mnt mount mountable mounted mountpoint mp3 mp3dec music necessary obtain occur occurs offset ogg omitted opening operations optional otrunc pac pac4dec parsed pause pcm play playctl played player playing playlist playlistfs playout plays playvol postname posts process puts quoted read reading reads receive recognized reference removed report reread resume return returns seek selected skip source specify src srv starts status stop stopping stops strings sys tokenize truncated user using usual value volume vorbisdec wait writes written playlistfs 7/playlistfs + accepts alarm algorithm allows alone alphanumeric alter ampersands apid appends applied arg artificial assigned assignment assignments associative asynchronously automatically backquote backslash becomes bin binaries binary bind binds bitwise blank blanks brace braces brackets bugs build built builtin caret carets cases cc cd cdpath character characters check circumstances class clear clone closed closing cmd cmp command's compare complemented complete completed completion component components composed compound comprising concatenated concatenates concatenation condition connected connects construction construction's constructions constructs contains continued control copy cpu creates ctrl current data debugging decorated default defines definition definitions delete deleted depends described descriptor descriptors dev device diagnostic dir directories directory directs discouraged disguised distributive document documents doesn't doing don't duff dup duration echo effective effects enclosed ens entirely entry env environment eof equal equivalent eval everybody exactly examined except exec executable execute executed executes executing execution exists exit exits explicitly favor fd fd0 fd1 file files finish flag flags floating fn follow fork full gets grouping handle hangup hi highest i.e id ifs implied indicate indirection initialization initialize initialized inline input insert inserted instance interactively intermediate internal internally interrupt interrupts interspersed intervening inverted invocation it's junk junk.c keyword keywords language letters level levels lexically lib linear lines list lists lowest lpd machine's manner marker marks match matched matches matching meanings mentioned message names needed neither nested net newconn newline nneesffm non none nor note notes notify null occurs omitted op opened opens operand operands operations operator option origin output outputs outstanding pair pairs pairwise parentheses parenthesis parenthesized path pathname pattern patterns permission pid pipe pipelines plan precedence preceding prefixed prefixing previously print printed priorities process process's processes profile prompt prompted puts qualifying questionable quits quotation quote quoted quotes rc rc's rcmain read reading reads receives receiving recognizes recursive redirected redirection redirections redirects referring remain remainder removes repeatedly replaced replaces requested required requires rescinded restored returns rfcenvg rfcfdg rfcnameg rfenvg rffdg rfnameg rfnomnt rfnoteg rfork run runs saved saving script scripts search searched semicolons sends sent separators serve shell shift sigalrm sigexit sigfpe sighup sigint sign signal simplest slash source space spaces splitting square src srdiilxepvv stand standard standing stands started starts stat status stem stem.c stop stored stream string strings structure subject subjected subscript subscripts subsequently subshell substituted substitution substitutions successful suggest suitable surrounded switch syntax sys tab tabs tcp terminal test text th therefore tighter time tmp tom trap type typed typing unary underscore unless unquoted user using usual utility valid value values variable variable's variables wait waited what's whatever whatis whenever writing yields rc 1/rc + accepts alpha auth.html auth.ms browser cd character characters cmd consisting conversion converts debugging default describes devutf doc entity eqn especially exhausted file files font format formats formatting generate html htmlroff index.html index.tr input invokes iuv language lib macro macros mapping mhtml minus ms names nbsp options output page paper pic plan plan9 process processed processing read reads register runes sequences source src standard suspicious sys tbl tcs tmac tmac.html troff typesetting unaltered unicode using usr utf utfmap viewing warnings web htmlroff 1/htmlroff + accepts alter args arguable arranges attached attachments attributes audio auto automatically base behaviour besides bin binary boot bugs built bus class cmd comms compilation compiled complements configuration configure configured connection control correspond creates csp csps daemon data dd debug debugging deciding default describing descriptor detachments detect dev device devices diagnostics directories disk diskargs driver driver's drivers dump ease embed embedded endpoint endpoints entry enumerates environment execute exercised exist extra file files flags fsdebug heavily hex hexadecimal hid hub hubs id identifying included includes increases increasing independently initialized interface intervention kb kbargs kbmain kernel keyboard level lines link linked links list locate location main matches matching mechanism mnt mount mounted names necessary ones opens operation option options overrides particular paths performed performs plan9.ini polling ports positive post posted print printer prints process proto protocol provide provided provides recognizes repeating representation representing requests rest restarted restrict scans section sections serial served setup source src srv started starts statically storage subclass supposed syntax sys systems tries universal usb usbd usbdb usbdctl usbdebug user using value values variables vendor verbosity via vid whenever writes usbd 4/usbd + accepts anchors assumed attempt base brackets bugs character charset cmd copies default dimensional directive displaying document entries fields file files filling flag flags fmt fmt.c fold formatted formatters geometry html htmlfmt idempotent image indent indenting input inserted isn't iso join leaves length lines meta option options output performs plain preserved print render short similar source space spaces square src standard suppresses synonym sys table tables tags text treats unchanged url urls fmt 1/fmt + access accessed accessing accompanied add allows alt alternate announce application applications args authenticated authentication bandwidth base bit breakable buffer buffer's buffers bugs cert certificate challenge characters click clients closed cmd color compose computing connect connected connecting connection connections connects control copyrect corner corre correctly cstv ctl ctrl default display displays drawterm encodings encryption error events except exchange expose extant factotum file format frame full graphical handles happens height hextile host http identifier inferno inferred input integer interactive interface internal key keyboard keypattern keys kills lack larger lightweight list loaded locations machine's map matching memory message mouse moves names net network option options ordered output owner password pattern persists pixel pixels pixfmt plan pop port presented pressed print private protocol provides quoted r3g3b2 r4g4b4 r5g6b5 raw receipt remote remotely represents request resizes response retyped rfb rre run running screen searches select send sending sent sequences served server server's serving sessions share shell shift shifted significantly simulating size smaller snarf source space src standard starts support supports sys systems takes tcp terminal tls typing unicode unused update upper user's using various verbose verification version viewer viewers virtual vnc vncs vncv weak whichever width window worse www.uk.research.att.com vnc 1/vnc + access accessed account actively added addition aid arbitrary ata attach attached attributes bind buggy bugs bytes capabilities capability cat cd closed cmd640 config configuration contained contains controller controllers convention counts created ctl ctlletter ctltype cu cylinder data default defined deleted delpart dependent detected dev device device's devices devsd.c diagnostic direct direction directory disable disabled disc discs dma dmactl dos driver drives e.g echo enable enabled enforced etc except execute exist fdisk file files fit follow geometry hc identify individually inquiry instance integer interface irq kenwood legacy letter level limit logical low luns machinery maintenance manipulate manufacturer maximum media merely message model multi naming nil non opened operating options partition partitions passes pci pi plan port prefixed prep prevented process processing programs purposes raw read reading remainder remaining removable rest retrieve returned returns rom rwm scan scsi scuzz sd sd00 sdc0 sdctl sdd0 sdev seconds sector sectors serves shows size source specifier split src ssdd0 standby starts status steps storage subdirectory supported supports swap sys systems text textual timer transfer type typically ucr unit units using via working write writing wtopctl yields sd 3/sd + access accessed address char current eleven file generated getpid id include letter letters libc libc.h mktemp mktemp.c port process replaced replaces returns source src sys template tried u.h unique mktemp 2/mktemp + access accessed attach bind broken bugs bytes channel communication communications connect connection converted data device devmnt.c directly distinct driver drivers error errors file files identify illegal involving issues kernel maximum message messages mnt mount mounting multiplexed multiplexes oriented port portion procedure process processes protocol provided read remote reply return returned returns separately served server servers session short size source space src string sys transferred translated translates transmitted user users validate various write mnt 3/mnt + access accessible accumulate ack acquire activates acts adding affect afterwards allow allows alphanumeric arg arranged arrow asynchronous asynchronously attached automatically background bar behave behaves behavior beyond bin bind bit bitsyload blanks block blocks blue border borders bottom bound brings bs buffer bugs button calling cases cd character characters choice circumstances claimed clear click clicking cmd collect color common communicating compiler's complete completion computation computing cons consctl console construct contains contiguous continuous continuously control controlling controls coordinates copies corner cpu create created creates cross current cursor cursor's cut dark default define del delete deleted deletes deleting delimited delimiter deliver delivered described determines dev diagnostic diagonally dir direction directly directories directory discussed display displays distinct document double dragging draw dx dy echoed edge edit edited editing editor enq entry environment eot eots erases error esc established establishes etb events eventually exactly except feature file files final finishes font forestall forward fragment frame front gathered generated geometry gets graphics gray gunsight hairline hangup happen hence hidden hide hold holding holds honor identifying imported imports indicate indicated indicates indication initializes initially input insert inside instance interactive interpretation interpreting interprets interrupt intervening item jumps kbdcmd key keyboard keys label layers lib limitation lines location mail maintained maintaining maintains manages manipulating matched maxx maxy measures mentioned menu menus messages minx miny missing mnt mode mount mouse mousing move moved moves multi nak names newline newlines newly non nonalphanumeric noscroll note notify null occasionally occur opening operating operation operations opposite option optional options ordinary output overlapping page pair partially particular paste pasting pending pid pipe pixels placement places plumb plumber plumbing pointing points portion preceding press pressed pressing prints process processes programs proof properties provide provided prudent punctuation puts putting raster raw rc reaches read reading reads real rearranged rectangle redirected refrains released releasing removes replace replaces request resize responsibility restore return reversing rio riowctl ruler run running runs sam screen script scroll scrolling scrolls section selected selection selects send sends sent served server serves services shell shows simplify size sizes snarf soh sometimes source space src srv standard starts startup stored string successfully supplying suppresses sweep sweeping sys systems takes terminal terminal's text therefore time toggles total treating triggers turns type typed typical typically typing underlying unioned units unlike unread upper user using usual value variable variety vertical vertically view visible wctl whereupon window window's windows wloc working written wsys rio 1/rio + access accessible acpv actually address aliasmail allow apop assume authenticate authenticated authenticating authentication bin box bugs certificate challenge clear client cmd connection connections contained contains conversation cram create created cs debug debugfile debugging default defaults dele deleted deletes deletion details disallowed domain enabled encrypted ending enforce env error examined expect faces file files filter flagged imap's imap.subscrib imap.subscribed imap4d imap4rev1 imp implements inbox initially input internet ip keyfs list listen log login mail mailbox mailboxes marshal md5 messages mlmgr ndb nedmail network non none option options output password passwords peeraddr plan policy pop3 programs protocol provided provides qer queried quit ratfs ratify rc read remote response rewrite rooted running scripts secret securenet send sends server server's servername servers sessions shadow site smtp smtpdomain source src ssl standard started subscribed support sync sys sysname tls tlscertfile trusted upas upasfs user user's username using verbose via write pop3 8/pop3 + access accessible acts avoid block blocks buf byte bytes cache caller's care client concurrent conn contains copied copy count create creates data deadlock decrements described directly directory documented dsize ensure entries entry error existing fewer file file.c files filling fills flushes freeing frees grows happen hash holds increments indicating int interface internal internally leaf length libventi locked locking locks loops manipulate manual memory mode moderate modes modify needed nil offset opens page parent pointer potentially provide psize read reads reference references regularly releases releasing removes reopen reopening requested responsibility return returned returns routines score server size sizes source specifying src stored structure sys taking th thread time tree trees type u32int uchar unlocked unwritten uvlong venti via vlong void vtblock vtcache vtdatatype vtdirtype vtentry vtfile vtfileblock vtfileblockscore vtfileclose vtfilecreate vtfilecreateroot vtfileflush vtfileflushbefore vtfilegetdirsize vtfilegetentry vtfilegetsize vtfileincref vtfilelock vtfilelock2 vtfileopen vtfileopenroot vtfileread vtfileremove vtfilesetdirsize vtfilesetentry vtfilesetsize vtfiletruncate vtfileunlock vtfilewrite vtordwr vtoread vtowrite vtscoresize writes writing written venti-file 2/venti-file + access account accounts address adm administrative allowing alternative auth authserver background chattier check checking client cmd connection cons create created date debugging default describes dev directory enables exist existing exists expiration fictitious file files hardware lib listens log logs machine mapping mode ndb net network obscure option owner password port prefer prompts protocol puts radius requests runs secstore secstored secuser server servername serves source specifies specify src status storage store supplements suppresses sys tcp tokens user userid username validation verbose verifier warns writing secstore 8/secstore + access account acme ad address addresses affect aliasmail allow altering announcements apop apops apoptls atomically attachment attributes authentication bcc becomes biff biffing bin bnps box bytes cc challenge choose cleartext closed cmd connect connects contains content conversation ctl date dead.letter default delegated delete deleted deleting delivery described digest direct directories directory disappeared disposition don't encrypted envelope es essentially exclusion exit faces factotum file filename files filetype filter final fourth fs full generates gleaned groups header headers host id imap imaps imaptls info initially initiating inline inreplyto intended interprets invoking item key l.mbox l.reading length level lines lists lock mail mailbox mailboxes mailfs mailtype marshal mbox mboxname mean message messages mime mimeheader minus mlmgr mntpoint mount mounts mutual names nauseam nedmail nice none numbered omitted one's opens optional options output overridden parse password path plaintext plumb plumber plumbing pop pops poptls port post posted presents printed profile proto protocol protocols provide qer raw rawbody rawheader rc reader readers reads received recipient recurse references removed renumbered replies reply replyto representing reread response rewrite rfc822 rio running runs script seemail send sender senders sends server sha1 shell source space specifies specifying src srv standard standards stands starts starttls startupasfs stls stored structure style subject suitable summary supported sys takes telnetting that's there's time tls type undecoded unixheader unless upas upasfs updated user user's username using whenever window written upasfs 4/upasfs + access account add adding administration alice arranged ascii attach attribute attributes automates aux avoid barney baud bignose bin bind bit bob bootes bootesctl boris broadcast broadcasts bugs carol cat channel client clients clog clog.c closes cmd complete computer con connect connected console consoledb consolefs consolefs.c consoles controlled cronly ctl database default defined detected dev device directory dirty ease edited eia0 eia1 eia205 enter entries equivalent excessive exist file files format fornax fornaxctl gid gid's glenda groups holds identify import inadvertently installation interfering lets level lib lines locally log logging ls machine machines member message mnt mntpt mount mounts names namespace ndb newlines notification opened openondemand opens output pair pairs permissions pipe posts prefixed presents procedure provide rate rc read readers reads remote represents restart returns running script sent serial server server's simultaneously source space specifies speed src srv stat support sys sysname ted therefore time typed typing uid uid's underlying user users using value values vlad whenever writes consolefs 4/consolefs + access accounts ad addition address adds adm administrative allows anywhere apop appends arbitrary arg asks attempts auth authenticate authenticated authentication authsrv bin biographical box bugs caphash challenge changeuser chosen cmd connect connection constructing conversation converts convkeys convkeys2 cpu cram current database databases debug debugging decrypt default department described disable displays domain e.g easy email enable enables encryption encrypts entered everything exec executes exists factotum file files forces foreign format fs guard.srv guess handles holding host hostowner http httppasswords id id's imap incoming input install installed installs it's kernels key keyfile keyfs keys keys.who lib list login machine maintain manipulates mappings match microsoft namespace ndb neither netkey netkeys.who network newns non none np nvram option output owner p9sk1 passwd password passwords performed permit plan pop3 port printnetkey prints progress prompt prompts protocol protocols query radius ram rc re readnvram realms rekeying relationships release remaining reports requesting requests response responses rfc1939 rfc2195 run script scripts secret securenet served server server's servers shell similar source speaksfor sponsor src standard started starts status stored stores sys tcp ticket twice unix user user's userid users using volatile vpn wants whenever works wrkey auth 8/auth + access accurate allows auth behaves bind boot clock clocks cons dev device devices devrtc.c file key machine's maintained necessarily neither non nvram permission provides ram reads real rtc server source src supports sys time volatile rtc 3/rtc + access acid acme active addenda adhere adm administration alias alpha appearance applications architecture arm assemble auth authentication aux auxiliary behave bin binaries bindings bins bit bitmap boot bootstrap bootstrapping box cfg channel cmd code collecting collection collections comments communication communications compile compiled composed configures connection connections cons console consoledb conventional conventions copy cpu cpurc cputype created cron cs ctime current data database databases debugging default defined dependent describing descriptors dev device devices directories directory display dist distribution's dns doc documentation documents domain draw dup easily eastern electronic env environment est.edt establish establishes etc executable executables exhaustive factotum fd file files floppy font formed fs generally grabrfc guide hershey hierarchy holders holding holds imported include independent init initialization installation intel interface internet intro ip isomorphic kernel keys kremvax level lib libraries list load loader log machine macros mail main maintains mammals manual mips mk mkfile mnt modified modules mount mounted mounts multiplexed namesakes namespace ndb net netkeys network networking newns none notably object objtype operating overriding page parser parts pieces plan points prefixes private proc process processes profile programs proper protocol provides pseudonyms ranging raster rc rcmain registry related remote requests reside rfc rio root run securenet selected server servers serves services serving shell simulations sky software source sources space sparc specific specifications src srv standard starts startup structure subdirectories supported sys systems tables tcp term terminal's terminals termrc time timezone tmp tools traversal traversing trees trivia troff udp union unioned unwritable user's users usr variables various vector version window wsys yacc yaccpar zone namespace 4/namespace + access acme add advised aes aescbc apop append auth authenticates authsrv automatically backup belonging bin bits block bugs cbc cd chaining cinv cipher ciphertext cleartext cmd confirm cons convenient copies copy copying crash created creates credentials ctl current dates decrypts default delete deleted deliberately descriptor detect dev directory disk dom echo edit editing editor ehg encrypted encrypts ephemeral except exits factotum feedback fetch file files final flush full getfile grabs hardware hashes hi i.e input insted intended invisible invokes ipso irrevocable key keypairs keys lengths list load loads location memory mentioned mistyping mnt mode modifed newly nvram ones operations option optionally options output packages particular password passwords pathname perform persistent plain private produces prompts proto provides providing putfile q.v ramfs rc read reads remote removed removes requested resident retrieves rijndael rmfile rooted running sam save saves says script secret secrets secstore secure send server sha1 similar simplify source specifying src standard startup store stored stores sys tcp text tmp token type updated user user's using verbose window workspace writes x.com secstore 1/secstore + access acname add addition address addresses allows ask authentication baud believe bugs bytes challenge chat chatfile client cmd communicate communicates communications compression concentrator configuration connection connections contains control conversation cpscdfu debugging default dev device dial differences dir directory disallow discovery don't dp drop e.g encapsulate encrypted eof error ether ether0 etherdir ethernet except execute expected factotum file forth fraction framing gre hdlc header initiates input inside insist interface internet invokes ip ipv4 key keyspec lack lines looking maximum missing mode modem modemcmd mounted mtu ndb necessary net netmntpt ok option options output packet packets pass password pattern pd ppp pppnetmntpt pppnetmtpt pppoe pppoe.c pptp pptpd pptpd.c primary proto protocol rate reads receive received relayed remote reponse response route run runs send sent serial server shuttle size source specific specifies specify src srvname stack standard stream string supplies supply supports sys takes tcp tcpdir terminate testing transfer transmitted tries tunnel tunneled type unit user using via wants window write ppp 8/ppp + access acquire afid aname aqid attach auth authenticate authentication authsrv bind boots client complete connection contains defined defining definition described desired device devices directory doing entry error establish established evaluates execute fauth fcall.h fid file fresh generated generates granting idea identifies intro introduction kernel knows machine message messages mount nofid pipe points presented previously protocol protocol's qid qtauth rattach rauth read remote requested require required rerror returned returns root select server server's serves size specifies tag tattach tauth transaction tree type u32int uname uninitialized user using usual validate validated version wish write written attach 5/attach + access actions actual addition affecting altered anyone append archives atime attach attempt attempted attempts attributes avoid bit bits break bugs byte bytes claims clients committed conditions consider consistency contains content convd2m conventional convert convm2d count create current data datum decide defined deny described dev devices dir directories directory dmappend dmdir dmexcl dmtmp don't draws easy echoed encoding endian entries entry epoch error establishing etc exactly except exclusive existing explicit extended fails fcall fid fields file file's files flags formatted fossil fsconfig fstat further fwstat generated gid gmt groups guarantee happen holding identification identified illegal implement included independent inquire inquires integers integral interpret intro jan kernel laid leader length limited lock machine maximum mean measured member message messages minutes mode modification modified modifying mtime muid names nightly non none note offset otrunc owner parent parse particular path permission permissions plain points properties providing qid.path qid.type qid.vers read reasonable reasons recent recently records reflects reject relaxed remove reply representing request requires returned root routines rstat rwstat seconds sent server server's servers significant similarly size stable stat status storage strings structure succeeds successful tag temporary text time timeout total touch transaction trigger truncation tstat twice twstat type uid unique unsigned unused user users value values variable vector version walk whenever write writes wstat yields stat 5/stat + access actions appended approach assumed bugs bytes chan channel char character characters closekeyboard closes combination complete connection cons consfd control ctl ctlfd ctlkeyboard delivers descriptors dev device draw driven environment event file frees graphics include initkeyboard int interface kc keyboard keyboard.h keyboardct keyboardctl keyboardctl.c keys kills lesser libc.h libdraw library message mode mouse msg multi naming nil opens passing pid proc processes programs raw read regular report returns rune runes sent shift slave source src string struct structure sys thread thread.h threaded threads time typedef typically u.h void wish writes keyboard 2/keyboard + access active activity allows anonymous append apply approximately ask attempt attempting attempts automatically avoid bind bugs cache cached caches cases clients clue cmd confuse connecting connection conventionally copies correspond default desired determined dials directories directory doesn't don't dqnt effects encryption entry equivalent export.lcs.mit.edu ext extension factotum fail fails fall falls feel file filenames files finally flush flush.ftpfs forces forcing format ftp ftp's ftpfs gateway guest handle hangup heuristics immediate implement import include interpret interpretation ip issue key keyspec length links list listings ls machine machines main matching mean meant memory messages metadata minutes mode mount mountpoint mounts mvs names necessary negotiate net netware nlst nop notices occur offer operating option options os pass passive password pattern plan9 port prompt proto protocol provide ps quiescent ramfs rare rarely re read remote remoteroot removing request required resorts response retrieve retrieved return root run seconds seeing send server servers sometimes source spaces specify specifying src startup steer succeed sun switches symbolic synthetic sys syst systems tar tcp terminate tls tmp tops transfer transferred try tso types unix unmount user user's using valid via visible vm vms walk walking windows_nt wordy writing you'll yourmachine yourname ftpfs 4/ftpfs + access activities actual approach array atomouse backing behaves bit bits blocking buffered button buttons cancels cfd chan channel char closemouse closes connected control create creates creating cursor cursor.h data default defined described descriptors dev device dimensions directly discarded display displayed draw draw.h drawgetrect drawn driven emenuhit environment erase event exceptions file flushimage format frees gen getrect getwindow graphics image include initdraw initmouse int interface item keyboard kills lasthit libc.h libdraw library lmr maintain manner mc mechanism menu menuhit message messages mfd millisecond motion mouse mouse.h mousectl mousectl.c mousectl.resizec moves moveto msec multi namesake naming nil null parallel parameter passing permitting pid press pressed proc processes programs progress provides pt rc read readmouse receipt reconnect recorded records rectangle red released removed reported representing requests resizec resized restoring returned returns rio routine running sam says scr screen sent setcursor showing slave source specifies spelled src stamp store struct structure succeeds successive sweep swept sys tells thread thread.h threaded threads time type typedef typically u.h ulong updates user using value variable visible void window wish writing xy mouse 2/mouse + access actual allow allowing base32 bind bugs bytes cmd directory encoding exists file files filtered getting hash lnfs lnfs.c longer longnames maintains mapping md5 mount mountpoint mounts moved names option options performed post posting presents process provide read real record renames server servers shame shortened source src srv srvname starts support sys underlying unlnfs unlnfs.c user users view working lnfs 4/lnfs + access add afile alter append ar ar.c architecture archive assumptions avoids behavior bugs character characters checking cmd combined concatenated constituent constituents cr create current date dates delete deleted directory drqtpmx duplicates elsewhere etc except explicitly extract extracted file files front gid groups id's inserts instance invalid key lib.a library list listed listing loaders ls main maintainer maintains meanings mentioned missing mode modification modified modifiers move moved names neither numeric object option optional optionally places plan posname precede predates preserve print purpose quadratic quick rebuilt replace required showing similar size somewhat source src sys table temporaries temporary times tmp twice uid update user valid verbose vuaibclo vxxxx whenever ar 1/ar + access add aid allocating alternative arg ask assigns aux auxiliary bind binding bits bitwise bound buf buffer buffers bufsize byte bytes calling care cases char checking checks clear clone cloned clunk clunks cmd cnt completion contains copied copies count counted counterpart counts creates customary data declared decorate described desirable dev device devices dfs diagnostics dir directly directories directory dirgen disk driver drivers ebadcall ebadctl ebadfid einuse eio eisopen embedded enotfound entry enum eperm errmax error etoosmall exist extern failure fake fid fids fields file files fill fits flag fs gen global handled handling hdrsize headers identified ids implement implementation implementing implements include index indicate initialized input int iterate kept lib libc.h library links locate looking maintains memory mnt mode modification mount mounts msgsize namesz needed nf nil offset omode ones onone onto opening operations outstanding path performs permission permits plenty plus pointer populated posts prepares processing protocol provides purpose qid qid.path qids quickly read reads reference referenced refers reflect release releases releasing remove request resources responsible rest return returned returns root server size source src srv started starts stat static string strings strongly struct structure successful suggested sys tailored takes termination thread.h times tracing tree trees trigger trivial typedef u.h unique update updated usb usb.h usbd usbdirfs usbdirread usbfs usbfs.aux usbfs.dev usbfs.h usbfs.name usbfs.qid usbfsadd usbfsdebug usbfsdel usbfsdirdump usbfsinit usbreadbuf user using uvlong valid value values various vlong void walk write usbfs 2/usbfs + access add alphabetically append behavior bin bits bytes character characters cmd code contains current default devices directory disables dlmnpqrstufqt dlmnqrstufqt don't e.g entry exclusive executable execute fields file files final flag format granted indicate indicated instance intro kbytes latest lc letter list listed listing lists ls ls.c mc mean mode modification modified names none option options output owner path permission permissions pipes plain print printed qid quoted rc read readable reader recently refers repeats requested reverse search size sort sorted source src stat subdevice sys temporary time type user version writable write writer ls 1/ls + access adding allocate allow blocks bugs byte bytes channel check checked checking choices cmd component connection consistency create creating data deciding default descriptor dev disk doesn't edition efficient erasing faster file files fit fossil fourth fs hierarchical holding inconsistent intro kfs kfs.local kfscmd larger level list longer maintains megabytes memory messages mkfs mount names nbuf nlocal offers options packet perm permission permissions placing plan post prep protocol q.v rb4096 rc read ream reamed rebuilding sd sdc0 serve server serves smaller sniffing source space src srv sys terminal third user versions whichever write kfs 4/kfs + access addition addns adm afd ai allocated amount amount_getkey aname apop applies arg args attribute auth auth.h auth_allocrpc auth_challenge auth_chuid auth_freeai auth_freechal auth_freerpc auth_getinfo auth_getkey auth_getuserpasswd auth_proxy auth_respond auth_response auth_rpc auth_userpasswd authenticate authenticated authenticating authentication authentications authgetkey authinfo authrpc authsrv bind build builds byte caller calling cap capability chal challenge chalstate chalstate.nresp chap char client communicating concert connection contains conversation converts copies cram create cuid current default definition described desired device diagnostics dom encryption environment erases error errstr executes expect factotum fails fauth_proxy fd fields file flag fmt format freed frees ftpd generated generic getkey global hashing holds id ids implementation include int interface interprets invoke invoking kept key keys length lib libauth libc.h library list login maxchlen maxnamelen message mnt mount mounted namespace nchal necessary newns nil noworld nresp ns nsecret nsfile null nuser obtained opens p9cr pair params passes passwd password perform performs permitted phase pointer posess primary print process prompting proper proto protocol protocols provide provided provides proxies queries reading reads recreates remote required requires resp response rest retrieves return returned returns role routine routines rpc sandboxed scratch secret sent server shared similary source space specify specifying sprint src storage string struct structure successful suid supply sys takes telnetd template typedef u.h uchar uint unlike user userbuf userinchal userpasswd users using variable variables verb verifies vnc void whenever wiping writing xxx yields auth 2/auth + access addr address adjacent alternate application architecture architectures assume automatic beieee80ftos beieeedftos beieeesftos beyond bio.h bit bits buf buffer bytes calculate calculated cany cases caused cdata char character characters cisc ciscframe cisctrace code combining common compiler conforming consistent contained contains context convert converted converts count counter counterparts crackhdr ctext current data debugger defined defining described describing desired diagnostics directly double endian entry equal error errstr executable executing execution exists extended extern fills float floating floats fn formatted former fp fpformat frame frames generic global header hexadecimal hold i.e ieeedftos ieeesftos image implement implementations include independent indicates indirectly instantiated int interpret invoked invoking iteration jump legitimate leieee80ftos leieeedftos leieeesftos length levels libc.h libmach link localaddr location low mach mach.h machdata machine main map meaningful mechanism memory model models multi names nearest negative non offset owning parameters passes pc pointed pointer pointers precision primarily printed process processing programs prototype provide receive recent recursive reference register registers reglist requiring resolving responsible resulting ret retrieval retrieve return returned returns rget rgetter risc riscframe risctrace rp search selecting setting significant somewhere source sp space specifying src stack stacks starts string structure structures successfully suitable supports symbol symbolic symoff sys table target threaded trace tracer type u.h ulong uniform unwind unwinding unwinds unwound valid value values var variable variables virtual void debugger 2/debugger + access addr adec ainc alpha amd64 architecture architectures arm atom atom.s atomic atomically availability bit cas casp casv compare conditional cpu decrements depends diagnostics don't earlier emulated failure iii implement implementation implements include increments instructions int kernel ldrex libc libc.h linked ll load loadlink lock locks lwar mips movlc movll nor nv operations ov pentium plan pointed powerpc processors return returns rmw sc semacquire source src store storecond strex stwccc success swap sys tas tas.s test thread u.h u64int ulong value values vlong void atom 2/atom + access addr arg arranges buf bytes calling cdfp char closeioproc common complete counting descriptors dial dir error execute executing fails fd fd0 fd1 file forks frees implement include instances int interrupts io iocall ioclose iodial iointerrupt ioopen ioproc ioread ioreadn iowrite libc.h library libthread list mallocz messages omode op parameter pointer primitive proc proccreate process processes procs programs provide read relay relaythread return returning returns routines run running similarly sizeof slave source sp src static struct sys sysfatal terminates thread thread.h threadcreate threaded threads time tot total typedef u.h unsafe va_arg va_list value variable void waits ioproc 2/ioproc + access address assumed authenticated based blocks cache cachesize channel checking clients cmd communication configured create created data debugging default descriptors dips disables environment error eventually exist file fingerprint groups hierarchy host interprets limited location member memory metaname mount mounted mounting mtpt ndb network options permission pipe plan post print read removed restrictions root server source src srv srvname standard stored sys vac vacfile vacfs variable venti via vacfs 4/vacfs + access adds allocated allows applies arg argpos args basic behave bits buf buffer buffered buffering buffers bytes c.i c.r cases char character characters chars checking clear closure code compared complex construction conversion current custom data declared decoded defined described describes descriptor design details diagnostics directive dofmt dorfmt double emit emitting enum errfmt error errors errstr essence except execution existing exits fails failure farg fatal fd fetch file finally finishes fixed flag flags flush fmt fmtcomma fmtfdflush fmtfdinit fmtflag fmtinstall fmtleft fmtlong fmtprec fmtprint fmtrune fmtrunestrcpy fmtsharp fmtshort fmtsign fmtspace fmtstrcpy fmtstrflush fmtstrinit fmtunsigned fmtvlong fmtvprint fmtwidth fmtzero fn format formats formatted formatters fp fprint freed generate generates handler honor identify include influences initialize initializes insofar install installation int interface internal internally interpretation items labeled libc libc.h library list ll main maintains message messages nbuf negative nfmt nil non num output outputting outside overflows overwritten parameters passes pointer pragma prec precision prepare primitive print printing prints process processed produce produced properly provide quits receive recorded recording records regardless relatives reset resize return returns routine routines run rune runefmtstrflush runefmtstrinit runes saved section size sizeof smaller sophisticated source src standard stop string struct structure style subsidiary succeeds success successful suite support sys truncate type typedef types typical u.h uchar ulong underlying unicode unimportant user users using utf va_arg va_end va_list va_start value values varargck variable verb verbs version vfprint void width workings write xfmt fmtinstall 2/fmtinstall + access advisable anyone authentication author bind bl bodet bugs cached channel checking clients communications cox creates creation debugging default descriptor device directory disk explicit ext2 ext2srv extended file files flag flags flushed format fsck full holding id implementation input inquiries instance instructs interprets irrespective laurent linux machine mapping memory miller mime.univ mode mount mounted numeric optional output ownership paris8.fr partition partitions passwd password permission pipe plan posts prevents provide raw read rebooted recommended reported required richard russ server simultaneously spec specification specify srv standard started status stopped strings superblock therefore tracked typically undefined unix unless unmounted updates user valid verbose vrs whenever write written ext2srv 4/ext2srv + access algorithm archive block blocks blocksize byte bytes cmd compact compressed compression copies default directory divided embeds file files flate header identifying label larger longer mkpaqfs mkpaqfs.c option paqfs range read source src structure sys tree using mkpaqfs 8/mkpaqfs + access algorithm archive block blocks blocksize byte cmd compact compressed compression copies default directory disk divided efficient file files larger longer mksacfs mksacfs.c sacfs source src structure sys tree using mksacfs 8/mksacfs + access alive bit bits build byte cd cmd collisions database default dist doesn't env exclusive file holding intro lib lock lock.c lockfile minute mode occurrences preventing prompt qid.type rc replica run runs scan scan.lock source sources.replica src stat sys trying waits writing lock 1/lock + access allow array associates bit black blue color colors convert data datum depth described display displays draw draw.h error errstr etc graphics green greyscale hardware hold images include int intensities length libc.h libdraw map mapped maximum offset operator pixel pixels positions provided readcolmap reads red retrieves return rgb setting source space src struct success sys treating typedef typically u.h ulong unsigned value writecolmap readcolmap 2/readcolmap + access allow asks attempts client clunk connections consider continue correct defined directory entry error fail fails fid fids file fs generated implementation messages opened parent permission permissions phase plan points possibly provide remain remove removing request rremove semantics server servers size tag tremove typically u9fs underlying unix usable write yield remove 5/remove + access alone assumes authenticate aux based blocks brzr byte channel clients cmd compact create created debugging default dev device directory divided dr erasable exactly file files flash flashfs forces fs interprets journal journalling larger longer member memory mkflashfs mounted mountpoint mounts nsect option output paqfs persistent plan post read sacfs sectors sectsize source src stand storage stored structure supplying sys turns typically flashfs 4/flashfs + access anti bugs bunny.bit cmd communal devices disable displayed files grabs image invoking keyboard lib locked mouse newline password plan run screen screenlock screenlock.c source src sys terminal terminals typing unlocked user's screenlock 8/screenlock + access apop at&t auth authentication authsrv avoid bell box bugs challenges characters clear cmd concern connections cons cpu domain encrypt encrypted establish external forestall greater guess hard identity imap invoker's journal ken laboratories length login machine mistakes morris netkey netkey.c network optional passwd passwd.c password passwords plan pop3 pp prompts readnvram require robert run secret secrets securenet security server services seven source specifies src substitute subverted sufficiently sys technical terminal terminals text thompson transmitting twice typed unix user username verify vol vpn passwd 1/passwd + access authentication boot bytes cache cached caches caching cfs cfsctl checks client clone cmd concerning connect connecting connection connections consistency data debugging default descriptors destination dev dial discards disk dknrs efficiency except exclusive file files gathering improve interposed intro kernel latencies level lines manually messages missing modem mount mounts mtpt netaddr network obey onto options partition queried read reformat remote root satisfied sdc0 server sides slow source src srv srvfile started statistics storing sys time unchanged user users walk cfs 4/cfs + access aux blocks byte cmd compact creates default dev directory divided exactly file files flash flashfs forces journalling larger longer memory mkflashfs mkflashfs.c nsect option paqfs sacfs sectors sectsize source src structure supplying sys typically mkflashfs 8/mkflashfs + access bell data databases describes distributed intro introduction involve laboratories manual outside plan proprietary section 0intro 7/0intro + accessed accuracy alternate announces aux boot clock cmd debugging default determined determines dial dir directory doesn't error file files frequency frnddlilg gmt gps gpsfs guess impotent indicate kept listen log logging missing nanoseconds netroot network ntp options os pcs print real reference requests rooted rtc run server source sources specifies src srv standard stands stratum synchronize synchronized synchronizes sys sysname time timeserver timesync timesync.c tmp tracking ts turns type udp windows timesync 8/timesync + accessed aefhnqstu allocated assumes binary blocks bytes cmd contained corresponds count counts current data default descend directories directory disk du du.c e.g factor file files format fractional gigabytes hierarchy includes kbytes looking messages missing modified multiplication notation option optionally options path paths prefix print printed printing prints qid quantized recursively scale scaled scientific sep sepg si size sizes source specify src storage suffixed suitable summary suppresses sys time times tmp tu units usage values via warning du 1/du + accessed allow bind boot contains dev device devroot.c directly env exception exec file files holders illegal initializing kernel level mostly names net net.alt port proc root source space src srv syntax sys tree root 3/root + accessed automatically cmd creating current default demand file generate intended mnt mntgen mntgen.c mount mounts option points post source src srv subdirectories supply sys systems mntgen 4/mntgen + accesses assure bank belongs bit bureau byte bytewise census char cia comes connected consecutive contains coordinates corner counted data degree degrees differences digitized earth's endian fields file files formats geological highres ii index indicate integers kept latdiff latitude lexicographically londiff longitude low map measured necessarily negative north ordered padding patch patches patchlatitude patchlongitude points portability positive printable radian range related segment segments short shorts signed sources southeast stands stored struct structs structures succeeding surface survey u.s union units values map 6/map + accessible add addition additional alias aspects attach authenticated authentication becomes bind bind.c binding boot bootstrap bound cache cached client cmd communications compile condition connection consisting constrains contains control convenient create created creation currency current data default definition device directories directory discussion doesn't dump effects entirely evaluation everything existing exit factotum fails file files flag fork happens henceforth hide intro july kernel keypattern keys lib libc.a library loaded machine message mips mk modification modify mount mount.c mounted none object opened operation option options original originally permission permit port possibly process processes read refer refers registry rendezvous replace requests retrieved root satisfy selects served servename server services silently skip source space spec src srv successful sys takes time translated trees undo undone union unmount unmount.c unmounted verified write yields bind 1/bind + accessible add addition adm allows appearance archaic ascii awk bdays birthdays bugs character cmd collating comm comma common comprises consists contains count database default designated designators discarded equivalent fields file file1 file2 files forms identical increasing input join join.c joined ken:feb layout leading leaving lines names omitting operator options output pair paired pairs posix print produce randomly recognized relational relations replace rest separation separator separators significant sort sorted source space spaces src standard string syntax sys tab tabs temp th tr unknown unpairable usage userids users join 1/join + accessible address architectures bugs build bus bytes char code continue data dealing define defined env environment error errors establishes except execution fault frame goto handler include int interim interrupts invoker jmp_buf jmp_bufs jmpbufdpc jmpbufpc jmpbufsp label leaves level libc libc.h longjmp low macros non note notejmp notejmp.c notify nstack objtype page pc recover restores returned returns routines saved saves setjmp setjmp.s setlabel sizeof source src stack stacks subroutine switch sys time trap u.h ulong uregs val value values void setjmp 2/setjmp + accessing additional affect affects allows alternatively assumes at&t attempts automatically auxiliary base basename bases batchmode becomes beginfig behavior bell binary bitmap bitmaps bitmask block book box btex column compatible construct contained control converts correct corresponds create cstr current debug debugging default defaults definitions describes detail details directly directories directory display distribution doc document documentstyle donald download downloaded drawing dump dumping dvips editor embedded encoded ensure environment epsf.tex epsfbox eqn errorstopmode etex examples.mp except exit experts explicitly expression extension extensions fast feature features figs figs.mp figure figures file filename files flag flags font fonts format forming generate generated graphs handling hobby implicitly included ini inimpost input interaction interprets invoked invoking jobname jobname.nnn knowledge knuth knuth's kpathsea kpsewhich labs language latex lib list loading macro macros makempx manual mechanism mem memname message messages metafont metafont's metapost mf mfinputs mfplain.mem mfplain.mp minipage mode modes mp mpedit mpictures mpinputs mpintro.tex mpost.pool mpout mpsupport mpxcommand names negative nnn nonstopmode online options original output overridden package packages path paths permits picture pictures pipeline plain plain.mem plain.mp postscript predigested pretend print process processing produce produces progname prologues ps psfile psfonts.map query read reads sample script scrollmode search searching section self shell similar simulates size source specifying standard stick support sys table tables template tex texmf texmfoutput text third trfonts.map troff troffmpx typesetting understands unless usage user's using utility values variable variables various vbox verbatimtex version via works mp 1pub/mp + accessing additional allocated arbitrary array arrow attach bits block blocking buf buffer buffered button buttons buttons&1 buttons&2 buttons&4 bytes calling channel char character characters checks chosen complete conflict connected connection cons continually converts corner corners count current cursor cursor.h data default described descriptor descriptors displayed displays draw draw.h drawn draws eatomouse ecankbd ecanmouse ecanread edrawgetrect egetrect einit ekbd ekeyboard emaxmsg emenuhit emouse emoveto enabled enum erase eread ereadmouse eresized error esetcursor establish estart estartfn etimer event event.h event.v events extern extra fails fd file filled fills final flag flush fn gen getrect getwindow global graphics hold holding id image include initdraw input int interface item items kbdc key keyboard keys lasthit length libc.h libdraw list looks maintain marking mask maximum mechanism menu menuhit message middle milliseconds mode mouse moves msec nil non none null numbered parameter plumb pointed pressed process processes programs progress prompts provide queue queued raw rc re read reads received rectangle red register released repeating resized resizing restores return returned returning returns rio routines rune running says scan screen selected selection showing similar soon source sources specifying src stamp started starts string strings struct structure submitted successive sweep swept sys takes textual thread threaded time timer triggered type typed u.h uchar ulong units unless unthreaded update updated user variable void waiting waits whenever window window's xy event 2/event + accident adaptation address adequate advantage advantages aids allocimage alpha applications artifacts avoids bit bits black blue buffers byte bytes caused cells channels check chosen cited cmap color colors common compatibility components computes concentrating consistency conspicuous constant contiguous continuous converted converts coordinates corrected covering created cube demonstrate den depths described design designed dice dicing differences display displays distribute divide draw duff e.g easy endian entries external extra factor fewer film fixed format formats former frame full fully gamma graphics green grey hue hues idea ignores images imperceptible increase index indexed initialization int intensities intensity interface latter leftmost libraries linear loops low maintain map mapping maps maximum multiplexing navigator nested netscape non ntsc's num odd opacity opaque ordering pack packed packing paper parts peculiar photographic physics pick picking picture pixel pixels plan plus portability porter premultiplied primary properly property purposes range reasonable reasons red red,green,blue reduce releases replicating represent representation represents require requires resolution response rest results rgb24 rgbv sample samples sampling scaled secondary selection sensitive setalpha setmaprgbv shade shades significant size space stored subcube subcubes subdivision subregions suggests suitable systems television tend th therefore tone tones transparent triple trivial uchar uniformly unintuitive usable value values various vga visual void whence color 6/color + accidents agree allocates anymore assumed ata base bear bios bioses bits char constraints control ctl ctlfd cylinders declares dependent descriptor descriptors device directory discover disk disk.c disk.h disks employs fat fd fields file filename files finds fit floppy formatting forming gather generic geometries geometry hard heads heuristics ibm include initialized int interface kept length libc.h libdisk looks measured messages modern namelen noctl offset offsets opendisk opened opens operating parses partition partition's partitioning partitions pc plain prefix prevent provide rdonly reading reads reality report resemblance resulting returned routines saved sd secs secsize sector sectors setting size source src stats store stored stores struct structure suffix supposed sys systems tables tfile tfloppy track tsd type typedef u.h vlong wfd works writing disk 2/disk + accompany bytes clients convention defined describing ename errmax error failing failure libc.h message messages replaces reply request rerror return size string successful tag terror transaction truncate error 5/error + accomplished allows angle animating ap arbitrary arc attention axis button buttons caller center circle conference controller curves diameter dimensions dragging draw.h endpoints event events examine expected geometry.h imagine include interaction interactive ken libgeometry midpoint mouse mousep multiplying nearest null orientation outside particular plane pointer points proceedings projected projecting qball qball's qball.c quaternion read reading rectangle redraw reflect restrict return rotation rotations routine screen shoemake siggraph smaller source space specifies sphere sphere's src sys triggered twice unconstrained unit update updated void qball 2/qball + account add added address addressable addresses aliasmail allow altering alternate append appended applied args att.xxxxxxxxxxx attachment attachments backwards binary bodies box cc characters cmd contains contiguous control create created current dead.letter default defaults delete deleted deletes deletion destination dir directories directory directry disposition doesn't don't ed edits entire eot equivalent es escape exclusion exit exiting expression faces file filename files filter fool format forward forwarded forwarding fs generated header headers here's hierarchical howard html implies included indicate individually input interrupt jmk l.mbox l.reading lines lock looks madeup.net mail mailbox mailfile mark marshal match matches mbox message messages mfile miles mime mixed mktemp mlmgr movement multipart mutual names ned nedmail noone northwest.htm northwest.html notice nr numbered omitted option optional options original particular path person persons pipeto plain plumbing possibility presotto print printing produced prompting provided purged quiting range read readers reading reception recipient recipient's regular relative remove reply resides restarting reverse rewrite rf rules run save saved saves search sender sendername session shell size smtp source specifies src standard starts stop stops stored string stripped structure structures subject subpart subparts summary synchronize sys ten text time tmp treat type undeleted unrooted upas upasfs user username using write xxx yourself yyy.net nedmail 1/nedmail + account address addresses ascii attempts authentication automatic baud behave bidirectionally bits break bsd bugs bytes carriage cat cdnrrstv character characters closed cmd combined communicate communication compatible computer con con's connect connecting connection connections connectivity connects consolefs consume control cooked copied copy copying cpu create dcrn debug debugging deepthought deprecated dev device dial dialing dials disables e.g echo ensues environment eof eqn error escape etr executes execution exit file file1 file2 files forces forestall hang hayes incoming input inseparably intended ip kilobyte kilobytes kremvax legitimate length listed logged login logs lp machine merely message misinterpretation mode modem ms net network networks newlines null obsolescent obsolete option options output packet paper parallel parity performing pipe pipeline plan post print printable printing processing programs progress prompt prompts protocol provided pulse pv quit rate receive received receiving redirect remote responses return returns rlogin rudimentary run runs rx rx.c screen send session shares shell shells sic signal similar size source specially src srv ssh stage standard standing strips supported suppresses svc sys target telco telnet telnet.c ten terminals that's toggle towards transfer translates transmitting troff trying typed user using utf verbose versa vice wait written xmodem xmr xms con 1/con + account addresses adds adm affect allow attempts auth authentication authsrv bad binary byte bytes changeuser cmd connect consecutive considered contains cpu creates creating current database databases date decrypt decrypts dedicated default delimited derived des described deskeylen directories directory disabled disables duplicate enabled enables encrypted encryption endian entries entry epoch error except expiration expire expired expiring failed file files holds host hours identifies increments initialized installed integer interface interpretation key keyfile keyfs keyfs.c keys keys.who level lines list log machine mail manipulating match mnt mntpt namelen names namespace netkeys netkeys.who network newline non np null nvram ok option password plan prior programs prompts providing purgatory ram reached reaches read reading reads record reflected removes removing renaming represents resets restrict return returns rooted rtc runs seconds secret securenet send sent separately server serves source src starts status stored string strings sys temporarily ten time tree user user's users using utf version volatile warn warning warning's warning.c warnings writing written keyfs 4/keyfs + account addresses adm auth biographic biographical changeuser characters contains cox creates department dept disrepair dmr email expire expiry fallen fields full holders key keyfs keys.who login mailed modifies notified postid read rob rsc rscox russell user warning warnings wide writes keys.who 6/keys.who + account aes algorithm alleged backwards blowfish buffer byte bytes cover cycle data decrypt des dlen dsa elgamal encrypt encryption entered forward generator include input int keeps length libc.h libsec libsec.h lost mp mp.h nbytes output prime pseudo rand random rc4 rc4back rc4skip rc4state retransmitted rivest's rsa run sechash seed setuprc4state skip slen source src structure sys track transmissions u.h uchar using void xor'd rc4 2/rc4 + accounts bin date dev files format rc running shows source sysname time timezone uptime uptime 1/uptime + accrued affects architectures behavior bits characteristics clear clears contains control controlled default define defined divide double efficiently enable equivalent exception exceptions execution extended fairly fcr floating fpainex fpainval fpaovfl fpaunfl fpazdiv fpinex fpinval fpovfl fppdbl fppext fppmask fppsgl fprmask fprninf fprnr fprpinf fprz fpunfl fpzdiv fsr getfcr getfcr.s getfsr gradual guaranteed halt hardware holds identify ieee include inexact infinity installing interface internal invalid libc libc.h machine machines macros mask mc68020 modes modify nearest negative objtype operation overflow pair portable positive precision provide pseudo register registers retrieve round rounded rounding routine routines selective setfcr setfsr source src status support sys towards traps u.h ulong underflow units value values vary void getfcr 2/getfcr + accumulate accumulated add append arbitrary box bracketed closes convenient current default defined definitions document emit encoded eqn fe file files footnotes format formatting fs header heading html htmlroff identical image input inside invoke invokes invoking lib lines listed loose macro macros margin marking mhtml ms notes opens output package packages pe percent pic pixels png print printed provides ps replace replaces running section sys tag tags tbl te text title tmac tmac.html transitional troff ts utf width mhtml 6/mhtml + accumulate accumulated arg arranges clock data dumps entries exec execution files finally fn histogram include int interrupt interrupts kernel libc libc.h measure pcs pid port process prof prof.out profile profile.c profiling profkernel profoff profsample proftime profuser recording sample sampling source src sys time total u.h user values void prof 2/prof + accumulate added address addresses append applied applies apply awk backslashes bearing bears beyond blank blanks branch buffering bugs chapter chapter1 chapter2 character characters cmd comment consists consume context convention copies copy counts created cumulatively current cycle cyclically decimal default delete deletes denoted distinct don't drop ed edited editing editor embedded equal es etc exactly except exchange execute executed execution expression file files flags formatted fuller global grep hide hold ignore inclusive input insert instance instances interactive label lengths lex lines looking manual manuscript matches matching mcmahon ms negation newline newlines non nroff occurrences omitted operation option options output overlapping pattern pipe print process processing programmer's protect quit range read reading recent regexp regular repeated replace replacement research rest rfile sam script sed sed.c segment select selected selects sfile source space spaces src standard stream string string1 string2 stripping style substitute substitutions suffixed suppresses sys tabs terminate test text thereafter transform unix unless volume wfile write sed 1/sed + accumulate ahead allocates append approximate arena arena.3 arena0 asynchronously bd buf buffer buffering bugs busy bytes cd cdfs circular cmd copies copy cp data dd default device disc drain dvd e.g ecp fairly file files fill iando initially input ireadsize kb kilobytes limited milliseconds mnt modest none ofile operations optical options output owritesize permitting pipe pipeline prevents process processes pump pump.c quickly rdarena read reading sharing size sleep sleepms slow source spin src standard sys time using venti via waiting wd write writes writing pump 1/pump + accumulate appended blocks buffer bugs bytes cmd continue copied copies copying counted counts custom data default deliver designated ell file flag follow fr further grows ignorant input lbc length limited lines measured nbytes nlines option options output posix print printing promulgated relative reverse rf sed signed source src standard syntax sys tail tail.c tails ten treasured utf watch tail 1/tail + accumulate arcs background bounding buffer cmd col color created current default double drawing erase factor file files fill filter foreground grade grades graphics higher input instructions interprets interspersed middle names newline newly options pause pen persists plot plot's plotting processing quality rectangle results rio screen source specify src standard sys typed various window write x0,y0,x1,y1 plot 1/plot + accumulated adjustments amount assumed attach baseline bottom boundingbox box bp break bugs can't center clockwise closed comment comments complex current default defaults define degrees delimiting described destined diagnostics dimensions disappear distance diversion document documents downward entire ep everything explicitly file fill filled fills flags frame freely goes height horizontal horizontally implicitly improper inch included inclusion incorrectly indent insert isn't justify label lacks length level low macro macros margin measuring missing move mpictures null occupied offset optionally options original outline packages page pi picture pictures positive postprocessor postscript prevents reached read replaced retrieve retrieved rotate scale select silently size source space started suffixed sweeps text there's trap troff vertical width xoffset yoffset mpictures 6/mpictures + accumulates active actual address adser algorithm allowing amount appended args assumed avoid c.xxxxxx character chunks cmd combination connect consist contains continue control copied copies create created creates cron cumulative d.xxxxxx data debugging default depends describing dev differ directory drained e.xxxxxx entire entry error etc exactly executing executions exists exits external failed failure fax file files fits flag flags folded forces hour hours identify incrementally input instance instructs kremvax leaving lib limit limits load mail mailed management meaningful memory message minutes mktemp modified names nfiles notification nprocs null older option output page parallel parallelism pass piling preceding prevents process processed processes processing progress qer queue queued queues regardless remotemail removed reply reprocessed reprocessing request requester requests retried retries retry return returns root runq secondary send slow source spaces specifies spooled src standard starts status subdir successful sweeping sweeps swept sys systems tag telco time times total trying upas user xxxxxx younger qer 8/qer + accurate allows amount amounts args average bugs caused clock cmd cons consists content data dbfile debugging default dev df display displaying dup e.g error exits fastest fd figures file files final flag fooled fresh gather headers incurred interposes involved iostats iostats.out level log ls measure message messages mounts names opens outside overhead plan poor printed process programs protocol purview rate rc read reads regular report reports resolution rpc section sections sent server shell slowest source src standard statistics summary sys terms time total traffic transactions transferred type user vary write writes written iostats 4/iostats + accurate approaching arc artificial ascension astro astronomical azimuth bopp bugs calculated celestial centers clock cmd comet conjunctions data date declination default degrees described difference distance dlpsatokm due earth earth's eclipses ecliptic elevation empirical english environment ephemeris estartab etc events file files format formula fractions gmt hale hours include includes input interesting interval involving kitchen latitude lib list longitude magnitude meters minutes missing modified moon needed north obj1 obj2 objects observation occultations option options orbital output outside positions presents print printed prompt read refer refers report reports reverts rotation satellites scat search searching seconds semidiameter sidereal sky slowing source speech src standard star steady stellar successive suitable sun synthesizers sys time times timezone timing universal upcoming usable variable astro 7/astro + achille actually am amsterdam.lcs.mit.edu aux bind cmd con connected create dd default directory entry file intent labs.com machine messages mit mntgen mode mount mounts net net.alt network options path plan9.bell port print protocol provide resources serves source space src ssh sshnet stub stub.c stubs sys sysname tcp tunneled union via whoami stub 8/stub + acid add allow alternate author awk bugs cmd compressing conventional create current db debug debugger debugging default directories disk entries errant file gone gs hung id images machine memory month mount mountpoint mounts mtpt nf non numeric option output owned page page.snap pid postscript print proc process processes psu recommended recreates requests rest restore return returns rewritable running save saved serve server snap snapfs snapshot snapshots source space specify src srv standard static storing string suppose sys terminal text time unimplemented user via viewing writes snap 4/snap + acid apply ascii bugs bytes characters cmd ctl data db del delete determined errstr exclusive executed fields files fixed follow fresh include integer invocation kernel length limited limiting nanoseconds non output overhead pc pid pointer printed printing proc process ratrace ratrace.c replacing return rules sensible shows source sp space src stop string sys syscalltrace text times trace tracing user value values ratrace 1/ratrace + acid apr baseline bin broken cmd created critical current db dead default display elapsed event examined exited fault files flag id idle kernel kill lingering moribund newlines ns page pageout paging performing print printed prints priorities proc process processes ps ps.c psu queue queueing rc ready real reclaimed reported resource resources run running scheding servicing size source spaces src started status stop stopped stopwait sys syscall time translated unnatural user waiting wake wakeme ps 1/ps + acme active advanced amount apm apm.c apm0 aux battery bin bind bios block brings bugs charge charging cmd contains control critical ctl default descriptions dev device directory disable display doing eia enable estimate event fields file files full guaranteed integral interface kernel lists low lpt management messages mnt mode modes mountpoint network nontrivial occurred parts pcmcia percent plan9.ini posted presents puts read reads remaining requires return seconds source src srv standby status storage string supported suspend sys textual time try unknown various verb verbs apm 8/apm + acme additions arriving arrows automatically behavior bin box button clear clicking cmd current deleted deletions determined directories directory directs display displays entries faces file files flag flags fs icon icons ih image incoming interface invokes lib listens log mail mailbox mailboxes maildir marshal mbox message messages middle mode monitors nedmail notified option organised particular person persons plumb plumbed plumber port portrait priority rc reacts read reader reads received removed representation rule running screen script scroll scrolls seemail sender sending showmail source src startup sys tells typical typically upas user user's using usr venerable visible vwhois watch window faces 1/faces + acme advance analysis appended behavior blank bugs caller char character complete complete.h completion control controlled diagnostics dir directory embryonic error errstr extend extended extension fields file filename files filled flag forward freecompletion frees full identifies implements include insert int libc.h libcomplete match matched names nfile nmatch null plain plumber pointer prefix progress reports represents resulting return returned returns rio slash source src string struct structure suffixed sys triggered typedef u.h uchar unambiguously uniquely unreadable value void complete 2/complete + acme attempt aux berlin.de bin binary chart charts cmd column columns comma control conversion count dashes debugging default defaults delim delimiter developer disable disables doc doc2ps doc2txt document documentation documents embedding emits enables excel excelfileformat.pdf extract extracting fat fields file file.doc file.xls files format formatting http included inside inter laola limit limits linking list microsoft microsoft's mnt ms msdn msexceltables mswordstrings mtpt non object ole olefs openoffice.org's option options output padding page pages parse performs pieces plumb pmh postscript presents printable processing qadnt quote quoting range ranges rc report.xls rpt.txt sc.openoffice.org scaled schwartz script send sheet sheets similar source space spreadsheet src standard stored stream string strings structures suppressed syntax sys tabular text textural truncate unmount user.cs.tu using version wdoc2txt width window worddocument workbook worksheet write xls2txt doc2txt 1/doc2txt + acme blanks cmd colon columns default ending file fit input lc ls mc mc.c multicolumn option positions pr print printed rio run separately source splits src sys window mc 1/mc + acos arc asin atan atan2 bugs caller checked cos cosine double garbage greater include intro libc libc.h magnitude meaningful port radian range return returns sin sine source src sys tan tangent trigonometric u.h value sin 2/sin + acquire actual actually affect allocate allocates allocimage allocscreen allocwindow analogous appearance apply arbitrary array background backing band border bottom bottomnwindows bottomwindow bugs builds cachechars calling chan channel check choice client clients color completely confusing connected coordinate coordinates coordination corner corresponds covered create created creates creation data deallocated define defining deletion delivered descriptor designed disappear discover discussed display draw draw.h drawing enum expected facilities fill finished flag freed freeimage freescreen fully gather geometry global graphics historic holding id image images include indented initdraw initialization initialize initially int integer internal leave libc.h libdraw library listed log logical management messages method methods move necessary needs newly nw obscuring operations origin originwindow owner paint parent particular permit pixel pointer profitably programs protect protected protects provides pt publicly publicscreen published pull pulls push pushes r.min recorded rectangle ref refbackup reference refmesg refnone refresh regular releases repainted require resides rio routine routines safety scr screen section separately share shown shuffling source specifying src stack stacking store struct structure sweeping sys takes temporary topnwindows topwindow translated turns typedef typically u.h ulong unaffected unless unlike unused upper usage val value view visible void window windows wp window 2/window + acquire atof bind buf bulletin channel channels char create data descriptor descriptors device devsrv.c directory drop entry error executing fd file fprint hello holding holds install int level myserv namedpipe owrite pipe port post process processes provides read receive received reference registered registry releases removing server service1 service2 services sizeof source src srv string strtoul suitable sys text write written srv 3/srv + actions actual attach client clunk clunked current entry error failed fid file forget generated indirectly informs longer message needed opened orclose points rclunk removed request returns reused server size tag tclunk unless valid walk clunk 5/clunk + actions address addresses alias append applied arg1 arg2 arriving bell blank box bundling com common composed concatenating consists continues convert dead.letter deliver delivered delivering depends deposit depth destination destinations dispose disposition ed entire error es event executing execution expanded expanding expands expression fields file follow formed id indicated indicates insensitive invoked ken labs labs.com lib lines list locally login loop machine mail mailbox match matched matches message net network output parenthesized pattern performed performs pipe plan9.bell postmaster presotto print provided qmail queuing rc recur recursion recursively reduce regexp regular remote replace replaced replacement returned rewrite rewriting rmail rob rule rules run runs script sender sent standing starts string strings style subpattern substring text th times translate transmitted type user valid rewrite 6/rewrite + actions arbitrary block brings bugs button center checkerboard cmd counting decrease default dictated digit display dragging easier freezes grid imposed increase indicate interactive interface key keyboard keys lens lens.c limit lower magnification magnified magnifier magnify menu mouse moves movie multiplexing pixel pixels presents pressed pressing refresh releasing rio rules screen showing snapshot source space src standing static sys toggles typing unit update upper using view window lens 1/lens + active activity adjacent affect affected average averaged axes axis battery buffer bugs button card choose cmd collected columns computed configured context control corner count decimal default details detected device disable display displayed displays disregard due enable error errors ether ether0 etherin,out etherin,out,err ethernet exceptions executing factor factors fault faults files floating flushes fraction fractions goes graph graphs hardware highest horizontal idle indicate interrupts intr labeled larger linear load logarithmic lookaside lower machine machine's machines markers matters maxima maximum mechanism mem memory menu midrange misses mouse multiplied multiprocessor names net operating option options origin packets page pages parameter percentage percentages plot plotted presents process processes processors range ready received receiver remaining remote represents rightmost rolling run running samples scale scaling seconds sent serves showing shown signal sleepsecs source space specific src statistics stats stats.c strength strong swap switches sys syscall sysstat time times tlb tlbmiss tlbpurge total translation transmitter twice unless updated upper valid value values various vertical visible wireless stats 8/stats + active added aligned allocate allocated allocation bin bin.h binalloc binfree bingrow block bp bytes calling chunks clr deallocation diagnostics extend freed grouped grow include int item items libbin libc.h locations malloc memory nil non null object op original osize pieces pointed pointer pointers provide remaining return returned returns routines size source src storage struct suitably sys type typedef u.h ulong undefined using valid value void bin 2/bin + active addr adds adm algorithm arp authentication aux bandt2 bind bit break brickdb bridge bridge0 bridging bugs cat client cmd compressed compression connection correspond ctl daemon database developed dr due echo encrypted encryption env establish establishes ether ether1 ethernet fashion files getuser hash hashes hill hmac host hosts i.e inside interfaces invoked invoker ipv4 ipv6 keydb limitations locally md5 mode mounted mtpt murray my.sec net net.alt network options ordinal owns pc plan port protocol rc4 re repeatedly research returned robin round runs sdp secret server source src started supply sys sysname systems terminate thwack traffic try tunnel udp user user's values vespine vespine2 via viaduct viaduct's viaducts bandt2 8/bandt2 + active adds appending applications applied behavior bugs clears client cmd consist convention copy cpu created creating default defined deleted deliver delivered delivery destination determined difficult directory discarded discards dispatches dispatching dynamically earlier edit edited editor elsewhere error examined examines exist file files fixed format include interprocess involve item level lib menu message messages messaging mnt mount mounted mounting neither newly none opened opening otrunc output plumb plumber plumbing plumbsrv port ports pre programmed programs published read reading reads receive receives returned rewrites rule rules run runs sam search send sender sent server services source space specification src srv statements sys term text traditional unique user usr write plumber 4/plumber + activities added address addresses algorithm annotates ar architecture architectures archives assembly automatically bare base bdata binary boot bss bugs character cmd code compilation compiler correspondence creates data db debugging decimal default defaults depend dependent divide dynamic dynld edata emulation enabled entries entry etc etext executable exits explicitly export exported ext file files format generate header hexadecimal image import imported included includes insert inserted instructions kl language letter lib libc.a libc.h libraries library linkage list listed load loaded loader loaders loading main mainp mbedded mention mentioned mips move multiply necessary needed needs nm object objtype octal option optional options output partial parties picked pike plan practice print produce prof profiling provided ql rarely read regular remaining repeatedly represents resolve restricts retired reversed rob rounded routines scan scanning search searching section segment sgi source specifies src starts startup strings strip supported suppress symbol symbols sys systems table tables text third time topological tracein traceout tracing type types typically undefined unix values vl 2l 1/2l + activities address addresses administration approved aux bad bell belongs bis_exports.pdf bugs cached compares consults countries databases defined department's designated determine ehime entries export files guys http ip ipok ipok.cache ipokfs ipv4 laboratories lib licensing list listed loaded lucent ok okay owner pre print queries range section supporting sys technologies terrorist various verify whois works www.bis.doc.gov ipok 8/ipok + actual actually agreed alg algorithms algoritms allocated anti assumed authenticating authentication base64 binary bind boundaries buffers bugs byte bytes channel clear clone configured connection connections contains control controlled correspond cryptoalgs ctl data decrypting des_40_cbc des_40_ecb des_56_cbc des_56_ecb descriptor device devssl.c dial digest digesting direction directions directory enables enabling encalgs encoded encrypting encryption equal established exchange existing fd file files filter greater handshake hash hashalgs hashing implementing included incoming interface kernel key layer lengths level list listen loaded longer md5 messages mode mutual net newly numbered opening optional options outgoing port presented preserves protocol provides providing rc4_128 rc4_256 rc4_40 read reading reads record remote replaced representing reserves responsible returned returns run secret secretin secretout secrets secure sha shared shown similarly smaller socket source space specify src ssl sslv2 stream string strings subdirectories supported sys tampering text time transmission truncated turns using write writes writing written ssl 3/ssl + actual addr address advantage allowing application args bin cat cert.pem cert.thumb certificate client cmd connection convention create creating crypt dials dyourdomain encrypted encryption establish excludedkeys exec exec'd factotum file files flag hash helper hold http imap imap.pem imap4d imaps input interact ip key krem kremvax kremvax:5 launching legacy lib limap4d listed listen listen1 listener log logfile logging mail mainly mosc moscvax network offset optionally output plain port private provide putting rc relays remote remotesys reverse rsa running script server service.auth sha1 source src ssl standard starts stunnel sys target tcp tcp993 thumbprint tls tlsclient tlsclient.c tlsclienttunnel tlssrv tlssrv.c tlssrvtunnel tools trustedkeys tunnels typical typically unix's usr vnc vncs vncv tlssrv 8/tlssrv + actual address affects allocated attach attached automatically bind bit boundary bytes check class continue control create created ctl data defined device devsegment.c directory dmdir echo equivalent error exist exit file files format hi ing length level lived longer megabyte memory message mkdir mnt mode mom opening ordwr page performed permissions port process processes properties provides reading remove representing reset reside retrieves returns rounded seg1 seg2 segattach segdetach segment segment's segments setting sharable sharing source src string sys ulong using va virtual writing yields segment 3/segment + actual adds adjusted al ar ar.h ar_hdr arch architecture archive archives arfmag armag automatically bits blank boundary bugs char combine compatibility constituent contains data date decimal define defined dependent described et except exclusive externally extra fields file files fmag format gid header include independently index inserted insertion layout length libraries library loaders locate low magic mainly manner member mod mode modification necessary nevertheless newline nm object octal padded padding permission plan presence produced provide provision read reflects sar_hdr sarmag searched size stat string struct structure symbols symdef text time uid unit unix unused verify written ar 6/ar + actual adjective admit affix agglutinated amspell aux backyard bin biology british brspell bugs cede check checker chemistry classes cmd common constructs coverage covered crew crewmember default derivations deroff don't english error errors excise expects favor file files follow formatting heuristics ignores imperfect input judgement judgment languages lib lightly list list's literally looks medicine member mention misspellings modeled modelled names noun options output particular perforce places policy preferred preprocessors print proper rc rejected rules sanctioned script shunned sizable sizeable source spell spelling spellings sprog src standard stem sys takes troff understands uneven unruly usage variants yard spell 1/spell + actual allocated alternate ansi appends arg array ascii binary bio blanks buf buffered bug bugs byte bytes char character characters commas complete consecutive contains control conversion conversions converted converts copied copies count custom decimal dependent deprecated described descriptor diagnostics difference digit digits directly distinctly doesn't double ensure error errstr etc except excess exhausted existence exits exponent fatal fd fetching file finally fit flag flags floating fmt fmtinstall format formats formatted formatting fprint fprintf fraction friends generate goal hexadecimal hh holds include indicated installed int integer interprets intro justification justified len length libc libc.h list main malloc maximal maximum mean message minimum missing msg negative neither non nor nul numeric objects obtained octal omitted output pad padded parameter places plain plus pointer points positive precision precludes print prints produces producing promoted quits reasons relatives remain removed replaced representative required responsibility resulting results return returned returns routines rune runefprint runeprint runes runeseprint runesmprint runesnprint runesprint runevseprint runevsmprint runevsnprint safe safety section seprint short shows sign significant similar simply size sized sizeof smallest smprint snprint sometimes source space spaces specification specifications sprint src standard storage stream string strings sys takes text transmitted type types u.h uintptr undefined unsigned upper usage user's using utf va_end va_list va_start value values variable variadic verb verbs vfprint vlong void vseprint vsmprint vsnprint width works write writes written wrong print 2/print + actual ask assuming bad bcprvz bits block blocksize bsd bugs bytes cached caching capable confirmation cons consecutive continues controllers copies copy copying cp cranky current data dd dealing decades deeper default defeat deliver dev devices diagnosing differences disk disks dup ecp encounters error errors fashion fast fcp file files groups handling hardware helpful indicate input intended issect limit locations lots mainly mark max maximum media missing operating options origin ossect output overlap permit pipe print printed prints progress quitting read reading reads reassuring reblock record reflects reports rereading retries reverse sector sectors seekable seeking seeks short size speed standard stir swizzle swizzling systems tape time times transfers troublesome verify written ecp 1/ecp + actually adjusted admit alternating alternation amount applied bi blanks bold br break bugs chapter closing column columns commentary constant declarations default denoted diagnostics direct displayed distance doesn't dot double dt e.g ee ens eq eqn equalize equations ex except explanation extra file files fit font fonts fool format handling hanging hp ib include indent indented indents input inserting interparagraph ip ir italic italicize join keywords lengths letters lib literal literals lower lp lr macros main manual margin marks move n.t.l naked names nested nofill non nroff output p.i page pages paragraph paragraphs parameters pd pp predefined preferred prevailing printed processing punctuation quote quotes rarely re reaching reg relative remembered request requests reset restore return ri rl roman rs secondary setting sh short six size sm sp ss string strings struct style subhead successive summary support suppress symbol sys tables tabs tag tbl text tf th there's tmac tmac.an tp trademark treatment troff ts type typeset units value values wide widows width xx yes man 6/man + actually advances append appended appends appropriately array bio block bugs char character characters check clears converted data deprecated described discarding discards eof error except fails fgetc fgets file fopen fputc fputs fread fseek fsetpos fwrite getc getchar gets guaranteed handle include indicated indicator input int intervening items itemsize libstdio macro mode newline nitems nonnegative null occurred occurs onto opened operation output overflow pointer positioning ptr push pushed pushes pushing putc putchar puts read reading reads receiving requests returned returning returns reverse rewind runes similar size source src stdin stdio stdio.h stdout stream streams string successful successive support sys takes type u.h ungetc unsigned utf value void write writes writing written fgetc 2/fgetc + actually affects amount append asks atomically bytes correspond count data directly directories directory entries entry equal error exactly fid file generate generated greater guaranteed identified illegal implementations include indicates integral iounit limit maximum member message messages non offset opened plus points pread produced pwrite read reading recorded records regardless reply reports request requested returned returns rread rwrite seek seeking size stat tag transfer transferred tread twrite value write writing written read 5/read + actually answers approximate arbitrarily arbitrary arctangent arithmetic array assignment assignments auto automatic automatically bc bc.y bclib bessel brackets break bugs calculation cdls cmd comments compile compute cosine dc debugging decimal declaration define definitions digits display enables enclosed executed exponential expression file files follow global hoc ibase include influences input interactive invokes language length letter level lexical lib library log main manner math mathematical names newlines null obase operands operations operator operators option optional output precision preprocessor print printed processor programs provides pushed quit quotes radix read reads remainder resembles results retained return scale semicolons sent sign significant simultaneously sine source sqrt square src standard stands statement statements suppresses syntax sys takes text unless value values variable variables via bc 1/bc + actually arbitrary bind bit bugs child clears configuration cons contains content continue contrast creates current devenv.c device directory ec env environment error everything exactly extent file files filling fork global groups host initially intention kernel level mistake names noticed offset owner parent plan9.ini port process processes rc reboot rfcenvg rfenvg rfork serves source split splits src sys that's value var1 var2 variable variable's variables writable write xxx yields env 3/env + adapted addition advertising allocates allow application appropriately array based bitsyload button capslock card character characters charater classifiers code compaq computer contains control copies copy copyright copyrighted corporation cs_digits cs_letters cs_punctuation ctrlshift curcharset current define definitions depressed digits distribute distribution documentation draw draw.h drawing drawn easy encoded encodes express fee fields file files flags graf graffiti graffiti.c granted graphical groups hereby identified implements implied include influenced initialized int intended keith key keyboard letter letters lib libc.h library libscribble microsystems mode modifies modify mouse non notice packard palmtop parameters pen pen_points permission pertaining points poly portions ppasize primary printable prior private prompter provided ps pt publicity puncshift punctuation purpose quick quickref.gif recognition recognize recognized recognizes reference representations reproduced returned returns rune scribble scribble.c scribble.h scribblealloc searched sell serves similarly software source specific src standalone storing stroke strokes struct structure suitability sun supporting switch sys tmpshift u.h upper using version void warranty written scribble 2/scribble + add added addition additions address addressfile aliasmail appended ar box bulk cmd comments consequence created creates deletions describes dev directing directories directory entries envelope error events exclamation faces fields file files filter hash header inserted key lines list list's listname lists log mail mailbox mailed mailing marshal membership message messages ml mlmgr mlowner nedmail notification null ones option options owner owner's pipeto precedence programs qer receive removal removals remove removed replies reply replyto represents requests rewrite send sent smtp source specifying src subscribe sys unmoderated unsubscribe upas upasfs updates user using mlmgr 1/mlmgr + add added allows amd analyzing annotation applied approximate approximation array ascii asynchronous automaton behaves bglmprsv blocked buffer büchi cbhmt channel channels chart checker choice claim cmd combination combined comments communication compatibility compilation compiled completes complicate computer concise concurrent consistency contains conventions correctness cpp creation current data declaration declared default defines described design desired detail details deterministic distributed dynamic earlier equivalent error events eventually except executable executed execution exercises.pdf exhaustive exits explicitly expressed fields file file.ps filename files final formula full g.j generate generated gettingstarted.pdf global gotos guarded guided hall hints holzmann http identically ieee includes input integer interactive intervention isdn language level linear listed logic logical loops lost ltl manual.pdf manuals meant message mode model modeling models networks nondeterministic object omitted online operator operators option options ordinarily output pan pan.c parameter partial pcc perform performs postscript pp prentice printf prints proceeds process processes produce produces promela promela's prompting protocols quoted quoting random reached read reads receive receiving reduction reference requirements requires restricted roadmap.pdf rules run scope se secure seed selection semantics send sent shell simulation simulations size software solve source space spaces specifically specification spin spinroot.com src standard statement statements step store stored strong structure suppress symbol syntax sys system's systems table target temporal text third time tool trail trans translate translates tutorial type types user validation value variable variables verbose verification verifier verifiers version vol wants warnings whatsnew.pdf write written spin 1/spin + add addison aho allows apply arbitrary argc argv arithmetic array assignable assignment associative atan2 attempt average awk blank blanks boolean botch braces break buffered bugs built capture cases character characters closes cmd column combination combinations combine comma commonly compensate concatenate concatenated concatenation conditional consist constant constants constituents continue control conversion conversions converting converts convfmt copes copy correctly cos count counted created current dealt default defined defines definition delete denote denoted directed echo entire environ environment equivalents error escapes except excess executed executes exit exp explicit exponentiation expr expression expressions fflush fields file filename files final finally flushed flushes fmt fnr foo format formats formatting fprintf fs getline global gsub i,j,k identical implementation inadequate index indicated initialized input int integer isbn isolated kernighan language length lines list literal literally log longer lower management match matched matches matchop mathematical maximum meanings memory mf missing mode names necessarily newline newlines nextfile nf non nr null numeric numerical occur occurrence occurrences occurs ofmt ofs omitted opened operators opposite option options ordinal ors output pairs parameters parenthesized pattern patterns performed permitted pipe pipes portion print printf prints processing prog progfile programming providing quoted rand random re read recognized record recursively reference refers regexp regular relational relop remaining replaced replacements rest resulting return returned returns rlength rs rstart rules run safe scalar scalars scanning scans scope sed seed semicolons separates separation separator settable shell simulate sin six size skip source space split splits sprintf sqrt srand src standard stands statement statements status stop storage str string string's strings sub subscripts subsep substitutes substr substring successful sum syntax sys tabs time tolower toupper translated truncates upper using usual utf value values var variable variables weinberger wesley worse awk 1/awk + add additional addr address analogous arranges begnning block byte caller calling char chattyventi client closes conn connection connections contains data debug debugging default described descriptors desirable diagnostics dial dials enabling error errors errstr established exchanges extern fields file flag fmt formatted frees future global hanging hangs include infd initializes int integers length libc.h library libventi message necessary negotiated network nil omit op outfd packet pointers prints proc proccreate procs protocol read reading reads receive received remote represents return returned returning returns routines rpcs run send sent server shuts sid source src standard started stored struct structure success sys thread threaded threads typedef typically u.h uid unverified user using variable venti venti.h version visible void vtconn vtdebug vtdial vtfcallpack vtfreeconn vthangup vtrecv vtrecvproc vtsend vtsendproc vtversion waiting writes writing written yield venti-conn 2/venti-conn + add addpt arithmetic canonicalized canonrect clips combinerect compares completely components construct contained cover data difference divpt draw.h dx dy eqpt eqrect equal extent geometrical graphics height include insetrect int libc.h libdraw macros max max.x max.y min min.x min.y mulpt overwrites pixels pointed points pt ptinrect rect rectaddpt rectangle rectangles rectclip rectinrect rectsubpt rectxrect return returns rp rpt share smallest source src sub subpt sufficient sum sys types u.h unchanged unequal value void width addpt 2/addpt + add angle arithmetic axis carries commutative complex component components componentwise composes convert cos cross designed divide dot double draw.h extension geometry.h imaginary include interpolate inverse length lerp libgeometry mat matrix mtoq multiplication multiplicative multiply negate non object operate ordinary orientation orientations points products proportional q.i q.j q.k q.r qadd qball qdiv qinv qlen qmid qmul qneg qsqrt qsub qtom quaternion quaternion.c quaternions qunit real relative return root rotation rotations routines rs rule rw sin slerp source space spherical sqrt square src standard struct subtract sys transforms typedef unit vector void vs x',y',z x,y,z quaternion 2/quaternion + add arena arena.0 arenafile arenaname arenapart arenas awk backup backup.example backups block blocks bugs byte can't cat clump clumpoffset cmd code connection contained copy data default dev directly entire error errors external external.media extracts file fileoffset finally generates host incrementally index list media minus needs network offset offsets option optional output partition pipe print prints processed qv rdarena read reading reinitialize sdc0 server server's servers shown size source specifies src srv standard starts stopped substitute sys track typically using venti venti2 verbose version wrapper wrarena writes writing venti-backup 8/venti-backup + add attr attribute attributes blanks cmd concatenation current data default destination directory dst file files formats input lib message mnt mount options plumb plumber plumbfile plumbing rules send sends showdata source src standard strings sys text type user usr wdir working write plumb 1/plumb + added adding allocated allows alternate ambiguity automatically avoid becomes blanks char character characters check compiler contains control copy created default don''t don't doquote doubled embedded evaluated flags fmt fmtquote.c format formatting freshly hello identical include includes indicated installed installs instance int libc libc.h malloc manipulate mechanism necessary needs needsrcquote nil non original output pointer port pragma print printed produce programs properties provided quote quote.c quoted quotefmtinstall quoterunestrdup quoterunestrfmt quotes quotestrdup quotestrfmt rc regardless removing return returned returns routines rune runestrcat source specify src standard statements strcat strdup string strings style surrounding sys type u.h unquoterunestrdup unquotestrdup using value variants versions void worry quote 2/quote + added addition address appending approximately archival archive archives backup based block blocks blocksize broken build building bytes cmd coalesced collection comparing configured consumption copy copying create creates creating data default described detected detecting directories directory duplicate environment equal error examining exclude exist existing expand expanded explicitly extract extracted extracting extracts file files fingerprint format generated hexadecimal host include increase incremental indicate input inserted kilobytes list listed listing lists match merge merged meta metadata metaname modification mqsv names ndb network note occurs oldvacfile operations optimization option options output performance plan print produce properties range reading reduce reduction relative repeated representation require resulting results root score server sha1 shares simply size source specifies src standard statistics storage stored storing string sys tctv time times transparently tree trees unchanged units unpacked unusual unvac user vac vac:64daefaecc4df4b5cb48a368b361ef56012a4f46 vacfile vacfs variable various venti verbose via write written vac 1/vac + added addition advance advances advancing allocate allocated allocation amount array ascii avoid avoided base basic begining beyond bio bio.h biobuf bounding bytes char character characters code constant converts copied copies copy copying count create define defined directly discard discarded doesn't double encountering eof equivalent error escape exposes extensible files filling finger fixed freed freeing frowned grow grown grows implementation include included int interaction keeps leading libc.h libstring lightly lines lock longer lower macros maintains manipulate mechanism memory multithreaded multithreading necessary needs newline nul null parsing performs pointer pointers points programs ptr quoted quotes read reading reads recursively reference released requested resets returned returns routines s_alloc s_append s_array s_clone s_copy s_error s_free s_getline s_grow s_incref s_len s_memappend s_nappend s_new s_newalloc s_parse s_putc s_read s_read_line s_reset s_restart s_terminate s_to_c s_tolower s_unique source space spaces specifying src stop string string's string.h strings struct structure sys tab tabs terminates token track tread type typedef u.h unique user using void won't write writes string 2/string + added addressable afterwards allocate allowing alongside appended application appropriately array assumes background backspaces bar beforehand beyond bord borders box button buttons bytes cachechars caller calling chaos character characters chars check clear closest col color colored colors cols components consistent contiguous control copy corner data deallocated defined defines deletes deletion delimited designed determine determines directly display displayed displays document draw draw.h drawn draws editable ensue entire entirely enum erase establish except fewer file fills fixed flag folded font frame frame.h frames frbox frcharofpt frclear frdelete frdrawsel frdrawsel0 freed frees frgetmouse frinit frinittick frinsert frptofchar frselect frselectpaint frsetrects frtick ft full generated geometrical geometry graphics handled helper highlighted hold holds htext image image's images include index indicated indicating initialize inserted inserts int interface internal intervals inverse involve larger lastlinefull level libc.h libframe library limit lines location longer lower maintain maintained maintenance manage managing max maxlines maxtab modified mouse mouse.h mousectl moved nalloc nbox nchars ncol necessary needs newlines nlines non nul null obscured occupy onscreen p'th paint pass permitting pixels plain pointer points portion positions prepares printed programs provided pt pt0 q.v range raster recreate rectangle redrawing redrawn region regular removed removes repaints replaced representing required resize resized return returns rio routine routines rune runes sam saved screen scroll section select selected selection separately session shape size solid source src stops string struct structure structures sufficient supports sys tab tabs taking terminal text thread.h tick tickback ticked times total tracks type typedef typical typically typing u.h ulong unchanged unless unnecessary upper user ushort value vertical visible void width window wish frame 2/frame + added advantage alphabetics ascii blanks block blocks bs buffer bytes cases catenate cbs character characters cmd conv conversion conversions convert copied copies copy copying core count cp dd dd.c default device diagnostics ebcdic ebcdic,ucase efficient error expected file files finished fixed forward full handled ibm ibs indicate input iseek latter lcase length lower magnetic map mapping multiplication noerror obs opens option options oseek output packing pad pair partial particularly physical preserve prints processing product quiet raw read record records reports seek sending short silences similar size sizes skip slightly source specify src standard stop structure style summary superseding swab swap sync sys tape trimmed trunc truncates truncation ucase unblock unspecified upper value variable written dd 1/dd + adding adds aux bin bracketed bugs ccitt character characters cmd conversion converts correct corresponds cputype data deal default descriptions determine dev device devutf directory dlcfilmnorxy dlcimnorxy dlm dpost drive dvipost executes exists faces fax file files font g3post generated generic gif gifpost handle header hpost image input interface job's jobs jpeg jpgpost lcinor lib list lp mappings noproc option options output owner p9bitpos p9bitpost page pair paper passes patches pdf pdfpost plan post postscript ppost preprocessors printer process processor processors programs provides rc responds reversal screen script smart source space src suite sys systems table tex text tr2post tray troff troff'ed type types unix untouched utf width window window's wsys lp 8/lp + adding advanced apm apm.c apm0 apmjump.s bind bios dev device driver enable enabled enables equals executes friendly intended interface interfaces level low management pc pcs plan9.ini presence presents read reading registers returned sign source src structure sys uniprocessor ureg user value writing written apm 3/apm + adding alter analogously appends array ascii assembly beyond bugs byte bytes char check cistrcmp cistrncmp cistrstr compares comparing comparison comparisons considered considers consist consists copied copies copy correctly definition dependent differences distinct distinctions entirely equal es1 exactly examines exists greater guarantees ignore ignores implementations include int integer keeps language length lexicographically libc libc.h machine malloc memory moves necessary none note null objtype obtained occur occurrence operates operations original outcome overflow overlapping pointed pointer port portable remains returned returns routines rune runestrcat segment separator signified source space spans src stopping strcat strchr strcmp strcpy strcspn strdup strecpy string strings strlen strncat strncmp strncpy strpbrk strrchr strspn strstr strtok substring sys text token tokens track truncating u.h unsigned utf varies writes written strcat 2/strcat + addition address addresses agents alias aliases aliasmail appends based box cmd compatibility dead.letter decision deliver delivery determines directly disposes error exactly execute expect faces file files filter fork full handling implies input lib lists log login mail mailaddr mailbox mailers marshal message mlmgr namefiles names nedmail option options personal pipe preparers prints protocol provide purely qer queue queues reads recipient recipient's refers remote reply report returns rewrite routing rules run send sender smtp smtpd source src standard suppresses sys text timestamp undeliverable unmailable upas upasfs user username via ways send 8/send + addition alpha altered anywhere arbitrary automatically ax bar bars bold braces bracket brackets bugs bx ccol ceiling center centering character characters cherry circumflex circumflexes clause cmd column comes commonly communicate complicated construction cos cpile customarily default define defined defines delim delimiters descriptions desired dest devutf diacritical digits display document dot dotdot double dyad edition embolden en enclosed entered eq eqn equation equations escapes etc existing fails fat file files filters floor font fonts fractions full gamma generally gfont globally greek grouping gsize guide hat height identical inf input int introduce italic justified justifies kernighan keywords lcol legal letters lh lib lim limits lined lines lineup log lower lpile macro manual mark marks mathematical mathematics matrices matrix necessary neither newlines nor numbering occur operators option optional ossanna output packages parens permits pile piles postscript prefix prepares preprocessor prime produced produces programmer's quote quotes rcol reads recognized redefined reduced replaced replacement represents research results roman roots rpile run shorthands sin size sizes source space spaces spacing speaking spelled sqrt square src standard strings sub subscripts successive sum sup superscripts sys tabs tbl tenth text thereafter tilde tildes token tokens troff tutf typeset typesetter typesetting unix untouched upper usage user's vec vertical vertically volume whenever xy yields eqn 1/eqn + addition alphabetic alternative awk bchillnsv buffer care character characters cmd confuse converse copied count counted default defined dev diagnostics discovered distinctions don't easy ed ell enclose entire error exit expression expressions file files folds grep headers ignore implementation include input interpretation letters lines literal lower lowest mark match matched matching metacharacters names newline non null occurs option options original output parsing pattern patternfile patterns precedence print printed produce quotes regexp regular rest return reverse safest sam search searches sed selected shell soon source specify src standard status substitute sys tagged tagging tags treat using write grep 1/grep + additional addr appended arena arenas assigned bcmem blockcachesize cachesize collection comments component components configuration consists constitute contains copied described descriptions disk disks enumerates file fmt fmtarenas fmtindex fmtisect formatted formatting fs holds httpaddr httpaddress icmem index indexcachesize indicated internally isect isect0 isect1 lines location main mem names optionally parameters particular partition queuewrites reside sample section sections server started tmp typically using variables various venti venti.conf ventiaddress venti.conf 6/venti.conf + additional alone archive assumes authenticate blocks byte cache cachesize channel checksum clients cmd communication compared compressed concatenated consist create created creation data date debugging default descriptors device disv embedded enables entire file files filesystem fingerprint flash integrity interprets location maximum member memory mesgsize message mkpaqfs mount mounted mounting mtpt option options output paq paqfile paqfs paqfs.c parsed persistent pipe plan post read rom sha1 size source src srvname stand stderr storage stored sufficient suppress sys typically various verify paqfs 4/paqfs + addr address altaddr attribute aux caller's carries checks cmd connection connections contains copies data dial dials directory entry ether file files finds forward forwarding ignoring incoming input link listen log logs mac machine machines messages ndb netdir network options output particular provides rejected relay restrict source src standard sys time trampok trampoline trampoline.c typically trampoline 8/trampoline + addr address announces automatically blocks care char claimed client clients cmd conn connected connection contains dangerous detail devnull devnull.c discards distinguish error execute executes framework frees fresh goodbye handled hello include initialized int interface internally libc.h libventi messages network packet packets ping programs protocol provide provided proxy read reads rejects representing req request requests response returned returning returns ro ro.c routines running rx rx.data send served server servers source src srv stored struct structure sync sys takes time transaction tx tx.data typedef u.h uid user using venti venti.h void vtconn vtfcall vtgetreq vtlisten vtreq vtrespond vtsrv vtsrvhello vtversion waits write writing written venti-server 2/venti-server + addr addresses automatic bin command's cron current default error exits failed mail mailcmd mails output rc run runs scripts source started status typically user using mailcmd 1/mailcmd + addr allocate allocated allocating allow altered applies arbitrarily arbitrary arglist atof bbuffered beof bfildes bflush bgetc bgetd bgetrune binit binits bio bio.h biobuf biobufhdr bits blanks blinelen boffset bopen bp bprint bputc bputrune brdline brdstr bread bseek bsize bterm buf buffer buffered bugs bungetc bungetrune bungetsize bvprint bwrite byte bytes cases char character characters charstod closed cost creates data declaration delim delimited delimiter descriptor descriptors diagnostics double error errstr examined except excluding exit exits fast fd file floating flushes format formatted freed full implement include independent initializes input int integer integers interchangeably interface issues length libbio libc.h longer low malloc maximum memory mode nbytes negative non nul nulldelim occur occurred offset opened opens oread output outputs overwritten owrite parameter pointer print processed read reading reads ready recent related reread return returned returns routine routines rune seek sidesteps size skipping source src standard stored stream string strings struct success successful sys tabs takes terminal type typedef types u.h uchar unlike user utf va_list value variadic vlong void won't write writing written yield bio 2/bio + address addressed bind bit bugs bus bytes circuit delivered dev device devices devtwsi.c directory file files integrated inter interface i⁲c level mode offset queued rate read reading received seeking serial serves setting slave source src supported sys transmitted twsi wire write writing written twsi 3/twsi + address addresses answer approved aux belong bugs caches consults countries deemed descriptor determine ehime exists file files ip ipok ipokfs ipv4 ls mnt mount mountable non ok option posts srv terrorist works ipokfs 4/ipokfs + address addresses appeared arrange articles automatically cmd core create currency current daemon dead.letter file files gets header invoked item items lib list mail mailed mails modify names news news.c newstime options particular post print printing prints read reading receive recent recorded regardless registering report select source src subscribers sys time news 1/news + address addresses ascii asterisk blank buffer bugs byte bytes characters cmd concatenates db decimal default don't dump dumps endian escape file files flush format formats groups hex hexadecimal identical input octal offset option options output padded pairs prefixed print printed printing properly repeating representations reverse sequences size sizes source src standard style styles swab sys telling unbuffered units various xd xd.c xd 1/xd + address addresses cmd connection connections databases default device disables errors files interface ip ipconfig listing looks mask mounted mtu names net netmtpt netstat netstat.c network option options packets port print prints proto protocol remote reports source src summarize symbolic sys translation user usual netstat 1/netstat + address adds bin bridges bus bv class code configuration described device english fields files ids index interrupt irq lib obtained option output pairs pci pnp print prints rc registers size source suppresses vendor pci 8/pci + address adm bin brickdb bridge bridging clients data doc ehg files findviaduct ip ipboot log owners prints rc source sys tunnelling user usr viaduct findviaduct 8/findviaduct + address allocated alters amongst arp aspects associate awaiting bind block bridge bridge's bridge0 bridges bugs byte bytes cache cacheflush carrying clear connection constant contains control count ctl data default delay delay0 delayn descriptor destination devbridge.c device directory disassociate doesn't don't e.g echo entries entry epoch ether ether0 ether1 ethernet ethernets expired expiry file files format forward hash hex inner interface interfaces ip ipv4 ipv6 limits log mac maximum medium messages microsecond mounted mtu net network newly numbered opening option optional outer owner ownhash packet packets parameters particular passing path path2 physical port prints read reading representing reserves returned returns seconds segment selects size source src statistics stats status string subdirectories subdirectory summary sys tcp tcpmss tcpv4 text time treat tunnel tunnels tuples type unbind understand valid write writing bridge 3/bridge + address aoe aoer10.txt aoesrv ata binary bridged bugs config configuration connected control customary data depends documents ether ethernet exported file frames header http initialize interfaces ip listen lost minor multiplier network option options override port ports protocol raw read repeated sdaoe security segment serve serves settings shelf size slot slots space specify string target unrouted unwise valid via wireless www.coraid.com aoesrv 8/aoesrv + address broadcast bytes default dial dialstr en.wikipedia.org ethernet http inserted intended interface ip ipv4 lan mac macaddr machine magic option optional packet parseether password prints protocol required route send sends sent six udp verbose wake wiki wol wol 8/wol + address bugs cmd connected data default directory display file files flag inaccurate includes names namespace net network ns ns.c output pid principle printed prints proc process produced ps rc reading recreate reformatting renamed replacing represent representation rewrites rewriting script source space src suppresses sys tcp ns 1/ns + addressed assuming assumption backup behavior block blocks breaks bugs checked clients cmd consults control copies copy dangerous data default denoting destination directories dsthost entire environment error errors exist exists exits expects fast files finds fir fmt full host indicate input introduction kilobytes mode numeric omitted option options output pointers printing prints programs reachable reaction read reading reads replaces resulting root run score server sha1 source src srchost standard storage sys time tree truncates try type unreadable vac vacfs variable venti vtroot works write writes writing venti 1/venti + addresses alias aliases aliasmail appending arg backslash cmd comment consulted continued domain expand expands expansion faces file files filter fromfiles include invoked items lib lines listed mail marshal mlmgr namefiles names nedmail option printed qer replaced rest rewrite rule searched send smtp source space src sys upas upasfs wide aliasmail 8/aliasmail + adds adelson algorithm allocated allow anonymous application's avl avl.h avlnext avlprev avltree avlwalk bal balance balancing binary bits calling cmp comparison created creation defined deleteavl diagnostics endwalk equal error exists freed frees greater handled include insertavl int intended key landis libavl libc.h lookupavl maintenance matches matching mathematics member memory mkavltree nearest negative neighbor newly nil node non none np object objects oldp organization parent pass pointer pointers points positive pp removes res return returning returns routines score search searchavl self source soviet src storage struct structure sys tree trees type typedef u.h uchar usage values velsky void vol vtscoresize walk avl 2/avl + adds adjacent algorithm appending archive automaticialy avd becoming bigger block broken bugs bunzip2 burrows bytes bz2 bzip2 category central cisttvd cmd compress compressed compression compromise computer contained convert converted converting created creates creating cttvd cv cvd data de debugging decompressed default deflate descriptive directories directory directory's encodes ends error expand extension extract extracted extracting extracts facto fails fall faulty file files gunzip gz gzip huffman hybrid ieee implementations implies interface invoking june lempel level list looks lower matching microsoft minimal mode modification modified names needed none oldest omit operating option options original output path performance places pp prints process produce programs read readable recent recognizes recursively removed removes resulting results reverses scheme seeking similar size smaller sorting source speed src standard streaming stripping subdirectories suffix synonym sys systems tables taking tar tar.bz2 tar.gz tbz tbz2 technique terry tgz time tuned uncompress uncompressed unix unzip vol welch wheeler widespread write zip zipfile ziv gzip 1/gzip + adjacent alice arg args array bob break char charles definition delimiter delimiters delims depends exactly except fields getfields gettokens handling include int libc libc.h manner maxargs multiflag non null places pointed pointers port quote quoted quotes rc related remain resulting returns similar software source src str strcat string strtok substrings sys tokenize tokenize.c u.h using utf value yields getfields 2/getfields + adjacent blanks bugs characters cmd comparing comparison compatible copies copy count defined duplicated fields file implies input lines neighbors non num output prefix print removed repeated repetition report selection skipped sort source space spaces src standard string succeeding sys tab tabs udc uniq uniq.c unique uniq 1/uniq + adjoint affine aligned allocated angle apex arbitrary arith3 aspect ax axes axial axis bottom calling can't centered central clipping coefficients cofactors contains coordinate coordinates copy corner creates creating cube cz data define described describing determinant difference directions discards displacement divides double draw.h dual dx dy equal equation euclidean eye factors fit fov frustum geometric geometry.h homogeneous ident identity implicit include increasing indicating infinity inside int inv inverse invertmat ixform libgeometry lower madj manipulate mapped maps matmul matmulr matrices matrix matrix's matrix.c max min minv modify move moved newly nominally non null origin outside pair parent persp perspective pixels plane planes point3 point3s pointed pointer pointing points popmat positive priori projective pushmat qrot quaternion radians ratio recomputing rectangle remaining represent representation represents rest returning returns root rot rotated rotates rotation routines save scale scales screen singular slop source space spaces src stack stored stores struct structure structures sys theta times tinv transform transformation transformations transformed transforms translates tree typedef unchanged unit vectors view viewed viewport viewport's void window window's xaxis xform xformplane xformpoint xformpointd yaxis zaxis matrix 2/matrix + adjust align aligned allbox alphabetic becomes bedminster bernards bernardsville block box center centered centering character cherry cmd column columns consisting contains continue continues copied current data decimal default delim delimiters describe describes doctype double doublebox draw draws edition enclose ens eqn equalize except expand extend fb fi file files font format formatted formatting gap genuine horizontal household households indented inferred input integer integers item items justify key keys lay length lesk letters lines linesize lower manual mean minimize modifiers nroff numeric obligatory optional options output parens pipeline pipes population pp preprocessor programmer's range reads recognize recognized relative remainder repeat replaced represent requests research row rows rule rules segments semicolon separately signed size source sp3 spacing span spanned specification src standard sys tab table tables tabs tb tbl te tenth text town troff ts twp type typed unix upper vertical vertically volume wide widest width widths xy tbl 1/tbl + adjust applied ascent attach bit bits bitwise bottom bugs but1 but2 button buttons cachechars cancel canceled char character character's click clicking cmd column complain coordinate copy covered create cross cursor default defined depth described desired digit display displayed displays edit edited edits encloses entire entry etc existing exit file files fit folded font fonts forms global graphics gunsight height hex hexadecimal holding image image's images includes indicated invert inverted iwidth leave lines mag magnification magnified magnify menu methods mode modified modify mouse move multi necessary negation obtain offset ones operation optionally original parameters performed physical pixel pixels portion portions presenting presents pressed pressing prompt prompts pushed quit read reads rectangle report representing reread resulting rio rune screen select selection shows smaller source src stored subfont subfont's sweep sweeping switch switching sys tables text textual tilde transfer tweak tweak's tweak.c type typed types typically typing unmagnified unreasonably unwritten val value values variety various vertical view views wide width window write written tweak 1/tweak + adjust bar bottom box boxes button controls convert corner crop current cursor derived displays dragging edge eight endpoint faces file format grabbing gray grid icon image imagine input jpeg jpg larger levels map mapped menu middle midsection mouse move mug output periphery picture plan plus.1 plus.jpg putting ramp reads restore save section selecting settings shown standard surrounded translates values version vertically width working write mug 1/mug + adjusted allow approximation assumed bin capability character characters cmd col comma consisting count cstr dasi default definitions deroff dest devices diablo dir directory doctype dpost driving edition emits emitting encoded encoding eqn equally exhausted file files final font format formats formatting full further generated grap halt handle horizontal hp hyterm image include independent input intermediate invoke kernighan lib lines linotron list loading lp macro manual mergenthaler minus mode model ms names needed nominal nroff option options ossanna output page pages paper pic plan post postscript prepare preprocessing print printable printer printers printing prior process processing processor produce produces programmer's programs proof range ranges rc rd read reduce register regular request research resolution results send settings simultaneous source spaced spacing speed src standard suitable sys tab tables tabs tbl teletype temporary tenth term terminal tex text textual thinkjet tmac tmp tpost troff trtmp tutf tutorial typesetter typesetting typewriter understood unicode unix user's using utf volume width widths xx troff 1/troff + adjusted alphabetic appended applying approximate arc ashed automatically backslash basic becomes blanks blue bo box brackets ca cdash center centered cf cfill character characters ci circle circular cl clockwise closely co color commas comments connected controlling coordinates corner counterclockwise csp current cyan data ddash de default define defined delimited designated device devices di disc display displayable dotd dott double draw drawing drawn draws dsp dx dy ed elliptical enclosed ending endpoint endpoints environment escaped exact exactly except executed extra faces fall fi file filename files fill filling filters fit floating format fr fraction frame fsp graph graphics green guided holes include inherits inner instruction instructions interface inverts invoke joining kblack leading letters levels li limit lines lower lsp magenta magnified marks mean midpoint move needed negative newline newlines nonsquare numeric output outside par parabola parabolic parameters passes pe pen plot plots plotting poi points pol polygon polygons positive preserve punctuation px1 px2 py1 py2 quadrant quote ra radius range re read red reduced remain repeated requires rest restore rm rmove run rv rvec sa save sb scale scaling screen separator settings short size solid sp spaces specifies specify spill spline square stream string strings style styles supported tabs tangent troff unity upper using utf valid vec vector vertex vertices x,y xc xg xm xn yc yellow yg ym yn plot 6/plot + adjusted awk bars chosen closing cmd color coordinates daily displayed dji dji&a dow draw draws exit expected factor file graph hget histogram histogram.c hoc hold http ichart.finance.yahoo.com index input interrupted january jones keeps maximum maxv menu minx,miny,maxx,maxy modulus nf operation option pi;i plot price print range reaches read reads rectangle scale scaling sin sine site source src standard statusbar sys table.csv?s title unless value wave window histogram 8/histogram + adjustments adm analog aug cdt clock clock.c cmd conversion convert copied ctime current date date.c default depends directory draws env environment epoch file files format gmt greenwich init january mean option optional options print real report seconds source src sys tables time timezone tue variable window date 1/date + adler adler32 algorithm allocates amount bit block blockcrc blocks buf buffer butes byte bytes calling char checksum complementation compress compressed compresses compressing compression compromise computation conditions converting converts count crc cryptic data debug debugging decompress defined deflate deflateblock deflateinit deflatezlib deflatezlibblock dsize dst error fail fewer files flate flate.h flatecorrupted flateerr flateinputfail flateinternal flatenomem flateok flateoutputfail getr gzip header higher include inclusive indicates indicating inflate inflateblock inflateinit inflatezlib inflatezlibblock initializes initially input int interface level levels libc.h libflate malloc memory message mkcrctab negative non ones operate output outputs poly polynomial post pre printable process produce produced rapid read requested retrieved return returned returning returns reverses routines rr seeing signaled similar smaller source src ssize standard succeed successful sys tab table time trailer u.h uchar ulong uncompressed update updates using valid value values void wr write writing written zip zlib flate 2/flate + adm adm.users aprvxu arch archive archived assuming block bytes cmd contains copied copies copy copying correspond created date dates default destination directories directory disk dist entire establish exist extracted fields file files format gid headers intermediate kfs kfscmd list missing mkext mkext.c mkfs mkfs.c modification mount mounted moved names newfs onto option options output owners pass path permissions prep print prints producing proto read reenable removed restores root rooted sd serve setting sizes source specifies src srv standard subdirectories suitable suppresses sys tar temporary times tree uid unpack unpacked unpacking unpacks update updated users valued write writes writing mkfs 8/mkfs + adm arbitrary attach characters comma console convention decimal defines disk duplicate excluding file format fossil fossilcons groups id identifier intro leader lines list maintain maintained member names negative older owned permanent plan printable private protected server servers stat strings structures text typically user users via write users 6/users + adm bin current everyone exiting looks machine non person prints process rc source users using whois who 1/who + administration connection describes device divided documents hardware interact intro introduction manual operation page recreate sections serial setup typically various 0intro 9/0intro + administration describes intro introduction invoked manual necessary programs routinely section user utility various 0intro 8/0intro + administrative automatic based bin boot boots boottime bring cfg compilation configuration cpu cpurc cpurc.local cputype daemons edited enable env environment execs executable execute executed exists file files init initialization installations invokes kernel listen machine mk mouse namespace network none nproc paragraph parallel pc processes rc rc.local read reflect root script scripts servers source specific srv suitable suppressed swapping sysname systems terminal termrc termrc.local time user value values variable vga cpurc 8/cpurc + administrative based behaves blocks cat cmd connected copies copy copying cp cp.c device diagnostics dir dircp directories directory disk distance equivalent except excludes existing exists faster fcp fcp.c file file1 file2 files gux id includes involved lines messages mode modified move moves mv mv.c names noticeably offset onto option original owner parallel plain preserved ramfs read refuse refuses rename renamed respect rm server servers source src stat stored sys systems tar time transfers user write cp 1/cp + advance bugs cmd decimal default effective equalize exponential floating format incr increments infinite integer integers leading lines loop max min near necessary nor notation option options padding painful print printed printing prints seq seq.c sequences source src style surveys sys val value values widths seq 1/seq + aes aid algorithm allocated asn1 asn1dump asn1torsapriv bell beyond binary bit blowfish caller calling cert certificate certificate's certificates certlen chains char character check checks cn computing conventionally conventions convert converting converts copy creates crt data dates dec64 decoded decodepem decodes decryption decrypts default der des distinguished dk dns dsa ed ek elen elgamal encrypting encryption ending enhanced eric error exp exponent fingerprint format formatted generated getfields host include int issuer key keypair keys kp kq labs latter len length libc.h libsec libsec.h lucent mail malloc miller mod modulus mp mp.h mpint ncert new_s newly nil nj nlen nname npriv nrep object ou output owner pem pk precomputed primality prime prints priv privacy private provided pub publishes quoting rabin rand rc4 repetitions residues returned returns rounds routine routines rsa rsaalloc rsadecrypt rsaencrypt rsafree rsagen rsapriv rsaprivalloc rsaprivfree rsaprivtopub rsapub rsapuballoc rsapubfree run sechash section self sent sha1 signature signed source src st standard step storage stored string struct structure subj subject successful sys table takes test tokenize trusted type u.h uchar ulong undefined user userid using valid validity values verification void x509gen x509req x509torsapub x509verify rsa 2/rsa + aes algorithm allocated alpha approved blowfish copied copy created decryption des digital divides dsa dsagen dsaprimes dsapriv dsaprivalloc dsaprivfree dsaprivtopub dsapub dsapuballoc dsapubfree dsasig dsasigalloc dsasigfree dsasign dsaverify generated generator include int key keys libc.h libsec libsec.h manage message mod modulus mp mp.h mpint newly nil nist opub owner prime private provided pub publishes rand rc4 returns routines rsa sechash secret sig signature signatures signs source src storage struct sys u.h using valid verifying void yielding dsa 2/dsa + aes algorithm allocated alpha bit blowfish copy data decryption decrypts default des dsa egdecrypt egencrypt eggen egpriv egprivalloc egprivfree egprivtopub egpub egpuballoc egpubfree egsig egsigalloc egsigfree egsign egverify elgamal encrypting encryption generated generator include int key keys latter length libc.h libsec libsec.h manage message miller mod modulus mp mp.h mpint newly nlen nrep owner primality prime private provided pub publishes rabin rand rc4 repetitions returns rounds routines rsa run sechash secret sent sig signature signs source src storage struct sys takes test u.h using valid void yielding elgamal 2/elgamal + aes bfcbcdecrypt bfcbcencrypt bfecbdecrypt bfecbencrypt bfstate bits block blowfish bruce buffer bytes cbc cipher data decryption des dsa ecb eight elgamal encryption include initialization int ivec key keybytes keys len length libc.h libsec libsec.h modes mp mp.h nil padding prime rand rc4 rsa schneier's sechash setupbfstate size source src structure supported supports symmetric sys takes u.h uchar unsupported variable vector void zeroes blowfish 2/blowfish + aexception arg author becomes bracketed bracketing bugs caught chan char clears code construct context contexts control customer deep diagnostics dynamic err error error.h except exception exceptions excerpt fmt fmterror format func handle handled handling include innermost int kernel larger levels libc.h library malloc mechanism memory modelled mullender nested nexterror non occurs plan poperror prepares previously print programs provide raied raise raised recvp reqfree return returns sape sendp silenterror spcified stack standard static string takes thread.h threaded transfers try u.h user using void waserror worker workerthreads error 2/error + affect assumed binary blanks character cmd collating compare comparison comparisons comprises consults decimal default df dfnixt dfnt diagnostics dictionary digits directory entire equal exact exactly exit file files fold grep input interactive key letters lib lines list look.c lower match matches minus missing numeric opened optional options participate print prints recognized search sign sort sorted source src standard status string strings sys tab tabs takes terminates upper look 1/look + affect attach bind bugs cat cmd cons continuous data date delivered dev device devices direction doesn't echo edt eof established exit exits file files filter filters flag hello insert intended interpose interposes level managed mode model mouse oct opened opens option ordwr pair peculiar pipefile pipefile.c pipes plain process programs rc read repaired rewritten run simulate simulated source space specify src subsequently sys terminal thu tr twice unaffected unusable user using written pipefile 1/pipefile + affected applied applies associate assumes bind carries chdir client constant create current descend despite difference directory discussion dot elementwise entry equal equivalent evaluate exec existing failed fcall fid file files final full generated greater hierarchy identified illegal implementation implicit implied imposes index intro legal limit locally maximum maxwelem message messages mount names newfid nwname nwqid obvious opened packed parent path permission points preceding proposed protocol qid qids reached remove represent represents request requested rerror rest restriction restrictions results return returned root rwalk search server servers session simplify sixteen size stat succeed successful successfully successive tag therefore transmitted traversing twalk unaffected unless unmount user using valid value visited walk walked walking walks wishes wname wstat walk 5/walk + affixes basename basename.c cmd component contains deletes directory ending file final newline option output prefix printed prints slash source src standard string strip suffix sys basename 1/basename + agvsbg8gd29ybgqk applications auth base binary certificates cmd common commonly data decode decoded describing echo encode encoded encodes encoding enhanced extracts file files format greeting hello input labels lines mail notably originally output pem pemdecode pemencode plan privacy rsa section source src standard string sys textual tls writes pem 8/pem + alef apparent arabic archive armenian ascii assembler attempt audio bengali binary blocks box bugs character chinese classification classify cmd code compressed content cpio cyrillic decides describing determine devanagari device devices directory dvi encrypted english executable extended fails fax file file.c files filled flag font format georgian gif greek gujarati gurmukhi hebrew holding image include input japanese kannada korean language lao latin looks mail malayalam mime mistakes object oriya output outputs pac performed performs plan postscript purpose rc script series sh source specification src standard subfont subtype symbol sys table tamil telugu tests tex text thai tibetan troff type types unicode utf various file 1/file + algorithm algorithms algs allows analogue architecture args auth auth_proxy authentication authenticator authsrv aware bin bindings binds bound bugs built challenge clear cmd comes comprise connecting connection cons control cpu cpu.c cputype current default dependent details dev directory domain encrypt encryption environment error except executed exits exported exportfs fast file files flag goes hash hashing host id input interaction invoked invoking key keyboard keypattern keys lib locations log machine mechanism mechanisms method mnt mounted mounts netkey objtype older option output passwd paths pattern patternfile plan possibilities pre profile protection protocol quoted rc rc4_256 reflect reflected remainder remote required resources response restrict rio root run running selected server server's servers sha1 shell similar simulates source space specifies specify src ssl standard starts sys talk tcp17010 term terminal type user using usr variable variables version versions via wants window working cpu 1/cpu + algorithm algorithms bad bit bits blocks byte calculates checksum cmd cmp communicated computes count data default described determine digest digit file files fips hash hex hexadecimal inc input institute length machines md5 md5sum md5sum.c message nist option options print prints pub quick rfc1321 rsa sechash secure security sha1 sha1sum sha1sum.c sha2 source spots src standard standards sum sum.c summed summing supported sys technology transmission typically v's validate values wc sum 1/sum + algorithm array ascii auth.h authentication binary block broken buffer bugs byte bytes copied data decimal decrypt decrypted decryption defined des deskeylen diagnostics digit digits encrypt encrypted encryption encrypts fail fails fewer fill formatted full hexadecimal implementation include int invalid inverse key len libc libc.h longer method netcrypt numeric perform performs points port preceding prefixed remain remaining repeated return routines securenet source src string sys u.h unencrypted unsuitable usual value void encrypt 2/encrypt + algorithms aspect bit bugs cmd compressed correct crop decimated default described dimension exist faster file format iconv image implementation input interpolated kaiser options original output percent percentage picture pictures pixel pixels plan preserve produces r8g8b8 ratio reduce resample resample.c resampled resamples scaled sign size source specifies src standard suffixed sys unadorned uncompress using value window resample 1/resample + aligning apply balance blanks cat character characters cmd column columns date default double ensure feeds file files headed header input length lines listing lp margin missing multi necessary numeric offset option options output pad page pages positions pr pr.c print printed printers printing prints produce produces replace reset sequences sided simultaneously source space spaces src standard stops sys tab tabs text trailer using width pr 1/pr + alignment allows backspaces bfx bugs can't characters col column converts emits esc escaped expunge feature feed feeds file filter fine format full handle lines ms non nroff option output overlays overrides overstruck paginate pile pr printing produced pure remove removes reverse space tables tabs tbl typewriters understands vt col 1/col + allocate allocated allocators block bytes char checking error failure freed include int libc.h libventi longer malloc mem memory message needed noted permanently perror pointer print ptr realloc return returning returns routines size source src strdup sys sysfatal u.h venti venti.h void vtbrk vtfree vtmalloc vtmallocz vtrealloc vtstrdup venti-mem 2/venti-mem + allocated allocates appending appends avoid beyond block blocks buf buffers bytes calling chain compares completely computes contained contiguous contiguously copied copies copy creates data deletes described diagnostics e.g entire error errors except exceptions filled foreign fragment fragments freed frees hash helps include initialized initializes inputs inserts int integers internal invalid io iochunk larger length libc.h libventi longer memcmp memory messages necessary needed negative network nil nio offset offsets output packet packetalloc packetappend packetasize packetcmp packetconcat packetconsume packetcopy packetdup packetforeign packetfragments packetfree packetheader packetpeek packetprefix packets packetsha1 packetsize packetsplit packetstats packettrailer packettrim pointed pointer pointers points print prints removed removes representation requested requests return returned returning returns run sections sha1 source src standard statistics storage stored storing structures success sys sysfatal time total u.h uchar uint unnecessary unused values venti venti.h void venti-packet 2/venti-packet + allocated allocimage allocsubfont allows alone analogous application applications approximately arrangement array ascenders ascent ascii bit bitmap briefly cache cachechars cached caching calling cfname char character characters class comes components comprises constructs contains convention default depth descenders described describes descriptions descriptor device diagnostics display dolock draw draw.h drawn dst elided encoded environments error etc exists extension external failure fd fields file files finally fname font fontchar fonts format frees freesbufont freesubfont graphics greek header height hold holding identify image images include info initialized installsubfont int intended interface internal kept kernels latin1 letters lib libc.h libdraw library loaded locate lookupsubfont lower malloc manipulation maps maximum memory min mkfont names naming nil operating oriented partially pixels pointer primitives principally processes provide q.v range read reads readsubfont readsubfonti registered removes resolved returned returns routine run rune runes scheme searches shared size source specifies src stand stores str string stringsubfont strsubfontwidth structure subffree subfont subfontname subfonts substituted suitable synchronize sys takes threaded time tree typically u.h underlying uninstallsubfont version void width writeimage writes writesubfont zeroed subfont 2/subfont + allocated appends appropriately arrive assumes attr attribute buf byte bytes caller char character characters complete components contains converting converts copy count data deletes descriptor diagnostics dst enables encodes eplumb equal error errstr event exists fails fd file format formats frees header include int interface inverse key length libc.h libplumb list literal location malloc manipulate message messages mode morep ndata newline nil np null occur omode op opens original owrite permit pieces plumb plumb.h plumbaddattr plumbattr plumbattra plumbdelattr plumber plumbfree plumblookup plumbmsg plumbopen plumbpack plumbpackattr plumbrecv plumbsend plumbsendtext plumbunpack plumbunpackattr plumbunpackpartial points port processing programs quote quoted read recall receipt received receiving registers remaining reports resulting return returned returning returns routine routines searches sections send setting signs simplified slash source space src string strlen struct structures sufficient sys terminate text therefore total translating transmitting type typedef u.h unpack unpacked unpacking using value version void wdir writes plumb 2/plumb + allocated array beyond bugs bytes char character characters chars compiled compiles context correspond corresponds counting delimited dest detected diagnostics digit dlen entry ep error exactly except exits exp expression expressions extended failure fields file filled fills fit generated grep illegal include instance int involving libc.h libregexp literally malloc match matched matches matching metacharacter msg msize newlines nul null nuls parenthesis parenthesized patterns perform performed pick places pointer pointers points preceding processing prog regcomp regcomplit regcompnl regerror regexec regexp regexp.h regsub regular released rep replaced reprog resub return returns routines rregexec rregsub rsp rune runes source sp space specify src standard starts string strings struct structure subexpression subexpressions substitution substring substrings sys terminate th trimmed typedef u.h union unused user using variants void whenever writes regexp 2/regexp + allocates atomic attach becomes bind boundaries buffer byte bytes channel comes communication connected contiguous cross data data1 delivered descriptors device devpipe.c dir file files full guaranteed interprocess mode ordwr performs piece pipe pipe's port preserved provided read readers reading receiving recipient return returns size source src streams sys terminates typically whichever write writers writes written pipe 3/pipe + allocimage alpha backward base bit bits blank block blocks blue bottom byte byte's bytes care chan channel channels character characters code color comfortably comma compressed compression comprising confused consists contains contiguous coordinate coordinates copied copy correspond current cursor cursors data deal decimal deduce deep define defines definition deprecated depth described describing descriptions descriptors design details directly discussion divisor don't draw draw.h eight encode encoded encoding error external faces file files fine fit font fonts format formats graphics greater green greyscale header hexadecimal identical image image's images include inclusion independent indicates input integral jacm jpg justified laid larger ldepth lempel length lengths letter limit literal loadimage logarithm longs low lz77 machine mapped memdraw memory message mod numbered occurring offset offsets ordering overlap padded pair particular pixel pixel's pixels pp prescient previously processed programs r.max.x r.max.y r.min.x r.min.y r8g8b8 read readimage readmemimage reads rectangle red reflect replaces represents requires rest row rows scan scheme seemail separately shorts size sizes sliding software source starts stored storer stream string strings strtochan subfonts substitution substring substrings suitable sum szymanski takes text textual textually tweak twelve uncompressed unloadimage unused user using usual value values variable venerable version via wide width window works writeimage writememimage written ziv's image 6/image + allocimage alpha bit bits blue closest cmap2rgb cmap2rgba col color colors convert decomposes defined draw draw.h format full graphics green image include index int integer intensity libc.h libdraw library low map maps memdraw plan red representation representing returns rgb2cmap rgbv routines scaled shifted source src standard sys takes trio triples u.h value values color 2/color + allocimage bit blue button clicking cmap cmd color colormap colors colors.c components contains contrast current default define defined defining directory display display's displays entry exit file files finally floating gamma getmap green grey grid hardware hexadecimal index lib listed loads map mapped menu monochrome mouse names option presents ramp red repository reverse rgamma rgbv rx scale screen showing shows similarly source src standard stored string synonyms sys value vga video colors 1/colors + allotted alternate arrows assumed behavior binary black blocks byte cmd colored current data deadline deadlines displays event events factor file files generated green include kernel keystroke machine mark marking options overran pause pid print proc process processes processor providing quit read reader reads real recognizes red releases resume retrieve run running scheduler shows source specify src structures sys time times trace trace.c trace.h traced using window yielded zoom trace 1/trace + allow announces apparently asn.1 association associations bla bugs cat cd cert.cer cert.pem certdebug certificates child cmd connection conventionally create creation ctl datadump debugging default defaults directories directory doesn't echo enables encrdebug encrdump etc exchange factotum file files fsdebug ike ikedebug implements include increases initially initiate initiator internet ip ipsec key keyclear.asn keyclear.pem keys lib message mount negotiated negotiates newsa output parsedebug pem port possibly posted prefix removing represents resp_state_auth rfc rfc4306 role rsa saname sas security server shut simpler source src srv ssl suffices sys udp usr usual values verbose verbosity version worse writing yraddr ike 4/ike + allow applications asn.1 asn12rsa attribute attributes auth authorized_keys bell binary bits bugs cached cat cert certificate certificates certinfo cmd cn comment comments compatibility configure contains converts cs.bell ctl current decimal decryption default der derived describing distinguished dk ek enabled encoded encoding encrypted encryption enhanced exactly except expect expires expiretime exponent external extracts factotum file format formats fresh full g.r.emlin generate generated generates generic hexadecimal httpd identifying implementations includes info insecure inserting ip issuer key keyring keys kp kq labeled labs labs.com lib list logins lucent mail merely missing mnt nbits nj note omits ou output owner pair parameters pem pemdecode pemencode plan pop3 popular portion prefixed preserved prime printed prints privacy private product proto randomly reads recomputes remote removes represents resulting rsa rsa2pub rsa2ssh rsa2x509 rsafill rsagen rules seconds section self serve server sessions signed significant size source space speed src ssh st standard stored string subject sys tag text textual time tls tlssrv typically unix using utilities value web windows writes rsa 8/rsa + allow approximately bind bytedelay bytes clear connected connection contains control controlled cross ctl data delay device devloopback.c directories directory disallow divided drop dropped droprate due exit file files flow format hold indrop input interface latency limit link links list loopback machine monitor nanoseconds net network options output overflows packet packets parameters permitting port queue queues randomly readable reading receive receiver receiving recorded reported representing reset returns send sent simulated simulation size source src statistics stats status subdirectories supply supported sys tagged takes time transferred typically writes writing written loopback 3/loopback + allow ascii aux backspace bar bigfile cmd continuously control converting coordinates created decimal del denominator display displayed download exit exits file fraction graph hget http input kt lines minx,miny,maxx,maxy monitor numerator option options output print reaches reads redraw screen server.com source space src standard status statusbar statusbar.c suitable sys textual title typing updated using window statusbar 8/statusbar + allow authenticate behalf bind bytes cap capabilities capability caphash capuse characters computes concatenation cons consisting create dev devcap.c device diagnostics dir doesn't enables error errors errstr executing factotum freeing generated generates hash hashes hmac_sha1 host hostowner id identity indeed intent invalid ipserv kernel key length list maintains match matching minute nil null obtained old_at_new owner pass port process process's processes proved randomly read reading running searches sechash secure server setting source src string strlen sys telnetd trusted user using write writing cap 3/cap + allow bin broke broken caught ctl current debugger default delivered dies error examination execute executing file handed heavy ignoring kill lets linger message necessary note notes notify offending output owned pipe print printed prints proc process process's processes ps rc reclaim resources rio send sending slay source stop suggests surer user kill 1/kill + allowing bin bugs directives document files implied inclusion input lib lines mullender note objects performs placement preprocess programs rc reads run sape script share shell soelim some_file source standard suppressed tables tbl text textual tmac tmac.s troff using usr written soelim 1/soelim + allows append appended ar archive archiver archives aren't ask attempt automatically backwards behavior bin bits block bugs bundle bytes bzip2 cd characters cmd compatibility compress compressed compression concepts contained contains copied copy corrupt create current deeper default details dircp directories directory doesn't dumped entire entries errors exclusive exist exists expected extension extensions extract extracted extracting file files filesystem finding flag foreign format fromdir generate gzip header hierarchies id ignore implies indicate inferred input key keys latest leading length letter letters limited links list matches maximum metadata mkfs mode modes modification modified modifiers modifies moving names non numeric occurrence occurrences older operate optional output path pathname permission permitting plan plus posix print processed produce raises rc reading recognised recognized record recursively relative respect restored restores resynchronise saves slash source specific specification src standard string subdirectories symbolic sys tape tapefs tar tar.bz tar.bz2 tar.c tar.gz tar.z tars tbz tbz2 tgz time todir transport tree trees type tz unnecessary user using ustar verbose verbs versions wins writing xt tar 1/tar + allows arbitrary bit bottommost bounds button character clear cmd convert current debug desired dir displayed doubles entirety everything file files flag font fonts goes gs hold input intermediate interpreter item kernighan keyboard language lib location lp mag magnification manual map menu missing mouse move moving names nearer negative newline nview offset options ossanna output page pages pan pans pauses piece pieces pixels positioning press print printed proof quit reads redisplayed released resulting rightmost screen selecting shown shrinks signed simulates size slightly source split src standard sys text toggle troff typed user's val wait window proof 1/proof + alone assumes authenticate based block channel clients cmd communication compressed create created default descriptors device disk file flag flash infd interprets member mksacfs mounted mountpoint mounts neither nor outfd persistent plan post rom sacfs sacfs.c source src stand storage stored sys typically sacfs 4/sacfs + alphabetic analogously ascii cases character characters classes conversion ctype defined defines examine explanatory include int isalpharune isdigitrune islowerrune isspacerune istitlerune isupperrune libc libc.h lower modify names operate particular port properties return routines rune runetype.c self source specifies src standard subset sys test title tolowerrune totitlerune toupperrune types u.h unchanged unicode upper isalpharune 2/isalpharune + alphabetics ascii bit cds character characters cmd code codes combination complement copies create cs delete deletion digits duplicating file1 file2 hexadecimal input length letters lexicographically list lower mapped maximal mixed newline noninitial occur octal options ordered output padded possibly quoted range repeated replace runes running sed selected short source squeeze src standard stands string string1 string2 substitution successor sys tr tr.c translate upper value za tr 1/tr + alphabets bugs button characters clicking cmd column consisting current default defined dev entire entry exists file files highlight kbmap kbmap.c keyboard keyboards lib list map mapping maps mouse names quits requires served shows source src switch sys typing writable kbmap 1/kbmap + alphanumeric ampersands apostrophes attachments backslash bugs chaos characters cmd complete consider constructions constructs definition definitions delatex delatex.c deletions delimiters deroff deroff.c digits documents embedded emitted eqn etc execution file files filters formatting ignore included input inside interpreters latex letter letters list lists macro macros mentioned ml mm ms non nroff nx option options ordinary original output pic popular preprocessors properly punctuation reads remaining remove removes requests skipped source spell src standard string sys tbl terminates tex text titles troff underscores wi written deroff 1/deroff + alt bind button buttons character characters code codes cons control csa current decimal dependent dev device devkbmap.c directory distinguish entry fields file files fn hardware hexadecimal index kbmap kernel's keyboard keys laptops level lib lines map mapping maps mice mouse none numeric octal platform port reads represent representation representing return scan scroll serves shifted similarly source space src sys table typically unicode unless unshifted utf value values vary wheel writes written kbmap 3/kbmap + alternate announce average bandwidth byte bytes cmd compute debugging default dftv enable exit exits file filename floating fragment input interrupted interval ip log machines maxfrag maxfragsize maximum measure megabytes options output ping port print process read readsize receive receiving rtcp run seconds secs session shuffle size source src standard stcp str sv sys target tcp throughput time totsize transferred transmit ttcp verbose wait write writesize rtcp 8/rtcp + alternative applications ascending awk bounds bracketed character characters charclass class commonly concatenated delimiter ed expression expressions extends grep inclusive instances literal match matched matches member metacharacter metacharacters negated newline non nonempty notation operators preceding preventing range regexp regular remainder rep rune sam sed specification specifies stands string strings substring syntax unescaped regexp 6/regexp + amount asc ascq atapi attempt attempts bit bring bytes changetime char closes closescsi cmd codes commonly connection consulted consulting current data debugging denoted descriptor detected devdir device device's dir disk.h drive error errstr execute fail fails failure fair fields file files frees harder include inconsistent inquire inquiry inserted int interface issued issues lib libc.h libdisk list maintained media messages nchange ncmd ndata obtain openscsi operation operations output overwritten produce provide raw rawfd reads ready record request responds return returned returning returns routine routines scsi scsi.c scsicmd scsicodes scsierror scsiready scsiverbose scuzz sd send sends simply snone source src sread status store stored stores string struct structure success successful swrite sys textual time times transmitted tries try typedef u.h uchar ulong unit via void works written scsi 2/scsi + analogues bugs es1 implementations include int libc libc.h memory moves operations outcome overlapping port rune runestrcat runestrchr runestrcmp runestrcpy runestrdup runestrecpy runestrlen runestrncat runestrncmp runestrncpy runestrrchr runestrstr source src strcat string sys u.h varies runestrcat 2/runestrcat + aname attach auth automatically bind binds bound channel character characters client console conventional dev device device's devices driver equivalents error file files flush identified identifies implements includes init intro introduction ip kernel lib list locations looks ls messages mrepl names namespace newns nop pages parameter particular performs plan pound procedure processes protect protocol provided quotes rc remote representing root section sections server session sign space stack string subroutine tree typed using valid 0intro 3/0intro + annotated annotations bugs cases cmd complex confused constructions convert converts cp create default depends described documents don't easily eqn etc experimental file files handle helped helper html httpd hyperlinks improve indented independent input interpolated introduced invoked lines macro macros magic main man2html manhtml manref mesh models modulo ms ms2html output package pages pair paragraphs pic placing pointing preprocessors produced properties reads recognized reliable rest reverse served shows source specially src standard straight subsume sys text time title tolerable troff troff2html understands x'html troff2html 1/troff2html + ap article articles bin column descriptions fetch fetches http invoked key keys list news press provides rc source www.newsday.com ap 1/ap + aphorism automatically chosen cmd fast file files fortune fortune.c fortunes fortunes.index games lib lines lookup maintained prints random sample saying selected source src sys table fortune 1/fortune + append architecture architectures assemble assembler assembler's assemblers bugs character cmd common correspondence default dependent directives directory etc file files handle include input ka letter list machine manual obj object objtype option options output partial parties path pike plan preprocessor programs provided qa retired rob searched source specifies src strip supported sys systems third va 2a 1/2a + append awk cmd contained default divisions exclude excluding expression file files grep identified ignore input lines lower matched matches names nod occur option options output parentheses pieces portion reads regexp regular sed source split split.c src standard stem subexpression suffix synonym syntax sys unix's writes xaa xab xzz split 1/split + append cmd copies files fitting ignore input interrupts options output pipe rewriting source src standard sys tee tee.c transcribes tee 1/tee + appending areacodes bin book chosen codes comma contains customarily database differences directory domain files grep ignore internet iwhois key lib looks miscellaneous names nic's option optionally personal personnel phone private rc server server's source surname tel telephone userids users tel 1/tel + appends assumes automatically block blocks blocksize blocktype buf buffer buffers byte caller char codec colon constants conversion convert converts copy crypto data defined described describing diagnostics differs digit dir directly disk distinguish dsize enum enumeration error except fail fcall fields file flags fmt formats formatters freed frees gen generation hexadecimal holds include index input installed int invalid label libc.h libventi maximum message msgtype network nil packet packets parses pointed pointer pointers prefix prefixed presented prev print programs protocol psize reads renamed representation representations return returned returning returns reverse root routines score scores serialized sid size source src string strings struct structure structures success sys text tree type typedef u.h uchar uid uint ulong ushort using uvlong value values venti venti.h version void vtcorrupttype vtdatatype vtdirtype vtentry vtentrypack vtentrysize vtentryunpack vtfcall vtfcallclear vtfcallfmt vtfcallpack vtfcallunpack vtfromdisktype vtgetstring vtparsescore vtputstring vtrhello vtroot vtrootpack vtrootsize vtrootunpack vtscorefmt vtscoresize vtthello vttodisktype writing venti-fcall 2/venti-fcall + applicable behavior blank char considered continues copied copy current default desired destination dir directories directory disk.h enm enumeration environment error except exist expanded explicitly extra fetch fields fifth file files formats fourth generic gid guaranteed include indentation int interprets length level lib libc.h libdisk lines listed listing message mk9660 mkfs mode msg mtime names nil opened optional override owner owning parse path permissions pointing points portproto prefix prints process processed processing proto proto.c protoenum prototype protowarn rdproto read reads recursively relative returns root setting significant source space specifies specifying src standard subdirectories sys sysconfig tabs third tree typedef typically u.h uid valid variables void warn warning wishes proto 2/proto + applications base bind cd cmd constructing current directory enter fd2path final getwd guaranteed intended intro longer mechanism names newline path pbd pbd.c prints prompts pwd pwd.c rc return shell source space src sys valid working pwd 1/pwd + appropriately assumes bin bugs cat certainly cmd connect default dial dialing directory exec execnet executed execution exists hosts instance instances interface ip na net netdir network newly none ny page presents protocol remote running sh shown source src srv ssh strings sys tested tmp u9fs u9fs.log user execnet 4/execnet + appropriately diagnostics double eptr exp exponent fractional frexp frexp.c include indirectly infinity int integer intro iptr ir ldexp libc libc.h mantissa modf overflow port quantity returns signed source split src stores sys u.h underflow value frexp 2/frexp + approximation aux bin bit bitmap characters cmd embedded files font formats generates images japanese jp lib looks macros mnihongo output pelm post processing processor provides source src sys text tmac tmac.nihongo troff truth typesetting unicode unicode.9x24.font widths mnihongo 6/mnihongo + ar archives beware bin boris bourne bugs bundle cd ch collect complete create directories distributing distribution documenting executed file files gift horse horses kremvax machine mail main makefile mk mkfile non original output postmark preparation rc receiving recreate refined related required sans save script self send shell source standard tar text unsatisfactory writes bundle 1/bundle + architectures division equivalent final fit generate hold include integer integers intermediate libc.h muldiv multiplication overflowing precision returns routines scale silently trap truncate u.h ulong umuldiv unsigned using values vlong worry muldiv 2/muldiv + arg argc argv bugs char cs current discover fetch firstarg getcallerpc include int libc libc.h main necessary objtype parameter pc pointer portable print printpc return source src sys u.h uintptr void getcallerpc 2/getcallerpc + arg args aux b,s,f binary,r cmd comma creates described environment error eval exit explaining final flag flagfmt getflags getflags.c ifs indicating initializes leak letter list mentioned message names non option option's options output parse parses parsing pid printed prints rc res,x script scripts shell source space src standard status string success sys takes usage usage.c using variable width getflags 8/getflags + arg blanks cmd diagnostics draws echo echo.c error exit newline option output print source src standard status suppresses sys write writes writing echo 1/echo + arg cmd complete elapsed error executed prof program's real reports seconds source src standard sys time time.c user time 1/time + array arrays base buffer byte bytes char create dec16 dec32 dec64 decoded decoding default display enc16 enc32 enc64 encode encoded encodefmt encoding fails flag fmt fmtinstall forces hex hexadecimal i.e include input int length libc libc.h lim lower mime null output port print representations return size sizeof source src string strings sys u.h u32.c u64.c uchar upper verbs encode 2/encode + array base bytes compar compared comparison considered data equal greater include int integer libc libc.h nel nondecreasing pointer pointers port qsort qsort.c quicker return routine sort sorts source src sys third u.h void width qsort 2/qsort + article articles authenticate authenticates bugs check cmd comp comp.os.plan9 compliant connection contains ctl default deleted detected determined dials directories directory directory's dots e.g echo effort entire eventually exist factotum file files follow full groups hang hangups header keepalives key largest lines list location megabyte mnt modification mount mountpoint necessary network news newsgroup newsgroups nntp nntpfs nntpfs.c nose.mit.edu note numbered numbering obtained opened option os pass password plan9 port post posted presented presents private proto protocol qid recorded redials rfc1036 root rsc secret send server servers session slashes source specifier src srv stat stored sys tcp terminate text tied time transferred transport unmount user version write written nntpfs 4/nntpfs + ascent baseline bit blank bottom byte bytes cachechars calculate character characters chosen consistently consists contains convention covered decimal default described directories directory display distance draw draw.h entries external fields file files font fontchar fonts format glyphs graphics header height hexadecimal image include inclusive info inter irrelevant justified lib low mapped minimum names non note nul numeric octal openfont optional padded pixels plain range read readsubfont relative represent rigid slash space spacing specification specifications strings subfont subfonts suitable text using value width writesubfont written zeroth font 6/font + ascii based bugs cmd converts data decode dis emits encode encoded encoding error expanded file files filters ignoring included input leading limbo.dis lines mail marshal media message mime msg original output printable produced purely reads recipient relic representation send source src standard support sys third tmp transmission transmit uudecode uudecode.c uuencode uuencode.c writing uuencode 1/uuencode + ascii binary blank characters cmd consecutive continuation decimal default dots encoded extract ffff file finds hexadecimal inclusive input longer min nm offset printable printing prints reports resumed runes source src standard starts string strings strings.c sys text tilde typically utf value strings 1/strings + ascii blank broken bugs bytes characters cmd code codes count counts delimited file files includes input invalid letters lines looks lwc lwrbc maximal newline newlines occur optional options reported runes scattered selected source space spaces src standard string suboptimal syntactically sys tab tabs unicode utf wc wc.c wc 1/wc + assembler base dependent double exp exponential hypot implementations include int intro libc libc.h log log10 logarithm machine natural objtype port portable pow pow10 returns root routines sinh source sqrt square src sys u.h written exp 2/exp + association attr attribute bind bugs card card's chip compatible computer ctl databook dev devi82365.c device devices driver drivers ethernet included intel interface mem memory ne4100 pc pcm pcm0attr pcm0ctl pcm0mem pcm1attr pcm1ctl pcm1mem pcmcia personal plan9.ini provides ram reading reads returns routines slots source src status supports sys writes writing i82365 3/i82365 + atcommand attention badstring baud bin buffer can''t cmd communicate communications compatible connect connected cons control copies copy ctl cts dcd default dev device dial dialer dialfn dialing dials discards doing don't drain dt dtr e.g echo eia1 equal error everything exit expect expecting files flag flow fn gets goodstring handup hayes ignore initfn input ip ipconf iq lets looking lose matches modem modem's mostly newline nonblocking ok options output pass password ppp prefixed primary rc read reading reads response return rts script scripting scripts seconds sends serial sessions sleep source src standard status stream string strings success successul sync sys telco telephone telnet telno terminates test timeout tools type uart user username using waiting write writes zh0 expect 1/expect + atexit atexit.c atexitdont brief calling cancels char cleanup conventional conventionally errlen exit exiting exits explanation failed fn fork id include includes indicate int invoke length libc libc.h limit maximum memory msg null package parent pointer port prefixed process programs reached recorded records register registered registration return returns reverse routine share simplify source src string sys terminate termination twice typical u.h underlying void wait exits 2/exits + attached bin bound cfg claim configures control copying ctl current dev devices diskparts disks dma dmaon enables fdisk files fs fsconfig ide interface partfs partitions plan prepare rc sd source storage support sysname time diskparts 8/diskparts + attack denial disguise doing echo ext identity ip listen packets port received run someone testing udp udpecho udpecho 8/udpecho + attempting bare bin bugs cons copying directory file fossil fshalt halt halting halts impossible invoked invoking kfs machine machines necessary optionally ramfs rc reboot rebooting restarts roots servers source standalone syncs systems venti fshalt 8/fshalt + attempts bugs chmod cmd created current date default directories exist file files ls modification option source src stat sys time touch touch.c unless touch 1/touch + attribute aux card cmd default file files identify memory output pcm0attr pcmcia pcmcia.c readable slot source src standard structure sys translates writes pcmcia 8/pcmcia + auth authenticates authentication blank cat clock cmd commas con create cron cron.c current daemon dates entries equivalent executes execution fields file files helix host hour hyphens inclusive instructions integer lib lines lists lock machine mail mailnews mails minute minutes month news option patterns plan prevent profile range ranges rc reach reliable remote run running runs rx send server skips source spaces specify src string sunday syntax sys time times upas user user's using valid weekday cron 8/cron + automatic belong bin bnppstw bugs cases chapter date default definition detail display doesn't editor eqn except file files i.e index indices intended key lib locates lookman lower manual match mechanism names nroff options output page pages plumber print printed prints proof rc recognize run sacrificed search searched secindex section sections send serve sig signature source standard sys tbl terminals text title titles troff typeset using man 1/man + aux broken cmd connection cpu cputype default diskless fails file lib loss minutes reboot reboot.c reboots remote restart server servers source src stat stats sys timing whenever reboot 8/reboot + bar beautifier bugs cb cmd code comments correct default errors file files hidden indentation initializers input join js k&r language length lines longer macros newline options output pleasing preserved print programming programs punctuation reads reformat source spacing split src stdout structure style syntactically syntax sys understands user visually writes cb 1/cb + base basename bugs cmd contains convert converted converts defined delim delimiters delims document doesn't entry eqn equations files gif handle html html2ms html2ms.c htmlroff images input macro macros malformed ms ms2html ms2html.c options output pipe postscript preprocessors prints reads source src standard strings suppresses sys tables tbl text title tl troff troff's understand unknown value warnings ms2html 1/ms2html + based cci ccid cmd communicates content continuously dev disappears iso led library message mifare ongoing orange plumb plumbing plumbs polling programming reader rpc runs scard smartcard source src standards successfully sys tag tagrd tagrd.c touchatag uid ultralight usb tagrd 1/tagrd + baw cmd control data default dev device disk diskimage diskname disksim dr fdisk file flash geometry manner mbr message mtpt option partfs partfs.c partition partitions plan9 post prep presents sd sdxx sector sectors serve setting size source src srv srvname sys unless usb written partfs 8/partfs + becomes binary blank byte bytes character characters check contains core cpu creation data debugging decimal denotes described describes descriptions disjoint dumps fd file flag format formatted fpregs guaranteed header hold humans id identification image images incomplete indicating intended justified kernel kilobyte kregs machine mem memory missing noteid ns offset omitted padded page prefix previously proc process programs quickly reading record records regs rest save section sections segment shorter size smaller snap snapshot snapshots space split status string strings text throughout time type understood unix useless user snap 6/snap + behavior default defines division domain double equal exception floating getfcr greater ieee include inf infinity int isinf isnan libc libc.h library manipulating nan nan.c negative overflow port positive processors produced range return returns setfcr sign sometimes source src standard sys u.h values void nan 2/nan + beware blocks buffered bugs cat cat.c catenate cmd concatenates continue copies cp data default destroy diagnostics doesn't eof exactly executes exits expect file file1 file2 file3 files flag helpful input interactive lines matching nline nlines output places preparing prints programs rc read read.c reading reads scripts source src standard status sys third time write writes writing cat 1/cat + bin break bugs details digit express fedex output parcel post programs rc redesigns shipment shipments similar source standard takes track tracking ups usps website writes fedex 1/fedex + bin code current db defined definition directory ed editor examines executable extract file files flag identifies locate looks main plumb print rc routine sam script send sent source src strcmp subdirectories symbol table using src 1/src + bin consistent current debugged execute kill owned pipe print prints proc processes ps rc rio send source started stop stopped user stop 1/stop + bin http online rc search searches source thesaurus thesaurus.reference.com thesaurus 1/thesaurus + bind codes cons correspond described dev device devkbin.c directory driver drivers external file handle input kbin kbmap kernel keyboard keyboards level necessary pc processed scan send serves source src sys translated usb kbin 3/kbin + bind conventional describes file files interesting interface intro introduction maintained manner manual mounted permanent plan process processes provider provides section server servers services space storage synthesizes tree 0intro 4/0intro + blank bugs editor emacs intentionally macros mit options page sam source vi yes emacs 1/emacs + block blocks buf buffer byte bytes canonicalize compute data extern grow ignoring include int length libc.h libventi newsize pads pointed pointer replace returns score scores size source src storing sys truncate truncation type u.h uchar uint utility venti venti.h void vtscoresize vtzeroextend vtzeroscore vtzerotruncate zero.c zeroscore.c venti-zero 2/venti-zero + blocks boot bugs channel closed cmd configured created deadlock device devices directly directory environment error establish establishes file files full kfs lead level process raw remote replaced resulting returned served source src swap swap.c swapping sys time unique user valid variable swap 8/swap + bootstrap chgrp chgrp.c chmod cmd current file file's holding ineffectual leader ls member option ou owner ownership permits server source specify src stat synonyms sys unless chgrp 1/chgrp + bw chunk cmd compare diff differ differences displays environment error execute file1 file2 files flags future hall idiff idiff.c interactive interactively invokes kernighan merges onto output pike prentice programming prompt prompts questions response responses select source src standard style sys tmp unix user valid wherever idiff 1/idiff + byte bytes cmd cmp cmp.c compare compares comparison decimal designated diagnostics diff differ difference differing disagreeing eof except exit file file1 file2 files hexadecimal inaccessible lls longer message missing octal offset1 offset2 offsets options print prints reports source src starts status sys cmp 1/cmp + byte cdorx character cmd counts decimal default entry file files flags formats freq freq.c frequencies hex histogram histograms input non octal option options print printable printed prints reads runes sequences source specify src standard subset sys table unicode utf value wc freq 1/freq + bytes calling capable char circular conn convenient creates debugging default defaults descriptor error events exist existing extern fd file fmt freed freeing holding include inspect int length libc.h library libventi list log logs memory names nil non op ops packaging pointer prints provide purposes record reference releases removes returned returns routines server size source src storage string strings structure structures sys u.h uint utf venti venti.h ventilogging void vtfree vtlog vtlogchunk vtlogclose vtlogdump vtlognames vtlogopen vtlogprint vtlogremove vtserverlog writes venti-log 2/venti-log + bytes char clean cleanname cleanname.c components directory eliminates file filename hypothetical include interprets lexical lexically libc libc.h names null overwritten path port possibly processing return returns shortest slashes source src string sys takes therefore u.h cleanname 2/cleanname + caches char cons contains current data dev file getuser getuser.c include intro libc libc.h machine null owns pointer port process provides reading reads returns source src static string sys sysname u.h unlike user void getuser 2/getuser + can't cmd delete directories directory don't entire file files fr neither nor options permission read recursively removal remove removed removes report requires rm rm.c source src sys write rm 1/rm + cd cmd complain creates creating default diagnostic diagnostics directories directory dirname error exists exit flag mkdir mkdir.c mode necessary null parent permission permissions prints rc requires returns rm source src status successfully sys target write mkdir 1/mkdir + clean cleanname cleanname.c cmd components directory eliminates equivalent file hypothetical interprets lexical lexically names option path possibly prefixed prints processing pwd shortest slashes source src string sys unrooted cleanname 1/cleanname + clicking cmd current del dev display displays exclude excluding expression faces files flag focus font label labels matching monitor quits raises refreshing regexp regular rio seconds showed shown source src stats sys typing unhides window window's windows winwatch winwatch.c wsys winwatch 1/winwatch + cmd cmp column comm comm.c common diff file file1 file2 files flag input lexicographical lines output print printing produces reads reject select sort sorted source src standard suppresses sys uniq comm 1/comm + cmd epoch file modification mtime mtime.c print prints seconds source src sys time mtime 1/mtime + cmd execute execution floating hence interval repeat seconds sleep sleep.c source src suspend suspends sys time sleep 1/sleep + cmd exits factor factor.c factors finish generate input integer maximum missing positive prime primes primes.c prints proper proportional ranging reads repeated running source sqrt src standard stream sys time times factor 1/factor + compute cosh designated double hyperbolic include intro libc libc.h port real sinh source src sys tanh u.h sinh 2/sinh + describes file formats intro introduction macro manual miscellany packages section troff 0intro 6/0intro + distance double euclidean hypot hypot.c include libc libc.h overflows port precautions returns source sqrt src sys taking u.h unwarranted hypot 2/hypot diff --git a/sys/man/vol1.pdf b/sys/man/vol1.pdf new file mode 100755 index 000000000..21fad0be0 Binary files /dev/null and b/sys/man/vol1.pdf differ diff --git a/sys/man/vol1.ps.gz b/sys/man/vol1.ps.gz new file mode 100755 index 000000000..4570cc5d3 Binary files /dev/null and b/sys/man/vol1.ps.gz differ -- cgit v1.2.3