From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/index.html | 45 ++ man/man1/9.html | 100 ++++ man/man1/9c.html | 172 ++++++ man/man1/9p.html | 122 +++++ man/man1/9term.html | 259 +++++++++ man/man1/acid.html | 486 +++++++++++++++++ man/man1/acme.html | 481 ++++++++++++++++ man/man1/acmeevent.html | 332 ++++++++++++ man/man1/ascii.html | 159 ++++++ man/man1/astro.html | 125 +++++ man/man1/basename.html | 63 +++ man/man1/bc.html | 272 ++++++++++ man/man1/bundle.html | 95 ++++ man/man1/cal.html | 81 +++ man/man1/calendar.html | 82 +++ man/man1/cat.html | 126 +++++ man/man1/cleanname.html | 65 +++ man/man1/clog.html | 61 +++ man/man1/cmp.html | 84 +++ man/man1/colors.html | 92 ++++ man/man1/comm.html | 79 +++ man/man1/core.html | 83 +++ man/man1/crop.html | 127 +++++ man/man1/date.html | 75 +++ man/man1/db.html | 548 +++++++++++++++++++ man/man1/dc.html | 199 +++++++ man/man1/deroff.html | 102 ++++ man/man1/dial.html | 67 +++ man/man1/dict.html | 168 ++++++ man/man1/diff.html | 141 +++++ man/man1/doctype.html | 88 +++ man/man1/echo.html | 62 +++ man/man1/ed.html | 439 +++++++++++++++ man/man1/eqn.html | 203 +++++++ man/man1/factor.html | 73 +++ man/man1/fmt.html | 100 ++++ man/man1/fortune.html | 64 +++ man/man1/freq.html | 69 +++ man/man1/fsize.html | 68 +++ man/man1/grap.html | 232 ++++++++ man/man1/graph.html | 117 ++++ man/man1/grep.html | 117 ++++ man/man1/gview.html | 155 ++++++ man/man1/gzip.html | 135 +++++ man/man1/hoc.html | 136 +++++ man/man1/idiff.html | 87 +++ man/man1/index.html | 449 +++++++++++++++ man/man1/intro.html | 221 ++++++++ man/man1/join.html | 144 +++++ man/man1/jpg.html | 175 ++++++ man/man1/kill.html | 96 ++++ man/man1/label.html | 117 ++++ man/man1/lex.html | 110 ++++ man/man1/look.html | 96 ++++ man/man1/ls.html | 121 +++++ man/man1/man.html | 139 +++++ man/man1/map.html | 483 +++++++++++++++++ man/man1/mc.html | 64 +++ man/man1/mk.html | 621 +++++++++++++++++++++ man/man1/mk9660.1 | 232 ++++++++ man/man1/mkdir.html | 79 +++ man/man1/namespace.html | 61 +++ man/man1/news.html | 91 ++++ man/man1/p.html | 63 +++ man/man1/page.html | 97 ++++ man/man1/pic.html | 435 +++++++++++++++ man/man1/plot.html | 88 +++ man/man1/plumb.html | 80 +++ man/man1/pr.html | 90 +++ man/man1/proof.html | 119 ++++ man/man1/ps.html | 95 ++++ man/man1/psfonts.html | 148 +++++ man/man1/pwd.html | 73 +++ man/man1/rc.html | 655 ++++++++++++++++++++++ man/man1/rio.html | 172 ++++++ man/man1/rm.html | 66 +++ man/man1/sam.html | 577 ++++++++++++++++++++ man/man1/scat.html | 385 +++++++++++++ man/man1/secstore.html | 145 +++++ man/man1/sed.html | 300 ++++++++++ man/man1/seq.html | 99 ++++ man/man1/sleep.html | 91 ++++ man/man1/sort.html | 200 +++++++ man/man1/spell.html | 125 +++++ man/man1/split.html | 91 ++++ man/man1/src.html | 99 ++++ man/man1/stats.html | 214 ++++++++ man/man1/strings.html | 69 +++ man/man1/sum.html | 92 ++++ man/man1/tail.html | 116 ++++ man/man1/tbl.html | 187 +++++++ man/man1/tcs.html | 131 +++++ man/man1/tee.html | 56 ++ man/man1/test.html | 156 ++++++ man/man1/time.html | 63 +++ man/man1/touch.html | 69 +++ man/man1/tr.html | 107 ++++ man/man1/tr2post.html | 152 ++++++ man/man1/troff.html | 126 +++++ man/man1/troff2html.1 | 96 ++++ man/man1/troff2html.html | 108 ++++ man/man1/tweak.html | 194 +++++++ man/man1/uniq.html | 79 +++ man/man1/units.html | 156 ++++++ man/man1/vac.html | 160 ++++++ man/man1/wc.html | 75 +++ man/man1/web.html | 115 ++++ man/man1/wintext.html | 124 +++++ man/man1/xd.html | 99 ++++ man/man1/yacc.html | 170 ++++++ man/man3/9p-cmdbuf.html | 128 +++++ man/man3/9p-fid.html | 170 ++++++ man/man3/9p-file.html | 258 +++++++++ man/man3/9p-intmap.html | 110 ++++ man/man3/9p.html | 434 +++++++++++++++ man/man3/9pclient.html | 250 +++++++++ man/man3/addpt.html | 174 ++++++ man/man3/aes.html | 85 +++ man/man3/allocimage.html | 321 +++++++++++ man/man3/arg.html | 152 ++++++ man/man3/arith3.html | 216 ++++++++ man/man3/atof.html | 170 ++++++ man/man3/bin.html | 131 +++++ man/man3/bio.html | 293 ++++++++++ man/man3/blowfish.html | 95 ++++ man/man3/cachechars.html | 292 ++++++++++ man/man3/cleanname.html | 71 +++ man/man3/color.html | 89 +++ man/man3/complete.html | 136 +++++ man/man3/cputime.html | 65 +++ man/man3/ctime.html | 150 +++++ man/man3/des.html | 170 ++++++ man/man3/dial.html | 241 ++++++++ man/man3/dirread.html | 114 ++++ man/man3/draw.html | 1174 +++++++++++++++++++++++++++++++++++++++ man/man3/dsa.html | 172 ++++++ man/man3/dup.html | 78 +++ man/man3/elgamal.html | 174 ++++++ man/man3/encode.html | 109 ++++ man/man3/errstr.html | 121 +++++ man/man3/event.html | 390 +++++++++++++ man/man3/exec.html | 146 +++++ man/man3/exits.html | 126 +++++ man/man3/fcall.html | 274 ++++++++++ man/man3/flate.html | 333 ++++++++++++ man/man3/fmtinstall.html | 339 ++++++++++++ man/man3/frame.html | 325 +++++++++++ man/man3/genrandom.html | 84 +++ man/man3/get9root.html | 109 ++++ man/man3/getcallerpc.html | 99 ++++ man/man3/getenv.html | 79 +++ man/man3/getfields.html | 136 +++++ man/man3/getns.html | 67 +++ man/man3/getsnarf.html | 73 +++ man/man3/getuser.html | 75 +++ man/man3/getwd.html | 84 +++ man/man3/graphics.html | 592 ++++++++++++++++++++ man/man3/html.html | 1206 +++++++++++++++++++++++++++++++++++++++++ man/man3/index.html | 647 ++++++++++++++++++++++ man/man3/intro.html | 288 ++++++++++ man/man3/ioproc.html | 211 +++++++ man/man3/ip.html | 345 ++++++++++++ man/man3/isalpharune.html | 96 ++++ man/man3/keyboard.html | 135 +++++ man/man3/lock.html | 222 ++++++++ man/man3/mach-cmd.html | 167 ++++++ man/man3/mach-file.html | 185 +++++++ man/man3/mach-map.html | 312 +++++++++++ man/man3/mach-stack.html | 232 ++++++++ man/man3/mach-swap.html | 124 +++++ man/man3/mach-symbol.html | 272 ++++++++++ man/man3/mach.html | 123 +++++ man/man3/malloc.html | 181 +++++++ man/man3/matrix.html | 263 +++++++++ man/man3/memdraw.html | 466 ++++++++++++++++ man/man3/memlayer.html | 325 +++++++++++ man/man3/memory.html | 123 +++++ man/man3/mouse.html | 249 +++++++++ man/man3/mousescrollsize.html | 108 ++++ man/man3/mp.html | 441 +++++++++++++++ man/man3/muldiv.html | 61 +++ man/man3/mux.html | 169 ++++++ man/man3/nan.html | 79 +++ man/man3/needstack.html | 98 ++++ man/man3/notify.html | 183 +++++++ man/man3/open.html | 130 +++++ man/man3/opentemp.html | 78 +++ man/man3/pipe.html | 111 ++++ man/man3/plumb.html | 257 +++++++++ man/man3/post9pservice.html | 67 +++ man/man3/postnote.html | 80 +++ man/man3/prime.html | 114 ++++ man/man3/print.html | 309 +++++++++++ man/man3/proto.html | 140 +++++ man/man3/pushtls.html | 261 +++++++++ man/man3/qball.html | 111 ++++ man/man3/quaternion.html | 163 ++++++ man/man3/quote.html | 164 ++++++ man/man3/rand.html | 190 +++++++ man/man3/rc4.html | 86 +++ man/man3/read.html | 109 ++++ man/man3/regexp.html | 178 ++++++ man/man3/rfork.html | 118 ++++ man/man3/rsa.html | 262 +++++++++ man/man3/rune.html | 157 ++++++ man/man3/runestrcat.html | 107 ++++ man/man3/sechash.html | 195 +++++++ man/man3/seek.html | 96 ++++ man/man3/sendfd.html | 85 +++ man/man3/setjmp.html | 110 ++++ man/man3/sleep.html | 95 ++++ man/man3/stat.html | 244 +++++++++ man/man3/strcat.html | 203 +++++++ man/man3/string.html | 244 +++++++++ man/man3/stringsize.html | 116 ++++ man/man3/subfont.html | 260 +++++++++ man/man3/sysfatal.html | 71 +++ man/man3/thread.html | 383 +++++++++++++ man/man3/time.html | 79 +++ man/man3/udpread.html | 105 ++++ man/man3/wait.html | 170 ++++++ man/man3/wctl.html | 78 +++ man/man3/window.html | 241 ++++++++ man/man4/9pserve.html | 79 +++ man/man4/acme.html | 268 +++++++++ man/man4/import.html | 107 ++++ man/man4/index.html | 49 ++ man/man4/intro.html | 92 ++++ man/man4/plumber.html | 122 +++++ man/man4/ramfs.html | 81 +++ man/man5/index.html | 28 + man/man7/color.html | 169 ++++++ man/man7/face.html | 127 +++++ man/man7/font.html | 101 ++++ man/man7/image.html | 175 ++++++ man/man7/index.html | 76 +++ man/man7/man.html | 292 ++++++++++ man/man7/map.html | 108 ++++ man/man7/ms.html | 185 +++++++ man/man7/plot.html | 386 +++++++++++++ man/man7/plumb.html | 357 ++++++++++++ man/man7/regexp.html | 131 +++++ man/man7/thumbprint.html | 68 +++ man/man7/utf.html | 96 ++++ man/man9/attach.html | 107 ++++ man/man9/clunk.html | 66 +++ man/man9/error.html | 53 ++ man/man9/flush.html | 98 ++++ man/man9/index.html | 69 +++ man/man9/intro.html | 344 ++++++++++++ man/man9/open.html | 154 ++++++ man/man9/read.html | 96 ++++ man/man9/remove.html | 70 +++ man/man9/stat.html | 258 +++++++++ man/man9/version.html | 100 ++++ man/man9/walk.html | 119 ++++ 256 files changed, 44925 insertions(+) create mode 100644 man/index.html create mode 100644 man/man1/9.html create mode 100644 man/man1/9c.html create mode 100644 man/man1/9p.html create mode 100644 man/man1/9term.html create mode 100644 man/man1/acid.html create mode 100644 man/man1/acme.html create mode 100644 man/man1/acmeevent.html create mode 100644 man/man1/ascii.html create mode 100644 man/man1/astro.html create mode 100644 man/man1/basename.html create mode 100644 man/man1/bc.html create mode 100644 man/man1/bundle.html create mode 100644 man/man1/cal.html create mode 100644 man/man1/calendar.html create mode 100644 man/man1/cat.html create mode 100644 man/man1/cleanname.html create mode 100644 man/man1/clog.html create mode 100644 man/man1/cmp.html create mode 100644 man/man1/colors.html create mode 100644 man/man1/comm.html create mode 100644 man/man1/core.html create mode 100644 man/man1/crop.html create mode 100644 man/man1/date.html create mode 100644 man/man1/db.html create mode 100644 man/man1/dc.html create mode 100644 man/man1/deroff.html create mode 100644 man/man1/dial.html create mode 100644 man/man1/dict.html create mode 100644 man/man1/diff.html create mode 100644 man/man1/doctype.html create mode 100644 man/man1/echo.html create mode 100644 man/man1/ed.html create mode 100644 man/man1/eqn.html create mode 100644 man/man1/factor.html create mode 100644 man/man1/fmt.html create mode 100644 man/man1/fortune.html create mode 100644 man/man1/freq.html create mode 100644 man/man1/fsize.html create mode 100644 man/man1/grap.html create mode 100644 man/man1/graph.html create mode 100644 man/man1/grep.html create mode 100644 man/man1/gview.html create mode 100644 man/man1/gzip.html create mode 100644 man/man1/hoc.html create mode 100644 man/man1/idiff.html create mode 100644 man/man1/index.html create mode 100644 man/man1/intro.html create mode 100644 man/man1/join.html create mode 100644 man/man1/jpg.html create mode 100644 man/man1/kill.html create mode 100644 man/man1/label.html create mode 100644 man/man1/lex.html create mode 100644 man/man1/look.html create mode 100644 man/man1/ls.html create mode 100644 man/man1/man.html create mode 100644 man/man1/map.html create mode 100644 man/man1/mc.html create mode 100644 man/man1/mk.html create mode 100644 man/man1/mk9660.1 create mode 100644 man/man1/mkdir.html create mode 100644 man/man1/namespace.html create mode 100644 man/man1/news.html create mode 100644 man/man1/p.html create mode 100644 man/man1/page.html create mode 100644 man/man1/pic.html create mode 100644 man/man1/plot.html create mode 100644 man/man1/plumb.html create mode 100644 man/man1/pr.html create mode 100644 man/man1/proof.html create mode 100644 man/man1/ps.html create mode 100644 man/man1/psfonts.html create mode 100644 man/man1/pwd.html create mode 100644 man/man1/rc.html create mode 100644 man/man1/rio.html create mode 100644 man/man1/rm.html create mode 100644 man/man1/sam.html create mode 100644 man/man1/scat.html create mode 100644 man/man1/secstore.html create mode 100644 man/man1/sed.html create mode 100644 man/man1/seq.html create mode 100644 man/man1/sleep.html create mode 100644 man/man1/sort.html create mode 100644 man/man1/spell.html create mode 100644 man/man1/split.html create mode 100644 man/man1/src.html create mode 100644 man/man1/stats.html create mode 100644 man/man1/strings.html create mode 100644 man/man1/sum.html create mode 100644 man/man1/tail.html create mode 100644 man/man1/tbl.html create mode 100644 man/man1/tcs.html create mode 100644 man/man1/tee.html create mode 100644 man/man1/test.html create mode 100644 man/man1/time.html create mode 100644 man/man1/touch.html create mode 100644 man/man1/tr.html create mode 100644 man/man1/tr2post.html create mode 100644 man/man1/troff.html create mode 100644 man/man1/troff2html.1 create mode 100644 man/man1/troff2html.html create mode 100644 man/man1/tweak.html create mode 100644 man/man1/uniq.html create mode 100644 man/man1/units.html create mode 100644 man/man1/vac.html create mode 100644 man/man1/wc.html create mode 100644 man/man1/web.html create mode 100644 man/man1/wintext.html create mode 100644 man/man1/xd.html create mode 100644 man/man1/yacc.html create mode 100644 man/man3/9p-cmdbuf.html create mode 100644 man/man3/9p-fid.html create mode 100644 man/man3/9p-file.html create mode 100644 man/man3/9p-intmap.html create mode 100644 man/man3/9p.html create mode 100644 man/man3/9pclient.html create mode 100644 man/man3/addpt.html create mode 100644 man/man3/aes.html create mode 100644 man/man3/allocimage.html create mode 100644 man/man3/arg.html create mode 100644 man/man3/arith3.html create mode 100644 man/man3/atof.html create mode 100644 man/man3/bin.html create mode 100644 man/man3/bio.html create mode 100644 man/man3/blowfish.html create mode 100644 man/man3/cachechars.html create mode 100644 man/man3/cleanname.html create mode 100644 man/man3/color.html create mode 100644 man/man3/complete.html create mode 100644 man/man3/cputime.html create mode 100644 man/man3/ctime.html create mode 100644 man/man3/des.html create mode 100644 man/man3/dial.html create mode 100644 man/man3/dirread.html create mode 100644 man/man3/draw.html create mode 100644 man/man3/dsa.html create mode 100644 man/man3/dup.html create mode 100644 man/man3/elgamal.html create mode 100644 man/man3/encode.html create mode 100644 man/man3/errstr.html create mode 100644 man/man3/event.html create mode 100644 man/man3/exec.html create mode 100644 man/man3/exits.html create mode 100644 man/man3/fcall.html create mode 100644 man/man3/flate.html create mode 100644 man/man3/fmtinstall.html create mode 100644 man/man3/frame.html create mode 100644 man/man3/genrandom.html create mode 100644 man/man3/get9root.html create mode 100644 man/man3/getcallerpc.html create mode 100644 man/man3/getenv.html create mode 100644 man/man3/getfields.html create mode 100644 man/man3/getns.html create mode 100644 man/man3/getsnarf.html create mode 100644 man/man3/getuser.html create mode 100644 man/man3/getwd.html create mode 100644 man/man3/graphics.html create mode 100644 man/man3/html.html create mode 100644 man/man3/index.html create mode 100644 man/man3/intro.html create mode 100644 man/man3/ioproc.html create mode 100644 man/man3/ip.html create mode 100644 man/man3/isalpharune.html create mode 100644 man/man3/keyboard.html create mode 100644 man/man3/lock.html create mode 100644 man/man3/mach-cmd.html create mode 100644 man/man3/mach-file.html create mode 100644 man/man3/mach-map.html create mode 100644 man/man3/mach-stack.html create mode 100644 man/man3/mach-swap.html create mode 100644 man/man3/mach-symbol.html create mode 100644 man/man3/mach.html create mode 100644 man/man3/malloc.html create mode 100644 man/man3/matrix.html create mode 100644 man/man3/memdraw.html create mode 100644 man/man3/memlayer.html create mode 100644 man/man3/memory.html create mode 100644 man/man3/mouse.html create mode 100644 man/man3/mousescrollsize.html create mode 100644 man/man3/mp.html create mode 100644 man/man3/muldiv.html create mode 100644 man/man3/mux.html create mode 100644 man/man3/nan.html create mode 100644 man/man3/needstack.html create mode 100644 man/man3/notify.html create mode 100644 man/man3/open.html create mode 100644 man/man3/opentemp.html create mode 100644 man/man3/pipe.html create mode 100644 man/man3/plumb.html create mode 100644 man/man3/post9pservice.html create mode 100644 man/man3/postnote.html create mode 100644 man/man3/prime.html create mode 100644 man/man3/print.html create mode 100644 man/man3/proto.html create mode 100644 man/man3/pushtls.html create mode 100644 man/man3/qball.html create mode 100644 man/man3/quaternion.html create mode 100644 man/man3/quote.html create mode 100644 man/man3/rand.html create mode 100644 man/man3/rc4.html create mode 100644 man/man3/read.html create mode 100644 man/man3/regexp.html create mode 100644 man/man3/rfork.html create mode 100644 man/man3/rsa.html create mode 100644 man/man3/rune.html create mode 100644 man/man3/runestrcat.html create mode 100644 man/man3/sechash.html create mode 100644 man/man3/seek.html create mode 100644 man/man3/sendfd.html create mode 100644 man/man3/setjmp.html create mode 100644 man/man3/sleep.html create mode 100644 man/man3/stat.html create mode 100644 man/man3/strcat.html create mode 100644 man/man3/string.html create mode 100644 man/man3/stringsize.html create mode 100644 man/man3/subfont.html create mode 100644 man/man3/sysfatal.html create mode 100644 man/man3/thread.html create mode 100644 man/man3/time.html create mode 100644 man/man3/udpread.html create mode 100644 man/man3/wait.html create mode 100644 man/man3/wctl.html create mode 100644 man/man3/window.html create mode 100644 man/man4/9pserve.html create mode 100644 man/man4/acme.html create mode 100644 man/man4/import.html create mode 100644 man/man4/index.html create mode 100644 man/man4/intro.html create mode 100644 man/man4/plumber.html create mode 100644 man/man4/ramfs.html create mode 100644 man/man5/index.html create mode 100644 man/man7/color.html create mode 100644 man/man7/face.html create mode 100644 man/man7/font.html create mode 100644 man/man7/image.html create mode 100644 man/man7/index.html create mode 100644 man/man7/man.html create mode 100644 man/man7/map.html create mode 100644 man/man7/ms.html create mode 100644 man/man7/plot.html create mode 100644 man/man7/plumb.html create mode 100644 man/man7/regexp.html create mode 100644 man/man7/thumbprint.html create mode 100644 man/man7/utf.html create mode 100644 man/man9/attach.html create mode 100644 man/man9/clunk.html create mode 100644 man/man9/error.html create mode 100644 man/man9/flush.html create mode 100644 man/man9/index.html create mode 100644 man/man9/intro.html create mode 100644 man/man9/open.html create mode 100644 man/man9/read.html create mode 100644 man/man9/remove.html create mode 100644 man/man9/stat.html create mode 100644 man/man9/version.html create mode 100644 man/man9/walk.html (limited to 'man') diff --git a/man/index.html b/man/index.html new file mode 100644 index 00000000..3d00d11b --- /dev/null +++ b/man/index.html @@ -0,0 +1,45 @@ + + +Manual - Plan 9 from User Space + + + +
+
+ +
+
+
+ Manual - Plan 9 from User Space +
+
+
Section 1commands +
+
+
+
Section 3C library functions +
+
+
+
Section 4file servers +
+
+
+
Section 7file formats, protocols, and conventions +
+
+
+
Section 9Pthe Plan 9 file protocol +
+
+		 +
+ +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/9.html b/man/man1/9.html new file mode 100644 index 00000000..1ddef719 --- /dev/null +++ b/man/man1/9.html @@ -0,0 +1,100 @@ + +9(1) - Plan 9 from User Space + + + + +
+
+
9(1)9(1) +
+
+

NAME
+ +
+ + 9 – run Plan 9 commands
+ +
+

SYNOPSIS
+ +
+ + 9 cmd [ args ... ] +
+ + . 9
+ +
+

DESCRIPTION
+ +
+ + Because Plan 9 supplies commands with the same name as but different + behavior than many basic Unix system commands (e.g., grep, sed, + mkdir, rm), it is not recommended to run with the Plan 9 bin directory + ahead of the system directories. +
+ + 9 is a shell script that sets up a Plan 9 environment and runs + cmd . It sets $PLAN9 and adds $PLAN9/bin to the beginning of $PATH + before running cmd. +
+ + If run with no arguments, 9 does not do anything. This is so that + it can be invoked from sh-style shells using . 9 in order to make + the current shell start running in the Plan 9 environment.
+ +
+

EXAMPLES
+ +
+ + Search for greek in the password file:
+ +
+ + $ 9 grep '[α−ζ]' /etc/passwd
+ +
+ + +
+ Start an rc(1) with the Plan 9 commands in the path before the + system commands.
+ +
+ + 9 rc
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin/9
+ +
+

SEE ALSO
+ +
+ + intro(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/9c.html b/man/man1/9c.html new file mode 100644 index 00000000..894a34ae --- /dev/null +++ b/man/man1/9c.html @@ -0,0 +1,172 @@ + +9c(1) - Plan 9 from User Space + + + + +
+
+
9C(1)9C(1) +
+
+

NAME
+ +
+ + 9c, 9a, 9l, 9ar – C compiler, assembler, linker, archiver
+ +
+

SYNOPSIS
+ +
+ + 9c [ −I path ] [ −D name ] file ... +
+ + 9a file ... +
+ + 9l [ -o target ] object ... [ library ... ] [ −Lpath ... ] [ −lname + ... ] +
+ + 9ar key [ posname ] afile [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + These programs are shell scripts that invoke the appropriate standard + tools for the current operating system and architecture. One can + use them to write portable recipes for mkfiles. +
+ + 9c compiles the named C files into object files for the current + system. The system C compiler is invoked with warnings enabled. + The −I option adds path to the include path, and the −D option + defines name in the C preprocessor. 9c always defines the symbol + PLAN9PORT defined in the C preprocessor and adds + $PLAN9/include to the include path. +
+ + 9c also defines __sun__ on SunOS systems and __Linux26__ on Linux + systems with 2.6-series kernels. +
+ + 9a assembles the named files into object files for the current + system. Unlike some system assemblers, it does not promise to + run the C preprocessor on the source files. +
+ + 9l links the named object files and libraries to create the target + executable. Each −l option specifies that a library named libname.a + be found and linked. The −L option adds directories to the library + search path. 9l invokes the system linker with $PLAN9/lib already + on the library search path. +
+ + 9l searches the named objects and libraries for symbols of the + form __p9l_autolib_name, which it takes as indication that it + should link $PLAN9/lib/libname.a as well. It also examines such + libraries to find their own dependencies. A single −l option at + the beginning of the command line disables this + behavior. The symbol __p9l_autolib_name is added to an object + file by the macro AUTOLIB( name ), defined in <u.h>. Header files + associated with libraries contain AUTOLIB annotations; ordinary + programs need not use them. Due to shortcomings in the implementation, + a source file may not contain the + same AUTOLIB statement multiple times. +
+ + 9ar maintains object file archives called libraries. The exact + set of valid command keys varies from system to system, but 9ar + always provides the following key characters:
+ d     Delete files from the archive file.
+ r     Replace files in the archive file, or add them if missing.
+ t     List a table of contents of the archive. If names are given, + only those files are listed.
+ x     Extract the named files. If no names are given, all files in + the archive are extracted. In neither case does x alter the archive + file.
+ 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 + t, give a long listing of all information about the files, somewhat + like a listing by ls(1), showing
+ +
+ + +
+ + mode uid/gid size date name
+ +
+ +
+ c     Create. Normally 9ar will create a new archive when afile does + not exist, and give a warning. Option c discards any old contents + and suppresses the warning. +
+ + When a d, r, or m key is specified, 9ar inserts a table of contents, + required by the linker, at the front of the library. The table + of contents is rebuilt whenever the archive is modified.
+ +
+

EXAMPLES
+ +
+ + 9c file1.c file2.c file3.c
+ +
+ + Compile three C source files.
+ +
+ 9a file4.s
+ +
+ + Assemble one assembler source file.
+ +
+ 9ar rvc lib.a file[12].o
+ +
+ + Archive the first two object files into a library.
+ +
+ 9l −o prog file3.o file4.o lib.a
+ +
+ + Link the final two object files and any necessary objects from + the library into an executable.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/9p.html b/man/man1/9p.html new file mode 100644 index 00000000..449d0eb5 --- /dev/null +++ b/man/man1/9p.html @@ -0,0 +1,122 @@ + +9p(1) - Plan 9 from User Space + + + + +
+
+
9P(1)9P(1) +
+
+

NAME
+ +
+ + 9p – read and write files on a 9P server
+ +
+

SYNOPSIS
+ +
+ + 9p [ −a addr ] read path
+ 9p [ −a addr ] readfd path +
+ + 9p [ −a addr ] write path
+ 9p [ −a addr ] writefd path +
+ + 9p [ −a addr ] stat path
+ +
+

DESCRIPTION
+ +
+ + 9p is a trivial 9P client that can access a single file on a 9P + server. It can be useful for manual interaction with a 9P server + or for accessing simple 9P services from within shell scripts. + +
+ + The first argument is a command, one of:
+ readprint the contents of path to standard output
+ write
+ +
+ + write data on standard input to path
+ +
+ readfd, writefd
+ +
+ + like read and write but use openfd(9p) instead of open; this masks + errors and is mainly useful for debugging the implementation of + openfd
+ +
+ statexecute stat (9p) on path and print the result +
+ + 9p dials address to connect to the 9P server. If the −a option + is not given, 9p requires the path to be of the form service/subpath; + it connects to the Unix domain socket service in the name space + directory (see intro(4)) and then accesses subpath.
+ +
+

EXAMPLE
+ +
+ + To update plumber(4)’s copy of your plumbing rules after editing + $HOME/lib/plumbing:
+ +
+ + cat $HOME/lib/plumbing | 9p write plumb/rules
+ +
+ + +
+ To display the contents of the current acme(4) window:
+ +
+ + 9p read acme/$winid/body
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/9p.c
+ +
+

SEE ALSO
+ +
+ + intro(4), intro(9p), 9pclient(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/9term.html b/man/man1/9term.html new file mode 100644 index 00000000..7d6a741f --- /dev/null +++ b/man/man1/9term.html @@ -0,0 +1,259 @@ + +9term(1) - Plan 9 from User Space + + + + +
+
+
9TERM(1)9TERM(1) +
+
+

NAME
+ +
+ + 9term – terminal windows
+ +
+

SYNOPSIS
+ +
+ + 9term [ −as ] [ −f font ] [ cmd ... ]
+ +
+

DESCRIPTION
+ +
+ + 9term is a terminal window program for the X Window System, providing + an interface similar to that used on Plan 9.
+

Command
+ The 9term command starts a new window. +
+ + The −a flag causes button 2 to send the selection immediately, + like acme. Otherwise button 2 brings up a menu, described below. + +
+ + The −s option initializes windows so that text scrolls; the default + is not to scroll. +
+ + The font argument to −f names a font used to display text, both + in 9term’s menus and as a default for any programs running in + its windows; it also establishes the environment variable $font. + If −f is not given, 9term uses the imported value of $font if + set; otherwise it uses the graphics system default. +
+ + 9term runs the given command in the window, or $SHELL if no command + is given.
+

Text windows
+ Characters typed on the keyboard collect in the window to form + a long, continuous document. +
+ + There is always some selected 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 {[(<`'" on the left and }])>`'" + 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. +
+ + Characters typed on the keyboard replace the selected text; if + this text is not empty, it is placed in a snarf buffer common + to all windows but distinct from that of sam(1). +
+ + Programs access the text in the window at a single point maintained + automatically by 9term. The output point is the location in the + text where the next character written by a program to the terminal + 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. Since Unix does not make it possible to know when a + program is reading the terminal, lines are sent as they are completed + (when the user types a newline character). +
+ + 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 the terminal 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. Because of the + Unix issues mentioned above, a line of text is only editable until + it is completed with a newline character, or when hold mode (see + below) is enabled. +
+ + Even when there are newlines in the output text, 9term will not + honor reads if the window is in hold mode, which is indicated + by a white cursor and blue text and border. The ESC character + toggles hold mode. Some programs automatically turn on hold mode + to simplify the editing of multi-line text; type ESC when done + to allow mail to read the text. +
+ + 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. 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. +
+ + An ACK character (control-F) or Insert character triggers file + name completion for the preceding string (see complete(3)). +
+ + 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. + +
+ + Typing down-arrow scrolls forward one third of a window, and up-arrow + scrolls back. Typing page-down scrolls forward two thirds of a + window, and page-up scrolls back. Typing Home scrolls to the top + of the window; typing End scrolls to the end. +
+ + The DEL character sends an interrupt note to all processes in + the window’s process group. Unlike the other characters, the DEL + and arrow keys do not affect the selected text. The left (right) + arrow key moves the selection to one character before (after) + the current selection. +
+ + 9term relies on the kernel’s terminal processing to handle EOT + and DEL, so the terminal must be set up with EOT as the “eof” + character and DEL as the “intr” character. 9term runs stty(1) + to establish this when the terminal is created. +
+ + Normally, written output to a window blocks when the text reaches + the end of the screen and the terminal buffer fills; a button + 2 menu item toggles scrolling. +
+ + 9term changes behavior according to the terminal settings of the + running programs. Most programs run with echo enabled. In this + mode, 9term displays and allows editing of the input. Some programs, + typically those reading passwords, run with echo disabled. In + this mode, 9term passes keystrokes through directly, + without echoing them or buffering until a newline character. These + heuristics work well in many cases, but there are a few common + ones where they fall short. First, programs using the GNU readline + library typically disable terminal echo and perform echoing themselves. + The most common example is the shell + bash(1). Disabling the use of readline with “set +o emacs” [sic] + usually restores the desired behavior. Second, remote terminal + programs such as ssh(1) typically run with echo disabled, relying + on the remote system to echo characters as desired. Plan 9’s ssh + has a −C flag to disable this, leaving the terminal in + “cooked” mode. For similar situations on Unix, 9term’s button + 2 menu has an entry to toggle the forced use of cooked mode, despite + the terminal settings. In such cases, it is useful to run “stty + −echo” on the remote system to avoid seeing your input twice. + +
+ + Editing operations are selected from a menu on button 2. The cut + operation deletes the selected text from the screen and puts it + in the snarf buffer; snarf copies the selected text to the buffer + without deleting it; paste replaces the selected text with the + contents of the buffer; and send copies the snarf buffer to + just after the output point, adding a final newline if missing. + Paste will sometimes and 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. +
+ + The plumb menu item sends the contents of the selection (not the + snarf buffer) to the plumber (see plumb(1)). If the selection + is empty, it sends the white-space-delimited text containing the + selection (typing cursor). A typical use of this feature is to + tell the editor to find the source of an error by plumbing the + file and + line information in a compiler’s diagnostic. +
+ + Each 9term listens for connections on a Unix socket. When a client + connects, the 9term writes the window contents to the client and + then hangs up. 9term installs the name of this socket in the environment + as $text9term before running cmd.
+ +

+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/9term
+ +
+

BUGS
+ +
+ + There should be a program to toggle the current window’s hold + mode. +
+ + Unix makes everything harder.
+ +
+

SEE ALSO
+ +
+ + wintext(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/acid.html b/man/man1/acid.html new file mode 100644 index 00000000..f04c9baa --- /dev/null +++ b/man/man1/acid.html @@ -0,0 +1,486 @@ + +acid(1) - Plan 9 from User Space + + + + +
+
+
ACID(1)ACID(1) +
+
+

NAME
+ +
+ + acid, acidtypes – debugger
+ +
+

SYNOPSIS
+ +
+ + acid [ −l library ] [ −wq ] [ −m machine ] [ pid | core ] [ textfile + ] +
+ + acidtypes [ −p prefix ] file ...
+ +
+

DESCRIPTION
+ +
+ + 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 (a.out by default). + At the prompt, acid will store function definitions + or print the value of expressions. Options are
+ −w         Allow the textfile to be modified.
+ −q         Print variable renamings at startup.
+ −l library    Load from library at startup; see below.
+ −m machine   Assume instructions are for the given CPU type (see + mach(3)) instead of using the executable header to select the + CPU type.
+ −k         Debug the kernel state for the process, rather than the user + state. +
+ + At startup, acid obtains standard function definitions from the + library file /usr/local/plan9/acid/port, architecture-dependent + functions from /usr/local/plan9/acid/$objtype, user-specified + functions from $home/lib/acid, and further functions from −l files. + Definitions in any file may + override previously defined functions. If the function acidinit() + is defined, it will be invoked after all modules have been loaded. + Then the function acidmap() will be invoked if defined. /usr/local/plan9/acid/port + provides a definition of acidmap that attaches all the shared + libraries being used by the target + process and then runs acidtypes (q.v.) to create acid functions + for examining data structures.
+

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 main:argv. When program symbols conflict with acid + words, distinguishing $ signs are prefixed. Such + renamings are reported at startup; option −q suppresses them. + +
+ + Variable types (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 {} + and separated by commas. +
+ + 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.
+ +
+ + head list
+ tail list
+ append list, element
+ delete list, subscript +
+ + +
+ Format codes are the same as in db(1). Formats may be attached + to (unary) expressions with \, e.g. (32*7)\D. There are two indirection + operators, * to address a core image, @ 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. +
+ + Statements are
+ +
+ + if expr then statement [ else statement ]
+ while expr do statement
+ loop expr, expr do statement
+ defn name(args) { statement }
+ defn name
+ name(args)
+ builtin name(args)
+ local name
+ return expr
+ whatis [ name ] +
+ + +
+ The statement defn name clears the definition for name. A defn + may override a built-in function; prefixing a function call with + builtin ignores any overriding defn, forcing the use of the built-in + function. +
+ + Here is a partial list of functions; see the manual for a complete + list.
+ stk()          Print a stack trace for current process.
+ lstk()         Print a stack trace with values of local variables.
+ gpr()          Print general registers. Registers can also be accessed by + name, for example *R0.
+ spr()          Print special registers such as program counter and stack + pointer.
+ fpr()          Print floating-point registers.
+ regs()         Same as spr();gpr().
+ fmt(expr,format)
+ +
+ + +
+ + Expression expr with format given by the character value of expression + format.
+ +
+ +
+ src(address)     Print 10 lines of source around the program address.
+ Bsrc(address)    Get the source line for the program address into + a window of a running sam(1) and select it.
+ line(address)    Print source line nearest to the program address.
+ source()       List current source directories.
+ addsrcdir(string)
+ +
+ + +
+ + Add a source directory to the list.
+ +
+ +
+ filepc(where)   Convert a string of the form sourcefile:linenumber + to a machine address.
+ pcfile(address)Convert a machine address to a source file name.
+ pcline(address)Convert a machine address to a source line number.
+ bptab()        List breakpoints set in the current process.
+ bpset(address)   Set a breakpoint in the current process at the given + address. (Doesn’t work on Unix yet.)
+ bpdel(address)   Delete a breakpoint from the current process.
+ cont()         Continue execution of current process and wait for it to + stop.
+ step()         Execute a single machine instruction in the current process. + (Doesn’t work on Unix yet.)
+ func()         Step repeatedly until after a function return.
+ stopped(pid)    This replaceable function is called automatically + when the given process stops. It normally prints the program counter + and returns to the prompt.
+ asm(address)     Disassemble 30 machine instructions beginning at the + given address.
+ mem(address,string)
+ +
+ + +
+ + Print a block of memory interpreted according to a string of format + codes.
+ +
+ +
+ dump(address,n,string)
+ +
+ + +
+ + Like mem(), repeated for n consecutive blocks.
+ +
+ +
+ print(expr,...)   Print the values of the expressions.
+ newproc(arguments)
+ +
+ + +
+ + Start a new process with arguments given as a string and halt + at the first instruction.
+ +
+ +
+ new()          Like newproc(), but take arguments (except argv[0]) from + string variable progargs.
+ win()          Like new(), but run the process in a separate window.
+ start(pid)      Start a stopped process.
+ kill(pid)       Kill the given process.
+ setproc(pid)    Make the given process current.
+ rc(string)       Escape to the shell, rc(1), to execute the command string.
+ include(string)Read acid commands from the named file.
+ includepipe(string)
+ +
+ + +
+ + Run the command string, reading its standard output as acid commands.
+ +
+ +
+

Shared library segments
+ When a pid or core file is specified on the command line, acid + will, as part of its startup, determine the set of shared libraries + in use by the process image and map those at appropriate locations. + If acid is started without a pid or core file and is subsequently + attached to a process via setproc, the shared library maps + can be initialized by calling dynamicmap().
+

Type information
+ Unix compilers conventionally include detailed type information + in the debugging symbol section of binaries. The external program + acidtypes extracts this information and formats it as acid program + text. Once the shared libraries have been mapped, the default + acid startup invokes acidtypes (via + includepipe) on the set of currently mapped text files. The function + acidtypes() can be called to rerun the command after changing + the set of mapped text files.
+

Acid Libraries
+ There are a number of acid ‘libraries’ that provide higher-level + debugging facilities. One notable example is trump, which uses + acid to trace memory allocation. Trump requires starting acid + on the program, either by attaching to a running process or by + executing new() on a binary (perhaps after setting progargs), + stopping the process, and then running trump() to execute the + program under the scaffolding. The output will be a trace of the + memory allocation and free calls executed by the program. When + finished tracing, stop the process and execute untrump() followed + by cont() to resume execution. + +

+

EXAMPLES
+ +
+ + Start to debug /bin/ls; set some breakpoints; run up to the first + one (this example doesn’t work on Unix yet):
+ +
+ + % 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\s
+ acid: whatis argv0
+ integer variable format s
+ acid: *argv0
+ /bin/ls
+ acid: bpset(ls)
+ acid: cont()
+ 70094: breakpoint    ls      ADD    $−0x16c8,R29
+ acid:
+ +
+ + +
+ Display elements of a linked list of structures:
+ +
+ + complex Str { 'D' 0 val; 'X' 4 next; };
+ s = *headstr;
+ while s != 0 do{
+ +
+ + complex Str s;
+ print(s.val, "\n");
+ s = s.next;
+ +
+ }
+ +
+ + +
+ Note the use of the . operator instead of −>. +
+ + Display an array of bytes declared in C as char array[].
+ +
+ + *(array\s)
+ +
+ + +
+ This example gives array string format, then prints the string + beginning at the address (in acid notation) *array. +
+ + Trace the system calls executed by ls(1) (neither does this one):
+ +
+ + % 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()
+ +
+ +
+

FILES
+ +
+ + /usr/local/plan9/acid/$objtype
+ /usr/local/plan9/acid/port
+ /usr/local/plan9/acid/kernel
+ /usr/local/plan9/acid/trump
+ /usr/local/plan9/acid/truss
+ $home/lib/acid
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/acid
+ +
+

SEE ALSO
+ +
+ + mk(1), db(1)
+ Phil Winterbottom, “Acid Manual”.
+ +
+

DIAGNOSTICS
+ +
+ + At termination, kill commands are proposed for processes that + are still active.
+ +
+

BUGS
+ +
+ + There is no way to redirect the standard input and standard output + of a new process. +
+ + Source line selection near the beginning of a file may pick an + adjacent file. +
+ + With the extant stepping commands, one cannot step through instructions + outside the text segment and it is hard to debug across process + forks. +
+ + Breakpoints do not work yet. Therefore, commands such as step, + new, and truss do not work either. New in particular will need + some help to cope with dynamic libraries.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/acme.html b/man/man1/acme.html new file mode 100644 index 00000000..bc1063bd --- /dev/null +++ b/man/man1/acme.html @@ -0,0 +1,481 @@ + +acme(1) - Plan 9 from User Space + + + + +
+
+
ACME(1)ACME(1) +
+
+

NAME
+ +
+ + acme, win, awd – interactive text windows
+ +
+

SYNOPSIS
+ +
+ + acme [ −f varfont ] [ −F fixfont ] [ −c ncol ] [ −br ] [ −l file + | file ... ] +
+ + win [ command ] +
+ + awd [ label ]
+ +
+

DESCRIPTION
+ +
+ + 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 acme; + these are discussed in acme(4). +
+ + Any named files are read into acme windows before acme accepts + input. With the −l option, the state of the entire system is loaded + from file, which should have been created by a Dump command (q.v.), + and subsequent file names are ignored. Plain files display as + text; directories display as columnated lists of the + names of their components, as in ls −p directory|mc except that + the names of subdirectories have a slash appended. +
+ + The −f (−F) option sets the main font, usually variable-pitch + (alternate, usually fixed-pitch); the default is /usr/local/plan9/font/lucidasans/euro.8.font + (.../lucm/unicode.9.font). Tab intervals are set to the width + of 4 (or the value of $tabstop) numeral zeros in the appropriate + font. +
+ +

Windows
+ Acme windows are in two parts: a one-line tag above a multi-line + body. The body typically contains an image of a file, as in sam(1), + or the output of a program, as in an 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. +
+ + If a window holds a directory, the name (first word of the tag) + will end with a slash.
+

Scrolling
+ Each window has a scroll bar to the left of the body. The scroll + bar behaves much as in sam(1) or 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. (The experimental + option −r reverses the scrolling behavior of buttons 1 and 3, + to behave more like xterm(1).)
+

Layout
+ Acme windows are arranged in columns. By default, it creates two + columns when starting; this can be overridden with the −c option. + Placement is automatic but may be adjusted using the 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 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’: acme believes it is modified + from its original contents. +
+ + Tags exist at the top of each column and across the whole display. + Acme pre-loads them with useful commands. Also, the tag across + the top maintains a list of executing long-running commands.
+

Typing
+ The behavior of typed text is similar to that in 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 + causes typing to go to the most recently clicked-at or made window.) + The usual backspacing conventions apply. As in sam(1) but not + 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 Cut command (q.v.). +
+ + 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 acme.
+

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 /adm if the window holds /adm/users). This directory + provides a context for interpreting file names in that window. + For example, the string users in a window labeled /adm/ or + /adm/keys will be interpreted as the file name /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. /adm/not−a−file). File names beginning with a slash are + assumed to be absolute file names. +

Errors
+ Windows whose names begin with − or + conventionally hold diagnostics + and other data not directly associated with files. A window labeled + +Errors receives all diagnostics produced by acme itself. Diagnostics + from commands run by acme appear in a window named directory/+Errors + where directory is + identified by the context of the command. These error windows + are created when needed.
+

Mouse button 1
+ Mouse button 1 selects text just as in sam(1) or rio(1), including + the usual double-clicking conventions.
+

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’--indicates a null string--acme expands the + indicated text to find a command to run: if the click is within + button-1-selected text, 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 _ . − + /. This behavior is similar to double-clicking + with button 1 but, because a null command is meaningless, only + a single click is required. +
+ + Some commands, all by convention starting with a capital letter, + are built-ins that are executed directly by acme:
+ Cut   Delete most recently selected text and place in snarf buffer.
+ Del   Delete window. If window is dirty, instead print a warning; + a second Del will succeed.
+ Delcol
+ +
+ + Delete column and all its windows, after checking that windows + are not dirty.
+ +
+ Delete
+ +
+ + Delete window without checking for dirtiness.
+ +
+ DumpWrite the state of acme to the file name, if specified, or + $home/acme.dump by default.
+ EditTreat the argument as a text editing command in the style + of sam(1). The full Sam language is implemented except for the + commands k, n, q, and !. The = command is slightly different: + it includes the file name and gives only the line address unless + the command is explicitly =#. The ‘current window’ for the + +
+ + command is the body of the window in which the Edit command is + executed. Usually the Edit command would be typed in a tag; longer + commands may be prepared in a scratch window and executed, with + Edit itself in the current window, using the 2-1 chord described + below. + +
+ ExitExit acme after checking that windows are not dirty.
+ FontWith no arguments, change the font of the associated window + from fixed-spaced to proportional-spaced or vice 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 var + (fix), also set the default proportional-spaced + +
+ + (fixed-spaced) font for future use to that font. Other existing + windows are unaffected.
+ +
+ Get   Load file into window, replacing previous contents (after checking + for dirtiness as in 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.
+ ID    Print window ID number (q.v.).
+ InclWhen opening ‘include’ files (those enclosed in <>) with button + 3, acme searches in directories /$objtype/include and /sys/include. + Incl adds its arguments to a supplementary list of include directories, + analogous to the −I option to the compilers. This list is per-window + and is inherited when + +
+ + windows are created by actions in that window, so Incl is most + usefully applied to a directory containing relevant source. With + no arguments, Incl prints the supplementary list. This command + is largely superseded by plumbing (see plumb(7)).
+ +
+ KillSend a kill note to acme-initiated commands named as arguments.
+ Local
+ +
+ + In the Plan 9 acme, this prefix causes a command to be run in + acme’sown file name space and environment variable group. On Unix + this is impossible. Local is recognized as a prefix, but has no + effect on the command being executed.
+ +
+ LoadRestore the state of acme from a file (default $home/acme.dump) + created by the Dump command.
+ LookSearch in body for occurrence of literal text indicated by + the argument or, if none is given, by the selected text in the + body.
+ New   Make new window. With arguments, load the named files into + windows.
+ Newcol
+ +
+ + Make new column.
+ +
+ Paste
+ +
+ + Replace most recently selected text with contents of snarf buffer.
+ +
+ Put   Write window to the named file. With no argument, write to + the file named in the tag of the window.
+ Putall
+ +
+ + Write all dirty windows whose names indicate existing regular + files.
+ +
+ RedoComplement of Undo.
+ SendAppend selected text or snarf buffer to end of body; used + mainly with win.
+ Snarf
+ +
+ + Place selected text in snarf buffer.
+ +
+ SortArrange the windows in the column from top to bottom in lexicographical + order based on their names.
+ 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.
+ UndoUndo last textual change or set of changes.
+ Zerox
+ +
+ + Create a copy of the window containing most recently selected + text. +
+ + +
+ A common place to store text for commands is in the tag; in fact + acme maintains a set of commands appropriate to the state of the + window to the left of the bar in the tag. +
+ + If the text indicated with button 2 is not a recognized built-in, + it is executed as a shell command. For example, indicating date + with button 2 runs 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 /etc/passwd executing pwd + will produce the output /etc in a (possibly newly-created) window + labeled /etc/+Errors; in a window containing /home/rob/sam/sam.c + executing mk will run mk(1) in /home/rob/sam, producing output + in a window labeled + /home/rob/sam/+Errors. The environment of such commands contains + the variable $% with value set to the filename of the window in + which the command is run, and $winid set to the window’s id number + (see acme(4)).
+

Mouse button 3
+ Pointing at text with button 3 instructs 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, + 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. +
+ + If the text names an existing window, 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, acme loads the file + into a new window and moves the mouse there. If the text is a + file name contained in angle brackets, acme loads the + indicated include file from the directory appropriate to the suffix + of the file name of the window holding the text. (The Incl command + adds directories to the standard list.) +
+ + If the text begins with a colon, it is taken to be an address, + in the style of 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 acme, one must type :/regexp + or :127 not just /regexp or 127. (There is an easier + way to locate literal text; see below.) +
+ + If the text is a file name followed by a colon and an address, + acme loads the file and evaluates the address. For example, clicking + button 3 anywhere in the text file.c:27 will open 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. +
+ + 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. +
+ + 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.
+

Chords of mouse buttons
+ Several operations are bound to multiple-button actions. After + selecting text, with button 1 still down, pressing button 2 executes + Cut and button 3 executes Paste. After clicking one button, the + other undoes the first; thus (while holding down button 1) 2 followed + by 3 is a 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. +
+ + 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 text one may execute Look text with + button 2 or instead point at text with button 1 in any window, + release button 1, then execute Look, clicking button 1 while 2 + is held down. +
+ + When an external command (e.g. echo(1)) is executed this way, + the extra argument is passed as expected and an environment variable + $acmeaddr is created that holds, in the form interpreted by button + 3, the fully-qualified address of the extra argument.
+

Support programs
+ Win creates a new acme window and runs a command (default $SHELL) + in it, turning the window into something analogous to an rio(1) + window. Executing text in a win window with button 2 is similar + to using Send. +
+ + Awd loads the tag line of its window with the directory in which + it’s running, suffixed −label (default rc); it is intended to + be executed by a cd function for use in win windows. An example + definition is
+ +
+ + fn cd { builtin cd $1 && awd $sysname }
+ +
+

Applications and guide files
+ In the directory /acme live several subdirectories, each corresponding + to a program or set of related programs that employ acme’s user + interface. Each subdirectory includes source, binaries, and a + readme file for further information. It also includes a 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. +
+ + Whenever a command is executed by acme, the default search path + includes the directory of the window containing the command and + its subdirectory $cputype. The program directories in /acme contain + appropriately labeled subdirectories of binaries, so commands + named in the guide files will be found + automatically when run. Also, acme binds the directories /acme/bin + and /acme/bin/$cputype to the end of /bin when it starts; this + is where acme-specific programs such as win and awd reside.
+ +

+

FILES
+ +
+ + $home/acme.dump   default file for Dump and Load; also where state + is written if acme dies or is killed unexpectedly, e.g. by deleting + its window.
+ /acme/*/guide     template files for applications
+ /acme/*/readme    informal documentation for applications
+ /acme/*/src       source for applications
+ /acme/*/mips      MIPS-specific binaries for applications
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/acme
+ /usr/local/plan9/src/cmd/9term/win.c
+ /usr/local/plan9/bin/awd
+ +
+

SEE ALSO
+ +
+ + acme(4)
+ Rob Pike, Acme: A User Interface for Programmers.
+ +
+

BUGS
+ +
+ + With the −l option or Load command, the recreation of windows + under control of external programs such as win is just to rerun + the command; information may be lost.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/acmeevent.html b/man/man1/acmeevent.html new file mode 100644 index 00000000..230145ce --- /dev/null +++ b/man/man1/acmeevent.html @@ -0,0 +1,332 @@ + +acmeevent(1) - Plan 9 from User Space + + + + +
+
+
ACMEEVENT(1)ACMEEVENT(1) +
+
+

NAME
+ +
+ + acmeevent, acme.rc – shell script support for acme clients
+ +
+

SYNOPSIS
+ +
+ + 9p read acme/acme/$winid/event | acmeevent +
+ + . /usr/local/plan9/lib/acme.rc +
+ + newwindow +
+ + winread file +
+ + winwrite file +
+ + winctl cmd +
+ + windump [ dumpdir | − ] [ dumpcmd | − ] +
+ + winname name +
+ + windel [ sure ] +
+ + winwriteevent c1 c2 q0 q1 [ eq0 eq1 flag textlen text chordarg + chordaddr ] +
+ + wineventloop
+ +
+

DESCRIPTION
+ +
+ + Acmeevent and acme.rc make it easy to write simple acme(1) client + programs as shell scripts. +
+ + Acme clients read the event files (see acme(4)) for the windows + they control, reacting to the events. The events are presented + in a format that is easy to read with C programs but hard to read + with shell scripts. +
+ + Acmeevent reads an acme(4) event stream from standard input, printing + a shell-friendly version of the events, one per line, on standard + output. Each output line from acmeevent has the form:
+ +
+ + event c1 c2 q0 q1 eq0 eq1 flag textlen text chordarg chordaddr + +
+ + +
+ The fields are:
+ c1    A character indicating the origin or cause of the action. The + possible causes are: a write to the body or tag file (E), a write + to the window’s other files (F), input via the keyboard (K), and + input via the mouse (M).
+ c2    A character indicating the type of action. The possible types + are: text deleted from the body (D), text deleted from the tag + (d), text inserted in the body (I), text inserted in the tag (i), + a button 3 action in the body (L), a button 3 action in the tag + (l), a button 2 action in the body (X), and a button 2 action + in the + +
+ + tag (x).
+ +
+ q0, q1The character addresses of the action.
+ eq0, q1
+ +
+ + The expanded character addresses of the action. If the text indicated + by q0, q1 is a null string that has a non-null expansion, eq0, + eq1 are the addresses of the expansion. Otherwise they are the + same as q0, q1.
+ +
+ flag   Flag is a bitwise OR (reported decimally) of the following: + 1 if the text indicated is recognized as an acme built-in command; + 2 if the text indicated is a null string that has a non-null expansion + (see eq0, eq1 above); 8 if the command has an extra (chorded) + argument (see chordarg below). Flag remains from the + +
+ + acme(4) event format. Because eq0, eq1, and chordarg are explicit + in each event (unlike in acme(4) events), flag can usually be + ignored.
+ +
+ textlen
+ +
+ + The length of the action text (or its expansion) for button 2 + and button 3 events in characters.
+ +
+ text   If textlen is less than 256 chracters, text is the action + text itself. Otherwise it is an empty string and must be read + from the data file.
+ chordarg
+ +
+ + The chorded argument for an action.
+ +
+ chordorigin
+ +
+ + If the chord argument is in the body of a named window, chordorigin + specifies the full address of the argument, as in /etc/group:#123,#234. + +
+ + +
+ To experiment with acmeevent, create an empty window in acme (using + New),type
+ +
+ + 9p read acme/$winid/event | acmeevent
+ +
+ + +
+ inside it, and execute it. Actions performed on the window will + be printed as events in the +Errors window. +
+ + Acme.rc is a library of rc(1) shell functions useful for writing + acme clients. +
+ + Newwindow creates a new acme window and sets $winid to the new + window’s id. The other commands all use $winid to determine which + window to operate on. +
+ + Winread prints the current window’s file to standard output. It + is equivalent to cat /mnt/acme/acme/$winid/file on Plan 9. Similarly, + winwrite writes standard input to the current window’s file. Winread + and winwrite are useful mainly in building more complex functions. + +
+ + Winctl writes cmd to the window’s ctl file. The most commonly-used + command is clean, which marks the window as clean. See acme(4) + for a full list of commands. +
+ + Windump sets the window’s dump directory and dump command (see + acme(4)). If either argument is omitted or is −, that argument + is not set. +
+ + Winname sets the name displayed in the window’s tag. +
+ + Windel simulates the Del command. If the argument sure is given, + it simulates the Delete command. +
+ + Winwriteevent writes an event to the window’s event file. The + event is in the format produced by acmeevent. Only the first four + arguments are necessary: the rest are ignored. Event handlers + should call winwriteevent to pass unhandled button 2 or button + 3 events back to acme for processing. +
+ + Wineventloop executes the current window’s event file, as output + by acmeevent. It returns when the window has been deleted. Before + running wineventloop , clients must define a shell function named + event, which will be run for each incoming event, as rc executes + the output of acmeevent. A typical event function + need only worry about button 2 and button 3 events. Those events + not handled should be sent back to acme with winwriteevent.
+ +
+

EXAMPLE
+ +
+ + Adict, a dictionary browser, is implemented using acmeevent and + acme.rc. The event handler is:
+ +
+ + fn event {
+ +
+ + switch($1$2){
+ case Mx MX      # button 2 − pass back to acme
+ winwriteevent $*
+ case Ml ML      # button 3 − open new window on dictionary or entry
+ {
+ if(~ $dict NONE)
+ dictwin /adict/$7/ $7
+ if not
+ dictwin /adict/$dict/$7 $dict $7
+ } &
+ }
+ +
+ }
+ +
+ + +
+ Note that the button 3 handler starts a subshell in which to run + dictwin. That subshell will create a new window, set its name, + possibly fill the window with a dictionary list or dictionary + entry, mark the window as clean, and run the event loop:
+ +
+ + fn dictwin {
+ +
+ + newwindow
+ winname $1
+ dict=$2
+ if(~ $dict NONE)
+ dict −d '?' >[2=1] | sed 1d | winwrite body
+ if(~ $#* 3)
+ dict −d $dict $3 >[2=1] | winwrite body
+ winctl clean
+ wineventloop
+ +
+ }
+ +
+ + +
+ The script starts with an initial window:
+ +
+ + dictwin /adict/ NONE
+ +
+ + +
+ Button 3 clicking on a dictionary name in the initial window will + create a new empty window for that dictionary. Typing and button + 3 clicking on a word in that window will create a new window with + the dictionary’s entry for that word. +
+ + See /usr/local/plan9/bin/adict for the full implementation.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/acmeevent.c
+ /usr/local/plan9/lib/acme.rc
+ +
+

SEE ALSO
+ +
+ + acme(1), acme(4), rc(1)
+ +
+

BUGS
+ +
+ + There is more that could be done to ease the writing of complicated + clients.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/ascii.html b/man/man1/ascii.html new file mode 100644 index 00000000..4067eece --- /dev/null +++ b/man/man1/ascii.html @@ -0,0 +1,159 @@ + +ascii(1) - Plan 9 from User Space + + + + +
+
+
ASCII(1)ASCII(1) +
+
+

NAME
+ +
+ + ascii, unicode – interpret ASCII, Unicode characters
+ +
+

SYNOPSIS
+ +
+ + ascii [ −8 ] [ −oxdbn ] [ −nct ] [ text ] +
+ + unicode [ −nt ] hexmin−hexmax +
+ + unicode [ −t ] hex [ ... ] +
+ + unicode [ −n ] characters +
+ + look hex /usr/local/plan9/lib/unicode
+ +
+

DESCRIPTION
+ +
+ + Ascii prints the ASCII values corresponding to characters and + vice versa; under the −8 option, the ISO Latin-1 extensions (codes + 0200-0377) are included. The values are interpreted in a settable + numeric base; −o specifies octal, −d decimal, −x hexadecimal (the + default), and −bn base n. +
+ + With no arguments, ascii prints a table of the character set in + the specified base. Characters of text are converted to their + ASCII values, one per line. If, however, the first 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:
+ −n    Force numeric output.
+ −c    Force character output.
+ −t    Convert from numbers to running text; do not interpret control + characters or insert newlines. +
+ + Unicode is similar; it converts between UTF and character values + from the Unicode Standard (see utf(7)). If given a range of hexadecimal + numbers, unicode prints a table of the specified Unicode characters + -- their values and UTF representations. Otherwise it translates + from UTF to numeric value or vice versa, depending + on the appearance of the supplied text; the −n option forces numeric + output to avoid ambiguity with numeric characters. If converting + to UTF , the characters are printed one per line unless the −t + flag is set, in which case the output is a single string containing + only the specified characters. Unlike ascii, unicode treats + no characters specially. +
+ + The output of ascii and unicode may be unhelpful if the characters + printed are not available in the current font. +
+ + The file /usr/local/plan9/lib/unicode contains a table of characters + and descriptions, sorted in hexadecimal order, suitable for look(1) + on the lower case hex values of characters.
+ +
+

EXAMPLES
+ +
+ + ascii −d
+ +
+ + Print the ASCII table base 10.
+ +
+ unicode p
+ +
+ + Print the hex value of ‘p’.
+ +
+ unicode 2200−22f1
+ +
+ + Print a table of miscellaneous mathematical symbols.
+ +
+ look 039 /usr/local/plan9/lib/unicode
+ +
+ + See the start of the Greek alphabet’s encoding in the Unicode + Standard.
+ +
+ +
+

FILES
+ +
+ + /usr/local/plan9/lib/unicode
+ +
+ + table of characters and descriptions.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/ascii.c
+ /usr/local/plan9/src/cmd/unicode.c
+ +
+

SEE ALSO
+ +
+ + look(1), tcs(1), utf(7), font(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/astro.html b/man/man1/astro.html new file mode 100644 index 00000000..f410421c --- /dev/null +++ b/man/man1/astro.html @@ -0,0 +1,125 @@ + +astro(1) - Plan 9 from User Space + + + + +
+
+
ASTRO(1)ASTRO(1) +
+
+

NAME
+ +
+ + astro – print astronomical information
+ +
+

SYNOPSIS
+ +
+ + astro [ −dlpsatokm ] [ −c n ] [ −C d ] [ −e obj1 obj2 ]
+ +
+

DESCRIPTION
+ +
+ + Astro reports upcoming celestial events, by default for 24 hours + starting now. The options are:
+ d     Read the starting date. A prompt gives the input format.
+ l     Read the north latitude, west longitude, and elevation of the + observation point. A prompt gives the input format. If l is missing, + the initial position is read from the file /usr/local/plan9/sky/here.
+ c     Report for n (default 1) successive days.
+ C     Used with −c, set the interval to d days (or fractions of days).
+ e     Report distance between the centers of objects, in arc seconds, + during eclipses or occultations involving obj1 and obj2.
+ 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.
+ +
+ s     Print output in English words suitable for speech synthesizers.
+ 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.)
+ 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.
+ o     Search for stellar occultations.
+ k     Print times in local time (‘kitchen clock’) as described in the + timezone environment variable.
+ 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).
+ +
+

FILES
+ +
+ + /usr/local/plan9/sky/estartab
+ +
+ + ecliptic star data
+ +
+ /usr/local/plan9/sky/here
+ +
+ + default latitude (N), longitude (W), and elevation (meters)
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/astro
+ +
+

SEE ALSO
+ +
+ + scat(1)
+ +
+

BUGS
+ +
+ + The k option reverts to GMT outside of 1970-2036.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/basename.html b/man/man1/basename.html new file mode 100644 index 00000000..b04ce45d --- /dev/null +++ b/man/man1/basename.html @@ -0,0 +1,63 @@ + +basename(1) - Plan 9 from User Space + + + + +
+
+
BASENAME(1)BASENAME(1) +
+
+

NAME
+ +
+ + basename – strip file name affixes
+ +
+

SYNOPSIS
+ +
+ + basename [ −d ] string [ suffix ]
+ +
+

DESCRIPTION
+ +
+ + +
+ + Basename deletes any prefix ending in slash (/) and the suffix, + if present in string, from string, and prints the result on the + standard output. +
+ + The −d option instead prints the directory component, that is, + string up to but not including the final slash. If the string + contains no slash, a period and newline are printed.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/basename.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/bc.html b/man/man1/bc.html new file mode 100644 index 00000000..c4f7e7ba --- /dev/null +++ b/man/man1/bc.html @@ -0,0 +1,272 @@ + +bc(1) - Plan 9 from User Space + + + + +
+
+
BC(1)BC(1) +
+
+

NAME
+ +
+ + bc – arbitrary-precision arithmetic language
+ +
+

SYNOPSIS
+ +
+ + bc [ −c ] [ −l ] [ −s ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Bc is an interactive processor for a language that resembles C + but provides arithmetic on numbers of arbitrary length with up + to 100 digits right of the decimal point. It takes input from + any files given, then reads the standard input. The −l argument + stands for the name of an arbitrary precision math library. The + −s + argument suppresses the automatic display of calculation results; + all output is via the print command. +
+ + The following syntax for bc programs is like that of C; L means + letter a-z, E means expression, S means statement.
+ Lexical
+ +
+ + +
+ + comments are enclosed in /* */
+ newlines end statements
+ +
+ +
+ Names
+ +
+ + +
+ + simple variables: L
+ array elements: L[E]
+ The words ibase, obase, and scale
+ +
+ +
+ Other operands
+ +
+ + +
+ + arbitrarily long numbers with optional sign and decimal point.
+ (E)
+ sqrt(E)
+ length(E)
+ number of significant decimal digits
+ scale(E)
+ number of digits right of decimal point
+ L(E,...,E)
+ function call
+ +
+ +
+ Operators
+ +
+ + +
+ + +    −    *    /    %    ^ (% is remainder; ^ is power)
+ ++    −−
+ ==    <=    >=    !=    <    >
+ =    +=    −=    *=    /=    %=    ^=
+ +
+ +
+ Statements
+ +
+ + +
+ + E
+ { S ; ... ; S }
+ print E
+ if ( E ) S
+ while ( E ) S
+ for ( E ; E ; E ) S
+ null statement
+ break
+ quit
+ "text"
+ +
+ +
+ Function definitions
+ +
+ + +
+ + define L ( L , ... , L ){
+ auto L , ... , L
+ S ; ... ; S
+ return E +
+ + }
+ +
+ +
+ Functions in    −l math library
+ +
+ + +
+ + s(x)sine
+ c(x)cosine
+ e(x)exponential
+ l(x)log
+ a(x)arctangent
+ j(n, x)
+ Bessel function
+ +
+ + +
+ +
+ All function arguments are passed by value. +
+ + The value of an expression at the top level is printed unless + the main operator is an assignment or the −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 scale influences the number of digits to + be retained on arithmetic operations in the manner of dc(1). Assignments + to ibase or obase set the input and output number radix respectively. + +
+ + 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. +
+ + Bc is actually a preprocessor for dc(1), which it invokes automatically, + unless the −c (compile only) option is present. In this case the + dc input is sent to the standard output instead.
+ +
+

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.) +
+ + 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)
+ +
+

FILES
+ +
+ + /usr/local/plan9/lib/bclib mathematical library
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/bc.y
+ +
+

SEE ALSO
+ +
+ + dc(1), hoc(1)
+ +
+

BUGS
+ +
+ + No &&, ||, or ! operators. +
+ + A for statement must have all three Es. +
+ + A quit is interpreted when read, not when executed.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/bundle.html b/man/man1/bundle.html new file mode 100644 index 00000000..4f052d42 --- /dev/null +++ b/man/man1/bundle.html @@ -0,0 +1,95 @@ + +bundle(1) - Plan 9 from User Space + + + + +
+
+
BUNDLE(1)BUNDLE(1) +
+
+

NAME
+ +
+ + bundle – collect files for distribution
+ +
+

SYNOPSIS
+ +
+ + bundle file ...
+ +
+

DESCRIPTION
+ +
+ + Bundle writes on its standard output a shell script for rc(1) + or a Bourne shell which, when executed, will recreate the original + files. Its main use is for distributing small numbers of text + files by mail(1). +
+ + Although less refined than standard archives from 9ar (see 9c(1)) + or tar(1), a bundle file is self-documenting and complete; little + preparation is required on the receiving machine.
+ +
+

EXAMPLES
+ +
+ + bundle mkfile *.[ch] | mail kremvax!boris
+ +
+ + Send a makefile to Boris together with related .c and .h files. + Upon receiving the mail, Boris may save the file sans postmark, + say in gift/horse, then do
+ +
+ cd gift; sh horse; mk
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin/bundle
+ +
+

SEE ALSO
+ +
+ + 9ar (in 9c(1)), tar(1), mail(1)
+ +
+

BUGS
+ +
+ + Bundle will not create directories and is unsatisfactory for non-text + files. +
+ + Beware of gift horses.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/cal.html b/man/man1/cal.html new file mode 100644 index 00000000..ec3cffc2 --- /dev/null +++ b/man/man1/cal.html @@ -0,0 +1,81 @@ + +cal(1) - Plan 9 from User Space + + + + +
+
+
CAL(1)CAL(1) +
+
+

NAME
+ +
+ + cal – print calendar
+ +
+

SYNOPSIS
+ +
+ + cal [ month ] [ year ]
+ +
+

DESCRIPTION
+ +
+ + Cal prints a calendar. 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. Year can be between 1 and 9999. If either month + or 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. +
+ + Try
+ +
+ + cal sep 1752
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/cal.c
+ +
+

BUGS
+ +
+ + The year is always considered to start in January even though + this is historically naive. +
+ + Beware that cal 90 refers to the early Christian era, not the + 20th century.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/calendar.html b/man/man1/calendar.html new file mode 100644 index 00000000..48b9816b --- /dev/null +++ b/man/man1/calendar.html @@ -0,0 +1,82 @@ + +calendar(1) - Plan 9 from User Space + + + + +
+
+
CALENDAR(1)CALENDAR(1) +
+
+

NAME
+ +
+ + calendar – print upcoming events
+ +
+

SYNOPSIS
+ +
+ + calendar [ –y ] [ –p days ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Calendar reads the named files, default $HOME/lib/calendar, and + writes to standard output any lines containing today’s or tomorrow’s + date. Examples of recognized date formats are "4/11", "April 11", + "Apr 11", "11 April", and "11 Apr". All comparisons are case insensitive. + +
+ + If the –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. + +
+ + If the –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. +
+ + On Friday and Saturday, events through Monday are printed. +
+ + To have your calendar mailed to you every day, use cron(8).
+ +
+

FILES
+ +
+ + $HOME/lib/calendar   personal calendar
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/calendar.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/cat.html b/man/man1/cat.html new file mode 100644 index 00000000..36d6923e --- /dev/null +++ b/man/man1/cat.html @@ -0,0 +1,126 @@ + +cat(1) - Plan 9 from User Space + + + + +
+
+
CAT(1)CAT(1) +
+
+

NAME
+ +
+ + cat, read, nobs – catenate files
+ +
+

SYNOPSIS
+ +
+ + cat [ file ... ]
+ read [ −m ] [ −n nline ] [ file ... ]
+ nobs [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Cat reads each file in sequence and writes it on the standard + output. Thus
+ +
+ + cat file +
+ + +
+ prints a file and
+ +
+ + cat file1 file2 >file3 +
+ + +
+ concatenates the first two files and places the result on the + third. +
+ + If no file is given, cat reads from the standard input. Output + is buffered in blocks matching the input. +
+ + Read copies to standard output exactly one line from the named + file, default standard input. It is useful in interactive rc(1) + scripts. +
+ + The −m flag causes it to continue reading and writing multiple + lines until end of file; −n causes it to read no more than nline + lines. +
+ + Read always executes a single 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. +
+ + Nobs copies the named files to standard output except that it + removes all backspace characters and the characters that precede + them. It is useful to use as $PAGER with the Unix version of man(1) + when run inside a win (see acme(1)) window.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/cat.c
+ /usr/local/plan9/src/cmd/read.c
+ /usr/local/plan9/bin/nobs
+ +
+

SEE ALSO
+ +
+ + cp(1)
+ +
+

DIAGNOSTICS
+ +
+ + Read exits with status eof on end of file or, in the −n case, + if it doesn’t read nlines lines.
+ +
+

BUGS
+ +
+ + Beware of cat a b >a and cat a b >b, which destroy input files before + reading them.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/cleanname.html b/man/man1/cleanname.html new file mode 100644 index 00000000..8f736fbd --- /dev/null +++ b/man/man1/cleanname.html @@ -0,0 +1,65 @@ + +cleanname(1) - Plan 9 from User Space + + + + +
+
+
CLEANNAME(1)CLEANNAME(1) +
+
+

NAME
+ +
+ + cleanname – clean a path name
+ +
+

SYNOPSIS
+ +
+ + cleanname [ −d pwd ] names ...
+ +
+

DESCRIPTION
+ +
+ + For each file name argument, 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 . and .. directory components + in the name. If the −d option is present, unrooted names are + prefixed with pwd/ before processing.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/cleanname.c
+ +
+

SEE ALSO
+ +
+ + cleanname(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/clog.html b/man/man1/clog.html new file mode 100644 index 00000000..6c12e0be --- /dev/null +++ b/man/man1/clog.html @@ -0,0 +1,61 @@ + +clog(1) - Plan 9 from User Space + + + + +
+
+
CLOG(1)CLOG(1) +
+
+

NAME
+ +
+ + auxclog – create date-stamped console log
+ +
+

SYNOPSIS
+ +
+ + auxclog console logfile
+ +
+

DESCRIPTION
+ +
+ + Auxclog opens the file console and writes every line read from + it, prefixed by the ASCII time, to the file logfile.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/auxclog.c
+ +
+

BUGS
+ +
+ + Should be named aux/clog.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/cmp.html b/man/man1/cmp.html new file mode 100644 index 00000000..cc7831a9 --- /dev/null +++ b/man/man1/cmp.html @@ -0,0 +1,84 @@ + +cmp(1) - Plan 9 from User Space + + + + +
+
+
CMP(1)CMP(1) +
+
+

NAME
+ +
+ + cmp – compare two files
+ +
+

SYNOPSIS
+ +
+ + cmp [ −lsL ] file1 file2 [ offset1 [ offset2 ] ]
+ +
+

DESCRIPTION
+ +
+ + The two files are compared. A diagnostic results if the contents + differ, otherwise there is no output. +
+ + The options are:
+ l     Print the byte number (decimal) and the differing bytes (hexadecimal) + for each difference.
+ s     Print nothing for differing files, but set the exit status.
+ L     Print the line number of the first differing byte. +
+ + If offsets are given, comparison starts at the designated byte + position of the corresponding file. Offsets that begin with 0x + are hexadecimal; with 0, octal; with anything else, decimal.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/cmp.c
+ +
+

SEE ALSO
+ +
+ + diff(1)
+ +
+

DIAGNOSTICS
+ +
+ + If a file is inaccessible or missing, the exit status is 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 EOF. Otherwise cmp reports the position of the + first disagreeing byte and the exit status is differ. + +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/colors.html b/man/man1/colors.html new file mode 100644 index 00000000..af67eec2 --- /dev/null +++ b/man/man1/colors.html @@ -0,0 +1,92 @@ + +colors(1) - Plan 9 from User Space + + + + +
+
+
COLORS(1)COLORS(1) +
+
+

NAME
+ +
+ + colors, cmapcube – display color map
+ +
+

SYNOPSIS
+ +
+ + +
+ + colors [ −r −x ] +
+ + cmapcube [ −nbw ]
+ +
+

DESCRIPTION
+ +
+ + Colors presents a grid showing the colors in the RGBV color map + (see color(7)). +
+ + 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 allocimage(3). + If the −x option is specified, the components will also be listed + in hexadecimal. +
+ + The −r option instead shows, in the same form, a grey-scale ramp. + +
+ + A menu on mouse button 3 contains a single entry, to exit the + program. +
+ + Cmapcube presents the same colors but in a 3-dimensional cube. + Dragging with button 1 rotates the cube. Clicking on a color with + button 2 displays the map index for that color. Clicking button + 3 exits. +
+ + The −n option disables drawing of the color squares. The −b and + −w options set the background (default grey) to black or white.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/draw/colors.c
+ +
+

SEE ALSO
+ +
+ + color(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/comm.html b/man/man1/comm.html new file mode 100644 index 00000000..860a0956 --- /dev/null +++ b/man/man1/comm.html @@ -0,0 +1,79 @@ + +comm(1) - Plan 9 from User Space + + + + +
+
+
COMM(1)COMM(1) +
+
+

NAME
+ +
+ + comm – select or reject lines common to two sorted files
+ +
+

SYNOPSIS
+ +
+ + comm [ −123 ] file1 file2
+ +
+

DESCRIPTION
+ +
+ + Comm reads file1 and file2, which are in lexicographical order, + and produces a three column output: lines only in file1; lines + only in file2; and lines in both files. The file name − means + the standard input. +
+ + Flag 1, 2, or 3 suppresses printing of the corresponding column.
+ +
+

EXAMPLE
+ +
+ + comm −12 file1 file2
+ +
+ + Print lines common to two sorted files.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/comm.c
+ +
+

SEE ALSO
+ +
+ + sort(1), cmp(1), diff(1), uniq(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/core.html b/man/man1/core.html new file mode 100644 index 00000000..9c1cf3df --- /dev/null +++ b/man/man1/core.html @@ -0,0 +1,83 @@ + +core(1) - Plan 9 from User Space + + + + +
+
+
CORE(1)CORE(1) +
+
+

NAME
+ +
+ + core – print information about dead processes
+ +
+

SYNOPSIS
+ +
+ + core [ dir | corefile ]...
+ +
+

DESCRIPTION
+ +
+ + Core prints information about dead processes that have been saved + as core dumps. +
+ + Core reads its arguments in order. If a directory is encountered, + core reads every core file named core.* or *.core in that directory. + +
+ + For each core file read, core prints the date and time the core + was generated, the command that generated it, and a short stack + trace at the time of the core dump. +
+ + If no arguments are given, core searches the directory $COREDIR + for core files; if $COREDIR is not set, core searches the current + directory.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/core.c
+ +
+

SEE ALSO
+ +
+ + acid(1), db(1), core(5)
+ +
+

BUGS
+ +
+ + Core has not been written.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/crop.html b/man/man1/crop.html new file mode 100644 index 00000000..34a4eefb --- /dev/null +++ b/man/man1/crop.html @@ -0,0 +1,127 @@ + +crop(1) - Plan 9 from User Space + + + + +
+
+
CROP(1)CROP(1) +
+
+

NAME
+ +
+ + crop, iconv – frame, crop, and convert image
+ +
+

SYNOPSIS
+ +
+ + crop [ −c red green blue ] [ −i n | −x dx | −y dy | −r minx miny + maxx maxy ] [ −t tx ty ] [ −b red green blue ] [ file ] +
+ + iconv [ −u ] [ −c chandesc ] [ file ]
+ +
+

DESCRIPTION
+ +
+ + Crop reads an image(7) file (default standard input), crops it, + and writes it as a compressed image(7) file to standard output. + There are two ways to specify a crop, by color value or by geometry. + They may be combined in a single run of crop, in which case the + color value crop will be done first. +
+ + The −c option takes a red-green-blue triplet as described in color(3). + (For example, white is 255 255 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. + +
+ + The −i option insets the image rectangle by a constant amount, + n, which may be negative to generate extra space around the image. + The −x and −y options are similar, but apply only to the x or + y coordinates of the image. +
+ + The −r option specifies an exact rectangle. +
+ + The −t option specifies that the image’s coordinate system should + be translated by tx, ty as the last step of processing. +
+ + The −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 −i option is given a negative argument. This can + be used to draw a monochrome frame around the image. The default + color is black. +
+ + Iconv changes the format of pixels in the image file (default + standard input) and writes the resulting image to standard output. + Pixels in the image are converted according to the channel descriptor + chandesc, (see image(7)). For example, to convert a 4-bit-per-pixel + grey-scale image to an 8-bit-per-pixel color-mapped + image, chandesc should be m8. If chandesc is not given, the format + is unchanged. The output image is by default compressed; the −u + option turns off the compression.
+ +
+

EXAMPLE
+ +
+ + To crop white edges off the picture and add a ten-pixel pink border,
+ +
+ + crop −c 255 255 255 −i −10 −b 255 150 150 imagefile > cropped
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/draw/crop.c
+ +
+

SEE ALSO
+ +
+ + image(7), color(3)
+ +
+

BUGS
+ +
+ + Iconv should be able to do Floyd-Steinberg error diffusion or + dithering when converting to small image depths.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/date.html b/man/man1/date.html new file mode 100644 index 00000000..a8cbbf9a --- /dev/null +++ b/man/man1/date.html @@ -0,0 +1,75 @@ + +date(1) - Plan 9 from User Space + + + + +
+
+
DATE(1)DATE(1) +
+
+

NAME
+ +
+ + date – date and time
+ +
+

SYNOPSIS
+ +
+ + date [ option ] [ seconds ]
+ +
+

DESCRIPTION
+ +
+ + Print the date, in the format +
+ + +
+ + Tue Aug 16 17:03:52 CDT 1977 +
+ + +
+ The options are
+ −u    Report Greenwich Mean Time (GMT) rather than local time.
+ −n    Report the date as the number of seconds since the epoch, 00:00:00 + GMT, January 1, 1970. +
+ + The conversion from Greenwich Mean Time to local time depends + on the $timezone environment variable; see ctime(3). +
+ + If the optional argument seconds is present, it is used as the + time to convert rather than the real time.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/date.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/db.html b/man/man1/db.html new file mode 100644 index 00000000..eed2c3f9 --- /dev/null +++ b/man/man1/db.html @@ -0,0 +1,548 @@ + +db(1) - Plan 9 from User Space + + + + +
+
+
DB(1)DB(1) +
+
+

NAME
+ +
+ + db – debugger
+ +
+

SYNOPSIS
+ +
+ + db [ option ... ] [ textfile ] [ pid | corefile ]
+ +
+

DESCRIPTION
+ +
+ + Db is a general purpose debugging program. It may be used to examine + files and to provide a controlled environment for the execution + of programs. +
+ + A textfile is a file containing the text and initialized data + of an executable program. A pid or corefile specifies the memory + image of a process. A pid gives the id of an executing process + to be accessed via ptrace(2). A corefile specifies the name of + a core dump (see core(5) on your system of choice) containing + the + memory image of a terminated process. This manual refers to the + memory image specified by pid or corefile as a memfile. +
+ + A map associated with each textfile or memfile supports accesses + to instructions and data in the file; see ‘Addresses’. +
+ + An argument consisting entirely of digits is assumed to be a process + id; otherwise, it is the name of a textfile or corefile. When + a textfile is given, the textfile map is associated with it. If + only a memfile is given, the textfile map is derived from the + corresponding textfile, if it can be determined (this varies from + system to + system). When a memfile is given, the memfile map is associated + with it; otherwise the map is undefined and accesses to it are + not permitted. +
+ + Commands to db are read from the standard input and responses + are to the standard output. The options are
+ −w    Open textfile and memfile for writing as well as reading.
+ −Ipath
+ +
+ + Directory in which to look for relative path names in $< and $<< + commands.
+ +
+ −mmachine
+ +
+ + Assume instructions are for the given CPU type (possible names + include 386 and powerpc; adding the suffix −co as in 386−co and + powerpc−co selects disassembly in the manufacturer’s syntax, if + available, rather than the default Plan 9 syntax). +
+ + +
+ Most db commands have the following form:
+ +
+ + [address] [, count] [command] +
+ + +
+ If address is present then the current position, called ‘dot’, + is set to address. Initially dot is set to 0. Most commands are + repeated count times with dot advancing between repetitions. The + default count is 1. Address and count are expressions. Multiple + commands on one line must be separated by ;. +

Expressions
+ Expressions are evaluated as long ints.
+ .     The value of dot.
+ +     The value of dot incremented by the current increment.
+ ^     The value of dot decremented by the current increment.
+ "     The last address typed.
+ integer
+ +
+ + A number, in decimal radix by default. The prefixes 0 and 0o and + 0O (zero oh) force interpretation in octal radix; the prefixes + 0t and 0T force interpretation in decimal radix; the prefixes + 0x, 0X, and # force interpretation in hexadecimal radix. Thus + 020, 0o20, 0t16, and #10 all represent sixteen. + +
+ integer.fraction
+ +
+ + A single-precision floating point number.
+ +
+ 'c'   The 16-bit value of a character. \ may be used to escape a + '.
+ <name
+ +
+ + The value of name, which is a register name. The register names + are those printed by the $r command.
+ +
+ symbol
+ +
+ + A symbol is a sequence of upper or lower case letters, underscores + or digits, not starting with a digit. \ may be used to escape + other characters. The location of the symbol is calculated from + the symbol table in textfile.
+ +
+ routine.name
+ +
+ + The address of the variable name in the specified C routine. Both + routine and name are symbols. If name is omitted the value is + the address of the most recently activated stack frame corresponding + to routine; if routine is omitted, the active procedure is assumed.
+ +
+ 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.
+ +
+ (exp)
+ +
+ + The value of the expression exp. +
+ + +
+ Monadic operators
+ +
+ + *exp   The contents of the location addressed by exp in memfile.
+ @exp   The contents of the location addressed by exp in textfile.
+ −exp   Integer negation.
+ ~exp   Bitwise complement.
+ %exp   When used as an address, exp is an offset into the segment + named ublock; see ‘Addresses’.
+ +
+ + +
+ Dyadic operators are left-associative and are less binding than + monadic operators.
+ +
+ + e1+e2Integer addition.
+ e1−e2Integer subtraction.
+ e1*e2Integer multiplication.
+ e1%e2Integer division.
+ e1&e2Bitwise conjunction.
+ e1|e2Bitwise disjunction.
+ e1#e2E1 rounded up to the next multiple of e2.
+ +
+

Commands
+ Most commands have the following syntax:
+ ?f    Locations starting at address in textfile are printed according + to the format f.
+ /f    Locations starting at address in memfile are printed according + to the format f.
+ =f    The value of address itself is printed according to the format + f. +
+ + A 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. +
+ + 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 currentincrement.
+ +
+ + o     Print two-byte integer in octal.
+ O     Print four-byte integer in octal.
+ q     Print two-byte integer in signed octal.
+ Q     Print four-byte integer in signed octal.
+ d     Print two-byte integer in decimal.
+ D     Print four-byte integer in decimal.
+ V     Print eight-byte integer in decimal.
+ Z     Print eight-byte integer in unsigned decimal.
+ x     Print two-byte integer in hexadecimal.
+ X     Print four-byte integer in hexadecimal.
+ Y     Print eight-byte integer in hexadecimal.
+ u     Print two-byte integer in unsigned decimal.
+ U     Print four-byte integer in unsigned decimal.
+ f     Print as a single-precision floating point number.
+ F     Print double-precision floating point.
+ b     Print the addressed byte in hexadecimal.
+ c     Print the addressed byte as an ASCII character.
+ C     Print the addressed byte as a character. Printable ASCII characters + are represented normally; others are printed in the form \xnn.
+ s     Print the addressed characters, as a UTF string, until a zero + byte is reached. Advance dot by the length of the string, including + the zero terminator.
+ S     Print a string using the escape convention (see C above).
+ r     Print as UTF the addressed two-byte integer (rune).
+ R     Print as 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.
+ i     Print as machine instructions. Dot is incremented by the size + of the instruction.
+ I     As i above, but print the machine instructions in an alternate + form if possible.
+ M     Print the addressed machine instruction in a machine-dependent + hexadecimal form.
+ a     Print the value of dot in symbolic form. Dot is unaffected.
+ A     Print the value of dot in hexadecimal. Dot is unaffected.
+ z     Print the function name, source file, and line number corresponding + to dot (textfile only). Dot is unaffected.
+ p     Print the addressed value in symbolic form. Dot is advanced by + the size of a machine address.
+ t     When preceded by an integer, tabs to the next appropriate tab + stop. For example, 8t moves to the next 8-space tab stop. Dot + is unaffected.
+ n     Print a newline. Dot is unaffected.
+ "..."   Print the enclosed string. Dot is unaffected.
+ ^     Dot is decremented by the current increment. Nothing is printed.
+ +     Dot is incremented by 1. Nothing is printed.
+ −     Dot is decremented by 1. Nothing is printed.
+ +
+ + +
+ Other commands include:
+ newline
+ +
+ + Update dot by the current increment. Repeat the previous command + with a count of 1.
+ +
+ [?/]l value mask
+ +
+ + Words starting at dot are masked with mask and compared with value + until a match is found. If l is used, the match is for a two-byte + integer; L matches four bytes. If no match is found then dot is + unchanged; otherwise dot is set to the matched location. If mask + is omitted then ~0 is used. + +
+ [?/]w value ...
+ +
+ + Write the two-byte value into the addressed location. If the command + is W, write four bytes.
+ +
+ [?/]m s b e f [?]
+ +
+ + New values for (b, e, f) in the segment named s are recorded. + Valid segment names are text, data, or ublock. If less than three + address expressions are given, the remaining parameters are left + unchanged. If the list is terminated by ? or / then the file (textfile + or memfile respectively) is used for subsequent + requests. For example, /m? causes / to refer to textfile.
+ +
+ >name
+ +
+ + Dot is assigned to the variable or register named.
+ +
+ !     The rest of the line is passed to rc(1) for execution.
+ $modifier
+ +
+ + Miscellaneous commands. The available modifiers are:
+ <f    Read commands from the file f. If this command is executed in + a file, further commands in the file are not seen. If f is omitted, + the current input stream is terminated. If a count is given, and + is zero, the command is ignored.
+ <<f   Similar to < 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 << files that can be open at once.
+ >f    Append output to the file f, which is created if it does not + exist. If f is omitted, output is returned to the terminal.
+ ?     Print process id, the condition which caused stopping or termination, + the registers and the instruction addressed by pc. This is the + default if modifier is omitted.
+ r     Print the general registers and the instruction addressed by + pc. Dot is set to pc.
+ R     Like $r, but include miscellaneous processor control registers + and floating point registers.
+ f     Print floating-point register values as single-precision floating + point numbers.
+ F     Print floating-point register values as double-precision floating + point numbers.
+ b     Print all breakpoints and their associated counts and commands. + ‘B’ produces the same results.
+ c     Stack backtrace. If address is given, it specifies the address + of a pair of 32-bit values containing the sp and pc of an active + process. This allows selecting among various contexts of a multi-threaded + process. If C is used, the names and (long) values of all parameters, + automatic and static variables are + +
+ + printed for each active function. If count is given, only the + first count frames are printed.
+ +
+ a     Attach to the running process whose pid is contained in address.
+ e     The names and values of all external variables are printed.
+ w     Set the page width for output to address (default 80).
+ q     Exit from db.
+ m     Print the address maps.
+ k     Simulate kernel memory management.
+ Mmachine
+ +
+ + Set the machine type used for disassembling instructions.
+ +
+ +
+ :modifier
+ +
+ + Manage a subprocess. Available modifiers are:
+ h     Halt an asynchronously running process to allow breakpointing. + Unnecessary for processes created under db, e.g. by :r.
+ bc    Set breakpoint at address. The breakpoint is executed count–1 + times before causing a stop. Also, if a command c is given it + is executed at each breakpoint and if it sets dot to zero the + breakpoint causes a stop.
+ d     Delete breakpoint at address.
+ r     Run textfile as a subprocess. If address is given the program + is entered at that point; otherwise the standard entry point is + used. 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.
+ +
+ cs    The subprocess is continued. If 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 r. + ss    As for c except that the subprocess is single stepped for count + machine instructions. If a note is pending, it is received before + the first instruction is executed. If there is no current subprocess + then textfile is run as a subprocess as for r. In this case no + note can be sent; the remainder of the line is + +
+ + treated as arguments to the subprocess.
+ +
+ Ss    Identical to s except the subprocess is single stepped for count + lines of C source. In optimized code, the correspondence between + C source and the machine instructions is approximate at best.
+ x     The current subprocess, if any, is released by db and allowed + to continue executing normally.
+ k     The current subprocess, if any, is terminated.
+ nc    Display the pending notes for the process. If c is specified, + first delete c’th pending note.
+ +
+

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 (t, f, b, e, o), defining a segment named + t (usually, text, data, or core) in file f mapping addresses in + the range b through e to the part of the file beginning at + offset o. If segments overlap, later segments obscure earlier + ones. An address a is translated to a file address by finding + the last segment in the list for which b≤a<e; the location in the + file is then address+f–b. +
+ + Usually, the text and initialized data of a program are mapped + by segments called text, data, and bss. Since a program file does + not contain stack data, this data is not mapped. The text segment + is mapped similarly in a normal (i.e., non-kernel) memfile. However, + one or more segments called data provide access to + process memory. This region contains the program’s static data, + the bss, the heap and the stack. +
+ + 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 an + entire file to be examined without address translation. +
+ + The $m command dumps the currently active maps. The ?m and /m + commands modify the segment parameters in the textfile and memfile + maps, respectively.
+ +

+

EXAMPLES
+ +
+ + To set a breakpoint at the beginning of write() in extant process + 27:
+ +
+ + % db 27
+ :h
+ write:b
+ :c
+ +
+ + +
+ To set a breakpoint at the entry of function parse when the local + variable argc in main is equal to 1:
+ +
+ + parse:b *main.argc−1=X
+ +
+ + +
+ This prints the value of argc−1 which as a side effect sets dot; + when argc is one the breakpoint will fire. Beware that local variables + may be stored in registers; see the BUGS section.
+ +
+

SEE ALSO
+ +
+ + acid(1)
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/db
+ +
+

DIAGNOSTICS
+ +
+ + Exit status is 0, unless the last command failed or returned non-zero + status.
+ +
+

BUGS
+ +
+ + Examining a local variable with routine.name returns the contents + of the memory allocated for the variable, but with optimization, + variables often reside in registers. Also, on some architectures, + the first argument is always passed in a register. +
+ + Variables and parameters that have been optimized away do not + appear in the symbol table, returning the error bad local variable + when accessed by db. +
+ + 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.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/dc.html b/man/man1/dc.html new file mode 100644 index 00000000..95b7fd24 --- /dev/null +++ b/man/man1/dc.html @@ -0,0 +1,199 @@ + +dc(1) - Plan 9 from User Space + + + + +
+
+
DC(1)DC(1) +
+
+

NAME
+ +
+ + dc – desk calculator
+ +
+

SYNOPSIS
+ +
+ + dc [ file ]
+ +
+

DESCRIPTION
+ +
+ + 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 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:
+ number
+ +
+ + The value of the number is pushed on the stack. A number is an + unbroken string of the digits 0−9A−F or 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 _ to + input a negative number. Numbers may contain decimal points.
+ +
+ +    − /    *    %    ^
+ +
+ + Add +, subtract −, multiply *, divide /, remainder %, or exponentiate + ^ 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.
+ +
+ sx
+ Sx    Pop the top of the stack and store into a register named x, + where x may be any character. Under operation S register x is + treated as a stack and the value is pushed on it.
+ lx
+ Lx    Push the value in register x onto the stack. The register x + is not altered. All registers start with zero value. Under operation + L register x is treated as a stack and its top value is popped + onto the main stack.
+ d     Duplicate the top value on the stack.
+ p     Print the top value on the stack. The top value remains unchanged. + P interprets the top of the stack as an text string, removes it, + and prints it.
+ f     Print the values on the stack.
+ q
+ Q     Exit the program. If executing a string, the recursion level + is popped by two. Under operation Q the top value on the stack + is popped and the string execution level is popped by that value.
+ x     Treat the top element of the stack as a character string and + execute it as a string of dc commands.
+ X     Replace the number on the top of the stack with its scale factor.
+ [ ... ]
+ +
+ + Put the bracketed text string on the top of the stack.
+ +
+ <x
+ >x
+ =x    Pop and compare the top two elements of the stack. Register + x is executed if they obey the stated relation.
+ 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.
+ !     Interpret the rest of the line as a shell command.
+ c     Clear the stack.
+ i     The top value on the stack is popped and used as the number base + for further input.
+ I     Push the input base on the top of the stack.
+ 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.
+ O     Push the output base on the top of the stack.
+ 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. + z     Push the stack level onto the stack.
+ Z     Replace the number on the top of the stack with its length.
+ ?     A line of input is taken from the input source (usually the terminal) + and executed.
+ ; :   Used by bc for array operations. +
+ + The scale factor set by k determines how many digits are kept + to the right of the decimal point. If s is the current scale factor, + sa is the scale of the first operand, sb is the scale of the second, + and b is the (integer) second operand, results are truncated to + the following scales.
+ +
+ + +,−     max(sa,sb)
+ *      min(sa+sb , max(s,sa,sb))
+ /      s
+ %      so that dividend = divisor*quotient + remainder; remainder has + sign of dividend
+ ^      min(sa×|b|, max(s,sa))
+ v      max(s,sa)
+ +
+ +
+

EXAMPLES
+ +
+ + +
+ + Print the first ten values of n!
+ +
+ + [la1+dsa*pla10>y]sy
+ 0sa1
+ lyx
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/dc.c
+ +
+

SEE ALSO
+ +
+ + bc(1), hoc(1)
+ +
+

DIAGNOSTICS
+ +
+ + x is unimplemented, where x is an octal number: an internal error.
+ ‘Out of headers’ for too many numbers being kept around.
+ ‘Nesting depth’ for too many levels of nested execution.
+ +
+

BUGS
+ +
+ + When the input base exceeds 16, there is no notation for digits + greater than F. +
+ + Past its time.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/deroff.html b/man/man1/deroff.html new file mode 100644 index 00000000..cb0c5aff --- /dev/null +++ b/man/man1/deroff.html @@ -0,0 +1,102 @@ + +deroff(1) - Plan 9 from User Space + + + + +
+
+
DEROFF(1)DEROFF(1) +
+
+

NAME
+ +
+ + deroff, delatex – remove formatting requests
+ +
+

SYNOPSIS
+ +
+ + deroff [ option ... ] file ... +
+ + delatex file
+ +
+

DESCRIPTION
+ +
+ + Deroff reads each file in sequence and removes all nroff and troff(1) + requests and non-text arguments, backslash constructions, and + constructs of preprocessors such as eqn(1), pic(1), and tbl(1). + Remaining text is written on the standard output. Deroff follows + files included by .so and .nx commands; if a file has + already been included, a .so for that file is ignored and a .nx + terminates execution. If no input file is given, deroff reads + from standard input. +
+ + The options are
+ −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.
+ −_    Like −w, but consider underscores to be alphanumeric rather + than punctuation.
+ −i    Ignore .so and .nx requests.
+ −ms
+ −mm   Remove titles, attachments, etc., as well as ordinary troff + constructs, from ms(7) or mm documents.
+ −ml   Same as −mm, but remove lists as well. +
+ + Delatex does for tex and latex (see tex(1)) files what deroff + −wi does for troff files.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/deroff.c
+ /usr/local/plan9/src/cmd/delatex.lx
+ +
+

SEE ALSO
+ +
+ + troff(1), tex(1), spell(1)
+ +
+

BUGS
+ +
+ + These filters are not complete interpreters of troff or tex. For + example, macro definitions containing \$ cause chaos in deroff + when the popular $$ delimiters for eqn are in effect. +
+ + Text inside macros is emitted at place of definition, not place + of call.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/dial.html b/man/man1/dial.html new file mode 100644 index 00000000..70456274 --- /dev/null +++ b/man/man1/dial.html @@ -0,0 +1,67 @@ + +dial(1) - Plan 9 from User Space + + + + +
+
+
DIAL(1)DIAL(1) +
+
+

NAME
+ +
+ + dial – connect to a remote service
+ +
+

SYNOPSIS
+ +
+ + dial [ −e ] addr
+ +
+

DESCRIPTION
+ +
+ + Dial connects to the network address addr (see dial(3)) and then + copies data from the connection to standard output, and from standard + input to the connection. +
+ + By default, dial exits when end of file is reached on standard + input or on the network connection. The −e flag causes dial to + exit only in response to end of file on the network connection.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/dial.c
+ +
+

SEE ALSO
+ +
+ + dial(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/dict.html b/man/man1/dict.html new file mode 100644 index 00000000..48d086ba --- /dev/null +++ b/man/man1/dict.html @@ -0,0 +1,168 @@ + +dict(1) - Plan 9 from User Space + + + + +
+
+
DICT(1)DICT(1) +
+
+

NAME
+ +
+ + dict, adict – dictionary browser
+ +
+

SYNOPSIS
+ +
+ + dict [ −k ] [ −d dictname ] [ −c command ] [ pattern ] adict [ + −d dictname ] [ pattern ]
+ +
+

DESCRIPTION
+ +
+ + Dict is a dictionary browser. If a pattern is given on the command + line, dict prints all matching entries; otherwise it repeatedly + accepts and executes commands. The options are
+ −d dictname   Use the given dictionary. A list of available dictionaries + is printed by option −d?. The default is the first dictionary + on the list that is installed on the system.
+ −c command   Execute one command and quit. The command syntax is + described below.
+ −k          Print a pronunciation key. +
+ + Patterns are regular expressions (see regexp(7)), with an implicit + leading ^ and trailing $. 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. + +
+ + Commands have an address followed by a command letter. Addresses + have the form:
+ /re/     Set the match set to all entries matching the regular expression + re, sorted in dictionary order. Set the current entry to the first + of the match set.
+ !re!     Like /re/ but use exact matching, i.e., without case and accent + folding.
+ n       An integer n means change the current entry to the nth of the + current match set.
+ #n      The integer n is an absolute byte offset into the raw dictionary. + (See the A command, below.)
+ addr+    After setting the match set and current entry according to + 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.
+ addr−    Like addr+ but go to previous dictionary entry. +
+ + 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.
+ p,P    Print the whole entry.
+ h,H    Print only the headword(s) of the entry.
+ a,A    Print the dictionary byte offset of the entry.
+ r,R    Print the whole entry in raw format (without translating special + characters, etc.). +
+ + If no command letter is given for the first command, H is assumed. + After an H, the default command is p. Otherwise, the default command + is the previous command. +
+ + Adict is a dictionary browser for acme(1). When run with no arguments, + it creates a new acme window named /adict/ listing the installed + dictionaries. Clicking with button 3 on a dictionary name will + create a new empty window named /adict/dict/. Typing and then + clicking on a pattern in this window will create + a new lookup window named /adict/dict/pattern containing the dictionary’s + definition of pattern. Clicking with button 3 on any word in this + new window will create new lookup windows. +
+ + If adict is run with a pattern , it starts with the /adict/dict/pattern + window. +
+ + If adict is run with no pattern but with a −d option, it starts + with the /adict/dict/ window.
+ +
+

FILES
+ +
+ + /usr/local/plan9/dict
+ +
+ + dictionaries
+ +
+ +
+

SEE ALSO
+ +
+ + regexp(7)
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/dict
+ /usr/local/plan9/bin/adict
+ +
+

BUGS
+ +
+ + A font with wide coverage of the Unicode Standard should be used + for best results. (Try /usr/local/plan9/font/pelm/unicode.9.font.) + +
+ + If the pattern doesn’t begin with a few literal characters, matching + takes a long time. +
+ + The dictionaries are not distributed outside Bell Labs, though + see /usr/local/plan9/dict/README for information on using free + dictionaries prepared by Project Gutenberg.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/diff.html b/man/man1/diff.html new file mode 100644 index 00000000..c5e824be --- /dev/null +++ b/man/man1/diff.html @@ -0,0 +1,141 @@ + +diff(1) - Plan 9 from User Space + + + + +
+
+
DIFF(1)DIFF(1) +
+
+

NAME
+ +
+ + diff – differential file comparator
+ +
+

SYNOPSIS
+ +
+ + diff [ −efmnbwr ] file1 ... file2
+ +
+

DESCRIPTION
+ +
+ + 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 diff for text + files and + cmp(1) otherwise. If more than two file names are given, then + each argument is compared to the last argument as above. The −r + option causes diff to process similarly named subdirectories recursively. + When processing more than one file, diff prefixes file differences + with a single line listing the two differing files, in + the form of a diff command line. The −m flag causes this behavior + even when processing single files. +
+ + The normal output contains lines of these forms:
+ +
+ + n1 a n3,n4
+ n1,n2 d n3
+ n1,n2 c n3,n4 +
+ + +
+ These lines resemble ed commands to convert file1 into file2. + The numbers after the letters pertain to file2. In fact, by exchanging + ‘a’ for ‘d’ and reading backward one may ascertain equally how + to convert file2 into file1. As in ed, identical pairs where n1 + = n2 or n3 = n4 are abbreviated as a single number. +
+ + 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 ‘>’. +
+ + The −b option causes trailing blanks (spaces and tabs) to be ignored + and other strings of blanks to compare equal. The −w option causes + all white-space to be removed from input lines before applying + the difference algorithm. +
+ + The −n option prefixes each range with file: and inserts a space + around the a, c, and d verbs. The −e option produces a script + of a, c and d commands for the editor ed, which will recreate + file2 from file1. The −f option produces a similar script, not + useful with ed, in the opposite order. It may, however, be useful + as + input to a stream-oriented post-processor. +
+ + Except in rare circumstances, diff finds a smallest sufficient + set of file differences.
+ +
+

FILES
+ +
+ + /tmp/diff[12]
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/diff
+ +
+

SEE ALSO
+ +
+ + cmp(1), comm(1), ed(1)
+ +
+

DIAGNOSTICS
+ +
+ + Exit status is the empty string for no differences, some for some, + and error for trouble.
+ +
+

BUGS
+ +
+ + Editing scripts produced under the −e or −f option are naive about + creating lines consisting of a single ‘.’. +
+ + When running diff on directories, the notion of what is a text + file is open to debate.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/doctype.html b/man/man1/doctype.html new file mode 100644 index 00000000..f837d915 --- /dev/null +++ b/man/man1/doctype.html @@ -0,0 +1,88 @@ + +doctype(1) - Plan 9 from User Space + + + + +
+
+
DOCTYPE(1)DOCTYPE(1) +
+
+

NAME
+ +
+ + doctype – intuit command line for formatting a document
+ +
+

SYNOPSIS
+ +
+ + doctype [ −n ] [ −T dev ] [ file ] ...
+ +
+

DESCRIPTION
+ +
+ + Doctype examines a troff(1) input file to deduce the appropriate + text formatting command and prints it on standard output. Doctype + recognizes input for troff(1), related preprocessors like eqn(1), + and the ms(7) and mm macro packages. +
+ + Option −n invokes nroff instead of troff. The −T option is passed + to troff.
+ +
+

EXAMPLES
+ +
+ + eval `{doctype chapter.?} | lp
+ +
+ + Typeset files named chapter.0, chapter.1, ...
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin/doctype
+ +
+

SEE ALSO
+ +
+ + troff(1), eqn(1), tbl(1), pic(1), grap(1), ms(7), man(7)
+ +
+

BUGS
+ +
+ + In true A.I. style, its best guesses are inspired rather than + accurate.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/echo.html b/man/man1/echo.html new file mode 100644 index 00000000..a4f6e359 --- /dev/null +++ b/man/man1/echo.html @@ -0,0 +1,62 @@ + +echo(1) - Plan 9 from User Space + + + + +
+
+
ECHO(1)ECHO(1) +
+
+

NAME
+ +
+ + echo – print arguments
+ +
+

SYNOPSIS
+ +
+ + echo [ −n ] [ arg ... ]
+ +
+

DESCRIPTION
+ +
+ + Echo writes its arguments separated by blanks and terminated by + a newline on the standard output. Option −n suppresses the newline.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/echo.c
+ +
+

DIAGNOSTICS
+ +
+ + If echo draws an error while writing to standard output, the exit + status is write error. Otherwise the exit status is empty.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/ed.html b/man/man1/ed.html new file mode 100644 index 00000000..a259b9bc --- /dev/null +++ b/man/man1/ed.html @@ -0,0 +1,439 @@ + +ed(1) - Plan 9 from User Space + + + + +
+
+
ED(1)ED(1) +
+
+

NAME
+ +
+ + ed – text editor
+ +
+

SYNOPSIS
+ +
+ + ed [ − ] [ −o ] [ file ]
+ +
+

DESCRIPTION
+ +
+ + Ed is a venerable text editor. +
+ + If a file argument is given, ed simulates an e command (see below) + on that file: it is read into ed’s buffer so that it can be edited. + The options are
+ −     Suppress the printing of character counts by e, r, and w commands + and of the confirming ! by ! commands.
+ −o    (for output piping) Write all output to the standard error file + except writing by w commands. If no file is given, make /dev/stdout + the remembered file; see the e command below. +
+ + 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 w (write) + command is given. The copy of the text being edited resides in + a temporary file called the buffer. +
+ + Commands to ed have a simple and regular structure: zero, one, + or two addresses followed by a single character command, possibly + followed by parameters to the command. These addresses specify + one or more lines in the buffer. Missing addresses are supplied + by default. +
+ + In general, only one command may appear on a line. Certain commands + allow the addition of text to the buffer. While ed is accepting + text, it is said to be in input mode. In this mode, no commands + are recognized; all input is merely collected. Input mode is left + by typing a period . alone at the beginning of a line. +
+ + Ed supports the regular expression notation described in regexp(7). + Regular expressions are used in addresses to specify lines and + in one command (see 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 ‘\’. This also applies to the character + bounding the regular expression (often /) and to \ itself. +
+ + To understand addressing in ed it is necessary to know that at + any time there is a 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. + 1.    The character ., customarily called ‘dot’, addresses the current + line.
+ 2.    The character $ addresses the last line of the buffer.
+ 3.    A decimal number n addresses the n-th line of the buffer.
+ 4.    'x addresses the line marked with the name x, which must be + a lower-case letter. Lines are marked with the k command.
+ 5.    A regular expression enclosed in slashes ( /) 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.
+ 6.    A regular expression enclosed in queries ? 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.
+ 7.    An address followed by a plus sign + or a minus sign − followed + by a decimal number specifies that address plus (resp. minus) + the indicated number of lines. The plus sign may be omitted.
+ 8.    An address followed by + (or −) 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 + may be omitted, so 0/x/ addresses the first line in the + buffer with an x. Enclosing the regular expression in + +
+ + ? reverses the search direction.
+ +
+ 9.    If an address begins with + or − the addition or subtraction + is taken with respect to the current line; e.g. −5 is understood + to mean .−5.
+ 10.   If an address ends with + or −, then 1 is added (resp. subtracted). + As a consequence of this rule and rule 9, the address − refers + to the line before the current line. Moreover, trailing + and + − characters have cumulative effect, so −− refers to the current + line less 2.
+ 11.   To maintain compatibility with earlier versions of the editor, + the character ^ in addresses is equivalent to −. +
+ + 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. +
+ + Addresses are separated from each other typically by a comma ,. + They may also be separated by a semicolon ;. 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. +
+ + In the following list of 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.
+ (.)a
+ <text>
+ .     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 0 is legal for this command; text + is placed at the beginning of the buffer.
+ (.,.)b[+−][pagesize][pln]
+ +
+ + Browse. Print a ‘page’, normally 20 lines. The optional + (default) + or − specifies whether the next or previous page is to be printed. + The optional pagesize is the number of lines in a page. The optional + p, n, or l causes printing in the specified format, initially + p. Pagesize and format are remembered between b + commands. Dot is left at the last line displayed.
+ +
+ (.,.)c
+ <text>
+ .     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.
+ (.,.)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.
+ +
+ 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 e, r, or w commands. If + filename is missing, the remembered name is used. + +
+ E filename
+ +
+ + Unconditional e; see ‘q’ below.
+ +
+ f filename
+ +
+ + Print the currently remembered file name. If filename is given, + the currently remembered file name is first changed to filename.
+ +
+ (1,$)g/regular expression/command list
+ (1,$)g/regular expression/
+ (1,$)g/regular expression
+ +
+ + Global. First mark every line which matches the given regularexpression. + Then for every such line, execute the 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 \. The ‘.’ terminating input mode for an a, i, c + command may be omitted if it would be on the last line of the + command list. The commands g and v are not permitted in the command + list. Any character other than space or newline may be used instead + of / to delimit the regular expression. + The second and third forms mean g/regular expression/p.
+ +
+ (.)i
+ <text>
+ .     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 a command only + in the placement of the text.
+ (.,.+1)j
+ +
+ + Join the addressed lines into a single line; intermediate newlines + are deleted. Dot is left at the resulting line.
+ +
+ (.)kxMark the addressed line with name x, which must be a lower-case + letter. The address form 'x then addresses this line.
+ (.,.)l
+ +
+ + List. Print the addressed lines in an unambiguous way: a tab is + printed as \t, a backspace as \b, backslashes as \\, and non-printing + characters as a backslash, an 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 \n. An l may be appended, + like p, to any non-I/O command.
+ +
+ (.,.)ma
+ +
+ + Move. Reposition the addressed lines after the line addressed + by a. Dot is left at the last moved line.
+ +
+ (.,.)n
+ +
+ + Number. Perform p, prefixing each line with its line number and + a tab. An n may be appended, like p, to any non-I/O command.
+ +
+ (.,.)p
+ +
+ + Print the addressed lines. Dot is left at the last line printed. + A p appended to any non-I/O command causes the then current line + to be printed after the command is executed.
+ +
+ (.,.)P
+ +
+ + This command is a synonym for p.
+ +
+ q     Quit the editor. No automatic write of a file is done. A q or + e command is considered to be in error if the buffer has been + modified since the last w, q, or e command.
+ Q     Quit unconditionally.
+ ($)r filename
+ +
+ + Read in the given file after the addressed line. If no 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. + +
+ (.,.)sn/regular expression/replacement/
+ (.,.)sn/regular expression/replacement/g
+ (.,.)sn/regular expression/replacement
+ +
+ + Substitute. Search each addressed line for an occurrence of the + specified regular expression. On each line in which n matches + are found (n defaults to 1 if missing), the nth matched string + is replaced by the replacement specified. If the global replacement + indicator 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 / to delimit the + regular expression and the replacement. Dot is left at the last + line substituted. The third form means + sn/regular expression/replacement/p. The second / may be omitted + if the replacement is empty.
+ An ampersand & appearing in the replacement is replaced by the + string matching the regular expression. The characters \n, where + n is a digit, are replaced by the text matched by the n-th regular + subexpression enclosed between ( and ). When nested parenthesized + subexpressions are present, n is + determined by counting occurrences of ( starting from the left.
+ A literal &, /, \ or newline may be included in a replacement by + prefixing it with \.
+ +
+ (.,.)ta
+ +
+ + Transfer. Copy the addressed lines after the line addressed by + a. Dot is left at the last line of the copy.
+ +
+ (.,.)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).
+ +
+ (1,$)v/regular expression/command list
+ +
+ + This command is the same as the global command g except that the + command list is executed with dot initially set to every line + except those matching the regular expression.
+ +
+ (1,$)w filename
+ +
+ + 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 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.
+ +
+ (1,$)W filename
+ +
+ + Perform w, but append to, instead of overwriting, any existing + file contents.
+ +
+ ($)=   Print the line number of the addressed line. Dot is unchanged.
+ !shell command
+ +
+ + Send the remainder of the line after the ! to rc(1) to be interpreted + as a command. Dot is unchanged.
+ +
+ (.+1)<newline>
+ +
+ + An address without a command is taken as a p command. A terminal + / may be omitted from the address. A blank line alone is equivalent + to .+1p; it is useful for stepping through text. +
+ + +
+ If an interrupt signal (DEL) is sent, ed prints a ? and returns + to its command level. +
+ + When reading a file, ed discards NUL characters and all characters + after the last newline.
+ +
+

FILES
+ +
+ + /tmp/e*
+ ed.hup work is saved here if terminal hangs up
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/ed.c
+ +
+

SEE ALSO
+ +
+ + sam(1), sed(1), regexp(7)
+ +
+

DIAGNOSTICS
+ +
+ + ?name for inaccessible file; ?TMP for temporary file overflow; + ? for errors in commands or other overflows.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/eqn.html b/man/man1/eqn.html new file mode 100644 index 00000000..3d819235 --- /dev/null +++ b/man/man1/eqn.html @@ -0,0 +1,203 @@ + +eqn(1) - Plan 9 from User Space + + + + +
+
+
EQN(1)EQN(1) +
+ +
+ + +
+ + delim $$
+ +
+ +
+

NAME
+ +
+ + eqn – typeset mathematics
+ +
+

SYNOPSIS
+ +
+ + eqn [ option ... ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Eqn is a troff(1) preprocessor for typesetting mathematics on + a typesetter. Usage is almost always
+ +
+ + eqn file ... | troff +
+ + +
+ If no files are specified, eqn reads from the standard input. + Eqn prepares output for the typesetter named in the −Tdest option + (default −Tutf; see troff(1)). When run with other preprocessor + filters, eqn usually comes last. +
+ + A line beginning with .EQ marks the start of an equation; the + end of an equation is marked by a line beginning with .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 + eqn input. Delimiters may be set to characters x and y with the + option −dxy or (more commonly) with delim xy between .EQ and .EN. + Left and right delimiters may be identical. (They are customarily + taken to be $font L "$$" )$. Delimiters are turned off by delim + off. All text that is neither between delimiters + nor between .EQ and .EN is passed through untouched. +
+ + Tokens within 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 + x could appear, a complicated construction enclosed in braces + may be used instead. Tilde ~ represents a full space in the + output, circumflex ^ half as much. +
+ + Subscripts and superscripts are produced with the keywords sub + and sup. Thus x sub i makes $x sub i$, a sub i sup 2 produces + $a sub i sup 2$, and e sup {x sup 2 + y sup 2} gives $e sup {x + sup 2 + y sup 2}$. +
+ + Over makes fractions: a over b yields $a over b$. +
+ + Sqrt produces square roots: 1 over sqrt {ax sup 2 +bx+c} results + in $1 over sqrt {ax sup 2 +bx+c}$ . +
+ + The keywords from and to introduce lower and upper limits on arbitrary + things: $lim from {n -> inf} sum from 0 to n x sub i$ is made with + lim from {n −> inf} sum from 0 to n x sub i. +
+ + Left and right brackets, braces, etc., of the right height are + made with left and right: left [ x sup 2 + y sup 2 over alpha + right ] ~=~1 produces $left [ x sup 2 + y sup 2 over alpha right + ] ~=~1$. The right clause is optional. Legal characters after + left and right are braces, brackets, + bars, c and f for ceiling and floor, and "" for nothing at all (useful + for a right-side-only bracket). +
+ + Vertical piles of things are made with pile, lpile, cpile, and + rpile: pile {a above b above c} produces $pile {a above b above + c}$. There can be an arbitrary number of elements in a pile. lpile + left-justifies, pile and cpile center, with different vertical + spacing, and rpile right justifies. +
+ + Matrices are made with matrix: 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 rcol + for a right-justified column. +
+ + Diacritical marks are made with prime, dot, dotdot, hat, tilde, + bar, under, vec, dyad, and under: x sub 0 sup prime = f(t) bar + + g(t) under is $x sub 0 sup prime = f(t) bar + g(t) under$, and + x vec = y dyad is $x vec = y dyad$. +
+ + Sizes and fonts can be changed with prefix operators size n, size + ±n, fat, roman, italic, bold, or font n. Size and fonts can be + changed globally in a document by gsize n and gfont n, or by the + command-line arguments −sn and −fn. +
+ + Normally subscripts and superscripts are reduced by 3 point sizes + from the previous size; this may be changed by the command-line + argument −pn. +
+ + Successive display arguments can be lined up. Place mark before + the desired lineup point in the first equation; place lineup at + the place that is to line up vertically in subsequent equations. + +
+ + Shorthands may be defined or existing keywords redefined with + define: define thing % replacement % defines a new token called + thing which will be replaced by replacement whenever it appears + thereafter. The % may be any character that does not occur in + replacement. +
+ + Keywords like sum ( sum ), int ( int ), inf ( inf ), and shorthands + like >= (>=), −> (->), and != ( != ) are recognized. Greek letters + are spelled out in the desired case, as in alpha or GAMMA. Mathematical + words like sin, cos, log are made Roman automatically. Troff(1) + four-character escapes like \(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 troff when all else fails.
+ +
+

FILES
+ +
+ + /sys/lib/troff/font/devutf   font descriptions for PostScript
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/eqn
+ +
+

SEE ALSO
+ +
+ + troff(1), tbl(1)
+ J. F. Ossanna and B. W. Kernighan, “Troff User’s Manual”.
+ B. W. Kernighan and L. L. Cherry, “Typesetting Mathematics--User’s + Guide”, Unix Research System Programmer’s Manual, Tenth Edition, + Volume 2.
+ +
+

BUGS
+ +
+ + To embolden digits, parens, etc., it is necessary to quote them, + as in bold "12.3". delim off
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/factor.html b/man/man1/factor.html new file mode 100644 index 00000000..893f2ad9 --- /dev/null +++ b/man/man1/factor.html @@ -0,0 +1,73 @@ + +factor(1) - Plan 9 from User Space + + + + +
+
+
FACTOR(1)FACTOR(1) +
+
+

NAME
+ +
+ + factor, primes – factor a number, generate large primes
+ +
+

SYNOPSIS
+ +
+ + factor [ number ] +
+ + primes [ start [ finish ] ]
+ +
+

DESCRIPTION
+ +
+ + Factor prints number and its prime factors, each repeated the + proper number of times. The number must be positive and less than + 254 (about 1.8×1016). +
+ + If no number is given, 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 -/n . +
+ + +
+ + Primes prints the prime numbers ranging from start to finish, + where start and finish are positive numbers less than 256. If + finish is missing, primes prints without end; if start is missing, + it reads the starting number from the standard input.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/factor.c
+ /usr/local/plan9/src/cmd/primes.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/fmt.html b/man/man1/fmt.html new file mode 100644 index 00000000..28d339a4 --- /dev/null +++ b/man/man1/fmt.html @@ -0,0 +1,100 @@ + +fmt(1) - Plan 9 from User Space + + + + +
+
+
FMT(1)FMT(1) +
+
+

NAME
+ +
+ + fmt, htmlfmt – simple text formatters
+ +
+

SYNOPSIS
+ +
+ + fmt [ option ... ] [ file ... ] +
+ + htmlfmt [ −a ] [ −c charset ] [ −u url ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Fmt copies the given files (standard input by default) to its + standard output, filling and indenting lines. The options are
+ −l n   Output line length is n, including indent (default 70).
+ −w n   A synonym for −l.
+ −i n   Indent n spaces (default 0).
+ −j    Do not join short lines: only fold long lines. +
+ + Empty lines and initial white space in input lines are preserved. + Empty lines are inserted between input files. +
+ + Fmt is idempotent: it leaves already formatted text unchanged. + +
+ + Htmlfmt performs a similar service, but accepts as input text + formatted with HTML tags. It accepts fmt’s −l and −w flags and + also:
+ −a    Normally htmlfmt suppresses the contents of form fields and + anchors (URLs and image files); this flag causes it to print them, + in square brackets.
+ −c charset
+ +
+ + change the default character set from iso-8859-1 to charset. This + is the character set assumed if there isn’t one specified by the + html itself in a <meta> directive.
+ +
+ −u urlUse url as the base URL for the document when displaying + anchors; sets −a.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/fmt.c +
+ + /usr/local/plan9/src/cmd/htmlfmt
+ +
+

BUGS
+ +
+ + Htmlfmt makes no attempt to render the two-dimensional geometry + of tables; it just treats the table entries as plain, to-be-formatted + text.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/fortune.html b/man/man1/fortune.html new file mode 100644 index 00000000..2793ee92 --- /dev/null +++ b/man/man1/fortune.html @@ -0,0 +1,64 @@ + +fortune(1) - Plan 9 from User Space + + + + +
+
+
FORTUNE(1)FORTUNE(1) +
+
+

NAME
+ +
+ + fortune – sample lines from a file
+ +
+

SYNOPSIS
+ +
+ + fortune [ file ]
+ +
+

DESCRIPTION
+ +
+ + Fortune prints a one-line aphorism chosen at random. If a file + is specified, the saying is taken from that file; otherwise it + is selected from /usr/local/plan9/lib/fortunes.
+ +
+

FILES
+ +
+ + /usr/local/plan9/lib/fortunes
+ /usr/local/plan9/lib/fortunes.index fast lookup table, maintained + automatically
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/fortune.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/freq.html b/man/man1/freq.html new file mode 100644 index 00000000..6a4b82d0 --- /dev/null +++ b/man/man1/freq.html @@ -0,0 +1,69 @@ + +freq(1) - Plan 9 from User Space + + + + +
+
+
FREQ(1)FREQ(1) +
+
+

NAME
+ +
+ + freq – print histogram of character frequencies
+ +
+

SYNOPSIS
+ +
+ + freq [ −dxocr ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Freq reads the given files (default standard input) and prints + histograms of the character frequencies. By default, freq counts + each byte as a character; under the −r option it instead counts + UTF sequences, that is, runes. +
+ + 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 −d, −x, −o, −c flags specify a subset + of value formats: decimal, hex, octal, and character, respectively.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/freq.c
+ +
+

SEE ALSO
+ +
+ + utf(7), wc(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/fsize.html b/man/man1/fsize.html new file mode 100644 index 00000000..871ef383 --- /dev/null +++ b/man/man1/fsize.html @@ -0,0 +1,68 @@ + +fsize(1) - Plan 9 from User Space + + + + +
+
+
FSIZE(1)FSIZE(1) +
+
+

NAME
+ +
+ + fsize, mtime – print file information
+ +
+

SYNOPSIS
+ +
+ + fsize file ... +
+ + mtime file ...
+ +
+

DESCRIPTION
+ +
+ + Fsize prints the name and size of each of the files. +
+ + Mtime prints the name and modification time (in seconds since + the epoch) of each of the files.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/fsize.c
+ /usr/local/plan9/src/cmd/mtime.c
+ +
+

BUGS
+ +
+ + The output formats of the two programs are different.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/grap.html b/man/man1/grap.html new file mode 100644 index 00000000..e4e9c3c4 --- /dev/null +++ b/man/man1/grap.html @@ -0,0 +1,232 @@ + +grap(1) - Plan 9 from User Space + + + + +
+
+
GRAP(1)GRAP(1) +
+
+

NAME
+ +
+ + grap – pic preprocessor for drawing graphs
+ +
+

SYNOPSIS
+ +
+ + grap [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Grap is a pic(1) preprocessor for drawing graphs on a typesetter. + Graphs are surrounded by the troff ‘commands’ .G1 and .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, + grap provides the same loops, conditionals, and macro processing + that pic does. +
+ + frame ht e wid e top dotted ...: Set the frame around the graph + to specified ht and wid; default is 2 by 3 (inches). The line + styles (dotted, dashed, invis, solid (default)) of the sides (top, + bot, left, right) of the frame can be set independently. +
+ + label side "a label" "as a set of strings" adjust: Place label on + specified side; default side is bottom. adjust is up (or down + left right) expr to shift default position; width expr sets the + width explicitly. +
+ + ticks side in at optname expr, expr, ...: Put ticks on side at + expr, ..., and label with "expr". If any expr is followed by "...", + label tick with "...", and turn off all automatic labels. If "..." + contains %f’s, they will be interpreted as printf formatting instructions + for the tick value. Ticks point in or out (default out). Tick + iterator: instead of at ..., use from expr to expr by op expr + where op is optionally +−*/ for additive or multiplicative steps. + by can be omitted, to give steps of size 1. If no ticks are requested, + they are supplied automatically; suppress this with ticks off. + Automatic ticks normally leave a margin of 7% on each + side; set this to anything by margin = expr. +
+ + grid side linedesc at optname expr, expr, ...: Draw grids perpendicular + to side in style linedesc at expr, .... Iterators and labels work + as with ticks. +
+ + coord optname x min, max y min, max log x    log y: Set range of + coords and optional log scaling on either or both. This overrides + computation of data range. Default value of optname is current + coordinate system (each coord defines a new coordinate system). + +
+ + plot "str" at point; "str" at point: Put str at point. Text position + can be qualified with rjust, ljust, above, below after "...". +
+ + line from point to point linedesc: Draw line from here to there. + arrow works in place of line. +
+ + next optname at point linedesc: Continue plot of data in optname + to point; default is current. +
+ + draw optname linedesc ...: Set mode for next: use this style from + now on, and plot "..." at each point (if given). +
+ + new optname linedesc ...: Set mode for next, but disconnect from + previous. +
+ + A list of numbers x y1 y2 y3 ... is treated as plot bullet at + x,y1; plot bullet at x,y2; etc., or as next at x,y1 etc., if draw + is specified. Abscissae of 1,2,3,... are provided if there is + only one input number per line. +
+ + A point optname expr, expr maps the point to the named coordinate + system. A linedesc is one of dot dash invis solid optionally followed + by an expression. +
+ + define name {whatever}: Define a macro. There are macros already + defined for standard plotting symbols like bullet, circle, star, + plus, etc., in /usr/local/plan9/lib/grap.defines, which is included + if it exists. +
+ + var = expr: Evaluate an expression. Operators are + − * and /. + Functions are log and exp (both base 10), sin, cos, sqrt; rand + returns random number on [0,1); max(e,e), min(e,e), int(e). +
+ + print expr; print "...": As a debugging aid, print expr or string + on the standard error. +
+ + copy "file name": Include this file right here. +
+ + copy thru macro: Pass rest of input (until .G2) through macro, + treating each field (non-blank, or "...") as an argument. macro + can be the name of a macro previously defined, or the body of + one in place, like /plot $1 at $2,$3/. +
+ + copy thru macro until "string": Stop copy when input is string (left-justified). + +
+ + pic remainder of line: Copy to output with leading blanks removed. + +
+ + graph Name pic-position: Start a new frame, place it at specified + position, e.g., graph Thing2 with .sw at Thing1.se + (0.1,0). + Name must be capitalized to keep pic happy. +
+ + .anything at beginning of line: Copied verbatim. +
+ + sh %anything %: Pass everything between the %’s to the shell; + as with macros, % may be any character and anything may include + newlines. +
+ + # anything: A comment, which is discarded. +
+ + Order is mostly irrelevant; no category is mandatory. Any arguments + on the .G1 line are placed on the generated .PS line for pic.
+ +
+

EXAMPLES
+ +
+ + .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
+ 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
+ +
+

FILES
+ +
+ + /usr/local/plan9/lib/grap.defines   definitions of standard plotting + characters, e.g., bullet
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/grap
+ +
+

SEE ALSO
+ +
+ + pic(1), troff(1)
+ J. L. Bentley and B. W. Kernighan, “GRAP--A Language for Typesetting + Graphs”, Unix Research System Programmer’s Manual, Tenth Edition, + Volume 2.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/graph.html b/man/man1/graph.html new file mode 100644 index 00000000..af80b3d4 --- /dev/null +++ b/man/man1/graph.html @@ -0,0 +1,117 @@ + +graph(1) - Plan 9 from User Space + + + + +
+
+
GRAPH(1)GRAPH(1) +
+
+

NAME
+ +
+ + graph – draw a graph
+ +
+

SYNOPSIS
+ +
+ + graph [ option ... ]
+ +
+

DESCRIPTION
+ +
+ + Graph with no options takes pairs of numbers from the standard + input as abscissas (x-values) and ordinates (y-values) of a graph. + Successive points are connected by straight lines. The graph is + encoded on the standard output for display by plot(1) filters. + +
+ + 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 " " in which case they may be empty or contain blanks + and numbers; labels never contain newlines. +
+ + The following options are recognized, each as a separate argument.
+ −a    Supply abscissas automatically; no 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 x, or the lower limit given by −x).
+ −b    Break (disconnect) the graph after each label in the input.
+ −c    Character string given by next argument is default label for + each point.
+ −g    Next argument is grid style, 0 no grid, 1 frame with ticks, + 2 full grid (default).
+ −l    Next argument is a legend to title the graph. Grid ranges are + automatically printed as part of the title unless a −s option + is present.
+ −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 −o.
+ −o    (Overlay.) The ordinates for n superposed curves appear in the + input with each abscissa value. The next argument is n.
+ −s    Save screen; no new page for this graph.
+ −x lIf l is present, x-axis is logarithmic. Next 1 (or 2) arguments + are lower (and upper) x limits. Third argument, if present, is + grid spacing on x axis. Normally these quantities are determined + automatically.
+ −y lSimilarly for y.
+ −e    Make automatically determined x and y scales equal.
+ −h    Next argument is fraction of space for height.
+ −w    Similarly for width.
+ −r    Next argument is fraction of space to move right before plotting.
+ −u    Similarly to move up before plotting.
+ −t    Transpose horizontal and vertical axes. (Option −a now applies + to the vertical axis.) +
+ + If a specified lower limit exceeds the upper limit, the axis is + reversed.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/graph
+ +
+

SEE ALSO
+ +
+ + plot(1), grap(1)
+ +
+

BUGS
+ +
+ + Segments that run out of bounds are dropped, not windowed. Logarithmic + axes may not be reversed. Option −e actually makes automatic limits, + rather than automatic scaling, equal.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/grep.html b/man/man1/grep.html new file mode 100644 index 00000000..e9682561 --- /dev/null +++ b/man/man1/grep.html @@ -0,0 +1,117 @@ + +grep(1) - Plan 9 from User Space + + + + +
+
+
GREP(1)GREP(1) +
+
+

NAME
+ +
+ + grep, g – search a file for a pattern
+ +
+

SYNOPSIS
+ +
+ + grep [ option ... ] pattern [ file ... ] +
+ + g [ option ... ] pattern [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Grep searches the input files (standard input default) for lines + that match the pattern, a regular expression as defined in regexp(7) + with the addition of a newline character as an alternative (substitute + for |) with lowest precedence. Normally, each line matching the + pattern is ‘selected’, and each selected line is copied to + the standard output. The options are
+ −c    Print only a count of matching lines.
+ −h    Do not print file name tags (headers) with output lines.
+ −e    The following argument is taken as a pattern. This option makes + it easy to specify patterns that might confuse argument parsing, + such as −n.
+ −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.
+ −l    (ell) Print the names of files with selected lines; don’t print + the lines.
+ −L    Print the names of files with no selected lines; the converse + of −l.
+ −n    Mark each printed line with its line number counted in its file.
+ −s    Produce no output, but return status.
+ −v    Reverse: print lines that do not match the pattern.
+ −f    The pattern argument is the name of a file containing regular + expressions one per line.
+ −b    Don’t buffer the output: write each output line as soon as it + is discovered. +
+ + Output lines are tagged by file name when there is more than one + input file. (To force this tagging, include /dev/null as a file + name argument.) +
+ + Care should be taken when using the shell metacharacters $*[^|()=\ + and newline in pattern; it is safest to enclose the entire expression + in single quotes '...'. An expression starting with ’*’ will treat + the rest of the expression as literal characters. +
+ + G invokes grep with −n and forces tagging of output lines by file + name. If no files are listed, it searches all files matching
+ +
+ + *.C *.b *.c *.h *.m *.cc *.java *.py *.tex *.ms
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/grep
+ /usr/local/plan9/bin/g
+ +
+

SEE ALSO
+ +
+ + ed(1), awk(1), sed(1), sam(1), regexp(7)
+ +
+

DIAGNOSTICS
+ +
+ + Exit status is null if any lines are selected, or non-null when + no lines are selected or an error occurs.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/gview.html b/man/man1/gview.html new file mode 100644 index 00000000..6abdc7da --- /dev/null +++ b/man/man1/gview.html @@ -0,0 +1,155 @@ + +gview(1) - Plan 9 from User Space + + + + +
+
+
GVIEW(1)GVIEW(1) +
+
+

NAME
+ +
+ + gview – interactive graph viewer
+ +
+

SYNOPSIS
+ +
+ + gview [ −l logfile ] [ −m ] [ file ]
+ +
+

DESCRIPTION
+ +
+ + Gview reads polygonal lines or a polygonal line drawing from an + 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. + 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. +
+ + Since the move and rotate commands are undesirable when just viewing + a graph, they are only enabled if gview is invoked with the −m + option. +
+ + Clicking on a polyline with button 1 displays the coordinates + and a t value that tells how far along the polyline. (t=0 at the + first vertex, t=1 at the first vertex, t=1.5 halfway between the + second and third vertices, etc.) The −l option generates a log + file that lists all points selected in this manner. +
+ + The most important interactive operations are to zoom in by sweeping + out a rectangle, or to zoom out so that everything currently being + displayed shrinks to fit in the swept-out rectangle. Other options + on the button 3 menu are unzoom which restores the coordinate + system to the default state where everything fits on + the screen, recenter which takes a point and makes it the center + of the window, and square up which makes the horizontal and vertical + scale factors equal. +
+ + 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 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 y). Then the zoom in command can be used + to accentuate deviations from horizontal. There is also an unslant + command that undoes all of this and goes back to an unslanted + coordinate system. +
+ + There is a 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. The + thick or 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 had commands to read a new input file and display + it on top of everything else, restack the drawing order (in case + lines of different color are drawn on top of each other), write + everything into an output file, or exit the program. +
+ + Each polyline in an input or output file is a space-delimited + x 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.)
+ If the label after a polyline can contains the word Thick or a + color name (Red, Pink, Dkred, Orange, Yellow, Dkyellow, Green, + Dkgreen, Cyan, Blue, Ltblue, Magenta, Violet, Gray, Black, White), + whichever color name comes first will be used to color the polyline. + +
+

EXAMPLE
+ +
+ + To see a graph of the function y=sin(x)/x generate input with + an awk script and pipe it into gview:
+ +
+ + awk 'BEGIN{for(x=.1;x<500;x+=.1)print x,sin(x)/x}' | gview
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/draw/gview.c
+ +
+

SEE ALSO
+ +
+ + awk(1)
+ +
+

BUGS
+ +
+ + The user interface for the slant command is counter-intuitive. + Perhaps it would be better to have a scheme for sweeping out a + parallelogram.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/gzip.html b/man/man1/gzip.html new file mode 100644 index 00000000..3f476f15 --- /dev/null +++ b/man/man1/gzip.html @@ -0,0 +1,135 @@ + +gzip(1) - Plan 9 from User Space + + + + +
+
+
GZIP(1)GZIP(1) +
+
+

NAME
+ +
+ + gzip, gunzip, bzip2, bunzip2, zip, unzip, – compress and expand + data
+ +
+

SYNOPSIS
+ +
+ + gzip [−cvD[1−9]] [file ...] +
+ + gunzip [−ctTvD] [file ...] +
+ + bzip2 [−cvD[1−9]] [file ...] +
+ + bunzip2 [−cvD] [file ...] +
+ + zip [−vD[1−9]] [−f zipfile] file [...] +
+ + unzip [−cistTvD] [−f zipfile] [file ...]
+ +
+

DESCRIPTION
+ +
+ + +
+ + Gzip encodes files with a hybrid Lempel-Ziv 1977 and Huffman compression + algorithm known as 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 + .gz; if the resulting name ends with + .tar.gz, it is converted to .tgz instead. Gunzip reverses the + process. Its output files are named by taking the last path element + of each file argument, converting .tgz to .tar.gz, and stripping + any .gz; the resulting name must be different from the original + name. +
+ + Bzip2 and bunzip2 are similar in interface to gzip and gunzip, + but use a modified Burrows-Wheeler block sorting compression algorithm. + The default suffix for output files is .bz2, with .tar.bz2 becoming + .tbz. Bunzip2 recognizes the extension .tbz2 as a synonym for + .tbz. +
+ + Zip encodes the named files and places the results into the archive + zipfile, or the standard output if no file is given. Unzip extracts + files from an archive created by 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. + +
+ + None of these programs removes the original files. If the process + fails, the faulty output files are removed. +
+ + The options are:
+ −c          Write to standard output rather than creating an output file.
+ −i          Convert all archive file names to lower case.
+ −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 unzip if no zipfile is specified. If −s is given, + −T is ignored.
+ −t          List matching files in the archive rather than extracting them.
+ −T          Set the output time to that specified in the archive.
+ −1 .. −9      Sets the compression level. −1 is tuned for speed, −9 + for minimal output size. The best compromise is −6, the default.
+ −v          Produce more descriptive output. With −t, adds the uncompressed + size in bytes and the modification time to the output. Without + −t, prints the names of files on standard error as they are compressed + or decompressed.
+ −D          Produce debugging output.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/gzip
+ /usr/local/plan9/src/cmd/bzip2
+ +
+

SEE ALSO
+ +
+ + tar(1), compress(1)
+ +
+

BUGS
+ +
+ + Unzip can only extract files which are uncompressed or compressed + with the deflate compression scheme. Recent zip files fall into + this category.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/hoc.html b/man/man1/hoc.html new file mode 100644 index 00000000..21107e8e --- /dev/null +++ b/man/man1/hoc.html @@ -0,0 +1,136 @@ + +hoc(1) - Plan 9 from User Space + + + + +
+
+
HOC(1)HOC(1) +
+
+

NAME
+ +
+ + hoc – interactive floating point language
+ +
+

SYNOPSIS
+ +
+ + hoc [ file ... ] [ −e expression ]
+ +
+

DESCRIPTION
+ +
+ + Hoc interprets a simple language for floating point arithmetic, + at about the level of BASIC, with C-like syntax and functions. + +
+ + The named files are read and interpreted in order. If no file + is given or if file is − hoc interprets the standard input. The + −e option allows input to hoc to be specified on the command line, + to be treated as if it appeared in a file. +
+ + Hoc input consists of expressions and statements. Expressions + are evaluated and their results printed. Statements, typically + assignments and function or procedure definitions, produce no + output unless they explicitly call print. +
+ + Variable names have the usual syntax, including _; the name _ + by itself contains the value of the last expression evaluated. + The variables E, PI, PHI, GAMMA and DEG are predefined; the last + is 59.25..., degrees per radian. +
+ + Expressions are formed with these C-like operators, listed by + decreasing precedence.
+ ^     exponentiation
+ ! − ++ −−
+ * / %
+ + −
+ > >= < <= == !=
+ &&
+ ||
+ = += −= *= /= %=
+ +
+ + Built in functions are abs, acos, asin, atan (one argument), cos, + cosh, exp, int, log, log10, sin, sinh, sqrt, tan, and tanh. The + function read(x) reads a value into the variable x and returns + 0 at EOF; the statement print prints a list of expressions that + may include string constants such as + "hello\n". +
+ + Control flow statements are if-else, while, and for, with braces + for grouping. Newline ends a statement. Backslash-newline is equivalent + to a space. +
+ + Functions and procedures are introduced by the words func and + proc; return is used to return with a value from a function.
+ +
+

EXAMPLES
+ +
+ + 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)
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/hoc
+ +
+

SEE ALSO
+ +
+ + bc(1), dc(1)
+ B. W. Kernighan and R. Pike, The Unix Programming Environment, + Prentice-Hall, 1984
+ +
+

BUGS
+ +
+ + Error recovery is imperfect within function and procedure definitions.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/idiff.html b/man/man1/idiff.html new file mode 100644 index 00000000..15296a37 --- /dev/null +++ b/man/man1/idiff.html @@ -0,0 +1,87 @@ + +idiff(1) - Plan 9 from User Space + + + + +
+
+
IDIFF(1)IDIFF(1) +
+
+

NAME
+ +
+ + idiff – interactive diff
+ +
+

SYNOPSIS
+ +
+ + idiff [ −bw ] file1 file2
+ +
+

DESCRIPTION
+ +
+ + Idiff interactively merges file1 and file2 onto standard output. + Wherever file1 and file2 differ, idiff displays the differences + in the style of “diff −n” on standard error and prompts the user + to select a chunk. Valid responses are:
+ <     Use the chunk from file1.
+ >     Use the chunk from file2.
+ =     Use the diff output itself.
+ q<, q>, q=
+ +
+ + Use the given response for all future questions.
+ +
+ !cmdExecute cmd and prompt again. +
+ + Idiff invokes diff(1) to compare the files. The −b and −w flags, + if passed, are passed to diff.
+ +
+

FILES
+ +
+ + /tmp/idiff.*
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/idiff.c
+ +
+

SEE ALSO
+ +
+ + diff(1)
+ Kernighan and Pike, The Unix Programming Environment, Prentice-Hall, + 1984.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/index.html b/man/man1/index.html new file mode 100644 index 00000000..c35ab541 --- /dev/null +++ b/man/man1/index.html @@ -0,0 +1,449 @@ + + +Manual Section 1 - Plan 9 from User Space + + + +
+
+ +
+
+
+ Manual Section 1 - Plan 9 from User Space +
+
+
intro(1)intro – introduction to Plan 9 from User Space +
+
+
+
9(1)9 – run Plan 9 commands +
+
+
+
9c(1)9c, 9a, 9l, 9ar – C compiler, assembler, linker, archiver +
+
+
+
9p(1)9p – read and write files on a 9P server +
+
+
+
9term(1)9term – terminal windows +
+
+
+
acid(1)acid, acidtypes – debugger +
+
+
+
acme(1)acme, win, awd – interactive text windows +
+
+
+
acmeevent(1)acmeevent, acme.rc – shell script support for acme clients +
+
+
+
ascii(1)ascii, unicode – interpret ASCII, Unicode characters +
+
+
+
astro(1)astro – print astronomical information +
+
+
+
basename(1)basename – strip file name affixes +
+
+
+
bc(1)bc – arbitrary-precision arithmetic language +
+
+
+
bundle(1)bundle – collect files for distribution +
+
+
+
cal(1)cal – print calendar +
+
+
+
calendar(1)calendar – print upcoming events +
+
+
+
cat(1)cat, read, nobs – catenate files +
+
+
+
cleanname(1)cleanname – clean a path name +
+
+
+
clog(1)auxclog – create date-stamped console log +
+
+
+
cmp(1)cmp – compare two files +
+
+
+
colors(1)colors, cmapcube – display color map +
+
+
+
comm(1)comm – select or reject lines common to two sorted files +
+
+
+
core(1)core – print information about dead processes +
+
+
+
crop(1)crop, iconv – frame, crop, and convert image +
+
+
+
date(1)date – date and time +
+
+
+
db(1)db – debugger +
+
+
+
dc(1)dc – desk calculator +
+
+
+
deroff(1)deroff, delatex – remove formatting requests +
+
+
+
dial(1)dial – connect to a remote service +
+
+
+
dict(1)dict, adict – dictionary browser +
+
+
+
diff(1)diff – differential file comparator +
+
+
+
doctype(1)doctype – intuit command line for formatting a document +
+
+
+
echo(1)echo – print arguments +
+
+
+
ed(1)ed – text editor +
+
+
+
eqn(1)eqn – typeset mathematics +
+
+
+
factor(1)factor, primes – factor a number, generate large primes +
+
+
+
fmt(1)fmt, htmlfmt – simple text formatters +
+
+
+
fortune(1)fortune – sample lines from a file +
+
+
+
freq(1)freq – print histogram of character frequencies +
+
+
+
fsize(1)fsize, mtime – print file information +
+
+
+
grap(1)grap – pic preprocessor for drawing graphs +
+
+
+
graph(1)graph – draw a graph +
+
+
+
grep(1)grep, g – search a file for a pattern +
+
+
+
gview(1)gview – interactive graph viewer +
+
+
+
gzip(1)gzip, gunzip, bzip2, bunzip2, zip, unzip, – compress and expand data +
+
+
+
hoc(1)hoc – interactive floating point language +
+
+
+
idiff(1)idiff – interactive diff +
+
+
+
join(1)join – relational database operator +
+
+
+
jpg(1)jpg, gif, png, ppm, bmp, yuv, ico, togif, toppm, topng, toico – view and convert pictures +
+
+
+
kill(1)kill, slay, start, stop – print commands to manipulate processes +
+
+
+
label(1)label, awd – set window label +
+
+
+
lex(1)lex – generator of lexical analysis programs +
+
+
+
look(1)look – find lines in a sorted list +
+
+
+
ls(1)ls, lc – list contents of directory +
+
+
+
man(1)man, lookman, sig – print or find pages of this manual +
+
+
+
map(1)map, mapdemo, mapd – draw maps on various projections +
+
+
+
mc(1)mc – multicolumn print +
+
+
+
mk(1)mk – maintain (make) related files +
+
+
+
mkdir(1)mkdir – make a directory +
+
+
+
namespace(1)namespace – print name space directory +
+
+
+
news(1)news – print news items +
+
+
+
p(1)p – paginate +
+
+
+
page(1)img, psv – view +
+
+
+
pic(1)pic, tpic – troff and tex preprocessors for drawing pictures +
+
+
+
plot(1)plot – graphics filter +
+
+
+
plumb(1)plumb – send message to plumber +
+
+
+
pr(1)pr – print file +
+
+
+
proof(1)proof – troff output interpreter +
+
+
+
ps(1)ps, psu – process status +
+
+
+
psfonts(1)psfonts, psdownload – add necessary fonts to PostScript document for printing +
+
+
+
pwd(1)pwd, pbd – working directory +
+
+
+
rc(1)rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ – command language +
+
+
+
rio(1)rio – rio-like Window Manager for X +
+
+
+
rm(1)rm – remove files +
+
+
+
sam(1)sam, B, E, sam.save, samterm, samsave – screen editor with structural regular expressions +
+
+
+
scat(1)scat – sky catalogue and Digitized Sky Survey +
+
+
+
secstore(1)aescbc, secstore, ipso – secstore commands +
+
+
+
sed(1)sed – stream editor +
+
+
+
seq(1)seq – print sequences of numbers +
+
+
+
sleep(1)sleep – suspend execution for an interval +
+
+
+
sort(1)sort – sort and/or merge files +
+
+
+
spell(1)spell, sprog – find spelling errors +
+
+
+
split(1)split – split a file into pieces +
+
+
+
src(1)src – find source code for executable +
+
+
+
stats(1)stats, auxstats – display graphs of system activity +
+
+
+
strings(1)strings – extract printable strings +
+
+
+
sum(1)sum, md5sum, sha1sum – sum and count blocks in a file +
+
+
+
tail(1)tail – deliver the last part of a file +
+
+
+
tbl(1)tbl – format tables for nroff or troff +
+
+
+
tcs(1)tcs – translate character sets +
+
+
+
tee(1)tee – pipe fitting +
+
+
+
test(1)test – set status according to condition +
+
+
+
time(1)time – time a command +
+
+
+
touch(1)touch – set modification date of a file +
+
+
+
tr(1)tr – translate characters +
+
+
+
tr2post(1)tr2post – convert troff intermediate to PostScript +
+
+
+
troff(1)troff, nroff – text formatting and typesetting +
+
+
+
troff2html(1)troff2html – convert troff output into HTML +
+
+
+
tweak(1)tweak – edit image files, subfont files, face files, etc. +
+
+
+
uniq(1)uniq – report repeated lines in a file +
+
+
+
units(1)units – conversion program +
+
+
+
vac(1)vac – create a vac archive on Venti +
+
+
+
wc(1)wc – word count +
+
+
+
web(1)web, wmail – handle web page, mail message for plumber +
+
+
+
wintext(1)wintext, ", "" – access text in current window +
+
+
+
xd(1)xd – hex, octal, decimal, or ASCII dump +
+
+
+
yacc(1)yacc – yet another compiler-compiler +
+
+ +
+
+
+Space Glenda +
+
+		 +
+ + diff --git a/man/man1/intro.html b/man/man1/intro.html new file mode 100644 index 00000000..fc628e5a --- /dev/null +++ b/man/man1/intro.html @@ -0,0 +1,221 @@ + +intro(1) - Plan 9 from User Space + + + + +
+
+
INTRO(1)INTRO(1) +
+
+

NAME
+ +
+ + intro – introduction to Plan 9 from User Space
+ +
+

DESCRIPTION
+ +
+ + Plan 9 is a distributed computing environment built at Bell Labs + starting in the late 1980s. The system can be obtained from Bell + Labs at http://plan9.bell−labs.com/plan9 and runs on PCs and a + variety of other platforms. Plan 9 became a convenient platform + for experimenting with new ideas, + applications, and services. +
+ + Plan 9 from User Space provides many of the ideas, applications, + and services from Plan 9 on Unix-like systems. It runs on FreeBSD + (x86), Linux (x86 and PowerPC), Mac OS X (PowerPC), OpenBSD (x86), + and SunOS (Sparc).
+

Commands
+ Plan 9 from User Space expects its own directory tree, conventionally + /usr/local/plan9. When programs need to access files in the tree, + they expect the $PLAN9 environment variable to contain the name + of the root of the tree. See install(1) for details about installation. + +
+ + Many of the familiar Unix commands, for example cat(1), ls(1), + and wc(1), are present, but in their Plan 9 forms: cat takes no + arguments, ls does not columnate its output when printing to a + terminal, and wc counts UTF characters. In some cases, the differences + are quite noticeable: grep(1) and sed(1) expect Plan 9 + regular expressions (see regexp(7)), which are closest to what + Unix calls extended regular expressions. Because of these differences, + it is not recommended to put $PLAN9/bin before the usual system + bin directories in your search path. Instead, put it at the end + of your path and use the 9(1) script when you want to + invoke the Plan 9 version of a traditional Unix command. +
+ + Occasionally the Plan 9 programs have been changed to adapt to + Unix. Mk(1) now allows mkfiles to choose their own shell, and + rc(1) has a ulimit builtin and manages $PATH. +
+ + Many of the graphical programs from Plan 9 are present, including + sam(1) and acme(1). An X11 window manager rio(1) mimics Plan 9’s + window system, with command windows implemented by the external + program 9term(1). Following the style of X Windows, these programs + run in new windows rather than the one in + which they are invoked. They all take a −W option to specify the + size and placement of the new window. The argument is one of widthxheight, + widthxheight@xmin,xmax, or xmin,ymin,xmax,ymax. +
+ + The plumber(4) helps to connect the various Plan 9 programs together, + and fittings like web(1) connect it to external programs such + as web browsers; one can click on a URL in acme and see the page + load in Firefox.
+

User-level file servers
+ In Plan 9, user-level file servers present file trees via the + Plan 9 file protocol, 9P. Processes can mount arbitrary file servers + and customize their own name spaces. These facilities are used + to connect programs. Clients interact with file servers by reading + and writing files. +
+ + This cannot be done directly on Unix. Instead the servers listen + for 9P connections on Unix domain sockets; clients connect to + these sockets and speak 9P directly using the 9pclient(3) library. + Intro(4) tells more of the story. The effect is not as clean as + on Plan 9, but it gets the job done and still provides a uniform + and + easy-to-understand mechanism. The 9p(1) client can be used in + shell scripts or by hand to carry out simple interactions with + servers.
+

External databases
+ Some programs rely on large databases that would be cumbersome + to include in every release. Scripts are provided that download + these databases separately. These databases can be downloaded + separately. See $PLAN9/dict/README and $PLAN9/sky/README.
+

Programming
+ The shell scripts 9c and 9l (see 9c(1)) provide a simple interface + to the underlying system compiler and linker, similar to the 2c + and 2l families on Plan 9. 9c compiles source files, and 9l links + object files into executables. When using Plan 9 libraries, 9l + infers the correct set of libraries from the object files, so + that no −l + options are needed. +
+ + The only way to write multithreaded programs is to use the thread(3) + library. Rfork(3) exists but is not as capable as on Plan 9. There + are many unfortunate by necessary preprocessor diversions to make + Plan 9 and Unix libraries coexist. See intro(3) for details. +
+ + The debuggers acid(1) and db(1) and the debugging library mach(3) + are works in progress. They are platform-independent, so that + x86 Linux core dumps can be inspected on PowerPC Mac OS X machines, + but they are also fairly incomplete. The x86 target is the most + mature; initial PowerPC support exists; and other + targets are unimplemented. The debuggers can only inspect, not + manipulate, target processes. Support for operating system threads + and for 64-bit architectures needs to be rethought. On x86 Linux + systems, acid and db can be relied upon to produce reasonable + stack traces (often in cases when GNU gdb cannot) and + dump data structures, but that it is the extent to which they + have been developed and exercised.
+

Porting programs
+ The vast majority of the familiar Plan 9 programs have been ported, + including the Unicode-aware troff(1). +
+ + Of the more recent additions to Plan 9, the secstore(1) client + has been ported, though secstored has not. Vac(1) has been ported, + though vacfs has not. Factotum and venti are in progress. +
+ + A backup system providing a dump file system built atop Venti + is also in progress.
+

Porting to new systems
+ Porting the tree to new operating systems or architectures should + be straightforward, as system-specific code has been kept to a + minimum. The largest pieces of system-specific code are <u.h>, which + must include the right system files and set up the right integer + type definitions, and libthread, which must implement + spin locks, operating system thread creation, and context switching + routines. Portable implementations of these using <pthread.h> and + <ucontext.h> already exist. If your system supports them, you may + not need to write any system specific code at all. +
+ + There are other smaller system dependencies, such as the terminal + handling code in 9term(1) and the implementation of getcallerpc(3), + but these are usually simple and are not on the critical path + for getting the system up and running.
+ +

+

SEE ALSO
+ +
+ + The rest of this manual describes Plan 9 from User Space. Many + of the man pages have been brought from Plan 9, but they have + been updated, and others have been written from scratch. +
+ + The manual pages are in a Unix style tree, with names like $PLAN9/man/man1/cat.1 + instead of Plan 9’s simpler $PLAN9/man/1/cat, so that the Unix + man(1) utility can handle it. Some systems, for example Debian + Linux, deduce the man page locations from the search path, so + that adding $PLAN9/bin to + your path is sufficient to cause $PLAN9/man to be consulted for + manual pages using the system man. On other systems, or to look + at manual pages with the same name as a system page, invoke the + Plan 9 man directly, as in 9 man cat. +
+ + The manual sections follow the Unix numbering conventions, not + the Plan 9 ones. +
+ + Section (1) describes general publicly accessible commands. +
+ + Section (3) describes C library functions. +
+ + Section (4) describes user-level file servers. +
+ + Section (7) describes file formats and protocols. (On Unix, section + (5) is technically for file formats but seems now to be used for + describing specific files.) +
+ + Section (9p) describes the Plan 9 file protocol 9P.
+ +
+

DIAGNOSTICS
+ +
+ + In Plan 9, a program’s exit status is an arbitrary text string, + while on Unix it is an integer. Section (1) of this manual describes + commands as though they exit with string statuses. In fact, exiting + with an empty status corresponds to exiting with status 0, and + exiting with any non-empty string corresponds to exiting with + status 1. See exits(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/join.html b/man/man1/join.html new file mode 100644 index 00000000..704837e4 --- /dev/null +++ b/man/man1/join.html @@ -0,0 +1,144 @@ + +join(1) - Plan 9 from User Space + + + + +
+
+
JOIN(1)JOIN(1) +
+
+

NAME
+ +
+ + join – relational database operator
+ +
+

SYNOPSIS
+ +
+ + join [ options ] file1 file2
+ +
+

DESCRIPTION
+ +
+ + Join forms, on the standard output, a join of the two relations + specified by the lines of file1 and file2. If one of the file + names is −, the standard input is used. +
+ + File1 and file2 must be sorted in increasing ASCII collating sequence + on the fields on which they are to be joined, normally the first + in each line. +
+ + There is one line in the output for each pair of lines in file1 + and file2 that have identical join fields. The output line normally + consists of the common field, then the rest of the line from file1, + then the rest of the line from file2. +
+ + 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. +
+ + The following options are recognized, with POSIX syntax.
+ −a n   In addition to the normal output, produce a line for each + unpairable line in file n, where n is 1 or 2.
+ −v n   Like −a, omitting output for paired lines.
+ −e s   Replace empty output fields by string s.
+ −1 m
+ −2 m   Join on the mth field of file1 or file2.
+ −jn m
+ +
+ + Archaic equivalent for −n m.
+ +
+ −ofields
+ +
+ + Each output line comprises the designated fields. The comma-separated + field designators are either 0, meaning the join field, or have + the form n.m, where n is a file number and m is a field number. + Archaic usage allows separate arguments for field designators. + +
+ + +
+ −tc   Use character c as the only separator (tab character) on input + and output. Every appearance of c in a line is significant.
+ +
+

EXAMPLES
+ +
+ + sort /etc/passwd | join −t: −1 1 −a 1 −e "" − bdays
+ +
+ + Add birthdays to the /etc/passwd file, leaving unknown birthdays + empty. The layout of /adm/users is given in passwd(5); bdays contains + sorted lines like ken:Feb 4, 1953.
+ +
+ tr : ' ' </etc/passwd | sort −k 3 3 >temp
+ join −1 3 −2 3 −o 1.1,2.1 temp temp | awk '$1 < $2'
+ +
+ + Print all pairs of users with identical userids.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/join.c
+ +
+

SEE ALSO
+ +
+ + sort(1), comm(1), awk(1)
+ +
+

BUGS
+ +
+ + With default field separation, the collating sequence is that + of sort −b −ky,y; with −t, the sequence is that of sort −tx −ky,y. + +
+ + One of the files must be randomly accessible.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/jpg.html b/man/man1/jpg.html new file mode 100644 index 00000000..30629c7c --- /dev/null +++ b/man/man1/jpg.html @@ -0,0 +1,175 @@ + +jpg(1) - Plan 9 from User Space + + + + +
+
+
JPG(1)JPG(1) +
+
+

NAME
+ +
+ + jpg, gif, png, ppm, bmp, yuv, ico, togif, toppm, topng, toico + – view and convert pictures
+ +
+

SYNOPSIS
+ +
+ + jpg [ −39cdefFkJrtv ] [ file ... ]
+ gif [ −39cdektv ] [ file ... ]
+ png [ −39cdektv ] [ file ... ]
+ ppm [ −39cdektv ] [ file ... ]
+ bmp [ file ]
+ yuv [ file ] +
+ + togif [ −c comment ] [ −l loopcount ] [ −d msec ] [ −t transindex + ] [ file ... [ −d msec ] file ... ]
+ toppm [ −c comment ] [ file ]
+ topng [ −c comment ] [ [ −g gamma ] [ file ] +
+ + ico [ file ]
+ toico [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + These programs read, display, and write image files in public + formats. Jpg, gif, png, ppm, bmp, and 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. Togif, + Toppm, and topng read Plan 9 images files, convert them to GIF, + PPM, or PNG, and write them to standard output. +
+ + The default behavior of jpg, gif, and ppm is to display the 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 q, DEL, or control-D exits the program. For a more user-friendly + interface, use 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. +
+ + These programs share many options:
+ −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.
+ −k    Convert and display the image as a black and white (really grey-scale) + image.
+ −v    Convert the image to an RGBV color-mapped image, even if the + display has true RGB color.
+ −d    Suppress display of the image; this is set automatically by + any of the following options:
+ −c    Convert the image to a Plan 9 representation, as defined by + image(7), and write it to standard output.
+ −9    Like −c, but produce an uncompressed image. This saves processing + time, particularly when the output is being piped to another program + such as page(1), since it avoids compression and decompression.
+ −t    Convert the image, if it is in color, to a true color RGB image.
+ −3    Like −t, but force the image to RGB even if it is originally + grey-scale. +
+ + Jpg has two extra options used to process the output of the LML + video card:
+ −f    Merge two adjacent images, which represent the two fields of + a video picture, into a single image.
+ −F    The input is a motion JPEG file, with multiple images representing + frames of the movie. Sets −f. +
+ + The togif and 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 −c to set the comment field of the resulting + file. If there is only one input picture, togif converts the image + to GIF format. If there are many files, though, it will + assemble them into an animated GIF file. The options control this + process:
+ −lloopcount
+ +
+ + By default, the animation will loop forever; 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.
+ +
+ −dmsec
+ +
+ + 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 file. +
+ + +
+ Gif translates files that contain a ‘transparency’ index by attaching + an alpha channel to the converted image. +
+ + Ico displays a Windows icon (.ico) file. If no file is specified, + ico reads from standard input. Icon files contain sets of icons + represeted by an image and a mask. Clicking the right button pops + up a menu that lets you write any icon’s image as a Plan 9 image + (widthxheight.image), write any icon’s mask as a Plan 9 + image (widthxheight.mask), or exit. Selecting one of the write + menu items yields a sight cursor. Move the sight over the icon + and right click again to write. +
+ + 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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/jpg
+ +
+

SEE ALSO
+ +
+ + page(1), image(7).
+ +
+

BUGS
+ +
+ + Writing an animated GIF using togif is a clumsy undertaking.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/kill.html b/man/man1/kill.html new file mode 100644 index 00000000..107e438d --- /dev/null +++ b/man/man1/kill.html @@ -0,0 +1,96 @@ + +kill(1) - Plan 9 from User Space + + + + +
+
+
KILL(1)KILL(1) +
+
+

NAME
+ +
+ + kill, slay, start, stop – print commands to manipulate processes
+ +
+

SYNOPSIS
+ +
+ + kill name ... +
+ + slay name ... +
+ + start name ... +
+ + stop name ...
+ +
+

DESCRIPTION
+ +
+ + Kill prints commands that will cause all processes with name and + owned by the current user to be terminated. Each command is commented + with an output line from ps(1) describing the process that would + be killed. Use the send command of 9term(1), or pipe the output + of kill into rc(1) or sh(1) to execute the + commands. +
+ + Kill suggests sending a Unix TERM signal to the process; sending + a KILL signal is a surer, if heavy handed, kill, but is necessary + if the offending process is ignoring signals. The slay command + prints commands to do this. +
+ + Stop prints commands to pause execution of processes by sending + them the STOP signal. +
+ + Start prints commands to restart stopped processes by sending + them the CONT signal.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin
+ +
+

SEE ALSO
+ +
+ + ps(1), notify(3)
+ +
+

BUGS
+ +
+ + Stop and start should limit themselves to currently running or + stopped processes.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/label.html b/man/man1/label.html new file mode 100644 index 00000000..8c7999d4 --- /dev/null +++ b/man/man1/label.html @@ -0,0 +1,117 @@ + +label(1) - Plan 9 from User Space + + + + +
+
+
LABEL(1)LABEL(1) +
+
+

NAME
+ +
+ + label, awd – set window label
+ +
+

SYNOPSIS
+ +
+ + label string
+ awd
+ +
+

DESCRIPTION
+ +
+ + Label sets the label of the current win (see acme(1)) or X terminal + window (e.g., 9term(1) or xterm(1)) by echoing a special control + sequence to standard output. +
+ + Acme and 9term windows assume the label is a directory name. When + unrooted file names are plumbed in the window, they are evaluated + relative to the directory named in the label.
+ +
+

EXAMPLE
+ +
+ + One can use the following sh(1) function to keep the label up-to-date + in response to cd commands:
+ +
+ + _cd () {
+ +
+ + \cd "$@" &&
+ case $− in
+ *i*)
+ awd
+ esac
+ +
+ }
+ alias cd=_cd
+ cd .
+ +
+ + +
+ Rc(1) installs a similar fn cd at startup if there is not already + a function named cd:
+ +
+ + fn cd {
+ +
+ + builtin cd $1 && flag i && awd
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin/label
+ /usr/local/plan9/bin/awd
+ +
+

BUGS
+ +
+ + Awd is also documented in acme(1). +
+ + Awd does not append the −label suffix that it does on Plan 9.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/lex.html b/man/man1/lex.html new file mode 100644 index 00000000..e0f84d1e --- /dev/null +++ b/man/man1/lex.html @@ -0,0 +1,110 @@ + +lex(1) - Plan 9 from User Space + + + + +
+
+
LEX(1)LEX(1) +
+
+

NAME
+ +
+ + lex – generator of lexical analysis programs
+ +
+

SYNOPSIS
+ +
+ + lex [ −tvn9 ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Lex generates programs to be used in simple lexical analysis of + text. The input files (standard input default) contain regular + expressions to be searched for and actions written in C to be + executed when expressions are found. +
+ + A C source program, 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. +
+ + The options have the following meanings.
+ −t    Place the result on the standard output instead of in file lex.yy.c.
+ −v    Print a one-line summary of statistics of the generated analyzer.
+ −n    Opposite of −v; −n is default.
+ −9    Adds code to be able to compile through the native C compilers.
+ +
+

EXAMPLES
+ +
+ + This program converts upper case to lower, removes blanks at the + end of lines, and replaces multiple blanks by single blanks. +
+ + %%
+ [A−Z]       putchar(yytext[0]+'a'−'A');
+ [ ]+$
+ [ ]+ putchar(' ');
+ +
+

FILES
+ +
+ + lex.yy.c             output
+ /sys/lib/lex/ncform   template
+ +
+

SEE ALSO
+ +
+ + yacc(1), sed(1)
+ M. E. Lesk and E. Schmidt, ‘LEX--Lexical Analyzer Generator’, Unix + Research System Programmer’s Manual, Tenth Edition, Volume 2.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/lex
+ +
+

BUGS
+ +
+ + Cannot handle UTF. +
+ + The asteroid to kill this dinosaur is still in orbit.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/look.html b/man/man1/look.html new file mode 100644 index 00000000..cc8686d0 --- /dev/null +++ b/man/man1/look.html @@ -0,0 +1,96 @@ + +look(1) - Plan 9 from User Space + + + + +
+
+
LOOK(1)LOOK(1) +
+
+

NAME
+ +
+ + look – find lines in a sorted list
+ +
+

SYNOPSIS
+ +
+ + look [ −dfnixtc ] [ string ] [ file ]
+ +
+

DESCRIPTION
+ +
+ + Look consults a sorted file and prints all lines that begin with + string. It uses binary search. +
+ + The following options are recognized. Options dfnt affect comparisons + as in sort(1).
+ −i    Interactive. There is no string argument; instead look takes + lines from the standard input as strings to be looked up.
+ −x    Exact. Print only lines of the file whose key matches string + exactly.
+ −d    ‘Directory’ order: only letters, digits, tabs and blanks participate + in comparisons.
+ −f    Fold. Upper case letters compare equal to lower case.
+ −n    Numeric comparison with initial string of digits, optional minus + sign, and optional decimal point.
+ −t[c]Character c terminates the sort key in the file. By default, + tab terminates the key. If c is missing the entire line comprises + the key. +
+ + If no file is specified, /lib/words is assumed, with collating + sequence df.
+ +
+

FILES
+ +
+ + /lib/words
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/look.c
+ +
+

SEE ALSO
+ +
+ + sort(1), grep(1)
+ +
+

DIAGNOSTICS
+ +
+ + The exit status is “not found” if no match is found, and “no dictionary” + if file or the default dictionary cannot be opened.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/ls.html b/man/man1/ls.html new file mode 100644 index 00000000..e5ed5566 --- /dev/null +++ b/man/man1/ls.html @@ -0,0 +1,121 @@ + +ls(1) - Plan 9 from User Space + + + + +
+
+
LS(1)LS(1) +
+
+

NAME
+ +
+ + ls, lc – list contents of directory
+ +
+

SYNOPSIS
+ +
+ + ls [ −dlmnpqrstuFQ ] name ... +
+ + lc [ −dlmnpqrstuFQ ] name ...
+ +
+

DESCRIPTION
+ +
+ + For each directory argument, ls lists the contents of the directory; + for each file argument, 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. + +
+ + Lc is the same as ls, but sets the −p option and pipes the output + through mc(1). +
+ + There are a number of options:
+ −d    If argument is a directory, list it, not its contents.
+ −l    List in long format, giving mode (see below), file system type + (e.g., for devices, the # code letter that names it; see intro(3)), + the instance or subdevice number, owner, group, size in bytes, + and time of last modification for each file.
+ −m    List the name of the user who most recently modified the file.
+ −n    Don’t sort the listing.
+ −p    Print only the final path element of each file name.
+ −q    List the qid (see stat(3)) of each file; the printed fields + are in the order path, version, and type.
+ −r    Reverse the order of sort.
+ −s    Give size in Kbytes for each entry.
+ −t    Sort by time modified (latest first) instead of by name.
+ −u    Under −t sort by time of last access; under −l print time of + last access.
+ −F    Add the character / after all directory names and the character + * after all executable files.
+ −L    Print the character t before each file if it has the temporary + flag set, and − otherwise.
+ −Q    By default, printed file names are quoted if they contain characters + special to rc(1). The −Q flag disables this behavior. +
+ + The mode printed under the −l option contains 11 characters, interpreted + as follows: the first character is
+ d     if the entry is a directory;
+ a     if the entry is an append-only file;
+ −     if the entry is a plain file. +
+ + The next letter is l if the file is exclusive access (one writer + or reader at a time). +
+ + 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:
+ rif the file is readable;
+ wif the file is writable;
+ xif the file is executable;
+ −if none of the above permissions is granted.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/ls.c
+ /usr/local/plan9/bin/lc
+ +
+

SEE ALSO
+ +
+ + stat(3), mc(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/man.html b/man/man1/man.html new file mode 100644 index 00000000..41f472ab --- /dev/null +++ b/man/man1/man.html @@ -0,0 +1,139 @@ + +man(1) - Plan 9 from User Space + + + + +
+
+
MAN(1)MAN(1) +
+
+

NAME
+ +
+ + man, lookman, sig – print or find pages of this manual
+ +
+

SYNOPSIS
+ +
+ + man [ option ... ] [ section ... ] title ... +
+ + lookman key ... +
+ + sig function ...
+ +
+

DESCRIPTION
+ +
+ + Man locates and prints pages of this manual named title in the + specified sections. Title is given in lower case. Each section + is a number; pages marked (2S), for example, belong to chapter + 2. If no section is specified, pages in all sections are printed. + Any name from the NAME section at the top of the page will serve + as a + title. +
+ + The options are:
+ −p    Run proof(1) on the specified man pages.
+ −P    Run page(1) on the specified man pages.
+ −t    Run troff and send its output to standard output.
+ −n    (Default) Print the pages on the standard output using nroff. + +
+ + Lookman prints the names of all manual sections that contain all + of the key words given on the command line. +
+ + Sig prints the signature (i.e. C definition) of the function’s + given on the command line.
+ +
+

FILES
+ +
+ + /usr/local/plan9/man?/*
+ +
+ + troff source for manual; this page is /usr/local/plan9/man/man1/man.1
+ +
+ /usr/local/plan9/man/man?/INDEX
+ +
+ + indices searched to find pages corresponding to titles
+ +
+ /usr/local/plan9/man/secindex
+ +
+ + command to make an index for a given section
+ +
+ /usr/local/plan9/man/lookman/index
+ +
+ + index for lookman
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin/man
+ /usr/local/plan9/bin/lookman
+ +
+

SEE ALSO
+ +
+ + page(1), proof(1)
+ +
+

BUGS
+ +
+ + The manual was intended to be typeset; some detail is sacrificed + on text terminals. +
+ + There is no automatic mechanism to keep the indices up to date. + +
+ + Except for special cases, man doesn’t recognize things that should + be run through tbl and/or eqn.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/map.html b/man/man1/map.html new file mode 100644 index 00000000..6ed18ccb --- /dev/null +++ b/man/man1/map.html @@ -0,0 +1,483 @@ + +map(1) - Plan 9 from User Space + + + + +
+
+
MAP(1)MAP(1) +
+
+

NAME
+ +
+ + map, mapdemo, mapd – draw maps on various projections
+ +
+

SYNOPSIS
+ +
+ + map projection [ option ... ] +
+ + mapdemo +
+ + +
+

DESCRIPTION
+ +
+ + Map prepares on the standard output a map suitable for display + by any plotting filter described in plot(1). A menu of projections + is produced in response to an unknown projection. Mapdemo is a + short course in mapping. +
+ + The default data for map are world shorelines. Option −f accesses + more detailed data classified by feature.
+ −f [ feature ... ]
+ +
+ + Features are ranked 1 (default) to 4 from major to minor. Higher-numbered + ranks include all lower-numbered ones. Features are
+ shore[1-4]      seacoasts, lakes, and islands; option −f always shows + shore1
+ ilake[1-2]      intermittent lakes
+ river[1-4]      rivers
+ iriver[1-3]     intermittent rivers
+ canal[1-3]      3=irrigation canals
+ glacier
+ iceshelf[12]
+ reef
+ saltpan[12]
+ country[1-3]    2=disputed boundaries, 3=indefinite boundaries
+ state          states and provinces (US and Canada only)
+ +
+ + +
+ In other options coordinates are in degrees, with north latitude + and west longitude counted as positive.
+ −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.
+ +
+ −k S N E W
+ +
+ + Set the scale as if for a map with limits −l S N E W . Do not + consider any −l or −w option in setting scale.
+ +
+ −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 lon on the globe. Then tilt the North Pole of the + overlay along its Prime Meridian to latitude 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 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 −o, the orientation is 90, 0, m, where + m is the middle of the longitude range.
+ +
+ −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 + −l option with −w. Otherwise for small windows computing time + varies inversely with area!) + +
+ −d n   For speed, plot only every nth point.
+ −r    Reverse left and right (good for star charts and inside-out + views).
+ −v    Verso. Switch to a normally suppressed sheet of the map, such + as the back side of the earth in orthographic projection.
+ −s1
+ −s2   Superpose; outputs for a −s1 map (no closing) and a −s2 map + (no opening) may be concatenated.
+ −g dlat dlon res
+ +
+ + Grid spacings are dlat, dlon. Zero spacing means no grid. Missing + dlat is taken to be zero. Missing dlon is taken the same as dlat. + Grid lines are drawn to a resolution of res (2° or less by default). + In the absence of −g, grid spacing is 10°.
+ +
+ −p lat lon extent
+ +
+ + Position the point lat, lon at the center of the plotting area. + Scale the map so that the height (and width) of the nominal plotting + area is 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 extent overrides option −k. + +
+ −c x y rot
+ +
+ + After all other positioning and scaling operations have been performed, + rotate the image rot degrees counterclockwise about the center + and move the center to position x, y, where the nominal plotting + area is –1≤x≤1, –1≤y≤1. Missing arguments are taken to be 0. −x Allow + the map to extend outside the + nominal plotting area.
+ +
+ −m [ file ... ]
+ +
+ + 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 + −f,
+ +
+ + world      World Data Bank I (default)
+ states     US map from Census Bureau
+ counties   US map from Census Bureau
+ The environment variables MAP and MAPDIR change the default map + and default directory.
+ +
+ −b [lat0 lon0 lat1 lon1... ]
+ +
+ + Suppress the drawing of the normal boundary (defined by options + −l and −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 −u track. + +
+ −t file ...
+ +
+ + The files contain lists of points, given as latitude-longitude + pairs in degrees. If the first file is named −, the standard input + is taken instead. The points of each list are plotted as connected + ‘tracks’.
+ Points in a track file may be followed by label strings. A label + breaks the track. A label may be prefixed by ", :, or ! and is + terminated by a newline. An unprefixed string or a string prefixed + with " is displayed at the designated point. The first word of + a : or ! string names a special symbol (see option −y). + An optional numerical second word is a scale factor for the size + of the symbol, 1 by default. A : symbol is aligned with its top + to the north; a ! symbol is aligned vertically on the page.
+ +
+ −u file ...
+ +
+ + Same as −t, except the tracks are unbroken lines. (−t tracks appear + as dot-dashed lines if the plotting filter supports them.)
+ +
+ −y file
+ +
+ + The file contains plot(7)-style data for : or ! labels in −t or + −u files. Each symbol is defined by a comment :name then a sequence + of m and v commands. Coordinates (0,0) fall on the plotting point. + Default scaling is as if the nominal plotting range were ra −1 + −1 1 1; ra commands in file change the + scaling.
+ +
+

Projections
+ Equatorial projections centered on the Prime Meridian (longitude + 0). Parallels are straight horizontal lines. +
+ + mercator         equally spaced straight meridians, conformal, straight + compass courses
+ sinusoidal       equally spaced parallels, equal-area, same as bonne + 0.
+ cylequalarea lat0   equally spaced straight meridians, equal-area, + true scale on lat0
+ cylindrical      central projection on tangent cylinder
+ rectangular lat0   equally spaced parallels, equally spaced straight + meridians, true scale on lat0
+ gall lat0          parallels spaced stereographically on prime meridian, + equally spaced straight meridians, true scale on lat0
+ mollweide        (homalographic) equal-area, hemisphere is a circle
+ +
+ + +
+ + gilbert() sphere conformally mapped on hemisphere and viewed orthographically
+ +
+ +
+ gilbert          globe mapped conformally on hemisphere, viewed orthographically + +
+ + Azimuthal projections centered on the North Pole. Parallels are + concentric circles. Meridians are equally spaced radial lines. + +
+ + azequidistant     equally spaced parallels, true distances from pole
+ azequalarea      equal-area
+ gnomonic         central projection on tangent plane, straight great circles
+ perspective dist   viewed along earth’s axis dist earth radii from + center of earth
+ orthographic      viewed from infinity
+ stereographic     conformal, projected from opposite pole
+ laueradius = tan(2×colatitude), used in X-ray crystallography
+ fisheye n         stereographic seen from just inside medium with refractive + index n
+ newyorker rradius = log(colatitude/r): New Yorker map from viewing + pedestal of radius r degrees +
+ + 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. + +
+ + conic lat0         central projection on cone tangent at lat0
+ simpleconic lat0 lat1
+ +
+ + +
+ + equally spaced parallels, true scale on lat0 and lat1
+ +
+ +
+ lambert lat0 lat1    conformal, true scale on lat0 and lat1
+ albers lat0 lat1     equal-area, true scale on lat0 and lat1
+ bonne lat0         equally spaced parallels, equal-area, parallel lat0 + developed from tangent cone +
+ + Projections with bilateral symmetry about the Prime Meridian and + the equator. +
+ + polyconic        parallels developed from tangent cones, equally spaced + along Prime Meridian
+ aitoff           equal-area projection of globe onto 2-to-1 ellipse, based + on azequalarea
+ lagrange         conformal, maps whole sphere into a circle
+ bicentric lon0     points plotted at true azimuth from two centers + on the equator at longitudes ±lon0, great circles are straight + lines (a stretched gnomonic )
+ elliptic lon0      points plotted at true distance from two centers + on the equator at longitudes ±lon0
+ globular         hemisphere is circle, circular arc meridians equally spaced + on equator, circular arc parallels equally spaced on 0- and 90-degree + meridians
+ vandergrinten     sphere is circle, meridians as in globular, circular + arc parallels resemble mercator +
+ + Doubly periodic conformal projections. +
+ + guyou            W and E hemispheres are square
+ square           world is square with Poles at diagonally opposite corners
+ tetra            map on tetrahedron with edge tangent to Prime Meridian at + S Pole, unfolded into equilateral triangle
+ hex              world is hexagon centered on N Pole, N and S hemispheres are + equilateral triangles +
+ + Miscellaneous projections. +
+ + harrison dist angleoblique perspective from above the North Pole, + dist earth radii from center of earth, looking along the Date + Line angle degrees off vertical
+ trapezoidal lat0 lat1
+ +
+ + +
+ + equally spaced parallels, straight meridians equally spaced along + parallels, true scale at lat0 and lat1 on Prime Meridian
+ lune(lat,angle) conformal, polar cap above latitude lat maps to + convex lune with given angle at 90°E and 90°W +
+ + +
+ +
+ Retroazimuthal projections. At every point the angle between vertical + and a straight line to ‘Mecca’, latitude lat0 on the prime meridian, + is the true bearing of Mecca. +
+ + mecca lat0         equally spaced vertical meridians
+ homing lat0        distances to Mecca are true +
+ + Maps based on the spheroid. Of geodetic quality, these projections + do not make sense for tilted orientations. For descriptions, see + corresponding maps above. +
+ + sp_mercator
+ sp_albers lat0 lat1
+ +

+

EXAMPLES
+ +
+ + 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: map perspective + 1.025 −o 40.75 74 −l 20 60 30 100. A circular border can be forced + by adding option + −w 77.33. (Latitude 77.33° falls just inside a polar cap of opening + angle arccos(1/1.025) = 12.6804°.)
+ +
+ 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° 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 +    map mercator −o 130.75 74
+ +
+ map albers 28 45 −l 20 50 60 130 −m states
+ +
+ + A customary curved-latitude map of the United States.
+ +
+ 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 −o option overrides the default + −o 90 0 180, which would rotate the scene to behind the observer.
+ +
+ +
+

FILES
+ +
+ + /lib/map/[1−4]??   World Data Bank II, for −f
+ /lib/map/*         maps for −m
+ /lib/map/*.x       map indexes
+ mapd              Map driver program
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/map
+ +
+

SEE ALSO
+ +
+ + map(7), plot(1)
+ +
+

DIAGNOSTICS
+ +
+ + ‘Map seems to be empty’--a coarse survey found zero extent within + the −l and −w bounds; for maps of limited extent the grid resolution, + res, or the limits may have to be refined.
+ +
+

BUGS
+ +
+ + Windows (option −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 + −d setting may cause long line segments to be dropped. Map tries + to draw grid lines dotted and −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. Gilbert should be a map + from sphere to sphere, independent of the mapping from sphere + to plane.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/mc.html b/man/man1/mc.html new file mode 100644 index 00000000..1c133aec --- /dev/null +++ b/man/man1/mc.html @@ -0,0 +1,64 @@ + +mc(1) - Plan 9 from User Space + + + + +
+
+
MC(1)MC(1) +
+
+

NAME
+ +
+ + mc – multicolumn print
+ +
+

SYNOPSIS
+ +
+ + mc [ − ] [ −N ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Mc splits the input into as many columns as will fit in N print + positions. If run in a 9term(1), xterm(1), or acme(1) window, + the default N is the number of blanks that will fit across the + window; otherwise the default N is 80. Under option − each input + line ending in a colon : is printed separately. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/draw/mc.c
+ +
+

SEE ALSO
+ +
+ + 9term(1), acme(1), acme(4), xterm(1), pr(1), lc in ls(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/mk.html b/man/man1/mk.html new file mode 100644 index 00000000..3dde6143 --- /dev/null +++ b/man/man1/mk.html @@ -0,0 +1,621 @@ + +mk(1) - Plan 9 from User Space + + + + +
+
+
MK(1)MK(1) +
+
+

NAME
+ +
+ + mk – maintain (make) related files
+ +
+

SYNOPSIS
+ +
+ + mk [ −f mkfile ] ... [ option ... ] [ target ... ]
+ +
+

DESCRIPTION
+ +
+ + Mk uses the dependency rules specified in mkfile to control the + update (usually by compilation) of targets (usually files) from + the source files upon which they depend. The mkfile (default mkfile) + contains a rule for each target that identifies the files and + other targets upon which it depends and an sh(1) script, a + 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. Mkfile may also contain meta-rules that define actions for + updating implicit targets. If no target is specified, the target + of the first rule (not meta-rule) in mkfile is updated. +
+ + The environment variable $NPROC determines how many targets may + be updated simultaneously; Some operating systems, e.g., Plan + 9, set $NPROC automatically to the number of CPUs on the current + machine. +
+ + Options are:
+ −a       Assume all targets to be out of date. Thus, everything is updated.
+ −d[egp]   Produce debugging output (p is for parsing, g for graph + building, e for execution).
+ −e       Explain why each target is made.
+ −i       Force any missing intermediate targets to be made.
+ −k       Do as much work as possible in the face of errors.
+ −n       Print, but do not execute, the commands needed to update the + targets.
+ −s       Make the command line arguments sequentially rather than in + parallel.
+ −t       Touch (update the modified date of) file targets, without executing + any recipes.
+ −wtarget1,target2,...
+ +
+ + +
+ + Pretend the modify time for each target is the current time; useful + in conjunction with −n to learn what updates would be triggered + by modifying the targets.
+ +
+ +
+

The mkfile
+ A mkfile consists of assignments (described under ‘Environment’) + and rules. A rule contains targets and a tail. A target is a literal + string and is normally a file name. The tail contains zero or + more prerequisites and an optional recipe, which is an shell script. + Each line of the recipe must begin with white space. A rule + takes the form
+ +
+ + target: prereq1 prereq2
+ +
+ + recipe using prereq1, prereq2 to build target
+ +
+ + +
+ +
+ When the recipe is executed, the first character on every line + is elided. +
+ + After the colon on the target line, a rule may specify attributes, + described below. +
+ + A meta-rule has a target of the form A%B where A and B are (possibly + empty) strings. A meta-rule acts as a rule for any potential target + whose name matches A%B with % replaced by an arbitrary string, + called the stem. In interpreting a meta-rule, the stem is substituted + for all occurrences of % in the prerequisite + names. In the recipe of a meta-rule, the environment variable + $stem contains the string matched by the %. For example, a meta-rule + to compile a C program using 9c(1) might be:
+ +
+ + %:      %.c
+ +
+ + 9c −c $stem.c
+ 9l −o $stem $stem.o
+ +
+ +
+ +
+ + + +
+ +
+ Meta-rules may contain an ampersand & rather than a percent sign + %. A % matches a maximal length string of any characters; an & + matches a maximal length string of any characters except period + or slash. +
+ + The text of the mkfile is processed as follows. Lines beginning + with < followed by a file name are replaced by the contents of + the named file. Lines beginning with <| 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 # characters + to the following newline, are deleted. The character sequence + backslash-newline is deleted, so long lines in mkfile may be folded. + Non-recipe lines are processed by substituting for `{command} + the output of the command when run by sh. References to variables + are replaced by the variables’ values. Special + characters may be quoted using single quotes '' as in sh(1). +
+ + Assignments and rules are distinguished by the first unquoted + occurrence of : (rule) or = (assignment). +
+ + A later rule may modify or override an existing rule under the + following conditions:
+ –     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.
+ –     If the targets of the rules match exactly and the prerequisites + do not match and both rules contain recipes, mk reports an “ambiguous + recipe” error.
+ –     If the target and prerequisites of both rules match exactly, the + second rule overrides the first.
+

Environment
+ Rules may make use of shell environment variables. A legal reference + of the form $OBJ or ${name} is expanded as in sh(1). A reference + of the form ${name:A%B=C%D}, where A, B, C, D are (possibly empty) + strings, has the value formed by expanding $name and substituting + C for A and D for B in each word in + $name that matches pattern A%B. +
+ + Variables can be set by assignments of the form
+ +
+ + var=[attr=]value
+ +
+ Blanks in the value break it into words. Such variables are exported + to the environment of recipes as they are executed, unless U, + the only legal attribute attr, is present. The initial value of + a variable is taken from (in increasing order of precedence) the + default values below, mk’s environment, the mkfiles, and any + command line assignment as an argument to mk. A variable assignment + argument overrides the first (but not any subsequent) assignment + to that variable. +
+ + The variable MKFLAGS contains all the option arguments (arguments + starting with − or containing =) and MKARGS contains all the targets + in the call to mk. +
+ + The variable MKSHELL contains the shell command line mk uses to + run recipes. If the first word of the command ends in rc or rcsh, + mk uses rc(1)’s quoting rules; otherwise it uses sh(1)’s. The + MKSHELL variable is consulted when the mkfile is read, not when + it is executed, so that different shells can be used within + a single mkfile:
+ +
+ + MKSHELL=$PLAN9/bin/rc
+ use−rc:V:
+ +
+ + for(i in a b c) echo $i
+ +
+ MKSHELL=sh
+ use−sh:V:
+ +
+ + for i in a b c; do echo $i; done
+ +
+ +
+ +
+ + + +
+ +
+ Mkfiles included via < or <| (q.v.) see their own private copy of + MKSHELL, which always starts set to sh . +
+ + Dynamic information may be included in the mkfile by using a line + of the form
+ +
+ + <|command args +
+ + +
+ This runs the command command with the given arguments args and + pipes its standard output to mk to be included as part of the + mkfile. For instance, the Inferno kernels use this technique to + run a shell command with an awk script and a configuration file + as arguments in order for the awk script to process the file + and output a set of variables and their values.
+

Execution
+ +
+ + During execution, mk determines which targets must be updated, + and in what order, to build the names specified on the command + line. It then runs the associated recipes. +
+ + A target is considered up to date if it has no prerequisites or + if all its prerequisites are up to date and it is newer than all + its prerequisites. Once the recipe for a target has executed, + the target is considered up to date. +
+ + The date stamp used to determine if a target is up to date is + computed differently for different types of targets. If a target + is virtual (the target of a rule with the V attribute), its date + stamp is initially zero; when the target is updated the date stamp + is set to the most recent date stamp of its prerequisites. Otherwise, + if a + target does not exist as a file, its date stamp is set to the + most recent date stamp of its prerequisites, or zero if it has + no prerequisites. Otherwise, the target is the name of a file + and the target’s date stamp is always that file’s modification + date. The date stamp is computed when the target is needed in + the execution of + a rule; it is not a static value. +
+ + Nonexistent targets that have prerequisites and are themselves + prerequisites are treated specially. Such a target t is given + the date stamp of its most recent prerequisite and if this causes + all the targets which have t as a prerequisite to be up to date, + t is considered up to date. Otherwise, t is made in the normal + fashion. + The −i flag overrides this special treatment. +
+ + Files may be made in any order that respects the preceding restrictions. + +
+ + A recipe is executed by supplying the recipe as standard input + to the command /bin/sh. (Note that unlike make, mk feeds the entire + recipe to the shell rather than running each line of the recipe + separately.) The environment is augmented by the following variables:
+ $alltarget
+ +
+ + +
+ + all the targets of this rule.
+ +
+ +
+ $newprereq
+ +
+ + +
+ + the prerequisites that caused this rule to execute.
+ +
+ +
+ $newmember
+ +
+ + +
+ + the prerequisites that are members of an aggregate that caused + this rule to execute. When the prerequisites of a rule are members + of an aggregate, $newprereq contains the name of the aggregate + and out of date members, while $newmember contains only the name + of the members. + +
+ +
+ $nproc     the process slot for this recipe. It satisfies 0≤$nproc<$NPROC.
+ $pid       the process id for the mk executing the recipe.
+ $prereq    all the prerequisites for this rule.
+ $stem      if this is a meta-rule, $stem is the string that matched + % or &. Otherwise, it is empty. For regular expression meta-rules + (see below), the variables stem0, ..., stem9 are set to the corresponding + subexpressions.
+ $target    the targets for this rule that need to be remade. +
+ + These variables are available only during the execution of a recipe, + not while evaluating the mkfile. +
+ + Unless the rule has the Q attribute, the recipe is printed prior + to execution with recognizable environment variables expanded. + Commands returning error status cause mk to terminate. +
+ + Recipes and backquoted rc commands in places such as assignments + execute in a copy of mk’s environment; changes they make to environment + variables are not visible from mk. +
+ + Variable substitution in a rule is done when the rule is read; + variable substitution in the recipe is done when the recipe is + executed. For example:
+ +
+ + bar=a.c
+ foo: $bar
+ +
+ + $CC −o foo $bar
+ +
+ bar=b.c
+ +
+ + +
+ will compile b.c into foo, if a.c is newer than foo.
+

Aggregates
+ Names of the form a(b) refer to member b of the aggregate a. Currently, + the only aggregates supported are 9ar (see 9c(1)) archives.
+

Attributes
+ The colon separating the target from the prerequisites may be + immediately followed by attributes and another colon. The attributes + are:
+ D     If the recipe exits with a non-null status, the target is deleted.
+ E     Continue execution if the recipe draws errors.
+ N     If there is no recipe, the target has its time updated.
+ n     The rule is a meta-rule that cannot be a target of a virtual + rule. Only files match the pattern in the target.
+ P     The characters after the P until the terminating : are taken + as a program name. It will be invoked as sh −c prog 'arg1' 'arg2' + and should return a zero exit status if and only if arg1 is up + to date with respect to arg2. Date stamps are still propagated + in the normal way.
+ Q     The recipe is not printed prior to execution.
+ R     The rule is a meta-rule using regular expressions. In the rule, + % has no special meaning. The target is interpreted as a regular + expression as defined in regexp(7). The prerequisites may contain + references to subexpressions in form \n, as in the substitute + command of sed(1).
+ U     The targets are considered to have been updated even if the recipe + did not do so.
+ V     The targets of this rule are marked as virtual. They are distinct + from files of the same name.
+ +

+

EXAMPLES
+ +
+ + A simple mkfile to compile a program:
+ +
+ + </$objtype/mkfile
+ prog: a.$O b.$O c.$O
+ +
+ + $LD $LDFLAGS −o $target $prereq
+ +
+ %.$O: %.c
+ +
+ + $CC $CFLAGS $stem.c
+ +
+ +
+ +
+ + + +
+ +
+ Override flag settings in the mkfile:
+ +
+ + % mk target 'CFLAGS=−S −w'
+ +
+ + +
+ Maintain a library:
+ +
+ + libc.a(%.$O):N:    %.$O
+ libc.a:      libc.a(abs.$O) libc.a(access.$O) libc.a(alarm.$O) ...
+ +
+ + ar r libc.a $newmember
+ +
+ +
+ +
+ + + +
+ +
+ String expression variables to derive names from a master list:
+ +
+ + NAMES=alloc arc bquote builtins expand main match mk var word
+ OBJ=${NAMES:%=%.$O}
+ +
+ + +
+ Regular expression meta-rules:
+ +
+ + ([^/]*)/(.*)\.$O:R:    \1/\2.c
+ +
+ + cd $stem1; $CC $CFLAGS $stem2.c
+ +
+ +
+ +
+ + + +
+ +
+ A correct way to deal with yacc(1) grammars. The file lex.c includes + the file x.tab.h rather than y.tab.h in order to reflect changes + in content, not just modification time.
+ +
+ + lex.$O:      x.tab.h
+ x.tab.h:     y.tab.h
+ +
+ + cmp −s x.tab.h y.tab.h || cp y.tab.h x.tab.h
+ +
+ y.tab.c y.tab.h: gram.y
+ +
+ + $YACC −d gram.y
+ +
+ +
+ +
+ + + +
+ +
+ The above example could also use the P attribute for the x.tab.h + rule:
+ +
+ + x.tab.h:Pcmp −s: y.tab.h
+ +
+ + cp y.tab.h x.tab.h
+ +
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/mk
+ +
+

SEE ALSO
+ +
+ + sh(1), regexp(7) +
+ + A. Hume, “Mk: a Successor to Make” (Tenth Edition Research Unix + Manuals). +
+ + Andrew G. Hume and Bob Flandrena, “Maintaining Files on Plan 9 + with Mk”. DOCPREFIX/doc/mk.pdf
+ +
+

HISTORY
+ +
+ + Andrew Hume wrote mk for Tenth Edition Research Unix. It was later + ported to Plan 9. This software is a port of the Plan 9 version + back to Unix.
+ +
+

BUGS
+ +
+ + Identical recipes for regular expression meta-rules only have + one target. +
+ + Seemingly appropriate input like CFLAGS=−DHZ=60 is parsed as an + erroneous attribute; correct it by inserting a space after the + first =. +
+ + The recipes printed by mk before being passed to the shell for + execution are sometimes erroneously expanded for printing. Don’t + trust what’s printed; rely on what the shell does.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/mk9660.1 b/man/man1/mk9660.1 new file mode 100644 index 00000000..0d655cf0 --- /dev/null +++ b/man/man1/mk9660.1 @@ -0,0 +1,232 @@ +.TH MK9660 1 +.SH NAME +dump9660, mk9660 \- create an ISO-9660 CD image +.SH SYNOPSIS +.B mk9660 +[ +.B -:D +] +[ +.B -9cjr +] +[ +.B -b +.I bootfile +] +[ +.B -p +.I proto +] +[ +.B -s +src +] +[ +.B -v +volume +] +.I image +.PP +.B 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 \*9/proto/allproto ) +from the file tree +.I src +(by default, +the current directory). +The +.I proto +file is formatted as described in +.IR proto (3). +.PP +The created CD image will be in ISO-9660 +format, but by default the file names will +be stored in UTF-8 with no imposed length +or character restrictions. +The +.B -c +flag causes +.I mk9660 +to use only file names in ``8.3'' form +that use digits, letters, and underscore. +File names that do not conform are changed +to +.BI D nnnnnn +(for directories) +or +.BI F nnnnnn +(for files); +a key file +.B _CONFORM.MAP +is created in the root +directory to ease the reverse process. +.PP +If the +.B -9 +flag is given, the system use fields at the end of +each directory entry will be populated with +Plan directory information (owner, group, mode, +full name); this is interpreted by +.IR 9660srv . +.PP +If the +.B -j +flag is given, the usual directory tree is written, +but an additional tree in Microsoft Joliet format is +also added. +This second tree can contain long Unicode file names, +and can be read by +.I 9660srv +as well as most versions of Windows +and many Unix clones. +The characters +.BR * , +.BR : , +.BR ; , +.BR ? , +and +.B \e +are allowed in Plan 9 file names but not in Joliet file names; +non-conforming file names are translated +and a +.B _CONFORM.MAP +file written +as in the case of the +.B -c +option. +.PP +If the +.B -r +flag is given, Rock Ridge extensions are written in the +format of the system use sharing protocol; +this format provides Posix-style file metadata and is +common on Unix platforms. +.PP +The options +.BR -c , +.BR -9 , +.BR -j , +and +.B -r +may be mixed freely with the exception that +.B -9 +and +.B -r +are mutually exclusive. +.PP +The +.B -v +flag sets the volume title; +if unspecified, the base name of +.I proto +is used. +.PP +The +.B -: +flag causes +.B mk9660 +to replace colons in scanned file names with spaces; +this is the inverse of the map applied by Plan 9's +\fIdossrv\fR(4) +and is useful for writing Joliet CDs containing data +from FAT file systems. +.PP +The +.B -b +option creates a bootable CD. +Bootable CDs contain pointers to floppy images which are +loaded and booted by the BIOS. +.I Bootfile +should be the name of the floppy image to use; +it is a path relative to the root of the created CD. +That is, the boot floppy image must be listed in the +.I proto +file already: +the +.B -b +flag just creates a pointer to it. +.PP +The +.B -D +flag creates immense amounts of debugging output +on standard error. +.PP +.I Dump9660 +is similar in specification to +.I mk9660 +but creates and updates backup CD images in the style of +the +.I dump +file system +(see Plan 9's \fIfs\fR(4)). +The dump is file-based rather than block-based: +if a file's contents have not changed since the last +backup, only its directory entry will be rewritten. +.PP +The +.B -n +option specifies a time (in seconds since January 1, 1970) +to be used for naming the dump directory. +.PP +The +.B -m +option specifies a maximum size for the image; +if a backup would cause the image to grow larger than +.IR maxsize , +it will not be written, and +.I dump9660 +will exit with a non-empty status. +.SH EXAMPLE +.PP +Create an image of the Plan 9 source tree, +including a conformant ISO-9660 directory tree, +Plan 9 extensions in the system use fields, and +a Joliet directory tree. +.IP +.EX +mk9660 -9cj -s /n/bootes -p srcproto cdimage +.EE +.SH SOURCE +\*9/src/cmd/9660 +.SH "SEE ALSO +.IR proto (3) +.\" .SH "SEE ALSO" +.\" .I 9660srv +.\" (in +.\" .IR dossrv (4)), +.\" .IR cdfs (4), +.\" .IR proto (3) diff --git a/man/man1/mkdir.html b/man/man1/mkdir.html new file mode 100644 index 00000000..489d8b91 --- /dev/null +++ b/man/man1/mkdir.html @@ -0,0 +1,79 @@ + +mkdir(1) - Plan 9 from User Space + + + + +
+
+
MKDIR(1)MKDIR(1) +
+
+

NAME
+ +
+ + mkdir – make a directory
+ +
+

SYNOPSIS
+ +
+ + mkdir [ −p ] [ −m mode ] dirname ...
+ +
+

DESCRIPTION
+ +
+ + Mkdir creates the specified directories. It requires write permission + in the parent directory. +
+ + If the −p flag is given, mkdir creates any necessary parent directories + and does not complain if the target directory already exists. + +
+ + The −m flag sets the permissions to be used when creating the + directory. The default is 0777.
+ +
+

SEE ALSO
+ +
+ + rm(1)
+ cd in rc(1)
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/mkdir.c
+ +
+

DIAGNOSTICS
+ +
+ + Mkdir returns null exit status if all directories were successfully + made. Otherwise it prints a diagnostic and returns "error" status.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/namespace.html b/man/man1/namespace.html new file mode 100644 index 00000000..45ae83bc --- /dev/null +++ b/man/man1/namespace.html @@ -0,0 +1,61 @@ + +namespace(1) - Plan 9 from User Space + + + + +
+
+
NAMESPACE(1)NAMESPACE(1) +
+
+

NAME
+ +
+ + namespace – print name space directory
+ +
+

SYNOPSIS
+ +
+ + namespace
+ +
+

DESCRIPTION
+ +
+ + Namespace prints the directory representing the current name space. + See intro(4).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/namespace.c
+ +
+

SEE ALSO
+ +
+ + getns(3), intro(4)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/news.html b/man/man1/news.html new file mode 100644 index 00000000..29cede42 --- /dev/null +++ b/man/man1/news.html @@ -0,0 +1,91 @@ + +news(1) - Plan 9 from User Space + + + + +
+
+
NEWS(1)NEWS(1) +
+
+

NAME
+ +
+ + news – print news items
+ +
+

SYNOPSIS
+ +
+ + news [ −a ] [ −n ] [ item ... ]
+ +
+

DESCRIPTION
+ +
+ + When invoked without options, this simple local news service prints + files that have appeared in /lib/news since last reading, most + recent first, with each preceded by an appropriate header. The + time of reading is recorded. The options are
+ −a    Print all items, regardless of currency. The recorded time is + not changed.
+ −n    Report the names of the current items without printing their + contents, and without changing the recorded time. +
+ + Other arguments select particular news items. +
+ + To post a news item, create a file in /usr/local/plan9/news. +
+ + Empty news items, and news items named core or dead.letter are + ignored.
+ +
+

FILES
+ +
+ + /usr/local/plan9/news/*
+ +
+ + articles
+ +
+ $HOME/lib/newstime
+ +
+ + modify time is time news was last read who gets news mailed to + them
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/news.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/p.html b/man/man1/p.html new file mode 100644 index 00000000..a2339d2f --- /dev/null +++ b/man/man1/p.html @@ -0,0 +1,63 @@ + +p(1) - Plan 9 from User Space + + + + +
+
+
P(1)P(1) +
+
+

NAME
+ +
+ + p – paginate
+ +
+

SYNOPSIS
+ +
+ + p [ −number ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + 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 + number of lines on a page. +
+ + While waiting for a newline, p interprets the commands:
+ !     Pass the rest of the line to the shell as a command.
+ q     Quit. +
+ + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/p.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/page.html b/man/man1/page.html new file mode 100644 index 00000000..91b48993 --- /dev/null +++ b/man/man1/page.html @@ -0,0 +1,97 @@ + +page(1) - Plan 9 from User Space + + + + +
+
+
PAGE(1)PAGE(1) +
+
+

NAME
+ +
+ + img, psv – view FAX, image, graphic, PostScript, PDF, and typesetter + output files
+ +
+

SYNOPSIS
+ +
+ + page [ file... ] +
+ + img file.bit +
+ + psv file.ps +
+ + psv file.pdf
+ +
+

DESCRIPTION
+ +
+ + Plan 9’s page(1) is not ported. Instead, page is a script that + invokes qiv(1) to view graphic files or psv to view PostScript + and PDF. On Mac OS X, page invokes Preview to handle all files. + +
+ + Img is a simple image viewer for Plan 9 images (see image(7)). + +
+ + Psv is a PostScript and PDF viewer. It is a streamlined interface + to gv(1). +
+ + To view troff output, use proof(1).
+ +
+

SEE ALSO
+ +
+ + gs(1), gv(1), jpg(1), proof(1), tex(1), troff(1)
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/draw/img.c
+ /usr/local/plan9/bin/psv
+ +
+

BUGS
+ +
+ + When using Preview on Mac OS X, page leaves temporary files in + /var/tmp, since it has no way to know when the viewer has exited. + +
+ + Page does not handle Plan 9 image(7) files; use img explicitly.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/pic.html b/man/man1/pic.html new file mode 100644 index 00000000..acba241b --- /dev/null +++ b/man/man1/pic.html @@ -0,0 +1,435 @@ + +pic(1) - Plan 9 from User Space + + + + +
+
+
PIC(1)PIC(1) +
+
+

NAME
+ +
+ + pic, tpic – troff and tex preprocessors for drawing pictures
+ +
+

SYNOPSIS
+ +
+ + pic [ files ] +
+ + tpic [ files ]
+ +
+

DESCRIPTION
+ +
+ + Pic is a troff(1) preprocessor for drawing figures on a typesetter. + Pic code is contained between .PS and .PE lines:
+ +
+ + .PS optional-width optional-height
+ element-list
+ .PE
+ +
+ + +
+ or in a file mentioned in a .PS line:
+ +
+ + .PS <file +
+ + +
+ If 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 optional-height is present. + If .PF is used instead of .PE, the typesetting position after + printing is restored to what it was upon entry. +
+ + An element-list is a list of elements:
+ +
+ + primitive attribute-list
+ placename : element
+ placename : position
+ var = expr
+ direction
+ { element-list }
+ [ element-list ]
+ for var = expr to expr by expr do { anything }
+ if expr then { anything } else { anything }
+ copy file,    copy thru macro,    copy file thru macro
+ sh { commandline }
+ print expr
+ reset optional var-list
+ troff-command
+ +
+ + +
+ 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 # 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. +
+ + After each primitive the current position moves in the current + direction (up,down, left,right (default)) by the size of the primitive. + The current position and direction are saved upon entry to a {...} + block and restored upon exit. Elements within a block enclosed + in [...] 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. +
+ + 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. +
+ + The primitive objects are:
+ +
+ + box    circle    ellipse    arc    line    arrow    spline    move    text-list
+ +
+ arrow is a synonym for line −>. +
+ + An attribute-list is a sequence of zero or more attributes; each + attribute consists of a keyword, perhaps followed by a value.
+ +
+ + +
+ + h(eigh)t expr           wid(th) expr
+ rad(ius) expr           diam(eter) expr
+ up opt-expr              down opt-expr
+ right opt-expr           left opt-expr
+ from position             to position
+ at position               with corner
+ by expr, expr             then
+ dotted opt-expr          dashed opt-expr
+ chop opt-expr            −>    <−    <−>
+ invis                  same
+ fill opt-expr
+ text-list                 expr
+ +
+ +
+ Missing attributes and values are filled in from defaults. Not + all attributes make sense for all primitives; irrelevant ones + are silently ignored. The attribute at causes the geometrical + center to be put at the specified place; with causes the position + on the object to be put at the specified place. For lines, splines + and + arcs, height and width refer to arrowhead size. A bare expr implies + motion in the current direction. +
+ + 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:
+ +
+ + text-item:
+ +
+ + "..." +
+ +
+ + positioning ...
+ sprintf("format", expr, ...) positioning ...
+ +
+ positioning:
+ +
+ + center    ljust    rjust    above    below
+ +
+ +
+ 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 + 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. +
+ + A position is ultimately an x,y coordinate pair, but it may be + specified in other ways.
+ +
+ + position:
+ +
+ + expr, expr
+ place ± expr, expr
+ place ± ( expr, expr )
+ ( position, position )        x from one, y the other
+ expr [of the way] between position and position
+ expr < position , position >
+ ( position )
+ +
+ + +
+ place:
+ +
+ + placename optional-corner
+ corner of placename
+ nth primitive optional-corner
+ corner of nth primitive
+ Here
+ +
+ +
+ An optional-corner is one of the eight compass points or the center + or the start or end of a primitive.
+ +
+ + optional-corner:
+ +
+ + .n    .e    .w    .s    .ne    .se    .nw    .sw    .c    .start    .end
+ +
+ corner:
+ +
+ + top    bot    left    right    start    end
+ +
+ +
+ Each object in a picture has an ordinal number; nth refers to + this.
+ +
+ + nth:
+ +
+ + nth,    nth last
+ +
+ + +
+ +
+ The built-in variables and their default values are:
+ +
+ + +
+ + 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
+ +
+ +
+ 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 reset statement. Variables changed within [ and ] revert to + their previous value upon exit from the block. Dimensions are + divided by scale during output. +
+ + Expressions in pic are evaluated in floating point. All numbers + representing dimensions are taken to be in inches.
+ +
+ + expr:
+ +
+ + expr op expr
+ − expr
+ ! expr
+ ( expr )
+ variable
+ number
+ place .x    place .y    place .ht    place .wid    place .rad
+ sin(expr)    cos(expr)    atan2(expr,expr)    log(expr)    exp(expr)
+ sqrt(expr)    max(expr,expr)    min(expr,expr)    int(expr)    rand()
+ +
+ op:
+ +
+ + +    −    *    /    %    <    <=    >    >=    ==    !=    &&    ||
+ +
+ +
+ +
+ + + +
+ +
+ The define and undef statements are not part of the grammar.
+ +
+ + +
+ + define name { replacement text }
+ undef name
+ +
+ +
+ Occurrences of $1, $2, etc., in the replacement text will be replaced + by the corresponding arguments if name is invoked as
+ +
+ + +
+ + name(arg1, arg2, ...)
+ +
+ +
+ Non-existent arguments are replaced by null strings. Replacement + text may contain newlines. The undef statement removes the definition + of a macro. +
+ + Tpic is a tex(1) preprocessor that accepts pic language. It produces + Tex commands that define a box called \graph, which contains the + picture. The box may be output this way:
+ +
+ + \centerline{\box\graph}
+ +
+ +
+

EXAMPLES
+ +
+ + 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 <A.c, A.ne>
+ circle rad .065 at 0.5 <A.c, A.ne>
+ 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 }
+ +
+ +
+ +
+ + + +
+ 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 <A.c, A.ne>
+ circle rad .065 at 0.5 <A.c, A.ne>
+ 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 }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/pic
+ +
+

SEE ALSO
+ +
+ + grap(1), doctype(1), troff(1)
+ B. W. Kernighan, “PIC--a Graphics Language for Typesetting”, Unix + Research System Programmer’s Manual, Tenth Edition, Volume 2
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/plot.html b/man/man1/plot.html new file mode 100644 index 00000000..b93d6d34 --- /dev/null +++ b/man/man1/plot.html @@ -0,0 +1,88 @@ + +plot(1) - Plan 9 from User Space + + + + +
+
+
PLOT(1)PLOT(1) +
+
+

NAME
+ +
+ + plot – graphics filter
+ +
+

SYNOPSIS
+ +
+ + plot [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Plot interprets plotting instructions (see plot(7)) from the files + or standard input, drawing the results in a newly created rio(1) + window. Plot persists until a newline is typed in the window. + Various options may be interspersed with the file arguments; they + take effect at the given point in processing. Options are: + −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.
+ −e        Erase the screen.
+ −c col     Set the foreground color (see plot(7) for color names).
+ −f fill     Set the background color.
+ −g grade   Set the quality factor for arcs. Higher grades give better + quality.
+ −p col     Set the pen color.
+ −w        Pause until a newline is typed on standard input.
+ −C        Close the current plot.
+ −W    x0,y0,x1,y1
+ +
+ + +
+ + Specify the bounding rectangle of plot’s window. By default it + uses a 512x512 window in the middle of the screen.
+ +
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/plot
+ +
+

SEE ALSO
+ +
+ + rio(1), plot(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/plumb.html b/man/man1/plumb.html new file mode 100644 index 00000000..2a868f7a --- /dev/null +++ b/man/man1/plumb.html @@ -0,0 +1,80 @@ + +plumb(1) - Plan 9 from User Space + + + + +
+
+
PLUMB(1)PLUMB(1) +
+
+

NAME
+ +
+ + plumb – send message to plumber
+ +
+

SYNOPSIS
+ +
+ + plumb [ −p plumbfile ] [ −a attributes ] [ −s source ] [ −d destination + ] [ −t type ] [ −w directory ] −i | data...
+ +
+

DESCRIPTION
+ +
+ + The 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:
+ −p    write the message to plumbfile (default /mnt/plumb/send).
+ −a    set the attr field of the message (default is empty).
+ −s    set the src field of the message (default is plumb).
+ −d    set the dst field of the message (default is empty).
+ −t    set the type field of the message (default is text).
+ −w    set the wdir field of the message (default is the current working + directory of plumb).
+ −i    take the data from standard input rather than the argument strings. + If an action= attribute is not otherwise specified, plumb will + add an action=showdata attribute to the message.
+ +
+

FILES
+ +
+ + $HOME/lib/plumbing   default rules file
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/plumb
+ +
+

SEE ALSO
+ +
+ + plumb(3), plumber(4), plumb(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/pr.html b/man/man1/pr.html new file mode 100644 index 00000000..ca8772b2 --- /dev/null +++ b/man/man1/pr.html @@ -0,0 +1,90 @@ + +pr(1) - Plan 9 from User Space + + + + +
+
+
PR(1)PR(1) +
+
+

NAME
+ +
+ + pr – print file
+ +
+

SYNOPSIS
+ +
+ + pr [ option ... ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Pr produces a printed listing of one or more 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, pr prints its standard input. +
+ + Options apply to all following files but may be reset between + files:
+ −n    Produce n-column output.
+ +n    Begin printing with page n.
+ −b    Balance columns on last page, in case of multi-column output.
+ −d    Double space.
+ −en   Set the tab stops for input text every n spaces.
+ −h    Take the next argument as a page header (file by default).
+ −in   Replace sequences of blanks in the output by tabs, using tab + stops set every n spaces.
+ −f    Use form feeds to separate pages.
+ −ln   Take the length of the page to be n lines instead of the default + 66.
+ −m    Print all files simultaneously, each in one column.
+ −nm   Number the lines of each file. The numeric argument m, default + 5, sets the width of the line-number field.
+ −on   Offset the left margin n character positions.
+ −p    Pad each file printed to an odd number of pages. For two-sided + printers, this will ensure each file will start a new page.
+ −sc   Separate columns by the single character c instead of aligning + them with white space. A missing c is taken to be a tab.
+ −t    Do not print the 5-line header or the 5-line trailer normally + supplied for each page.
+ −wn   For multi-column output, take the width of the page to be n + characters instead of the default 72.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/pr.c
+ +
+

SEE ALSO
+ +
+ + cat(1), lp(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/proof.html b/man/man1/proof.html new file mode 100644 index 00000000..a442fd71 --- /dev/null +++ b/man/man1/proof.html @@ -0,0 +1,119 @@ + +proof(1) - Plan 9 from User Space + + + + +
+
+
PROOF(1)PROOF(1) +
+
+

NAME
+ +
+ + proof – troff output interpreter
+ +
+

SYNOPSIS
+ +
+ + proof [ −mmag ] [ −/nview ] [ −F dir ] [ −d ] [ file ]
+ +
+

DESCRIPTION
+ +
+ + Proof reads troff(1) intermediate language from file or standard + input and simulates the resulting pages on the screen. +
+ + After a page of text is displayed, proof pauses for a command + from the keyboard. The typed commands are:
+ newlineGo on to next page of text.
+ −      Go back to the previous page.
+ q      Quit.
+ pn     Print page 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.
+ n      Same as pn.
+ c      Clear the screen, then wait for another command.
+ mmag   Change the magnification at which the output is printed. Normally + it is printed with magnification .9; mag=.5 shrinks it to half + size; mag=2 doubles the size.
+ xval    Move everything val screen pixels to the right (left, if val + is negative).
+ yval    Move everything val screen pixels down (up, if val is negative).
+ /nview   Split the window into nview pieces. The current page goes + into the rightmost, bottommost piece, and previous pages are shown + in the other pieces.
+ −F dirUse dir for fonts instead of /lib/font/bit.
+ d      Toggle the debug flag. +
+ + These commands are also available, under slightly different form, + from a menu on button 3. The pan menu item allows arbitrary positioning + of the page: after selecting 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. +
+ + The m, x, y, F, /, and d commands are also available as command + line options.
+ +
+

FILES
+ +
+ + /usr/local/plan9/font/*
+ +
+ + fonts
+ +
+ /usr/local/plan9/font/MAP
+ +
+ + how to convert troff output fonts and character names into screen + fonts and character numbers
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/proof
+ +
+

SEE ALSO
+ +
+ + lp(1), gs(1), page(1)
+ J. F. Ossanna and B. W. Kernighan, “Troff User’s Manual”
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/ps.html b/man/man1/ps.html new file mode 100644 index 00000000..bf19c676 --- /dev/null +++ b/man/man1/ps.html @@ -0,0 +1,95 @@ + +ps(1) - Plan 9 from User Space + + + + +
+
+
PS(1)PS(1) +
+
+

NAME
+ +
+ + ps, psu – process status
+ +
+

SYNOPSIS
+ +
+ + ps [ −pa ] +
+ + psu [ −pa ] [ user ]
+ +
+

DESCRIPTION
+ +
+ + Ps prints information about processes. Psu prints only information + about processes started by user (default $USER). +
+ + 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:
+ Moribund   Process has exited and is about to have its resources + reclaimed.
+ Ready      on the queue of processes ready to be run.
+ Scheding   about to be run.
+ Running    running.
+ Queueing   waiting on a queue for a resource.
+ Wakeme     waiting for I/O or some other kernel event to wake it up.
+ Broken     dead of unnatural causes; lingering so that it can be examined.
+ Stopped    stopped.
+ Stopwait   waiting for another process to stop.
+ Fault      servicing a page fault.
+ Idle       waiting for something to do (kernel processes only).
+ New        being created.
+ Pageout    paging out some other process.
+ Syscall      performing the named system call.
+ no resource   waiting for more of a critical resource.
+ wchan       waiting on the named wait channel (on a Unix kernel). +
+ + With the −p flag, ps also prints, after the system time, the baseline + and current priorities of each process. +
+ + The −a flag causes ps to print the arguments for the process. + Newlines in arguments will be translated to spaces for display.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin/ps
+ /usr/local/plan9/bin/psu
+ +
+

SEE ALSO
+ +
+ + acid(1), db(1), kill(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/psfonts.html b/man/man1/psfonts.html new file mode 100644 index 00000000..b0510a81 --- /dev/null +++ b/man/man1/psfonts.html @@ -0,0 +1,148 @@ + +psfonts(1) - Plan 9 from User Space + + + + +
+
+
PSFONTS(1)PSFONTS(1) +
+
+

NAME
+ +
+ + psfonts, psdownload – add necessary fonts to PostScript document + for printing
+ +
+

SYNOPSIS
+ +
+ + psfonts [ files ... ] +
+ + psdownload [ options ] [ files ... ]
+ +
+

DESCRIPTION
+ +
+ + Plan 9’s troff(1) and tr2post(1) use non-standard PostScript fonts + (found in /usr/local/plan9/postscript/font). Before sending PostScript + output from tr2post to a standard printer, code implementing the + non-standard fonts must be added to the PostScript. +
+ + Psfonts copies files (or standard input) to standard output, adding + necessary PostScript fonts. +
+ + Psdownload is the more general program used to implement psfonts. + The options are:
+ −c comment
+ +
+ + Expect the fonts used in the document to be listed in a comment + beginning with this string (default %%DocumentFonts:).
+ +
+ −f atend
+ +
+ + Expect extra fonts comments at the end of the document, so read + the entire input before starting output (by default this only + happens if a %%DocumentFonts: (atend) comment is encountered).
+ +
+ −m mapfile
+ +
+ + Use mapfile to translate from PostScript font names to files. + Each line in the map has two white space-separated fields: a font + name and the corresponding file. If mapfile is not a rooted path, + it is evaluated relative to the fontdir (see −H below).
+ +
+ −p printer
+ +
+ + Set the name of the printer. This option is deprecated. Its only + effect is to override the −r option, causing fontdir/printers/printer + to be used as the resident fonts list.
+ +
+ −r residentfonts
+ +
+ + Read a list of fonts assumed to be on the printer (not necessary + to re-download) from the file residentfonts. If residentfonts + is not a rooted path, it is evaluated relative to the fontdir + (see −H below).
+ +
+ −H fontdir
+ +
+ + Set the directory that is assumed to contain the PostScript fonts + and information about printers (see −m, −p, and −r above; default + /usr/local/plan9/postscript/font).
+ +
+ −T tmpdir
+ +
+ + Use tmpdir for storing temporary files (default /var/tmp).
+ +
+ −D    Produce copious amounts of debugging information on standard + error.
+ −I    Continue running even after fatal errors occur.
+ +
+

EXAMPLE
+ +
+ + See tr2post(1) for an example.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin/psfonts
+ /usr/local/plan9/src/cmd/postscript/download
+ +
+

SEE ALSO
+ +
+ + troff(1), tr2post(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/pwd.html b/man/man1/pwd.html new file mode 100644 index 00000000..ab8b8c3d --- /dev/null +++ b/man/man1/pwd.html @@ -0,0 +1,73 @@ + +pwd(1) - Plan 9 from User Space + + + + +
+
+
PWD(1)PWD(1) +
+
+

NAME
+ +
+ + pwd, pbd – working directory
+ +
+

SYNOPSIS
+ +
+ + pwd
+ pbd
+ +
+

DESCRIPTION
+ +
+ + Pwd prints the path name of the working (current) directory. +
+ + 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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/pbd.c
+ +
+

SEE ALSO
+ +
+ + cd in rc(1), getwd(3)
+ +
+

BUGS
+ +
+ + Pwd is not provided. Unix already provides one.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/rc.html b/man/man1/rc.html new file mode 100644 index 00000000..a599adfd --- /dev/null +++ b/man/man1/rc.html @@ -0,0 +1,655 @@ + +rc(1) - Plan 9 from User Space + + + + +
+
+
RC(1)RC(1) +
+
+

NAME
+ +
+ + rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., + ~ – command language
+ +
+

SYNOPSIS
+ +
+ + rc [ −srdiIlxepvV ] [ −c command ] [ file [ arg ... ]]
+ +
+

DESCRIPTION
+ +
+ + Rc is the Plan 9 shell. It executes command lines read from a + terminal or a file or, with the −c flag, from rc’s argument list.
+

Command Lines
+ A command line is a sequence of commands, separated by ampersands + or semicolons (& or ;), terminated by a newline. The commands are + executed in sequence from left to right. Rc does not wait for + a command followed by & to finish executing before starting the + following command. Whenever a command + followed by & is executed, its process id is assigned to the rc + variable $apid. Whenever a command not followed by & exits or is + terminated, the rc variable $status gets the process’s wait message + (see wait(3)); it will be the null string if the command was successful. + +
+ + A long command line may be continued on subsequent lines by typing + a backslash (\) followed by a newline. This sequence is treated + as though it were a blank. Backslash is not otherwise a special + character. +
+ + A number-sign (#) and any following characters up to (but not + including) the next newline are ignored, except in quotation marks.
+

Simple Commands
+ A simple command is a sequence of arguments interspersed with + I/O redirections. If the first argument is the name of an rc function + or of one of rc’s built-in commands, it is executed by rc. Otherwise + if the name starts with a slash (/), 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 $path. The first executable file of the given name found in + a directory in $path is the program to be executed. To be executable, + the user must have execute permission (see stat(3)) 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 /bin/rc), + prefixed by #!. +
+ + The first word of a simple command cannot be a keyword unless + it is quoted or otherwise disguised. The keywords are
+ +
+ + for in while if not switch fn ~ ! @
+ +
+

Arguments and Variables
+ A number of constructions may be used where 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. +
+ + 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:
+ +
+ + # ; & | ^ $ = ` ' { } ( ) < >
+ +
+ An unquoted word that contains any of the characters * ? [ is + a pattern for matching against file names. The character * matches + any sequence of characters, ? matches any single character, and + [class] matches any character in the class. If the first character + of class is ~, the class is complemented. The class may + also contain pairs of characters separated by −, standing for + all characters lexically between the two. The character / must + appear explicitly in a pattern, as must the first character of + the path name components . and ... 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,
+ +
+ + x=/tmp echo $x^/*.c
+ +
+ matches /tmp/*.c, rather than matching /*.c and then prefixing + /tmp. +
+ + A quoted word is a sequence of characters surrounded by single + quotes ('). A single quote is represented in a quoted word by + a pair of quotes (''). +
+ + Each of the following is an argument.
+ (arguments)
+ +
+ + 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:
+ +
+ + echo hi there everybody
+ ((echo) (hi there) everybody)
+ +
+ +
+ $argument
+ $argument(subscript)
+ +
+ + The argument after the $ 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 argument is a number n, the value is the nth element of $*, + unless $* doesn’t have n elements, in which case the value is + empty. If argument is followed by a parenthesized list of subscripts, + the value substituted is a list composed of the requested elements + (origin 1). The parenthesis must follow the variable name with + no spaces. Assignments to variables are described below.
+ +
+ $#argument
+ +
+ + The value is the number of elements in the named variable. A variable + never assigned a value has zero elements.
+ +
+ $"argument
+ +
+ + 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.
+ +
+ `{command}
+ +
+ + rc executes the command and reads its standard output, splitting + it into a list of arguments, using characters in $ifs as separators. + If $ifs is not otherwise set, its value is ' \t\n'.
+ +
+ <{command}
+ >{command}
+ +
+ + The 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 old and new + and uses cmp to compare their outputs
+ +
+ + cmp <{old} <{new}
+ +
+ +
+ argument^argument
+ +
+ + The ^ 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.
+ +
+

Free Carets
+ In most circumstances, rc will insert the ^ operator automatically + between words that are not separated by white space. Whenever + one of $ ' ` follows a quoted or unquoted word or an unquoted + word follows a quoted word with no intervening blanks or tabs, + a ^ is inserted between the two. If an unquoted word + immediately follows a $ and contains a character other than an + alphanumeric, underscore, or *, a ^ is inserted before the first + such character. Thus
+ +
+ + cc −$flags $stem.c +
+ + +
+ is equivalent to
+ +
+ + cc −^$flags $stem^.c
+ +
+

I/O Redirections
+ The sequence >file redirects the standard output file (file descriptor + 1, normally the terminal) to the named file; >>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 <file, or from an inline ‘here document’ by the + sequence <<eof-marker. The contents of a here document are lines + of text taken from the command input stream up to a line containing + nothing but the eof-marker, which may be either a quoted or unquoted + word. If eof-marker is unquoted, variable names of the form $word + have their values substituted from rc’s + environment. If $word is followed by a caret (^), the caret is + deleted. If eof-marker is quoted, no substitution occurs. +
+ + 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 cc junk.c >[2]junk. + +
+ + A file descriptor may be redirected to an already open descriptor + by writing >[fd0=fd1] or <[fd0=fd1]. Fd1 is a previously opened + file descriptor and fd0 becomes a new copy (in the sense of dup(3)) + of it. A file descriptor may be closed by writing >[fd0=] or <[fd0=]. + +
+ + Redirections are executed from left to right. Therefore, cc junk.c + >/dev/null >[2=1] and cc junk.c >[2=1] >/dev/null have different effects: + the first puts standard output in /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 /dev/null.
+

Compound Commands
+ A pair of commands separated by a pipe operator (|) 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. |[fd] connects + the output end of the pipe to file descriptor fd rather + than 1. |[fd0=fd1] connects output to fd1 of the left command + and input to fd0 of the right command. +
+ + A pair of commands separated by && or || is a command. In either + case, the left command is executed and its exit status examined. + If the operator is && the right command is executed if the left + command’s status is null. || causes the right command to be executed + if the left command’s status is non-null. +
+ + 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 !. + +
+ + The | operator has highest precedence, and is left-associative + (i.e. binds tighter to the left than the right). ! has intermediate + precedence, and && and || have the lowest precedence. +
+ + The unary @ operator, with precedence equal to !, causes its operand + to be executed in a subshell. +
+ + Each of the following is a command.
+ if ( list ) command
+ +
+ + A list is a sequence of commands, separated by &, ;, or newline. + It is executed and if its exit status is null, the command is + executed.
+ +
+ if not command
+ +
+ + The immediately preceding command must have been if(list) command. + If its condition was non-zero, the command is executed.
+ +
+ for(name in arguments) command
+ for(name) command
+ +
+ + The command is executed once for each argument with that argument + assigned to name. If the argument list is omitted, $* is used.
+ +
+ while(list) command
+ +
+ + The list is executed repeatedly until its exit status is non-null. + Each time it returns null status, the command is executed. An + empty list is taken to give null status.
+ +
+ switch(argument){list}
+ +
+ + The list is searched for simple commands beginning with the word + case. (The search is only at the ‘top level’ of the list. That + is, cases in nested constructs are not found.) Argument is matched + against each word following case using the pattern-matching algorithm + described above, except that / and the + first characters of . and .. need not be matched explicitly. When + a match is found, commands in the list are executed up to the + next following case command (at the top level) or the closing + brace.
+ +
+ {list}
+ +
+ + Braces serve to alter the grouping of commands implied by operator + priorities. The body is a sequence of commands separated by &, + ;, or newline.
+ +
+ fn name{list}
+ fn name
+ +
+ + The first form defines a function with the given name. Subsequently, + whenever a command whose first argument is name is encountered, + the current value of the remainder of the command’s argument list + will be assigned to $*, after saving its current value, and rc + will execute the list. The second form removes + name’s function definition.
+ +
+ fn note{list}
+ fn note
+ +
+ + A function with a special name will be called when rc receives + a corresponding note; see notify(3). The valid note names (and + corresponding notes) are sighup (hangup), sigint (interrupt), + sigalrm (alarm), and sigfpe (floating point trap). By default + rc exits on receiving any signal, except when + run interactively, in which case interrupts and quits normally + cause rc to stop whatever it’s doing and start reading a new command. + The second form causes rc to handle a signal in the default manner. + Rc recognizes an artificial note, sigexit, which occurs when rc + is about to finish executing. + +
+ name=argument command
+ +
+ + 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. + +
+

Built-in Commands
+ These commands are executed internally by rc, usually because + their execution changes or depends on rc’s internal state.
+ . file ...
+ +
+ + Execute commands from file. $* is set for the duration to the + remainder of the argument list following file. File is searched + for using $path.
+ +
+ builtin command ...
+ +
+ + Execute command as usual except that any function named command + is ignored in favor of the built-in meaning.
+ +
+ cd [dir]
+ +
+ + Change the current directory to dir. The default argument is $home. + dir is searched for in each of the directories mentioned in $cdpath.
+ +
+ eval [arg ...]
+ +
+ + The arguments are concatenated separated by spaces into a single + string, read as input to rc, and executed.
+ +
+ exec [command ...]
+ +
+ + This instance of rc replaces itself with the given (non-built-in) + command.
+ +
+ flag f [+−]
+ +
+ + Either set (+), clear (−), or test (neither + nor −) the flag + f, where f is a single character, one of the command line flags + (see Invocation, below).
+ +
+ exit [status]
+ +
+ + Exit with the given exit status. If none is given, the current + value of $status is used.
+ +
+ rfork [nNeEsfFm]
+ +
+ + Become a new process group using rfork(flags) where flags is composed + of the bitwise OR of the rfork flags specified by the option letters + (see fork(2)). If no flags are given, they default to ens. The + flags and their meanings are: n is RFNAMEG; N is RFCNAMEG; e is + RFENVG; E is RFCENVG; s is + RFNOTEG; f is RFFDG; F is RFCFDG; and m is RFNOMNT.
+ +
+ shift [n]
+ +
+ + Delete the first n (default 1) elements of $*.
+ +
+ wait [pid]
+ +
+ + Wait for the process with the given pid to exit. If no pid is + given, all outstanding processes are waited for.
+ +
+ whatis name ...
+ +
+ + Print the value of each name in a form suitable for input to rc. + The output is an assignment to any variable, the definition of + any function, a call to builtin for any built-in command, or the + completed pathname of any executable file.
+ +
+ ~ subject pattern ...
+ +
+ + The subject is matched against each pattern in sequence. If it + matches any pattern, $status is set to zero. Otherwise, $status + is set to one. Patterns are the same as for file name matching, + except that / and the first character of . and .. need not be + matched explicitly. The patterns are not subjected to + file name matching before the ~ command is executed, so they need + not be enclosed in quotation marks.
+ +
+

Environment
+ The environment is a list of strings made available to executing + binaries by the kernel. 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 + = and its value. If the value has more than one component, + these are separated by SOH (001) characters. The string for a + function is just the rc input that defines the function. The name + of a function in the environment is the function name preceded + by fn#. +
+ + When rc starts executing it reads variable and function definitions + from its environment.
+

Special Variables
+ The following variables are set or used by rc.
+ $*        Set to rc’s argument list during initialization. Whenever a + . command or a function is executed, the current value is saved + and $* receives the new argument list. The saved value is restored + on completion of the . or function.
+ $apid     Whenever a process is started asynchronously with &, $apid + is set to its process id.
+ $home     The default directory for cd.
+ $ifs      The input field separators used in backquote substitutions. + If $ifs is not set in rc’s environment, it is initialized to blank, + tab and newline.
+ $path     The search path used to find commands and input files for + the . command. If not set in the environment, it is initialized + by parsing the $PATH variable (as in sh(1)) or by path=(. /bin). + The variables $path and $PATH are maintained together: changes + to one will be reflected in the other. + $pid      Set during initialization to rc’s process id.
+ $prompt   When rc is run interactively, the first component of $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 prompt=('% ' ' '). + $status   Set to the wait message of the last-executed program. (unless + started with &). ! and ~ also change $status. Its value is used + to control execution in &&, ||, if and while commands. When rc exits + at end-of-file of its input or on executing an exit command with + no argument, $status is its + +
+ + +
+ + exit status.
+ +
+ +
+

Invocation
+ If 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 −c below). Subsequent + arguments become the initial value of $*. Rc accepts the following + command-line flags.
+ −c string   Commands are read from string.
+ −s        Print out exit status after any command where the status is + non-null.
+ −e        Exit if $status is non-null after executing a simple command.
+ −i        If −i is present, or rc is given no arguments and its standard + input is a terminal, it runs interactively. Commands are prompted + for using $prompt.
+ −I        Makes sure rc is not run interactively.
+ −l        If −l is given or the first character of argument zero is −, + rc reads commands from $home/lib/profile, if it exists, before + reading its normal input.
+ −p        A no-op.
+ −d        A no-op.
+ −v        Echo input on file descriptor 2 as it is read.
+ −x        Print each simple command before executing it.
+ −r        Print debugging information (internal form of commands as they + are executed).
+ +

+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/rc
+ +
+

SEE ALSO
+ +
+ + Tom Duff, “Rc – The Plan 9 Shell”.
+ +
+

BUGS
+ +
+ + There should be a way to match patterns against whole lists rather + than just single strings. +
+ + Using ~ to check the value of $status changes $status. +
+ + Functions that use here documents don’t work. +
+ + Free carets don’t get inserted next to keywords. +
+ + The <{command} syntax depends on the underlying operating system + providing a file descriptor device tree at /dev/fd. +
+ + By default, FreeBSD 5 does not provide file descriptors greater + than 2 in /dev/fd. To fix this, add
+ +
+ + /fdescfs      /dev/fd      fdescfs      rw      0      0
+ +
+ + +
+ to /etc/fstab, and then mount /dev/fd. (Adding the line to fstab + ensures causes FreeBSD to mount the file system automatically + at boot time.)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/rio.html b/man/man1/rio.html new file mode 100644 index 00000000..ad3f9adc --- /dev/null +++ b/man/man1/rio.html @@ -0,0 +1,172 @@ + +rio(1) - Plan 9 from User Space + + + + +
+
+
RIO(1)RIO(1) +
+
+

NAME
+ +
+ + rio – rio-like Window Manager for X
+ +
+

SYNOPSIS
+ +
+ + rio [ –font fontname ] [ –grey ] [ –s ] [ –term termprog ] [ –version + ] [ –virtuals num ] [ exit | restart ]
+ +
+

DESCRIPTION
+ +
+ + Rio is a window manager for X which attempts to emulate the window + management policies of Plan 9’s rio window manager. Rio is derived + from David Hogan’s 8½. +
+ + The –grey option makes the background stippled grey, the default + X11 background, instead of solid grey, the Plan 9 background. + +
+ + The –font option sets the font in rio’s menu to fname, overriding + the default. Unlike the other programs in the Plan 9 ports, rio + expects this font to be an X11 font rather than a Plan 9 font. + +
+ + The –term option specifies an alternative program to run when the + New menu item is selected. The default is to try 9term(1) and + then to fall back to xterm(1). The –s option causes rio to add + −s to 9term’s command-line, starting the window in scrolling mode. + +
+ + The –version option prints the current version on standard error, + then exits. +
+ + The –virtuals option sets the number of virtual screens (the default + is 1, and the maximum is 12). +
+ + If the argument exit or restart is given, it is sent to an already-running + rio, causing the extant rio to exit or restart.
+

Using rio
+ +
+ + One window is current, and is indicated with a dark border and + text; characters typed on the keyboard are available in the /dev/cons + file of the process in the current window. Characters written + on /dev/cons appear asynchronously in the associated window whether + or not the window is current. +
+ + 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 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:
+ 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. The new + +
+ + +
+ + window is created running termprog, by default 9term(1) or, if + 9term is not available, xterm(1).
+ +
+ +
+ 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 New operation. The window is made current.
+ 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.
+ Delete   Delete a window. Click in the window to be deleted (gunsight + cursor). Deleting a window causes a hangup note to be sent to + all processes in the window’s process group (see notify(3)).
+ 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 its current window + system label.
+ label     Restore a hidden window. +
+ + 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. +
+ + When the mouse cursor points to the background area and rio has + been started with multiple virtual screens using the –virtuals + option, clicking button 2 brings up a menu to select a virtual + screen to view. Scrolling the mouse wheel while the cursor points + at the background will cycle through the virtual screens. + +

+

BUGS
+ +
+ + In Plan 9’s rio, clicking button 2 or button 3 to select a window + also sends that event to the window itself. This rio does not. + +
+ + The command-line syntax is non-standard. +
+ + In Plan 9’s rio, newly started applications take over the current + window. This rio starts a new window for each program. (In X11, + it appears to be impossible to know which window starts a particular + program.) +
+ + There is a currently a compiled-in limit of 128 hidden windows.
+ +
+

SEE ALSO
+ +
+ + 9term(1), xterm(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/rm.html b/man/man1/rm.html new file mode 100644 index 00000000..a19b3d3c --- /dev/null +++ b/man/man1/rm.html @@ -0,0 +1,66 @@ + +rm(1) - Plan 9 from User Space + + + + +
+
+
RM(1)RM(1) +
+
+

NAME
+ +
+ + rm – remove files
+ +
+

SYNOPSIS
+ +
+ + rm [ −fr ] file ...
+ +
+

DESCRIPTION
+ +
+ + 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
+ −f    Don’t report files that can’t be removed.
+ −r    Recursively delete the entire contents of a directory and the + directory itself.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/rm.c
+ +
+

SEE ALSO
+ +
+ + remove(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/sam.html b/man/man1/sam.html new file mode 100644 index 00000000..c27afa63 --- /dev/null +++ b/man/man1/sam.html @@ -0,0 +1,577 @@ + +sam(1) - Plan 9 from User Space + + + + +
+
+
SAM(1)SAM(1) +
+
+

NAME
+ +
+ + sam, B, E, sam.save, samterm, samsave – screen editor with structural + regular expressions
+ +
+

SYNOPSIS
+ +
+ + sam [ option ... ] [ files ] +
+ + sam −r machine +
+ + sam.save +
+ + B file[:line] ... +
+ + E file
+ +
+

DESCRIPTION
+ +
+ + Sam is a multi-file editor. It modifies a local copy of an external + file. The copy is here called a file. The files are listed in + a menu available through mouse button 3 or the 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--that to which editing commands apply--whereupon + its menu entry is printed. The options are
+ −d          Do not ‘download’ the terminal part of sam. Editing will be + done with the command language only, as in ed(1).
+ −r machine    Run the host part remotely on the specified machine, + the terminal part locally.
+ −s path      Start the host part from the specified file on the remote + host. Only meaningful with the −r option.
+ −t path      Start the terminal part from the specified file. Useful + for debugging.
+

Regular expressions
+ Regular expressions are as in regexp(7) with the addition of \n + 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 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.
+

Addresses
+ An address identifies a substring in a file. In the following, + ‘character n’ means the null string after the n-th character in + the file, with 1 the first character in the file. ‘Line n’ means + the n-th match, starting at the beginning of the file, of the + regular expression .*\n?. All files always have a current substring, + called + dot, that is the default address.
+

Simple Addresses
+ #n    The empty string after character n; #0 is the beginning of the + file.
+ n     Line n; 0 is the beginning of the file.
+ /regexp/
+ ?regexp?
+ +
+ + The substring that matches the regular expression, found by looking + toward the end (/) or beginning (?) 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.
+ +
+ 0     The string before the first full line. This is not necessarily + the null string; see + and − below.
+ $     The null string at the end of the file.
+ .     Dot.
+ '     The mark in the file (see the k command below).
+ "regexp"
+ +
+ + Preceding a simple address (default .), refers to the address + evaluated in the unique file whose menu line matches the regular + expression.
+ +
+

Compound Addresses
+ In the following, a1 and a2 are addresses.
+ a1+a2   The address a2 evaluated starting at the end of a1.
+ a1−a2   The address a2 evaluated looking in the reverse direction + starting at the beginning of a1.
+ a1,a2   The substring from the beginning of a1 to the end of a2. + If a1 is missing, 0 is substituted. If a2 is missing, $ is substituted.
+ a1;a2   Like a1,a2, but with a2 evaluated at the end of, and dot + set to, a1. +
+ + The operators + and − are high precedence, while , and ; are low + precedence. +
+ + In both + and − forms, if a2 is a line or character address with + a missing number, the number defaults to 1. If a1 is missing, + . is substituted. If both a1 and a2 are present and distinguishable, + + may be elided. a2 may be a regular expression; if it is delimited + by ?’s, the effect of the + or − is reversed. +
+ + It is an error for a compound address to represent a malformed + substring. Some useful idioms: a1+− (a1-+) selects the line containing + the end (beginning) of a1. 0/regexp/ locates the first match of + the expression in the file. (The form 0;// sets dot unnecessarily.) + ./regexp/// finds the second following + occurrence of the expression, and .,/regexp/ extends dot.
+

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; \n may be typed for newline; and \/ quotes the delimiter, + here /. Backslash is otherwise interpreted literally, except in + s commands. +
+ + Most commands may be prefixed by an address to indicate their + range of operation. Those that may not are marked with a * below. + If a command takes an address and none is supplied, dot is used. + The sole exception is the w command, which defaults to 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 s and e commands).
+

Text commands
+ a/text/
+ or
+ a
+ lines of text
+ .     Insert the text into the file after the range. Set dot.
+ c
+ i     Same as a, but c replaces the text, while i inserts before the + range.
+ d     Delete the text in the range. Set dot.
+ s/regexp/text/
+ +
+ + Substitute text for the first match to the regular expression + in the range. Set dot to the modified range. In text the character + & stands for the string that matched the expression. Backslash + behaves as usual unless followed by a digit: \d stands for the + string that matched the subexpression begun by the d-th left + parenthesis. If s is followed immediately by a number n, as in + s2/x/y/, the n-th match in the range is substituted. If the command + is followed by a g, as in s/x/y/g, all matches in the range are + substituted.
+ +
+ m a1
+ t a1   Move (m) or copy (t) the range to after a1. Set dot.
+

Display commands
+ p     Print the text in the range. Set dot.
+ =     Print the line address and character address of the range.
+ =#    Print just the character address of the range.
+

File commands
+ * b file-list
+ +
+ + Set the current file to the first file named in the list that + sam also has in its menu. The list may be expressed <Plan 9 command + in which case the file names are taken as words (in the shell + sense) generated by the Plan 9 command.
+ +
+ * B file-list
+ +
+ + Same as b, except that file names not in the menu are entered + there, and all file names in the list are examined.
+ +
+ * n    Print a menu of files. The format is:
+ +
+ + ' or blankindicating the file is modified or clean,
+ − or +    indicating the file is unread or has been read (in the terminal, + * means more than one window is open),
+ . or blankindicating the current file,
+ a blank,
+ and the file name.
+ +
+ * D file-list
+ +
+ + Delete the named files from the menu. If no files are named, the + current file is deleted. It is an error to D a modified file, + but a subsequent D will delete such a file.
+ +
+

I/O Commands
+ * e filename
+ +
+ + Replace the file by the contents of the named external file. Set + dot to the beginning of the file.
+ +
+ r filename
+ +
+ + Replace the text in the range by the contents of the named external + file. Set dot.
+ +
+ w filename
+ +
+ + Write the range (default 0,$) to the named external file.
+ +
+ * f filename
+ +
+ + Set the file name and print the resulting menu entry. +
+ + +
+ If the file name is absent from any of these, the current file + name is used. e always sets the file name; r and w do so if the + file has no name.
+ < Plan 9-command
+ +
+ + Replace the range by the standard output of the Plan 9 command.
+ +
+ > Plan 9-command
+ +
+ + Send the range to the standard input of the Plan 9 command.
+ +
+ | Plan 9-command
+ +
+ + Send the range to the standard input, and replace it by the standard + output, of the Plan 9 command.
+ +
+ * ! Plan 9-command
+ +
+ + Run the Plan 9 command.
+ +
+ * cd directory
+ +
+ + Change working directory. If no directory is specified, $home + is used. +
+ + +
+ In any of <, >, | or !, if the Plan 9 command is omitted the last + Plan 9 command (of any type) is substituted. If sam is downloaded + (using the mouse and raster display, i.e. not using option −d), + ! sets standard input to /dev/null, and otherwise unassigned output + (stdout for ! and >, stderr for all) is placed in + /tmp/sam.err and the first few lines are printed.
+

Loops and Conditionals
+ 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, /.*\n/ + is assumed. Null string matches potentially occur before every + character of the range and at the end of the range. + +
+ y/regexp/ command
+ +
+ + Like x, but run the command for each substring that lies before, + between, or after the matches that would be generated by x. There + is no default regular expression. Null substrings potentially + occur before every character in the range.
+ +
+ * X/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.
+ +
+ * Y/regexp/ command
+ +
+ + Same as X, but for files that do not match the regular expression, + and the expression is required.
+ +
+ g/regexp/ command
+ v/regexp/ command
+ +
+ + If the range contains (g) or does not contain (v) a match for + the expression, set dot to the range and run the command. +
+ + +
+ These may be nested arbitrarily deeply, but only one instance + of either X or Y may appear in a single command. An empty command + in an x or y defaults to p; an empty command in X or Y defaults + to f. g and v do not have defaults.
+

Miscellany
+ k         Set the current file’s mark to the range. Does not set dot.
+ * q        Quit. It is an error to quit with modified files, but a second + q will succeed.
+ * u n      Undo the last 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 u’s move further back in time. The only commands for + which u is ineffective are cd, u, q, w and + +
+ + +
+ + D. If n is negative, u ‘redoes,’ undoing the undo, going forwards + in time again.
+ +
+ +
+ (empty)    If the range is explicit, set dot to the range. If 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 .+1 and + +
+ + +
+ + printed.
+ +
+ +
+

Grouping and multiple changes
+ Commands may be grouped by enclosing them in braces {}. 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. +
+ + When a command makes a number of changes to a file, as in 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.
+

The terminal
+ What follows refers to behavior of sam when downloaded, that is, + when operating as a display editor on a raster display. This is + the default behavior; invoking sam with the −d (no download) option + provides access to the command language only. +
+ + 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 rio(1); also the escape key (ESC) selects (sets dot to) + text typed since the last mouse button hit. +
+ + The button 3 menu controls window operations. The top of the menu + provides the following operators, each of which uses one or more + 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.
+ new      Create a new, empty file.
+ zerox    Create a copy of an existing window.
+ resize   As in rio.
+ close    Delete the window. In the last window of a file, close is + equivalent to a D for the file.
+ write    Equivalent to a w for the file. +
+ + Below these operators is a list of available files, starting with + ~~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 ~~sam~~ are marked with + one of the characters −+* according as zero, one, or more windows + are open on the file. A further mark . appears on the file in + the current window and a single quote, ', on a file modified since + last write. +
+ + The command window, created automatically when 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 + 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--the file in the most recently current + window.
+

Manipulating text
+ Button 1 changes selection, much like 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. +
+ + Button 2 provides a menu of editing commands:
+ cut       Delete dot and save the deleted text in the snarf buffer.
+ paste     Replace the text in dot by the contents of the snarf buffer.
+ snarf     Save the text in dot in the snarf buffer.
+ 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 click attribute defining where + the selection lies (see plumb(7)).
+ 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.
+ <rio>     Exchange snarf buffers with rio.
+ /regexp    Search forward for the next match of the last regular expression + typed in a command. (Not in command window.)
+ 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.)
+

External communication
+ Sam listens to the edit plumb port. If plumbing is not active, + on invocation sam creates a named pipe /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. +
+ + B is a shell-level command that causes an instance of sam running + on the same terminal to load the named files. 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). + +
+ + E is a shell-level command that can be used as $EDITOR in a Unix + environment. It runs B on file and then does not exit until file + is changed, which is taken as a signal that file is done being + edited.
+

Abnormal termination
+ If sam terminates other than by a q command (by hangup, deleting + its window, etc.), modified files are saved in an executable file, + $HOME/sam.save. This program, when executed, asks whether to write + each file back to a external file. The answer y causes writing; + anything else skips the file. + +

+

FILES
+ +
+ + $HOME/sam.save
+ $HOME/sam.err
+ /usr/local/plan9/bin/samsave
+ +
+ + +
+ + the program called to unpack $HOME/sam.save.
+ +
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/sam       source for sam itself
+ /usr/local/plan9/src/cmd/samterm   source for the separate terminal + part
+ /usr/local/plan9/bin/B
+ /usr/local/plan9/bin/E
+ +
+

SEE ALSO
+ +
+ + ed(1), sed(1), grep(1), rio(1), regexp(7). +
+ + Rob Pike, “The text editor sam”.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/scat.html b/man/man1/scat.html new file mode 100644 index 00000000..d5cf2007 --- /dev/null +++ b/man/man1/scat.html @@ -0,0 +1,385 @@ + +scat(1) - Plan 9 from User Space + + + + +
+
+
SCAT(1)SCAT(1) +
+
+

NAME
+ +
+ + scat – sky catalogue and Digitized Sky Survey
+ +
+

SYNOPSIS
+ +
+ + scat
+ +
+

DESCRIPTION
+ +
+ + 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 astro(1) 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. +
+ + 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, scat prints how many objects are in the set; + otherwise it prints the objects’ descriptions or cross-index listings + (suitable for input to scat). An item is in one of the following + formats:
+ ngc1234
+ +
+ + Number 1234 in the New General Catalogue of Nonstellar Objects, + NGC2000.0. The output identifies the type (Gx=galaxy, Pl=planetary + nebula, OC=open cluster, Gb=globular cluster, Nb=bright nebula, + C+N=cluster associated with nebulosity, Ast=asterism, Kt=knot + or nebulous region in a galaxy, + ***=triple star, D*=double star, ?=uncertain, −=nonexistent, 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.
+ +
+ ic1234
+ +
+ + Like NGC references, but from the Index Catalog.
+ +
+ 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.
+ +
+ m4    Catalog number 4 in Messier’s catalog. The output is the NGC + number.
+ 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.
+ +
+ 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.
+ +
+ "α umi"
+ +
+ + 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. 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.
+ +
+ 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.
+ +
+ umi   All the patches in the named constellation.
+ marsThe planets are identified by their names. The names shadow + and comet refer to the earth’s penumbra at lunar distance and + the comet installed in the current astro(1). The output is the + planet’s name, right ascension and declination, azimuth and altitude, + and phase for the moon and sun, as shown by + +
+ + astro. The positions are current at the start of scat’s execution; + see the astro command in the next section for more information. + +
+ + +
+ The commands are:
+ add itemAdd the named item to the set.
+ keep class ...
+ +
+ + +
+ + Flatten the set and cull it, keeping only the specified classes. + The classes may be specific NGC types, all stars (sao), all NGC + objects (ngc), all M objects (m), all Abell clusters (abell), + or a specified brightness range. Brightness ranges are specified + by a leading > or < followed by a magnitude. Remember + that brighter objects have lesser magnitudes.
+ +
+ +
+ drop class ...
+ +
+ + +
+ + Complement to keep.
+ +
+ +
+ flat    Some items such as patches represents sets of items. Flat + flattens the set so scat holds all the information available for + the objects in the set.
+ print   Print the contents of the set. If the information seems meager, + try flattening the set.
+ expand n
+ +
+ + +
+ + Flatten the set, expand the area of the sky covered by the set + to be n degrees wider, and collect all the objects in that area. + If n is zero, expand collects all objects in the patches that + cover the current set.
+ +
+ +
+ astro option
+ +
+ + +
+ + Run astro(1) with the specified options (to which will be appended + −p), to discover the positions of the planets. Astro’s −d and + −l options can be used to set the time and place; by default, + it’s right now at the coordinates in /lib/sky/here. Running astro + does not change the positions of planets + already in the display set, so astro may be run multiple times, + executing e.g. add mars each time, to plot a series of planetary + positions.
+ +
+ +
+ 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, scat does not have the information necessary to show + the correct orientation for galaxies. + The option nogrid suppresses the lines of declination and right + ascension. By default, scat labels NGC objects, Abell clusters, + and bright stars; option nolabel suppresses these while alllabel + labels stars with their SAO number as well. The default size is + 512x512; options dx n and dy n set the x and + y extent. The option zenithup orients the map so it appears as + it would in the sky at the time and location used by the astro + command (q.v.).
+ The output is designed to look best on an LCD display. CRTs have + trouble with the thin, grey lines and dim stars. The option nogrey + uses white instead of grey for these details, improving visibility + at the cost of legibility when plotting on CRTs.
+ +
+ +
+ plate [[ra dec] rasize [decsize]]
+ +
+ + +
+ + 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 500x500 + pixel block from the survey containing the center of + the object is displayed. The survey is stored in the CD-ROM juke + box; run 9fs juke before running scat.
+ +
+ +
+ 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. Scat does not change + the hardware color map, which should be set externally to a grey + scale; try the command getmap gamma (see + getmap(9.1)) on an 8-bit color-mapped display.
+ +
+ +
+ +
+

EXAMPLES
+ +
+ + Plot the Messier objects and naked-eye stars in Orion.
+ +
+ + ori
+ keep m <6
+ plot nogrid
+ +
+ + +
+ Draw a finder chart for Uranus:
+ +
+ + uranus
+ expand 5
+ plot
+ +
+ + +
+ Show a partial lunar eclipse:
+ +
+ + astro −d
+ 2000 07 16 12 45
+ moon
+ add shadow
+ expand 2
+ plot
+ +
+ + +
+ Draw a map of the Pleiades.
+ +
+ + "alcyone"
+ expand 1
+ plot
+ +
+ +
+

FILES
+ +
+ + /usr/local/plan9/sky/*.scat
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/scat
+ +
+

SEE ALSO
+ +
+ + astro(1)
+ /usr/local/plan9/sky/constelnames the three-letter abbreviations + of the constellation names. +
+ + 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. + +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/secstore.html b/man/man1/secstore.html new file mode 100644 index 00000000..1b9a3a89 --- /dev/null +++ b/man/man1/secstore.html @@ -0,0 +1,145 @@ + +secstore(1) - Plan 9 from User Space + + + + +
+
+
SECSTORE(1)SECSTORE(1) +
+
+

NAME
+ +
+ + aescbc, secstore, ipso – secstore commands
+ +
+

SYNOPSIS
+ +
+ + secstore [ −s server ] [ −(g|G) getfile ] [ −p putfile ] [ −r + rmfile ] [ −c ] [ −u user ] [ −v ] [ −i ] +
+ + aescbc -e <cleartext >ciphertext
+ aescbc -d <ciphertext >cleartext +
+ + ipso [ −a −e −l −f −s ] [ file ... ] +
+ + +
+

DESCRIPTION
+ +
+ + +
+ + Secstore authenticates to the server using a password and optionally + a hardware token, then saves or retrieves a file. This is intended + to be a credentials store (public/private keypairs, passwords, + and other secrets) for a factotum. +
+ + Option −p stores a file on the secstore. +
+ + Option −g retrieves a file to the local directory; option −G writes + it to standard output instead. Specifying getfile of . will send + to standard output a list of remote files with dates, lengths + and SHA1 hashes. +
+ + Option −r removes a file from the secstore. +
+ + Option −c prompts for a password change. +
+ + Option −v produces more verbose output, in particular providing + a few bits of feedback to help the user detect mistyping. +
+ + Option −i says that the password should be read from standard + input instead of from /dev/cons. +
+ + Option −n says that the password should be read from NVRAM instead + of from /dev/cons. This option is unsupported. +
+ + The server is tcp!$auth!5356, or the server specified by option + −s. +
+ + For example, to add a secret to the file read by factotum(4) at + startup, open a new window, type
+ +
+ + % 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
+ +
+ + +
+ 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. +
+ + Aescbc encrypts and decrypts using AES (Rijndael) in cipher block + chaining (CBC) mode.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/secstore
+ +
+

SEE ALSO
+ +
+ + factotum(4), Plan 9’s secstore(8)
+ +
+

BUGS
+ +
+ + There is deliberately no backup of files on the secstore, so −r + (or a disk crash) is irrevocable. You are advised to store important + secrets in a second location.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/sed.html b/man/man1/sed.html new file mode 100644 index 00000000..c40874ad --- /dev/null +++ b/man/man1/sed.html @@ -0,0 +1,300 @@ + +sed(1) - Plan 9 from User Space + + + + +
+
+
SED(1)SED(1) +
+
+

NAME
+ +
+ + sed – stream editor
+ +
+

SYNOPSIS
+ +
+ + sed [ −n ] [ −g ] [ −e script ] [ −f sfile ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Sed copies the named files (standard input default) to the standard + output, edited according to a script of commands. The −f option + causes the script to be taken from file sfile; these options accumulate. + If there is just one −e option and no −f’s, the flag −e may be + omitted. The −n option suppresses the default + output; −g causes all substitutions to be global, as if suffixed + g. +
+ + A script consists of editing commands, one per line, of the following + form:
+ +
+ + [address [, address] ] function [argument ...] +
+ + +
+ In normal operation sed cyclically copies a line of input into + a pattern space (unless there is something left after a D command), + applies in sequence all commands whose addresses select that pattern + space, and at the end of the script copies the pattern space to + the standard output (except under −n) and deletes the + pattern space. +
+ + An address is either a decimal number that counts input lines + cumulatively across files, a $ that addresses the last line of + input, or a context address, /regular-expression/, in the style + of regexp(7), with the added convention that \n matches a newline + embedded in the pattern space. +
+ + A command line with no addresses selects every pattern space. + +
+ + A command line with one address selects each pattern space that + matches the address. +
+ + 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. +
+ + Editing commands can be applied to non-selected pattern spaces + by use of the negation function ! (below). +
+ + An argument denoted text consists of one or more lines, all but + the last of which end with \ to hide the newline. Backslashes + in text are treated like backslashes in the replacement string + of an s command, and may be used to protect initial blanks and + tabs against the stripping that is done on every script line. + +
+ + An argument denoted rfile or wfile must terminate the command + line and must be preceded by exactly one blank. Each wfile is + created before processing begins. There can be at most 120 distinct + wfile arguments.
+ a\
+ text        Append. Place text on the output before reading the next input + line.
+ b label      Branch to the : command bearing the label. If label is + empty, branch to the end of the script.
+ c\
+ text        Change. Delete the pattern space. With 0 or 1 address or at + the end of a 2-address range, place text on the output. Start + the next cycle.
+ d          Delete the pattern space. Start the next cycle.
+ D          Delete the initial segment of the pattern space through the first + newline. Start the next cycle.
+ g          Replace the contents of the pattern space by the contents of + the hold space.
+ G          Append the contents of the hold space to the pattern space.
+ h          Replace the contents of the hold space by the contents of the + pattern space.
+ H          Append the contents of the pattern space to the hold space.
+ i\
+ text        Insert. Place text on the standard output.
+ n          Copy the pattern space to the standard output. Replace the pattern + space with the next line of input.
+ N          Append the next line of input to the pattern space with an embedded + newline. (The current line number changes.)
+ p          Print. Copy the pattern space to the standard output.
+ P          Copy the initial segment of the pattern space through the first + newline to the standard output.
+ q          Quit. Branch to the end of the script. Do not start a new cycle.
+ r rfile       Read the contents of rfile. Place them on the output before + reading the next input line.
+ s/regular-expression/replacement/flags
+ +
+ + +
+ + Substitute the replacement string for instances of the regular-expression + in the pattern space. Any character may be used instead of /. + For a fuller description see regexp(7). Flags is zero or more + of
+ g     Global. Substitute for all non-overlapping instances of the regular + expression rather than just the first one.
+ p     Print the pattern space if a replacement was made.
+ w wfile
+ Write. Append the pattern space to wfile if a replacement was + made.
+ +
+ +
+ t label      Test. Branch to the : command bearing the label if any + substitutions have been made since the most recent reading of + an input line or execution of a t. If label is empty, branch to + the end of the script.
+ w          wfile
+ +
+ + +
+ + Write. Append the pattern space to wfile.
+ +
+ +
+ x          Exchange the contents of the pattern and hold spaces.
+ y/string1/string2/
+ +
+ + +
+ + Transform. Replace all occurrences of characters in string1 with + the corresponding character in string2. The lengths of string1 + and string2 must be equal.
+ +
+ +
+ !function     Don’t. Apply the function (or group, if function is {) + only to lines not selected by the address(es).
+ : label      This command does nothing; it bears a label for b and t + commands to branch to.
+ =          Place the current line number on the standard output as a line.
+ {          Execute the following commands through a matching } only when + the pattern space is selected.
+ +
+ + +
+ + An empty command is ignored.
+ +
+ +
+ +
+

EXAMPLES
+ +
+ + sed 10q file
+ +
+ + Print the first 10 lines of the file.
+ +
+ sed '/^$/d'
+ +
+ + Delete empty lines from standard input.
+ +
+ sed 's/UNIX/& system/g'
+ +
+ + Replace every instance of UNIX by UNIX system. +
+ + +
+ sed 's/ *$//     drop trailing blanks
+ /^$/d                drop empty lines
+ s/    */\          replace blanks by newlines
+ /g
+ /^$/d' chapter*
+ +
+ + Print the files chapter1, chapter2, etc. one word to a line. +
+ + +
+ nroff −ms manuscript | sed '
+ ${
+ +
+ + /^$/p +
+ +
+ +           if last line of file is empty, print it
+ +
+ }
+ //N             if current line is empty, append next line
+ /^\n$/D'         if two lines are empty, delete the first
+ +
+ + Delete all but one of each group of empty lines from a formatted + manuscript.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/sed.c
+ +
+

SEE ALSO
+ +
+ + ed(1), grep(1), awk(1), lex(1), sam(1), regexp(7)
+ L. E. McMahon, ‘SED -- A Non-interactive Text Editor’, Unix Research + System Programmer’s Manual, Volume 2.
+ +
+

BUGS
+ +
+ + If input is from a pipe, buffering may consume characters beyond + a line on which a q command is executed.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/seq.html b/man/man1/seq.html new file mode 100644 index 00000000..c04a08e5 --- /dev/null +++ b/man/man1/seq.html @@ -0,0 +1,99 @@ + +seq(1) - Plan 9 from User Space + + + + +
+
+
SEQ(1)SEQ(1) +
+
+

NAME
+ +
+ + seq – print sequences of numbers
+ +
+

SYNOPSIS
+ +
+ + seq [ −w ] [ −fformat ] [ first [ incr ] ] last
+ +
+

DESCRIPTION
+ +
+ + Seq prints a sequence of numbers, one per line, from first (default + 1) to as near last as possible, in increments of incr (default + 1). The loop is:
+ +
+ + for(val = min; val <= max; val += incr) print val;
+ +
+ The numbers are interpreted as floating point. +
+ + Normally integer values are printed as decimal integers. The options + are
+ −fformat    Use the print(3)-style format print for printing each + (floating point) number. The default is %g.
+ −w        Equalize the widths of all numbers by padding with leading zeros + as necessary. Not effective with option −f, nor with numbers in + exponential notation.
+ +
+

EXAMPLES
+ +
+ + seq 0 .05 .1
+ +
+ + Print 0 0.05 0.1 (on separate lines).
+ +
+ seq −w 0 .05 .1
+ +
+ + Print 0.00 0.05 0.10.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/seq.c
+ +
+

BUGS
+ +
+ + Option −w always surveys every value in advance. Thus seq −w 1000000000 + is a painful way to get an ‘infinite’ sequence.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/sleep.html b/man/man1/sleep.html new file mode 100644 index 00000000..622bca9a --- /dev/null +++ b/man/man1/sleep.html @@ -0,0 +1,91 @@ + +sleep(1) - Plan 9 from User Space + + + + +
+
+
SLEEP(1)SLEEP(1) +
+
+

NAME
+ +
+ + sleep – suspend execution for an interval
+ +
+

SYNOPSIS
+ +
+ + sleep time
+ +
+

DESCRIPTION
+ +
+ + Sleep suspends execution for time seconds.
+ +
+

EXAMPLES
+ +
+ + Execute a command 100 seconds hence.
+ +
+ + {sleep 100; command}&
+ +
+ + +
+ Repeat a command every 30 seconds.
+ +
+ + while (){
+ +
+ + command
+ sleep 30
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/sleep.c
+ +
+

SEE ALSO
+ +
+ + sleep(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/sort.html b/man/man1/sort.html new file mode 100644 index 00000000..2f6de1b7 --- /dev/null +++ b/man/man1/sort.html @@ -0,0 +1,200 @@ + +sort(1) - Plan 9 from User Space + + + + +
+
+
SORT(1)SORT(1) +
+
+

NAME
+ +
+ + sort – sort and/or merge files
+ +
+

SYNOPSIS
+ +
+ + sort [ −cmuMbdfinrwtx ] [ +pos1 [ −pos2 ] ... ] ... [ −k pos1 + [ ,pos2 ] ] ...
+ +
+ + +
+ + ’ [ −o output ] [ −T dir ... ] [ option ... ] [ file ... ]
+ +
+ +
+ +
+

DESCRIPTION
+ +
+ + Sort sorts lines of all the files together and writes the result + on the standard output. If no input files are named, the standard + input is sorted. +
+ + 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.
+ −M    Compare as months. The first three non-white space characters + of the field are folded to upper case and compared so that JAN + precedes FEB, etc. Invalid fields compare low to JAN.
+ −b    Ignore leading white space (spaces and tabs) in field comparisons.
+ −d    ‘Phone directory’ order: only letters, accented letters, digits + and white space are significant in comparisons.
+ −f    Fold lower case letters onto upper case. Accented characters + are folded to their non-accented upper case form.
+ −i    Ignore characters outside the ASCII range 040-0176 in non-numeric + comparisons.
+ −w    Like −i, but ignore only tabs and spaces.
+ −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.
+ −g    Numbers, like −n but with optional e-style exponents, are sorted + by value.
+ −r    Reverse the sense of comparisons.
+ −tx   ‘Tab character’ separating fields is x. +
+ + The notation +pos1 −pos2 restricts a sort key to a field beginning + at pos1 and ending just before pos2. Pos1 and pos2 each have the + form m.n, optionally followed by one or more of the flags Mbdfginr, + where m tells a number of fields to skip from the beginning of + the line and 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 .n means .0; a missing + −pos2 means the end of the line. Under the −tx option, fields + are strings separated by x; otherwise fields are non-empty strings + separated by white space. White space before a field is part of + the field, except under option −b. A b flag may be attached independently + to pos1 and pos2. +
+ + The notation −k pos1[,pos2] is how POSIX sort defines fields: + pos1 and pos2 have the same format but different meanings. The + value of m is origin 1 instead of origin 0 and a missing .n in + pos2 is the end of the field. +
+ + 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. +
+ + These option arguments are also understood:
+ −c       Check that the single input file is sorted according to the + ordering rules; give no output unless the file is out of sort.
+ −m       Merge; assume the input files are already sorted.
+ −u       Suppress all but one in each set of equal lines. Ignored bytes + and bytes outside keys do not participate in this comparison.
+ −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.
+ −Tdir     Put temporary files in dir rather than in /var/tmp.
+ +
+

EXAMPLES
+ +
+ + sort −u +0f +0 list
+ +
+ + Print in alphabetical order all the unique spellings in a list + of words where capitalized words differ from uncapitalized.
+ +
+ sort −t: +1 /adm/users
+ +
+ + Print the users file sorted by user name (the second colon-separated + field).
+ +
+ sort −umM dates
+ +
+ + Print the first instance of each month in an already sorted file. + Options −um with just one input file make the choice of a unique + representative from a set of equal lines predictable.
+ +
+ 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.
+ +
+ +
+

FILES
+ +
+ + /var/tmp/sort.<pid>.<ordinal>
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/sort.c
+ +
+

SEE ALSO
+ +
+ + uniq(1), look(1)
+ +
+

DIAGNOSTICS
+ +
+ + Sort comments and exits with non-null status for various trouble + conditions and for disorder discovered under option −c.
+ +
+

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. +
+ + Some of the options, e.g. −i and −M, are hopelessly provincial.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/spell.html b/man/man1/spell.html new file mode 100644 index 00000000..9f412d2c --- /dev/null +++ b/man/man1/spell.html @@ -0,0 +1,125 @@ + +spell(1) - Plan 9 from User Space + + + + +
+
+
SPELL(1)SPELL(1) +
+
+

NAME
+ +
+ + spell, sprog – find spelling errors
+ +
+

SYNOPSIS
+ +
+ + spell [ options ] ... [ file ] ... +
+ + sprog [ options ] [ −f file ]
+ +
+

DESCRIPTION
+ +
+ + Spell looks up words from the named files (standard input default) + in a spelling list and places possible misspellings--words not sanctioned + there--on the standard output. +
+ + Spell ignores constructs of troff(1) and its standard preprocessors. + It understands these options:
+ −b    Check British spelling.
+ −v    Print all words not literally in the spelling list, with derivations.
+ −x    Print, marked with =, every stem as it is looked up in the spelling + list, along with its affix classes. +
+ + As a matter of policy, 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).
+ +
+

FILES
+ +
+ + /usr/local/plan9/lib/amspell
+ +
+ + American spelling list
+ +
+ /usr/local/plan9/lib/brspell
+ +
+ + British spelling list
+ +
+ /usr/local/plan9/bin/sprog
+ +
+ + The actual spelling checker. It expects one word per line on standard + input, and takes the same arguments as spell.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin/spell       the script
+ /usr/local/plan9/src/cmd/spell   source for sprog
+ +
+

SEE ALSO
+ +
+ + deroff(1)
+ +
+

BUGS
+ +
+ + The heuristics of deroff(1) used to excise formatting information + are imperfect. +
+ + 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.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/split.html b/man/man1/split.html new file mode 100644 index 00000000..ff3a3d38 --- /dev/null +++ b/man/man1/split.html @@ -0,0 +1,91 @@ + +split(1) - Plan 9 from User Space + + + + +
+
+
SPLIT(1)SPLIT(1) +
+
+

NAME
+ +
+ + split – split a file into pieces
+ +
+

SYNOPSIS
+ +
+ + split [ option ... ] [ file ]
+ +
+

DESCRIPTION
+ +
+ + Split reads file (standard input by default) and writes it in + pieces of 1000 lines per output file. The names of the output + files are xaa, xab, and so on to xzz. The options are
+ −n n   Split into n-line pieces.
+ −l n   Synonym for −n n, a nod to Unix’s syntax.
+ −e expression
+ +
+ + File divisions occur at each line that matches a regular expression; + see regexp(7). Multiple −e options may appear. If a subexpression + of expression is contained in parentheses (...), the output file + name is the portion of the line which matches the subexpression.
+ +
+ −f stem
+ +
+ + Use stem instead of x in output file names.
+ +
+ −s suffix
+ +
+ + Append suffix to names identified under −e.
+ +
+ −x    Exclude the matched input line from the output file.
+ −i    Ignore case in option −e; force output file names (excluding + the suffix) to lower case.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/split.c
+ +
+

SEE ALSO
+ +
+ + sed(1), awk(1), grep(1), regexp(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/src.html b/man/man1/src.html new file mode 100644 index 00000000..cd8334ec --- /dev/null +++ b/man/man1/src.html @@ -0,0 +1,99 @@ + +src(1) - Plan 9 from User Space + + + + +
+
+
SRC(1)SRC(1) +
+
+

NAME
+ +
+ + src – find source code for executable
+ +
+

SYNOPSIS
+ +
+ + src [ −n ] [ −s symbol ] file ...
+ +
+

DESCRIPTION
+ +
+ + Src examines the named files to find the corresponding source + code, which is then sent to the editor using B (see sam(1)). If + file is an rc(1) script, the source is the file itself. If file + is an executable, the source is defined to be the single file + containing the definition of main and src will point the editor + at the line that + begins the definition. Src uses db(1) to extract the symbol table + information that identifies the source. +
+ + Src looks for each file in the current directory, in /bin, and + in the subdirectories of /bin, in that order. +
+ + The −n flag causes src to print the file name but not send it + to the editor. The −s flag identifies a symbol other than main + to locate.
+ +
+

EXAMPLES
+ +
+ + Find the source to the main routine in /bin/ed:
+ +
+ + src ed
+ +
+ + +
+ Find the source for strcmp:
+ +
+ + src −s strcmp rc
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin/src
+ +
+

SEE ALSO
+ +
+ + db(1), plumb(1), sam(1).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/stats.html b/man/man1/stats.html new file mode 100644 index 00000000..77b598d5 --- /dev/null +++ b/man/man1/stats.html @@ -0,0 +1,214 @@ + +stats(1) - Plan 9 from User Space + + + + +
+
+
STATS(1)STATS(1) +
+
+

NAME
+ +
+ + stats, auxstats – display graphs of system activity
+ +
+

SYNOPSIS
+ +
+ + stats [ −option ] [ machine[:path] ... ] +
+ + auxstats [ machine [ path ] ]
+ +
+

DESCRIPTION
+ +
+ + 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 machine or multiple 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. +
+ + Auxstats collects the machine statistics for display by stats. + With no arguments, it collects statistics from the local machine. + If machine is named, it executes ssh machine path; when ssh finishes, + auxstats sleeps for one minute and runs it again. The default + path is simply auxstats, but since some shells do not + execute any sort of user profile when run as a non-login shell, + it is often necessary to specify an exact path. +
+ + The right mouse button presents a menu to enable and disable the + display of various statistics; by default, stats begins by showing + the load average on the executing machine. +
+ + The lower-case options choose the initial set to display:
+ b battery     percentage battery life remaining.
+ c context     number of process context switches per second.
+ e ether       total number of packets sent and received per second.
+ E etherin,out
+ +
+ + +
+ + number of packets sent and received per second, displayed as separate + graphs.
+ +
+ +
+ f fault       number of page faults per second.
+ i intr        number of interrupts per second.
+ 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. On most systems, it changes only every five seconds and + has limited accuracy.
+ m mem         total pages of active memory. The graph displays the fraction + of the machine’s total memory in use.
+ n etherin,out,err
+ +
+ + +
+ + number of packets sent and received per second, and total number + of errors, displayed as separate graphs.
+ +
+ +
+ s syscall     number of system calls per second.
+ 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. + +
+ + 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. +
+ + Upper-case options control details of the display. All graphs + are affected; there is no mechanism to affect only one graph.
+ −T sleepsecs
+ +
+ + Set the number of seconds between samples to sleepsecs (default + one second).
+ +
+ −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.
+ +
+ −L    Plot all graphs with logarithmic 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 y axis and the total range of the graph + is a factor of 1000; thus the y origin is 1/100 of the default + maximum value and the top of the graph is 10 times the + +
+ + default maximum.
+ +
+ −Y    If the display is large enough to show them, place value markers + along the 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. +
+ + +
+ Typing ‘q’ or DEL causes stats to exit.
+ +
+

EXAMPLE
+ +
+ + Show the load, memory, interrupts, system calls, context switches, + and ethernet packets for the local machine, a remote BSD machine + daemon, and a remote Linux machine tux. Auxstats is not in tux’s + path, so the full path must be given.
+ +
+ + stats −lmisce `hostname` daemon \
+ +
+ + tux:/usr/local/plan9/bin/auxstats
+ +
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/draw/stats.c +
+ + /usr/local/plan9/src/cmd/auxstats
+ +
+

BUGS
+ +
+ + The auxstats binary needs read access to /dev/kmem in order to + collect network statistics on non-Linux systems. Typically this + can be arranged by setting the auxstat binary’s group to kmem + and then turning on its set-gid bit.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/strings.html b/man/man1/strings.html new file mode 100644 index 00000000..3b1f4eff --- /dev/null +++ b/man/man1/strings.html @@ -0,0 +1,69 @@ + +strings(1) - Plan 9 from User Space + + + + +
+
+
STRINGS(1)STRINGS(1) +
+
+

NAME
+ +
+ + strings – extract printable strings
+ +
+

SYNOPSIS
+ +
+ + strings [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Strings finds and prints strings containing 6 or more consecutive + printable UTF-encoded characters in a (typically) binary file, + default standard input. Printable characters are taken to be 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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/strings.c
+ +
+

SEE ALSO
+ +
+ + nm(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/sum.html b/man/man1/sum.html new file mode 100644 index 00000000..2b86af65 --- /dev/null +++ b/man/man1/sum.html @@ -0,0 +1,92 @@ + +sum(1) - Plan 9 from User Space + + + + +
+
+
SUM(1)SUM(1) +
+
+

NAME
+ +
+ + sum, md5sum, sha1sum – sum and count blocks in a file
+ +
+

SYNOPSIS
+ +
+ + sum [ −5r ] [ file ... ] +
+ + md5sum [ file ... ] +
+ + sha1sum [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + By default, sum calculates and prints a 32-bit hexadecimal checksum, + a byte count, and the name of each file. The checksum is also + a function of the input length. If no files are given, the standard + input is summed. Other summing algorithms are available. The options + are
+ −r    Sum with the algorithm of System V’s sum −r and print the length + (in 1K blocks) of the input.
+ −5    Sum with System V’s default algorithm and print the length (in + 512-byte blocks) of the input. +
+ + 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. + +
+ + Md5sum computes the 32 hex digit RSA Data Security, Inc. MD5 Message-Digest + Algorithm described in RFC1321. If no files are given, the standard + input is summed. +
+ + Sha1sum computes the 40 hex digit National Institute of Standards + and Technology SHA1 secure hash algorithm described in FIPS PUB + 180-1. If no files are given, the standard input is summed.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/sum.c
+ /usr/local/plan9/src/cmd/md5sum.c
+ /usr/local/plan9/src/cmd/sha1sum.c
+ +
+

SEE ALSO
+ +
+ + cmp(1), wc(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/tail.html b/man/man1/tail.html new file mode 100644 index 00000000..781f3333 --- /dev/null +++ b/man/man1/tail.html @@ -0,0 +1,116 @@ + +tail(1) - Plan 9 from User Space + + + + +
+
+
TAIL(1)TAIL(1) +
+
+

NAME
+ +
+ + tail – deliver the last part of a file
+ +
+

SYNOPSIS
+ +
+ + tail [ +−number[lbc][rf] ] [ file ] +
+ + tail [ −fr ] [ −n nlines ] [ −c nbytes ] [ file ]
+ +
+

DESCRIPTION
+ +
+ + Tail copies the named file to the standard output beginning at + a designated place. If no file is named, the standard input is + copied. +
+ + Copying begins at position +number measured from the beginning, + or −number from the end of the input. Number is counted in lines, + 1K blocks or bytes, according to the appended flag l, b, or c. + Default is −10l (ten ell). +
+ + The further flag r causes tail to print lines from the end of + the file in reverse order; f (follow) causes tail, after printing + to the end, to keep watch and print further data as it appears. + +
+ + The second syntax is that promulgated by POSIX, where the numbers + rather than the options are signed.
+ +
+

EXAMPLES
+ +
+ + tail file
+ +
+ + Print the last 10 lines of a file.
+ +
+ tail +0f file
+ +
+ + Print a file, and continue to watch data accumulate as it grows.
+ +
+ sed 10q file
+ +
+ + Print the first 10 lines of a file.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/tail.c
+ +
+

BUGS
+ +
+ + Tails relative to the end of the file are treasured up in a buffer, + and thus are limited in length. +
+ + According to custom, option +number counts lines from 1, and counts + blocks and bytes from 0. +
+ + Tail is ignorant of UTF.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/tbl.html b/man/man1/tbl.html new file mode 100644 index 00000000..a50e8939 --- /dev/null +++ b/man/man1/tbl.html @@ -0,0 +1,187 @@ + +tbl(1) - Plan 9 from User Space + + + + +
+
+
TBL(1)TBL(1) +
+
+

NAME
+ +
+ + tbl – format tables for nroff or troff
+ +
+

SYNOPSIS
+ +
+ + tbl [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Tbl is a preprocessor for formatting tables for nroff or troff(1). + The input files are copied to the standard output, except for + segments of the form
+ +
+ + .TS
+ options ;
+ format .
+ data
+ .T&
+ format .
+ data
+ . . .
+ .TE
+ +
+ + +
+ which describe tables and are replaced by troff requests to lay + out the tables. If no arguments are given, tbl reads the standard + input. +
+ + The (optional) options line is terminated by a semicolon and contains + one or more of
+ +
+ + center        center the table; default is left-adjust
+ expand        make table as wide as current line length
+ box
+ doublebox     enclose the table in a box or double box
+ allbox        enclose every item in a box
+ tab(x)        use x to separate input items; default is tab
+ linesize(n)   set rules in n-point type
+ delim(xy)     recognize x and y as eqn(1) delimiters
+ +
+ + +
+ Each line, except the last, of the obligatory format describes + one row of the table. The last line describes all rows until the + next .T&, where the format changes, or the end of the table at + .TE. A format is specified by key letters, one per column, either + upper or lower case:
+ +
+ + L     Left justify: the default for columns without format keys.
+ R     Right justify.
+ C     Center.
+ N     Numeric: align at decimal point (inferred for integers) or at + \&.
+ S     Span: extend previous column across this one.
+ A     Alphabetic: left-aligned within column, widest item centered, + indented relative to L rows.
+ ^     Vertical span: continue item from previous row into this row.
+ −     Draw a horizontal rule in this column.
+ =     Draw a double horizontal rule in this column.
+ +
+ + +
+ Key letters may be followed by modifiers, also either case:
+ +
+ + |      Draw vertical rule between columns.
+ ||     Draw a double vertical rule between columns.
+ n      Gap between column is n ens wide. Default is 3.
+ Ffont   Use specified font. B and I mean FB and FI.
+ T      Begin vertically-spanned item at top row of range; default is + vertical centering (with ^).
+ Pn     Use point size n.
+ Vn     Use n-point vertical spacing in text block; signed n means relative + change.
+ W(n)   Column width as a troff width specification. Parens are optional + if n is a simple integer.
+ E      Equalize the widths of all columns marked E.
+ +
+ + +
+ Each line of data becomes one row of the table; tabs separate + items. Lines beginning with . are troff requests. Certain special + data items are recognized:
+ +
+ + _     Draw a horizontal rule in this column.
+ =     Draw a double horizontal rule in this column. A data line consisting + of a single _ or = draws the rule across the whole table.
+ \_    Draw a rule only as wide as the contents of the column.
+ \Rx   Repeat character x across the column.
+ \^    Span the previous item in this column down into this row.
+ T{    The item is a text block to be separately formatted by troff + and placed in the table. The block continues to the next line + beginning with T}. The remainder of the data line follows at that + point.
+ +
+ + +
+ When it is used in a pipeline with eqn, the tbl command should + be first, to minimize the volume of data passed through pipes.
+ +
+

EXAMPLES
+ +
+ + Let <tab> represent a tab (which should be typed as a genuine tab).
+ .TS
+ c s s
+ c c s
+ c c c
+ l n n.
+ Household Population
+ Town<tab>Households
+ <tab>Number<tab>Size
+ +
+Bedminster<tab>789<tab>3.26
+Bernards Twp.<tab>3087<tab>3.74
+Bernardsville<tab>2018<tab>3.30
+.TE
+
+
+
+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
+

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/tcs.html b/man/man1/tcs.html new file mode 100644 index 00000000..50919607 --- /dev/null +++ b/man/man1/tcs.html @@ -0,0 +1,131 @@ + +tcs(1) - Plan 9 from User Space + + + + +
+
+
TCS(1)TCS(1) +
+
+

NAME
+ +
+ + tcs – translate character sets
+ +
+

SYNOPSIS
+ +
+ + tcs [ −slcv ] [ −f ics ] [ −t ocs ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Tcs interprets the named file(s) (standard input default) as a + stream of characters from the ics character set or format, converts + them to runes, and then converts them into a stream of characters + from the ocs character set or format on the standard output. The + default value for ics and ocs is utf, the UTF encoding + described in utf(7). The −l option lists the character sets known + to tcs. Processing continues in the face of conversion errors + (the −s option prevents reporting of these errors). The −c option + forces the output to contain only correctly converted characters; + otherwise, 0x80 characters will be substituted for UTF + encoding errors and 0xFFFD characters will substituted for unknown + characters. +
+ + The −v option generates various diagnostic and summary information + on standard error, or makes the −l output more verbose. +
+ + 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
+ utf         The Plan 9 UTF encoding, known by ISO as UTF-8
+ utf1        The deprecated original UTF encoding from ISO 10646
+ ascii       7-bit ASCII
+ 8859−1      Latin-1 (Central European)
+ 8859−2      Latin-2 (Czech .. Slovak)
+ 8859−3      Latin-3 (Dutch .. Turkish)
+ 8859−4      Latin-4 (Scandinavian)
+ 8859−5      Part 5 (Cyrillic)
+ 8859−6      Part 6 (Arabic)
+ 8859−7      Part 7 (Greek)
+ 8859−8      Part 8 (Hebrew)
+ 8859−9      Latin-5 (Finnish .. Portuguese)
+ koi8        KOI-8 (GOST 19769-74)
+ jis−kanji   ISO 2022-JP
+ ujis        EUC-JX: JIS 0208
+ ms−kanji    Microsoft, or Shift-JIS
+ jis         (from only) guesses between ISO 2022-JP, EUC or Shift-Jis
+ gb          Chinese national standard (GB2312-80)
+ big5        Big 5 (HKU version)
+ unicode     Unicode Standard 1.0
+ tis         Thai character set plus ASCII (TIS 620-1986)
+ msdos       IBM PC: CP 437
+ atari       Atari-ST character set
+ +
+

EXAMPLES
+ +
+ + tcs −f 8859−1
+ +
+ + Convert 8859-1 (Latin-1) characters into UTF format.
+ +
+ tcs −s −f jis
+ +
+ + Convert characters encoded in one of several shift JIS encodings + into UTF format. Unknown Kanji will be converted into 0xFFFD characters.
+ +
+ tcs −lv
+ +
+ + Print an up to date list of the supported character sets.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/tcs
+ +
+

SEE ALSO
+ +
+ + ascii(1), rune(3), utf(7).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/tee.html b/man/man1/tee.html new file mode 100644 index 00000000..2ece532f --- /dev/null +++ b/man/man1/tee.html @@ -0,0 +1,56 @@ + +tee(1) - Plan 9 from User Space + + + + +
+
+
TEE(1)TEE(1) +
+
+

NAME
+ +
+ + tee – pipe fitting
+ +
+

SYNOPSIS
+ +
+ + tee [ −i ] [ −a ] files
+ +
+

DESCRIPTION
+ +
+ + Tee transcribes the standard input to the standard output and + makes copies in the files. The options are
+ −i    Ignore interrupts.
+ −a    Append the output to the files rather than rewriting them.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/tee.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/test.html b/man/man1/test.html new file mode 100644 index 00000000..0f3fa85d --- /dev/null +++ b/man/man1/test.html @@ -0,0 +1,156 @@ + +test(1) - Plan 9 from User Space + + + + +
+
+
TEST(1)TEST(1) +
+
+

NAME
+ +
+ + test – set status according to condition
+ +
+

SYNOPSIS
+ +
+ + test expr
+ +
+

DESCRIPTION
+ +
+ + Test evaluates the expression 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. +
+ + The following primitives are used to construct expr.
+ −r file      True if the file exists (is accessible) and is readable.
+ −w file      True if the file exists and is writable.
+ −x file      True if the file exists and has execute permission.
+ −e file      True if the file exists.
+ −f file      True if the file exists and is a plain file.
+ −d file      True if the file exists and is a directory.
+ −s file      True if the file exists and has a size greater than zero.
+ −t fildes     True if the open file whose file descriptor number is + fildes (1 by default) is the same file as /dev/cons.
+ −A file      True if the file exists and is append-only.
+ −L file      True if the file exists and is exclusive-use.
+ −Tfile      True if the file exists and is temporary.
+ s1 = s2     True if the strings s1 and s2 are identical.
+ s1 != s2    True if the strings s1 and s2 are not identical.
+ s1         True if s1 is not the null string. (Deprecated.)
+ −n s1       True if the length of string s1 is non-zero.
+ −z s1       True if the length of string s1 is zero.
+ n1 −eq n2True if the integers n1 and n2 are arithmetically equal. + Any of the comparisons −ne, −gt, −ge, −lt, or −le may be used + in place of −eq. The (nonstandard) construct −l string, meaning + the length of string, may be used in place of an integer.
+ a −nt b    True if file a is newer than (modified after) file b.
+ a −ot b    True if file a is older than (modified before) file b.
+ f −older tTrue if file f is older than (modified before) time + t. If t is a integer followed by the letters y(years), M(months), + d(days), h(hours), m(minutes), or 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, 3d12h means three days and twelve hours ago. +
+ + +
+ +
+ These primaries may be combined with the following operators:
+ !         unary negation operator
+ −o        binary or operator
+ −a        binary and operator; higher precedence than −o
+ ( expr )   parentheses for grouping. +
+ + The primitives −b, −u, −g, and −s return false; they are recognized + for compatibility with POSIX. +
+ + Notice that all the operators and flags are separate arguments + to test. Notice also that parentheses and equal signs are meaningful + to rc and must be enclosed in quotes.
+ +
+

EXAMPLES
+ +
+ + Test is a dubious way to check for specific character strings: + it uses a process to do what an rc(1) match or switch statement + can do. The first example is not only inefficient but wrong, because + test understands the purported string "−c" as an option.
+ +
+ + if (test $1 '=' "−c") echo OK # wrong!
+ +
+ + +
+ A better way is
+ +
+ + if (~ $1 −c) echo OK
+ +
+ + +
+ Test whether abc is in the current directory.
+ +
+ + test −f abc −o −d abc
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/test.c
+ +
+

SEE ALSO
+ +
+ + rc(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/time.html b/man/man1/time.html new file mode 100644 index 00000000..4646754f --- /dev/null +++ b/man/man1/time.html @@ -0,0 +1,63 @@ + +time(1) - Plan 9 from User Space + + + + +
+
+
TIME(1)TIME(1) +
+
+

NAME
+ +
+ + time – time a command
+ +
+

SYNOPSIS
+ +
+ + time command [ arg ... ]
+ +
+

DESCRIPTION
+ +
+ + The command is executed with the given arguments; after it is + complete, time reports on standard error the program’s elapsed + user time, system time, and real time, in seconds, followed by + the command line.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/time.c
+ +
+

SEE ALSO
+ +
+ + prof(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/touch.html b/man/man1/touch.html new file mode 100644 index 00000000..6e2f7f91 --- /dev/null +++ b/man/man1/touch.html @@ -0,0 +1,69 @@ + +touch(1) - Plan 9 from User Space + + + + +
+
+
TOUCH(1)TOUCH(1) +
+
+

NAME
+ +
+ + touch – set modification date of a file
+ +
+

SYNOPSIS
+ +
+ + touch [ −c ] [ −t time ] file ...
+ +
+

DESCRIPTION
+ +
+ + Touch attempts to set the modification time of the files to time + (by default, the current time). If a file does not exist, it will + be created unless option −c is present.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/touch.c
+ +
+

SEE ALSO
+ +
+ + ls(1), stat(3), chmod(1)
+ +
+

BUGS
+ +
+ + Touch will not touch directories.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/tr.html b/man/man1/tr.html new file mode 100644 index 00000000..dc827b3f --- /dev/null +++ b/man/man1/tr.html @@ -0,0 +1,107 @@ + +tr(1) - Plan 9 from User Space + + + + +
+
+
TR(1)TR(1) +
+
+

NAME
+ +
+ + tr – translate characters
+ +
+

SYNOPSIS
+ +
+ + tr [ −cds ] [ string1 [ string2 ] ]
+ +
+

DESCRIPTION
+ +
+ + Tr copies the standard input to the standard output with substitution + or deletion of selected characters (runes). Input characters found + in string1 are mapped into the corresponding characters of string2. + When string2 is short it is padded to the length of string1 by + duplicating its last character. Any combination of the + options −cds may be used:
+ −c    Complement string1: replace it with a lexicographically ordered + list of all other characters.
+ −d    Delete from input all characters in string1.
+ −s    Squeeze repeated output characters that occur in string2 to + single characters. +
+ + In either string a noninitial sequence −x, where 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 x. The character \ followed by 1, + 2 or 3 octal digits stands for the character whose 16-bit + value is given by those digits. The character sequence \x followed + by 1, 2, 3, or 4 hexadecimal digits stands for the character whose + 16-bit value is given by those digits. A \ followed by any other + character stands for that character.
+ +
+

EXAMPLES
+ +
+ + Replace all upper-case ASCII letters by lower-case.
+ +
+ + tr A−Z a−z <mixed >lower
+ +
+ + +
+ Create a list of all the words in file1 one per line in file2, + where a word is taken to be a maximal string of alphabetics. String2 + is given as a quoted newline.
+ +
+ + tr −cs A−Za−z '
+ ' <file1 >file2
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/tr.c
+ +
+

SEE ALSO
+ +
+ + sed(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/tr2post.html b/man/man1/tr2post.html new file mode 100644 index 00000000..808c329b --- /dev/null +++ b/man/man1/tr2post.html @@ -0,0 +1,152 @@ + +tr2post(1) - Plan 9 from User Space + + + + +
+
+
TR2POST(1)TR2POST(1) +
+
+

NAME
+ +
+ + tr2post – convert troff intermediate to PostScript
+ +
+

SYNOPSIS
+ +
+ + tr2post [ options ] [ files ... ]
+ +
+

DESCRIPTION
+ +
+ + Tr2post converts files (or standard input), which should be the + device-independent output of troff(1), into the PostScript printer + language. +
+ + The options are:
+ −a aspectratio
+ +
+ + Set an aspect ratio (y/x) to stretch the PostScript output (default + 1.0).
+ +
+ −c copies
+ +
+ + Set a comment in the PostScript output marking the number of copies + that should be printed. The comment is intended for ancient versions + of the Unix lp(1) and is not recognized by any current printer + or print spooler.
+ +
+ −d    Emit volumes of debugging output on standard error.
+ −m magnification
+ +
+ + Magnify the PostScript output (default 1.0).
+ +
+ −n formsperpage
+ +
+ + Print the PostScript with formsperpage logical pages per physical + page (default 1). Using this option emits PostScript with invalid + document structuring comments. It will print fine but will not + view correctly in gv(1) or psv (see page(1)).
+ +
+ −o pagelist
+ +
+ + Print only the pages in the pagelist, which is a comma-separated + list of ranges. Each range is of the form p (just page p), p−q + (pages p through q), −p (pages 1 through p), or p− (pages p through + the end of the document).
+ +
+ −p l   Print the document in landscape mode. An argument that does + not begin with l will print the document in portrait mode.
+ −x xoffset
+ +
+ + Translate the page output by xoffset inches to the right. (Negative + offsets translate to the left.)
+ +
+ −y yoffset
+ +
+ + Translate the page output by yoffset inches down. (Negative offsets + translate up.)
+ +
+ −P pscode
+ +
+ + Emit the text pscode at the end of the usual PostScript header.
+ +
+ +
+

EXAMPLE
+ +
+ + Preview this manual page:
+ +
+ + troff −man /usr/local/plan9/man/man1/tr2post.1 |
+ tr2post |
+ psfonts >/tmp/a.ps
+ psv /tmp/a.ps
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/postscript/tr2post
+ +
+

SEE ALSO
+ +
+ + troff(1), psfonts(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/troff.html b/man/man1/troff.html new file mode 100644 index 00000000..a3d8477f --- /dev/null +++ b/man/man1/troff.html @@ -0,0 +1,126 @@ + +troff(1) - Plan 9 from User Space + + + + +
+
+
TROFF(1)TROFF(1) +
+
+

NAME
+ +
+ + troff, nroff – text formatting and typesetting
+ +
+

SYNOPSIS
+ +
+ + troff [ option ... ] [ file ... ] +
+ + nroff [ option ... ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Troff formats text in the named files for printing on a typesetter. + Nroff does the same, but produces output suitable for typewriter-like + devices. +
+ + If no file argument is present, the standard input is read. An + argument consisting of a single minus (−) is taken to be a file + name corresponding to the standard input. The options are:
+ −olist   Print pages in the comma-separated list of numbers and ranges. + A range N−M means N through M; initial −M means up to M; final + N− means from N to the end.
+ −nN     Number first generated page N.
+ −mnameProcess the macro file /sys/lib/tmac/tmac.name before the + input files.
+ −raN    Set register a (one character name) to N.
+ −i      Read standard input after the input files are exhausted.
+ −q      Invoke the simultaneous input-output mode of the rd request.
+ −N      Produce output suitable for typewriter-like devices.
+

Typesetter devices (not −N) only
+ −a      Send a printable textual approximation of the results to the + standard output.
+ −Tdest   Prepare output for typesetter dest:
+ +
+ + +
+ + −Tutf     (The default.) PostScript printers with preprocessing to + handle Unicode characters encoded in UTF
+ −Tpost    Regular PostScript printers
+ −T202     Mergenthaler Linotron 202
+ +
+ +
+ −Fdir   Take font information from directory dir.
+

Typewriter (−N) output only
+ −sN     Halt prior to every N pages (default N=1) to allow paper loading + or changing.
+ −TnamePrepare output for specified terminal. Known names include + utf for the normal Plan 9 UTF encoding of the Unicode Standard + character set (default), 37 for the Teletype model 37, lp (‘line-printer’) + for any terminal without half-line capability, 450 for the DASI-450 + (Diablo Hyterm), and think (HP ThinkJet). + −e      Produce equally-spaced words in adjusted lines, using full terminal + resolution.
+ −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.
+ +

+

FILES
+ +
+ + /tmp/trtmp*                   temporary file
+ /usr/local/plan9/tmac/tmac.*    standard macro files
+ /usr/local/plan9/troff/term/*   terminal driving tables for nroff
+ /usr/local/plan9/troff/font/*   font width tables for troff
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/troff
+ +
+

SEE ALSO
+ +
+ + lpr(1), proof(1), tr2post(1), eqn(1), tbl(1), pic(1), grap(1), + doctype(1), ms(7), image(7), tex(1), deroff(1)
+ J. F. Ossanna and B. W. Kernighan, “Troff User’s Manual”
+ B. W. Kernighan, “A TROFF Tutorial”, Unix Research System Programmer’s + Manual, Tenth Edition, Volume 2.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/troff2html.1 b/man/man1/troff2html.1 new file mode 100644 index 00000000..01bd0681 --- /dev/null +++ b/man/man1/troff2html.1 @@ -0,0 +1,96 @@ +.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 Plan 9's \fIhttpd\fR(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 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/man/man1/troff2html.html b/man/man1/troff2html.html new file mode 100644 index 00000000..77dff2d7 --- /dev/null +++ b/man/man1/troff2html.html @@ -0,0 +1,108 @@ + +troff2html(1) - Plan 9 from User Space + + + + +
+
+
TROFF2HTML(1)TROFF2HTML(1) +
+
+

NAME
+ +
+ + troff2html – convert troff output into HTML
+ +
+

SYNOPSIS
+ +
+ + troff2html [ −t title ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Troff2html reads the troff(1) output in the named files, default + standard input, and converts them into HTML. +
+ + Troff2html does a tolerable job with straight troff output, but + it is helped by annotations, described below. Its main use is + for man2html (see Plan 9’s httpd(8)), which converts man(1) pages + into HTML and depends on a specially annotated set of man(6) macros, + invoked by troff −manhtml. +
+ + Troff output lines beginning
+ +
+ + x X html ...
+ +
+ + +
+ which are introduced by placing \X'html ...' in the input, cause + the rest of the line to be interpolated into the HTML produced. + Several such lines are recognized specially by troff2html. The + most important are the pair
+ +
+ + x X html manref start cp 1
+ x X html manref end cp 1
+ +
+ + +
+ which are used to create HTML hyperlinks around text of the form + cp(1) pointing to /magic/man2html/1/cp. +
+ + Troff2html is new and experimental; in time, it may improve and + subsume ms2html(1). On the one hand, because it uses the input, + ms2html can handle pic(1), eqn(1), etc., which troff2html does + not handle at all; on the other hand, ms2html understands only + ms(6) documents and is easily confused by complex + troff constructions. 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.
+ +
+

SEE ALSO
+ +
+ + troff(1), ms2html(1), man2html in httpd(8).
+ +
+

BUGS
+ +
+ + Troff and HTML have different models, and they don’t mesh well + in all cases. Troff’s indented paragraphs are not well served + in HTML, and the output of troff2html shows this.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/tweak.html b/man/man1/tweak.html new file mode 100644 index 00000000..9d63dcd4 --- /dev/null +++ b/man/man1/tweak.html @@ -0,0 +1,194 @@ + +tweak(1) - Plan 9 from User Space + + + + +
+
+
TWEAK(1)TWEAK(1) +
+
+

NAME
+ +
+ + tweak – edit image files, subfont files, face files, etc.
+ +
+

SYNOPSIS
+ +
+ + tweak [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Tweak edits existing files holding various forms of images. To + create original images, start from an existing image, subfont, + etc. +
+ + Tweak reads its argument 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 rio + window. Under each image is displayed one or two lines of text + presenting its parameters. The first line shows the image’s depth, + the number of bits per pixel; r, the rectangle covered by the + image; and the name of the file from which it was read. If the + file is a subfont, a second line presents a hexadecimal 16-bit + offset to be applied to character values from the subfont (typically + as stored in a font file; see font(7)); and the subfont’s n, + height, and ascent as defined in cachechars(3). +
+ + By means described below, magnified views of portions of the images + may be displayed. The text associated with such a view includes + 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 tweak’s default font; the character’s x, top, bottom, + left, and width as defined in cachechars(3); and iwidth, the physical + width of the image in the subfont’s image. +
+ + 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 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. +
+ + 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 rio, that encloses + the portion of the image to be magnified. (If the file is 16x16 + or smaller, tweak will just magnify the entire file; no sweeping + is + necessary.) +
+ + 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. +
+ + 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:
+ mag   Default magnification.
+ 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.
+ +
+ but1
+ but2The pixel value written when the corresponding button is pressed + over a pixel.
+ invert−on−copy
+ +
+ + Whether the pixel values are inverted when a copy operation is + performed. +
+ + +
+ 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.
+ openRead and display a file. The name of the file is typed to + the prompt on the bottom line.
+ readReread a file.
+ write
+ +
+ + Write a file.
+ +
+ copyUse the copy function, default 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.
+ +
+ charAs described above, open a magnified view of a character image + in a subfont.
+ 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.
+ +
+ close
+ +
+ + Close the specified image. If the image is the unmagnified file, + also close any magnified views of that file.
+ +
+ exitQuit tweak. The program will complain once about modified + but unwritten files.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/draw/tweak.c
+ +
+

SEE ALSO
+ +
+ + cachechars(3), image(7), font(7)
+ +
+

BUGS
+ +
+ + For a program written to adjust width tables in fonts, tweak has + been pushed unreasonably far.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/uniq.html b/man/man1/uniq.html new file mode 100644 index 00000000..7f0e4377 --- /dev/null +++ b/man/man1/uniq.html @@ -0,0 +1,79 @@ + +uniq(1) - Plan 9 from User Space + + + + +
+
+
UNIQ(1)UNIQ(1) +
+
+

NAME
+ +
+ + uniq – report repeated lines in a file
+ +
+

SYNOPSIS
+ +
+ + uniq [ −udc [ +−num ] ] [ file ]
+ +
+

DESCRIPTION
+ +
+ + Uniq copies the input 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.
+ −u    Print unique lines.
+ −d    Print (one copy of) duplicated lines.
+ −c    Prefix a repetition count and a tab to each output line. Implies + −u and −d.
+ −numThe first 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.
+ +numThe first num characters are ignored. Fields are skipped before + characters.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/uniq.c
+ +
+

SEE ALSO
+ +
+ + sort(1)
+ +
+

BUGS
+ +
+ + Field selection and comparison should be compatible with sort(1).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/units.html b/man/man1/units.html new file mode 100644 index 00000000..fed0c287 --- /dev/null +++ b/man/man1/units.html @@ -0,0 +1,156 @@ + +units(1) - Plan 9 from User Space + + + + +
+
+
UNITS(1)UNITS(1) +
+
+

NAME
+ +
+ + units – conversion program
+ +
+

SYNOPSIS
+ +
+ + units [ −v ] [ file ]
+ +
+

DESCRIPTION
+ +
+ + Units converts quantities expressed in various standard scales + to their equivalents in other scales. It works interactively in + this fashion:
+ +
+ + you have: inch
+ you want: cm
+ +
+ + * 2.54
+ / 0.393701
+ +
+ +
+ +
+ + + +
+ +
+ A quantity is specified as a multiplicative combination of units + and floating point numbers. Operators have the following precedence:
+ +
+ + + −             add and subtract
+ * / x ÷           multiply and divide
+ catenation         multiply
+ ² ³ ^            exponentiation
+ |               divide
+ ( ... )            grouping
+ +
+ + +
+ Most familiar units, abbreviations, and metric prefixes are recognized, + together with a generous leavening of exotica and a few constants + of nature including:
+ +
+ + pi,π      ratio of circumference to diameter
+ c         speed of light
+ e         charge on an electron
+ g         acceleration of gravity
+ force     same as g
+ mole      Avogadro’s number
+ water     pressure head per unit height of water
+ au        astronomical unit
+ +
+ + +
+ The pound is a unit of mass. Compound names are run together, + e.g. lightyear. British units that differ from their US counterparts + are prefixed thus: brgallon. Currency is denoted belgiumfranc, + britainpound, etc. +
+ + The complete list of units can be found in /usr/local/plan9/lib/units. + A file argument to units specifies a file to be used instead of + /usr/local/plan9/lib/units. The −v flag causes units to print + its entire database.
+ +
+

EXAMPLE
+ +
+ + you have: 15 pounds force/in²
+ you want: atm
+ +
+ + * 1.02069
+ / .97973
+ +
+ +
+

FILES
+ +
+ + /usr/local/plan9/lib/units
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/units.y
+ +
+

BUGS
+ +
+ + Since units does only multiplicative scale changes, it can convert + Kelvin to Rankine but not Centigrade to Fahrenheit. +
+ + Currency conversions are only as accurate as the last time someone + updated the database.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/vac.html b/man/man1/vac.html new file mode 100644 index 00000000..71f121ff --- /dev/null +++ b/man/man1/vac.html @@ -0,0 +1,160 @@ + +vac(1) - Plan 9 from User Space + + + + +
+
+
VAC(1)VAC(1) +
+
+

NAME
+ +
+ + vac – create a vac archive on Venti
+ +
+

SYNOPSIS
+ +
+ + vac [ −mqsv ] [ −b blocksize ] [ −d oldvacfile ] [ −e exclude + ] [ −f vacfile ] [ −i name ] [ −h host ] file ...
+ +
+

DESCRIPTION
+ +
+ + 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 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. +
+ + As an optimization, the −d and −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 vac, but simply reduce the number of write operations to Venti. + +
+ + The output of vac is the hexadecimal representation of the Sha1 + fingerprint of the root of the archive, in this format:
+ +
+ + vac:64daefaecc4df4b5cb48a368b361ef56012a4f46
+ +
+ + +
+ Option to vac are:
+ −b blocksize
+ +
+ + Specifies the block size that data will be broken into. The units + for the size can be specified by appending k to indicate kilobytes. + The default is 8k. The size must be in the range of 512 bytes + to 52k.
+ +
+ −d oldvacfile
+ +
+ + Reduce the number of blocks written to Venti by comparing the + files to be stored with the contents of an existing vac file tree + given by oldvacfile.
+ +
+ −e exclude
+ +
+ + Do not include the file or directory specified by exclude. This + option may be repeated multiple times.
+ +
+ −f vacfile
+ +
+ + The results of vac are place in vacfile, or the standard output + if no file is given.
+ +
+ −i name
+ +
+ + Include standard input as one of the input files, storing it in + the archive with the specified name.
+ +
+ −h host
+ +
+ + The network address of the Venti server. The default is taken + from the environment variable venti.
+ +
+ −m    Expand and merge any 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 .vac. Note, an archive is inserted by + simply copying the root fingerprint and does not require the archive + to be unpacked.
+ +
+ −q    Increase the performance of the −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.
+ −s    Print out various statistics on standard error.
+ −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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/vac
+ +
+

SEE ALSO
+ +
+ + Plan 9’s vacfs(4) and venti(8)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/wc.html b/man/man1/wc.html new file mode 100644 index 00000000..677c2937 --- /dev/null +++ b/man/man1/wc.html @@ -0,0 +1,75 @@ + +wc(1) - Plan 9 from User Space + + + + +
+
+
WC(1)WC(1) +
+
+

NAME
+ +
+ + wc – word count
+ +
+

SYNOPSIS
+ +
+ + wc [ −lwrbc ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Wc counts lines, words, runes, syntactically-invalid UTF codes + and bytes in the named 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. +
+ + If the optional argument is present, just the specified counts + (lines, words, runes, broken UTF codes or bytes) are selected + by the letters l, w, r, b, or c. Otherwise, lines, words and bytes + (−lwc) are reported.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/wc.c
+ +
+

BUGS
+ +
+ + The Unicode Standard has many blank characters scattered through + it, but wc looks for only ASCII space, tab and newline. +
+ + Wc should have options to count suboptimal UTF codes and bytes + that cannot occur in any UTF code.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/web.html b/man/man1/web.html new file mode 100644 index 00000000..cb0ad0b4 --- /dev/null +++ b/man/man1/web.html @@ -0,0 +1,115 @@ + +web(1) - Plan 9 from User Space + + + + +
+
+
WEB(1)WEB(1) +
+
+

NAME
+ +
+ + web, wmail – handle web page, mail message for plumber
+ +
+

SYNOPSIS
+ +
+ + web url ...
+ wmail address
+ +
+

DESCRIPTION
+ +
+ + Web opens each of the named urls in a new web browser window. + Any of the urls may be relative paths to files in the file system; + they will be translated into file:// URLs before being passed + to the web browser. +
+ + Web uses the web browser’s −remote option command-line option, + which requires an instance of the web browser to be already running. + The choice of browser is determined by the $BROWSER environment + variable, which should be the name of the executable for your + choice of web browser. The default is + firefox. Since the various browsers all use different syntaxes + in their −remote options, the executable name is inspected to + determine the type of browser. The supported browsers are Opera, + Mozilla Firefox, Mozilla Firebird, and Mozilla. When possible, + web opens each URL in a new tab rather than a new window. + +
+ + When run under Mac OS X, $BROWSER should be set to the string + safari or firefox. Web uses AppleScript to talk to the browser. + If $BROWSER is not set, web looks for Firefox in /Applications/Firefox.app + and uses it if found; otherwise it uses Safari. +
+ + Wmail starts the composition of a new mail message to address. + +
+ + The choice of mailer is determined by the $MAILER environment + variable. The supported mailers are:
+ browser
+ +
+ + invoke the mailer via a mailto:// URL passed to web +
+ + +
+ Web and wmail are invoked as start commands in the plumber(4)’s + rules for opening web pages and writing mail messages.
+ +
+

FILES
+ +
+ + /usr/local/plan9/plumb/basic
+ +
+ + plumbing rules using web and wmail
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin
+ +
+

SEE ALSO
+ +
+ + plumber(4)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/wintext.html b/man/man1/wintext.html new file mode 100644 index 00000000..d4de3349 --- /dev/null +++ b/man/man1/wintext.html @@ -0,0 +1,124 @@ + +wintext(1) - Plan 9 from User Space + + + + +
+
+
WINTEXT(1)WINTEXT(1) +
+
+

NAME
+ +
+ + wintext, ", "" – access text in current window
+ +
+

SYNOPSIS
+ +
+ + wintext
+ ?? [ prefix ]
+ ???? [ prefix ]
+ +
+

DESCRIPTION
+ +
+ + Wintext prints the text of the current win (see acme(1)) or 9term(1) + window to standard output. +
+ + ?? searches the window text for commands typed with a particular + prefix and prints them, indented, to standard output. Prefix is + a regular expression that is matched against the beginning of + the command-line. If prefix is omitted, ?? prints the last command + executed. ???? prints the last command that ?? would print and + then executes it by piping it into rc(1). +
+ + Both ?? and ???? identify commands in the window text by looking for + lines beginning with a shell prompt. Prompts are assumed to be + an unindented sequence of non-whitespace characters followed by + one of the characters %, ;, $, or #.
+ +
+

EXAMPLES
+ +
+ + Print the ls(1) and lc commands executed in this window:
+ +
+ + % ?? 'l[sc]'
+ +
+ + % ls −l /tmp/qq*
+ # ls −lrt /etc
+ % lc r*
+ +
+ %
+ +
+ + +
+ Execute the most recent lc command again:
+ +
+ + % ???? lc
+ +
+ + % lc r*
+ +
+ ramfs     rc        read      rio       rm
+ %
+ +
+ +
+

SEE ALSO
+ +
+ + 9term(1), acme(1)
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/bin
+ +
+

BUGS
+ +
+ + ?? and ???? are hard to type in shells other than rc(1).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/xd.html b/man/man1/xd.html new file mode 100644 index 00000000..86e6152e --- /dev/null +++ b/man/man1/xd.html @@ -0,0 +1,99 @@ + +xd(1) - Plan 9 from User Space + + + + +
+
+
XD(1)XD(1) +
+
+

NAME
+ +
+ + xd – hex, octal, decimal, or ASCII dump
+ +
+

SYNOPSIS
+ +
+ + xd [ option ... ] [ −format ... ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + Xd concatenates and dumps the 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. +
+ + Formats other than −c are specified by pairs of characters telling + size and style, 4x by default. The sizes are
+ 1 or b   1-byte units.
+ 2 or w   2-byte big-endian units.
+ 4 or l   4-byte big-endian units.
+ 8 or v   8-byte big-endian units. +
+ + The styles are
+ o     Octal.
+ x     Hexadecimal.
+ d     Decimal. +
+ + Other options are
+ −c      Format as 1x but print ASCII representations or C escape sequences + where possible.
+ −astyle   Print file addresses in the given style (and size 4).
+ −u      (Unbuffered) Flush the output buffer after each 16-byte sequence.
+ −s      Reverse (swab) the order of bytes in each group of 4 before + printing.
+ −r      Print repeating groups of identical 16-byte sequences as the + first group followed by an asterisk.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/xd.c
+ +
+

SEE ALSO
+ +
+ + db(1)
+ +
+

BUGS
+ +
+ + The various output formats don’t line up properly in the output + of xd.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man1/yacc.html b/man/man1/yacc.html new file mode 100644 index 00000000..1a485ce6 --- /dev/null +++ b/man/man1/yacc.html @@ -0,0 +1,170 @@ + +yacc(1) - Plan 9 from User Space + + + + +
+
+
YACC(1)YACC(1) +
+
+

NAME
+ +
+ + yacc – yet another compiler-compiler
+ +
+

SYNOPSIS
+ +
+ + yacc [ option ... ] grammar
+ +
+

DESCRIPTION
+ +
+ + 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. +
+ + The output file, y.tab.c, must be compiled by the C compiler to + produce a program yyparse. This program must be loaded with a + lexical analyzer function, yylex(void) (often generated by lex(1)), + with a main(int    argc,    char    *argv[]) program, and with an error + handling routine, + yyerror(char*). +
+ + The options are
+ −o output   Direct output to the specified file instead of y.tab.c.
+ −Dn       Create file y.debug, containing diagnostic messages. To incorporate + them in the parser, compile it with preprocessor symbol yydebug + defined. The amount of diagnostic output from the parser is regulated + by value n. The value 0 reports errors; 1 reports reductions; + higher values (up to 4) include + +
+ + +
+ + more information about state transitions.
+ +
+ +
+ −v        Create file y.output, containing a description of the parsing + tables and of conflicts arising from ambiguities in the grammar.
+ −d        Create file y.tab.h, containing #define statements that associate + yacc-assigned ‘token codes’ with user-declared ‘token names’. + Include it in source files other than y.tab.c to give access to + the token codes.
+ −s stem     Change the prefix y of the file names y.tab.c, y.tab.h, + y.debug, and y.output to stem.
+ −S        Write a parser that uses Stdio instead of the print routines + in libc. +
+ + The specification of yacc itself is essentially the same as the + UNIX version described in the references mentioned below. Besides + the −D option, the main relevant differences are:
+ +
+ + The interface to the C environment is by default through <libc.h> + rather than <stdio.h>; the −S option reverses this.
+ The parser accepts UTF input text (see utf(7)), which has a couple + of effects. First, the return value of yylex() no longer fits + in a short; second, the starting value for non-terminals is now + 0xE000 rather than 257.
+ The generated parser can be recursive: actions can call yyparse, + for example to implement a sort of #include statement in an interpreter.
+ Finally, some undocumented inner workings of the parser have been + changed, which may affect programs that know too much about its + structure.
+ +
+ +
+

FILES
+ +
+ + y.output
+ y.tab.c
+ y.tab.h
+ y.debug
+ y.tmp.*         temporary file
+ y.acts.*        temporary file
+ /usr/local/plan9/lib/yaccpar
+ +
+ + +
+ + parser prototype
+ +
+ +
+ /usr/local/plan9/lib/yaccpars
+ +
+ + +
+ + parser prototype using stdio
+ +
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/yacc.c
+ +
+

SEE ALSO
+ +
+ + lex(1)
+ S. C. Johnson and R. Sethi, “Yacc: A parser generator”, Unix Research + System Programmer’s Manual, Tenth Edition, Volume 2
+ B. W. Kernighan and Rob Pike, The UNIX Programming Environment, + Prentice Hall, 1984
+ +
+

BUGS
+ +
+ + The parser may not have full information when it writes to y.debug + so that the names of the tokens returned by yylex may be missing.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9p-cmdbuf.html b/man/man3/9p-cmdbuf.html new file mode 100644 index 00000000..122a5857 --- /dev/null +++ b/man/man3/9p-cmdbuf.html @@ -0,0 +1,128 @@ + +9p-cmdbuf(3) - Plan 9 from User Space + + + + +
+
+
9P-CMDBUF(3)9P-CMDBUF(3) +
+
+

NAME
+ +
+ + Cmdbuf, parsecmd, respondcmderror, lookupcmd – control message + parsing
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + 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, ...)
+ +
+

DESCRIPTION
+ +
+ + These data structures and functions provide parsing of textual + control messages. +
+ + Parsecmd treats the n bytes at p (which need not be NUL-terminated) + as a UTF string and splits it using tokenize (see getfields(3)). + It returns a Cmdbuf structure holding pointers to each field in + the message. +
+ + Lookupcmd walks through the array ctab, which has ntab entries, + looking for the first Cmdtab that matches the parsed command. + (If the parsed command is empty, lookupcmd returns nil immediately.) + A Cmdtab matches the command if cmd is equal to cb−>f[0] or if + cmd is *. Once a matching Cmdtab has been + found, if narg is not zero, then the parsed command must have + exactly narg fields (including the command string itself). If + the command has the wrong number of arguments, lookupcmd returns + nil. Otherwise, it returns a pointer to the Cmdtab entry. If lookupcmd + does not find a matching command at all, it returns + nil. Whenever lookupcmd returns nil, it sets the system error + string. +
+ + Respondcmderror resoponds to request r with an error of the form + ‘fmt: cmd,’ where fmt is the formatted string and cmd is a reconstruction + of the parsed command. Fmt is often simply %r .
+ +
+

EXAMPLES
+ +
+ + This interface is not used in any distributed 9P servers. It was + lifted from the Plan 9 kernel. Almost any Plan 9 kernel driver + (/sys/src/9/*/dev*.c on Plan 9) is a good example.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p/parse.c
+ +
+

SEE ALSO
+ +
+ + 9p(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9p-fid.html b/man/man3/9p-fid.html new file mode 100644 index 00000000..44bca53c --- /dev/null +++ b/man/man3/9p-fid.html @@ -0,0 +1,170 @@ + +9p-fid(3) - Plan 9 from User Space + + + + +
+
+
9P-FID(3)9P-FID(3) +
+
+

NAME
+ +
+ + Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, + removefid, Req, Reqpool, allocreqpool, freereqpool, allocreq, + closereq, lookupreq, removereq – 9P fid, request tracking
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + typedef struct Fid
+ {
+ +
+ + ulong fid;
+ char    omode;    /* −1 if not open */
+ char    *uid;
+ Qid     qid;
+ File    *file;
+ void    *aux;
+ +
+ +
+ + ...
+ +
+ } Fid;
+ +
+ + typedef struct Req
+ {
+ +
+ + ulong tag;
+ Fcall ifcall;
+ Fcall ofcall;
+ Req     *oldreq;
+ void    *aux;
+ +
+ +
+ + ...
+ +
+ } Req;
+ +
+ + Fidpool* allocfidpool(void (*destroy)(Fid*))
+ void       freefidpool(Fidpool *p)
+ Fid*       allocfid(Fidpool *p, ulong fid)
+ Fid*       lookupfid(Fidpool *p, ulong fid)
+ void       closefid(Fid *f)
+ void       removefid(Fid *f)
+ +
+ + Reqpool* allocreqpool(void (*destroy)(Req*))
+ void       freereqpool(Reqpool *p)
+ Req*       allocreq(Reqpool *p, ulong tag)
+ Req*       lookupreq(Reqpool *p, ulong tag)
+ void       closereq(Req *f)
+ void       removereq(Req *r)
+ +
+

DESCRIPTION
+ +
+ + These routines provide management of Fid and Req structures from + Fidpools and Reqpools. They are primarily used by the 9P server + loop described in 9p(3). +
+ + Fid structures are intended to represent active fids in a 9P connection, + as Chan structures do in the Plan 9 kernel. The fid element is + the integer fid used in the 9P connection. Omode is the mode under + which the fid was opened, or −1 if this fid has not been opened + yet. Note that in addition to the values OREAD, + OWRITE, and ORDWR, omode can contain the various flags permissible + in an open call. To ignore the flags, use omode&OMASK. Omode should + not be changed by the client. The fid derives from a successful + authentication by uid. Qid contains the qid returned in the last + successful walk or create transaction + involving the fid. In a file tree-based server, the Fid’s file + element points at a File structure (see 9p-file(3)) corresponding + to the fid. The aux member is intended for use by the client to + hold information specific to a particular Fid. With the exception + of aux, these elements should be treated as read-only by + the client. +
+ + Allocfidpool creates a new Fidpool. Freefidpool destroys such + a pool. Allocfid returns a new Fid whose fid number is fid. There + must not already be an extant Fid with that number in the pool. + Once a Fid has been allocated, it can be looked up by fid number + using lookupfid. Fids are reference counted: both + allocfid and lookupfid increment the reference count on the Fid + structure before returning. When a reference to a Fid is no longer + needed, closefid should be called to note the destruction of the + reference. When the last reference to a Fid is removed, if destroy + (supplied when creating the fid pool) is not zero, it is + called with the Fid as a parameter. It should perform whatever + cleanup is necessary regarding the aux element. Removefid is equivalent + to closefid but also removes the Fid from the pool. Note that + due to lingering references, the return of removefid may not mean + that destroy has been called. +
+ + Allocreqpool, freereqpool, allocreq, lookupreq, closereq, and + removereq are analogous but operate on Reqpools and Req structures.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p
+ +
+

SEE ALSO
+ +
+ + 9p(3), 9p-file(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9p-file.html b/man/man3/9p-file.html new file mode 100644 index 00000000..63ae5042 --- /dev/null +++ b/man/man3/9p-file.html @@ -0,0 +1,258 @@ + +9p-file(3) - Plan 9 from User Space + + + + +
+
+
9P-FILE(3)9P-FILE(3) +
+
+

NAME
+ +
+ + Tree, alloctree, freetree, File, createfile, closefile, removefile, + walkfile, opendirfile, readdirfile, closedirfile, hasperm – in-memory + file hierarchy
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + typedef struct File
+ {
+ +
+ + +
+ + Ref;
+ Dir;
+ void*aux;
+ +
+ +
+ +
+ + +
+ + ...
+ +
+ +
+ } File;
+ +
+ + typedef struct Tree
+ {
+ +
+ + +
+ + File *root;
+ +
+ +
+ +
+ + +
+ + ...
+ +
+ +
+ } Tree;
+ +
+ + Tree*      alloctree(char *uid, char *gid, ulong mode,
+ +
+ + +
+ + void (*destroy)(File*))
+ +
+ +
+ void       freetree(Tree *tree)
+ File*      createfile(File *dir, char *name, char *uid,
+ +
+ + +
+ + ulong mode, void *aux)
+ +
+ +
+ int        removefile(File *file)
+ void       closefile(File *file)
+ File*      walkfile(File *dir, char *path)
+ Readdir* opendirfile(File *dir)
+ long       readdirfile(Readdir *rdir, char *buf, long n)
+ void       closedirfile(Readdir *rdir)
+ int        hasperm(File *file, char *uid, int p)
+ +
+

DESCRIPTION
+ +
+ + Files and Trees provide an in-memory file hierarchy intended for + use in 9P file servers. +
+ + Alloctree creates a new tree of files, and freetree destroys it. + The root of the tree (also the root element in the structure) + will have mode mode and be owned by user uid and group gid. Destroy + is used when freeing File structures and is described later. +
+ + Files (including directories) other than the root are created + using createfile, which attempts to create a file named name in + the directory dir. If created, the file will have owner uid and + have a group inherited from the directory. Mode and the permissions + of dir are used to calculate the permission bits for the file + as + described in open(9p). It is permissible for name to be a slash-separated + path rather than a single element. +
+ + 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. Removefile returns zero on success, + –1 on error. It is correct to consider removefile to be closefile + with the side effect of removing the file when possible. +
+ + Walkfile evaluates path relative to the directory dir, returning + the resulting file, or zero if the named file or any intermediate + element does not exist. +
+ + The File structure’s aux pointer may be used by the client for + per-File storage. Files are reference-counted: if not zero, destroy + (specified in the call to alloctree) will be called for each file + when its last reference is removed or when the tree is freed. + Destroy should take care of any necessary cleanup related to + aux. When creating new file references by copying pointers, call + incref (see lock(3)) to update the reference count. To note the + removal of a reference to a file, call closefile. Createfile and + walkfile return new references. Removefile, closefile, and walkfile + (but not createfile) consume the passed reference. +
+ + Directories may be read, yielding a directory entry structure + (see stat(9p)) for each file in the directory. In order to allow + concurrent reading of directories, clients must obtain a Readdir + structure by calling opendirfile on a directory. Subsequent calls + to readdirfile will each yield an integral number of machine- + independent stat buffers, until end of directory. When finished, + call closedirfile to free the Readdir. +
+ + Hasperm does simplistic permission checking; it assumes only one-user + groups named by uid and returns non-zero if uid has permission + p (a bitwise-or of AREAD, AWRITE and AEXEC) according to file−>mode. + 9P servers written using File trees will do standard permission + checks automatically; hasperm may be + called explicitly to do additional checks. A 9P server may link + against a different hasperm implementation to provide more complex + groups.
+ +
+

EXAMPLE
+ +
+ + The following code correctly handles references when elementwise + walking a path and creating a file.
+ +
+ + f = tree−>root;
+ incref(f);
+ for(i=0; i<n && f!=nil; i++)
+ +
+ + f = walkfile(f, elem[i]);
+ +
+ if(f == nil)
+ +
+ + return nil;
+ +
+ nf = createfile(f, "foo", "nls", 0666, nil);
+ closefile(f);
+ return nf;
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p/file.c
+ +
+

SEE ALSO
+ +
+ + 9p(3)
+ +
+

BUGS
+ +
+ + The reference counting is cumbersome.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9p-intmap.html b/man/man3/9p-intmap.html new file mode 100644 index 00000000..f6d1822f --- /dev/null +++ b/man/man3/9p-intmap.html @@ -0,0 +1,110 @@ + +9p-intmap(3) - Plan 9 from User Space + + + + +
+
+
9P-INTMAP(3)9P-INTMAP(3) +
+
+

NAME
+ +
+ + Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey, + deletekey – integer to data structure maps
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + 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)
+ +
+

DESCRIPTION
+ +
+ + An Intmap is an arbitrary mapping from integers to pointers. Allocmap + creates a new map, and freemap destroys it. The inc function is + called each time a new pointer is added to the map; similarly, + 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 insertkey, which will + return the previous value associated with the given key, or zero + if there was no previous value. Caninsertkey is like insertkey + but only inserts val if there is no current mapping. It returns + 1 if val was inserted, 0 otherwise. Lookupkey returns the pointer + associated with key, or zero if there is no such pointer. Deletekey + removes the entry for id from the map, returning the associated + pointer, if any. +
+ + Concurrent access to Intmaps is safe, moderated via a QLock stored + in the Intmap structure. +
+ + In anticipation of the storage of reference-counted structures, + an increment function inc may be specified at map creation time. + Lookupkey calls 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 insertkey and the external increment. Insertkey and caninsertkey + do not call inc when inserting val into the map, nor do insertkey + or deletekey call 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 deletekey or the next insertkey. + +
+ + Intmaps are used by the 9P library to implement Fidpools and Reqpools.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p/intmap.c
+ +
+

SEE ALSO
+ +
+ + 9p(3), 9p-fid(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9p.html b/man/man3/9p.html new file mode 100644 index 00000000..9896b0b7 --- /dev/null +++ b/man/man3/9p.html @@ -0,0 +1,434 @@ + +9p(3) - Plan 9 from User Space + + + + +
+
+
9P(3)9P(3) +
+
+

NAME
+ +
+ + Srv, dirread9p, emalloc9p, erealloc9p, estrdup9p, postfd, postmountsrv, + readbuf, readstr, respond, srv, threadpostmountsrv, walkandclone + – 9P file service
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + 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;
+ +
+ + int     srv(Srv *s)
+ void    postmountsrv(Srv *s, char *name, char *mtpt, int flag)
+ void    threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
+ int     postfd(char *srvname, int fd)
+ void    respond(Req *r, char *error)
+ ulong readstr(Req *r, char *src)
+ ulong readbuf(Req *r, void *src, ulong nsrc)
+ typedef int Dirgen(int n, Dir *dir, void *aux)
+ void    dirread9p(Req *r, Dirgen *gen, void *aux)
+ void    walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, + void *v),
+ +
+ + +
+ + char *(*clone)(Fid *old, Fid *new, void *v), void *v)
+ +
+ + +
+ +
+ void* emalloc9p(ulong n)
+ void* erealloc9p(void *v, ulong n)
+ char* estrdup9p(char *s)
+ +
+ + extern int chatty9p;
+ +
+

DESCRIPTION
+ +
+ + The function srv serves a 9P session by reading requests from + s−>infd, dispatching them to the function pointers kept in Srv, + and writing the responses to s−>outfd. (Typically, postmountsrv + or threadpostmountsrv initializes the infd and outfd structure + members. See the description below.) +
+ + Req and Fid structures are allocated one-to-one with uncompleted + requests and active fids, and are described in 9p-fid(3). +
+ + The behavior of srv depends on whether there is a file tree (see + 9p-file(3)) associated with the server, that is, whether the tree + element is nonzero. The differences are made explicit in the discussion + of the service loop below. The aux element is the client’s, to + do with as it pleases. +
+ + 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 emalloc9p, erealloc9p, and estrdup9p + to obtain its memory. The default implementations of these + functions act as malloc, realloc, and 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. + +
+ + Postmountsrv and threadpostmountsrv are wrappers that create a + separate process in which to run srv. They do the following:
+ +
+ + If s−>nopipe is zero (the common case), initialize s−>infd and s−>outfd + to be one end of a freshly allocated pipe, with s−>srvfd initialized + as the other end.
+ If name is non-nil, call postfd(s−>srvfd, name) to post s−>srvfd + as /srv/name.
+ Fork a child process via rfork(3) or procrfork (see thread(3)), + using the RFFDG, RFNAMEG, and RFMEM flags. The child process calls + close(s->srvfd) and then srv(s); it will exit once srv returns.
+ If mtpt is non-nil, call amount(s−>srvfd, mtpt, flag, ""); otherwise, + close s−>srvfd.
+ The parent returns to the caller. +
+ + +
+ If any error occurs during this process, the entire process is + terminated by calling sysfatal(3).
+

Service functions
+ The functions in a Srv structure named after 9P transactions are + called to satisfy requests as they arrive. If a function is provided, + it must arrange for respond to be called when the request is satisfied. + The only parameter of each service function is a Req* parameter + (say r). The incoming request parameters are + stored in r−>ifcall; r−>fid and r−>newfid are pointers to Fid structures + corresponding to the numeric fids in r−>ifcall; similarly, r−>oldreq + is the Req structure corresponding to r−>ifcall.oldtag. The outgoing + response data should be stored in r−>ofcall. The one exception + to this rule is that stat should fill in + r−>d rather than r−>ofcall.stat: the library will convert the structure + into the machine-independent wire representation. Similarly, wstat + may consult r−>d rather than decoding r−>ifcall.stat itself. When + a request has been handled, respond should be called with 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 + respond, as long as it has arranged for respond to be called at + some point in the future by another proc sharing its address space, + but see the discussion of flush below. Once respond has been + called, the Req* as well as any pointers it once contained must + be considered freed and not referenced. +
+ + 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. +
+ + The service loop provided by srv (and indirectly by postmountsrv + and threadpostmountsrv) is single-threaded. If it is expected + that some requests might block, arranging for alternate processes + to handle them is suggested. +
+ + 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, srv will call + endsrv and then abort.
+ Auth   If authentication is desired, the auth function should record + that afid is the new authentication fid and set afid->qid and ofcall.qid. + Auth may be nil, in which case it will be treated as having responded + with the error “argv0: authentication not required,” where argv0 + is the program name variable as set by + +
+ + ARGBEGIN (see arg(3)).
+ +
+ AttachThe attach function should check the authentication state + of afid if desired, and set r−>fid−>qid and ofcall.qid to the qid + of the file system root. 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. + Walk   If file trees are in use, walk is handled internally, and + srv−>walk is never called.
+ +
+ + If file trees are not in use, walk should consult r−>ifcall.wname + and r−>ifcall.nwname, filling in ofcall.qid and ofcall.nqid, and + also copying any necessary aux state from r−>fid to r−>newfid when + the two are different. As long as walk sets ofcall.nqid appropriately, + it can respond with a nil error string + even when 9P demands an error (e.g., in the case of a short walk); + the library detects error conditions and handles them appropriately.
+ Because implementing the full walk message is intricate and prone + to error, the helper routine walkandclone will handle the request + given pointers to two functions walk1 and (optionally) clone . + Clone, if non-nil, is called to signal the creation of newfid + from oldfid. Typically a clone routine will copy or increment + a reference count in oldfid’s aux element. Walk1 should walk fid + to name, initializing fid−>qid to the new path’s qid. Both should + return nil on success or an error message on error. Walkandclone + will call respond after handling the request.
+ +
+ Walk1, Clone
+ +
+ + If the client provides functions srv−>walk1 and (optionally) srv−>clone, + the 9P service loop will call walkandclone with these functions + to handle the request. Unlike the walk1 above, srv−>walk1 must + fill in both fid−>qid and *qid with the new qid on a successful + walk.
+ +
+ 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. +
+ + If not using file trees or the user has the appropriate permissions, + open is called with r−>ofcall.qid already initialized to the one + stored in the Fid structure (that is, the one returned in the + previous walk). If the qid changes, both should be updated.
+ CreateThe create function must fill in both r−>fid−>qid and r−>ofcall.qid + on success. When using file trees, create should allocate a new + File with createfile; note that createfile may return nil (because, + say, the file already exists). If the create function is nil, + srv behaves as though it were a function that always + +
+ + responded with the error “create prohibited”.
+ +
+ Remove
+ +
+ + Remove +
+ +
+ + should mark the file as removed, whether by calling removefile + when using file trees, or by updating an internal data structure. + In general it is not a good idea to clean up the aux information + associated with the corresponding File at this time, to avoid + memory errors if other fids have references to that + file. Instead, it is suggested that 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 aux pointer. If not using file trees, it is prudent to take + the analogous measures. If remove is not provided, all remove + requests will draw “remove prohibited” errors.
+ +
+ Read   The read function must be provided; it fills r−>ofcall.data + with at most r−>ifcall.count bytes of data from offset r−>ifcall.offset + of the file. It also sets r−>ofcall.count to the number of bytes + being returned. If using file trees, srv will handle reads of + directories internally, only calling read for requests on + +
+ + files. Readstr and readbuf are useful for satisfying read requests + on a string or buffer. Consulting the request in r−>ifcall, they + fill r−>ofcall.data and set r−>ofcall.count; they do not call respond. + Similarly, dirread9p can be used to handle directory reads in + servers not using file trees. The passed gen + function will be called as necessary to fill dir with information + for the nth entry in the directory. The string pointers placed + in dir should be fresh copies made with estrdup9p; they will be + freed by dirread9p after each successful call to gen. Gen should + return zero if it successfully filled dir, minus one on end of + directory.
+ +
+ WriteThe write function is similar but need not be provided. If + it is not, all writes will draw “write prohibited” errors. Otherwise, + write should attempt to write the r−>ifcall.count bytes of r−>ifcall.data + to offset r−>ifcall.offset of the file, setting r−>ofcall.count + to the number of bytes actually written. Most + +
+ + programs consider it an error to write less than the requested + amount.
+ +
+ Stat   Stat should fill r−>d with the stat information for r−>fid. + If using file trees, r−>d will have been initialized with the stat + info from the tree, and stat itself may be nil.
+ WstatThe wstat consults r−>d in changing the metadata for r−>fid + as described in stat(9p). When using file trees, srv will take + care to check that the request satisfies the permissions outlined + in stat(9p). Otherwise wstat should take care to enforce permissions + where appropriate.
+ Flush   Single-threaded servers, which always call respond before + returning from the service functions, need not provide a flush + implementation: flush is only necessary in multithreaded programs, + which arrange for respond to be called asynchronously. Flush should + cause the request r−>oldreq to be cancelled or + +
+ + hurried along. If oldreq is cancelled, this should be signalled + by calling respond on oldreq with error string ‘interrupted’. + Flush must respond to r with a nil error string. Flush may respond + to r before forcing a response to r−>oldreq. In this case, the + library will delay sending the Rflush message until the + response to r−>oldreq has been sent. +
+ + +
+ Destroyfid, destroyreq, and end are auxiliary functions, not called + in direct response to 9P requests.
+ Destroyfid
+ +
+ + When a Fid’s reference count drops to zero (i.e., it has been + clunked and there are no outstanding requests referring to it), + destroyfid is called to allow the program to dispose of the fid−>aux + pointer.
+ +
+ Destroyreq
+ +
+ + Similarly, when a Req’s reference count drops to zero (i.e., it + has been handled via respond and other outstanding pointers to + it have been closed), destroyreq is called to allow the program + to dispose of the r−>aux pointer.
+ +
+ End    Once the 9P service loop has finished (end of file been reached + on the service pipe or a bad message has been read), 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 end, the service + loop (which runs in a separate process from its caller) terminates + using _exits (see exits(3)). +
+ + +
+ If the chatty9p flag is at least one, a transcript of the 9P session + is printed on standard error. If the chatty9p flag is greater + than one, additional unspecified debugging output is generated. + By convention, servers written using this library accept the −D + option to increment chatty9p. + +

+

EXAMPLES
+ +
+ + /usr/local/plan9/src/lib9p/ramfs.c is an example of a simple single-threaded + file server. On Plan 9, see archfs, cdfs, nntpfs, webfs, and sshnet + for more examples. +
+ + In general, the File interface is appropriate for maintaining + arbitrary file trees (as in ramfs). The 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 cdfs and + nntpfs) or is maintained elsewhere.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p
+ +
+

SEE ALSO
+ +
+ + 9p-fid(3), 9p-file(3), intro(9p)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/9pclient.html b/man/man3/9pclient.html new file mode 100644 index 00000000..4ae50c21 --- /dev/null +++ b/man/man3/9pclient.html @@ -0,0 +1,250 @@ + +9pclient(3) - Plan 9 from User Space + + + + +
+
+
9PCLIENT(3)9PCLIENT(3) +
+
+

NAME
+ +
+ + CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, + fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, + fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, + fspread, fspwrite, fsread, fsreadn, fswrite – 9P client library
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + #include <fcall.h> +
+ + #include <9pclient.h> +
+ + CFsys* fsmount(int fd, char *aname) +
+ + CFsys* nsmount(char *name, char *aname) +
+ + CFid*    fsroot(CFsys *fsys) +
+ + void     fsunmount(CFsys *fsys) +
+ + CFsys* fsinit(int fd) +
+ + int      fsversion(CFsys *fsys, int msize, char *version, int nversion) + +
+ + CFid     *fsauth(CFsys *fsys, char *uname, char *aname) +
+ + CFid     *fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname) + +
+ + void     fssetroot(CFsys *fsys, CFid *fid) +
+ + void     fsclose(CFid *fid) +
+ + CFid     *fscreate(CFsys *fs, char *path, int mode, ulong perm) +
+ + CFid*    fsopen(CFsys *fs, char *path, int mode) +
+ + long     fspread(CFid *fid, void *buf, long n, vlong offset) +
+ + long     fspwrite(CFid *fid, void *buf, long n, vlong offset) +
+ + long     fsread(CFid *fid, void *buf, long n) +
+ + long     fsreadn(CFid *fid, void *buf, long n) +
+ + long     fswrite(CFid *fid, void *buf, long n) +
+ + long     fsdirread(CFid *fid, Dir **d) +
+ + long     fsdirreadall(CFid *fid, Dir **d) +
+ + Dir*     fsdirstat(CFsys *fs, char *path) +
+ + Dir*     fsdirfstat(CFid *fid) +
+ + int      fsdirwstat(CFsys *fs, char *path, Dir *d) +
+ + int      fsdirfwstat(CFid *fid, Dir *d) +
+ + int      fsopenfd(CFsys *fs, char *path, int mode)
+ +
+

DESCRIPTION
+ +
+ + The 9pclient library helps client programs interact with 9P servers. + +
+ + A CFsys* represents a connection to a 9P server. A CFid* represents + an active fid on some connection; see intro(9p). +
+ + A new connection to a 9P server is typically established by fsmount + or nsmount. Fsmount initializes a new 9P conversation on the open + file descriptor fd; nsmount connects to a service named name in + the current name space directory (see intro(4)). Both attach to + the root of the file system using the attach name aname. + Fsroot returns the CFid* corresponding to this root. +
+ + Fsinit, fsversion, fsauth, fsattach, and fssetroot provide more + detailed control over the file system connection than fsmount + and nsmount. Fsinit allocates a new CFsys* corresponding to a + 9P conversation on the file descriptor fd. Fsversion executes + a version(9p) transaction to establish maximum message size and + 9P + version. Fsauth executes an auth(9p) transaction, returning the + new auth fid. (Fsread and fswrite can then be used to run the + authentication protocol over the fid.) Fsattach executes an attach(9p) + transaction to connect to the root of a file tree served by the + server. It presents afid (which may be nil) to establish + identity. Fssetroot sets the root fid used by fsopen, fsopenfd, + fsdirstat, and fsdirwstat, which evaluate rooted path names. +
+ + When a fid is no longer needed, it should be clunked by calling + fsclose and then considered freed. Similarly, when the connection + to the server is no longer needed, it should be closed by calling + fsunmount, which will take care of calling fsclose on the current + root fid. Once all fids have been clunked and the connection + has been closed (the order is not important), the allocated structures + will be freed and the file descriptor corresponding to the connection + will be closed (see close(2)). Fids are not reference counted: + when fsclose is called, the clunk transaction and freeing of storage + happen immediately. +
+ + Fscreate and fsopen establish new fids using the walk, create + and open transactions (see walk(9p) and open(9p)). The path argument + is evaluated relative to the CFsys root (see fsroot and fssetroot + above). The path is parsed as a slash-separated sequence of path + elements, as on Unix and Plan 9. Elements that are + empty or dot (.) are ignored. +
+ + Once opened, these fids can be read and written using fspread + and fspwrite, which execute read and write transactions (see read(9p)). + The library maintains an offset for each fid, analagous to the + offset maintained by the kernel for each open file descriptor. + Fsread and fswrite read and write from this offset, and + update it after successful calls. Calling fspread or fspwrite + with an offset of –1 is identical to calling fsread or fswrite. + Fsreadn calls fsread repeatedly to obtain exactly n bytes of data, + unless it encounters end-of-file or an error. +
+ + Reading an open a directory returns directory entries encoded + as described in stat(9p). Fsdirread calls fsread and then parses + the encoded entries into an array of Dir* data structures, storing + a pointer to the array in *d and returning the number of entries. + Fsdirreadall is similar but reads the entire directory. The + returned pointer should be freed with free (see malloc(3)) when + no longer needed. +
+ + Fsdirfstat and fsdirfwstat execute stat and wstat (see stat(9p)) + transactions. The Dir structure returned by fsdirfstat should + be freed with free (see malloc(3)) when no longer needed. +
+ + Fsdirstat and fsdirwstat are similar to fsdirfstat and fsdirfwstat + but operate on paths relative to the file system root (see fsopen + and fscreate above). +
+ + Fsopenfd opens a file on the 9P server for reading or writing + but returns a Unix file descriptor instead of a fid structure. + The file descriptor is actually one end of a pipe(2). A proxy + process on the other end is ferrying data between the pipe and + the 9P fid. Because of the implementation as a pipe, the only + signal of a + read or write error is the closing of the pipe. The file descriptor + remains valid even after the CFsys is unmounted.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9pclient
+ +
+

SEE ALSO
+ +
+ + intro(4), intro(9p)
+ +
+

BUGS
+ +
+ + The implementation should use a special version string to distinguish + between servers that support openfd(9p) and servers that do not. + +
+ + The interface does not provide access to the walk(9p) transaction, + or to open and create on already-established fids. +
+ + There is no fsseek.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/addpt.html b/man/man3/addpt.html new file mode 100644 index 00000000..1c327aaa --- /dev/null +++ b/man/man3/addpt.html @@ -0,0 +1,174 @@ + +addpt(3) - Plan 9 from User Space + + + + +
+
+
ADDPT(3)ADDPT(3) +
+
+

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
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h> +
+ + Point       addpt(Point p, Point q) +
+ + Point       subpt(Point p, Point q) +
+ + Point       mulpt(Point p, int a) +
+ + Point       divpt(Point p, int a) +
+ + Rectangle rectaddpt(Rectangle r, Point p) +
+ + Rectangle rectsubpt(Rectangle r, Point p) +
+ + Rectangle insetrect(Rectangle r, int n) +
+ + Rectangle canonrect(Rectangle r) +
+ + int         eqpt(Point p, Point q) +
+ + int         eqrect(Rectangle r, Rectangle s) +
+ + int         ptinrect(Point p, Rectangle r) +
+ + int         rectinrect(Rectangle r, Rectangle s) +
+ + int         rectXrect(Rectangle r, Rectangle s) +
+ + int         rectclip(Rectangle *rp, Rectangle b) +
+ + void        combinerect(Rectangle *rp, Rectangle b) +
+ + int         Dx(Rectangle r) +
+ + int         Dy(Rectangle r) +
+ + Point       Pt(int x, int y) +
+ + Rectangle Rect(int x0, int y0, int x1, int y1) +
+ + Rectangle Rpt(Point p, Point q)
+ +
+

DESCRIPTION
+ +
+ + The functions Pt, Rect and Rpt construct geometrical data types + from their components. +
+ + Addpt returns the Point sum of its arguments: Pt(p.x+q.x, p.y+q.y). + Subpt returns the Point difference of its arguments: Pt(p.x−q.x, + p.y−q.y). Mulpt returns the Point Pt(p.x*a, p.y*a). Divpt returns + the Point Pt(p.x/a, p.y/a). +
+ + Rectaddpt returns the Rectangle Rect(add(r.min, p), add(r.max, + p)); rectsubpt returns the Rectangle Rpt(sub(r.min, p), sub(r.max, + p)). +
+ + Insetrect returns the Rectangle Rect(r.min.x+n, r.min.y+n, r.max.x−n, + r.max.y−n). +
+ + Canonrect returns a rectangle with the same extent as r, canonicalized + so that min.x ≤ max.x, and min.y ≤ max.y. +
+ + Eqpt compares its argument Points and returns 0 if unequal, 1 + if equal. Eqrect does the same for its argument Rectangles. +
+ + Ptinrect returns 1 if p is a point within r, and 0 otherwise. + +
+ + Rectinrect returns 1 if all the pixels in r are also in s, and + 0 otherwise. +
+ + RectXrect returns 1 if r and s share any point, and 0 otherwise. + +
+ + Rectclip clips in place the Rectangle pointed to by rp so that + it is completely contained within b. The return value is 1 if + any part of *rp is within b. Otherwise, the return value is 0 + and *rp is unchanged. +
+ + Combinerect overwrites *rp with the smallest rectangle sufficient + to cover all the pixels of *rp and b. +
+ + The functions Dx and Dy give the width (Δx) and height (Δy) of + a Rectangle. They are implemented as macros.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/aes.html b/man/man3/aes.html new file mode 100644 index 00000000..1a455c2f --- /dev/null +++ b/man/man3/aes.html @@ -0,0 +1,85 @@ + +aes(3) - Plan 9 from User Space + + + + +
+
+
AES(3)AES(3) +
+
+

NAME
+ +
+ + setupAESstate, aesCBCencrypt, aesCBCdecrypt - advanced encryption + standard (rijndael)
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void setupAESstate(AESstate *s, uchar key[], int keybytes, uchar + *ivec) +
+ + void aesCBCencrypt(uchar*, int, AESstate*) +
+ + void aesCBCdecrypt(uchar*, int, AESstate*) +
+ + +
+

DESCRIPTION
+ +
+ + +
+ + DES is being replaced by Rijndael, also known as AES, as the preferred + block ciper. setupAESstate, aesCBCencrypt, and aesCBCdecrypt implement + cipher block chaining encryption. Keybytes should be 16, 24, or + 32. The initialization vector ivec of AESbsize bytes should random + enough to be unlikely to be reused but + does not need to be cryptographically strongly unpredictable.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), blowfish(3), des(3), dsa(3), elgamal(3), rc4(3), rsa(3), + sechash(3), prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/allocimage.html b/man/man3/allocimage.html new file mode 100644 index 00000000..d36fb0eb --- /dev/null +++ b/man/man3/allocimage.html @@ -0,0 +1,321 @@ + +allocimage(3) - Plan 9 from User Space + + + + +
+
+
ALLOCIMAGE(3)ALLOCIMAGE(3) +
+
+

NAME
+ +
+ + allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, + loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, + wordsperline – allocating, freeing, reading, writing images
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ +
+ + Image *allocimage(Display *d, Rectangle r,
+ +
+ + +
+ + ulong chan, int repl, int col)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ Image *allocimagemix(Display *d, ulong one, ulong three)
+ +
+ + void    freeimage(Image *i)
+ +
+ + int     nameimage(Image *i, char *name, int in)
+ +
+ + Image *namedimage(Display *d, char *name)
+ +
+ + ulong setalpha(ulong color, uchar alpha)
+ +
+ + int     loadimage(Image *i, Rectangle r, uchar *data, int ndata)
+ +
+ + int     cloadimage(Image *i, Rectangle r, uchar *data, int ndata)
+ +
+ + int     unloadimage(Image *i, Rectangle r, uchar *data, int ndata)
+ +
+ + Image *readimage(Display *d, int fd, int dolock)
+ +
+ + int     writeimage(int fd, Image *i, int dolock)
+ +
+ + int     bytesperline(Rectangle r, int d)
+ +
+ + int     wordsperline(Rectangle r, int d)
+ +
+ + enum
+ {
+ +
+ + 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,
+
+ +
+ };
+ +
+

DESCRIPTION
+ +
+ + A new Image on Display d is allocated with allocimage; it will + have the rectangle, pixel channel format, and replication flag + given by its arguments. Convenient pixel channels like GREY1, + GREY2, CMAP8, RGB16, RGB24, and RGBA32 are predefined. All the + new image’s pixels will have initial value col. If col + is DNofill, no initialization is done. Representative useful values + of color are predefined: DBlack, DWhite, 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 id field will have been set to the identifying + number used by /dev/draw (see draw(3)), and the cache field will + be zero. If repl is true, the clip rectangle is set to a very + large region; if false, it is set to r. The depth field will be + set to the + number of bits per pixel specified by the channel descriptor (see + image(7)). Allocimage returns 0 if the server has run out of image + memory. +
+ + Allocimagemix is used to allocate background colors. On 8-bit + color-mapped displays, it returns a 2x2 replicated image with one + pixel colored the color one and the other three with 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 1x1 replicated image whose pixel is the + result of mixing the two colors in a one to three ratio. +
+ + Freeimage frees the resources used by its argument image. +
+ + Nameimage publishes in the server the image i under the given + name. If in is non-zero, the image is published; otherwise i must + be already named name and it is withdrawn from publication. Namedimage + returns a reference to the image published under the given name + on Display d. These routines permit + unrelated applications sharing a display to share an image; for + example they provide the mechanism behind getwindow (see graphics(3)). + +
+ + The RGB values in a color are premultiplied by the alpha value; + for example, a 50% red is 0x7F00007F not 0xFF00007F. The function + setalpha performs the alpha computation on a given color, ignoring + its initial alpha value, multiplying the components by the supplied + alpha. For example, to make a 50% red + color value, one could execute setalpha(DRed, 0x7F). +
+ + 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 image(7)). + +
+ + Unloadimage reads a rectangle of pixels from image i into data, + whose length is specified by ndata. It is an error if ndata is + too small to accommodate the pixels. +
+ + Loadimage replaces the specified rectangle in image i with the + ndata bytes of data. +
+ + The pixels are presented one horizontal line at a time, starting + with the top-left pixel of 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 data, regardless + of + the rectangle being extracted. Bytes are filled from most to least + significant bit order, as the x coordinate increases, aligned + so x=0 would appear as the leftmost pixel of its byte. Thus, for + depth 1, the pixel at x offset 165 within the rectangle will be + in a data byte at bit-position 0x04 regardless of the overall + rectangle: 165 mod 8 equals 5, and 0x80 >> 5 equals 0x04. +
+ + Cloadimage does the same as loadimage, but for ndata bytes of + compressed image data (see image(7)). On each call to cloadimage, + the data must be at the beginning of a compressed data block, + in particular, it should start with the y coordinate and data + length for the block. +
+ + Loadimage, cloadimage, and unloadimage return the number of bytes + copied. +
+ + Readimage creates an image from data contained in an external + file (see image(7) for the file format); fd is a file descriptor + obtained by opening such a file for reading. The returned image + is allocated using allocimage. The dolock flag specifies whether + the Display should be synchronized for multithreaded access; + single-threaded programs can leave it zero. +
+ + Writeimage writes image i onto file descriptor fd, which should + be open for writing. The format is as described for readimage. + +
+ + Readimage and writeimage do not close fd. +
+ + Bytesperline and wordsperline return the number of bytes or words + occupied in memory by one scan line of rectangle r in an image + with d bits per pixel.
+ +
+

EXAMPLE
+ +
+ + To allocate a single-pixel replicated image that may be used to + paint a region red,
+ +
+ + red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), draw(3), image(7)
+ +
+

DIAGNOSTICS
+ +
+ + These functions return pointer 0 or integer –1 on failure, usually + due to insufficient memory. +
+ + May set errstr.
+ +
+

BUGS
+ +
+ + Depth must be a divisor or multiple of 8.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/arg.html b/man/man3/arg.html new file mode 100644 index 00000000..8ca66c80 --- /dev/null +++ b/man/man3/arg.html @@ -0,0 +1,152 @@ + +arg(3) - Plan 9 from User Space + + + + +
+
+
ARG(3)ARG(3) +
+
+

NAME
+ +
+ + ARGBEGIN, ARGEND, ARGC, ARGF, EARGF, arginit, argopt – process + option letters from argv
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + ARGBEGIN {
+ char *ARGF();
+ char *EARGF(code);
+ Rune ARGC();
+ } ARGEND
+ +
+ + extern char *argv0;
+ +
+

DESCRIPTION
+ +
+ + These macros assume the names argc and argv are in scope; see + exec(3). ARGBEGIN and 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 −−, before an argument −, or + before an argument that doesn’t begin with −. +
+ + The function macro ARGC returns the current option character, + as an integer. +
+ + The function macro ARGF returns the current option argument: a + pointer to the rest of the option string if not empty, or the + next argument in argv if any, or 0. ARGF must be called just once + for each option that takes an argument. The macro EARGF is like + ARGF but instead of returning zero runs code and, if that + returns, calls abort(3). A typical value for code is usage(), + as in EARGF(usage()). +
+ + After ARGBEGIN, argv0 is a copy of argv[0] (conventionally the + name of the program). +
+ + After ARGEND, argv points at a zero-terminated list of the remaining + argc arguments.
+ +
+

EXAMPLE
+ +
+ + This C program can take option b and option f, which requires + an argument.
+ +
+ + #include <u.h>
+ #include <libc.h>
+ 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("\n");
+ exits(nil);
+ +
+ }
+ +
+ + +
+ Here is the output from running the command prog −bffile1 −r −f + file2 arg1 arg2
+ +
+ + prog −b −f(file1) badflag('r') −f(file2) 2 args: 'arg1' 'arg2' + +
+ +
+ +
+ + + +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/include/libc.h
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/arith3.html b/man/man3/arith3.html new file mode 100644 index 00000000..71cf815c --- /dev/null +++ b/man/man3/arith3.html @@ -0,0 +1,216 @@ + +arith3(3) - Plan 9 from User Space + + + + +
+
+
ARITH3(3)ARITH3(3) +
+
+

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
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <draw.h> +
+ + #include <geometry.h> +
+ + Point3 add3(Point3 a, Point3 b) +
+ + Point3 sub3(Point3 a, Point3 b) +
+ + Point3 neg3(Point3 a) +
+ + Point3 div3(Point3 a, double b) +
+ + Point3 mul3(Point3 a, double b) +
+ + int eqpt3(Point3 p, Point3 q) +
+ + int closept3(Point3 p, Point3 q, double eps) +
+ + double dot3(Point3 p, Point3 q) +
+ + Point3 cross3(Point3 p, Point3 q) +
+ + double len3(Point3 p) +
+ + double dist3(Point3 p, Point3 q) +
+ + Point3 unit3(Point3 p) +
+ + Point3 midpt3(Point3 p, Point3 q) +
+ + Point3 lerp3(Point3 p, Point3 q, double alpha) +
+ + Point3 reflect3(Point3 p, Point3 p0, Point3 p1) +
+ + Point3 nearseg3(Point3 p0, Point3 p1, Point3 testp) +
+ + double pldist3(Point3 p, Point3 p0, Point3 p1) +
+ + double vdiv3(Point3 a, Point3 b) +
+ + Point3 vrem3(Point3 a, Point3 b) +
+ + Point3 pn2f3(Point3 p, Point3 n) +
+ + Point3 ppp2f3(Point3 p0, Point3 p1, Point3 p2) +
+ + Point3 fff2p3(Point3 f0, Point3 f1, Point3 f2) +
+ + Point3 pdiv4(Point3 a) +
+ + Point3 add4(Point3 a, Point3 b) +
+ + Point3 sub4(Point3 a, Point3 b)
+ +
+

DESCRIPTION
+ +
+ + These routines do arithmetic on points and planes in affine or + projective 3-space. Type Point3 is
+ +
+ + typedef struct Point3 Point3;
+ struct Point3{
+ +
+ + double x, y, z, w;
+ +
+ };
+ +
+ + +
+ Routines whose names end in 3 operate on vectors or ordinary points + in affine 3-space, represented by their Euclidean (x,y,z) coordinates. + (They assume w=1 in their arguments, and set w=1 in their results.)
+ Name       Description
+ add3       Add the coordinates of two points.
+ sub3       Subtract coordinates of two points.
+ neg3       Negate the coordinates of a point.
+ mul3       Multiply coordinates by a scalar.
+ div3       Divide coordinates by a scalar.
+ eqpt3      Test two points for exact equality.
+ closept3   Is the distance between two points smaller than eps?
+ dot3       Dot product.
+ cross3     Cross product.
+ len3       Distance to the origin.
+ dist3      Distance between two points.
+ unit3      A unit vector parallel to p.
+ midpt3     The midpoint of line segment pq.
+ lerp3      Linear interpolation between p and q.
+ reflect3   The reflection of point p in the segment joining p0 and + p1.
+ nearseg3   The closest point to testp on segment p0 p1.
+ pldist3    The distance from p to segment p0 p1.
+ vdiv3      Vector divide -- the length of the component of a parallel + to b, in units of the length of b.
+ vrem3      Vector remainder -- the component of a perpendicular to b. + Ignoring roundoff, we have eqpt3(add3(mul3(b, vdiv3(a, b)), vrem3(a, + b)), a). +
+ + The following routines convert amongst various representations + of points and planes. Planes are represented identically to points, + by duality; a point p is on a plane q whenever 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 p.w=1, we can’t + make the same + assumption for planes. The names of these routines are extra-cryptic. + They contain an f (for ‘face’) to indicate a plane, p for a point + and n for a normal vector. The number 2 abbreviates the word ‘to.’ + The number 3 reminds us, as before, that we’re dealing with affine + points. Thus pn2f3 takes a point and a normal + vector and returns the corresponding plane.
+ Name       Description
+ pn2f3      Compute the plane passing through p with normal n.
+ ppp2f3     Compute the plane passing through three points.
+ fff2p3     Compute the intersection point of three planes. +
+ + The names of the following routines end in 4 because they operate + on points in projective 4-space, represented by their homogeneous + coordinates.
+ pdiv4Perspective division. Divide p.w into p’s coordinates, converting + to affine coordinates. If p.w is zero, the result is the same + as the argument.
+ add4   Add the coordinates of two points.
+ sub4   Subtract the coordinates of two points.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libgeometry
+ +
+

SEE ALSO
+ +
+ + matrix(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/atof.html b/man/man3/atof.html new file mode 100644 index 00000000..ef464d0a --- /dev/null +++ b/man/man3/atof.html @@ -0,0 +1,170 @@ + +atof(3) - Plan 9 from User Space + + + + +
+
+
ATOF(3)ATOF(3) +
+
+

NAME
+ +
+ + atof, atoi, atol, atoll, charstod, strtod, strtol, strtoll, strtoul, + strtoull – convert text to numbers
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + double atof(char *nptr)
+ +
+ + int      atoi(char *nptr)
+ +
+ + long     atol(char *nptr)
+ +
+ + vlong    atoll(char *nptr)
+ +
+ + double charstod(int (*f)(void *), void *a)
+ +
+ + double strtod(char *nptr, char **rptr)
+ +
+ + long     strtol(char *nptr, char **rptr, int base)
+ +
+ + vlong    strtoll(char *nptr, char **rptr, int base)
+ +
+ + ulong    strtoul(char *nptr, char **rptr, int base)
+ +
+ + vlong    strtoull(char *nptr, char **rptr, int base)
+ +
+

DESCRIPTION
+ +
+ + Atof, atoi, atol, and atoll convert a string pointed to by nptr + to floating, integer, long integer, and long long integer (vlong) + representation respectively. The first unrecognized character + ends the string. Leading C escapes are understood, as in strtol + with base zero (described below). +
+ + 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 e or E followed by an optionally + signed integer. +
+ + Atoi and atol recognize an optional string of tabs and spaces, + then an optional sign, then a string of decimal digits. +
+ + Strtod, strtol, strtoll, strtoul, and strtoull behave similarly + to atof and atol and, if rptr is not zero, set *rptr to point + to the input character immediately after the string converted. + +
+ + Strtol, strtoll, strtoul, and strtoull interpret the digit string + in the specified 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 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 0, hexadecimal if they begin with 0x + or 0X, otherwise decimal. +
+ + Charstod interprets floating point numbers in the manner of atof, + but gets successive characters by calling (*f)(a). The last call + to 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 charstod.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + fscanf(3)
+ +
+

DIAGNOSTICS
+ +
+ + Zero is returned if the beginning of the input string is not interpretable + as a number; even in this case, rptr will be updated.
+ These routines set errstr.
+ +
+

BUGS
+ +
+ + Atoi and atol accept octal and hexadecimal numbers in the style + of C, contrary to the ANSI specification. +
+ + Atof, strtod, strtol, strtoul, strtoll, and strtoull are not provided: + they are expected to be provided by the underlying system. +
+ + Because they are implemented in the fmt library, charstod and + strtod are preprocessor macros defined as fmtcharstod and fmtstrtod. + +
+ + To avoid name conflicts with the underlying system, atoi, atol, + and atoll are preprocessor macros defined as p9atoi, p9atol, and + p9atoll; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/bin.html b/man/man3/bin.html new file mode 100644 index 00000000..f016622f --- /dev/null +++ b/man/man3/bin.html @@ -0,0 +1,131 @@ + +bin(3) - Plan 9 from User Space + + + + +
+
+
BIN(3)BIN(3) +
+
+

NAME
+ +
+ + binalloc, bingrow, binfree – grouped memory allocation
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <bin.h> +
+ + +
+ + typedef struct BinBin; +
+ + void    *binalloc(Bin **bp, ulong size, int clr); +
+ + void    *bingrow(Bin **bp, void *op, ulong osize,
+ +
+ + +
+ + ulong size, int clr); +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void    binfree(Bin **bp);
+ +
+

DESCRIPTION
+ +
+ + These routines provide simple grouped memory allocation and deallocation. + Items allocated with binalloc are added to the Bin pointed to + by bp. All items in a bin may be freed with one call to binfree; + there is no way to free a single item. +
+ + Binalloc returns a pointer to a new block of at least size bytes. + The block is suitably aligned for storage of any type of object. + No two active pointers from binalloc will have the same value. + The call binalloc(0) returns a valid pointer rather than null. + If clr is non-zero, the allocated memory is set to 0; otherwise, + the contents are undefined. +
+ + Bingrow is used to extend the size of a block of memory returned + by binalloc. Bp must point to the same bin group used to allocate + the original block, and osize must be the last size used to allocate + or grow the block. A pointer to a block of at least size bytes + is returned, with the same contents in the first osize + locations. If clr is non-zero, the remaining bytes are set to + 0, and are undefined otherwise. If op is nil, it and osize are + ignored, and the result is the same as calling binalloc. +
+ + Binalloc and bingrow allocate large chunks of memory using malloc(3) + and return pieces of these chunks. The chunks are free’d upon + a call to binfree.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libbin
+ +
+

SEE ALSO
+ +
+ + malloc(3)
+ +
+

DIAGNOSTICS
+ +
+ + binalloc and bingrow return 0 if there is no available memory.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/bio.html b/man/man3/bio.html new file mode 100644 index 00000000..78259922 --- /dev/null +++ b/man/man3/bio.html @@ -0,0 +1,293 @@ + +bio(3) - Plan 9 from User Space + + + + +
+
+
BIO(3)BIO(3) +
+
+

NAME
+ +
+ + Bopen, Bfdopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, + Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, + Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered + – buffered input/output
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <bio.h> +
+ + Biobuf* Bopen(char *file, int mode) +
+ + Biobuf* Bfdopen(int fd, int mode) +
+ + int       Binit(Biobuf *bp, int fd, int mode) +
+ + int       Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size) + +
+ + int       Bterm(Biobufhdr *bp) +
+ + int       Bprint(Biobufhdr *bp, char *format, ...) +
+ + int       Bvprint(Biobufhdr *bp, char *format, va_list arglist); +
+ + void*     Brdline(Biobufhdr *bp, int delim) +
+ + char*     Brdstr(Biobufhdr *bp, int delim, int nulldelim) +
+ + int       Blinelen(Biobufhdr *bp) +
+ + vlong     Boffset(Biobufhdr *bp) +
+ + int       Bfildes(Biobufhdr *bp) +
+ + int       Bgetc(Biobufhdr *bp) +
+ + long      Bgetrune(Biobufhdr *bp) +
+ + int       Bgetd(Biobufhdr *bp, double *d) +
+ + int       Bungetc(Biobufhdr *bp) +
+ + int       Bungetrune(Biobufhdr *bp) +
+ + vlong     Bseek(Biobufhdr *bp, vlong n, int type) +
+ + int       Bputc(Biobufhdr *bp, int c) +
+ + int       Bputrune(Biobufhdr *bp, long c) +
+ + long      Bread(Biobufhdr *bp, void *addr, long nbytes) +
+ + long      Bwrite(Biobufhdr *bp, void *addr, long nbytes) +
+ + int       Bflush(Biobufhdr *bp) +
+ + int       Bbuffered(Biobufhdr *bp) +
+ + +
+

DESCRIPTION
+ +
+ + These routines implement fast buffered I/O. I/O on different file + descriptors is independent. +
+ + Bopen opens file for mode OREAD or creates for mode OWRITE. It + calls malloc(3) to allocate a buffer. +
+ + Bfdopen allocates a buffer for the already-open file descriptor + fd for mode OREAD or OWRITE. It calls malloc(3) to allocate a + buffer. +
+ + Binit initializes a standard size buffer, type Biobuf, with the + open file descriptor passed in by the user. Binits initializes + a non-standard size buffer, type Biobufhdr, with the open file + descriptor, buffer area, and buffer size passed in by the user. + Biobuf and Biobufhdr are related by the declaration: + +
+ + typedef struct Biobuf Biobuf;
+ struct Biobuf
+ {
+ +
+ + Biobufhdr;
+ uchar b[Bungetsize+Bsize];
+ +
+ };
+ +
+ + +
+ Arguments of types pointer to Biobuf and pointer to Biobufhdr + can be used interchangeably in the following routines. +
+ + Bopen, Binit, or Binits should be called before any of the other + routines on that buffer. Bfildes returns the integer file descriptor + of the associated open file. +
+ + Bterm flushes the buffer for bp. If the buffer was allocated by + Bopen, the buffer is freed and the file is closed. +
+ + Brdline reads a string from the file associated with bp up to + and including the first delim character. The delimiter character + at the end of the line is not altered. Brdline returns a pointer + to the start of the line or 0 on end-of-file or read error. Blinelen + returns the length (including the delimiter) of the most recent + string + returned by Brdline. +
+ + Brdstr returns a malloc(3)-allocated buffer containing the next + line of input delimited by delim, terminated by a NUL (0) byte. + Unlike Brdline, which returns when its buffer is full even if + no delimiter has been found, Brdstr will return an arbitrarily + long line in a single call. If nulldelim is set, the terminal + delimiter will be + overwritten with a NUL. After a successful call to Brdstr, the + return value of Blinelen will be the length of the returned buffer, + excluding the NUL. +
+ + Bgetc returns the next character from bp, or a negative value + at end of file. Bungetc may be called immediately after Bgetc + to allow the same character to be reread. +
+ + Bgetrune calls Bgetc to read the bytes of the next 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. Bungetrune + may be called immediately after Bgetrune to allow the same UTF + sequence to be reread as either bytes or a rune. + Bungetc and Bungetrune may back up a maximum of five bytes. +
+ + Bgetd uses charstod (see atof(3)) and Bgetc to read the formatted + floating-point number in the input stream, skipping initial blanks + and tabs. The value is stored in *d. +
+ + Bread reads nbytes of data from bp into memory starting at addr. + The number of bytes read is returned on success and a negative + value is returned if a read error occurred. +
+ + Bseek applies seek(3) to bp. It returns the new file offset. Boffset + returns the file offset of the next character to be processed. + +
+ + Bputc outputs the low order 8 bits of c on bp. If this causes + a write to occur and there is an error, a negative value is returned. + Otherwise, a zero is returned. +
+ + Bputrune calls Bputc to output the low order 16 bits of c as a + rune in UTF format on the output stream. +
+ + Bprint is a buffered interface to print(3). If this causes a write + to occur and there is an error, a negative value (Beof) is returned. + Otherwise, the number of bytes output is returned. Bvprint does + the same except it takes as argument a va_list parameter, so it + can be called within a variadic function. +
+ + Bwrite outputs nbytes of data starting at addr to bp. If this + causes a write to occur and there is an error, a negative value + is returned. Otherwise, the number of bytes written is returned. + +
+ + Bflush causes any buffered output associated with bp to be written. + The return is as for Bputc. Bflush is called on exit for every + buffer still open for writing. +
+ + 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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libbio
+ +
+

SEE ALSO
+ +
+ + open(3), print(3), exits(3), utf(7),
+ +
+

DIAGNOSTICS
+ +
+ + Bio routines that return integers yield Beof if bp is not the + descriptor of an open file. Bopen returns zero if the file cannot + be opened in the given mode. All routines set errstr on error.
+ +
+

BUGS
+ +
+ + 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. Blinelen will tell how many characters are available + in these cases. In the case of a true end-of-file, Blinelen will + return zero. At the cost of allocating a buffer, Brdstr sidesteps + these issues. +
+ + The data returned by Brdline may be overwritten by calls to any + other bio routine on the same bp.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/blowfish.html b/man/man3/blowfish.html new file mode 100644 index 00000000..d8da66de --- /dev/null +++ b/man/man3/blowfish.html @@ -0,0 +1,95 @@ + +blowfish(3) - Plan 9 from User Space + + + + +
+
+
BLOWFISH(3)BLOWFISH(3) +
+
+

NAME
+ +
+ + setupBFstate, bfCBCencrypt, bfCBCdecrypt, bfECBencrypt, bfECBdecrypt + - blowfish encryption
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void setupBFstate(BFstate *s, uchar key[], int keybytes,                  uchar + *ivec) +
+ + void bfCBCencrypt(uchar *data, int len, BFstate *s) +
+ + void bfCBCdecrypt(uchar *data, int len, BFstate *s) +
+ + void bfECBencrypt(uchar *data, int len, BFstate *s) +
+ + void bfECBdecrypt(uchar *data, int len, BFstate *s)
+ +
+

DESCRIPTION
+ +
+ + +
+ + 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. +
+ + 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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), des(3), dsa(3), elgamal(3), rc4(3), rsa(3), sechash(3), + prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/cachechars.html b/man/man3/cachechars.html new file mode 100644 index 00000000..382b5e7e --- /dev/null +++ b/man/man3/cachechars.html @@ -0,0 +1,292 @@ + +cachechars(3) - Plan 9 from User Space + + + + +
+
+
CACHECHARS(3)CACHECHARS(3) +
+
+

NAME
+ +
+ + cachechars, agefont, loadchar, Subfont, Fontchar, Font – font utilities
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h> +
+ + +
+ + int    cachechars(Font *f, char **s, Rune **r, ushort *c, int max, + +
+ + +
+ + +
+ + int *widp, char **sfname) +
+ + +
+ +
+ int    loadchar(Font *f, Rune r, Cacheinfo *c, int h, +
+ + +
+ + +
+ + int noclr, char **sfname) +
+ + +
+ +
+ void agefont(Font *f)
+ +
+

DESCRIPTION
+ +
+ + A Font may contain too many characters to hold in memory simultaneously. + The graphics library and draw device (see 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: initdraw and its associated + font variable, openfont, stringwidth, string, and freefont are + sufficient for most purposes. The routines described below are + used internally by the graphics library to maintain the font cache. + +
+ + A 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.
+ +
+ + 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;
+ +
+ + +
+ The image fills the rectangle (0, 0, w, height), where w is the + sum of the horizontal extents (of non-zero pixels) for all characters. + The pixels to be displayed for character c are in the rectangle + (i−>x, i−>top, (i+1)−>x, i−>bottom) where i is &subfont−>info[c]. When + a character is displayed + at Point p in an image, the character rectangle is placed at (p.x+i−>left, + p.y) and the next character of the string is displayed at (p.x+i−>width, + p.y). The baseline of the characters is ascent rows down from + the top of the subfont image. The info array has n+1 elements, + one each for characters 0 + to n−1 plus an additional entry so the size of the last character + can be calculated. Thus the width, w, of the Image associated + with a Subfont s is s−>info[s−>n].x. +
+ + A Font consists of an overall height and ascent and a collection + of subfonts together with the ranges of runes (see utf(7)) they + represent. Fonts are described by the following structures.
+ +
+ + 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;
+ +
+ + +
+ The height and ascent fields of Font are described in graphics(3). + Sub contains nsub pointers to Cachefonts. A Cachefont connects + runes min through max, inclusive, to the subfont with file name + name; it corresponds to a line of the file describing the font. + +
+ + The characters are taken from the subfont starting at character + number offset (usually zero) in the subfont, permitting selection + of parts of subfonts. Thus the image for rune r is found in position + r−min+offset of the subfont. +
+ + 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 subf and cache fields are used by the library to maintain + these caches. The width of a font is the maximum of the horizontal + extents of the characters in the cache. + String draws a string by loading the cache and emitting a sequence + of cache indices to draw. Cachechars guarantees the images for + the characters pointed to by *s or *r (one of these must be nil + in each call) are in the cache of f. It calls loadchar to put + missing characters into the cache. Cachechars translates the + character string into a set of cache indices which it loads into + the array c, up to a maximum of n indices or the length of the + string. Cachechars returns in c the number of cache indices emitted, + updates *s to point to the next character to be processed, and + sets *widp to the total width of the characters processed. + 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 *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. +
+ + Loadchar loads a character image into the character cache. Then + it tells the graphics server to copy the character into position + h in the character cache. If the current font width is smaller + than the horizontal extent of the character being loaded, loadfont + clears the cache and resets it to accept characters with the + bigger width, unless noclr is set, in which case it just returns + –1. If the character does not exist in the font at all, loadfont + returns 0; if it is unable to load the character without destroying + cached information, it returns –1, updating *sfname as described + above. It returns 1 to indicate success. +
+ + The age fields record when subfonts and characters have been used. + The font age is increased every time the font is used (agefont + does this). A character or subfont 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. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), allocimage(3), draw(3), subfont(3), image(7), font(7)
+ +
+

DIAGNOSTICS
+ +
+ + All of the functions use the graphics error function (see graphics(3)).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/cleanname.html b/man/man3/cleanname.html new file mode 100644 index 00000000..eba39965 --- /dev/null +++ b/man/man3/cleanname.html @@ -0,0 +1,71 @@ + +cleanname(3) - Plan 9 from User Space + + + + +
+
+
CLEANNAME(3)CLEANNAME(3) +
+
+

NAME
+ +
+ + cleanname – clean a path name
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ char*       cleanname(char *filename)
+ +
+

DESCRIPTION
+ +
+ + Cleanname takes a 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 . and .. directory components in the name. The string + is overwritten in place. +
+ + The shortest string cleanname can return is two bytes: the null-terminated + string ".". Therefore filename must contain room for at least two + bytes.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/cleanname.c
+ +
+

SEE ALSO
+ +
+ + cleanname(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/color.html b/man/man3/color.html new file mode 100644 index 00000000..a8274707 --- /dev/null +++ b/man/man3/color.html @@ -0,0 +1,89 @@ + +color(3) - Plan 9 from User Space + + + + +
+
+
COLOR(3)COLOR(3) +
+
+

NAME
+ +
+ + cmap2rgb, cmap2rgba, rgb2cmap – colors and color maps
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h> +
+ + int    rgb2cmap(int red, int green, int blue) +
+ + int    cmap2rgb(int col) +
+ + int    cmap2rgba(int col)
+ +
+

DESCRIPTION
+ +
+ + These routines convert between ‘true color’ red/green/blue triples + and the Plan 9 color map. See color(7) for a description of RGBV, + the standard color map. +
+ + 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. +
+ + Cmap2rgb decomposes the color of RGBV index 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. + Cmap2rgba decomposes the color of RGBV index 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 cmap2rgba shifted up 8 bits. This 32-bit + representation is the format used by draw(3) and memdraw(3) library + routines that take colors as arguments.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), allocimage(3), draw(3), image(7), color(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/complete.html b/man/man3/complete.html new file mode 100644 index 00000000..29453752 --- /dev/null +++ b/man/man3/complete.html @@ -0,0 +1,136 @@ + +complete(3) - Plan 9 from User Space + + + + +
+
+
COMPLETE(3)COMPLETE(3) +
+
+

NAME
+ +
+ + complete, freecompletion – file name completion
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <complete.h> +
+ + typedef struct CompletionCompletion;
+ struct Completion{
+ +
+ + uchar advance;
+ uchar complete;
+ char *string;
+ int nmatch;
+ int nfile;
+ char **filename;
+ +
+ };
+ +
+ + +
+ + Completion* complete(char *dir, char *s); +
+ + void freecompletion(Completion *c);
+ +
+

DESCRIPTION
+ +
+ + The complete function implements file name completion. Given a + directory dir and a string s, it returns an analysis of the file + names in that directory that begin with the string s. The fields + nmatch and nfile will be set to the number of files that match + the prefix and filename will be filled in with their names. If + the file named is a directory, a slash character will be appended + to it. +
+ + If no files match the string, nmatch will be zero, but complete + will return the full set of files in the directory, with nfile + set to their number. +
+ + The flag advance reports whether the string s can be extended + without changing the set of files that match. If true, string + will be set to the extension; that is, the value of string may + be appended to s by the caller to extend the embryonic file name + unambiguously. +
+ + The flag complete reports whether the extended file name uniquely + identifies a file. If true, 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. +
+ + The freecompletion function frees a Completion structure and its + contents. +
+ + In rio(1) and acme(1), file name completion is triggered by a + control-F character or an Insert character.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libcomplete
+ +
+

SEE ALSO
+ +
+ + rio(1), acme(1)
+ +
+

DIAGNOSTICS
+ +
+ + The complete function returns a null pointer and sets errstr if + the directory is unreadable or there is some other error.
+ +
+

BUGS
+ +
+ + The behavior of file name completion should be controlled by the + plumber.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/cputime.html b/man/man3/cputime.html new file mode 100644 index 00000000..fafc7f57 --- /dev/null +++ b/man/man3/cputime.html @@ -0,0 +1,65 @@ + +cputime(3) - Plan 9 from User Space + + + + +
+
+
CPUTIME(3)CPUTIME(3) +
+
+

NAME
+ +
+ + cputime, times – cpu time in this process and children
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int      times(long t[4]) +
+ + double cputime(void)
+ +
+

DESCRIPTION
+ +
+ + If t is non-null, 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. Cputime returns the sum of + those same times, converted to seconds. Times returns the elapsed + real time, in milliseconds, that the process has been + running.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/time.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/ctime.html b/man/man3/ctime.html new file mode 100644 index 00000000..4c162391 --- /dev/null +++ b/man/man3/ctime.html @@ -0,0 +1,150 @@ + +ctime(3) - Plan 9 from User Space + + + + +
+
+
CTIME(3)CTIME(3) +
+
+

NAME
+ +
+ + ctime, localtime, gmtime, asctime, tm2sec, timezone – convert date + and time
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char* ctime(long clock) +
+ + Tm*     localtime(long clock) +
+ + Tm*     gmtime(long clock) +
+ + char* asctime(Tm *tm) +
+ + long    tm2sec(Tm *tm)
+ +
+

DESCRIPTION
+ +
+ + Ctime converts a time clock such as returned by time(3) into ASCII + (sic) and returns a pointer to a 30-byte string in the following + form. All the fields have constant width. +
+ + +
+ + +
+ + Wed Aug    5 01:07:47 EST 1973\n\0 +
+ + +
+ +
+ Localtime and gmtime return pointers to structures containing + the broken-down time. Localtime corrects for the time zone and + possible daylight savings time; gmtime converts directly to GMT. + Asctime converts a broken-down time to ASCII and returns a pointer + to a 30-byte string.
+ +
+ + 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;
+ +
+ + +
+ Tm2sec converts a broken-down time to seconds since the start + of the epoch. It ignores wday, and assumes the local time zone + if zone is not GMT.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/date.c
+ /usr/local/plan9/src/lib9/ctime.c
+ +
+

SEE ALSO
+ +
+ + date(1), time(3)
+ +
+

BUGS
+ +
+ + The return values point to static data whose content is overwritten + by each call. +
+ + Daylight Savings Time is “normal” in the Southern hemisphere. + +
+ + These routines are not equipped to handle non-ASCII text, and + are provincial anyway. +
+ + To avoid name conflicts with the underlying system, ctime, localtime, + gmtime, asctime, and tm2sec are preprocessor macros defined as + p9ctime, p9localtime, p9gmtime, p9asctime, and p9tm2sec; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/des.html b/man/man3/des.html new file mode 100644 index 00000000..0752e8c8 --- /dev/null +++ b/man/man3/des.html @@ -0,0 +1,170 @@ + +des(3) - Plan 9 from User Space + + + + +
+
+
DES(3)DES(3) +
+
+

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 + +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void des_key_setup(uchar key[8], ulong schedule[32]) +
+ + void block_cipher(ulong *schedule, uchar *data,            int decrypting) + +
+ + void setupDESstate(DESstate *s, uchar key[8], uchar *ivec) +
+ + void desCBCencrypt(uchar*, int, DESstate*) +
+ + void desCBCdecrypt(uchar*, int, DESstate*) +
+ + void desECBencrypt(uchar*, int, DESstate*) +
+ + void desECBdecrypt(uchar*, int, DESstate*) +
+ + void triple_block_cipher(ulong keys[3][32], uchar*, int) +
+ + void setupDES3state(DES3state *s, uchar key[3][8],                  uchar *ivec) + +
+ + void des3CBCencrypt(uchar*, int, DES3state*) +
+ + void des3CBCdecrypt(uchar*, int, DES3state*) +
+ + void des3ECBencrypt(uchar*, int, DES3state*) +
+ + void des3ECBdecrypt(uchar*, int, DES3state*) +
+ + void key_setup(uchar[7], ulong[32]) +
+ + void des56to64(uchar *k56, uchar *k64) +
+ + void des64to56(uchar *k64, uchar *k56)
+ +
+

DESCRIPTION
+ +
+ + +
+ + The Digital Encryption Standard (DES) is a shared key or symmetric + encryption using either a 56 bit key for single DES or three 56 + bit keys for triple des. The keys are encoded into 64 bits where + every eight bit is parity. +
+ + The basic DES function, 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 des_key_setup. + +
+ + Since it is a bit awkward, 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 DESstate structure that contains the key + schedule and any chained state. SetupDESstate sets up the DESstate + structure using the key and an 8 byte initialization vector. +
+ + Electronic code book, using desECBencrypt and 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. +
+ + Cipher block chaining mode, using desCBCencrypt and desCBCdecrypt, + is more secure. Every block encrypted depends on the initialization + vector and all blocks encrypted before it. +
+ + 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. +
+ + There are equivalent triple DES functions for each of the DES + functions. +
+ + 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: des56to64 and des64to56 to convert + back and forth between the two formats. Also a key schedule can + be set up from the 7 byte format using key_setup. +
+ + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), dsa(3), elgamal(3), rc4(3), rsa(3), + sechash(3), prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/dial.html b/man/man3/dial.html new file mode 100644 index 00000000..e1014859 --- /dev/null +++ b/man/man3/dial.html @@ -0,0 +1,241 @@ + +dial(3) - Plan 9 from User Space + + + + +
+
+
DIAL(3)DIAL(3) +
+
+

NAME
+ +
+ + dial, announce, listen, accept, reject, netmkaddr, dialparse – + make and break network connections
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int     dial(char *addr, char *local, char *dir, int *cfdp) +
+ + int     announce(char *addr, char *dir) +
+ + int     listen(char *dir, char *newdir) +
+ + int     accept(int ctl, char *dir) +
+ + int     reject(int ctl, char *dir, char *cause) +
+ + char* netmkaddr(char *addr, char *defnet, char *defservice) +
+ + int     dialparse(char *addr, char **net, char **unix,
+ +
+ + +
+ + u32int *host, int *port)
+ +
+ +
+ +
+

DESCRIPTION
+ +
+ + For these routines, addr is a network address of the form network!netaddr!service, + network!netaddr, or simply netaddr. Network is tcp, udp, unix, + or the special token, net. Net is a free variable that stands + for any network in common between the source and the host netaddr. + Netaddr can be a host name, a + domain name, or a network address. +
+ + On Plan 9, the dir argument is a path name to a line directory + that has files for accessing the connection. To keep the same + function signatures, the Unix port of these routines uses strings + of the form /dev/fd/n instead of line directory paths. These strings + should be treated as opaque data and ignored. +
+ + Dial makes a call to destination addr on a multiplexed network. + If the network in addr is net, dial will try in succession all + networks in common between source and destination until a call + succeeds. It returns a file descriptor open for reading and writing + the data file in the line directory. The addr file in the line + directory contains the address called. Dial’s local, dir, and + cfdp arguments are not supported and must be zero. +
+ + Announce and listen are the complements of dial. Announce establishes + a network name to which calls can be made. Like dial, announce + returns an open ctl file. The netaddr used in announce may be + a local address or an asterisk, to indicate all local addresses, + e.g. tcp!*!echo. The listen routine takes as its + first argument the dir of a previous announce. When a call is + received, listen returns an open ctl file for the line the call + was received on. It sets newdir to the path name of the new line + directory. Accept accepts a call received by listen, while reject + refuses the call because of cause. Accept returns a file descriptor + for + the data file opened ORDWR. +
+ + 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. +
+ + Dialparse parses a network address as described above into a network + name, a Unix domain socket address, an IPv4 host address, and + an IPv4 port number.
+ +
+

EXAMPLES
+ +
+ + Make a call and return an open file descriptor to use for communications:
+ +
+ + int callkremvax(void)
+ {
+ +
+ + return dial("kremvax", 0, 0, 0);
+ +
+ }
+ +
+ + +
+ Connect to a Unix socket served by acme(4):
+ +
+ + int dialacme(void)
+ {
+ +
+ + return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0);
+ +
+ }
+ +
+ + +
+ Announce as kremvax on TCP/IP and loop forever receiving calls + and echoing back to the caller anything sent:
+ +
+ + 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;
+ }
+ }
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/dial.c
+ /usr/local/plan9/src/lib9/announce.c
+ /usr/local/plan9/src/lib9/_p9dialparse.c
+ +
+

DIAGNOSTICS
+ +
+ + Dial, announce, and listen return –1 if they fail.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, dial, announce, + listen, netmkaddr, and reject are preprocessor macros defined + as p9dial, p9announce, and so on; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/dirread.html b/man/man3/dirread.html new file mode 100644 index 00000000..7c5ba4ed --- /dev/null +++ b/man/man3/dirread.html @@ -0,0 +1,114 @@ + +dirread(3) - Plan 9 from User Space + + + + +
+
+
DIRREAD(3)DIRREAD(3) +
+
+

NAME
+ +
+ + dirread, dirreadall – read directory
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + long dirread(int fd, Dir **buf) +
+ + long dirreadall(int fd, Dir **buf) +
+ + #define     STATMAX     65535U +
+ + #define     DIRMAX      (sizeof(Dir)+STATMAX)
+ +
+

DESCRIPTION
+ +
+ + The data returned by a read(3) on a directory is a set of complete + directory entries in a machine-independent format, exactly equivalent + to the result of a stat(3) on each file or subdirectory in the + directory. Dirread decodes the directory entries into a machine-dependent + form. It reads from fd and unpacks the data + into an array of Dir structures whose address is returned in *buf + (see stat(3) for the layout of a Dir). The array is allocated + with malloc(3) each time dirread is called. +
+ + Dirreadall is like dirread, but reads in the entire directory; + by contrast, dirread steps through a directory one read(3) at + a time. +
+ + Directory entries have variable length. A successful read of a + directory always returns an integral number of complete directory + entries; dirread always returns complete Dir structures. See read(9p) + for more information. +
+ + The constant STATMAX is the maximum size that a directory entry + can occupy. The constant DIRMAX is an upper limit on the size + necessary to hold a Dir structure and all the associated data. + +
+ + Dirread and dirreadall return the number of Dir structures filled + in buf. The file offset is advanced by the number of bytes actually + read.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/dirread.c
+ +
+

SEE ALSO
+ +
+ + intro(3), open(3), read(3)
+ +
+

DIAGNOSTICS
+ +
+ + Dirread and Dirreadall return zero for end of file and a negative + value for error. In either case, *buf is set to nil so the pointer + can always be freed with impunity. +
+ + These functions set errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/draw.html b/man/man3/draw.html new file mode 100644 index 00000000..f90b16fc --- /dev/null +++ b/man/man3/draw.html @@ -0,0 +1,1174 @@ + +draw(3) - Plan 9 from User Space + + + + +
+
+
DRAW(3)DRAW(3) +
+
+

NAME
+ +
+ + Image, draw, drawop, gendraw, gendrawop, drawreplxy, drawrepl, + replclipr, line, lineop, poly, polyop, fillpoly, fillpolyop, bezier, + bezierop, bezspline, bezsplineop, bezsplinepts, fillbezier, fillbezierop, + fillbezspline, fillbezsplineop, ellipse, ellipseop, fillellipse, + fillellipseop, arc, arcop, fillarc, fillarcop, icossin, icossin2, + border, string, stringop, stringn, stringnop, runestring, runestringop, + runestringn, runestringnop, stringbg, stringbgop, stringnbg, stringnbgop, + runestringbg, runestringbgop, runestringnbg, runestringnbgop, + _string, ARROW, drawsetdebug – graphics functions
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ +
+ + 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;
+ +
+ + typedef enum
+ {
+ +
+ + /* Porter−Duff compositing operators */
+ Clear       = 0,
+ SinD = 8,
+ DinS = 4,
+ SoutD       = 2,
+ DoutS       = 1,
+ S          = SinD|SoutD,
+ SoverD      = SinD|SoutD|DoutS,
+ SatopD      = SinD|DoutS,
+ SxorD       = SoutD|DoutS,
+ D          = DinS|DoutS,
+ DoverS      = DinS|DoutS|SoutD,
+ DatopS      = DinS|SoutD,
+ DxorS       = DoutS|SoutD, /* == SxorD */
+ Ncomp = 12,
+ +
+ } Drawop;
+ +
+ + void    draw(Image *dst, Rectangle r, Image *src,
+ +
+ + +
+ + Image *mask, Point p)
+ +
+ + +
+ +
+ void    drawop(Image *dst, Rectangle r, Image *src,
+ +
+ + +
+ + Image *mask, Point p, Drawop op)
+ +
+ + +
+ +
+ void    gendraw(Image *dst, Rectangle r, Image *src, Point sp,
+ +
+ + +
+ + Image *mask, Point mp)
+ +
+ + +
+ +
+ void    gendrawop(Image *dst, Rectangle r, Image *src, Point sp,
+ +
+ + +
+ + Image *mask, Point mp, Drawop op)
+ +
+ + +
+ +
+ int     drawreplxy(int min, int max, int x)
+ +
+ + Point drawrepl(Rectangle r, Point p)
+ +
+ + void    replclipr(Image *i, int repl, Rectangle clipr)
+ +
+ + void    line(Image *dst, Point p0, Point p1, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp)
+ +
+ + +
+ +
+ void    lineop(Image *dst, Point p0, Point p1, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    poly(Image *dst, Point *p, int np, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp)
+ +
+ + +
+ +
+ void    polyop(Image *dst, Point *p, int np, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    fillpoly(Image *dst, Point *p, int np, int wind,
+ +
+ + +
+ + Image *src, Point sp)
+ +
+ + +
+ +
+ void    fillpolyop(Image *dst, Point *p, int np, int wind,
+ +
+ + +
+ + Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ int     bezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
+ +
+ + +
+ + int end0, int end1, int radius, Image *src, Point sp)
+ +
+ + +
+ +
+ int     bezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
+ +
+ + +
+ + int end0, int end1, int radius, Image *src, Point sp,
+ Drawop op)
+ +
+ + +
+ +
+ int     bezspline(Image *dst, Point *pt, int npt, int end0, int end1,
+ +
+ + +
+ + int radius, Image *src, Point sp)
+ +
+ + +
+ +
+ int     bezsplineop(Image *dst, Point *pt, int npt, int end0, int + end1,
+ +
+ + +
+ + int radius, Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ int     bezsplinepts(Point *pt, int npt, Point **pp)
+ +
+ + int     fillbezier(Image *dst, Point p0, Point p1, Point p2, Point + p3,
+ +
+ + +
+ + int w, Image *src, Point sp)
+ +
+ + +
+ +
+ int     fillbezierop(Image *dst, Point p0, Point p1, Point p2, Point + p3,
+ +
+ + +
+ + int w, Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ int     fillbezspline(Image *dst, Point *pt, int npt, int w,
+ +
+ + +
+ + Image *src, Point sp)
+ +
+ + +
+ +
+ int     fillbezsplineop(Image *dst, Point *pt, int npt, int w,
+ +
+ + +
+ + Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    ellipse(Image *dst, Point c, int a, int b, int thick,
+ +
+ + +
+ + Image *src, Point sp)
+ +
+ + +
+ +
+ void    ellipseop(Image *dst, Point c, int a, int b, int thick,
+ +
+ + +
+ + Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    fillellipse(Image *dst, Point c, int a, int b,
+ +
+ + +
+ + Image *src, Point sp)
+ +
+ + +
+ +
+ void    fillellipseop(Image *dst, Point c, int a, int b,
+ +
+ + +
+ + Image *src, Point sp, Drawop op)
+ +
+ + +
+ +
+ void    arc(Image *dst, Point c, int a, int b, int thick,
+ +
+ + +
+ + Image *src, Point sp, int alpha, int phi)
+ +
+ + +
+ +
+ void    arcop(Image *dst, Point c, int a, int b, int thick,
+ +
+ + +
+ + Image *src, Point sp, int alpha, int phi, Drawop op)
+ +
+ + +
+ +
+ void    fillarc(Image *dst, Point c, int a, int b, Image *src,
+ +
+ + +
+ + Point sp, int alpha, int phi)
+ +
+ + +
+ +
+ void    fillarcop(Image *dst, Point c, int a, int b, Image *src,
+ +
+ + +
+ + Point sp, int alpha, int phi, Drawop op)
+ +
+ + +
+ +
+ int     icossin(int deg, int *cosp, int *sinp)
+ +
+ + int     icossin2(int x, int y, int *cosp, int *sinp)
+ +
+ + void    border(Image *dst, Rectangle r, int i, Image *color, Point + sp)
+ +
+ + Point string(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s)
+ +
+ + +
+ +
+ Point stringop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, Drawop op)
+ +
+ + +
+ +
+ Point stringn(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, int len)
+ +
+ + +
+ +
+ Point stringnop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, int len, Drawop op)
+ +
+ + +
+ +
+ Point runestring(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r)
+ +
+ + +
+ +
+ Point runestringop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, Drawop op)
+ +
+ + +
+ +
+ Point runestringn(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, int len)
+ +
+ + +
+ +
+ Point runestringnop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, int len, Drawop op)
+ +
+ + +
+ +
+ Point stringbg(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, Image *bg, Point bgp)
+ +
+ + +
+ +
+ Point stringbgop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, Image *bg, Point bgp, Drawop op)
+ +
+ + +
+ +
+ Point stringnbg(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, int len, Image *bg, Point bgp)
+ +
+ + +
+ +
+ Point stringnbgop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, char *s, int len, Image *bg, Point bgp, Drawop op)
+ +
+ + +
+ +
+ Point runestringbg(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, Image *bg, Point bgp)
+ +
+ + +
+ +
+ Point runestringbgop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, Image *bg, Point bgp, Drawop op)
+ +
+ + +
+ +
+ Point runestringnbg(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, int len, Image *bg, Point bgp)
+ +
+ + +
+ +
+ Point runestringnbgop(Image *dst, Point p, Image *src, Point sp,
+ +
+ + +
+ + Font *f, Rune *r, int len, Image *bg, Point bgp, Drawop op)
+ +
+ + +
+ +
+ 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)
+ +
+ + +
+ +
+ void    drawsetdebug(int on)
+ +
+ + enum
+ {
+ +
+ + +
+ + /* line ends */
+ Endsquare    = 0,
+ Enddisc      = 1,
+ Endarrow = 2,
+ Endmask      = 0x1F
+ +
+ +
+ };
+ +
+ + #define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23))
+ +
+

DESCRIPTION
+ +
+ + The 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 Image; no special operators are needed to draw + on a window. +
+ + r       The coordinates of the rectangle in the plane for which the Image + has defined pixel values. It should not be modified after the + image is created.
+ clipr   The clipping rectangle: operations that read or write the + image will not access pixels outside clipr. Frequently, clipr + is the same as r, but it may differ; see in particular the discussion + of repl. The clipping region may be modified dynamically using + replclipr (q.v.).
+ chan    The pixel channel format descriptor, as described in image(7). + The value should not be modified after the image is created.
+ depth   The number of bits per pixel in the picture; it is identically + chantodepth(chan) (see graphics(3)) and is provided as a convenience. + The value should not be modified after the image is created.
+ repl    A boolean value specifying whether the image is tiled to cover + the plane when used as a source for a drawing operation. If repl + is zero, operations are restricted to the intersection of r and + clipr. If repl is set, r defines the tile to be replicated and + clipr defines the portion of the plane covered by the + +
+ + +
+ + tiling, in other words, r is replicated to cover clipr; in such + cases r and clipr are independent.
+ For example, a replicated image with r set to ((0, 0), (1, 1)) + and clipr set to ((0, 0), (100, 100)), with the single pixel of + r set to blue, behaves identically to an image with r and 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 replclipr (q.v.). + +
+ + +
+ +
+ Most of the drawing functions come in two forms: a basic form, + and an extended form that takes an extra Drawop to specify a Porter-Duff + compositing operator to use. The basic forms assume the operator + is SoverD, which suffices for the vast majority of applications. + The extended forms are named by adding an + -op suffix to the basic form. Only the basic forms are listed + below.
+ draw(dst, r, src, mask, p)
+ +
+ + Draw is the standard drawing function. Only those pixels within + the intersection of dst−>r and dst−>clipr will be affected; draw + ignores dst−>repl. The operation proceeds as follows (this is a + description of the behavior, not the implementation):
+ 1.    If repl is set in src or mask, replicate their contents to fill + their clip rectangles.
+ 2.    Translate src and mask so p is aligned with r.min.
+ 3.    Set r to the intersection of r and dst−>r.
+ 4.    Intersect r with src−>clipr. If src−>repl is false, also intersect + r with src−>r.
+ 5.    Intersect r with mask−>clipr. If mask−>repl is false, also intersect + r with mask−>r.
+ 6.    For each location in r, combine the dst pixel with the src pixel + using the alpha value corresponding to the mask pixel. If the + mask has an explicit alpha channel, the alpha value corresponding + to the 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, + draw replaces the dst pixels with (src in mask) over dst. (In + the extended form, “over” is replaced by op).
+ +
+ 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.
+ +
+ gendraw(dst, r, src, p0, mask, p1)
+ +
+ + Similar to draw except that gendraw aligns the source and mask + differently: src is aligned so p0 corresponds to r.min and mask + is aligned so p1 corresponds to r.min. For most purposes with + simple masks and source images, draw is sufficient, but gendraw + is the general operator and the one all other + drawing primitives are built upon.
+ +
+ drawreplxy(min,max,x)
+ +
+ + Clips x to be in the half-open interval [min, max) by adding or + subtracting a multiple of max-min.
+ +
+ drawrepl(r,p)
+ +
+ + Clips the point p to be within the rectangle r by translating + the point horizontally by an integer multiple of rectangle width + and vertically by the height.
+ +
+ replclipr(i,repl,clipr)
+ +
+ + Because the image data is stored on the server, local modifications + to the Image data structure itself will have no effect. Repclipr + modifies the local Image data structure’s repl and clipr fields, + and notifies the server of their modification.
+ +
+ line(dst, p0, p1, end0, end1, thick, src, sp)
+ +
+ + Line draws in dst a line of width 1+2*thick pixels joining points + p0 and p1. The line is drawn using pixels from the src image aligned + so sp in the source corresponds to p0 in the destination. The + line touches both p0 and p1, and end0 and end1 specify how the + ends of the line are drawn. Endsquare + terminates the line perpendicularly to the direction of the line; + a thick line with Endsquare on both ends will be a rectangle. + Enddisc terminates the line by drawing a disc of diameter 1+2*thick + centered on the end point. Endarrow terminates the line with an + arrowhead whose tip touches the endpoint. + The macro ARROW permits explicit control of the shape of the arrow. + If all three parameters are zero, it produces the default arrowhead, + otherwise, a sets the distance along line from end of the regular + line to tip, b sets the distance along line from the barb to the + tip, and c sets the distance perpendicular to the + line from edge of line to the tip of the barb, all in pixels.
+ Line and the other geometrical operators are equivalent to calls + to gendraw using a mask produced by the geometric procedure.
+ +
+ poly(dst, p, np, end0, end1, thick, src, sp)
+ +
+ + Poly draws a general polygon; it is conceptually equivalent to + a series of calls to line joining adjacent points in the array + of Points p, which has np elements. The ends of the polygon are + specified as in line; interior lines are terminated with Enddisc + to make smooth joins. The source is aligned so sp + corresponds to p[0].
+ +
+ fillpoly(dst, p, np, wind, src, sp)
+ +
+ + Fillpoly is like poly but fills in the resulting polygon rather + than outlining it. The source is aligned so sp corresponds to + p[0]. The winding rule parameter wind resolves ambiguities about + what to fill if the polygon is self-intersecting. If wind is ~0, + a pixel is inside the polygon if the polygon’s winding number + about the point is non-zero. If wind is 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.
+ +
+ bezier(dst, a, b, c, d, end0, end1, thick, src, sp)
+ +
+ + Bezier draws the cubic Bezier curve defined by Points a, b, c, + and d. The end styles are determined by end0 and end1; the thickness + of the curve is 1+2*thick. The source is aligned so sp in src + corresponds to a in dst.
+ +
+ bezspline(dst, p, end0, end1, thick, src, sp)
+ +
+ + Bezspline takes the same arguments as poly but draws a quadratic + B-spline (despite its name) rather than a polygon. If the first + and last points in p are equal, the spline has periodic end conditions.
+ +
+ bezsplinepts(pt, npt, pp)
+ +
+ + Bezsplinepts returns in pp a list of points making up the open + polygon that bezspline would draw. The caller is responsible for + freeing *pp.
+ +
+ fillbezier(dst, a, b, c, d, wind, src, sp)
+ +
+ + Fillbezier is to bezier as fillpoly is to poly.
+ +
+ fillbezspline(dst, p, wind, src, sp)
+ +
+ + Fillbezspline is like fillpoly but fills the quadratic B-spline + rather than the polygon outlined by p. The spline is closed with + a line if necessary.
+ +
+ ellipse(dst, c, a, b, thick, src, sp)
+ +
+ + Ellipse draws in dst an ellipse centered on c with horizontal + and vertical semiaxes a and b. The source is aligned so sp in + src corresponds to c in dst. The ellipse is drawn with thickness + 1+2*thick.
+ +
+ fillellipse(dst, c, a, b, src, sp)
+ +
+ + Fillellipse is like ellipse but fills the ellipse rather than + outlining it.
+ +
+ arc(dst, c, a, b, thick, src, sp, alpha, phi)
+ +
+ + Arc is like ellipse, but draws only that portion of the ellipse + starting at angle alpha and extending through an angle of phi. + The angles are measured in degrees counterclockwise from the positive + x axis.
+ +
+ fillarc(dst, c, a, b, src, sp, alpha, phi)
+ +
+ + Fillarc is like arc, but fills the sector with the source color.
+ +
+ icossin(deg, cosp, sinp)
+ +
+ + Icossin stores in *cosp and *sinp scaled integers representing + the cosine and sine of the angle deg, measured in integer degrees. + The values are scaled so cos(0) is 1024.
+ +
+ icossin2(x, y, cosp, sinp)
+ +
+ + Icossin2 is analogous to icossin, with the angle represented not + in degrees but implicitly by the point (x,y). It is to icossin + what atan2 is to atan (see sin(3)).
+ +
+ border(dst, r, i, color, sp)
+ +
+ + Border draws an outline of rectangle r in the specified color. + The outline has width i; if positive, the border goes inside the + rectangle; negative, outside. The source is aligned so sp corresponds + to r.min.
+ +
+ string(dst, p, src, sp, font, s)
+ +
+ + String draws in dst characters specified by the string s and font; + it is equivalent to a series of calls to gendraw using source + src and masks determined by the character shapes. The text is + positioned with the left of the first character at p.x and the + top of the line of text at p.y. The source is positioned so sp + in + src corresponds to p in dst. String returns a Point that is the + position of the next character that would be drawn if the string + were longer.
+ For characters with undefined or zero-width images in the font, + the character at font position 0 (NUL) is drawn.
+ The other string routines are variants of this basic form, and + have names that encode their variant behavior. Routines whose + names contain rune accept a string of Runes rather than UTF-encoded + bytes. Routines ending in n accept an argument, n, that defines + the number of characters to draw rather than + accepting a NUL-terminated string. Routines containing bg draw + the background behind the characters in the specified color (bg) + and alignment (bgp); normally the text is drawn leaving the background + intact.
+ The routine _string captures all this behavior into a single operator. + Whether it draws a UTF string or Rune string depends on whether + s or r is null (the string length is always determined by len). + If bg is non-null, it is used as a background color. The 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.
+ +
+ drawsetdebug(on)
+ +
+ + Turns on or off debugging output (usually to a serial line) according + to whether on is non-zero.
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), stringsize(3), color(7), utf(7), addpt(3) +
+ + T. Porter, T. Duff. “Compositing Digital Images”, Computer Graphics + (Proc. SIGGRAPH), 18:3, pp. 253-259, 1984.
+ +
+

DIAGNOSTICS
+ +
+ + These routines call the graphics error function on fatal errors.
+ +
+

BUGS
+ +
+ + Anti-aliased characters can be drawn by defining a font with multiple + bits per pixel, but there are no anti-aliasing geometric primitives.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/dsa.html b/man/man3/dsa.html new file mode 100644 index 00000000..765ddd7c --- /dev/null +++ b/man/man3/dsa.html @@ -0,0 +1,172 @@ + +dsa(3) - Plan 9 from User Space + + + + +
+
+
DSA(3)DSA(3) +
+
+

NAME
+ +
+ + dsagen, dsasign, dsaverify, dsapuballoc, dsapubfree, dsaprivalloc, + dsaprivfree, dsasigalloc, dsasigfree, dsaprivtopub - digital signature + algorithm
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + DSApriv*    dsagen(DSApub *opub) +
+ + DSAsig*     dsasign(DSApriv *k, mpint *m) +
+ + int         dsaverify(DSApub *k, DSAsig *sig, mpint *m) +
+ + DSApub*     dsapuballoc(void) +
+ + void        dsapubfree(DSApub*) +
+ + DSApriv*    dsaprivalloc(void) +
+ + void        dsaprivfree(DSApriv*) +
+ + DSAsig*     dsasigalloc(void) +
+ + void        dsasigfree(DSAsig*) +
+ + DSApub*     dsaprivtopub(DSApriv*)
+ +
+

DESCRIPTION
+ +
+ + +
+ + DSA is the NIST approved digital signature algorithm. The owner + of a key publishes the public part of the key:
+ +
+ + struct DSApub
+ {
+ +
+ + mpint       *p;    // modulus
+ mpint       *q;    // group order, q divides p−1
+ mpint       *alpha;     // group generator
+ mpint       *key;       // alpha**secret mod p
+ +
+ };
+ +
+ This part can be used for verifying signatures (with dsaverify) + created by the owner. The owner signs (with dsasign) using his + private key:
+ +
+ + struct DSApriv
+ {
+ +
+ + DSApub      pub;
+ mpint       *secret; // (decryption key)
+ +
+ };
+ +
+ + +
+ Keys are generated using dsagen. If dsagen’s argument opub is + nil, a key is created using a new p and q generated by DSAprimes + (see prime(3)). Otherwise, p and q are copied from the old key. + +
+ + Dsaprivtopub returns a newly allocated copy of the public key + corresponding to the private key. +
+ + The routines dsapuballoc, dsapubfree, dsaprivalloc, and dsaprivfree + are provided to manage key storage. +
+ + Dsasign signs message m using a private key k yielding a
+ +
+ + struct DSAsig
+ {
+ +
+ + mpint       *r, *s;
+ +
+ };
+ +
+ Dsaverify returns 0 if the signature is valid and –1 if not. +
+ + The routines dsasigalloc and dsasigfree are provided to manage + signature storage.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), des(3), rc4(3), rsa(3), sechash(3), + prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/dup.html b/man/man3/dup.html new file mode 100644 index 00000000..c601e3b2 --- /dev/null +++ b/man/man3/dup.html @@ -0,0 +1,78 @@ + +dup(3) - Plan 9 from User Space + + + + +
+
+
DUP(3)DUP(3) +
+
+

NAME
+ +
+ + dup – duplicate an open file descriptor
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int dup(int oldfd, int newfd)
+ +
+

DESCRIPTION
+ +
+ + Given a file descriptor, oldfd, referring to an open file, dup + returns a new file descriptor referring to the same file. +
+ + If newfd is –1 the system chooses the lowest available file descriptor. + Otherwise, dup will use newfd for the new file descriptor (closing + any old file associated with newfd).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/dup.c
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, dup is a preprocessor + macro defined as p9dup; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/elgamal.html b/man/man3/elgamal.html new file mode 100644 index 00000000..a6518468 --- /dev/null +++ b/man/man3/elgamal.html @@ -0,0 +1,174 @@ + +elgamal(3) - Plan 9 from User Space + + + + +
+
+
ELGAMAL(3)ELGAMAL(3) +
+
+

NAME
+ +
+ + eggen, egencrypt, egdecrypt, egsign, egverify, egpuballoc, egpubfree, + egprivalloc, egprivfree, egsigalloc, egsigfree, egprivtopub - + elgamal encryption
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + EGpriv*     eggen(int nlen, int nrep) +
+ + mpint*      egencrypt(EGpub *k, mpint *in, mpint *out) +
+ + mpint*      egdecrypt(EGpriv *k, mpint *in, mpint *out) +
+ + EGsig*      egsign(EGpriv *k, mpint *m) +
+ + int         egverify(EGpub *k, EGsig *sig, mpint *m) +
+ + EGpub*      egpuballoc(void) +
+ + void        egpubfree(EGpub*) +
+ + EGpriv*     egprivalloc(void) +
+ + void        egprivfree(EGpriv*) +
+ + EGsig*      egsigalloc(void) +
+ + void        egsigfree(EGsig*) +
+ + EGpub*      egprivtopub(EGpriv*)
+ +
+

DESCRIPTION
+ +
+ + +
+ + Elgamal is a public key encryption and signature algorithm. The + owner of a key publishes the public part of the key:
+ +
+ + struct EGpub
+ {
+ +
+ + mpint       *p;    // modulus
+ mpint       *alpha;     // generator
+ mpint       *key;       // (encryption key) alpha**secret mod p
+ +
+ };
+ +
+ This part can be used for encrypting data (with egencrypt) to + be sent to the owner. The owner decrypts (with egdecrypt) using + his private key:
+ +
+ + struct EGpriv
+ {
+ +
+ + EGpub       pub;
+ mpint       *secret; // (decryption key)
+ +
+ };
+ +
+ + +
+ Keys are generated using eggen. 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. Egprivtopub returns a newly allocated copy of + the public key corresponding to the private key. +
+ + The routines egpuballoc, egpubfree, egprivalloc, and egprivfree + are provided to manage key storage. +
+ + Egsign signs message m using a private key k yielding a
+ +
+ + struct EGsig
+ {
+ +
+ + mpint       *r, *s;
+ +
+ };
+ +
+ Egverify returns 0 if the signature is valid and –1 if not. +
+ + The routines egsigalloc and egsigfree are provided to manage signature + storage.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), des(3), dsa(3), rc4(3), rsa(3), sechash(3), + prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/encode.html b/man/man3/encode.html new file mode 100644 index 00000000..c7a8132c --- /dev/null +++ b/man/man3/encode.html @@ -0,0 +1,109 @@ + +encode(3) - Plan 9 from User Space + + + + +
+
+
ENCODE(3)ENCODE(3) +
+
+

NAME
+ +
+ + dec64, enc64, dec32, enc32, dec16, enc16, encodefmt – encoding + byte arrays as strings
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int    dec64(uchar *out, int lim, char *in, int n) +
+ + int    enc64(char *out, int lim, uchar *in, int n) +
+ + int    dec32(uchar *out, int lim, char *in, int n) +
+ + int    enc32(char *out, int lim, uchar *in, int n) +
+ + int    dec16(uchar *out, int lim, char *in, int n) +
+ + int    enc16(char *out, int lim, uchar *in, int n) +
+ + int    encodefmt(Fmt*)
+ +
+

DESCRIPTION
+ +
+ + +
+ + Enc16, enc32 and 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 lim, the length of the output + buffer, is too small. +
+ + Dec16, dec32 and 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. +
+ + Encodefmt can be used with fmtinstall(3) and print(3) to print + encoded representations of byte arrays. The verbs are
+ H     base 16 (i.e. hexadecimal). The default encoding is in upper + case. The l flag forces lower case.
+ <     base 32
+ [     base 64 (same as MIME) +
+ + The length of the array is specified as f2. For example, to display + a 15 byte array as hex:
+ +
+ + char x[15];
+ fmtinstall('H', encodefmt);
+ print("%.*H\n", sizeof x, x);
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/u32.c
+ /usr/local/plan9/src/lib9/u64.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/errstr.html b/man/man3/errstr.html new file mode 100644 index 00000000..547efc8d --- /dev/null +++ b/man/man3/errstr.html @@ -0,0 +1,121 @@ + +errstr(3) - Plan 9 from User Space + + + + +
+
+
ERRSTR(3)ERRSTR(3) +
+
+

NAME
+ +
+ + errstr, rerrstr, werrstr – description of last system call error
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int errstr(char *err, uint nerr) +
+ + void rerrstr(char *err, uint nerr) +
+ + void werrstr(char *fmt, ...)
+ +
+

DESCRIPTION
+ +
+ + When a system call fails it returns –1 and records a null terminated + string describing the error in a per-process buffer. Errstr swaps + the contents of that buffer with the contents of the array err. + Errstr will write at most nerr bytes into 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 + 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 errstr. +
+ + The per-process buffer is ERRMAX bytes long. Any error string + provided by the user will be truncated at ERRMAX−1 bytes. ERRMAX + is defined in <libc.h>. +
+ + If no system call has generated an error since the last call to + errstr with an empty string, the result is an empty string. +
+ + The verb r in print(3) calls errstr and outputs the error string. + +
+ + Rerrstr reads the error string but does not modify the per-process + buffer, so a subsequent errstr will recover the same string. +
+ + Werrstr takes a print style format as its argument and uses it + to format a string to pass to errstr. The string returned from + errstr is discarded. +
+ + The error string is maintained in parallel with the Unix error + number errno. Changing errno will reset the error string, and + changing the error string via errstr or werrstr will reset errno.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/errstr.c
+ +
+

DIAGNOSTICS
+ +
+ + Errstr always returns 0.
+ +
+

SEE ALSO
+ +
+ + intro(3), perror(3)
+ +
+

BUGS
+ +
+ + The implementation sets errno to the (somewhat arbitrary) constant + 0x19283745 when the error string is valid. When errno is set to + other values, the error string is synthesized using strerror(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/event.html b/man/man3/event.html new file mode 100644 index 00000000..87cff2fd --- /dev/null +++ b/man/man3/event.html @@ -0,0 +1,390 @@ + +event(3) - Plan 9 from User Space + + + + +
+
+
EVENT(3)EVENT(3) +
+
+

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
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include    <u.h>
+ #include    <libc.h>
+ #include    <draw.h>
+ #include    <event.h>
+ #include    <cursor.h>
+ +
+ + void        einit(ulong keys)
+ +
+ + ulong       event(Event *e)
+ +
+ + Mouse       emouse(void)
+ +
+ + int         ekbd(void)
+ +
+ + int         ecanmouse(void)
+ +
+ + int         ecankbd(void)
+ +
+ + int         ereadmouse(Mouse *m)
+ +
+ + int         eatomouse(Mouse *m, char *buf, int n)
+ +
+ + ulong       estart(ulong key, int fd, int n)
+ +
+ + ulong       estartfn(int id, ulong key, int fd, int n,
+ +
+ + +
+ + int (*fn)(Event*, uchar*, int))
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ ulong       etimer(ulong key, int n)
+ +
+ + ulong       eread(ulong keys, Event *e)
+ +
+ + int         ecanread(ulong keys)
+ +
+ + void        eresized(int new)
+ +
+ + Rectangle egetrect(int but, Mouse *m)
+ +
+ + void        edrawgetrect(Rectangle r, int up)
+ +
+ + int         emenuhit(int but, Mouse *m, Menu *menu)
+ +
+ + +
+ + int         emoveto(Point p)
+ +
+ + +
+ + int         esetcursor(Cursor *c)
+ +
+ + extern Mouse      *mouse
+ +
+ + enum{
+ +
+ + +
+ + Emouse = 1,
+ Ekeyboard = 2,
+ +
+ +
+ };
+ +
+ + +
+

DESCRIPTION
+ +
+ + These routines provide an interface to multiple sources of input + for unthreaded programs. Threaded programs (see thread(3)) should + instead use the threaded mouse and keyboard interface described + in mouse(3) and keyboard(3). +
+ + Einit must be called first. If the argument to einit has the Emouse + and Ekeyboard bits set, the mouse and keyboard events will be + enabled; in this case, initdraw (see graphics(3)) must have already + been called. The user must provide a function called eresized + to be called whenever the window in which the process + is running has been resized; the argument new is a flag specifying + whether the program must call getwindow (see graphics(3)) to re-establish + a connection to its window. After resizing (and perhaps calling + getwindow), the global variable screen will be updated to point + to the new window’s Image structure. +
+ + As characters are typed on the keyboard, they are read by the + event mechanism and put in a queue. Ekbd returns the next rune + from the queue, blocking until the queue is non-empty. The characters + are read in raw mode, so they are available as soon as a complete + rune is typed. +
+ + When the mouse moves or a mouse button is pressed or released, + a new mouse event is queued by the event mechanism. Emouse returns + the next mouse event from the queue, blocking until the queue + is non-empty. Emouse returns a Mouse structure:
+ +
+ + struct Mouse
+ {
+ +
+ + int     buttons;
+ Point xy;
+ ulong msec;
+ +
+ };
+ +
+ + +
+ Buttons&1 is set when the left mouse button is pressed, buttons&2 + when the middle button is pressed, and buttons&4 when the right + button is pressed. The current mouse position is always returned + in xy. Msec is a time stamp in units of milliseconds. +
+ + Ecankbd and ecanmouse return non-zero when there are keyboard + or mouse events available to be read. +
+ + Ereadmouse reads the next mouse event from the file descriptor + connected to the mouse, converts the textual data into a Mouse + structure by calling eatomouse with the buffer and count from + the read call, and returns the number of bytes read, or –1 for + an error. +
+ + 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. Estartfn is + similar to estart, but processes the data received by calling + fn before returning the event to the user. The function fn is + called with the id of the event; it should return id if the event + is to be passed to the user, 0 if it is to be ignored. The variable + Event.v + can be used by fn to attach an arbitrary data item to the returned + Event structure.    Ekeyboard and Emouse are the keyboard and mouse + event keys. +
+ + Etimer starts a repeating timer with a period of 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. +
+ + Eread waits for the next event specified by the mask keys of event + keys submitted to estart. It fills in the appropriate field of + the argument Event structure, which looks like:
+ +
+ + struct Event
+ {
+ +
+ + int     kbdc;
+ Mouse mouse;
+ int     n;
+ void    *v;
+ uchar data[EMAXMSG];
+ +
+ };
+ +
+ + +
+ Data is an array which is large enough to hold a 9P message. Eread + returns the key for the event which was chosen. For example, if + a mouse event was read, Emouse will be returned. +
+ + Event waits for the next event of any kind. The return is the + same as for eread. +
+ + As described in graphics(3), the graphics functions are buffered. + Event, eread, emouse, and ekbd all cause a buffer flush unless + there is an event of the appropriate type already queued. +
+ + Ecanread checks whether a call to eread(keys) would block, returning + 0 if it would, 1 if it would not. +
+ + Getrect prompts the user to sweep a rectangle. It should be called + with m holding the mouse event that triggered the egetrect (or, + if none, a Mouse with buttons set to 7). It changes to the sweep + cursor, waits for the buttons all to be released, and then waits + for button number but to be pressed, marking the initial + corner. If another button is pressed instead, egetrect returns + a rectangle with zero for both corners, after waiting for all + the buttons to be released. Otherwise, egetrect continually draws + the swept rectangle until the button is released again, and returns + the swept rectangle. The mouse structure pointed to by m will + contain the final mouse event. +
+ + Egetrect uses successive calls to edrawgetrect to maintain the + red rectangle showing the sweep-in-progress. The rectangle to + be drawn is specified by rc and the up parameter says whether + to draw (1) or erase (0) the rectangle. +
+ + Emenuhit displays a menu and returns a selected menu item number. + It should be called with m holding the mouse event that triggered + the emenuhit; it will call emouse to update it. A Menu is a structure:
+ +
+ + struct Menu
+ {
+ +
+ + char    **item;
+ char    *(*gen)(int);
+ int     lasthit;
+ +
+ };
+ +
+ + +
+ If item is nonzero, it should be a null-terminated array of the + character strings to be displayed as menu items. Otherwise, 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. Menuhit + waits until but is released, and then returns the number of the + selection, or –1 for no selection. The m argument is filled in + with the final mouse event. +
+ + Emoveto moves the mouse cursor to the position p on the screen. + +
+ + Esetcursor changes the cursor image to that described by the Cursor + c (see mouse(3)). If c is nil, it restores the image to the default + arrow.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + rio(1), graphics(3), plumb(3), draw(3)
+ +
+

BUGS
+ +
+ + Etimer and estart are unimplemented.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/exec.html b/man/man3/exec.html new file mode 100644 index 00000000..e5397352 --- /dev/null +++ b/man/man3/exec.html @@ -0,0 +1,146 @@ + +exec(3) - Plan 9 from User Space + + + + +
+
+
EXEC(3)EXEC(3) +
+
+

NAME
+ +
+ + exec, execl – execute a file
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int exec(char *name, char* argv[])
+ +
+ + int execl(char *name, ...)
+ +
+

DESCRIPTION
+ +
+ + Exec and execl overlay the calling process with the named file, + then transfer to the entry point of the image of the file. +
+ + 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 stat(3)). It should also be a valid binary + image, as defined by the local operating system, or a shell script + (see rc(1)). The first line of a shell script must begin with + #! followed + by the name of the program to interpret the file and any initial + arguments to that program, for example
+ +
+ + #!/bin/rc
+ ls | mc
+ +
+ + +
+ When a C program is executed, it is called as follows:
+ +
+ + void main(int argc, char *argv[])
+ +
+ + +
+ Argv is a copy of the array of argument pointers passed to exec; + that array must end in a null pointer, and 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. Execl + is like exec except that argv will be an array of the parameters + that follow name in the call. The last argument to execl must + be a null pointer. +
+ + For a file beginning #!, the arguments passed to the program (/bin/rc + in the example above) will be the name of the file being executed, + any arguments on the #! line, the name of the file again, and + finally the second and subsequent arguments given to the original + exec call. The result honors the two conventions + of a program accepting as argument a file to be interpreted and + argv[0] naming the file being executed. +
+ + Most attributes of the calling process are carried into the result; + in particular, files remain open across exec (except those opened + with OCEXEC OR’d into the open mode; see open(3)); and the working + directory and environment (see getenv(3)) remain the same. However, + a newly exec’ed process has no notification + handlers (see notify(3)).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/exec.c
+ /usr/local/plan9/src/lib9/execl.c
+ +
+

SEE ALSO
+ +
+ + prof(1), intro(3), stat(3)
+ +
+

DIAGNOSTICS
+ +
+ + If these functions fail, they return and set errstr. There can + be no return from a successful exec or execl; the calling image + is lost.
+ +
+

BUGS
+ +
+ + On Unix, unlike on Plan 9, exec and execl use the user’s current + path to locate prog. This is a clumsy way to deal with Unix’s + lack of a union directory for /bin. +
+ + To avoid name conflicts with the underlying system, exec and execl + are preprocessor macros defined as p9exec and p9execl; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/exits.html b/man/man3/exits.html new file mode 100644 index 00000000..cc94a468 --- /dev/null +++ b/man/man3/exits.html @@ -0,0 +1,126 @@ + +exits(3) - Plan 9 from User Space + + + + +
+
+
EXITS(3)EXITS(3) +
+
+

NAME
+ +
+ + exits, _exits, atexit, atexitdont, terminate – terminate process, + process cleanup
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + void _exits(char *msg)
+ void exits(char *msg)
+ +
+ + int    atexit(void(*)(void))
+ +
+ + void atexitdont(void(*)(void))
+ +
+

DESCRIPTION
+ +
+ + Exits is the conventional way to terminate a process. _Exits also + terminates a process but does not call the registered atexit handlers + (q.v.). They can never return. +
+ + Msg conventionally includes a brief (maximum length 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 wait(3). +
+ + Before calling _exits with msg as an argument, exits calls in + reverse order all the functions recorded by atexit. +
+ + Atexit records fn as a function to be called by 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, exits only calls those atexit-registered + functions that were registered by the same process as that calling + exits. +
+ + Calling atexit twice (or more) with the same function argument + causes exits to invoke the function twice (or more). +
+ + There is a limit to the number of exit functions that will be + recorded; atexit returns 0 if that limit has been reached. +
+ + Atexitdont cancels a previous registration of an exit function.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/atexit.c
+ /usr/local/plan9/src/lib9/_exits.c
+ +
+

SEE ALSO
+ +
+ + fork(2), wait(3)
+ +
+

BUGS
+ +
+ + Because of limitations of Unix, the exit status of a process can + only be an 8-bit integer. Exit status 0 is used for empty exit + messages, and 1 for non-empty messages. +
+ + Exit codes 97 through 99 are used by the thread library to signal + internal synchronization errors between the main program and a + proxy process that implements backgrounding. +
+ + To avoid name conflicts with the underlying system, atexit and + atexitdont are preprocessor macros defined as p9atexit and p9atexitdont; + see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/fcall.html b/man/man3/fcall.html new file mode 100644 index 00000000..926b47dc --- /dev/null +++ b/man/man3/fcall.html @@ -0,0 +1,274 @@ + +fcall(3) - Plan 9 from User Space + + + + +
+
+
FCALL(3)FCALL(3) +
+
+

NAME
+ +
+ + Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, + read9pmsg, statcheck, sizeS2M, sizeD2M – interface to Plan 9 File + protocol
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h> +
+ + uint convS2M(Fcall *f, uchar *ap, uint nap) +
+ + uint convD2M(Dir *d, uchar *ap, uint nap) +
+ + uint convM2S(uchar *ap, uint nap, Fcall *f) +
+ + uint convM2D(uchar *ap, uint nap, Dir *d, char *strs) +
+ + int dirfmt(Fmt*) +
+ + int fcallfmt(Fmt*) +
+ + int dirmodefmt(Fmt*) +
+ + int read9pmsg(int fd, uchar *buf, uint nbuf) +
+ + int statcheck(uchar *buf, uint nbuf) +
+ + uint sizeS2M(Fcall *f) +
+ + uint sizeD2M(Dir *d)
+ +
+

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 Fcall structure: +
+ + #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;
+ /* 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
+ +
+ + This structure is defined in <fcall.h>. See section 5 for a full + description of 9P messages and their encoding. For all message + types, the type field of an Fcall holds one of Tversion, Rversion, + Tattach, Rattach, etc. (defined in an enumerated type in <fcall.h>). + Fid is used by most messages, and + tag is used by all messages. The other fields are used selectively + by the message types given in comments. +
+ + ConvM2S takes a 9P message at ap of length nap, and uses it to + fill in Fcall structure f. If the passed message including any + data for Twrite and Rread messages is formatted properly, the + return value is the number of bytes the message occupied in the + buffer ap, which will always be less than or equal to nap; + otherwise it is 0. For Twrite and Tread messages, data is set + to a pointer into the argument message, not a copy. +
+ + ConvS2M does the reverse conversion, turning f into a message + starting at ap. The length of the resulting message is returned. + For Twrite and Rread messages, count bytes starting at data are + copied into the message. +
+ + The constant IOHDRSZ is a suitable amount of buffer to reserve + for storing the 9P header; the data portion of a Twrite or Rread + will be no more than the buffer size negotiated in the Tversion/Rversion + exchange, minus IOHDRSZ. +
+ + The routine sizeS2M returns the number of bytes required to store + the machine-independent representation of the Fcall structure + f, including its initial 32-bit size field. In other words, it + reports the number of bytes produced by a successful call to convS2M. + +
+ + Another structure is Dir, used by the routines described in stat(3). + ConvM2D converts the machine-independent form starting at ap into + d and returns the length of the machine-independent encoding. + The strings in the returned Dir structure are stored at successive + locations starting at strs. Usually strs will + point to storage immediately after the Dir itself. It can also + be a nil pointer, in which case the string pointers in the returned + Dir are all nil; however, the return value still includes their + length. +
+ + ConvD2M does the reverse translation, also returning the length + of the encoding. If the buffer is too short, the return value + will be BIT16SZ and the correct size will be returned in the first + BIT16SZ bytes. (If the buffer is less that BIT16SZ, the return + value is zero; therefore a correct test for complete packing of + the + message is that the return value is greater than BIT16SZ). The + macro GBIT16 can be used to extract the correct value. The related + macros with different sizes retrieve the corresponding-sized quantities. + PBIT16 and its brethren place values in messages. With the exception + of handling short buffers in convD2M, + these macros are not usually needed except by internal routines. + +
+ + Analogous to sizeS2M, sizeD2M returns the number of bytes required + to store the machine-independent representation of the Dir structure + d, including its initial 16-bit size field. +
+ + The routine statcheck checks whether the nbuf bytes of buf contain + a validly formatted machine-independent Dir entry suitable as + an argument, for example, for the wstat (see stat(3)) system call. + It checks that the sizes of all the elements of the the entry + sum to exactly nbuf, which is a simple but effective test + of validity. Nbuf and buf should include the second two-byte (16-bit) + length field that precedes the entry when formatted in a 9P message + (see stat(9p)); in other words, nbuf is 2 plus the sum of the + sizes of the entry itself. Statcheck also verifies that the length + field has the correct value (that is, nbuf−2). It returns 0 + for a valid entry and −1 for an incorrectly formatted entry. +
+ + Dirfmt, fcallfmt, and dirmodefmt are formatting routines, suitable + for fmtinstall(3). They convert Dir*, Fcall*, and long values + into string representations of the directory buffer, Fcall buffer, + or file mode value. Fcallfmt assumes that dirfmt has been installed + with format letter D and dirmodefmt with format + letter M. +
+ + Read9pmsg calls read(3) multiple times, if necessary, to read + an entire 9P message into buf. The return value is 0 for end of + file, or -1 for error; it does not return partial messages.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + intro(3), 9p(3), stat(3), intro(9p)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/flate.html b/man/man3/flate.html new file mode 100644 index 00000000..41591034 --- /dev/null +++ b/man/man3/flate.html @@ -0,0 +1,333 @@ + +flate(3) - Plan 9 from User Space + + + + +
+
+
FLATE(3)FLATE(3) +
+
+

NAME
+ +
+ + deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, + inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, + flateerr, mkcrctab, blockcrc, adler32 – deflate compression
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <flate.h> +
+ + +
+ + int      deflateinit(void) +
+ + int      deflate(void *wr, int (*w)(void*,void*,int),
+ +
+ + +
+ + void *rr, int (*r)(void*,void*,int),
+ int level, int debug) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      deflatezlib(void *wr, int (*w)(void*,void*,int),
+ +
+ + +
+ + void *rr, int (*r)(void*,void*,int),
+ int level, int debug) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      deflateblock(uchar *dst, int dsize,
+ +
+ + +
+ + uchar *src, int ssize,
+ int level, int debug) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      deflatezlibblock(uchar *dst, int dsize,
+ +
+ + +
+ + uchar *src, int ssize,
+ int level, int debug) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      inflateinit(void) +
+ + int      inflate(void *wr, int (*w)(void*, void*, int),
+ +
+ + +
+ + void *getr, int (*get)(void*)) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      inflatezlib(void *wr, int (*w)(void*, void*, int),
+ +
+ + +
+ + void *getr, int (*get)(void*)) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      inflateblock(uchar *dst, int dsize,
+ +
+ + +
+ + uchar *src, int ssize) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int      inflatezlibblock(uchar *dst, int dsize,
+ +
+ + +
+ + uchar *src, int ssize) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ char     *flateerr(int error) +
+ + ulong    *mkcrctab(ulong poly) +
+ + ulong    blockcrc(ulong *tab, ulong crc, void *buf, int n) +
+ + ulong    adler32(ulong adler, void *buf, int n)
+ +
+

DESCRIPTION
+ +
+ + These routines compress and decompress data using the deflate + compression algorithm, which is used for most gzip, zip, and zlib + files. +
+ + Deflate compresses input data retrieved by calls to r with arguments + rr, an input buffer, and a count of bytes to read. 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 w with arguments wr, the + output data, and the number of bytes to write. W should return + the number of bytes written; writing fewer than the requested + number of bytes is an error. Level indicates the amount of computation + deflate should do while compressing the data. Higher levels usually + take more time and produce smaller outputs. Valid + values are 1 to 9, inclusive; 6 is a good compromise. If debug + is non-zero, cryptic debugging information is produced on standard + error. +
+ + Inflate reverses the process, converting compressed data into + uncompressed output. Input is retrieved one byte at a time by + calling get with the argument getr. End of input of signaled by + returning a negative value. The uncompressed output is written + to w, which has the same interface as for deflate. +
+ + Deflateblock and inflateblock operate on blocks of memory but + are otherwise similar to deflate and inflate. +
+ + The zlib functions are similar, but operate on files with a zlib + header and trailer. +
+ + Deflateinit or inflateinit must be called once before any call + to the corresponding routines. +
+ + If the above routines fail, they return a negative number indicating + the problem. The possible values are FlateNoMem, FlateInputFail, + FlateOutputFail, FlateCorrupted, and FlateInternal. Flateerr converts + the number into a printable message. FlateOk is defined to be + zero, the successful return value for deflateinit, + deflate, deflatezlib, inflateinit, inflate, and inflatezlib. The + block functions return the number of bytes produced when they + succeed. +
+ + Mkcrctab allocates (using malloc(3)), initializes, and returns + a table for rapid computation of 32 bit CRC values using the polynomial + poly. Blockcrc uses tab, a table returned by mkcrctab, to update + crc for the n bytes of data in buf, and returns the new value. + Crc should initially be zero. Blockcrc pre-conditions and + post-conditions crc by ones complementation. +
+ + Adler32 updates the Adler 32-bit checksum of the n butes of data + in buf. The initial value of adler (that is, its value after seeing + zero bytes) should be 1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libflate
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/fmtinstall.html b/man/man3/fmtinstall.html new file mode 100644 index 00000000..848c1333 --- /dev/null +++ b/man/man3/fmtinstall.html @@ -0,0 +1,339 @@ + +fmtinstall(3) - Plan 9 from User Space + + + + +
+
+
FMTINSTALL(3)FMTINSTALL(3) +
+
+

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
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + typedef struct Fmt    Fmt;
+ struct Fmt{
+ +
+ + uchar     runes;    /* output buffer is runes or chars? */
+ void      *start; /* of buffer */
+ void      *to;      /* current place in the buffer */
+ void      *stop;    /* end of the buffer; overwritten if flush fails */
+ int       (*flush)(Fmt*);/* called when to == stop */
+ void      *farg;    /* to make flush a closure */
+ int       nfmt;     /* num chars formatted so far */
+ va_list args;     /* args passed to dofmt */
+ int       r;        /* % format Rune */
+ int       width;
+ int       prec;
+ ulong     flags;
+ +
+ };
+ enum{
+ +
+ + FmtWidth      = 1,
+ FmtLeft       = FmtWidth << 1,
+ FmtPrec       = FmtLeft << 1,
+ FmtSharp      = FmtPrec << 1,
+ FmtSpace      = FmtSharp << 1,
+ FmtSign       = FmtSpace << 1,
+ FmtZero       = FmtSign << 1,
+ FmtUnsigned = FmtZero << 1,
+ FmtShort      = FmtUnsigned << 1,
+ FmtLong       = FmtShort << 1,
+ FmtVLong      = FmtLong << 1,
+ FmtComma      = FmtVLong << 1,
+ FmtFlag       = FmtComma << 1
+ +
+ };
+ +
+ + +
+ + int     fmtfdinit(Fmt *f, int fd, char *buf, int nbuf); +
+ + int     fmtfdflush(Fmt *f); +
+ + int     fmtstrinit(Fmt *f); +
+ + char* fmtstrflush(Fmt *f); +
+ + int     runefmtstrinit(Fmt *f); +
+ + Rune* runefmtstrflush(Fmt *f);
+ +
+ + int     fmtinstall(int c, int (*fn)(Fmt*)); +
+ + int     dofmt(Fmt *f, char *fmt); +
+ + int     dorfmt(Fmt*, Rune *fmt); +
+ + int     fmtprint(Fmt *f, char *fmt, ...); +
+ + int     fmtvprint(Fmt *f, char *fmt, va_list v); +
+ + int     fmtrune(Fmt *f, int r); +
+ + int     fmtstrcpy(Fmt *f, char *s); +
+ + int     fmtrunestrcpy(Fmt *f, Rune *s); +
+ + int     errfmt(Fmt *f);
+ +
+

DESCRIPTION
+ +
+ + The interface described here allows the construction of custom + print(3) verbs and output routines. In essence, they provide access + to the workings of the formatted print code. +
+ + The print(3) suite maintains its state with a data structure called + Fmt. A typical call to print(3) or its relatives initializes a + Fmt structure, passes it to subsidiary routines to process the + output, and finishes by emitting any saved state recorded in the + Fmt. The details of the Fmt are unimportant to outside users, + except + insofar as the general design influences the interface. The 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 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.
+

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. +
+ + To write to a file descriptor, call fmtfdinit to initialize the + local Fmt structure f, giving the file descriptor fd, the buffer + buf, and its size nbuf. Then call fmtprint or fmtvprint to generate + the output. These behave like fprint (see print(3)) or vfprint + except that the characters are buffered until fmtfdflush is called + and the return value is either 0 or –1. A typical example of this + sequence appears in the Examples section. +
+ + The same basic sequence applies when outputting to an allocated + string: call fmtstrinit to initialize the Fmt, then call fmtprint + and fmtvprint to generate the output. Finally, fmtstrflush will + return the allocated string, which should be freed after use. + To output to a rune string, use runefmtstrinit and runefmtstrflush. + Regardless of the output style or type, fmtprint or fmtvprint + generates the characters.
+

Custom format verbs
+ Fmtinstall is used to install custom verbs and flags labeled by + character c, which may be any non-zero Unicode character. Fn should + be declared as
+ +
+ + int     fn(Fmt*)
+ +
+ + +
+ Fp−>r is the flag or verb character to cause fn to be called. In + fn, fp−>width, fp−>prec are the width and precision, and fp−>flags + the decoded flags for the verb (see print(3) for a description + of these items). The standard flag values are: FmtSign (+), FmtLeft + (−), FmtSpace (' '), FmtSharp (#), + FmtComma (,), FmtLong (l), FmtShort (h), FmtUnsigned (u), and + FmtVLong (ll). The flag bits FmtWidth and FmtPrec identify whether + a width and precision were specified. +
+ + Fn is passed a pointer to the Fmt structure recording the state + of the output. If fp−>r is a verb (rather than a flag), fn should + use Fmt−>args to fetch its argument from the list, then format + it, and return zero. If fp−>r is a flag, fn should return one. + All interpretation of fp−>width, fp−>prec, and fp->flags is + left up to the conversion routine. Fmtinstall returns 0 if the + installation succeeds, –1 if it fails. +
+ + Fmtprint and 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. +
+ + The functions dofmt and dorfmt are the underlying formatters; + they use the existing contents of Fmt and should be called only + by sophisticated conversion routines. These routines return the + number of characters (bytes of UTF or runes) produced. +
+ + Some internal functions may be useful to format primitive types. + They honor the width, precision and flags as described in print(3). + Fmtrune formats a single character r. Fmtstrcpy formats a string + s; fmtrunestrcpy formats a rune string s. 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.
+ +

+

EXAMPLES
+ +
+ + This function prints an error message with a variable number of + arguments and then quits. Compared to the corresponding example + in print(3), this version uses a smaller buffer, will never truncate + the output message, but might generate multiple write system calls + to produce its output. + +
+ + #pragma    varargck argpos    error     1
+ void fatal(char *fmt, ...)
+ {
+ +
+ + Fmt f;
+ char buf[64];
+ va_list arg;
+ fmtfdinit(&f, 1, buf, sizeof buf);
+ fmtprint(&f, "fatal: ");
+ va_start(arg, fmt);
+ fmtvprint(&f, fmt, arg);
+ va_end(arg);
+ fmtprint(&f, "\n");
+ fmtfdflush(&f);
+ exits("fatal error");
+ +
+ }
+ +
+ + +
+ This example adds a verb to print complex numbers.
+ +
+ + typedef
+ struct {
+ +
+ + double    r, i;
+ +
+ } Complex;
+ #pragma    varargck type "X" Complex
+ int
+ Xfmt(Fmt *f)
+ {
+ +
+ + Complex c;
+ c = va_arg(f−>args, Complex);
+ return fmtprint(f, "(%g,%g)", c.r, c.i);
+ +
+ }
+ main(...)
+ {
+ +
+ + Complex x = (Complex){ 1.5, −2.3 };
+ fmtinstall('X', Xfmt);
+ print("x = %X\n", x);
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/fmt
+ +
+

SEE ALSO
+ +
+ + print(3), utf(7), errstr(3)
+ +
+

DIAGNOSTICS
+ +
+ + These routines return negative numbers or nil for errors and set + errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/frame.html b/man/man3/frame.html new file mode 100644 index 00000000..4a80453c --- /dev/null +++ b/man/man3/frame.html @@ -0,0 +1,325 @@ + +frame(3) - Plan 9 from User Space + + + + +
+
+
FRAME(3)FRAME(3) +
+
+

NAME
+ +
+ + frinit, frsetrects, frinittick, frclear, frcharofpt, frptofchar, + frinsert, frdelete, frselect, frtick, frselectpaint, frdrawsel, + frdrawsel0, frgetmouse – frames of text
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <thread.h>
+ #include <mouse.h>
+ #include <frame.h>
+ +
+ + void    frinit(Frame *f, Rectangle r, Font *ft, Image *b, Image **cols)
+ +
+ + void    frsetrects(Frame *f, Rectangle r, Image *b)
+ +
+ + void    frinittick(Frame *f)
+ +
+ + void    frclear(Frame *f, int resize)
+ +
+ + ulong frcharofpt(Frame *f, Point pt)
+ +
+ + Point frptofchar(Frame *f, ulong p)
+ +
+ + void    frinsert(Frame *f, Rune *r0, Rune *r1, ulong p)
+ +
+ + int     frdelete(Frame *f, ulong p0, ulong p1)
+ +
+ + void    frselect(Frame *f, Mousectl *m)
+ +
+ + void    frtick(Frame *f, Point pt, int up)
+ +
+ + void    frselectpaint(Frame *f, Point p0, Point p1, Image *col)
+ +
+ + void    frdrawsel(Frame *f, Point pt0, ulong p0, ulong p1,
+ +
+ + +
+ + int highlighted)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void    frdrawsel0(Frame *f, Point pt0, ulong p0, ulong p1,
+ +
+ + +
+ + Image *back, Image *text)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ enum{
+ +
+ + BACK,
+ HIGH,
+ BORD,
+ TEXT,
+ HTEXT,
+ NCOL
+ +
+ };
+ +
+

DESCRIPTION
+ +
+ + This library supports frames of editable text in a single font + on raster displays, such as in sam(1) and 9term(1). Frames may + hold any character except NUL (0). Long lines are folded and tabs + are at fixed intervals. +
+ + The user-visible data structure, a Frame, is defined in <frame.h>:
+ +
+ + 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? */
+ +
+ };
+ +
+ + +
+ Frbox is an internal type and is not used by the interface. P0 + and p1 may be changed by the application provided the selection + routines are called afterwards to maintain a consistent display. + Maxtab determines the size of tab stops. Frinit sets it to 8 times + the width of a 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. +
+ + 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 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 Frame; the application must + check maxlines, nlines, and lastlinefull to determine, for example, + whether new text needs to be appended at the + end of the Frame after calling frdelete (q.v.). +
+ + There are no routines in the library to allocate Frames; instead + the interface assumes that Frames will be components of larger + structures. Frinit prepares the Frame f so characters drawn in + it will appear in the single Font ft. It then calls frsetrects + and frinittick to initialize the geometry for the Frame. The Image + b is where the Frame is to be drawn; Rectangle r defines the limit + of the portion of the Image the text will occupy. The Image pointer + may be null, allowing the other routines to be called to maintain + the associated data structure in, for example, an obscured window. + +
+ + The array of Images cols sets the colors in which text and borders + will be drawn. The background of the frame will be drawn in cols[BACK]; + the background of highlighted text in cols[HIGH]; borders and + scroll bar in cols[BORD]; regular text in cols[TEXT]; and highlighted + text in cols[HTEXT]. +
+ + Frclear frees the internal structures associated with f, permitting + another frinit or frsetrects on the Frame. It does not clear the + associated display. If f is to be deallocated, the associated + Font and Image must be freed separately. The 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. +
+ + To resize a Frame, use frclear and frinit and then frinsert (q.v.) + to recreate the display. If a Frame is being moved but not resized, + that is, if the shape of its containing rectangle is unchanged, + it is sufficient to use draw(3) to copy the containing rectangle + from the old to the new location and then call frsetrects to + establish the new geometry. (It is unnecessary to call frinittick + unless the font size has changed.) No redrawing is necessary. + +
+ + Frames hold text as runes, not as bytes. Frptofchar returns the + location of the upper left corner of the p’th rune, starting from + 0, in the Frame f. If f holds fewer than p runes, frptofchar returns + the location of the upper right corner of the last character in + f. 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 + pt. +
+ + Frinsert inserts into Frame f starting at rune index p the runes + between r0 and 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 + frdelete. +
+ + Frdelete deletes from the Frame the text between p0 and p1; p1 + points at the first rune beyond the deletion. +
+ + Frselect tracks the mouse to select a contiguous string of text + in the Frame. When called, a mouse button is typically down. Frselect + will return when the button state has changed (some buttons may + still be down) and will set f−>p0 and f−>p1 to the selected range + of text. +
+ + 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. Frtick + draws (if up is non-zero) or removes (if up is zero) the tick + at + the screen position indicated by pt. Frdrawsel repaints a section + of the frame, delimited by character positions p0 and p1, either + with plain background or entirely highlighted, according to the + flag highlighted, managing the tick appropriately. The point pt0 + is the geometrical location of p0 on the screen; like all of the + selection-helper routines’ Point arguments, it must be a value + generated by frptofchar. Frdrawsel0 is a lower-level routine, + taking as arguments a background color, back, and text color, + text. It assumes that the tick is being handled (removed beforehand, + replaced afterwards, as required) by its caller. Frselectpaint + uses a solid color, col, to paint a region of the frame defined + by the Points p0 and p1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libframe
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), cachechars(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/genrandom.html b/man/man3/genrandom.html new file mode 100644 index 00000000..0cddd21d --- /dev/null +++ b/man/man3/genrandom.html @@ -0,0 +1,84 @@ + +genrandom(3) - Plan 9 from User Space + + + + +
+
+
GENRANDOM(3)GENRANDOM(3) +
+
+

NAME
+ +
+ + genrandom, prng – random number generation
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void genrandom(uchar *buf, int nbytes) +
+ + void prng(uchar *buf, int nbytes)
+ +
+

DESCRIPTION
+ +
+ + Most security software requires a source of random or, at the + very least, unguessable numbers. +
+ + 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 via truerand (see rand(3)). +
+ + Prng uses the native rand(3) pseudo-random number generator to + fill the buffer. Used with srand, this function can produce a + reproducible stream of pseudo random numbers useful in testing. + +
+ + Both functions may be passed to mprand (see mp(3)).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/get9root.html b/man/man3/get9root.html new file mode 100644 index 00000000..6ca02c02 --- /dev/null +++ b/man/man3/get9root.html @@ -0,0 +1,109 @@ + +get9root(3) - Plan 9 from User Space + + + + +
+
+
GET9ROOT(3)GET9ROOT(3) +
+
+

NAME
+ +
+ + get9root, unsharp – get path to root of Plan 9 tree
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char*       get9root(void) +
+ + char*       unsharp(char *path)
+ +
+

DESCRIPTION
+ +
+ + This tree of Plan 9 software is conventionally installed in /usr/local/plan9 + but may be installed in other places (for example, users without + the ability to write to /usr/local may with to install it in their + own home directories). The environment variable $PLAN9 should + contain the path to the root. Get9root + returns a static pointer to the pathname of root, first checking + $PLAN9 and defaulting to /usr/local/plan9. +
+ + The lack of a fixed location for the Plan 9 tree makes it difficult + to hard-code paths to files. Unsharp replaces a leading #9 in + path with the root of the tree. Unsharp also replaces a leading + #d with the path to the underlying system’s file descriptor dup + device, typically /dev/fd. The string returned from unsharp, if + different from path, should be freed with free (see malloc(3)) + when no longer needed. +
+ + As a convention, programs should never unsharp paths obtained + from user input.
+ +
+

EXAMPLE
+ +
+ + The plumber(4) uses this code to find unrooted file names included + by plumb rules.
+ +
+ + snprint(buf, sizeof buf, "#9/plumb/%s", name);
+ fd = open(unsharp(buf), OREAD);
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getns.c
+ +
+

SEE ALSO
+ +
+ + intro(4)
+ +
+

BUGS
+ +
+ + Get9root could be smarter about finding the tree when $PLAN9 is + not set.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getcallerpc.html b/man/man3/getcallerpc.html new file mode 100644 index 00000000..72a835d1 --- /dev/null +++ b/man/man3/getcallerpc.html @@ -0,0 +1,99 @@ + +getcallerpc(3) - Plan 9 from User Space + + + + +
+
+
GETCALLERPC(3)GETCALLERPC(3) +
+
+

NAME
+ +
+ + getcallerpc – fetch return PC of current function
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + ulong getcallerpc(void *firstarg)
+ +
+

DESCRIPTION
+ +
+ + Getcallerpc is a portable way to discover the PC to which the + current function will return. Firstarg should be a pointer to + the first argument to the function in question.
+ +
+

EXAMPLE
+ +
+ + +
+ + void
+ printpc(ulong arg)
+ {
+ +
+ + print("Called from %.8lux\n", getcallerpc(&arg));
+ +
+ }
+ void
+ main(int argc, char *argv[])
+ {
+ +
+ + printpc(0);
+ printpc(0);
+ printpc(0);
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/
+ +
+

BUGS
+ +
+ + The firstarg parameter should not be necessary.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getenv.html b/man/man3/getenv.html new file mode 100644 index 00000000..5b51354c --- /dev/null +++ b/man/man3/getenv.html @@ -0,0 +1,79 @@ + +getenv(3) - Plan 9 from User Space + + + + +
+
+
GETENV(3)GETENV(3) +
+
+

NAME
+ +
+ + getenv, putenv – access environment variables
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char* getenv(char *name)
+ int     putenv(char *name, char *val)
+ +
+

DESCRIPTION
+ +
+ + Getenv fetches the environment value associated with name into + memory allocated with malloc(3), 0-terminates it, and returns + a pointer to that area. If no file exists, 0 is returned. +
+ + Putenv sets the environment value associated with name to val.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getenv.c
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, getenv and + putenv are preprocessor macros defined as p9getenv and p9putenv; + see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getfields.html b/man/man3/getfields.html new file mode 100644 index 00000000..7c1d8f64 --- /dev/null +++ b/man/man3/getfields.html @@ -0,0 +1,136 @@ + +getfields(3) - Plan 9 from User Space + + + + +
+
+
GETFIELDS(3)GETFIELDS(3) +
+
+

NAME
+ +
+ + getfields, gettokens, tokenize – break a string into fields
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int     getfields(char *str, char **args, int maxargs, int multiflag,
+ +
+ + +
+ + char *delims) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int     gettokens(char *str, char **args, int maxargs, char *delims) + +
+ + int     tokenize(char *str, char **args, int maxargs)
+ +
+

DESCRIPTION
+ +
+ + Getfields places into the array args pointers to the first maxargs + fields of the null terminated UTF string str. Delimiters between + these fields are set to null. +
+ + Fields are substrings of str whose definition depends on the value + of multiflag. If multiflag is zero, adjacent fields are separated + by exactly one delimiter. For example
+ +
+ + +
+ + getfields("#alice#bob##charles###", arg, 3, 0, "#");
+ +
+ +
+ yields three substrings: null-string , alice, and bob##charles###. + If the multiflag argument is not zero, a field is a non-empty + string of non-delimiters. For example
+ +
+ + +
+ + getfields("#alice#bob##charles###", arg, 3, 1, "#");
+ +
+ +
+ yields the three substrings: alice, bob, and charles###. +
+ + Getfields returns the number of fields pointed to. +
+ + Gettokens is the same as getfields with multiflag non-zero, except + that fields may be quoted using single quotes, in the manner of + rc(1). See quote(3) for related quote-handling software. +
+ + Tokenize is gettokens with delims set to "\t\r\n ".
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/tokenize.c
+ +
+

SEE ALSO
+ +
+ + strtok in strcat(3), quote(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getns.html b/man/man3/getns.html new file mode 100644 index 00000000..e5da2bb2 --- /dev/null +++ b/man/man3/getns.html @@ -0,0 +1,67 @@ + +getns(3) - Plan 9 from User Space + + + + +
+
+
GETNS(3)GETNS(3) +
+
+

NAME
+ +
+ + getns – get path to name space directory
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char*       getns(void)
+ +
+

DESCRIPTION
+ +
+ + Getns returns a pointer to a malloced string that contains the + path to the name space directory for the current process. The + name space directory is a clumsy substitute for Plan 9’s per-process + name spaces; see intro(4) for details.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getns.c
+ +
+

SEE ALSO
+ +
+ + intro(4)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getsnarf.html b/man/man3/getsnarf.html new file mode 100644 index 00000000..3f3e7512 --- /dev/null +++ b/man/man3/getsnarf.html @@ -0,0 +1,73 @@ + +getsnarf(3) - Plan 9 from User Space + + + + +
+
+
GETSNARF(3)GETSNARF(3) +
+
+

NAME
+ +
+ + getsnarf, putsnarf – window system snarf (cut and paste) buffer
+ +
+

SYNOPSIS
+ +
+ + #include <draw.h> +
+ + char *getsnarf(void) +
+ + void putsnarf(char *text)
+ +
+

DESCRIPTION
+ +
+ + Getsnarf and putsnarf access the window system’s snarf (cut and + paste) buffer. +
+ + Getsnarf returns a copy of the current buffer; the returned pointer + should be freed with free (see malloc(3)) when no longer needed. + +
+ + Putsnarf sets the buffer to the text string text. +
+ + Callers should assume that the snarf buffer is UTF. If the window + system does not keep the buffer in UTF, getsnarf and putsnarf + will convert as necessary.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw/x11−itrans.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getuser.html b/man/man3/getuser.html new file mode 100644 index 00000000..c34b23cf --- /dev/null +++ b/man/man3/getuser.html @@ -0,0 +1,75 @@ + +getuser(3) - Plan 9 from User Space + + + + +
+
+
GETUSER(3)GETUSER(3) +
+
+

NAME
+ +
+ + getuser, sysname – get user or system name
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char*       getuser(void) +
+ + char*       sysname(void)
+ +
+

DESCRIPTION
+ +
+ + Getuser returns a pointer to static data which contains the null-terminated + name of the user who owns the current process. Getuser calls getuid(2) + and then reads /etc/passwd to find the corresponding name. +
+ + Sysname returns a pointer to static data which contains the name + of the machine on which the current process is running. Sysname + looks first for an environment variable $sysname. If there is + no such variable, sysname calls gethostname(2) and truncates the + returned name at the first dot. If gethostname fails, + sysname returns the default name gnot. +
+ + Unlike getuser, sysname caches the string, deriving the host name + only once.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getuser.c
+ /usr/local/plan9/src/lib9/sysname.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/getwd.html b/man/man3/getwd.html new file mode 100644 index 00000000..1f5d2288 --- /dev/null +++ b/man/man3/getwd.html @@ -0,0 +1,84 @@ + +getwd(3) - Plan 9 from User Space + + + + +
+
+
GETWD(3)GETWD(3) +
+
+

NAME
+ +
+ + getwd – get current directory
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char* getwd(char *buf, int size)
+ +
+

DESCRIPTION
+ +
+ + Getwd fills buf with a null-terminated string representing the + current directory and returns buf. +
+ + Getwd places no more than size bytes in the buffer provided.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/getwd.c
+ +
+

SEE ALSO
+ +
+ + pwd(1)
+ +
+

DIAGNOSTICS
+ +
+ + On error, zero is returned. Errstr(3) may be consulted for more + information.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, getwd is a + preprocessor macro defined as p9getwd; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/graphics.html b/man/man3/graphics.html new file mode 100644 index 00000000..92f08c00 --- /dev/null +++ b/man/man3/graphics.html @@ -0,0 +1,592 @@ + +graphics(3) - Plan 9 from User Space + + + + +
+
+
GRAPHICS(3)GRAPHICS(3) +
+
+

NAME
+ +
+ + Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, + initdisplay, closedisplay, getdefont, getwindow, gengetwindow, + flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, + cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, + chantostr, chantodepth – interactive graphics + +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <cursor.h>
+ +
+ + int     initdraw(void (*errfun)(Display*, char*), char *font,
+ +
+ + +
+ + char *label)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int     geninitdraw(char *devdir, void(*errfun)(Display*, char*),
+ +
+ + +
+ + +
+ + char *font, char *label, char *mousedir, char *windir,
+ int ref)
+ +
+ + +
+ +
+ int     newwindow(char *str)
+ +
+ + void    drawerror(Display *d, char *msg)
+ +
+ + Display*initdisplay(char *devdir, char *win, void(*errfun)(Display*, + char*))
+ +
+ + void    closedisplay(Display *d)
+ +
+ + Font* getdefont(Display *d)
+ +
+ + int     flushimage(Display *d, int vis)
+ +
+ + int     bufimage(Display *d, int n)
+ +
+ + int     lockdisplay(Display *d)
+ +
+ + int     unlockdisplay(Display *d)
+ +
+ + int     getwindow(Display *d, int ref)
+ +
+ + int     gengetwindow(Display *d, char *winname,
+ +
+ + +
+ + Image **ip, Screen **sp, int ref)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void    cursorswitch(Cursor *curs)
+ +
+ + void    cursorset(Point p)
+ +
+ + Font* openfont(Display *d, char *name)
+ +
+ + Font* buildfont(Display *d, char *desc, char *name)
+ +
+ + void    freefont(Font *f)
+ +
+ + int     Pfmt(Fmt*)
+ +
+ + int     Rfmt(Fmt*)
+ +
+ + ulong strtochan(char *s)
+ +
+ + char* chantostr(char *s, ulong chan)
+ +
+ + int     chantodepth(ulong chan)
+ +
+ + extern Display *display
+ +
+ + extern Image     *screen
+ +
+ + extern Screen     *_screen
+ +
+ + extern Font      *font
+ +
+

DESCRIPTION
+ +
+ + A Display structure represents a connection to the graphics device, + 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:
+ +
+ + typedef
+ struct Display
+ {
+ +
+ + ...
+ void     (*error)(Display*, char*);
+ ...
+ Image    *black;
+ Image    *white;
+ Image    *opaque;
+ Image    *transparent;
+ Image    *image;
+ Font     *defaultfont;
+ Subfont*defaultsubfont;
+ ...
+ +
+ };
+ +
+ + +
+ A Point is a location in an Image (see below and draw(3)), such + as the display, and is defined as:
+ +
+ + typedef
+ struct Point {
+ +
+ + int x;
+ int y;
+ +
+ } Point;
+ +
+ + +
+ The coordinate system has x increasing to the right and y increasing + down. +
+ + A Rectangle is a rectangular area in an image.
+ +
+ + typedef
+ struct Rectangle {
+ +
+ + Point min;        /* upper left */
+ Point max;        /* lower right */
+ +
+ } Rectangle;
+ +
+ + +
+ By definition, min.x≤max.x and min.y≤max.y. By convention, the right + (maximum x) and bottom (maximum y) edges are excluded from the + represented rectangle, so abutting rectangles have no points in + common. Thus, max contains the coordinates of the first point + beyond the rectangle. +
+ + The Image data structure is defined in draw(3). +
+ + A Font is a set of character images, indexed by runes (see utf(7)). + The images are organized into 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 cachechars(3), + is immaterial for most applications. Font and + Subfont structures contain two interrelated fields: ascent, the + distance from the top of the highest character (actually the top + of the image holding all the characters) to the baseline, and + height, the distance from the top of the highest character to + the bottom of the lowest character (and hence, the interline + spacing). See cachechars(3) for more details. +
+ + Buildfont parses the font description in the buffer desc, returning + a Font* pointer that can be used by string (see draw(3)) to draw + characters from the font. Openfont does the same, but reads the + description from the named file. Freefont frees a font. The convention + for naming font files is: + +
+ + /lib/font/bit/name/range.size.font +
+ + +
+ where size is approximately the height in pixels of the lower + case letters (without ascenders or descenders). Range gives some + indication of which characters will be available: for example + ascii, latin1, euro, or unicode. Euro includes most European languages, + punctuation marks, the International Phonetic + Alphabet, etc., but no Oriental languages. Unicode includes every + character for which appropriate-sized images exist on the system. + +
+ + A Cursor is defined:
+ +
+ + typedef struct
+ Cursor {
+ +
+ + Point offset;
+ uchar clr[2*16];
+ uchar set[2*16];
+ +
+ } Cursor;
+ +
+ + +
+ 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 offset to the current mouse + position, using clr as a mask to draw white at the pixels where + clr is one, and then drawing black at the pixels where set + is one. +
+ + The routine initdraw connects to the display; it returns –1 if + it fails and sets the error string. Initdraw sets up the global + variables display (the Display structure representing the connection), + screen (an Image representing the display memory itself or, if + rio(1) is running, the client’s window), and font (the + default font for text). The arguments to initdraw include a label, + which is written to /dev/label if non-nil so that it can be used + to identify the window when hidden (see rio(1)). The font is created + by reading the named font file. If font is null, initdraw reads + the file named in the environment variable $font; if + $font is not set, it imports the default (usually minimal) font + from the operating system. The global font will be set to point + to the resulting Font structure. The errfun argument is a 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 errfun is nil, the library provides a + default, called drawerror. Another effect of initdraw is that + it installs print(3) formats Pfmt and Rfmt as %P and %R for printing + Points and Rectangles. +
+ + The geninitdraw function provides a less automated way to establish + a connection, for programs that wish to connect to multiple displays. + Devdir is the name of the directory containing the device files + for the display (if nil, default /dev); errfun, font, and label + are as in initdraw; mousedir and windir are the directories + holding the mouse and winname files; and ref specifies the refresh + function to be used to create the window, if running under rio(1) + (see window(3)). +
+ + Initdisplay is part of geninitdraw; it sets up the display structures + but does not allocate any fonts or call getwindow. The arguments + are similar to those of initdraw; win names the directory, default + /dev, in which the files associated with the window reside. Closedisplay + disconnects the display and frees the associated + data structures. Getdefont builds a Font structure from in-core + data describing a default font. None of these routines is needed + by most programs, since initdraw calls them as needed. +
+ + 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 + display−>locking to 1, to notify the library to use a locking protocol + for its own accesses, and call lockdisplay and + unlockdisplay around any calls to the graphics library that will + cause messages to be sent to the display device. Initdraw and + geninitdraw initialize the display to the locked state. +
+ + Getwindow returns a pointer to the window associated with the + application; it is called automatically by initdraw to establish + the screen pointer but must be called after each resizing of the + window to restore the library’s connection to the window. If rio + is not running, it returns display−>image; otherwise it + negotiates with rio by looking in /dev/winname to find the name + of the window and opening it using namedimage (see allocimage(3)). + The resulting window will be created using the refresh method + ref (see window(3)); this should almost always be Refnone because + rio provides backing store for the window. +
+ + Getwindow overwrites the global variables screen, a pointer to + the Image defining the window (or the overall display, if no window + system is running); and _screen, a pointer to the Screen representing + the root of the window’s hierarchy. (See window(3). The overloading + of the screen word is an unfortunate + historical accident.) Getwindow arranges that screen point to + the portion of the window inside the border; sophisticated clients + may use _screen to make further subwindows. Gengetwindow’s extra + arguments are the full path of the window’s winname file and pointers + to be overwritten with the values of the + ‘global’ Image and Screen variables for the new window. +
+ + The mouse cursor is always displayed. The initial cursor is an + arrow. Cursorswitch causes the argument cursor to be displayed + instead. A zero argument causes a switch back to the arrow cursor. + Cursorset moves the mouse cursor to position p, provided (if in + a window) that the requesting program is executing in the + current window and the mouse is within the window boundaries; + otherwise cursorset is a no-op. +
+ + The graphics functions described in draw(3), allocimage(3), cachechars(3), + and subfont(3) are implemented by writing commands to files under + /dev/draw (see draw(3)); the writes are buffered, so the functions + may not take effect immediately. Flushimage flushes the buffer, + doing all pending graphics operations. If + 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 event(3)); most programs do not need to + call flushimage. It returns –1 on error. +
+ + Bufimage is used to allocate space for n bytes in the display + buffer. It is used by all the graphics routines to send messages + to the display. +
+ + The functions strtochan and chantostr convert between the channel + descriptor strings used by image(7) and the internal ulong representation + used by the graphics protocol (see draw(3)’s b message). Chantostr + writes at most nine bytes into the buffer pointed at by s and + returns s on success, 0 on failure. + Chantodepth returns the number of bits per pixel used by the format + specified by chan. Both chantodepth and strtochan return 0 when + presented with bad input.
+ +
+

EXAMPLES
+ +
+ + To reconnect to the window after a resize event,
+ +
+ + if(getwindow(display, Refnone) < 0)
+ +
+ + sysfatal("resize failed: %r");
+ +
+ +
+ +
+ + + +
+ +
+ To create and set up a new rio(1) window,
+ +
+ + 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 rio(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 */
+ ...
+ +
+ +
+

FILES
+ +
+ + /usr/local/plan9/font/bit    directory of fonts
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + rio(1), addpt(3), allocimage(3), cachechars(3), subfont(3), draw(3), + event(3), frame(3), print(3), window(3), draw(3), image(7), font(7)
+ +
+

DIAGNOSTICS
+ +
+ + An error function may call errstr(3) for further diagnostics.
+ +
+

BUGS
+ +
+ + The names clr and set in the Cursor structure are reminders of + an archaic color map and might be more appropriately called white + and black. +
+ + These manual pages contain many references to the now-fictitious + /dev/draw.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/html.html b/man/man3/html.html new file mode 100644 index 00000000..465edcdb --- /dev/null +++ b/man/man3/html.html @@ -0,0 +1,1206 @@ + +html(3) - Plan 9 from User Space + + + + +
+
+
HTML(3)HTML(3) +
+
+

NAME
+ +
+ + parsehtml, printitems, validitems, freeitems, freedocinfo, dimenkind, + dimenspec, targetid, targetname, fromStr, toStr – HTML parser
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <html.h>
+ +
+ + Item*    parsehtml(uchar* data, int datalen, Rune* src, int mtype,
+ +
+ + +
+ + int chset, Docinfo** pdi)
+ +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void     printitems(Item* items, char* msg)
+ +
+ + int      validitems(Item* items)
+ +
+ + void     freeitems(Item* items)
+ +
+ + void     freedocinfo(Docinfo* d)
+ +
+ + int      dimenkind(Dimen d)
+ +
+ + int      dimenspec(Dimen d)
+ +
+ + int      targetid(Rune* s)
+ +
+ + Rune*    targetname(int targid)
+ +
+ + uchar* fromStr(Rune* buf, int n, int chset)
+ +
+ + Rune*    toStr(uchar* buf, int n, int chset)
+ +
+

DESCRIPTION
+ +
+ + +
+ + 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. +
+ + Parsehtml parses an entire HTML document contained in the buffer + data and having length datalen. The URL of the document should + be passed in as src. Mtype is the media type of the document, + which should be either TextHtml or TextPlain. The character set + of the document is described in chset, which can be + one of US_Ascii, ISO_8859_1, UTF_8 or Unicode. The return value + is a linked list of Item structures, described in detail below. + As a side effect, *pdi is set to point to a newly created Docinfo + structure, containing information pertaining to the entire document. + +
+ + The library expects two allocation routines to be provided by + the caller, emalloc and 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, + emalloc is required to zero the memory. +
+ + For debugging purposes, printitems may be called to display the + contents of an item list; individual items may be printed using + the %I print verb, installed on the first call to parsehtml. validitems + traverses the item list, checking that all of the pointers are + valid. It returns 1 is everything is ok, and 0 if an error was + found. Normally, one would not call these routines directly. Instead, + one sets the global variable dbgbuild and the library calls them + automatically. One can also set warn, to cause the library to + print a warning whenever it finds a problem with the input document, + and dbglex, to print debugging information in the + lexer. +
+ + When an item list is finished with, it should be freed with freeitems. + Then, freedocinfo should be called on the pointer returned in + *pdi. +
+ + Dimenkind and dimenspec are provided to interpret the Dimen type, + as described in the section Dimension Specifications. +
+ + Frame target names are mapped to integer ids via a global, permanent + mapping. To find the value for a given name, call 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 targetname. The library + predefines FTtop, FTself, FTparent and + FTblank. +
+ + The library handles all text as Unicode strings (type Rune*). + Character set conversion is provided by fromStr and toStr. FromStr + takes n Unicode characters from buf and converts them to the character + set described by chset. ToStr takes n bytes from buf, interpretted + as belonging to character set chset, and converts + them to a Unicode string. Both routines null-terminate the result, + and use emalloc to allocate space for it.
+

Items
+ The return value of parsehtml is a linked list of variant structures, + with the generic portion described by the following definition: + +
+ + typedef struct Item Item;
+ struct Item
+ {
+ +
+ + Item*      next;
+ int        width;
+ int        height;
+ int        ascent;
+ int        anchorid;
+ int        state;
+ Genattr* genattr;
+ int        tag;
+ +
+ };
+ +
+ + The field next points to the successor in the linked list of items, + while width, height, and ascent are intended for use by the caller + as part of the layout process. Anchorid, if non-zero, gives the + integer id assigned by the parser to the anchor that this item + is in (see section Anchors). State is a collection of + flags and values described as follows: +
+ + 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<<IFindentshift),
+ IFhangmask =      255
+ +
+ };
+ +
+ + IFbrk is set if a break is to be forced before placing this item. + IFbrksp is set if a 1 line space should be added to the break + (in which case IFbrk is also set). IFnobrk is set if a break is + not permitted before the item. IFcleft is set if left floats should + be cleared (that is, if the list of pending left floats should + be placed) before this item is placed, and IFcright is set for + right floats. In both cases, IFbrk is also set. IFwrap is set + if the line containing this item is allowed to wrap. IFhang is + set if this item hangs into the left indent. IFrjust is set if + the line containing this item should be right justified, and IFcjust + is + set for center justified lines. IFsmap is used to indicate that + an image is a server-side map. The low 8 bits, represented by + IFhangmask, indicate the current hang into left indent, in tenths + of a tabstop. The next 8 bits, represented by IFindentmask and + IFindentshift, indicate the current indent in tab + stops. +
+ + The field genattr is an optional pointer to an auxiliary structure, + described in the section Generic Attributes. +
+ + Finally, tag describes which variant type this item has. It can + have one of the values Itexttag, Iruletag, Iimagetag, Iformfieldtag, + Itabletag, Ifloattag or Ispacertag. For each of these values, + there is an additional structure defined, which includes Item + as an unnamed initial substructure, + and then defines additional fields. +
+ + Items of type Itexttag represent a piece of text, using the following + structure: +
+ + struct Itext
+ {
+ +
+ + Item;
+ Rune* s;
+ int     fnt;
+ int     fg;
+ uchar voff;
+ uchar ul;
+ +
+ };
+ +
+ + Here s is a null-terminated Unicode string of the actual characters + making up this text item, fnt is the font number (described in + the section Font Numbers), and fg is the RGB encoded color for + the text. Voff measures the vertical offset from the baseline; + subtract Voffbias to get the actual value (negative values + represent a displacement down the page). The field ul is the underline + style: ULnone if no underline, ULunder for conventional underline, + and ULmid for strike-through. +
+ + Items of type Iruletag represent a horizontal rule, as follows: + +
+ + struct Irule
+ {
+ +
+ + Item;
+ uchar align;
+ uchar noshade;
+ int     size;
+ Dimen wspec;
+ +
+ };
+ +
+ + Here align is the alignment specification (described in the corresponding + section), noshade is set if the rule should not be shaded, size + is the height of the rule (as set by the size attribute), and + wspec is the desired width (see section Dimension Specifications). + +
+ + Items of type Iimagetag describe embedded images, for which the + following structure is defined: +
+ + struct Iimage
+ {
+ +
+ + Item;
+ Rune*     imsrc;
+ int       imwidth;
+ int       imheight;
+ Rune*     altrep;
+ Map*      map;
+ int       ctlid;
+ uchar     align;
+ uchar     hspace;
+ uchar     vspace;
+ uchar     border;
+ Iimage* nextimage;
+ +
+ };
+ +
+ + Here imsrc is the URL of the image source, imwidth and imheight, + if non-zero, contain the specified width and height for the image, + and altrep is the text to use as an alternative to the image, + if the image is not displayed. Map, if set, points to a structure + describing an associated client-side image map. + Ctlid is reserved for use by the application, for handling animated + images. Align encodes the alignment specification of the image. + Hspace contains the number of pixels to pad the image with on + either side, and Vspace the padding above and below. Border is + the width of the border to draw around the + image. Nextimage points to the next image in the document (the + head of this list is Docinfo.images). +
+ + For items of type Iformfieldtag, the following structure is defined: + +
+ + struct Iformfield
+ {
+ +
+ + Item;
+ Formfield* formfield;
+ +
+ };
+ +
+ + This adds a single field, formfield, which points to a structure + describing a field in a form, described in section Forms. +
+ + For items of type Itabletag, the following structure is defined: + +
+ + struct Itable
+ {
+ +
+ + Item;
+ Table* table;
+ +
+ };
+ +
+ + Table points to a structure describing the table, described in + the section Tables. +
+ + For items of type Ifloattag, the following structure is defined: + +
+ + struct Ifloat
+ {
+ +
+ + Item;
+ Item*     item;
+ int       x;
+ int       y;
+ uchar     side;
+ uchar     infloats;
+ Ifloat* nextfloat;
+ +
+ };
+ +
+ + The item points to a single item (either a table or an image) + that floats (the text of the document flows around it), and side + indicates the margin that this float sticks to; it is either ALleft + or ALright. X and y are reserved for use by the caller; these + are typically used for the coordinates of the top of the float. + Infloats is used by the caller to keep track of whether it has + placed the float. Nextfloat is used by the caller to link together + all of the floats that it has placed. +
+ + For items of type Ispacertag, the following structure is defined: + +
+ + struct Ispacer
+ {
+ +
+ + Item;
+ int     spkind;
+ +
+ };
+ +
+ + Spkind encodes the kind of spacer, and may be one of ISPnull (zero + height and width), ISPvline (takes on height and ascent of the + current font), ISPhspace (has the width of a space in the current + font) and ISPgeneral (for all other purposes, such as between + markers and lists). +

Generic Attributes
+ +
+ + The genattr field of an item, if non-nil, points to a structure + that holds the values of attributes not specific to any particular + item type, as they occur on a wide variety of underlying HTML + tags. The structure is as follows: +
+ + typedef struct Genattr Genattr;
+ struct Genattr
+ {
+ +
+ + Rune*     id;
+ Rune*     class;
+ Rune*     style;
+ Rune*     title;
+ SEvent* events;
+ +
+ };
+ +
+ + Fields id, class, style and title, when non-nil, contain values + of correspondingly named attributes of the HTML tag associated + with this item. Events is a linked list of events (with corresponding + scripted actions) associated with the item: +
+ + typedef struct SEvent SEvent;
+ struct SEvent
+ {
+ +
+ + SEvent* next;
+ int       type;
+ Rune*     script;
+ +
+ };
+ +
+ + Here, next points to the next event in the list, type is one of + SEonblur, SEonchange, SEonclick, SEondblclick, SEonfocus, SEonkeypress, + SEonkeyup, SEonload, SEonmousedown, SEonmousemove, SEonmouseout, + SEonmouseover, SEonmouseup, SEonreset, SEonselect, + SEonsubmit or SEonunload, and script is the text of the associated + script.
+

Dimension Specifications
+ +
+ + Some structures include a dimension specification, used where + a number can be followed by a % or a * to indicate percentage + of total or relative weight. This is encoded using the following + structure: +
+ + typedef struct Dimen Dimen;
+ struct Dimen
+ {
+ +
+ + int kindspec;
+ +
+ };
+ +
+ + Separate kind and spec values are extracted using dimenkind and + dimenspec. Dimenkind returns one of Dnone, Dpixels, Dpercent or + Drelative. Dnone means that no dimension was specified. In all + other cases, dimenspec should be called to find the absolute number + of pixels, the percentage of total, or the + relative weight.
+

Background Specifications
+ +
+ + It is possible to set the background of the entire document, and + also for some parts of the document (such as tables). This is + encoded as follows: +
+ + typedef struct Background Background;
+ struct Background
+ {
+ +
+ + Rune* image;
+ int     color;
+ +
+ };
+ +
+ + Image, if non-nil, is the URL of an image to use as the background. + If this is nil, color is used instead, as the RGB value for a + solid fill color.
+

Alignment Specifications
+ +
+ + Certain items have alignment specifiers taken from the following + enumerated type: +
+ + enum
+ {
+ +
+ + ALnone = 0, ALleft, ALcenter, ALright, ALjustify,
+ ALchar, ALtop, ALmiddle, ALbottom, ALbaseline
+ +
+ };
+ +
+ + These values correspond to the various alignment types named in + the HTML 4.0 standard. If an item has an alignment of ALleft or + ALright, the library automatically encapsulates it inside a float + item. +
+ + Tables, and the various rows, columns and cells within them, have + a more complex alignment specification, composed of separate vertical + and horizontal alignments: +
+ + typedef struct Align Align;
+ struct Align
+ {
+ +
+ + uchar halign;
+ uchar valign;
+ +
+ };
+ +
+ + Halign can be one of ALnone, ALleft, ALcenter, ALright, ALjustify + or ALchar. Valign can be one of ALnone, ALmiddle, ALbottom, ALtop + or ALbaseline.
+

Font Numbers
+ +
+ + Text items have an associated font number (the fnt field), which + is encoded as style*NumSize+size. Here, style is one of FntR, + FntI, FntB or FntT, for roman, italic, bold and typewriter font + styles, respectively, and size is Tiny, Small, Normal, Large or + Verylarge. The total number of possible + font numbers is NumFnt, and the default font number is DefFnt + (which is roman style, normal size).
+

Document Info
+ +
+ + Global information about an HTML page is stored in the following + structure: +
+ + typedef struct Docinfo Docinfo;
+ struct Docinfo
+ {
+ +
+ + // stuff from HTTP headers, doc head, and body tag
+ Rune*         src;
+ Rune*         base;
+ Rune*         doctitle;
+ Background    background;
+ Iimage*       backgrounditem;
+ int           text;
+ int           link;
+ int           vlink;
+ int           alink;
+ int           target;
+ int           chset;
+ int           mediatype;
+ int           scripttype;
+ int           hasscripts;
+ Rune*         refresh;
+ Kidinfo*      kidinfo;
+ int           frameid;
+ // info needed to respond to user actions
+ Anchor*       anchors;
+ DestAnchor* dests;
+ Form*         forms;
+ Table*        tables;
+ Map*          maps;
+ Iimage*       images;
+ +
+ };
+ +
+ + Src gives the URL of the original source of the document, and + base is the base URL. Doctitle is the document’s title, as set + by a <title> element. Background is as described in the section + Background Specifications, and backgrounditem is set to be an + image item for the document’s background image + (if given as a URL), or else nil. Text gives the default foregound + text color of the document, link the unvisited hyperlink color, + vlink the visited hyperlink color, and alink the color for highlighting + hyperlinks (all in 24-bit RGB format). Target is the default target + frame id. Chset and mediatype are as for + the chset and mtype parameters to parsehtml. Scripttype is the + type of any scripts contained in the document, and is always TextJavascript. + Hasscripts is set if the document contains any scripts. Scripting + is currently unsupported. Refresh is the contents of a <meta http−equiv=Refresh + ...> tag, if any. Kidinfo is set if this document is a frameset + (see section Frames). Frameid is this document’s frame id. +
+ + Anchors is a list of hyperlinks contained in the document, and + dests is a list of hyperlink destinations within the page (see + the following section for details). Forms, tables and maps are + lists of the various forms, tables and client-side maps contained + in the document, as described in subsequent sections. + Images is a list of all the image items in the document.
+

Anchors
+ +
+ + The library builds two lists for all of the <a> elements (anchors) + in a document. Each anchor is assigned a unique anchor id within + the document. For anchors which are hyperlinks (the href attribute + was supplied), the following structure is defined: +
+ + typedef struct Anchor Anchor;
+ struct Anchor
+ {
+ +
+ + Anchor* next;
+ int       index;
+ Rune*     name;
+ Rune*     href;
+ int       target;
+ +
+ };
+ +
+ + Next points to the next anchor in the list (the head of this list + is Docinfo.anchors). Index is the anchor id; each item within + this hyperlink is tagged with this value in its anchorid field. + Name and href are the values of the correspondingly named attributes + of the anchor (in particular, href is the URL to go + to). Target is the value of the target attribute (if provided) + converted to a frame id. +
+ + Destinations within the document (anchors with the name attribute + set) are held in the Docinfo.dests list, using the following structure: + +
+ + typedef struct DestAnchor DestAnchor;
+ struct DestAnchor
+ {
+ +
+ + DestAnchor* next;
+ int           index;
+ Rune*         name;
+ Item*         item;
+ +
+ };
+ +
+ + Next is the next element of the list, index is the anchor id, + name is the value of the name attribute, and item is points to + the item within the parsed document that should be considered + to be the destination.
+

Forms
+ +
+ + Any forms within a document are kept in a list, headed by Docinfo.forms. + The elements of this list are as follows: +
+ + typedef struct Form Form;
+ struct Form
+ {
+ +
+ + Form*        next;
+ int          formid;
+ Rune*        name;
+ Rune*        action;
+ int          target;
+ int          method;
+ int          nfields;
+ Formfield* fields;
+ +
+ };
+ +
+ + Next points to the next form in the list. Formid is a serial number + for the form within the document. Name is the value of the form’s + name or id attribute. Action is the value of any action attribute. + Target is the value of the target attribute (if any) converted + to a frame target id. Method is one of HGet or + HPost. Nfields is the number of fields in the form, and fields + is a linked list of the actual fields. +
+ + The individual fields in a form are described by the following + structure: +
+ + 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;
+ +
+ };
+ +
+ + Here, next points to the next field in the list. Ftype is the + type of the field, which can be one of Ftext, Fpassword, Fcheckbox, + Fradio, Fsubmit, Fhidden, Fimage, Freset, Ffile, Fbutton, Fselect + or Ftextarea. Fieldid is a serial number for the field within + the form. Form points back + to the form containing this field. Name, value, size, maxlength, + rows and cols each contain the values of corresponding attributes + of the field, if present. Flags contains per-field flags, of which + FFchecked and FFmultiple are defined. Image is only used for fields + of type Fimage; it points to an + image item containing the image to be displayed. Ctlid is reserved + for use by the caller, typically to store a unique id of an associated + control used to implement the field. Events is the same as the + corresponding field of the generic attributes associated with + the item containing this field. Options is only used by + fields of type Fselect; it consists of a list of possible options + that may be selected for that field, using the following structure: + +
+ + typedef struct Option Option;
+ struct Option
+ {
+ +
+ + Option* next;
+ int       selected;
+ Rune*     value;
+ Rune*     display;
+ +
+ };
+ +
+ + Next points to the next element of the list. Selected is set if + this option is to be displayed initially. Value is the value to + send when the form is submitted if this option is selected. Display + is the string to display on the screen for this option.
+

Tables
+ +
+ + The library builds a list of all the tables in the document, headed + by Docinfo.tables. Each element of this list has the following + format: +
+ + 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;
+ +
+ };
+ +
+ + Next points to the next element in the list of tables. Tableid + is a serial number for the table within the document. Rows is + an array of row specifications (described below) and nrow is the + number of elements in this array. Similarly, cols is an array + of column specifications, and ncol the size of this array. + Cells is a list of all cells within the table (structure described + below) and ncell is the number of elements in this list. Note + that a cell may span multiple rows and/or columns, thus ncell + may be smaller than nrow*ncol. Grid is a two-dimensional array + of cells within the table; the cell at row i and column j is + Table.grid[i][j]. A cell that spans multiple rows and/or columns + will be referenced by grid multiple times, however it will only + occur once in cells. Align gives the alignment specification for + the entire table, and width gives the requested width as a dimension + specification. Border, cellspacing + and cellpadding give the values of the corresponding attributes + for the table, and background gives the requested background for + the table. Caption is a linked list of items to be displayed as + the caption of the table, either above or below depending on whether + caption_place is ALtop or ALbottom. + Most of the remaining fields are reserved for use by the caller, + except tabletok, which is reserved for internal use. The type + Lay is not defined by the library; the caller can provide its + own definition. +
+ + The 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: +
+ + typedef struct Tablecol Tablecol;
+ struct Tablecol
+ {
+ +
+ + int     width;
+ Align align;
+ Point pos;
+ +
+ };
+ +
+ + The rows in the table are specified as follows: +
+ + typedef struct Tablerow Tablerow;
+ struct Tablerow
+ {
+ +
+ + Tablerow*    next;
+ Tablecell* cells;
+ int          height;
+ int          ascent;
+ Align        align;
+ Background background;
+ Point        pos;
+ uchar        flags;
+ +
+ };
+ +
+ + Next is only used during parsing; it should be ignored by the + caller. Cells provides a list of all the cells in a row, linked + through their nextinrow fields (see below). Height, ascent and + pos are reserved for use by the caller. Align is the alignment + specification for the row, and background is the + background to use, if specified. Flags is used by the parser; + ignore this field. +
+ + The individual cells of the table are described as follows: +
+ + 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;
+ +
+ };
+ +
+ + Next is used to link together the list of all cells within a table + (Table.cells), whereas nextinrow is used to link together all + the cells within a single row (Tablerow.cells). Cellid provides + a serial number for the cell within the table. Content is a linked + list of the items to be laid out within the cell. Lay + is reserved for the user to describe how these items have been + laid out. Rowspan and colspan are the number of rows and columns + spanned by this cell, respectively. Align is the alignment specification + for the cell. Flags is some combination of TFparsing, TFnowrap + and TFisth or’d together. Here + TFparsing is used internally by the parser, and should be ignored. + 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). TFisth means that the cell was created + by the <th> element (rather than the <td> element), indicating that + it is a header cell rather than a data cell. Wspec provides a + suggested width as a dimension specification, and hspec provides + a suggested height in pixels. Background gives a background specification + for the individual cell. Minw, maxw, + ascent and pos are reserved for use by the caller during layout. + Row and col give the indices of the row and column of the top + left-hand corner of the cell within the table grid.
+

Client-side Maps
+ +
+ + The library builds a list of client-side maps, headed by Docinfo.maps, + and having the following structure: +
+ + typedef struct Map Map;
+ struct Map
+ {
+ +
+ + Map*    next;
+ Rune* name;
+ Area* areas;
+ +
+ };
+ +
+ + Next points to the next element in the list, name is the name + of the map (use to bind it to an image), and areas is a list of + the areas within the image that comprise the map, using the following + structure: +
+ + typedef struct Area Area;
+ struct Area
+ {
+ +
+ + Area*    next;
+ int      shape;
+ Rune*    href;
+ int      target;
+ Dimen* coords;
+ int      ncoords;
+ +
+ };
+ +
+ + Next points to the next element in the map’s list of areas. Shape + describes the shape of the area, and is one of SHrect, SHcircle + or SHpoly. Href is the URL associated with this area in its role + as a hypertext link, and target is the target frame it should + be loaded in. Coords is an array of coordinates for + the shape, and ncoords is the size of this array (number of elements).
+

Frames
+ +
+ + If the Docinfo.kidinfo field is set, the document is a frameset. + In this case, it is typical for 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. + +
+ + The Kidinfo structure itself reflects the fact that framesets + can be nested within a document. If is defined as follows: +
+ + 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;
+ +
+ };
+ +
+ + 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. Isframeset is set when this structure represents a frameset; + if clear, it is an individual frame. +
+ + Some fields are used only for framesets. Rows is an array of dimension + specifications for rows in the frameset, and nrows is the length + of this array. Cols is the corresponding array for columns, of + length ncols. Kidinfos points to a list of components contained + within this frameset, each of which may be a + frameset or a frame. Nextframeset is only used during parsing, + and should be ignored. +
+ + The remaining fields are used if the structure describes a frame, + not a frameset. 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. 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. Marginw, marginh + and framebd are the values of the marginwidth, marginheight and + frameborder attributes, respectively. Flags can contain some combination + of the following: FRnoresize (the + frame had the noresize attribute set, and the user should not + be allowed to resize it), FRnoscroll (the frame should not have + any scroll bars), FRhscroll (the frame should have a horizontal + scroll bar), FRvscroll (the frame should have a vertical scroll + bar), FRhscrollauto (the frame should be automatically + given a horizontal scroll bar if its contents would not otherwise + fit), and FRvscrollauto (the frame gets a vertical scrollbar only + if required).
+ +

+

SOURCE
+ +
+ + /usr/local/plan9/src/libhtml
+ +
+

SEE ALSO
+ +
+ + fmt(1) +
+ + W3C World Wide Web Consortium, “HTML 4.01 Specification”.
+ +
+

BUGS
+ +
+ + The entire HTML document must be loaded into memory before any + of it can be parsed.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/index.html b/man/man3/index.html new file mode 100644 index 00000000..90e8d3cf --- /dev/null +++ b/man/man3/index.html @@ -0,0 +1,647 @@ + + +Manual Section 3 - Plan 9 from User Space + + + +
+
+ +
+
+
+ Manual Section 3 - Plan 9 from User Space +
+
+
intro(3)intro – introduction to library functions +
+
+
+
9p(3)Srv +dirread9p +emalloc9p +erealloc9p +estrdup9p +postfd +postmountsrv +readbuf +readstr +respond +srv +threadpostmountsrv +walkandclone – 9P file service +
+
+
+
9p-cmdbuf(3)Cmdbuf, parsecmd, respondcmderror, lookupcmd – control message parsing +
+
+
+
9p-fid(3)Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, removefid +Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq, lookupreq, removereq – 9P fid, request tracking +
+
+
+
9p-file(3)Tree, alloctree, freetree +File, createfile, closefile, removefile, walkfile +opendirfile, readdirfile, closedirfile, hasperm – in-memory file hierarchy +
+
+
+
9p-intmap(3)Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey +deletekey – integer to data structure maps +
+
+
+
9pclient(3)CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fswrite – 9P client library +
+
+
+
addpt(3)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 +
+
+
+
aes(3)setupAESstate, aesCBCencrypt, aesCBCdecrypt - advanced encryption standard (rijndael) +
+
+
+
allocimage(3)allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline – allocating, freeing, reading, writing images +
+
+
+
arg(3)ARGBEGIN, ARGEND, ARGC, ARGF, EARGF, arginit, argopt – process option letters from argv +
+
+
+
arith3(3)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 +
+
+
+
atof(3)atof, atoi, atol, atoll, charstod, strtod, strtol, strtoll, strtoul, strtoull – convert text to numbers +
+
+
+
bin(3)binalloc, bingrow, binfree – grouped memory allocation +
+
+
+
bio(3)Bopen, Bfdopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered – buffered input/output +
+
+
+
blowfish(3)setupBFstate, bfCBCencrypt, bfCBCdecrypt, bfECBencrypt, bfECBdecrypt - blowfish encryption +
+
+
+
cachechars(3)cachechars, agefont, loadchar, Subfont, Fontchar, Font – font utilities +
+
+
+
cleanname(3)cleanname – clean a path name +
+
+
+
color(3)cmap2rgb, cmap2rgba, rgb2cmap – colors and color maps +
+
+
+
complete(3)complete, freecompletion – file name completion +
+
+
+
cputime(3)cputime, times – cpu time in this process and children +
+
+
+
ctime(3)ctime, localtime, gmtime, asctime, tm2sec, timezone – convert date and time +
+
+
+
des(3)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 +
+
+
+
dial(3)dial, announce, listen, accept, reject, netmkaddr, dialparse – make and break network connections +
+
+
+
dirread(3)dirread, dirreadall – read directory +
+
+
+
draw(3)Image, draw, drawop, gendraw, gendrawop, drawreplxy, drawrepl +replclipr, line, lineop, poly, polyop, fillpoly, fillpolyop, bezier, bezierop +bezspline, bezsplineop, bezsplinepts, fillbezier, fillbezierop +fillbezspline, fillbezsplineop, ellipse, ellipseop +fillellipse, fillellipseop, arc, arcop, fillarc, fillarcop +icossin, icossin2, border, string, stringop, stringn, stringnop +runestring, runestringop, runestringn, runestringnop, stringbg +stringbgop, stringnbg, stringnbgop, runestringbg, runestringbgop +runestringnbg, runestringnbgop, _string, ARROW, drawsetdebug – graphics functions +
+
+
+
dsa(3)dsagen, dsasign, dsaverify, dsapuballoc, dsapubfree, dsaprivalloc, dsaprivfree, dsasigalloc, dsasigfree, dsaprivtopub - digital signature algorithm +
+
+
+
dup(3)dup – duplicate an open file descriptor +
+
+
+
elgamal(3)eggen, egencrypt, egdecrypt, egsign, egverify, egpuballoc, egpubfree, egprivalloc, egprivfree, egsigalloc, egsigfree, egprivtopub - elgamal encryption +
+
+
+
encode(3)dec64, enc64, dec32, enc32, dec16, enc16, encodefmt – encoding byte arrays as strings +
+
+
+
errstr(3)errstr, rerrstr, werrstr – description of last system call error +
+
+
+
event(3)event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu – graphics events +
+
+
+
exec(3)exec, execl – execute a file +
+
+
+
exits(3)exits, _exits, atexit, atexitdont, terminate – terminate process, process cleanup +
+
+
+
fcall(3)Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeS2M, sizeD2M – interface to Plan 9 File protocol +
+
+
+
flate(3)deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, flateerr, mkcrctab, blockcrc, adler32 – deflate compression +
+
+
+
fmtinstall(3)fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, runefmtstrinit, runefmtstrflush, errfmt – support for user-defined print formats and output routines +
+
+
+
frame(3)frinit, frsetrects, frinittick, frclear, frcharofpt, frptofchar, frinsert, frdelete, frselect, frtick, frselectpaint, frdrawsel, frdrawsel0, frgetmouse – frames of text +
+
+
+
genrandom(3)genrandom, prng – random number generation +
+
+
+
get9root(3)get9root, unsharp – get path to root of Plan 9 tree +
+
+
+
getcallerpc(3)getcallerpc – fetch return PC of current function +
+
+
+
getenv(3)getenv, putenv – access environment variables +
+
+
+
getfields(3)getfields, gettokens, tokenize – break a string into fields +
+
+
+
getns(3)getns – get path to name space directory +
+
+
+
getsnarf(3)getsnarf, putsnarf – window system snarf (cut and paste) buffer +
+
+
+
getuser(3)getuser, sysname – get user or system name +
+
+
+
getwd(3)getwd – get current directory +
+
+
+
graphics(3)Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth – interactive graphics +
+
+
+
html(3)parsehtml +printitems +validitems +freeitems +freedocinfo +dimenkind +dimenspec +targetid +targetname +fromStr +toStr +– HTML parser +
+
+
+
ioproc(3)closeioproc +iocall +ioclose +iointerrupt +iodial +ioopen +ioproc +ioread +ioread9pmsg +ioreadn +iorecvfd +iosendfd +iosleep +iowrite – slave I/O processes for threaded programs +
+
+
+
ip(3)eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, nhgetv, hnputl, hnputs, hnputv, ptclbsum, readipifc – Internet protocol +
+
+
+
isalpharune(3)isalpharune, islowerrune, isspacerune, istitlerune, isupperrune, tolowerrune, totitlerune, toupperrune – Unicode character classes and cases +
+
+
+
keyboard(3)initkeyboard, ctlkeyboard, closekeyboard – keyboard control +
+
+
+
lock(3)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 +
+
+
+
mach(3)machbytype, machbyname – machine-independent access to executables and programs +
+
+
+
mach-cmd(3)attachargs, attachcore, attachdynamic, attachproc, proctextfile – debugging processes and core files +
+
+
+
mach-file(3)crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, detachproc, ctlproc +procnotes – machine-independent access to exectuable files and running processes +
+
+
+
mach-map(3)allocmap, addseg, findseg, addrtoseg +addrtosegafter, removeseg, freemap +get1, get2, get4, get8 +put1, put2, put4, put8 +rget, rput, fpformat +locnone, locaddr, locconst, locreg, locindir +loccmp, loceval, locfmt, locsimplify +lget1, lget2, lget4, lget8 +lput1, lput2, lput4, lput8 – machine-independent +
+
+
+
mach-stack(3)stacktrace, localaddr, unwindframe, windindex, windreglocs – stack traces +
+
+
+
mach-swap(3)beswap2, beswap4, beswap8, beieeeftoa32, beieeeftoa64, beieeeftoa80 +beload2, beload4, beload8 +leswap2, leswap4, leswap8, leieeeftoa32, leieeeftoa64, leieeeftoa80 +leload2, leload4, leload8, ieeeftoa32, ieeeftoa64 – machine-independent access to byte-ordered data +
+
+
+
mach-symbol(3)symopen, symclose, findhdr, indexsym, lookupsym, findsym +findexsym, flookupsym, ffindsym +lookuplsym, indexlsym, findlsym +symoff, pc2file, file2pc, line2pc, fnbound, fileline +pc2line – symbol table access functions +
+
+
+
malloc(3)malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, getmalloctag, getrealloctag – memory allocator +
+
+
+
matrix(3)ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, xform, ixform, persp, look, viewport – Geometric transformations +
+
+
+
memdraw(3)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 +
+
+
+
memlayer(3)memdraw, memlalloc, memldelete, memlexpose, memlfree, memlhide, memline, memlnorefresh, memload, memunload, memlorigin, memlsetrefresh, memltofront, memltofrontn, memltorear, memltorearn – windows of memory-resident images +
+
+
+
memory(3)memccpy, memchr, memcmp, memcpy, memmove, memset – memory operations +
+
+
+
mouse(3)initmouse, readmouse, closemouse, moveto, cursorswitch, getrect, drawgetrect, menuhit, setcursor – mouse control +
+
+
+
mousescrollsize(3)mousescrollsize – compute mouse scroll increment +
+
+
+
mp(3)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, mpfactorial, mpcmp, mpextendedgcd, mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, crtpre, crtin, crtout, crtprefree, crtresfree – extended precision arithmetic +
+
+
+
muldiv(3)muldiv, umuldiv – high-precision multiplication and division +
+
+
+
mux(3)Mux, muxinit, muxrpc, muxthreads – protocol multiplexor +
+
+
+
nan(3)NaN, Inf, isNaN, isInf – not-a-number and infinity functions +
+
+
+
needstack(3)needstack – check for execution stack overflow +
+
+
+
notify(3)notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff – handle asynchronous process notification +
+
+
+
open(3)open, create, close – open a file for reading or writing, create file +
+
+
+
opentemp(3)opentemp – create a uniquely-named file +
+
+
+
pipe(3)pipe – create an interprocess channel +
+
+
+
plumb(3)eplumb, plumbfree, plumbopen, plumbopenfid, plumbsend, plumbsendtofid, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg – plumb messages +
+
+
+
post9pservice(3)post9pservice – post 9P service for use by clients +
+
+
+
postnote(3)postnote – send a note to a process or process group +
+
+
+
prime(3)genprime, gensafeprime, genstrongprime, DSAprimes, probably_prime, smallprimetest – prime number generation +
+
+
+
print(3)print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint – print formatted output +
+
+
+
proto(3)rdproto – parse and process a proto file listing +
+
+
+
pushtls(3)pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain – attach TLS1 or SSL3 encryption to a communication channel +
+
+
+
qball(3)qball – 3-d rotation controller +
+
+
+
quaternion(3)qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, qmid, qsqrt – Quaternion arithmetic +
+
+
+
quote(3)quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote, needsrcquote – quoted character strings +
+
+
+
rand(3)rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, fastrand, nfastrand – random number generator +
+
+
+
rc4(3)setupRC4state, rc4, rc4skip, rc4back - alleged rc4 encryption +
+
+
+
read(3)read, readn, write, pread, pwrite – read or write file +
+
+
+
regexp(3)regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, regerror – regular expression +
+
+
+
rfork(3)rfork – manipulate process state +
+
+
+
rsa(3)asn1dump +asn1toRSApriv +decodepem +decodepemchain +rsadecrypt +rsaencrypt +rsafill, +rsagen +rsaprivalloc +rsaprivfree +rsaprivtopub +rsapuballoc +rsapubfree +X509toRSApub +X509dump +X509gen +X509req +X509verify – RSA encryption algorithm +
+
+
+
rune(3)runetochar, chartorune, runelen, runenlen, fullrune, utfecpy, utflen, utfnlen, utfrune, utfrrune, utfutf – rune/UTF conversion +
+
+
+
runestrcat(3)runestrcat +runestrncat +runestrcmp +runestrncmp +runestrcpy +runestrncpy +runestrecpy +runestrlen +runestrchr +runestrrchr +runestrdup +runestrstr – rune string operations +
+
+
+
sechash(3)md4, md5, sha1, hmac_md5, hmac_sha1, md5pickle, md5unpickle, sha1pickle, sha1unpickle – cryptographically secure hashes +
+
+
+
seek(3)seek – change file offset +
+
+
+
sendfd(3)sendfd, recvfd – pass file descriptors along Unix domain sockets +
+
+
+
setjmp(3)setjmp, longjmp, notejmp – non-local goto +
+
+
+
sleep(3)sleep, alarm – delay, ask for delayed note +
+
+
+
stat(3)stat, fstat, wstat, fwstat, dirstat, dirfstat, dirwstat, dirfwstat, nulldir – get and put file status +
+
+
+
strcat(3)strcat, strncat, strcmp, strncmp, cistrcmp, cistrncmp, strcpy, strncpy, strecpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok, strdup, strstr, cistrstr – string operations +
+
+
+
string(3)s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, s_getline, s_allocinstack, s_freeinstack, s_rdinstack – extensible strings +
+
+
+
stringsize(3)stringsize, stringwidth, stringnwidth, runestringsize, runestringwidth, runestringnwidth – graphical size of strings +
+
+
+
subfont(3)allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, strsubfontwidth, mkfont – subfont manipulation +
+
+
+
sysfatal(3)sysfatal – system error messages +
+
+
+
thread(3)alt +chancreate +chanfree +chaninit +chanprint +chansetname +mainstacksize +proccreate +procdata +recv +recvp +recvul +send +sendp +sendul +nbrecv +nbrecvp +nbrecvul +nbsend +nbsendp +nbsendul +threadcreate +threaddata +threadexec +threadexecl +threadexits +threadexitsall +threadgetgrp +threadgetname +threadint +threadintgrp +threadkill +threadkillgrp +threadmain +threadnotify +threadid +threadpid +threadsetgrp +threadsetname +threadsetstate +threadspawn +threadwaitchan +yield – thread and proc management +
+
+
+
time(3)time, nsec – time in seconds and nanoseconds since epoch +
+
+
+
udpread(3)udpread, udpwrite – read and write UDP packets +
+
+
+
wait(3)await, awaitnohang, awaitfor, wait, waitnohang, waitfor, waitpid – wait for a process to exit +
+
+
+
wctl(3)drawresizewindow, drawsetlabel, drawtopwindow – window management +
+
+
+
window(3)Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, bottomnwindows, topwindow, topnwindows, originwindow – window management +
+
+ +
+
+
+Space Glenda +
+
+		 +
+ + diff --git a/man/man3/intro.html b/man/man3/intro.html new file mode 100644 index 00000000..f6f4b311 --- /dev/null +++ b/man/man3/intro.html @@ -0,0 +1,288 @@ + +intro(3) - Plan 9 from User Space + + + + +
+
+
INTRO(3)INTRO(3) +
+
+

NAME
+ +
+ + intro – introduction to library functions
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ +
+ + #include any Unix headers
+ +
+ + #include <libc.h>
+ +
+ + #include <auth.h>
+ +
+ + #include <bio.h>
+ +
+ + #include <draw.h>
+ +
+ + #include <fcall.h>
+ +
+ + #include <frame.h>
+ +
+ + #include <mach.h>
+ +
+ + #include <regexp.h>
+ +
+ + #include <thread.h>
+ +
+

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 /usr/local/plan9/lib/libx.a, + where x is the base of the include file name, + stripped of a leading lib if present. For example, <draw.h> defines + the contents of library /usr/local/plan9/lib/libdraw.a, which + may be abbreviated when named to the loader as −ldraw. In practice, + each include file contains a magic 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; see 9c(1). +
+ + The library to which a function belongs is defined by the header + file that defines its interface. The ‘C library’, libc, contains + most of the basic subroutines such as strlen. Declarations for + all of these functions are in <libc.h>, which must be preceded by + (needs) an include of <u.h>. The graphics library, draw, is + defined by <draw.h>, which needs <libc.h> and <u.h>. The Buffered I/O + library, libbio, is defined by <bio.h>, which needs <libc.h> and <u.h>. + The ANSI C Standard I/O library, libstdio, is defined by <stdio.h>, + which needs <u.h>. There are a few other, less commonly used libraries + defined on + individual pages of this section. +
+ + The include file <u.h>, a prerequisite of several other include + files, declares the architecture-dependent and -independent types, + including: uchar, ushort, and ulong, the unsigned integer types; + schar, the signed char type; vlong and uvlong, the signed and + unsigned very long integral types; Rune, the Unicode + character type; u8int, u16int, u32int, and u64int, the unsigned + integral types with specific widths; jmp_buf, the type of the + argument to setjmp and longjmp, plus macros that define the layout + of jmp_buf (see setjmp(3)); and the macros va_arg and friends + for accessing arguments of variadic functions (identical to the + macros defined in <stdarg.h> in ANSI C). +
+ + Plan 9 and Unix use many similarly-named functions for different + purposes: for example, Plan 9’s dup is closer to (but not exactly) + Unix’s dup2. To avoid name conflicts, <libc.h> defines many of these + names as preprocessor macros to add a p9 prefix, so that dup becomes + p9dup. To disable this renaming, + #define NOPLAN9DEFINES before including <libc.h>. If Unix headers + must be included in a program, they should be included after <u.h>, + which sets important preprocessor directives (for example, to + enable 64-bit file offsets), but before <libc.h>, to avoid renaming + problems. +

Name space
+ Files are collected into a hierarchical organization called a + file tree starting in a directory called the root. File names, + also called paths, consist of a number of /-separated path elements + with the slashes corresponding to directories. A path element + must contain only printable characters (those outside the control + spaces of ASCII and Latin-1). A path element cannot contain a + slash. +
+ + When a process presents a file name to Plan 9, it is evaluated + by the following algorithm. Start with a directory that depends + on the first character of the path: / means the root of the main + hierarchy, 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.
+

File I/O
+ Files are opened for input or output by open or create (see open(3)). + These calls return an integer called a file descriptor which identifies + the file to subsequent I/O calls, notably read(3) and 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 dup(3). File descriptors + are indices into a kernel resident file descriptor table. Each + process has an associated file descriptor table. In threaded programs + (see thread(3)), the file descriptor table is shared by all the + procs. +
+ + 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. +
+ + Files are normally read or written in sequential order. The I/O + position in the file is called the file offset and may be set + arbitrarily using the seek(3) system call. +
+ + Directories may be opened like regular files. Instead of reading + them with read(3), use the Dir structure-based routines described + in dirread(3). The entry corresponding to an arbitrary file can + be retrieved by dirstat (see stat(3)) or dirfstat; dirwstat and + dirfwstat write back entries, thus changing the properties of + a + file. +
+ + New files are made with create (see open(3)) and deleted with + remove(3). Directories may not directly be written; create, remove, + wstat, and fwstat alter them. +
+ + Pipe(3) creates a connected pair of file descriptors, useful for + bidirectional local communication.
+

Process execution and control
+ A new process is created when an existing one calls 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; exec(3) + will bring in a different one. +
+ + Each process has a unique integer process id; a set of open files, + indexed by file descriptor; and a current working directory (changed + by chdir(2)). +
+ + Each process has a set of attributes -- memory, open files, name + space, etc. -- that may be shared or unique. Flags to rfork control + the sharing of these attributes. +
+ + A process terminates by calling exits(3). A parent process may + call wait(3) to wait for some child to terminate. A bit of status + information may be passed from exits to wait. On Plan 9, the status + information is an arbitrary text string, but on Unix it is a single + integer. The Plan 9 interface persists here, although the + functionality does not. Instead, empty strings are converted to + exit status 0 and non-empty strings to 1. +
+ + A process can go to sleep for a specified time by calling sleep(3). + +
+ + There is a notification mechanism for telling a process about + events such as address faults, floating point faults, and messages + from other processes. A process uses notify(3) to register the + function to be called (the notification handler) when such events + occur.
+

Multithreading
+ Where possible according to the ANSI C standard, the main C library + works properly in multiprocess programs; malloc, print, and the + other routines use locks (see lock(3)) to synchronize access to + their data structures. The graphics library defined in <draw.h> + is also multi-process capable; details are in graphics(3). + In general, though, multiprocess programs should use some form + of synchronization to protect shared data. +
+ + The thread library, defined in <thread.h>, provides support for + multiprocess programs. It includes a data structure called a Channel + that can be used to send messages between processes, and coroutine-like + 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. +
+ + Most programs using the thread library comprise multiple processes + communicating over channels, and within some processes, multiple + threads. Since 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 ioproc(3) + or mouse(3).
+ +

+

SEE ALSO
+ +
+ + nm(1), 9c(1)
+ +
+

DIAGNOSTICS
+ +
+ + Math functions in libc return special values when the function + is undefined for the given arguments or when the value is not + representable (see nan(3)). +
+ + Some of the functions in 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; errstr(3) + recovers a string describing the error. Some user-level library + functions also use the errstr mechanism to report errors. + Functions that may affect the value of the error string are said + to “set errstr”; it is understood that the error string is altered + only if an error occurs.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/ioproc.html b/man/man3/ioproc.html new file mode 100644 index 00000000..092bac91 --- /dev/null +++ b/man/man3/ioproc.html @@ -0,0 +1,211 @@ + +ioproc(3) - Plan 9 from User Space + + + + +
+
+
IOPROC(3)IOPROC(3) +
+
+

NAME
+ +
+ + closeioproc, iocall, ioclose, iointerrupt, iodial, ioopen, ioproc, + ioread, ioread9pmsg, ioreadn, iorecvfd, iosendfd, iosleep, iowrite + – slave I/O processes for threaded programs
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <thread.h>
+ typedef struct Ioproc Ioproc;
+ Ioproc* ioproc(void);
+ int       ioclose(Ioproc *io, int fd);
+ int       iodial(Ioproc *io, char *addr, char *local, char *dir, char + *cdfp);
+ int       ioopen(Ioproc *io, char *file, int omode);
+ long      ioread(Ioproc *io, int fd, void *a, long n);
+ int       ioread9pmsg(Ioproc *io, int fd, void *a, uint n);
+ long      ioreadn(Ioproc *io, int fd, void *a, long n);
+ int       iorecvfd(int socket);
+ int       iosendfd(int socket, int fd);
+ int       iosleep(int milli);
+ long      iowrite(Ioproc *io, int fd, void *a, long n);
+ void      iointerrupt(Ioproc *io);
+ void      closeioproc(Ioproc *io);
+ long      iocall(Ioproc *io, long (*op)(va_list *arg), ...);
+ +
+

DESCRIPTION
+ +
+ + +
+ + 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. + +
+ + Ioproc forks a new slave proc and returns a pointer to the Ioproc + associated with it. Ioproc uses mallocz and proccreate; if either + fails, it calls sysfatal rather than return an error. +
+ + Ioclose, iodial, ioopen, ioread, ioread9pmsg, ioreadn, iorecvfd, + iosendfd, iosleep, and iowrite execute the similarly named library + or system calls (see close(2), dial(3), open(3), read(3), fcall(3), + sendfd(3), and sleep(3)) in the slave process associated with + io. It is an error to execute more than one call at a time in + an I/O + proc. +
+ + Iointerrupt interrupts the call currently executing in the I/O + proc. If no call is executing, iointerrupt is a no-op. +
+ + Closeioproc terminates the I/O proc and frees the associated Ioproc + . +
+ + Iocall is a primitive that may be used to implement more slave + I/O routines. Iocall arranges for op to be called in io’s proc, + with arg set to the variable parameter list, returning the value + that op returns.
+ +
+

EXAMPLE
+ +
+ + Relay messages between two file descriptors, counting the total + number of bytes seen:
+ +
+ + 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);
+ +
+ }
+ +
+ + +
+ If the two relaythread instances were running in different procs, + the common access to tot would be unsafe. +
+ + Implement ioread:
+ +
+ + 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);
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libthread
+ +
+

SEE ALSO
+ +
+ + dial(3), open(3), read(3), thread(3)
+ +
+

BUGS
+ +
+ + Iointerrupt is currently unimplemented.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/ip.html b/man/man3/ip.html new file mode 100644 index 00000000..0376fa95 --- /dev/null +++ b/man/man3/ip.html @@ -0,0 +1,345 @@ + +ip(3) - Plan 9 from User Space + + + + +
+
+
IP(3)IP(3) +
+
+

NAME
+ +
+ + eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, + myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, + v6tov4, nhgetl, nhgets, nhgetv, hnputl, hnputs, hnputv, ptclbsum, + readipifc – Internet protocol
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <ip.h> +
+ + int    eipfmt(Fmt*) +
+ + ulong       parseip(uchar *ipaddr, char *str) +
+ + ulong       parseipmask(uchar *ipaddr, char *str) +
+ + char*       v4parseip(uchar *ipaddr, char *str) +
+ + ulong       v4parsecidr(uchar *addr, uchar *mask, char *str) +
+ + int    parseether(uchar *eaddr, char *str) +
+ + int    myetheraddr(uchar *eaddr, char *dev) +
+ + int    myipaddr(uchar *ipaddr, char *net) +
+ + void maskip(uchar *from, uchar *mask, uchar *to) +
+ + int    equivip(uchar *ipaddr1, uchar *ipaddr2) +
+ + uchar*      defmask(uchar *ipaddr) +
+ + int    isv4(uchar *ipaddr) +
+ + void v4tov6(uchar *ipv6, uchar *ipv4) +
+ + void v6tov4(uchar *ipv4, uchar *ipv6) +
+ + ushort      nhgets(void *p) +
+ + uint nhgetl(void *p) +
+ + uvlong      nhgetv(void *p) +
+ + void hnputs(void *p, ushort v) +
+ + void hnputl(void *p, uint v) +
+ + void hnputv(void *p, uvlong v) +
+ + ushort      ptclbsum(uchar *a, int n) +
+ + Ipifc*      readipifc(char *net, Ipifc *ifc, int index) +
+ + uchar       IPv4bcast[IPaddrlen]; +
+ + uchar       IPv4allsys[IPaddrlen]; +
+ + uchar       IPv4allrouter[IPaddrlen]; +
+ + uchar       IPallbits[IPaddrlen]; +
+ + uchar       IPnoaddr[IPaddrlen]; +
+ + uchar       v4prefix[IPaddrlen];
+ +
+

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 unsigned chars, Ethernet addresses as 6 + unsigned 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, FFFF::1111 + is equivalent to 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 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00, 255.255.255.0, + or /120. The string representation of Ethernet addresses is exactly + 12 hexadecimal digits. +
+ + Eipfmt is a print(3) formatter for Ethernet (verb E) addresses, + IP V6 (verb I) addresses, IP V4 (verb V) addresses, and IP V6 + (verb M) masks. +
+ + Parseip converts a string pointed to by str to a 16-byte IP address + starting at 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. Parseipmask converts a string pointed to by + str + to a 6-byte IP mask starting at ipaddr. It too returns an unsigned + long big-endian V4 address or 6. Both routines return -1 on errors. + +
+ + V4parseip converts a string pointed to by str to a 4-byte V4 IP + address starting at ipaddr. +
+ + V4parsecidr converts a string of the form addr/mask, pointed to + by str, to a 4-byte V4 IP address starting at ipaddr and a 4-byte + V4 IP mask starting at mask. +
+ + Myipaddr returns the first valid IP address in the IP stack rooted + at net. +
+ + Parseether converts a string pointed to by str to a 6-byte Ethernet + address starting at eaddr. Myetheraddr reads the Ethernet address + string from file dev/1/stats and parses it into eaddr. Both routines + return a negative number on errors. +
+ + 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. + +
+ + Equivip returns non-zero if the IP addresses pointed to by its + two arguments are equal. +
+ + Defmask returns the standard class A, B, or C mask for ipaddr. + +
+ + Isv4 returns non-zero if the V6 address is in the V4 space, that + is, if it starts with 0:0:0:0:0:0:FFFF. V4tov6 converts the V4 + address, v4ip, to a V6 address and puts the result in v6ip. V6tov4 + converts the V6 address, v6ip, to a V4 address and puts the result + in v4ip. +
+ + Hnputs, hnputl, and hnputv are used to store 16-, 32-, and 64-bit + integers into IP big-endian form. Nhgets, nhgetl, and nhgetv convert + big-endian 2-, 4-, and 8-byte quantities into integers. +
+ + Pctlbsum returns the one’s complement checksum used in IP protocols, + typically invoked as
+ hnputs(hdr−>cksum, ~ptclbsum(data, len) & 0xffff);
+ +
+ + A number of standard IP addresses in V6 format are also defined. + They are:
+ IPv4bcast
+ +
+ + the V4 broadcast address
+ +
+ IPv4allsys
+ +
+ + the V4 all systems multicast address
+ +
+ IPv4allrouter
+ +
+ + the V4 all routers multicast address
+ +
+ IPallbits
+ +
+ + the V6 all bits on address
+ +
+ IPnoaddr
+ +
+ + the V6 null address, all zeros
+ +
+ v4prefix
+ +
+ + the IP V6 prefix to all embedded V4 addresses +
+ + +
+ Readipifc returns information about a particular interface (index + >= 0) or all IP interfaces (index < 0) configured under a mount + point net, default /net. Each interface is described by one Ipifc + structure which in turn points to a linked list of Iplifc structures + describing the addresses assigned to this interface. If the list + ifc is supplied, that list is freed. Thus, subsequent calls can + be used to free the list returned by the previous call. Ipifc + is: +
+ + typedef struct Ipifc
+ {
+ +
+ + Ipifc       *next;
+ Iplifc      *lifc;          /* local addressses */
+ /* per ip interface */
+ int    index;          /* number of interface in ipifc dir */
+ char dev[64];    /* associated physical device */
+ int    mtu;        /* max transfer unit */
+ long validlt;    /* valid life time */
+ long preflt;          /* preferred life time */
+ uchar       sendra6;    /* on == send router adv */
+ uchar       recvra6;    /* on == rcv router adv */
+ ulong       pktin;          /* packets read */
+ ulong       pktout;          /* packets written */
+ ulong       errin;          /* read errors */
+ ulong       errout;          /* write errors */
+ Ipv6rp      rp;         /* route advertisement params */
+ +
+ } Ipifc;
+ +
+ + Iplifc is: +
+ + struct Iplifc
+ {
+ +
+ + Iplifc      *next;
+ uchar       ip[IPaddrlen];
+ uchar       mask[IPaddrlen];
+ uchar       net[IPaddrlen];           /* ip & mask */
+ ulong       preflt;              /* preferred lifetime */
+ ulong       validlt;         /* valid lifetime */
+ +
+ };
+ +
+ + Ipv6rp is: struct Ipv6rp {       int     mflag;       int     oflag;       int     maxraint; +     /* max route adv interval */       int     minraint;     /* min route adv interval + */       int     linkmtu;       int     reachtime;       int     rxmitra;       int     ttl;       int     routerlt; +      }; +
+ + Dev contains the first 64 bytes of the device configured with + this interface. Net is ip&mask if the network is multipoint or + the remote address if the network is point to point.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libip
+ +
+

SEE ALSO
+ +
+ + print(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/isalpharune.html b/man/man3/isalpharune.html new file mode 100644 index 00000000..99c2f387 --- /dev/null +++ b/man/man3/isalpharune.html @@ -0,0 +1,96 @@ + +isalpharune(3) - Plan 9 from User Space + + + + +
+
+
ISALPHARUNE(3)ISALPHARUNE(3) +
+
+

NAME
+ +
+ + isalpharune, islowerrune, isspacerune, istitlerune, isupperrune, + tolowerrune, totitlerune, toupperrune – Unicode character classes + and cases
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int isalpharune(Rune c) +
+ + int islowerrune(Rune c) +
+ + int isspacerune(Rune c) +
+ + int istitlerune(Rune c) +
+ + int isupperrune(Rune c) +
+ + Rune tolowerrune(Rune c) +
+ + Rune totitlerune(Rune c) +
+ + Rune toupperrune(Rune c)
+ +
+

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 isalpha(3) for + ASCII, these routines test types and modify cases for + Unicode characters. The names are self-explanatory. +
+ + The case-conversion routines return the character unchanged if + it has no case.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/utf/runetype.c
+ +
+

SEE ALSO
+ +
+ + isalpha(3), The Unicode Standard.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/keyboard.html b/man/man3/keyboard.html new file mode 100644 index 00000000..19dc833d --- /dev/null +++ b/man/man3/keyboard.html @@ -0,0 +1,135 @@ + +keyboard(3) - Plan 9 from User Space + + + + +
+
+
KEYBOARD(3)KEYBOARD(3) +
+
+

NAME
+ +
+ + initkeyboard, ctlkeyboard, closekeyboard – keyboard control
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <thread.h>
+ #include <keyboard.h>
+ +
+ + Keyboardctl      *initkeyboard(char *file)
+ +
+ + int             ctlkeyboard(Keyboardctl *kc, char *msg)
+ +
+ + void            closekeyboard(Keyboard *kc)
+ +
+

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 + mouse(3). They use the message-passing Channel interface in the + threads library (see thread(3)); programs that wish a more event-driven, + single-threaded approach + should use event(3). +
+ + Initkeyboard opens a connection to the keyboard and returns a + Keyboardctl structure:
+ +
+ + 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 */
+ +
+ };
+ +
+ + +
+ The argument to initkeyboard is ignored (on Plan 9, it is the + name of the keyboard device). +
+ + Once the Keyboardctl is set up a message containing a Rune will + be sent on the Channel Keyboardctl.c to report each character + read from the device. +
+ + Ctlkeyboard is used to set the state of the interface, typically + to turn raw mode on and off. It writes the string msg to the control + file associated with the device, which is assumed to be the regular + device file name with the string ctl appended. +
+ + Closekeyboard closes the file descriptors associated with the + keyboard, kills the slave processes, and frees the Keyboardctl + structure. +
+ + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), event(3), thread(3).
+ +
+

BUGS
+ +
+ + Because the interface delivers complete runes, there is no way + to report lesser actions such as shift keys or even individual + bytes.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/lock.html b/man/man3/lock.html new file mode 100644 index 00000000..72d66e12 --- /dev/null +++ b/man/man3/lock.html @@ -0,0 +1,222 @@ + +lock(3) - Plan 9 from User Space + + + + +
+
+
LOCK(3)LOCK(3) +
+
+

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
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ +
+ + void lock(Lock *l)
+ int    canlock(Lock *l)
+ void unlock(Lock *l)
+ +
+ + void qlock(QLock *l)
+ int    canqlock(QLock *l)
+ void qunlock(QLock *l)
+ +
+ + void rlock(RWLock *l)
+ int    canrlock(RWLock *l)
+ void runlock(RWLock *l)
+ +
+ + void wlock(RWLock *l)
+ int    canwlock(RWLock *l)
+ void wunlock(RWLock *l)
+ +
+ + typedef struct Rendez {
+ +
+ + QLock *l;
+ +
+ +
+ + ...
+ +
+ } Rendez;
+ +
+ + void rsleep(Rendez *r)
+ int    rwakeup(Rendez *r)
+ int    rwakeupall(Rendez *r)
+ +
+ + #include <thread.h>
+ +
+ + typedef struct Ref {
+ +
+ + long ref;
+ +
+ } Ref;
+ +
+ + void incref(Ref*)
+ long decref(Ref*)
+ +
+

DESCRIPTION
+ +
+ + These routines are used to synchronize processes sharing memory. + +
+ + Locks are spin locks, QLocks and RWLocks are different types of + queueing locks, and Rendezes are rendezvous points. +
+ + Locks and rendezvous points have trivial implementations in programs + not using the thread library (see thread(3)), since such programs + have no concurrency. +
+ + 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. +
+ + Lock blocks until the lock has been obtained. Canlock is non-blocking. + It tries to obtain a lock and returns a non-zero value if it was + successful, 0 otherwise. Unlock releases a lock. +
+ + QLocks have the same interface but are not spin locks; instead + if the lock is taken qlock will suspend execution of the calling + thread until it is released. +
+ + Although Locks are the more primitive lock, they have limitations; + for example, they cannot synchronize between tasks in the same + proc. Use QLocks instead. +
+ + RWLocks manage access to a data structure that has distinct readers + and writers. Rlock grants read access; runlock releases it. Wlock + grants write access; wunlock releases it. Canrlock and 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. +
+ + All types of lock should be initialized to all zeros before use; + this puts them in the unlocked state. +
+ + Rendezes are rendezvous points. Each Rendez r is protected by + a QLock r−>l, which must be held by the callers of rsleep, rwakeup, + and rwakeupall. Rsleep atomically releases r−>l and suspends execution + of the calling task. After resuming execution, rsleep will reacquire + r−>l before returning. If any processes + are sleeping on r, rwakeup wakes one of them. it returns 1 if + a process was awakened, 0 if not. Rwakeupall wakes all processes + sleeping on r, returning the number of processes awakened. Rwakeup + and rwakeupall do not release r−>l and do not suspend execution + of the current task. +
+ + Before use, Rendezes should be initialized to all zeros except + for r−>l pointer, which should point at the QLock that will guard + r. +
+ + A Ref contains a long that can be incremented and decremented + atomically: Incref increments the Ref in one atomic operation. + Decref atomically decrements the Ref and returns zero if the resulting + value is zero, non-zero otherwise.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/qlock.c
+ /usr/local/plan9/src/libthread
+ +
+

BUGS
+ +
+ + Locks are not always spin locks. Instead they are usually implemented + using the pthreads library’s pthread_mutex_t, whose implementation + method is not defined. +
+ + On pthreads-based systems, the implementation of Lock never calls + pthread_mutex_destroy to free the pthread_mutex_t’s. This leads + to resource leaks on FreeBSD 5 (though not on Linux 2.6, where + pthread_mutex_destroy is a no-op). +
+ + On systems that do not have a usable pthreads implementation, + the Lock implementation provided by libthread is still not exactly + a spin lock. After each unsuccessful attempt, lock calls sleep(0) + to yield the CPU; this handles the common case where some other + process holds the lock. After a thousand + unsuccessful attempts, lock sleeps for 100ms between attempts. + Another another thousand unsuccessful attempts, lock sleeps for + a full second between attempts. 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.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-cmd.html b/man/man3/mach-cmd.html new file mode 100644 index 00000000..978e80b5 --- /dev/null +++ b/man/man3/mach-cmd.html @@ -0,0 +1,167 @@ + +mach-cmd(3) - Plan 9 from User Space + + + + +
+
+
MACH-CMD(3)MACH-CMD(3) +
+
+

NAME
+ +
+ + attachargs, attachcore, attachdynamic, attachproc, proctextfile + – debugging processes and core files
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + int      attachcore(Fhdr *hdr) +
+ + int      attachproc(int pid) +
+ + int      attachdynamic(void) +
+ + char*    proctextfile(int pid) +
+ + int      attachargs(int argc, char **argv, int omode) +
+ + extern Fhdr* symhdr;
+ extern     char*    symfil;
+ extern     Map*    symmap;
+ extern     Fhdr*    fhdrlist;
+ extern     Fhdr*    corhdr;
+ extern     char*    corfil;
+ extern     Map*    cormap;
+ extern     int      corpid;
+ extern     Regs*    correg;
+ +
+

DESCRIPTION
+ +
+ + These routines provide access to the objects a typical debugger + manipulates: an executable binary, some number of shared libraries, + a memory image in the form of a core dump or active process, and + a register set. +
+ + The maintained state is:
+ symhdr
+ +
+ + The file header for the main binary.
+ +
+ symfilThe file name of the main binary.
+ symmap
+ +
+ + The memory map of the main binary.
+ +
+ fhdrlist
+ +
+ + A linked list (via the Fhdr.next fields) of all currently open + headers (see symopen in mach-symbol(3)). When dynamically linked + objects have been attached, they are present in this linked list, + and therefore included in searches by indexsym, lookupsym, and + findsym (see mach-symbol(3)). + +
+ corhdrThe file header for the core dump, if any.
+ corfilThe file name of the core dump, if any.
+ cormap
+ +
+ + The memory map of the core dump or attached process.
+ +
+ corpidThe process id of the attached process, if any.
+ corregThe register set of the core dump or attached process. If + these fields are not valid, they are zeroed. +
+ + Attachcore and attachproc attach to an opened core file or an + executing process. They set corhdr, corfil, cormap, corpid, and + correg. +
+ + Proctextfile returns the name of the main binary for the process + with id pid. +
+ + Attachdynamic requires that the memory image already be attached. + It reads the dynamic linker’s internal run-time data structures + and then opens all the dynamic objects that are currently loaded. + +
+ + Attachargs uses all of these functions while parsing an argument + vector as would be passed to a debugger like db(1) or acid(1). + It expects a list of executable files, core dump files, or process + ids, given in any order. If extra arguments are given (for example, + more than one executable, or both a core dump and a + process id), they are ignored and diagnostics are printed to standard + error. If arguments are missing (for example, the process id is + given without an executable file), attachargs fills them in as + best it can.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3), mach-file(3), mach-map(3)
+ +
+

BUGS
+ +
+ + The interface needs to be changed to support multiple threads, + each with its own register set.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-file.html b/man/man3/mach-file.html new file mode 100644 index 00000000..7fd1a578 --- /dev/null +++ b/man/man3/mach-file.html @@ -0,0 +1,185 @@ + +mach-file(3) - Plan 9 from User Space + + + + +
+
+
MACH-FILE(3)MACH-FILE(3) +
+
+

NAME
+ +
+ + crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, + detachproc, ctlproc, procnotes – machine-independent access to + exectuable files and running processes
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + int     crackhdr(int fd, Fhdr *hdr)
+ void    uncrackhdr(Fhdr *hdr) +
+ + int     mapfile(Fhdr *hdr, ulong base, Map *map, Regs **regs)
+ void    unmapfile(Fhdr *hdr, Map *map)
+ int     mapproc(int pid, Map *map, Regs **regs)
+ void    unmapproc(Map *map)
+ int     detachproc(int pid)
+ int     ctlproc(int pid, char *msg)
+ int     procnotes(int pid, char ***notes)
+ +
+

DESCRIPTION
+ +
+ + These functions parse executable files and provide access to those + files and to running processes. +
+ + Crackhdr opens and parses the named executable file. The returned + data structure hdr is initialized with a machine-independent description + of the header information. The following fields are the most commonly + used:
+ macha pointer to the Mach structure for the target architecture
+ mname
+ +
+ + the name of the target architecture
+ +
+ fname
+ +
+ + a description of the kind of file (e.g., executable, core dump)
+ +
+ aname
+ +
+ + a description of the application binary interface this file uses; + typically it is the name of an operating system If the global + variable mach is nil, crackhdr points it to the same Mach structure. + +
+ + +
+ Mapfile adds the segments found in hdr to map. If hdr is an executable + file, there are typically three segments: text, data, and a zero-backed + bss. If hdr is a dynamic shared library, its segments are relocated + by base before being mapping. +
+ + If hdr is a core file, there is one segment named core for each + contiguous section of memory recorded in the core file. There + are often quite a few of these, as most operating systems omit + clean memory pages when writing core files (Mac OS X is the only + exception among the supported systems). Because core files + have such holes, it is typically necessary to construct the core + map by calling mapfile on the executable and then calling it again + on the core file. Newly-added segments are mapped on top of existing + segments, so this arrangement will use the core file for the segments + it contains but fall back to the executable for the + rest. +
+ + Unmapfile removes the mappings in map corresponding to hdr. +
+ + Mapproc attaches to a running program and adds its segments to + the given map. It adds one segment for each contiguous section + of mapped memory. On systems where this information cannot be + determined, it adds a single segment covering the entire address + space. Accessing areas of this segment that are + actually not mapped in the process address space will cause the + get/put routines to return errors. +
+ + Unmapproc removes the mappings in map corresponding to pid. Detachproc + detaches from all previously attached processes. +
+ + Ctlproc manipulates the process with id pid according to the message + msg. Valid messages include:
+ killterminate the process
+ startstop
+ +
+ + start the process and wait for it to stop
+ +
+ sysstop
+ +
+ + arrange for the process to stop at its next system call, start + the process, and then wait for it to stop
+ +
+ waitstop
+ +
+ + wait for the process to stop
+ +
+ start
+ +
+ + start the process +
+ + +
+ Procnotes fills *notes with a pointer to an array of strings representing + pending notes waiting for the process. (On Unix, these notes are + textual descriptions of any pending signals.) Procnotes returns + the number of pending notes. The memory at *notes should be freed + via free (see malloc(3)) when no longer needed. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3), mach-map(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-map.html b/man/man3/mach-map.html new file mode 100644 index 00000000..ddf7275f --- /dev/null +++ b/man/man3/mach-map.html @@ -0,0 +1,312 @@ + +mach-map(3) - Plan 9 from User Space + + + + +
+
+
MACH-MAP(3)MACH-MAP(3) +
+
+

NAME
+ +
+ + allocmap, addseg, findseg, addrtoseg, addrtosegafter, removeseg, + freemap, get1, get2, get4, get8, put1, put2, put4, put8, rget, + rput, fpformat, locnone, locaddr, locconst, locreg, locindir, + loccmp, loceval, locfmt, locsimplify, lget1, lget2, lget4, lget8, + lput1, lput2, lput4, lput8 – machine-independent access to address + spaces and register sets
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + typedef struct Map Map;
+ typedef struct Seg Seg;
+ +
+ + struct Seg
+ {
+ +
+ + char    *name;
+ char    *file;
+ int     fd;
+ ulong    base;
+ ulong    size;
+ ulong    offset;
+ int     (*rw)(Map*, Seg*, ulong, void*, uint, int);
+ +
+ };
+ +
+ + struct Map
+ {
+ +
+ + Seg     *seg;
+ int     nseg;
+ ...
+ +
+ };
+ +
+ + Map    *allocmap(void)
+ int     addseg(Map *map, Seg seg)
+ int     findseg(Map *map, char *name, char *file)
+ int     addrtoseg(Map *map, ulong addr, Seg *seg)
+ int     addrtosegafter(Map *map, ulong addr, Seg *seg)
+ void    removeseg(Map *map, int i)
+ void    freemap(Map *map)
+ +
+ + int     get1(Map *map, ulong addr, uchar *a, uint n)
+ int     get2(Map *map, ulong addr, u16int *u)
+ int     get4(Map *map, ulong addr, u32int *u)
+ int     get8(Map *map, ulong addr, u64int *u)
+ +
+ + int     put1(Map *map, ulong addr, uchar *a, uint n)
+ int     put2(Map *map, ulong addr, u16int u)
+ int     put4(Map *map, ulong addr, u32int u)
+ int     put8(Map *map, ulong addr, u64int u)
+ +
+ + int     rget(Regs *regs, char *reg, ulong *u)
+ int     fpformat(Map *map, char *reg, char *a, uint n, char code);
+ +
+ + int     rput(Regs *regs, char *name, ulong u)
+ +
+ + Loc    locnone(void)
+ Loc    locaddr(ulong addr)
+ Loc    locconst(ulong con)
+ Loc    locreg(char *reg)
+ Loc    locindir(char *reg, long offset)
+ +
+ + int     loccmp(Loc *a, Loc *b)
+ int     loceval(Map *map, Loc loc, ulong *addr)
+ int     locfmt(Fmt *fmt)
+ int     locsimplify(Map *map, Loc *regs, Loc loc, Loc *newloc)
+ +
+ + int     lget1(Map *map, Loc loc, uchar *a, uint n)
+ int     lget2(Map *map, Loc loc, u16int *u)
+ int     lget4(Map *map, Loc loc, u32int *u)
+ int     lget8(Map *map, Loc loc, u64int *u)
+ +
+ + int     lput1(Map *map, Loc loc, uchar *a, uint n)
+ int     lput2(Map *map, Loc loc, u16int u)
+ int     lput4(Map *map, Loc loc, u32int u)
+ int     lput8(Map *map, Loc loc, u64int u)
+ +
+ + +
+

DESCRIPTION
+ +
+ + These functions provide a processor-independent interface for + accessing executable files, core files, and running processes + via maps, data structures that provides access to an address space + and register set. The functions described in mach-file(3) are + typically used to construct these maps. Related library functions + described in mach-symbol(3) provide similar access to symbol tables. + +
+ + Each map comprises an optional register set and one or more segments, + each associating a non-overlapping range of memory addresses with + a logical section of an executable file or of a running process’s + address space. Other library functions then use a map and the + architecture-specific data structures to provide + a generic interface to the processor-dependent data. +
+ + Each segment has a name (e.g., text or data) and may be associated + with a particular file. A segment represents a range of accessible + address space. Segments may be backed an arbitary access function + (if the rw pointer is non-nil), or by the contents of an open + file (using the fd file descriptor). Each range has a + starting address in the space (base) and an extent (size). In + segments mapped by files, the range begins at byte offset in the + file. The rw function is most commonly used to provide access + to executing processes via ptrace(2) and to zeroed segments. +
+ + Allocmap creates an empty map; freemap frees a map. +
+ + Addseg adds the given segment to the map, resizing the map’s seg + array if necessary. A negative return value indicates an allocation + error. +
+ + Findseg returns the index of the segment with the given name (and, + if file is non-nil, the given file), or –1 if no such segment is + found. +
+ + Addrtoseg returns the index of the segment containing for the + given address, or –1 if that address is not mapped. Segments may + have overlapping address ranges: addseg appends segments to the + end of the seg array in the map, and addrtoseg searches the map + backwards from the end, so the most recently mapped + segment wins. +
+ + Addrtosegafter returns the index of the segment containing the + lowest mapped address greater than addr. +
+ + Removeseg removes the segment at the given index. +
+ + Get1, get2, get4, and get8 retrieve the data stored at address + addr in the address space associated with map. Get1 retrieves + n bytes of data beginning at addr into buf. Get2, get4 and get8 + retrieve 16-bit, 32-bit and 64-bit values respectively, into the + location pointed to by u. The value is byte-swapped if the source + byte order differs from that of the current architecture. This + implies that the value returned by get2, get4, and get8 may not + be the same as the byte sequences returned by get1 when n is two, + four or eight; the former may be byte-swapped, the latter reflects + the byte order of the target architecture. These functions + return the number of bytes read or a –1 when there is an error. + +
+ + Put1, put2, put4, and put8 write to the address space associated + with map. The address is translated using the map parameters and + multi-byte quantities are byte-swapped, if necessary, before they + are written. Put1 transfers n bytes stored at buf; put2, put4, + and put8 write the 16-bit, 32-bit or 64-bit quantity + contained in val, respectively. The number of bytes transferred + is returned. A –1 return value indicates an error. +
+ + When representing core files or running programs, maps also provide + access to the register set. Rget and rput read or write the register + named by reg. If the register is smaller than a ulong, the high + bits are ignored. +
+ + Fpformat converts the contents of a floating-point register to + a string. Buf is the address of a buffer of n bytes to hold the + resulting string. Code must be either F or f, selecting double + or single precision, respectively. If code is F, the contents + of the specified register and the following register are interpreted + as a + double-precision floating-point number; this is meaningful only + for architectures that implement double-precision floats by combining + adjacent single-precision registers. +
+ + A location represents a place in an executing image capable of + storing a value. Note that locations are typically passed by value + rather than by reference. +
+ + Locnone returns an unreadable, unwritable location. Locaddr returns + a location representing the memory address addr. Locreg returns + a location representing the register reg. Locindir returns an + location representing the memory address at offset added to the + value of reg. Locconst returns an imaginary unwritable + location holding the constant con; such locations are useful for + passing specific constants to functions expect locations, such + as unwind (see mach-stack(3)). +
+ + Loccmp compares two locations, returning negative, zero, or positive + values if *a is less than, equal to, or greater than *b, respectively. + Register locations are ordered before memory addresses, which + are ordered before indirections. +
+ + Locfmt is a print(3)-verb that formats a Loc structure (not a + pointer to one). +
+ + Indirection locations are needed in some contexts (e.g., when + using findlsym (see mach-symbol(3))), but bothersome in most. + Locsimplify rewrites indirections as absolute memory addresses, + by evaluating the register using the given map and adding the + offset. +
+ + The functions lget1, lget2, lget4, lget8, lput1, lput2, lput4, + and lput8 read and write the given locations, using the get, put, + rget, and rput function families as necessary.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3), mach-file(3)
+ +
+

DIAGNOSTICS
+ +
+ + These routines set errstr.
+ +
+

BUGS
+ +
+ + This man page needs to describe Regs and Regdesc
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-stack.html b/man/man3/mach-stack.html new file mode 100644 index 00000000..d08258bd --- /dev/null +++ b/man/man3/mach-stack.html @@ -0,0 +1,232 @@ + +mach-stack(3) - Plan 9 from User Space + + + + +
+
+
MACH-STACK(3)MACH-STACK(3) +
+
+

NAME
+ +
+ + stacktrace, localaddr, unwindframe, windindex, windreglocs – stack + traces
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + int     stacktrace(Map *map, Rgetter rget, Tracer trace) +
+ + int     localaddr(Map *map, Regs *regs, char *fn, char *val, ulong + *val) +
+ + int     unwindframe(Map *map, Regs *regs, ulong *next, Symbol *sym) + +
+ + int     windindex(char *regname) +
+ + Loc*    windreglocs(void)
+ +
+

DESCRIPTION
+ +
+ + Stacktrace provides machine-independent implementations of process + stack traces. They must retrieve data and register contents from + an executing image. Sometimes the desired registers are not the + current registers but rather a set of saved registers stored elsewhere + in memory. The caller may specify an initial + register set in the form of an Rgetter function, of the form +
+ + +
+ + ulong rget(Map *map, char *name)
+ +
+ + +
+ It returns the contents of a register when given a map and a register + name. It is usually sufficient for the register function to return + meaningful values only for SP and PC, and for the link register + (usually LR) on CISC machines. +
+ + Given the map and the rgetter, stacktrace unwinds the stack starting + at the innermost function. At each level in the trace, it calls + the tracer function, which has the form +
+ + +
+ + int trace(Map *map, ulong pc, ulong callerpc,
+ +
+ + Rgetter rget, Symbol *s)
+ +
+ +
+ +
+ + + +
+ +
+ The tracer is passed the map, the current program counter, the + program counter of the caller (zero if the caller is unknown), + a new rget function, and a symbol (see mach-symbol(3)) describing + the current function (nil if no symbol is known). The value returned + by the tracer controls whether the stack trace continues: a + zero or negative return value stops the trace, while a positive + return value continues it. +
+ + The rgetter passed to the tracer is not the rgetter passed to + stacktrace itself. Instead, it is a function returning the register + values at the time of the call, to the extent that they can be + reconstructed. The most common use for this rgetter is as an argument + to lget4, etc., when evaluating the locations of local + variables. +
+ + Localaddr uses stacktrace to walk up the stack looking for the + innermost instance of a function named fn ; once it finds the + function, it looks for the parameter or local variable var, storing + the address of the variable in val. +
+ + Unwindframe is the low-level function on which stacktrace is built. + Given the current memory image in map and the current register + set in regs , unwindframe fills in next with the values of the + register set at the time of the call to the function in the current + program counter. Sym should be the symbol corresponding to + the current function, if available. +
+ + The next array holds only the winding registers, typically the + caller-save registers and the program counter and stack pointer. + The order of registers in the array is called the winding order. + The winding set can be found in the array mach−>windreg, which + has mach−>nwindreg entries. Windindex returns the index of + the named register in the winding order. Windreglocs returns an + array of Loc structures corresponding to the winding registers, + in the winding order.
+ +
+

EXAMPLE
+ +
+ + The following code writes a simple stack trace to standard output, + stopping after at most 20 stack frames.
+ +
+ + static int
+ trace(Map *map, ulong pc, ulong callerpc,
+ +
+ + Rgetter rget, Symbol *s, int depth)
+ +
+ {
+ +
+ + char buf[512];
+ int i, first;
+ u32int v;
+ Symbol s2;
+ if(sym)
+ print("%s+%lx", s->name, pc - loceval(s->loc));
+ else
+ print("%lux", pc);
+ print("(");
+ first = 0;
+ for(i=0; indexlsym(s, &i, &s2)>=0; i++){
+ if(s.class != CPARAM)
+ continue;
+ if(first++)
+ print(", ");
+ if(lget4(map, rget, s->loc, &v) >= 0)
+ print("%s=%#lux", s->name, (ulong)v);
+ else
+ print("%s=???", s->name);
+ }
+ print(") called from ");
+ symoff(buf, sizeof buf, callerpc, CTEXT);
+ print("%s\n", buf);
+ return depth < 20;
+ +
+ }
+ +
+ + if(stacktrace(map, nil, trace) <= 0)
+ print("no stack frame0);
+ +
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3)
+ +
+

BUGS
+ +
+ + Need to talk about Regs
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-swap.html b/man/man3/mach-swap.html new file mode 100644 index 00000000..5eefd9d6 --- /dev/null +++ b/man/man3/mach-swap.html @@ -0,0 +1,124 @@ + +mach-swap(3) - Plan 9 from User Space + + + + +
+
+
MACH-SWAP(3)MACH-SWAP(3) +
+
+

NAME
+ +
+ + beswap2, beswap4, beswap8, beieeeftoa32, beieeeftoa64, beieeeftoa80, + beload2, beload4, beload8, leswap2, leswap4, leswap8, leieeeftoa32, + leieeeftoa64, leieeeftoa80, leload2, leload4, leload8, ieeeftoa32, + ieeeftoa64 – machine-independent access to byte-ordered data
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + u16int beswap2(u16int u)
+ u32int    beswap4(u32int u)
+ u64int    beswap8(u64int u) +
+ + int     beieeeftoa32(char *a, uint n, void *f)
+ int      beieeeftoa64(char *a, uint n, void *f)
+ int      beieeeftoa80(char *a, uint n, void *f) +
+ + u16int beload2(uchar *p)
+ u32int    beload4(uchar *p)
+ u64int    beload8(uchar *p) +
+ + u16int leswap2(u16int u)
+ u32int    leswap4(u32int u)
+ u64int    leswap8(u64int u) +
+ + int     leieeeftoa32(char *a, uint n, void *f)
+ int      leieeeftoa64(char *a, uint n, void *f)
+ int      leieeeftoa80(char *a, uint n, void *f) +
+ + u16int leload2(uchar *p)
+ u32int    leload4(uchar *p)
+ u64int    leload8(uchar *p) +
+ + int     ieeeftoa32(char *a, uint n, u32int u)
+ int      ieeeftoa64(char *a, uint n, u32int hi, u32int lo)
+ +
+

DESCRIPTION
+ +
+ + These functions provide machine-independent access to data in + a particular byte order. +
+ + Beswap2, beswap4, and beswap8 return the 2-byte, 4-byte, and 8-byte + big-endian representation of the bytes in val, respectively. +
+ + Beload2, beload4, and beload8 return the 2-byte, 4-byte, and 8-byte + big-endian interpretation of the bytes at p, respectively. +
+ + Beieeeftoa32, beieeeftoa64, and beieeeftoa80 format the big-endian + 4-byte, 8-byte, or 10-byte IEEE floating-point value at f into + the n-byte string buffer a. +
+ + Leswap2, leswap4, etc. are the little-endian equivalents of the + routines just described. +
+ + Ieeeftoa32 and ieeeftoa64 format a local machine byte-order floating-point + value into the n-byte string buffer a. Ieeeftoa32 expects a 32-bit + floating-point value stored in the bits of u. Ieeeftoa64 expects + a 64-bit floating-point value whose high 32-bits are in hi and + low 32-bits are in lo. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach-symbol.html b/man/man3/mach-symbol.html new file mode 100644 index 00000000..246d51b4 --- /dev/null +++ b/man/man3/mach-symbol.html @@ -0,0 +1,272 @@ + +mach-symbol(3) - Plan 9 from User Space + + + + +
+
+
MACH-SYMBOL(3)MACH-SYMBOL(3) +
+
+

NAME
+ +
+ + symopen, symclose, findhdr, indexsym, lookupsym, findsym, findexsym, + flookupsym, ffindsym, lookuplsym, indexlsym, findlsym, symoff, + pc2file, file2pc, line2pc, fnbound, fileline, pc2line – symbol + table access functions
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + int      symopen(Fhdr *hdr)
+ void     symclose(Fhdr *hdr)
+ Fhdr     *findhdr(char *name)
+ extern    Fhdr* fhdrlist; +
+ + int      indexsym(uint n, Symbol *s)
+ int      lookupsym(char *fn, char *var, Symbol *s)
+ int      findsym(Loc loc, uint class, Symbol *s) +
+ + int      findexsym(Fhdr *hdr, uint n, Symbol *s)
+ Symbol *flookupsym(Fhdr *hdr, char *name)
+ Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class) +
+ + int      indexlsym(Symbol *s1, uint n, Symbol *s2)
+ int      lookuplsym(Symbol *s1, char *name, Symbol *s2)
+ int      findlsym(Symbol *s1, Loc loc, Symbol *s2) +
+ + int      symoff(char *a, uint n, ulong addr, uint class) +
+ + int      pc2file(ulong pc, char *file, uint n, ulong *line)
+ int      pc2line(ulong pc, ulong *line)
+ int      fileline(ulong pc, char *buf, uint n)
+ int      file2pc(char *file, ulong line, ulong *pc)
+ int      line2pc(ulong basepc, ulong line, ulong *pc)
+ int      fnbound(ulong pc, ulong bounds[2])
+ +
+

DESCRIPTION
+ +
+ + These functions provide machine-independent access to the symbol + table of an executable file or executing process. Mach(3), mach-file(3), + and mach-map(3) describe additional library functions for accessing + executable files and executing processes. +
+ + Symopen uses the data in the Fhdr structure filled by crackhdr + (see mach-file(3)) to initialize in-memory structures used to + access the symbol tables contained in the file. Symclose frees + the structures. The rest of the functions described here access + a composite symbol table made up of all currently open tables. + +
+ + The set of all currently open Fhdrs is maintained as a linked + list starting at fhdrlist (chained via Fhdr.next). +
+ + Findhdr searches the currently open Fhdrs for one whose file name + ends with the path name (that is, libc.so matches /usr/lib/libc.so + but not mylibc.so). +
+ + The Symbol data structure:
+ +
+ + typedef struct Symbol Symbol;
+ struct Symbol
+ {
+ +
+ + char    *name;
+ Loc    loc;
+ Loc    hiloc;
+ char    class;
+ char    type;
+ ...
+ +
+ };
+ +
+ + +
+ describes a symbol table entry. The 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 type field contains the type of + the symbol:
+ +
+ + T     text segment symbol
+ t     static text segment symbol
+ D     data segment symbol
+ d     static data segment symbol
+ B     bss segment symbol
+ b     static bss segment symbol
+ a     automatic (local) variable symbol
+ p     function parameter symbol
+ U     undefined symbol
+ +
+ + +
+ The class field assigns the symbol to a general class; CTEXT, + CDATA, CAUTO, and CPARAM are the most popular. +
+ + Indexsym stores information for the n th symbol into s. The symbols + are ordered by increasing address. +
+ + Lookupsym fills a 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 fn and 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 var is zero, the text symbol table is searched + for function fn. If only fn is zero, the global variable table + is searched for var. +
+ + Findsym returns the symbol table entry of type class stored near + addr. The selected symbol is a global variable or function with + address nearest to and less than or equal to addr. Class specification + CDATA searches only the global variable symbol table; class CTEXT + limits the search to the text symbol table. Class + specification CANY searches the text table first, then the global + table. +
+ + Findexsym, flookupsym, and ffindsym are similar to indexsym, lookupsym, + and findsym, but operate only on the symbols from hdr. Flookupsym + and ffindsym return pointers to data stored in the hdr, which + must not be modified or freed. +
+ + Indexlsym, lookuplsym, and findlsym are similar to indexsym, lookupsym, + and findsym, but operate on the smaller symbol table of parameters + and variables local to the function represented by symbol s1. + +
+ + Indexlsym writes symbol information for the nth local symbol of + function s1 to s2. Function parameters appear first in the ordering, + followed by local symbols. +
+ + Lookuplsym writes symbol information for the symbol named name + in function s1 to s2. +
+ + Findlsym searches for a symbol local to the function s1 whose + location is exactly loc, writing its symbol information to s2. + Loc is almost always an indirection through a frame pointer register; + the details vary from architecture to architecture. +
+ + Symoff converts a location to a symbol 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 4096 bytes of + the address, the address is formatted as a hexadecimal address. + Buf is the address of a buffer of n bytes to receive the formatted + string. Addr is the address to be converted. Type is the type + code of the search space: CTEXT, CDATA, or CANY. Symoff + returns the length of the formatted string contained in buf. +
+ + Pc2file searches the symbol table to find the file and line number + corresponding to the instruction at program counter pc. File is + the address of a buffer of n bytes to receive the file name. Line + receives the line number. +
+ + Pc2line is like pc2file but neglects to return information about + the source file. +
+ + Fileline is also like pc2file, but returns the file and line number + in the n-byte text buffer buf, formatted as ‘file:line’. +
+ + File2pc performs the opposite mapping: it stores in pc a text + address associated with line line in file file. +
+ + Line2pc is similar: it converts a line number to an instruction + address, storing it in pc. Since a line number does not uniquely + identify an instruction (e.g., every source file has line 1), + basepc specifies a text address from which the search begins. + Usually this is the address of the first function in the file + of interest. +
+ + 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; 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 first + address beyond the end of the target function. +
+ + All functions return 0 on success and –1 on error. When an error + occurs, a message describing it is stored in the system error + buffer where it is available via errstr.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach(3), mach-file(3), mach-map(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mach.html b/man/man3/mach.html new file mode 100644 index 00000000..d69e5929 --- /dev/null +++ b/man/man3/mach.html @@ -0,0 +1,123 @@ + +mach(3) - Plan 9 from User Space + + + + +
+
+
MACH(3)MACH(3) +
+
+

NAME
+ +
+ + machbytype, machbyname – machine-independent access to executables + and programs
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mach.h> +
+ + +
+ + void machbytype(int type) +
+ + int machbyname(char *name) +
+ + extern Mach *mach;
+ +
+

DESCRIPTION
+ +
+ + Libmach provides an interface for accessing the executable files + and executing images of various architectures and operating systems. + The interface is machine-independent, meaning that, for example, + Mac OS X core dumps may be inspected using an x86 Linux machine + and vice versa. In its current form, the library is + mainly useful for writing debuggers of one sort or another. +
+ + An architecture is described primarily by a Mach structure, which + contains data structures and parameters describing the particular + architecture. Most library functions assume that the global variable + mach points at the structure for the architecture being debugged. + It is set implicitly by crackhdr (see mach-file(3)) and + can be set explicitly by calling machbyname or machbytype. +
+ + There is no operating system-specific structure akin to mach. + Typically the choice of operating system on a particular architecture + affects only the executable and core dump formats; the various + file parsers deduce the operating system from information in the + binary files themselves and adjust accordingly. +
+ + The supported architectures are 386 (Intel 32-bit x86) 386 and + later) and power (IBM PowerPC, typically running Mac OS X). +
+ + Other manual pages describe the library functions in detail. +
+ + Mach-cmd(3) describes some convenience routines for attaching + to processes and core files. +
+ + Mach-file(3) describes the manipulation of binary files. +
+ + Mach-map(3) describes the interface to address spaces and register + sets in executable files and executing programs. +
+ + Mach-stack(3) describes support for unwinding the stack. +
+ + Mach-swap(3) describes helper functions for accessing data in + a particular byte order. +
+ + Mach-symbol(3) describes the interface to debugging symbol information.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach
+ +
+

SEE ALSO
+ +
+ + mach-file(3), mach-map(3), mach-stack(3), mach-swap(3), mach-symbol(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/malloc.html b/man/man3/malloc.html new file mode 100644 index 00000000..9c30c293 --- /dev/null +++ b/man/man3/malloc.html @@ -0,0 +1,181 @@ + +malloc(3) - Plan 9 from User Space + + + + +
+
+
MALLOC(3)MALLOC(3) +
+
+

NAME
+ +
+ + malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, + getmalloctag, getrealloctag – memory allocator
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + void* malloc(ulong size) +
+ + void* mallocz(ulong size, int clr) +
+ + void    free(void *ptr) +
+ + void* realloc(void *ptr, ulong size) +
+ + void* calloc(ulong nelem, ulong elsize) +
+ + void    setmalloctag(void *ptr, ulong tag) +
+ + ulong getmalloctag(void *ptr) +
+ + void    setrealloctag(void *ptr, ulong tag) +
+ + ulong getrealloctag(void *ptr)
+ +
+

DESCRIPTION
+ +
+ + Malloc and free provide a simple memory allocation package. Malloc + returns a pointer to a new block of at least size bytes. The block + is suitably aligned for storage of any type of object. No two + active pointers from malloc will have the same value. The call + malloc(0) returns a valid pointer rather than null. +
+ + The argument to free is a pointer to a block previously allocated + by 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 malloc are undefined. Mallocz + behaves as malloc, except that if clr is non-zero, the memory + returned will be zeroed. +
+ + Realloc changes the size of the block pointed to by ptr to 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. Realloc takes on special meanings when one or both arguments + are zero:
+ realloc(0, size)
+ +
+ + means malloc(size); returns a pointer to the newly-allocated memory
+ +
+ realloc(ptr, 0)
+ +
+ + means free(ptr); returns null
+ +
+ realloc(0, 0)
+ +
+ + no-op; returns null +
+ + +
+ Calloc allocates space for an array of nelem elements of size + elsize. The space is initialized to zeros. Free frees such a block. + +
+ + The memory allocator on Plan 9 maintains two word-sized fields + associated with each block, the “malloc tag” and the “realloc + tag”. By convention, the malloc tag is the PC that allocated the + block, and the realloc tag the PC that last reallocated the block. + These may be set or examined with setmalloctag, getmalloctag, + setrealloctag, and getrealloctag. When allocating blocks directly + with malloc and 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 getcallerpc(3) + to setmalloctag) to provide more useful information about the + source + of allocation.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/malloc.c
+ /usr/local/plan9/src/lib9/malloctag.c
+ +
+

SEE ALSO
+ +
+ + trump (in acid(1)), getcallerpc(3)
+ +
+

DIAGNOSTICS
+ +
+ + Malloc, realloc and calloc return 0 if there is no available memory. + Errstr is likely to be set. If the allocated blocks have no malloc + or realloc tags, getmalloctag and getrealloctag return ~0. +
+ + The trump library for acid can be used to obtain traces of malloc + execution; see acid(1).
+ +
+

BUGS
+ +
+ + The different specification of calloc is bizarre. +
+ + 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 malloc and free detect such + corruption, they abort. +
+ + To avoid name conflicts with the system versions of these functions, + malloc, realloc, calloc, and free are preprocessor macros defined + as p9malloc, p9realloc, p9calloc, and p9free; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/matrix.html b/man/man3/matrix.html new file mode 100644 index 00000000..ad72d10a --- /dev/null +++ b/man/man3/matrix.html @@ -0,0 +1,263 @@ + +matrix(3) - Plan 9 from User Space + + + + +
+
+
MATRIX(3)MATRIX(3) +
+
+

NAME
+ +
+ + ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, + xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, + xform, ixform, persp, look, viewport – Geometric transformations
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <draw.h> +
+ + #include <geometry.h> +
+ + void ident(Matrix m) +
+ + void matmul(Matrix a, Matrix b) +
+ + void matmulr(Matrix a, Matrix b) +
+ + double determinant(Matrix m) +
+ + void adjoint(Matrix m, Matrix madj) +
+ + double invertmat(Matrix m, Matrix inv) +
+ + Point3 xformpoint(Point3 p, Space *to, Space *from) +
+ + Point3 xformpointd(Point3 p, Space *to, Space *from) +
+ + Point3 xformplane(Point3 p, Space *to, Space *from) +
+ + Space *pushmat(Space *t) +
+ + Space *popmat(Space *t) +
+ + void rot(Space *t, double theta, int axis) +
+ + void qrot(Space *t, Quaternion q) +
+ + void scale(Space *t, double x, double y, double z) +
+ + void move(Space *t, double x, double y, double z) +
+ + void xform(Space *t, Matrix m) +
+ + void ixform(Space *t, Matrix m, Matrix inv) +
+ + int persp(Space *t, double fov, double n, double f) +
+ + void look(Space *t, Point3 eye, Point3 look, Point3 up) +
+ + void viewport(Space *t, Rectangle r, double aspect)
+ +
+

DESCRIPTION
+ +
+ + These routines manipulate 3-space affine and projective transformations, + represented as 4×4 matrices, thus:
+ +
+ + typedef double Matrix[4][4];
+ +
+ + +
+ Ident stores an identity matrix in its argument. Matmul stores + a×b in a. Matmulr stores b×a in b. Determinant returns the determinant + of matrix m. Adjoint stores the adjoint (matrix of cofactors) + of m in madj. Invertmat stores the inverse of matrix m in minv, + returning m’s determinant. Should m be singular + (determinant zero), invertmat stores its adjoint in minv. +
+ + The rest of the routines described here manipulate Spaces and + transform Point3s. A Point3 is a point in three-space, represented + by its homogeneous coordinates:
+ +
+ + typedef struct Point3 Point3;
+ struct Point3{
+ +
+ + double x, y, z, w;
+ +
+ };
+ +
+ + +
+ The homogeneous coordinates (x, y, z, w) represent the Euclidean + point (x/w, y/w, z/w) if w!=0, and a “point at infinity” if w=0. + +
+ + A Space is just a data structure describing a coordinate system:
+ +
+ + typedef struct Space Space;
+ struct Space{
+ +
+ + Matrix t;
+ Matrix tinv;
+ Space *next;
+ +
+ };
+ +
+ + +
+ It contains a pair of transformation matrices and a pointer to + the Space’s parent. The matrices transform points to and from + the “root coordinate system,” which is represented by a null Space + pointer. +
+ + Pushmat creates a new Space. Its argument is a pointer to the + parent space. Its result is a newly allocated copy of the parent, + but with its next pointer pointing at the parent. Popmat discards + the Space that is its argument, returning a pointer to the stack. + Nominally, these two functions define a stack of + transformations, but pushmat can be called multiple times on the + same Space multiple times, creating a transformation tree. +
+ + Xformpoint and Xformpointd both transform points from the Space + pointed to by from to the space pointed to by to. Either pointer + may be null, indicating the root coordinate system. The difference + between the two functions is that xformpointd divides x, y, z, + and w by w, if w!=0, making (x, y, z) the Euclidean + coordinates of the point. +
+ + Xformplane transforms planes or normal vectors. A plane is specified + by the coefficients (a, b, c, d) of its implicit equation ax+by+cz+d=0. + Since this representation is dual to the homogeneous representation + of points, libgeometry represents planes by Point3 structures, + with (a, b, c, d) stored in (x, y, z, w). +
+ + The remaining functions transform the coordinate system represented + by a Space. Their Space * argument must be non-null -- you can’t + modify the root Space. Rot rotates by angle theta (in radians) + about the given axis, which must be one of XAXIS, YAXIS or ZAXIS. + Qrot transforms by a rotation about an + arbitrary axis, specified by Quaternion q. +
+ + Scale scales the coordinate system by the given scale factors + in the directions of the three axes. Move translates by the given + displacement in the three axial directions. +
+ + Xform transforms the coordinate system by the given Matrix. If + the matrix’s inverse is known a priori, calling ixform will save + the work of recomputing it. +
+ + Persp does a perspective transformation. The transformation maps + the frustum with apex at the origin, central axis down the positive + y axis, and apex angle fov and clipping planes y=n and y=f into + the double-unit cube. The plane y=n maps to y’=-1, y=f maps to + y’=1. +
+ + Look does a view-pointing transformation. The eye point is moved + to the origin. The line through the eye and look points is aligned + with the y axis, and the plane containing the eye, look and up + points is rotated into the x-y plane. +
+ + Viewport maps the unit-cube window into the given screen viewport. + The viewport rectangle r has r.min at the top left-hand corner, + and r.max just outside the lower right-hand corner. Argument aspect + is the aspect ratio (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 y axis, with x to + the left and z up. The viewport has x increasing to the right + and y increasing down. The window’s y coordinates are mapped, + unchanged, into the viewport’s z coordinates.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libgeometry/matrix.c
+ +
+

SEE ALSO
+ +
+ + arith3(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/memdraw.html b/man/man3/memdraw.html new file mode 100644 index 00000000..57a0c96c --- /dev/null +++ b/man/man3/memdraw.html @@ -0,0 +1,466 @@ + +memdraw(3) - Plan 9 from User Space + + + + +
+
+
MEMDRAW(3)MEMDRAW(3) +
+
+

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
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <memdraw.h>
+ +
+ + 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;
+ +
+ +
+ + ...
+ +
+ } Memimage;
+ typedef struct Memdrawparam
+ {
+ +
+ + Memimage    *dst;
+ Rectangle r;
+ Memimage    *src;
+ Rectangle sr;
+ Memimage    *mask;
+ Rectangle mr;
+ +
+ +
+ + ...
+ +
+ } Memdrawparam;
+ int           drawdebug;
+ +
+ + void          memimageinit(void)
+ ulong*        wordaddr(Memimage *i, Point p)
+ uchar*        byteaddr(Memimage *i, Point p)
+ void          memimagemove(void *from, void *to)
+ +
+ + 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)
+ +
+ + 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)
+ +
+ + 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)
+ +
+ + +
+ +
+ 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)
+ +
+ + 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, Drawop op)
+ +
+ + +
+ +
+ int           iprint(char *fmt, ...)
+ int           hwdraw(Memdrawparam *param)
+ +
+

DESCRIPTION
+ +
+ + The Memimage type defines memory-resident rectangular pictures + and the methods to draw upon them; Memimages differ from Images + (see draw(3)) in that they are manipulated directly in user memory + rather than by RPCs to the /dev/draw hierarchy. The library is + the basis for the kernel draw(3) driver and also + used by a number of programs that must manipulate images without + a display. +
+ + The r, clipr, depth, nchan, and chan structure elements are identical + to the ones of the same name in the Image structure. +
+ + The flags element of the Memimage structure holds a number of + bits of information about the image. In particular, it subsumes + the purpose of the repl element of Image structures. +
+ + Memimageinit initializes various static data that the library + depends on, as well as the replicated solid color images memopaque, + memtransparent, memblack, and memwhite. It should be called before + referring to any of these images and before calling any of the + other library functions. +
+ + Each Memimage points at a Memdata structure that in turn points + at the actual pixel data for the image. This allows multiple images + to be associated with the same Memdata. The first word of the + data pointed at by the base element of Memdata points back at + the Memdata structure, so that in the Plan 9 kernel, + the memory allocator (see Plan 9’s pool(3)) can compact image + memory using memimagemove. +
+ + Because images can have different coordinate systems, the zero + element of the Memimage structure contains the offset that must + be added to the bdata element of the corresponding Memdata structure + in order to yield a pointer to the data for the pixel (0,0). Adding + width machine words to this pointer moves it + down one scan line. The 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. Wordaddr and + byteaddr perform these calculations, returning pointers to the + word and byte, respectively, that contain the beginning of the + data for a given pixel. +
+ + Allocmemimage allocages images with a given rectangle and channel + descriptor (see strtochan in graphics(3)), creating a fresh Memdata + structure and associated storage. Allocmemimaged is similar but + uses the supplied Memdata structure rather than a new one. The + readmemimage function reads an + uncompressed bitmap from the given file descriptor, while creadmemimage + reads a compressed bitmap. Writememimage writes a compressed representation + of i to file descriptor fd. For more on bitmap formats, see image(7). + Freememimage frees images returned by any of these routines. The + Memimage structure + contains some tables that are used to store precomputed values + depending on the channel descriptor. Memsetchan updates the chan + element of the structure as well as these tables, returning –1 + if passed a bad channel descriptor. +
+ + Loadmemimage and cloadmemimage replace the pixel data for a given + rectangle of an image with the given buffer of uncompressed or + compressed data, respectively. When calling cloadmemimage, the + buffer must contain an integral number of compressed chunks of + data that exactly cover the rectangle. + 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. +
+ + Memfillcolor fills an image with the given color, a 32-bit number + as described in color(3). +
+ + Memarc, mempoly, memellipse, memfillpoly, memimageline, and memimagedraw + are identical to the arc, poly, ellipse, fillpoly, line, and gendraw, + routines described in draw(3), except that they operate on Memimages + rather than Images. Similarly, allocmemsubfont, openmemsubfont, + freememsubfont, + memsubfontwidth, getmemdefont, and memimagestring are the Memimage + analogues of allocsubfont, openfont, freesubfont, strsubfontwidth, + getdefont, and string (see subfont(3) and graphics(3)), except + that they operate only on Memsubfonts rather than Fonts. +
+ + Drawclip takes the images involved in a draw operation, together + with the destination rectangle dr and source and mask alignment + points sp and mp, and clips them according to the clipping rectangles + of the images involved. It also fills in the rectangles sr and + mr with rectangles congruent to the returned + destination rectangle but translated so the upper left corners + are the returned sp and mp. Drawclip returns zero when the clipped + rectangle is empty. Memlinebbox returns a conservative bounding + box containing a line between two points with given end styles + and radius. Memlineendsize calculates the extra length + added to a line by attaching an end of a given style. +
+ + The hwdraw and iprint functions are no-op stubs that may be overridden + by clients of the library. Hwdraw is called at each call to 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. + Iprint should format and print its arguments; it is given much + debugging output when the global integer variable drawdebug is + non-zero. In the kernel, iprint prints to a serial line rather + than the screen, for obvious reasons. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + addpt(3), color(3), draw(3), graphics(3), memlayer(3), stringsize(3), + subfont(3), color(7), utf(7)
+ +
+

BUGS
+ +
+ + Memimagestring is unusual in using a subfont rather than a font, + and in having no parameter to align the source. +
+ + These functions are archived into libdraw.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/memlayer.html b/man/man3/memlayer.html new file mode 100644 index 00000000..c21f5bf6 --- /dev/null +++ b/man/man3/memlayer.html @@ -0,0 +1,325 @@ + +memlayer(3) - Plan 9 from User Space + + + + +
+
+
MEMLAYER(3)MEMLAYER(3) +
+
+

NAME
+ +
+ + memdraw, memlalloc, memldelete, memlexpose, memlfree, memlhide, + memline, memlnorefresh, memload, memunload, memlorigin, memlsetrefresh, + memltofront, memltofrontn, memltorear, memltorearn – windows of + memory-resident images
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <memdraw.h>
+ #include <memlayer.h>
+ +
+ + typedef struct Memscreen Memscreen;
+ typedef struct Memlayer Memlayer;
+ typedef void (*Refreshfn)(Memimage*, Rectangle, void*);
+ 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 */
+ +
+ };
+ +
+ + Memimage* memlalloc(Memscreen *s, Rectangle r, Refreshfn fn, void + *arg, ulong col)
+ +
+ + void        memlnorefresh(Memimage *i, Rectangle r, void *arg)
+ +
+ + int         memlsetrefresh(Memimage *i, Refreshfn fn, void *arg)
+ +
+ + int         memldelete(Memimage *i)
+ +
+ + int         memlfree(Memimage *i)
+ +
+ + int         memlexpose(Memimage *i, Rectangle r)
+ +
+ + int         memlhide(Memimage *i, Rectangle r)
+ +
+ + void        memltofront(Memimage *i)
+ +
+ + void        memltofrontn(Memimage**ia, int n)
+ +
+ + void        memltorear(Memimage *i)
+ +
+ + void        memltorearn(Memimage **ia , int n)
+ +
+ + int         memlorigin(Memimage *i, Point log, Point phys)
+ +
+ + void        memdraw(Image *dst, Rectangle r,
+ +
+ + +
+ + Image *src, Point sp, Image *mask, Point mp, Drawop op)
+ +
+ +
+ int         memload(Memimage *i, Rectangle r,
+ +
+ + +
+ + uchar *buf, int n, int iscompressed) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int         memunload(Memimage *i, Rectangle r,
+ +
+ + +
+ + uchar *buf, int n) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ +
+

DESCRIPTION
+ +
+ + These functions build upon the memdraw(3) interface to maintain + overlapping graphical windows on in-memory images. They are used + by the kernel to implement the windows interface presented by + draw(3) and window(3) and probably have little use outside of + the kernel. +
+ + The basic function is to extend the definition of a Memimage (see + memdraw(3)) to include overlapping windows defined by the Memlayer + type. The first fields of the Memlayer structure are identical + to those in Memimage, permitting a function that expects a Memimage + to be passed a Memlayer, and vice versa. + Both structures have a save field, which is nil in a Memimage + and points to ‘backing store’ in a Memlayer. The layer routines + accept Memimages or Memlayers; if the image is a Memimage the + underlying 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 Memimage, either the display on which the window appears, + or the backing store. +
+ + Memlayers are associated with a Memscreen that holds the data + structures to maintain the windows and connects them to the associated + image. The fill color is used to paint the background when a window + is deleted. There is no function to establish a Memscreen; to + create one, allocate the memory, zero + frontmost and rearmost, set fill to a valid fill color or image, + and set image to the Memimage (or Memlayer) on which the windows + will be displayed. +
+ + Memlalloc allocates a Memlayer of size r on Memscreen s. If col + is not DNofill, the new window will be initialized by painting + it that color. +
+ + The refresh function fn and associated argument 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 arg recorded when the + window was created. A couple of predefined functions provide built-in + management methods: memlnorefresh does no backup at all, useful + for making efficient temporary windows; while a nil function specifies + that the backing store + (Memlayer.save) will be used to keep the obscured data. Other + functions may be provided by the client. Memlsetrefresh allows + one to change the function associated with the window. +
+ + Memldelete deletes the window i, restoring the underlying display. + Memlfree frees the data structures without unlinking the window + from the associated Memscreen or doing any graphics. +
+ + Memlexpose restores rectangle r within the window, using the backing + store or appropriate refresh method. Memlhide goes the other way, + backing up r so that that portion of the screen may be modified + without losing the data in this window. +
+ + Memltofront pulls i to the front of the stack of windows, making + it fully visible. Memltofrontn pulls the n windows in the array + ia to the front as a group, leaving their internal order unaffected. + Memltorear and memltorearn push the windows to the rear. +
+ + Memlorigin changes the coordinate systems associated with the + window i. The points log and phys represent the upper left corner + (min) of the window’s internal coordinate system and its physical + location on the screen. Changing 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 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 + +
+ + +
+ + memlorigin(i, i−>r.min, i−>r.min)
+ +
+ +
+ would be a no-op. +
+ + Memdraw and memline are implemented in the layer library but provide + the main entry points for drawing on memory-resident windows. + They have the signatures of memimagedraw and memimageline (see + memdraw(3)) but accept Memlayer or Memimage arguments both. +
+ + Memload and memunload are similarly layer-savvy versions of loadmemimage + and unloadmemimage. The iscompressed flag to memload specifies + whether the n bytes of data in buf are in compressed image format + (see image(7)).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), memdraw(3), stringsize(3), window(3), draw(3)
+ +
+

BUGS
+ +
+ + These functions are archived into libdraw.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/memory.html b/man/man3/memory.html new file mode 100644 index 00000000..a67101b7 --- /dev/null +++ b/man/man3/memory.html @@ -0,0 +1,123 @@ + +memory(3) - Plan 9 from User Space + + + + +
+
+
MEMORY(3)MEMORY(3) +
+
+

NAME
+ +
+ + memccpy, memchr, memcmp, memcpy, memmove, memset – memory operations
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + void* memccpy(void *s1, void *s2, int c, long n) +
+ + void* memchr(void *s, int c, long n) +
+ + int     memcmp(void *s1, void *s2, long n) +
+ + void* memcpy(void *s1, void *s2, long n) +
+ + void* memmove(void *s1, void *s2, long n) +
+ + void* memset(void *s, int c, long n)
+ +
+

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. +
+ + Memccpy copies bytes from memory area s2 into s1, stopping after + the first occurrence of byte c has been copied, or after n bytes + have been copied, whichever comes first. It returns a pointer + to the byte after the copy of c in s1, or zero if c was not found + in the first n bytes of s2. +
+ + Memchr returns a pointer to the first occurrence of byte c in + the first n bytes of memory area s, or zero if c does not occur. + +
+ + Memcmp compares its arguments, looking at the first n bytes only, + and returns an integer less than, equal to, or greater than 0, + according as s1 is lexicographically less than, equal to, or greater + than s2. The comparison is bytewise unsigned. +
+ + Memcpy copies n bytes from memory area s2 to s1. It returns s1. + +
+ + Memmove works like memcpy, except that it is guaranteed to work + if s1 and s2 overlap. +
+ + Memset sets the first n bytes in memory area s to the value of + byte c. It returns s.
+ +
+

SOURCE
+ +
+ + All these routines have portable C implementations in /usr/local/plan9/src/lib9.
+ +
+

SEE ALSO
+ +
+ + strcat(3)
+ +
+

BUGS
+ +
+ + ANSI C does not require memcpy to handle overlapping source and + destination; on Plan 9, it does, so memmove and memcpy behave + identically. +
+ + If memcpy and memmove are handed a negative count, they abort.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mouse.html b/man/man3/mouse.html new file mode 100644 index 00000000..5e2b278d --- /dev/null +++ b/man/man3/mouse.html @@ -0,0 +1,249 @@ + +mouse(3) - Plan 9 from User Space + + + + +
+
+
MOUSE(3)MOUSE(3) +
+
+

NAME
+ +
+ + initmouse, readmouse, closemouse, moveto, cursorswitch, getrect, + drawgetrect, menuhit, setcursor – mouse control
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <thread.h>
+ #include <mouse.h>
+ #include <cursor.h>
+ +
+ + Mousectl    *initmouse(char *file, Image *i)
+ +
+ + int         readmouse(Mousectl *mc)
+ +
+ + int         atomouse();
+ +
+ + void        closemouse(Mousectl *mc)
+ +
+ + void        moveto(Mousectl *mc, Point pt)
+ +
+ + void        setcursor(Mousectl *mc, Cursor *c)
+ +
+ + Rectangle getrect(int but, Mousectl *mc)
+ +
+ + void        drawgetrect(Rectangle r, int up)
+ +
+ + int         menuhit(int but, Mousectl *mc, Menu *menu, Screen *scr)
+ +
+

DESCRIPTION
+ +
+ + These functions access and control a mouse in a multi-threaded + environment. They use the message-passing Channel interface in + the threads library (see thread(3)); programs that wish a more + event-driven, single-threaded approach should use event(3). +
+ + The state of the mouse is recorded in a structure, Mouse, defined + in <mouse.h>:
+ +
+ + typedef struct Mouse Mouse;
+ struct Mouse
+ {
+ +
+ + int         buttons;     /* bit array: LMR=124 */
+ Point       xy;
+ ulong       msec;
+ +
+ };
+ +
+ + +
+ The Point xy records the position of the cursor, 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 msec, a millisecond time stamp. +
+ + The routine initmouse returns a structure through which one may + access the mouse:
+ +
+ + 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 */
+ +
+ };
+ +
+ + +
+ The arguments to initmouse are a file naming the device file connected + to the mouse and an Image (see draw(3)) on which the mouse will + be visible. Typically the file is nil, which requests the default + /dev/mouse; and the image is the window in which the program is + running, held in the variable screen after a call + to initdraw. +
+ + Once the Mousectl is set up, mouse motion will be reported by + messages of type Mouse sent on the Channel Mousectl.c. Typically, + a message will be sent every time a read of /dev/mouse succeeds, + which is every time the state of the mouse changes. +
+ + When the window is resized, a message is sent on Mousectl.resizec. + The actual value sent may be discarded; the receipt of the message + tells the program that it should call getwindow (see graphics(3)) + to reconnect to the window. +
+ + Readmouse updates the Mouse structure held in the Mousectl, blocking + if the state has not changed since the last readmouse or message + sent on the channel. It calls flushimage (see graphics(3)) before + blocking, so any buffered graphics requests are displayed. +
+ + Closemouse closes the file descriptors associated with the mouse, + kills the slave processes, and frees the Mousectl structure. +
+ + Moveto moves the mouse cursor on the display to the position specified + by pt. +
+ + Setcursor sets the image of the cursor to that specified by c. + If c is nil, the cursor is set to the default. The format of the + cursor data is spelled out in <cursor.h> and described in graphics(3). + +
+ + Getrect returns the dimensions of a rectangle swept by the user, + using the mouse, in the manner rio(1) or sam(1) uses to create + a new window. The 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. +
+ + Getrect uses successive calls to drawgetrect to maintain the red + rectangle showing the sweep-in-progress. The rectangle to be drawn + is specified by rc and the up parameter says whether to draw (1) + or erase (0) the rectangle. +
+ + Menuhit provides a simple menu mechanism. It uses a Menu structure + defined in <mouse.h>:
+ +
+ + typedef struct Menu Menu;
+ struct Menu
+ {
+ +
+ + char        **item;
+ char        *(*gen)(int);
+ int         lasthit;
+ +
+ };
+ +
+ + +
+ Menuhit behaves the same as its namesake emenuhit described in + event(3), with two exceptions. First, it uses a Mousectl to access + the mouse rather than using the event interface; and second, it + creates the menu as a true window on the Screen scr (see window(3)), + permitting the menu to be displayed in parallel + with other activities on the display. If scr is null, menuhit + behaves like emenuhit, creating backing store for the menu, writing + the menu directly on the display, and restoring the display when + the menu is removed. +
+ + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), event(3), keyboard(3), thread(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mousescrollsize.html b/man/man3/mousescrollsize.html new file mode 100644 index 00000000..3aa816fb --- /dev/null +++ b/man/man3/mousescrollsize.html @@ -0,0 +1,108 @@ + +mousescrollsize(3) - Plan 9 from User Space + + + + +
+
+
MOUSESCROLLSIZE(3)MOUSESCROLLSIZE(3) +
+
+

NAME
+ +
+ + mousescrollsize – compute mouse scroll increment
+ +
+

SYNOPSIS
+ +
+ + #include <draw.h> +
+ + int     mousescrollsize(int maxlines)
+ +
+

DESCRIPTION
+ +
+ + Mousescrollsize computes the number of lines of text that should + be scrolled in response to a mouse scroll wheel click. Maxlines + is the number of lines visible in the text window. +
+ + The default scroll increment is one line. This default can be + overridden by setting the $mousescrollsize environment variable + to an integer, which specifies a constant number of lines, or + to a real number followed by a percent character, indicating that + the scroll increment should be a percentage of the total + number of lines in the window. For example, setting $mousescrollsize + to 50% causes a half-window scroll increment. +
+ + Mousescrollsize is used by 9term(1) and acme(1) to set their scrolling + behavior.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw/scroll.c
+ +
+

SEE ALSO
+ +
+ + 9term(1), acme(1)
+ +
+

BUGS
+ +
+ + Libdraw expects up and down scroll wheel events to be expressed + as clicks of mouse buttons 4 and 5, but the XFree86 default is + to ignore the scroll wheel. To enable the scroll wheel, change + your InputDevice section of XF86Config−4 to look like:
+ +
+ + Section "InputDevice"
+ +
+ + Identifier       "Mouse0"
+ Driver      "mouse"
+ Option      "Device" "/dev/psaux"
+ # next four lines enable scroll wheel as buttons 4 and 5
+ Option      "Buttons" "5"
+ Option      "Emulate3Buttons" "off"
+ Option      "Protocol" "ImPS/2"
+ Option      "ZAxisMapping" "4 5"
+ +
+ EndSection
+ +
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mp.html b/man/man3/mp.html new file mode 100644 index 00000000..86dc7455 --- /dev/null +++ b/man/man3/mp.html @@ -0,0 +1,441 @@ + +mp(3) - Plan 9 from User Space + + + + +
+
+
MP(3)MP(3) +
+
+

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, mpfactorial, + mpcmp, mpextendedgcd, + mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, + mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, + crtpre, crtin, crtout, crtprefree, crtresfree – extended precision + arithmetic
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h> +
+ + mpint*      mpnew(int n) +
+ + void mpfree(mpint *b) +
+ + void mpsetminbits(int n) +
+ + void mpbits(mpint *b, int n) +
+ + void mpnorm(mpint *b) +
+ + mpint*      mpcopy(mpint *b) +
+ + void mpassign(mpint *old, mpint *new) +
+ + mpint*      mprand(int bits, void (*gen)(uchar*, int), mpint *b) +
+ + mpint*      strtomp(char *buf, char **rptr, int base, mpint *b) +
+ + char*       mptoa(mpint *b, int base, char *buf, int blen) +
+ + int    mpfmt(Fmt*) +
+ + mpint*      betomp(uchar *buf, uint blen, mpint *b) +
+ + int    mptobe(mpint *b, uchar *buf, uint blen, uchar **bufp) +
+ + mpint*      letomp(uchar *buf, uint blen, mpint *b) +
+ + int    mptole(mpint *b, uchar *buf, uint blen, uchar **bufp) +
+ + uint mptoui(mpint*) +
+ + mpint*      uitomp(uint, mpint*) +
+ + int    mptoi(mpint*) +
+ + mpint*      itomp(int, mpint*) +
+ + mpint*      vtomp(vlong, mpint*) +
+ + vlong       mptov(mpint*) +
+ + mpint*      uvtomp(uvlong, mpint*) +
+ + uvlong      mptouv(mpint*) +
+ + void mpadd(mpint *b1, mpint *b2, mpint *sum) +
+ + void mpmagadd(mpint *b1, mpint *b2, mpint *sum) +
+ + void mpsub(mpint *b1, mpint *b2, mpint *diff) +
+ + void mpmagsub(mpint *b1, mpint *b2, mpint *diff) +
+ + void mpleft(mpint *b, int shift, mpint *res) +
+ + void mpright(mpint *b, int shift, mpint *res) +
+ + void mpmul(mpint *b1, mpint *b2, mpint *prod) +
+ + void mpexp(mpint *b, mpint *e, mpint *m, mpint *res) +
+ + void mpmod(mpint *b, mpint *m, mpint *remainder) +
+ + void mpdiv(mpint *dividend, mpint *divisor,    mpint *quotient, mpint + *remainder) +
+ + mpint*      mpfactorial(ulong n) +
+ + int    mpcmp(mpint *b1, mpint *b2) +
+ + int    mpmagcmp(mpint *b1, mpint *b2) +
+ + void mpextendedgcd(mpint *a, mpint *b, mpint *d, mpint *x, mpint + *y) +
+ + void mpinvert(mpint *b, mpint *m, mpint *res) +
+ + int    mpsignif(mpint *b) +
+ + int    mplowbits0(mpint *b) +
+ + void mpdigdiv(mpdigit *dividend, mpdigit divisor, mpdigit *quotient) + +
+ + void mpvecadd(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit + *sum) +
+ + void mpvecsub(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit + *diff) +
+ + void mpvecdigmuladd(mpdigit *b, int n, mpdigit m, mpdigit *p) + +
+ + int    mpvecdigmulsub(mpdigit *b, int n, mpdigit m, mpdigit *p) +
+ + void mpvecmul(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit + *p) +
+ + int    mpveccmp(mpdigit *a, int alen, mpdigit *b, int blen) +
+ + CRTpre*     crtpre(int nfactors, mpint **factors) +
+ + CRTres*     crtin(CRTpre *crt, mpint *x) +
+ + void crtout(CRTpre *crt, CRTres *r, mpint *x) +
+ + void crtprefree(CRTpre *cre) +
+ + void crtresfree(CRTres *res) +
+ + mpint       *mpzero, *mpone, *mptwo
+ +
+

DESCRIPTION
+ +
+ + +
+ + These routines perform extended precision integer arithmetic. + The basic type is mpint, which points to an array of mpdigits, + stored in little-endian order:
+ typedef struct mpint mpint;
+ struct mpint
+ {
+ +
+ + int    sign;     /* +1 or −1 */
+ int    size;     /* allocated digits */
+ int    top;      /* significant digits */
+ mpdigit     *p;
+ char flags;
+ +
+ };
+ +
+ + The sign of 0 is +1. +
+ + The size of mpdigit is architecture-dependent and defined in /$cputype/include/u.h. + Mpints are dynamically allocated and must be explicitly freed. + Operations grow the array of digits as needed. +
+ + In general, the result parameters are last in the argument list. + +
+ + Routines that return an mpint will allocate the mpint if the result + parameter is nil. This includes strtomp, itomp, uitomp, and btomp. + These functions, in addition to mpnew and mpcopy, will return + nil if the allocation fails. +
+ + Input and result parameters may point to the same mpint. The routines + check and copy where necessary. +
+ + Mpnew creates an mpint with an initial allocation of n bits. If + n is zero, the allocation will be whatever was specified in the + last call to mpsetminbits or to the initial value, 1056. Mpfree + frees an mpint. Mpbits grows the allocation of b to fit at least + n bits. If b−>top doesn’t cover n bits it increases it to do so. + Unless + you are writing new basic operations, you can restrict yourself + to mpnew(0) and mpfree(b). +
+ + Mpnorm normalizes the representation by trimming any high order + zero digits. All routines except mpbits return normalized results. + +
+ + Mpcopy creates a new mpint with the same value as b while mpassign + sets the value of new to be that of old. +
+ + Mprand creates an n bit random number using the generator gen. + Gen takes a pointer to a string of uchar’s and the number to fill + in. +
+ + Strtomp and mptoa convert between ASCII and mpint representations + using the base indicated. Only the bases 10, 16, 32, and 64 are + supported. Anything else defaults to 16. Strtomp skips any leading + spaces or tabs. Strtomp’s scan stops when encountering a digit + not valid in the base. If rptr is not zero, *rptr is + set to point to the character immediately after the string converted. + If the parse pterminates before any digits are found, strtomp + return nil. Mptoa returns a pointer to the filled buffer. If the + parameter buf is nil, the buffer is allocated. Mpfmt can be used + with fmtinstall(3) and print(3) to print hexadecimal + representations of mpints. +
+ + Mptobe and mptole convert an mpint to a byte array. The former + creates a big endian representation, the latter a little endian + one. If the destination buf is not nil, it specifies the buffer + of length blen for the result. If the representation is less than + blen bytes, the rest of the buffer is zero filled. If buf is nil, + then a + buffer is allocated and a pointer to it is deposited in the location + pointed to by bufp. Sign is ignored in these conversions, i.e., + the byte array version is always positive. +
+ + Betomp, and letomp convert from a big or little endian byte array + at buf of length blen to an mpint. If b is not nil, it refers + to a preallocated mpint for the result. If b is nil, a new integer + is allocated and returned as the result. +
+ + The integer conversions are:
+ mptoui    mpint->unsigned int
+ uitomp    unsigned int->mpint
+ mptoi     mpint->int
+ itomp     int->mpint
+ mptouv    mpint->unsigned vlong
+ uvtomp    unsigned vlong->mpint
+ mptov     mpint->vlong
+ vtomp     vlong->mpint +
+ + When converting to the base integer types, if the integer is too + large, the largest integer of the appropriate sign and size is + returned. +
+ + The mathematical functions are:
+ mpadd      sum = b1 + b2.
+ mpmagadd   sum = abs(b1) + abs(b2).
+ mpsub      diff = b1 − b2.
+ mpmagsub    diff = abs(b1) − abs(b2).
+ mpleft      res = b<<shift.
+ mpright     res = b>>shift.
+ mpmul      prod = b1*b2.
+ mpexp      if m is nil, res = b**e. Otherwise, res = b**e mod m.
+ mpmod      remainder = b % m.
+ mpdiv      quotient = dividend/divisor. remainder = dividend % divisor.
+ mpfactorial   returns factorial of n.
+ mpcmp      returns -1, 0, or +1 as b1 is less than, equal to, or greater + than b2.
+ mpmagcmp   the same as mpcmp but ignores the sign and just compares + magnitudes. +
+ + Mpextendedgcd computes the greatest common denominator, d, of + a and b. It also computes x and y such that a*x + b*y = d. Both + a and b are required to be positive. If called with negative arguments, + it will return a gcd of 0. +
+ + Mpinverse computes the multiplicative inverse of b mod m. +
+ + Mpsignif returns the bit offset of the left most 1 bit in b. Mplowbits0 + returns the bit offset of the right most 1 bit. For example, for + 0x14, mpsignif would return 4 and mplowbits0 would return 2. +
+ + The remaining routines all work on arrays of mpdigit rather than + 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.
+ mpdigdiv          quotient = dividend[0:1] / divisor.
+ mpvecadd          sum[0:alen] = a[0:alen−1] + b[0:blen−1]. We assume alen + >= blen and that sum has room for alen+1 digits.
+ mpvecsub          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.
+ mpvecdigmuladd     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.
+ mpvecdigmulsub     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.
+ mpvecmul         p[0:alen*blen] = a[0:alen−1] * b[0:blen−1]. We assume + that p has room for alen*blen+1 digits.
+ mpveccmp         This returns -1, 0, or +1 as a - b is negative, 0, or + positive. +
+ + mptwo, mpone and mpzero are the constants 2, 1 and 0. These cannot + be freed.
+

Chinese remainder theorem
+ +
+ + When computing in a non-prime modulus, n, it is possible to perform + the computations on the residues modulo the prime factors of n + instead. Since these numbers are smaller, multiplication and exponentiation + can be much faster. +
+ + Crtin computes the residues of x and returns them in a newly allocated + structure:
+ +
+ + typedef struct CRTres      CRTres;
+ {
+ +
+ + int    n;     // number of residues
+ mpint       *r[n];      // residues
+ +
+ };
+ +
+ + +
+ Crtout takes a residue representation of a number and converts + it back into the number. It also frees the residue structure. + +
+ + 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. +
+ + Crtprefree and crtresfree free CRTpre and CRTres structures respectively.
+ +

+

SOURCE
+ +
+ + /usr/local/plan9/src/libmp
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/muldiv.html b/man/man3/muldiv.html new file mode 100644 index 00000000..486020ca --- /dev/null +++ b/man/man3/muldiv.html @@ -0,0 +1,61 @@ + +muldiv(3) - Plan 9 from User Space + + + + +
+
+
MULDIV(3)MULDIV(3) +
+
+

NAME
+ +
+ + muldiv, umuldiv – high-precision multiplication and division
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + long    muldiv(long a, long b, long c) +
+ + ulong umuldiv(ulong a, ulong b, ulong c)
+ +
+

DESCRIPTION
+ +
+ + Muldiv returns a*b/c, using a vlong to hold the intermediate result. + Umuldiv is the equivalent for unsigned integers. They can be used + to scale integer values without worry about overflowing the intermediate + result. +
+ + On some architectures, these routines can generate a trap if the + final result does not fit in a long or ulong; on others they will + silently truncate.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/mux.html b/man/man3/mux.html new file mode 100644 index 00000000..e3e7e4c8 --- /dev/null +++ b/man/man3/mux.html @@ -0,0 +1,169 @@ + +mux(3) - Plan 9 from User Space + + + + +
+
+
MUX(3)MUX(3) +
+
+

NAME
+ +
+ + Mux, muxinit, muxrpc, muxthreads – protocol multiplexor
+ +
+

SYNOPSIS
+ +
+ + #include <mux.h> +
+ + struct Mux
+ {
+ +
+ + uint mintag;
+ uint maxtag;
+ int (*settag)(Mux *mux, void *msg, uint tag);
+ int (*gettag)(Mux *mux, void *msg);
+ int (*send)(Mux *mux, void *msg);
+ void *(*recv)(Mux *mux);
+ void *aux;
+ ... /* private fields follow */
+ +
+ };
+ +
+ + void    muxinit(Mux *mux);
+ +
+ + void* muxrpc(Mux *mux, void *request);
+ +
+ + void    muxprocs(Mux *mux);
+ +
+

DESCRIPTION
+ +
+ + Libmux is a generic protocol multiplexor. A client program initializes + a Mux structure with information about the protocol (mainly in + the form of helper functions) and can then use muxrpc to execute + individual RPCs without worrying about details of multiplexing + requests and demultiplexing responses. +
+ + Libmux assumes that the protocol messages contain a tag (or message + ID) field that exists for the sole purpose of demultiplexing messages. + Libmux chooses the tags and then calls a helper function to put + them in the outgoing messages. Libmux calls another helper function + to retrieve tags from incoming messages. + It also calls helper functions to send and receive packets. +
+ + A client should allocate a Mux structure and then call muxinit + to initialize the library’s private elements. The client must + initialize the following elements:
+ mintag, maxtag
+ +
+ + The range of valid tags; maxtag is the maximum valid tag plus + one, so that maxtag–mintag is equal to the number of valid tags. + If libmux runs out of tags (all tags are being used for RPCs currently + in progress), a new call to muxrpc will block until an executing + call finishes.
+ +
+ settag, gettag
+ +
+ + Set or get the tag value in a message.
+ +
+ send, recv
+ +
+ + Send or receive protocol messages on the connection. Recv should + block until a message is available and should return nil if the + connection is closed. Libmux will arrange that only one call to + recv is active at a time.
+ +
+ aux   An auxiliary pointer for use by the client. Once a client has + initialized the Mux structure, it can call muxrpc to execute RPCs. + The request is the message passed to settag and send. The return + value is the response packet, as provided by recv, or nil if an + error occurred. Muxprocs allocates new procs (see + +
+ + thread(3)) in which to run send and recv. After a call to muxprocs, + muxrpc will run send and recv in these procs instead of in the + calling proc. This is useful if the implementation of either (particularly + recv) blocks an entire proc and there are other threads in the + calling proc that need to remain active. + +
+ +
+

EXAMPLE
+ +
+ + See /usr/local/plan9/src/lib9pclient/fs.c for an example of using + libmux with 9P (see intro(9p)).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmux
+ +
+

SEE ALSO
+ +
+ + thread(3), intro(9p)
+ +
+

BUGS
+ +
+ + Libmux does not know how to free protocol messages, so message + arriving with unexpected or invalid tags are leaked. +
+ + Using mintag other than zero is not well tested and probably buggy.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/nan.html b/man/man3/nan.html new file mode 100644 index 00000000..e644116b --- /dev/null +++ b/man/man3/nan.html @@ -0,0 +1,79 @@ + +nan(3) - Plan 9 from User Space + + + + +
+
+
NAN(3)NAN(3) +
+
+

NAME
+ +
+ + NaN, Inf, isNaN, isInf – not-a-number and infinity functions
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + double NaN(void) +
+ + double Inf(int) +
+ + int      isNaN(double) +
+ + int      isInf(double, int)
+ +
+

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. +
+ + NaN returns a double that is not-a-number. IsNaN returns true + if its argument is not-a-number. +
+ + Inf(i) returns positive infinity if i is greater than or equal + to zero, else negative infinity. IsInf returns true if its first + argument is infinity with the same sign as the second argument.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/nan.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/needstack.html b/man/man3/needstack.html new file mode 100644 index 00000000..bba5fbe8 --- /dev/null +++ b/man/man3/needstack.html @@ -0,0 +1,98 @@ + +needstack(3) - Plan 9 from User Space + + + + +
+
+
NEEDSTACK(3)NEEDSTACK(3) +
+
+

NAME
+ +
+ + needstack – check for execution stack overflow
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + int    needstack(int n)
+ +
+

DESCRIPTION
+ +
+ + Stack overflow in the thread library leads to bugs that are difficult + to diagnose. The Plan 9 libraries are careful about not allocating + large structures on the stack, so typically four or eight kilobytes + is plenty of stack for a thread. Other libraries are not always + as careful. Calling needstack indicates to the thread library + that an external routine is about to be called that will require + n bytes of stack space. If there is not enough space left on the + stack, the thread library prints an error and terminates the program. + The call needstack(0) can be used to check whether the stack is + currently overflowed. +
+ + Needstack is defined in libc.h so that library functions used + in threaded and non-threaded contexts can call it. The implementation + of needstack in lib9 is a no-op. +
+ + Needstack should be thought of as a comment checked at run time, + like assert(3).
+ +
+

EXAMPLE
+ +
+ + The X Window library implementation of XLookupString allocates + some very large buffers on the stack, so /usr/local/plan9/src/libdraw/x11−itrans.c + calls needstack(20*1024) before making calls to XLookupString. + If a thread (in this case, the keyboard-reading thread used inside + the draw(3) + library) does not allocate a large enough stack, the problem is + diagnosed immediately rather than left to corrupt memory.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/needstack.c
+ /usr/local/plan9/src/libthread
+ +
+

SEE ALSO
+ +
+ + thread(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/notify.html b/man/man3/notify.html new file mode 100644 index 00000000..9899e701 --- /dev/null +++ b/man/man3/notify.html @@ -0,0 +1,183 @@ + +notify(3) - Plan 9 from User Space + + + + +
+
+
NOTIFY(3)NOTIFY(3) +
+
+

NAME
+ +
+ + notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff + – handle asynchronous process notification
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int notify(void (*f)(void*, char*)) +
+ + int noted(int v) +
+ + int atnotify(int (*f)(void*, char*), int in) +
+ + int noteenable(char *msg)
+ int notedisable(char *msg) +
+ + int notifyon(char *msg)
+ int notifyoff(char *msg)
+ +
+

DESCRIPTION
+ +
+ + When a process raises an exceptional condition such as dividing + by zero or writing on a closed pipe, a note is posted to communicate + the exception. A note may also be posted by another process via + postnote(3). On Unix, notes are implemented as signals. +
+ + When a note is received, the action taken depends on the note. + See signal(7) for the full description of the defaults. +
+ + The default actions may be overridden. The notify function registers + a notification handler to be called within the process when a + note is received. The argument to notify replaces the previous + handler, if any. An argument of zero cancels a previous handler, + restoring the default action. A fork(2) system call leaves the + handler registered in both the parent and the child; exec(3) restores + the default behavior. Handlers may not perform floating point + operations. +
+ + After a note is posted, the handler is called with two arguments: + the first is unimplemented and should not be used (on Plan 9 it + is a Ureg structure giving the current values of registers); the + second is a pointer to the note itself, a null-terminated string. + +
+ + A notification handler must finish either by exiting the program + or by calling noted; if the handler returns the behavior is undefined + and probably erroneous. Until the program calls noted, any further + externally-generated notes (e.g., hangup or 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 noted defines the action to take: NDFLT + instructs the system to perform the default action as if the handler + had never been registered; NCONT instructs the system to resume + the process at the point it was notified. In neither case + does noted return to the handler. If the note interrupted an incomplete + system call, that call returns an error (with error string interrupted) + after the process resumes. A notification handler can also jump + out to an environment set up with setjmp using the notejmp function + (see setjmp(3)). +
+ + Unix provides a fixed set of notes (typically there are 32) called + signals. It also allows a process to block certain notes from + being delivered (see sigprocmask(2)) and to ignore certain notes + by setting the signal hander to the special value SIG_IGN (see + signal(2)). Noteenable and notedisable enable or disable receipt + of + a particular note by changing the current process’s blocked signal + mask. Receipt of a disabled note will be postponed until it is + reenabled. Notifyon and notifyoff enable or disable whether the + notification handler is called upon receipt of the note; if the + handler is not called, the note is discarded. +
+ + Regardless of the origin of the note or the presence of a handler, + if the process is being debugged (see ptrace(2)) the arrival of + a note puts the process in the Stopped state and awakens the debugger. + +
+ + Rather than using the system calls notify and noted, most programs + should use atnotify to register notification handlers. The parameter + in is non-zero to register the function 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 atnotify is called with arguments as described + above until one of the handlers returns non-zero. Then noted is + called with argument NCONT. If no registered function returns + non-zero, atnotify calls noted with argument NDFLT. +
+ + The set of notes a process may receive is system-dependent, but + there is a common set that includes: +
+ + +
+ + Note                          Meaning               Unix signal
+ interrupt                    user interrupt (DEL key)     SIGINTR
+ hangup                       I/O connection closed      SIGHUP
+ alarm                        alarm expired           SIGLARM
+ quit                         quit from keyboard        SIGQUIT
+ kill                         process requested to exit    SIGTERM
+ sys: kill                    process forced to exit      SIGKILL
+ sys: bus error                bus error              SIGBUS
+ sys: segmentation violation    segmentation violation      SIGSEGV
+ sys: write on closed pipe      write on closed pipe       SIGPIPE
+ sys: child                    child wait status change     SIGCHLD
+ +
+ + +
+ See /usr/local/plan9/src/lib9/await.c (sic) for the full list. + +
+ + The notes prefixed sys: are usually generated by the operating + system.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/notify.c
+ /usr/local/plan9/src/lib9/atnotify.c
+ +
+

SEE ALSO
+ +
+ + intro(3), notejmp in setjmp(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/open.html b/man/man3/open.html new file mode 100644 index 00000000..64f85c55 --- /dev/null +++ b/man/man3/open.html @@ -0,0 +1,130 @@ + +open(3) - Plan 9 from User Space + + + + +
+
+
OPEN(3)OPEN(3) +
+
+

NAME
+ +
+ + open, create, close – open a file for reading or writing, create + file
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int open(char *file, int omode) +
+ + int create(char *file, int omode, ulong perm) +
+ + int close(int fd)
+ +
+

DESCRIPTION
+ +
+ + Open opens the file for I/O and returns an associated file descriptor. + Omode is one of OREAD, OWRITE, ORDWR, or 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 omode: OTRUNC + says to truncate the file to zero length + before opening it; OCEXEC says to close the file when an exec(3) + or execl system call is made; and ORCLOSE says to remove the file + when it is closed (by everyone who has a copy of the file descriptor). + Open fails if the file does not exist or the user does not have + permission to open it for the requested purpose (see + stat(3) for a description of permissions). The user must have + write permission on the file if the OTRUNC bit is set. For the + open system call (unlike the implicit open in exec(3)), OEXEC + is actually identical to OREAD. +
+ + Create creates a new file or prepares to rewrite an existing file, + opens it according to omode (as described for 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 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 DMDIR bit is set in perm, an exclusive-use file if the DMEXCL + bit is set, and an append-only file if the 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 open(9p). +
+ + Create fails if the path up to the last element of 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 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. +
+ + Since create may succeed even if the file exists, a special mechanism + is necessary for those applications that require an atomic create + operation. If the OEXCL (0x1000) bit is set in the mode for a + create, the call succeeds only if the file does not already exist; + see open(9p) for details. +
+ + Close closes the file associated with a file descriptor. Provided + the file descriptor is a valid open descriptor, close is guaranteed + to close it; there will be no error. Files are closed automatically + upon termination of a process; close allows the file descriptor + to be reused.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + intro(3), stat(3)
+ +
+

DIAGNOSTICS
+ +
+ + These functions set errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/opentemp.html b/man/man3/opentemp.html new file mode 100644 index 00000000..9ec47571 --- /dev/null +++ b/man/man3/opentemp.html @@ -0,0 +1,78 @@ + +opentemp(3) - Plan 9 from User Space + + + + +
+
+
OPENTEMP(3)OPENTEMP(3) +
+
+

NAME
+ +
+ + opentemp – create a uniquely-named file
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int opentemp(char *template)
+ +
+

DESCRIPTION
+ +
+ + Opentemp replaces template by a unique file name, and returns + the address of the template. The template should look like a file + name with eleven trailing Xs. The Xs are replaced by a letter + followed by the current process id. Letters from a to z are tried + until the name of a file that does not yet exist (see access(2)) + is + generated. Opentemp then creates the file for reading and writing + and returns the file descriptor. +
+ + If no such name can be generated, opentemp returns –1. +
+ + Opentemp avoids races. Two simultaneous calls to opentemp will + never return the same name.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/opentemp.c
+ +
+

SEE ALSO
+ +
+ + create in open(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/pipe.html b/man/man3/pipe.html new file mode 100644 index 00000000..b087ae8b --- /dev/null +++ b/man/man3/pipe.html @@ -0,0 +1,111 @@ + +pipe(3) - Plan 9 from User Space + + + + +
+
+
PIPE(3)PIPE(3) +
+
+

NAME
+ +
+ + pipe – create an interprocess channel
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int pipe(int fd[2])
+ +
+

DESCRIPTION
+ +
+ + Pipe creates a buffered channel for interprocess I/O communication. + Two file descriptors are returned in fd. Data written to fd[1] + is available for reading from fd[0] and data written to fd[0] + is available for reading from fd[1]. +
+ + After the pipe has been established, cooperating processes created + by subsequent fork(2) calls may pass data through the pipe with + read and write calls. +
+ + When all the data has been read from a pipe and the writer has + closed the pipe or exited, read(3) will return 0 bytes. Writes + to a pipe with no reader will generate a note sys: write on closed + pipe.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/pipe.c
+ +
+

SEE ALSO
+ +
+ + intro(3), read(3)
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+

BUGS
+ +
+ + If a read or a write of a pipe is interrupted, some unknown number + of bytes may have been transferred. +
+ + Pipe is a macro defined as p9pipe to avoid name conflicts with + Unix’s pipe system call. +
+ + Unix pipes are not guaranteed to be bidirectional. In order to + ensure a bidirectional channel, p9pipe creates Unix domain sockets + via the socketpair(2) instead of Unix pipes. +
+ + The implementation of pipes as Unix domain sockets causes problems + with some Unix implementations of /dev/fd, Unix’s dup device. + If a Unix domain socket is open as file descriptor 0, some implementations + disallow the opening of /dev/fd/0; instead one must connect(2) + to it. If this functionality is important + (as it is for rc(1)), one must #undef pipe and fall back on the + (possibly unidirectional) Unix pipes.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/plumb.html b/man/man3/plumb.html new file mode 100644 index 00000000..d7649698 --- /dev/null +++ b/man/man3/plumb.html @@ -0,0 +1,257 @@ + +plumb(3) - Plan 9 from User Space + + + + +
+
+
PLUMB(3)PLUMB(3) +
+
+

NAME
+ +
+ + eplumb, plumbfree, plumbopen, plumbopenfid, plumbsend, plumbsendtofid, + plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, + plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, + plumbunpackattr, Plumbmsg – plumb messages
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <plumb.h> +
+ + +
+ + int          plumbopen(char *port, int omode) +
+ + int          plumbsend(int fd, Plumbmsg *m) +
+ + int          plumbsendtext(int fd, char *src, char *dst, char *wdir, char + *data) +
+ + void         plumbfree(Plumbmsg *m) +
+ + Plumbmsg*    plumbrecv(int fd) +
+ + char*        plumbpack(Plumbmsg *m, int *np) +
+ + Plumbmsg*    plumbunpack(char *buf, int n) +
+ + Plumbmsg*    plumbunpackpartial(char *buf, int n, int *morep) +
+ + char*        plumbpackattr(Plumbattr *a) +
+ + Plumbattr* plumbunpackattr(char *a) +
+ + char*        plumblookup(Plumbattr *a, char *name) +
+ + Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new) +
+ + Plumbattr* plumbdelattr(Plumbattra *a, char *name) +
+ + int          eplumb(int key, char *port) +
+ + #include <9pclient.h> +
+ + CFid         *plumbopenfid(char *port, int omode) +
+ + Plumbmsg*    plumbrecvfid(CFid *fid) +
+ + int          plumbsendtofid(CFid *fid, Plumbmsg *m)
+ +
+

DESCRIPTION
+ +
+ + These routines manipulate plumb(7) messages, transmitting them, + receiving them, and converting them between text and these data + structures:
+ +
+ + 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;
+ +
+ + +
+ Plumbopen opens the named plumb port, using open(3) mode omode. + If port begins with a slash, it is taken as a literal file name; + otherwise plumbopen searches for the location of the plumber(4) + service and opens the port there. +
+ + For programs using the event(3) interface, eplumb registers, using + the given key, receipt of messages from the named port. +
+ + Plumbsend formats and writes message m to the file descriptor + fd, which will usually be the result of plumbopen("send", OWRITE). + Plumbsendtext is a simplified version for text-only messages; + it assumes type is text, sets attr to nil, and sets ndata to strlen(data). + +
+ + Plumbfree frees all the data associated with the message m, all + the components of which must therefore have been allocated with + malloc(3). +
+ + Plumbrecv returns the next message available on the file descriptor + fd, or nil for error. +
+ + Plumbpack encodes message m as a character string in the format + of plumb(7), setting *np to the length in bytes of the string. + Plumbunpack does the inverse, translating the n bytes of buf into + a Plumbmsg. +
+ + Plumbunpackpartial enables unpacking of messages that arrive in + pieces. The first call to plumbunpackpartial for a given message + must be sufficient to unpack the header; subsequent calls permit + unpacking messages with long data sections. For each call, buf + points to the beginning of the complete message received + so far, and n reports the total number of bytes received for that + message. If the message is complete, the return value will be + as in plumbunpack. If not, and morep is not null, the return value + will be nil and *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 buf+n, and the message unpacked + again. If an error is encountered, the return value will be nil + and *morep will be zero. +
+ + Plumbpackattr converts the list a of 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. + Plumbunpackattr converts the null-terminated string a back into + a list of Plumbattr structures. +
+ + Plumblookup searches the Plumbattr list a for an attribute with + the given 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. +
+ + Plumbaddattr appends the new Plumbattr (which may be a list) to + the attribute list a and returns the new list. Plumbattr searches + the list a for the first attribute with name name and deletes + it from the list, returning the resulting list. Plumbdelattr is + a no-op if no such attribute exists. +
+ + The file descriptor returned by plumbopen is created with fsopenfd + (see 9pclient(3)), which masks information about read and write + errors. This is acceptable for use in plumbrecv but not for plumbsend, + which depends on seeing details of write errors. Plumbopenfid, + plumbrecvfid, and plumbsendtofid provide an + explicit interface to lib9pclient that preserves the exact error + details.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libplumb
+ +
+

SEE ALSO
+ +
+ + plumb(1), event(3), plumber(4), plumb(7)
+ +
+

DIAGNOSTICS
+ +
+ + When appropriate, including when a plumbsend fails, these routine + set errstr.
+ +
+

BUGS
+ +
+ + To avoid rewriting clients that use plumbsend, the call plumbopen("send", + OWRITE) returns a useless file descriptor (it is opened to /dev/null). + Plumbsend looks for this particular file descriptor and uses a + static copy of the CFid instead.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/post9pservice.html b/man/man3/post9pservice.html new file mode 100644 index 00000000..62238d0d --- /dev/null +++ b/man/man3/post9pservice.html @@ -0,0 +1,67 @@ + +post9pservice(3) - Plan 9 from User Space + + + + +
+
+
POST9PSERVICE(3)POST9PSERVICE(3) +
+
+

NAME
+ +
+ + post9pservice – post 9P service for use by clients
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int post9pservice(int fd, char *name)
+ +
+

DESCRIPTION
+ +
+ + Post9pservice invokes 9pserve(4) to post a new 9P service in the + current “name space” (see intro(4)) named name. Clients connecting + to the posted service are multiplexed onto a single 9P conversation + with the server on file descriptor fd.
+ +
+

SEE ALSO
+ +
+ + intro(4), 9pserve(4)
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/post9p.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/postnote.html b/man/man3/postnote.html new file mode 100644 index 00000000..b08507e5 --- /dev/null +++ b/man/man3/postnote.html @@ -0,0 +1,80 @@ + +postnote(3) - Plan 9 from User Space + + + + +
+
+
POSTNOTE(3)POSTNOTE(3) +
+
+

NAME
+ +
+ + postnote – send a note to a process or process group
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int    postnote(int who, int pid, char *note)
+ +
+

DESCRIPTION
+ +
+ + Postnote sends a note to a process or process group. If who is + PNPROC, then note is sent to the process with id pid. If who is + PNGROUP, the note is delivered to the process group which has + the process with id pid as a member. For PNGROUP only, if the + calling process is in the target group, the note is not delivered + to + that process. +
+ + If the write is successful, zero is returned. Otherwise –1 is returned.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/postnote.c
+ +
+

SEE ALSO
+ +
+ + notify(3), intro(3)
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/prime.html b/man/man3/prime.html new file mode 100644 index 00000000..abaffda0 --- /dev/null +++ b/man/man3/prime.html @@ -0,0 +1,114 @@ + +prime(3) - Plan 9 from User Space + + + + +
+
+
PRIME(3)PRIME(3) +
+
+

NAME
+ +
+ + genprime, gensafeprime, genstrongprime, DSAprimes, probably_prime, + smallprimetest – prime number generation
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + int    smallprimetest(mpint *p) +
+ + int    probably_prime(mpint *p, int nrep) +
+ + void genprime(mpint *p, int n, int nrep) +
+ + void gensafeprime(mpint *p, mpint *alpha, int n, int accuracy) + +
+ + void genstrongprime(mpint *p, int n, int nrep) +
+ + void DSAprimes(mpint *q, mpint *p, uchar seed[SHA1dlen])
+ +
+

DESCRIPTION
+ +
+ + +
+ + Public key algorithms abound in prime numbers. The following routines + generate primes or test numbers for primality. +
+ + Smallprimetest checks for divisibility by the first 10000 primes. + It returns 0 if p is not divisible by the primes and –1 if it is. + +
+ + Probably_prime uses the Miller-Rabin test to test p. It returns + non-zero if P is probably prime. The probability of it not being + prime is 1/4**nrep. +
+ + Genprime generates a random n bit prime. Since it uses the Miller-Rabin + test, nrep is the repetition count passed to probably_prime. Gensafegprime + generates an n-bit prime p and a generator alpha of the multiplicative + group of integers mod p; there is a prime q such that p-1=2*q. + Genstrongprime generates a + prime, p, with the following properties:
+ –     (p-1)/2 is prime. Therefore p-1 has a large prime factor, p’.
+ –p’-1 has a large prime factor
+ –p+1 has a large prime factor +
+ + DSAprimes generates two primes, q and p, using the NIST recommended + algorithm for DSA primes. q divides p-1. The random seed used + is also returned, so that skeptics can later confirm the computation. + Be patient; this is a slow algorithm.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + aes(3) blowfish(3), des(3), elgamal(3), rsa(3),
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/print.html b/man/man3/print.html new file mode 100644 index 00000000..8640efc7 --- /dev/null +++ b/man/man3/print.html @@ -0,0 +1,309 @@ + +print(3) - Plan 9 from User Space + + + + +
+
+
PRINT(3)PRINT(3) +
+
+

NAME
+ +
+ + print, fprint, sprint, snprint, seprint, smprint, runesprint, + runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, + vsmprint, runevsnprint, runevseprint, runevsmprint – print formatted + output
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + int     print(char *format, ...) +
+ + int     fprint(int fd, char *format, ...) +
+ + int     sprint(char *s, char *format, ...) +
+ + int     snprint(char *s, int len, char *format, ...) +
+ + char* seprint(char *s, char *e, char *format, ...) +
+ + char* smprint(char *format, ...) +
+ + int     runesprint(Rune *s, char *format, ...) +
+ + int     runesnprint(Rune *s, int len, char *format, ...) +
+ + Rune* runeseprint(Rune *s, Rune *e, char *format, ...) +
+ + Rune* runesmprint(char *format, ...) +
+ + int     vfprint(int fd, char *format, va_list v) +
+ + int     vsnprint(char *s, int len, char *format, va_list v) +
+ + char* vseprint(char *s, char *e, char *format, va_list v) +
+ + char* vsmprint(char *format, va_list v) +
+ + int     runevsnprint(Rune *s, int len, char *format, va_list v) +
+ + Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v) + +
+ + Rune* runevsmprint(Rune *format, va_list v) +
+ + +
+

DESCRIPTION
+ +
+ + Print writes text to the standard output. Fprint writes to the + named output file descriptor: a buffered form is described in + bio(3). Sprint places text followed by the NUL character (\0) + in consecutive bytes starting at 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 sprint), or a negative value if an output error was encountered. + +
+ + Snprint is like sprint, but will not place more than len bytes + in s. Its result is always NUL-terminated and holds the maximal + number of complete UTF-8 characters that can fit. Seprint is like + snprint, except that the end is indicated by a pointer e rather + than a count and the return value points to the terminating NUL + of + the resulting string. Smprint is like sprint, except that it prints + into and returns a string of the required length, which is allocated + by malloc(3). +
+ + The routines runesprint, runesnprint, runeseprint, and runesmprint + are the same as sprint, snprint, seprint and smprint except that + their output is rune strings instead of byte strings. +
+ + Finally, the routines vfprint, vsnprint, vseprint, vsmprint, runevsnprint, + runevseprint, and runevsmprint are like their v−less relatives + except they take as arguments a va_list parameter, so they can + be called within a variadic function. The Example section shows + a representative usage. +
+ + Each of these functions converts, formats, and prints its trailing + arguments under control of a 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. +
+ + Each conversion specification has the following format:
+ +
+ + % [flags] verb +
+ + +
+ 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 width, the second precision. A period + can be used to separate them, and if the period is present then + width and precision are taken to be zero if missing, otherwise + they are ‘omitted’. Either or both of the numbers may be replaced + with the character *, meaning that the actual number will be obtained + from the argument list as an integer. The flags and numbers are + arguments to the verb described below. +
+ + The numeric verbs d, o, b, x, and X format their arguments in + decimal, octal, binary, hexadecimal, and upper case hexadecimal. + Each interprets the flags 0, h, hh, l, u, +, −, ,, and # 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 +, 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 int. If unsigned + is specified, then the argument is interpreted as a positive number + and no sign is output. If two l flags are given, then + the argument is interpreted as a vlong (usually an 8-byte, sometimes + a 4-byte integer). If precision is not omitted, the number is + padded on the left with zeros until at least precision digits + appear. If precision is explicitly 0, and the number is 0, no + digits are generated, and alternate formatting does not apply. + Then, + if alternate format is specified, for o conversion, the number + is preceded by a 0 if it doesn’t already begin with one; for x + conversion, the number is preceded by 0x; for X conversion, the + number is preceded by 0X. Finally, if 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 width characters + long. +
+ + The floating point verbs f, e, E, g, and G take a double argument. + Each interprets the flags 0, L +, −, and # to mean pad with zeros, + long double argument, always print a sign, left justified, and + alternate format. Width is the minimum field width and, if the + converted value takes up less than width characters, it is + padded on the left (or right, if ‘left justified’) with spaces. + Precision is the number of digits that are converted after the + decimal place for e, E, and f conversions, and precision is the + maximum number of significant digits for g and G conversions. + The f verb produces output of the form [−]digits[.digits]. E + conversion appends an exponent E[−]digits, and e conversion appends + an exponent e[−]digits. The g verb will output the argument in + either e or 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 G verb is similar, but uses E format + instead of e. When alternate format is specified, the result will + always contain a decimal point, and for g and G conversions, trailing + zeros are not removed. +
+ + The s verb copies a NUL-terminated string (pointer to char) to + the output. The number of characters copied (n) is the minimum + of the size of the string and precision. These n characters are + justified within a field of width characters as described above. + If a precision is given, it is safe for the string not to be nul- + terminated as long as it is at least precision characters (not + bytes!) long. The S verb is similar, but it interprets its pointer + as an array of runes (see utf(7)); the runes are converted to + UTF before output. +
+ + The c verb copies a single char (promoted to int) justified within + a field of width characters as described above. The C verb is + similar, but works on runes. +
+ + The p verb formats a pointer value. At the moment, it is a synonym + for x, but that will change if pointers and integers are different + sizes. +
+ + The r verb takes no arguments; it copies the error string returned + by a call to errstr(3). +
+ + Custom verbs may be installed using fmtinstall(3).
+ +
+

EXAMPLE
+ +
+ + This function prints an error message with a variable number of + arguments and then quits.
+ +
+ + 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");
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/libfmt
+ +
+

SEE ALSO
+ +
+ + fmtinstall(3), fprintf(3), utf(7)
+ +
+

DIAGNOSTICS
+ +
+ + Routines that write to a file descriptor or call malloc set errstr.
+ +
+

BUGS
+ +
+ + The formatting is close to that specified for ANSI fprintf(3); + the main difference is that b and r are not in ANSI and u is a + flag here instead of a verb. Also, and distinctly not a bug, print + and friends generate UTF rather than ASCII. +
+ + There is no runeprint, runefprint, etc. because runes are byte-order + dependent and should not be written directly to a file; use the + UTF output of print or fprint instead. Also, sprint is deprecated + for safety reasons; use snprint, seprint, or smprint instead. + Safety also precludes the existence of runesprint. + +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/proto.html b/man/man3/proto.html new file mode 100644 index 00000000..59e4fccd --- /dev/null +++ b/man/man3/proto.html @@ -0,0 +1,140 @@ + +proto(3) - Plan 9 from User Space + + + + +
+
+
PROTO(3)PROTO(3) +
+
+

NAME
+ +
+ + rdproto – parse and process a proto file listing
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <disk.h>
+ +
+ + typedef void Protoenum(char *new, char *old, Dir *d, void *a)
+ +
+ + typedef void Protowarn(char *msg, void *a)
+ +
+ + int rdproto(char *proto, char *root, Protoenum *enm,
+ +
+ + +
+ + Protowarn *warn, void *a)
+ +
+ +
+ +
+

DESCRIPTION
+ +
+ + Rdproto reads and interprets the named proto file relative to + the root directory root. +
+ + Each line of the proto file specifies a file to copy. Blank lines + and lines beginning with # 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 + − for + permissions, owner, or group causes 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 + − is useful when one wishes to set, say, the file owner without + setting the permissions.) +
+ + Names beginning with a $ are expanded as environment variables. + If the first file specified in a directory is *, all of the files + in that directory are considered listed. If the first file is + +, all of the files are copied, and all subdirectories are recursively + considered listed. All files are considered relative to root. + +
+ + For each file named by the proto, enm is called with new pointing + at the name of the file (without the root prefix), old pointing + at the name of the source file (with the root prefix, when applicable), + and Dir at the desired directory information for the new file. + Only the name, uid, gid, mode, mtime, and length fields + are guaranteed to be valid. The argument a is the same argument + passed to rdproto; typically it points at some extra state used + by the enumeration function. +
+ + When files or directories do not exist or cannot be read by rdproto, + it formats a warning message, calls warn, and continues processing; + if warn is nil, rdproto prints the warning message to standard + error. +
+ + Rdproto returns zero if proto was processed, –1 if it could not + be opened.
+ +
+

FILES
+ +
+ + /sys/lib/sysconfig/proto/           directory of prototype files.
+ /sys/lib/sysconfig/proto/portproto   generic prototype file.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdisk/proto.c
+ +
+

SEE ALSO
+ +
+ + mk9660(8), Plan 9’s mkfs(8)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/pushtls.html b/man/man3/pushtls.html new file mode 100644 index 00000000..ee806701 --- /dev/null +++ b/man/man3/pushtls.html @@ -0,0 +1,261 @@ + +pushtls(3) - Plan 9 from User Space + + + + +
+
+
PUSHTLS(3)PUSHTLS(3) +
+
+

NAME
+ +
+ + pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, + okThumbprint, readcert, readcertchain – attach TLS1 or SSL3 encryption + to a communication channel
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int             pushtls(int fd, char *hashalg, char *encalg,
+ +
+ + +
+ + int isclient, char *secret, char *dir) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ #include <mp.h>
+ #include <libsec.h> +
+ + int             tlsClient(int fd, TLSconn *conn) +
+ + int             tlsServer(int fd, TLSconn *conn) +
+ + uchar           *readcert(char *filename, int *pcertlen) +
+ + PEMchain         *readcertchain(char *filename) +
+ + Thumbprint*      initThumbprints(char *ok, char *crl) +
+ + void            freeThumbprints(Thumbprint *table) +
+ + int             okThumbprint(uchar *hash, Thumbprint *table)
+ +
+

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. +
+ + To use just the record layer, as described in Plan 9’s tls(3), + call pushtls to open the record layer device, connect to the communications + channel fd, and start up encryption and message authentication + as specified in hashalg, encalg, and secret. These parameters + must have been arranged at the two ends of the + conversation by other means. For example, hashalg could be sha1, + encalg could be rc4_128, and 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. 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, fd. If dir is non-zero, + the path name of the connection directory is copied into dir. + This path name is guaranteed to be less than 40 bytes long. +
+ + Alternatively, call tlsClient to speak the full handshake protocol, + negotiate the algorithms and secrets, and return a new data file + descriptor for the data channel. Conn points to a (caller-allocated) + struct
+ +
+ + typedef struct TLSconn{
+ +
+ + char dir[40];       // OUT      connection directory
+ uchar *cert;        // IN/OUT certificate
+ uchar *sessionID; // IN/OUT sessionID
+ int certlen, sessionIDlen;
+ void (*trace)(char*fmt, ...);
+ PEMChain *chain;
+ +
+ } TLSconn;
+ +
+ defined in tls.h. On input, the caller can provide options such + as cert, the local certificate, and sessionID, used by a client + to resume a previously negotiated security association. On output, + the connection directory is set, as with listen (see dial(3)). + The input cert is freed and a freshly allocated copy of the remote’s + certificate is returned in conn, to be checked by the caller according + to its needs. One mechanism is supplied by initThumbprints and + freeThumbprints which allocate and free, respectively, a table + of hashes from files of known trusted and revoked certificates. + okThumbprint confirms that a particular hash is in the + table, as computed by +
+ + +
+ + uchar hash[SHA1dlen];
+ conn = (TLSconn*)mallocz(sizeof *conn, 1);
+ fd = tlsClient(fd, conn);
+ sha1(conn−>cert, conn−>certlen, hash, nil);
+ if(!okThumbprint(hash,table))
+ +
+ + exits("suspect server");
+ +
+ ...application begins...
+ +
+ + +
+ Call tlsServer to perform the corresponding function on the server + side: +
+ + +
+ + fd = accept(lcfd, ldir);
+ conn = (TLSconn*)mallocz(sizeof *conn, 1);
+ conn−>cert = readcert("cert.pem", &conn−>certlen);
+ fd = tlsServer(fd, conn);
+ ...application begins...
+ +
+ The private key corresponding to cert.pem should have been previously + loaded into factotum. (See rsa(3) for more about key generation.) + By setting
+ +
+ + conn−>chain = readcertchain("intermediate−certs.pem");
+ +
+ the server can present extra certificate evidence to establish + the chain of trust to a root authority known to the client. +
+ + Conn is not required for the ongoing conversation and may be freed + by the application whenever convenient.
+ +
+

FILES
+ +
+ + /sys/lib/tls
+ +
+ + thumbprints of trusted services
+ +
+ /sys/lib/ssl
+ +
+ + PEM certificate files
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec/port
+ +
+

SEE ALSO
+ +
+ + dial(3), thumbprint(7); Plan 9’s factotum(4) and tls(3)
+ +
+

DIAGNOSTICS
+ +
+ + return –1 on failure.
+ +
+

BUGS
+ +
+ + Pushtls is not implemented. +
+ + Client certificates and client sessionIDs are not yet implemented. + +
+ + Note that in the TLS protocol sessionID itself is public; it is + used as a pointer to secrets stored in factotum.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/qball.html b/man/man3/qball.html new file mode 100644 index 00000000..b1403336 --- /dev/null +++ b/man/man3/qball.html @@ -0,0 +1,111 @@ + +qball(3) - Plan 9 from User Space + + + + +
+
+
QBALL(3)QBALL(3) +
+
+

NAME
+ +
+ + qball – 3-d rotation controller
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <draw.h> +
+ + #include <geometry.h> +
+ + void qball(Rectangle r, Mouse *mousep,
+ +
+ + Quaternion *orientation,
+ void (*redraw)(void), Quaternion *ap)
+ +
+ +
+

DESCRIPTION
+ +
+ + 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 r, and diameter the smaller + of 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. + +
+ + Argument mousep is a pointer to the mouse event that triggered + the interaction. It should have some button set. Qball will read + more events into mousep, and return when no buttons are down. + +
+ + While qball is reading mouse events, it calls out to the caller-supplied + routine redraw, which is expected to update the screen to reflect + the changing orientation. Argument orientation is the orientation + that redraw should examine, represented as a unit Quaternion (see + quaternion(9.2)). The caller may set it to any + orientation. It will be updated before each call to redraw (and + on return) by multiplying by the rotation specified with the mouse. + +
+ + It is possible to restrict qball’s attention to rotations about + a particular axis. If ap is null, the rotation is unconstrained. + Otherwise, the rotation will be about the same axis as *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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libgeometry/qball.c
+ +
+

SEE ALSO
+ +
+ + quaternion(3)
+ Ken Shoemake, “Animating Rotation with Quaternion Curves”, SIGGRAPH + ’85 Conference Proceedings.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/quaternion.html b/man/man3/quaternion.html new file mode 100644 index 00000000..257ebe52 --- /dev/null +++ b/man/man3/quaternion.html @@ -0,0 +1,163 @@ + +quaternion(3) - Plan 9 from User Space + + + + +
+
+
QUATERNION(3)QUATERNION(3) +
+
+

NAME
+ +
+ + qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, + qmid, qsqrt – Quaternion arithmetic
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <draw.h> +
+ + #include <geometry.h> +
+ + Quaternion qadd(Quaternion q, Quaternion r) +
+ + Quaternion qsub(Quaternion q, Quaternion r) +
+ + Quaternion qneg(Quaternion q) +
+ + Quaternion qmul(Quaternion q, Quaternion r) +
+ + Quaternion qdiv(Quaternion q, Quaternion r) +
+ + Quaternion qinv(Quaternion q) +
+ + double qlen(Quaternion p) +
+ + Quaternion qunit(Quaternion q) +
+ + void qtom(Matrix m, Quaternion q) +
+ + Quaternion mtoq(Matrix mat) +
+ + Quaternion slerp(Quaternion q, Quaternion r, double a) +
+ + Quaternion qmid(Quaternion q, Quaternion r) +
+ + Quaternion qsqrt(Quaternion q)
+ +
+

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 + r and an imaginary vector component v=(i,j,k). Quaternions add + componentwise and multiply according to + the rule (r,v)(s,w)=(rs-v.w, rw+vs+vxw), where . and x are the ordinary + vector dot and cross products. The multiplicative inverse of a + non-zero quaternion (r,v) is (r,-v)/(r2-v.v). +
+ + The following routines do arithmetic on quaternions, represented + as
+ +
+ + typedef struct Quaternion Quaternion;
+ struct Quaternion{
+ +
+ + double r, i, j, k;
+ +
+ };
+ +
+ Name    Description
+ qadd    Add two quaternions.
+ qsub    Subtract two quaternions.
+ qneg    Negate a quaternion.
+ qmul    Multiply two quaternions.
+ qdiv    Divide two quaternions.
+ qinv    Return the multiplicative inverse of a quaternion.
+ qlen    Return sqrt(q.r*q.r+q.i*q.i+q.j*q.j+q.k*q.k), the length of + a quaternion.
+ qunit   Return a unit quaternion (length=1) with components proportional + to q’s. +
+ + A rotation by angle θ about axis A (where A is a unit vector) + can be represented by the unit quaternion q=(cos θ/2, Asin θ/2). + The same rotation is represented by -q; a rotation by -θ about -A + is the same as a rotation by θ about A. The quaternion q transforms + points by (0,x’,y’,z’) = q-1(0,x,y,z)q. 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. +
+ + The following routines operate on rotations or orientations represented + as unit quaternions:
+ mtoq    Convert a rotation matrix (see matrix(3)) to a unit quaternion.
+ qtom    Convert a unit quaternion to a rotation matrix.
+ slerp   Spherical lerp. Interpolate between two orientations. The + rotation that carries q to r is q-1r, so slerp(q, r, t) is q(q-1r)t.
+ qmid    slerp(q, r, .5)
+ qsqrt   The square root of q. This is just a rotation about the same + axis by half the angle.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libgeometry/quaternion.c
+ +
+

SEE ALSO
+ +
+ + matrix(3), qball(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/quote.html b/man/man3/quote.html new file mode 100644 index 00000000..433c5bfc --- /dev/null +++ b/man/man3/quote.html @@ -0,0 +1,164 @@ + +quote(3) - Plan 9 from User Space + + + + +
+
+
QUOTE(3)QUOTE(3) +
+
+

NAME
+ +
+ + quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, + quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote, needsrcquote + – quoted character strings
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char *quotestrdup(char *s) +
+ + Rune *quoterunestrdup(Rune *s) +
+ + char *unquotestrdup(char *s) +
+ + Rune *unquoterunestrdup(Rune *s) +
+ + int quotestrfmt(Fmt*) +
+ + int quoterunestrfmt(Fmt*) +
+ + void quotefmtinstall(void) +
+ + int (*doquote)(int c) +
+ + int needsrcquote(int c) +
+ + +
+

DESCRIPTION
+ +
+ + These routines manipulate character strings, either adding or + removing quotes as necessary. In the quoted form, the strings + are in the style of rc(1), with single quotes surrounding the + string. Embedded single quotes are indicated by a doubled single + quote. For instance,
+ +
+ + Don't worry!
+ +
+ + +
+ when quoted becomes
+ +
+ + 'Don''t worry!'
+ +
+ + +
+ The empty string is represented by two quotes, ''. +
+ + The first four functions act as variants of strdup (see strcat(3)). + Each returns a freshly allocated copy of the string, created using + malloc(3). Quotestrdup returns a quoted copy of s, while unquotestrdup + returns a copy of s with the quotes evaluated. The rune versions + of these functions do the same for strings (see + runestrcat(3)). +
+ + The string returned by quotestrdup or quoterunestrdup has the + following properties:
+ 1.    If the original string s is empty, the returned string is ''.
+ 2.    If s contains no quotes, blanks, or control characters, the + returned string is identical to s.
+ 3.    If s needs quotes to be added, the first character of the returned + string will be a quote. For example, hello world becomes 'hello + world' not hello' 'world. +
+ + The function pointer doquote is 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 *doquote, blanks, control + characters, and quotes are always quoted. Needsrcquote is provided + as a doquote function that flags any character special to rc(1). + +
+ + Quotestrfmt and quoterunestrfmt are print(3) formatting routines + that produce quoted strings as output. They may be installed by + hand, but quotefmtinstall installs them under the standard format + characters q and Q. (They are not installed automatically.) If + the format string includes the alternate format character #, + for example %#q, the printed string will always be quoted; otherwise + quotes will only be provided if necessary to avoid ambiguity. + In <libc.h> there are #pragma statements so the compiler can type-check + uses of %q and %Q in print(3) format strings.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/quote.c
+ /usr/local/plan9/src/lib9/fmt/fmtquote.c
+ +
+

SEE ALSO
+ +
+ + rc(1), malloc(3), print(3), strcat(3)
+ +
+

BUGS
+ +
+ + Because it is provided by the format library, doquote is a preprocessor + macro defined as fmtdoquote; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rand.html b/man/man3/rand.html new file mode 100644 index 00000000..0601c6bf --- /dev/null +++ b/man/man3/rand.html @@ -0,0 +1,190 @@ + +rand(3) - Plan 9 from User Space + + + + +
+
+
RAND(3)RAND(3) +
+
+

NAME
+ +
+ + rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, + fastrand, nfastrand – random number generator
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int      rand(void) +
+ + long     lrand(void) +
+ + double frand(void) +
+ + int      nrand(int val) +
+ + long     lnrand(long val) +
+ + void     srand(long seed) +
+ + ulong    truerand(void) +
+ + ulong    ntruerand(ulong val)
+ #include <mp.h>
+ #include <libsec.h> +
+ + void     genrandom(uchar *buf, int nbytes) +
+ + void     prng(uchar *buf, int nbytes) +
+ + ulong    fastrand(void) +
+ + ulong    nfastrand(ulong val)
+ +
+

DESCRIPTION
+ +
+ + Rand returns a uniform pseudo-random number x, 0≤x<215. +
+ + Lrand returns a uniform long x, 0≤x<231. +
+ + Frand returns a uniform double x, 0.0≤x<1.0, This function calls + lrand twice to generate a number with as many as 62 significant + bits of mantissa. +
+ + Nrand returns a uniform integer x, 0≤x<val. Lnrand is the same, + but returns a long. +
+ + The algorithm is additive feedback with:
+ +
+ + x[n] = (x[n-273] + x[n-607]) mod 231 +
+ + +
+ giving a period of 230 × (2607 – 1). +
+ + The generators are initialized by calling srand with whatever + you like as argument. To get a different starting value each time,
+ +
+ + srand(time(0)) +
+ + +
+ will work as long as it is not called more often than once per + second. Calling
+ +
+ + srand(1) +
+ + +
+ will initialize the generators to their starting state. +
+ + Truerand returns a random unsigned long read from /dev/random. + Due to the nature of /dev/random, truerand can only return a few + hundred bits a second. +
+ + Ntruerand returns a uniform random integer x, 0≤x<val≤232-1. +
+ + 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 /dev/random. +
+ + Prng uses the native rand(3) pseudo-random number generator to + fill the buffer. Used with srand, this function can produce a + reproducible stream of pseudo random numbers useful in testing. + +
+ + Both genrandom and prng may be passed to mprand (see mp(3)). +
+ + Fastrand uses genrandom to return a uniform unsigned long x, 0≤x<232-1. + +
+ + Nfastrand uses genrandom to return a uniform unsigned long x, + 0≤x<val≤232-1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ /usr/local/plan9/src/libsec/port
+ +
+

SEE ALSO
+ +
+ + mp(3)
+ +
+

BUGS
+ +
+ + Truerand and ntruerand maintain a static file descriptor. +
+ + To avoid name conflicts with the underlying system, rand, lrand, + frand, nrand, lnrand, and srand are preprocessor macros defined + as p9rand, p9lrand, and so on; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rc4.html b/man/man3/rc4.html new file mode 100644 index 00000000..8c0d374b --- /dev/null +++ b/man/man3/rc4.html @@ -0,0 +1,86 @@ + +rc4(3) - Plan 9 from User Space + + + + +
+
+
RC4(3)RC4(3) +
+
+

NAME
+ +
+ + setupRC4state, rc4, rc4skip, rc4back - alleged rc4 encryption
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + void setupRC4state(RC4state *s, uchar *seed, int slen) +
+ + void rc4(RC4state *s, uchar *data, int dlen) +
+ + void rc4skip(RC4state *s, int nbytes) +
+ + void rc4back(RC4state *s, int nbytes)
+ +
+

DESCRIPTION
+ +
+ + +
+ + 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 + setupRC4state, can be any length. The generator can + be run forward using rc4, skip over bytes using rc4skip to account + lost transmissions, or run backwards using rc4back to cover retransmitted + data. The RC4state structure keeps track of the algorithm.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), des(3), dsa(3), elgamal(3), rsa(3), + sechash(3), prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/read.html b/man/man3/read.html new file mode 100644 index 00000000..515c3f77 --- /dev/null +++ b/man/man3/read.html @@ -0,0 +1,109 @@ + +read(3) - Plan 9 from User Space + + + + +
+
+
READ(3)READ(3) +
+
+

NAME
+ +
+ + read, readn, write, pread, pwrite – read or write file
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + long read(int fd, void *buf, long nbytes) +
+ + long readn(int fd, void *buf, long nbytes) +
+ + long write(int fd, void *buf, long nbytes) +
+ + long pread(int fd, void *buf, long nbytes, vlong offset) +
+ + long pwrite(int fd, void *buf, long nbytes, vlong offset)
+ +
+

DESCRIPTION
+ +
+ + Read reads nbytes bytes of data from the offset in the file associated + with fd into memory at buf. The offset is advanced by the number + of bytes read. It is not guaranteed that all 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. +
+ + Readn is just like read, but does successive read calls until + nbytes have been read, or a read system call returns a non-positive + count. +
+ + Write writes nbytes bytes of data starting at buf to the file + associated with 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. +
+ + Pread and Pwrite equivalent to a seek(3) to offset followed by + a read or write. By combining the operations in a single atomic + call, they more closely match the 9P protocol (see intro(9p)) + and, more important, permit multiprocess programs to execute multiple + concurrent read and write operations on the same file + descriptor without interference.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/readn.c
+ +
+

SEE ALSO
+ +
+ + intro(3), open(3), dup(3), pipe(3)
+ +
+

DIAGNOSTICS
+ +
+ + These functions set errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/regexp.html b/man/man3/regexp.html new file mode 100644 index 00000000..21e1849b --- /dev/null +++ b/man/man3/regexp.html @@ -0,0 +1,178 @@ + +regexp(3) - Plan 9 from User Space + + + + +
+
+
REGEXP(3)REGEXP(3) +
+
+

NAME
+ +
+ + regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, + regerror – regular expression
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <regexp.h> +
+ + Reprog    *regcomp(char *exp) +
+ + Reprog    *regcomplit(char *exp) +
+ + Reprog    *regcompnl(char *exp) +
+ + int    regexec(Reprog *prog, char *string, Resub *match, int msize)
+ +
+ + void regsub(char *source, char *dest, int dlen, Resub *match, + int msize)
+ +
+ + int    rregexec(Reprog *prog, Rune *string, Resub *match, int msize)
+ +
+ + void rregsub(Rune *source, Rune *dest, int dlen, Resub *match, + int msize)
+ +
+ + void regerror(char *msg)
+ +
+

DESCRIPTION
+ +
+ + Regcomp compiles a regular expression and returns a pointer to + the generated description. The space is allocated by malloc(3) + and may be released by free. Regular expressions are exactly as + in regexp(7). +
+ + Regcomplit is like regcomp except that all characters are treated + literally. Regcompnl is like regcomp except that the . metacharacter + matches all characters, including newlines. +
+ + Regexec matches a null-terminated string against the compiled + regular expression in prog. If it matches, regexec returns 1 and + fills in the array match with character pointers to the substrings + of string that correspond to the parenthesized subexpressions + of exp: match[i].sp points to the beginning and + match[i].ep points just beyond the end of the ith substring. (Subexpression + i begins at the ith left parenthesis, counting from 1.) Pointers + in match[0] pick out the substring that corresponds to the whole + regular expression. Unused elements of match are filled with zeros. + Matches involving *, +, and ? are + extended as far as possible. The number of array elements in match + is given by msize. The structure of elements of match is:
+ +
+ + typedef struct {
+ +
+ + union {
+ char *sp;
+ Rune *rsp;
+ } s;
+ union {
+ char *ep;
+ Rune *rep;
+ } e;
+ +
+ } Resub;
+ +
+ + +
+ If match[0].s.sp is nonzero on entry, regexec starts matching + at that point within string. If match[0].e.ep is nonzero on entry, + the last character matched is the one preceding that point. +
+ + Regsub places in dest a substitution instance of source in the + context of the last regexec performed using match. Each instance + of \n, where n is a digit, is replaced by the string delimited + by match[n].sp and match[n].ep. Each instance of & is replaced + by the string delimited by match[0].sp and + match[0].ep. The substitution will always be null terminated and + trimmed to fit into dlen bytes. +
+ + Regerror, called whenever an error is detected in regcomp, writes + the string msg on the standard error file and exits. Regerror + can be replaced to perform special error processing. If the user + supplied regerror returns rather than exits, regcomp will return + 0. +
+ + Rregexec and rregsub are variants of regexec and regsub that use + strings of Runes instead of strings of chars. With these routines, + the rsp and rep fields of the match array elements should be used.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libregexp
+ +
+

SEE ALSO
+ +
+ + grep(1)
+ +
+

DIAGNOSTICS
+ +
+ + Regcomp returns 0 for an illegal expression or other failure. + Regexec returns 0 if string is not matched.
+ +
+

BUGS
+ +
+ + There is no way to specify or match a NUL character; NULs terminate + patterns and strings.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rfork.html b/man/man3/rfork.html new file mode 100644 index 00000000..f76a61fd --- /dev/null +++ b/man/man3/rfork.html @@ -0,0 +1,118 @@ + +rfork(3) - Plan 9 from User Space + + + + +
+
+
RFORK(3)RFORK(3) +
+
+

NAME
+ +
+ + rfork – manipulate process state
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int rfork(int flags)
+ +
+

DESCRIPTION
+ +
+ + Rfork is a partial implementation of the Plan 9 system call. It + can be used to manipulate some process state and to create new + processes a la fork(2). It cannot be used to create shared-memory + processes (Plan 9’s RFMEM flag); for that functionality use proccreate + (see thread(3)). +
+ + The flags argument to rfork selects which resources of the invoking + process (parent) are shared by the new process (child) or initialized + to their default values. Flags is the logical OR of some subset + of
+ RFPROC     If set a new process is created; otherwise changes affect + the current process.
+ RFNOWAIT   If set, the child process will be dissociated from the + parent. Upon exit the child will leave no Waitmsg (see wait(3)) + for the parent to collect.
+ RFNOTEG    Each process is a member of a group of processes that all + receive notes when a note is sent to the group (see postnote(3) + and signal(2)). The group of a new process is by default the same + as its parent, but if RFNOTEG is set (regardless of RFPROC), the + process becomes the first in a new group, isolated + +
+ + +
+ + from previous processes. In Plan 9, a process can call rfork(RFNOTEG) + and then be sure that it will no longer receive console interrupts + or other notes. Unix job-control shells put each command in its + own process group and then relay notes to the current foreground + command, making the idiom + less useful.
+ +
+ +
+ RFFDG      If set, the invoker’s file descriptor table (see intro()) + is copied; otherwise the two processes share a single table. +
+ + File descriptors in a shared file descriptor table are kept open + until either they are explicitly closed or all processes sharing + the table exit. +
+ + If 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 RFPROC, the return value is zero. Process + ids range from 1 to the maximum integer (int) value. Rfork will + sleep, if necessary, until required process resources are available. + +
+ + Calling rfork(RFFDG|RFPROC) is equivalent to calling fork(2).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/rfork.c
+ +
+

DIAGNOSTICS
+ +
+ + Rfork sets errstr.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rsa.html b/man/man3/rsa.html new file mode 100644 index 00000000..0cfd2949 --- /dev/null +++ b/man/man3/rsa.html @@ -0,0 +1,262 @@ + +rsa(3) - Plan 9 from User Space + + + + +
+
+
RSA(3)RSA(3) +
+
+

NAME
+ +
+ + asn1dump, asn1toRSApriv, decodepem, decodepemchain, rsadecrypt, + rsaencrypt, rsafill,, rsagen, rsaprivalloc, rsaprivfree, rsaprivtopub, + rsapuballoc, rsapubfree, X509toRSApub, X509dump, X509gen, X509req, + X509verify – RSA encryption algorithm
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + RSApriv*    rsagen(int nlen, int elen, int nrep) +
+ + RSApriv*    rsafill(mpint *n, mpint *ek, mpint *dk, mpint *p, mpint + *q) +
+ + mpint*      rsaencrypt(RSApub *k, mpint *in, mpint *out) +
+ + mpint*      rsadecrypt(RSApriv *k, mpint *in, mpint *out) +
+ + RSApub*     rsapuballoc(void) +
+ + void        rsapubfree(RSApub*) +
+ + RSApriv*    rsaprivalloc(void) +
+ + void        rsaprivfree(RSApriv*) +
+ + RSApub*     rsaprivtopub(RSApriv*) +
+ + RSApub*     X509toRSApub(uchar *cert, int ncert, char *name, int nname) + +
+ + RSApriv*    asn1toRSApriv(uchar *priv, int npriv) +
+ + void        asn1dump(uchar *der, int len) +
+ + uchar*      decodepem(char *s, char *type, int *len) +
+ + PEMChain* decodepemchain(char *s, char *type) +
+ + void        X509dump(uchar *cert, int ncert) +
+ + uchar*      X509gen(RSApriv *priv, char *subj, ulong valid[2], int + *certlen); +
+ + uchar*      X509req(RSApriv *priv, char *subj, int *certlen); +
+ + char* X509verify(uchar *cert, int ncert, RSApub *pk)
+ +
+

DESCRIPTION
+ +
+ + +
+ + RSA is a public key encryption algorithm. The owner of a key publishes + the public part of the key:
+ +
+ + +
+ + struct RSApub
+ {
+ mpint*n;// modulus
+ mpint*ek;// exp (encryption key)
+ };
+ +
+ +
+ This part can be used for encrypting data (with rsaencrypt) to + be sent to the owner. The owner decrypts (with rsadecrypt) using + his private key:
+ +
+ + +
+ + struct RSApriv
+ {
+ RSApubpub;
+ 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
+ };
+ +
+ + +
+ +
+ Keys are generated using rsagen. 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. + Rsagen returns a newly allocated structure containing both public + and + private keys. Rsaprivtopub returns a newly allocated copy of the + public key corresponding to the private key. +
+ + Rsafill takes as input the bare minimum pieces of an RSA private + key and computes the rest (kp, kq, and c2). It returns a new private + key. All the mpints in the key, even the ones that correspond + directly to rsafill’s input parameters, are freshly allocated, + +
+ + The routines rsaalloc, rsafree, rsapuballoc, rsapubfree, rsaprivalloc, + and rsaprivfree are provided to aid in user provided key I/O. + +
+ + Given a binary X.509 cert, the routine X509toRSApub returns the + public key and, if 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, + sha1(cert), against a table or check the certificate by other + means. X.509 certificates are often stored in PEM format; use + dec64 to convert to binary before computing the fingerprint or + calling X509toRSApub. For the special case of certificates signed + by a known trusted key (in a single step, without certificate + chains) + X509verify checks the signature on cert. It returns nil if successful, + else an error string. +
+ + X509dump prints an X.509 certificate to standard ouptut. +
+ + X509gen creates a self-signed X.509 certificate, given an RSA + keypair priv, a issuer/subject string subj, and the starting and + ending validity dates, valid. Length of the allocated binary certificate + is stored in certlen. The subject line is conventionally of the + form
+ +
+ + "C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric"
+ +
+ using the quoting conventions of tokenize (see getfields(3)). + +
+ + X509req creates an X.509 certification request. +
+ + Asn1toRSApriv converts an ASN1 formatted RSA private key into + the corresponding RSApriv structure. +
+ + Asn1dump prints an ASN1 object to standard output. +
+ + Decodepem takes a zero terminated string, s, and decodes the PEM + (privacy-enhanced mail) formatted section for type within it. + If successful, it returns the decoded section and sets *len to + its decoded length. If not, it returns nil, and *len is undefined. + +
+ + Decodepemchain is similar but expects a sequence of PEM-formatted + sections and returns a linked list of the decodings:
+ +
+ + typedef struct PEMChain PEMChain
+ struct PEMChain
+ {
+ +
+ + PEMChain *next;
+ uchar *pem;
+ int pemlen;
+ +
+ };
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + mp(3), aes(3), blowfish(3), des(3), dsa(3), elgamal(3), rc4(3), + sechash(3), prime(3), rand(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/rune.html b/man/man3/rune.html new file mode 100644 index 00000000..2fed11f3 --- /dev/null +++ b/man/man3/rune.html @@ -0,0 +1,157 @@ + +rune(3) - Plan 9 from User Space + + + + +
+
+
RUNE(3)RUNE(3) +
+
+

NAME
+ +
+ + runetochar, chartorune, runelen, runenlen, fullrune, utfecpy, + utflen, utfnlen, utfrune, utfrrune, utfutf – rune/UTF conversion
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int      runetochar(char *s, Rune *r) +
+ + int      chartorune(Rune *r, char *s) +
+ + int      runelen(long r) +
+ + int      runenlen(Rune *r, int n) +
+ + int      fullrune(char *s, int n) +
+ + char*    utfecpy(char *s1, char *es1, char *s2) +
+ + int      utflen(char *s) +
+ + int      utfnlen(char *s, long n) +
+ + char*    utfrune(char *s, long c) +
+ + char*    utfrrune(char *s, long c) +
+ + char*    utfutf(char *s1, char *s2)
+ +
+

DESCRIPTION
+ +
+ + These routines convert to and from a UTF byte stream and runes. + +
+ + Runetochar copies one rune at r to at most UTFmax bytes starting + at s and returns the number of bytes copied. UTFmax, defined as + 3 in <libc.h>, is the maximum number of bytes required to represent + a rune. +
+ + Chartorune copies at most UTFmax bytes starting at s to one rune + at r and returns the number of bytes copied. If the input is not + exactly in UTF format, chartorune will convert to 0x80 and return + 1. +
+ + Runelen returns the number of bytes required to convert r into + UTF. +
+ + Runenlen returns the number of bytes required to convert the n + runes pointed to by r into UTF. +
+ + Fullrune returns 1 if the string s of length n is long enough + to be decoded by chartorune and 0 otherwise. This does not guarantee + that the string contains a legal 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. +
+ + The following routines are analogous to the corresponding string + routines with utf substituted for str and rune substituted for + chr. +
+ + Utfecpy copies UTF sequences until a null sequence has been copied, + but writes no sequences beyond es1. If any sequences are copied, + s1 is terminated by a null sequence, and a pointer to that sequence + is returned. Otherwise, the original s1 is returned. +
+ + Utflen returns the number of runes that are represented by the + UTF string s. +
+ + Utfnlen returns the number of complete runes that are represented + by the first n bytes of UTF string s. If the last few bytes of + the string contain an incompletely coded rune, utfnlen will not + count them; in this way, it differs from utflen, which includes + every byte of the string. +
+ + Utfrune (utfrrune) returns a pointer to the first (last) occurrence + of rune c in the UTF string s, or 0 if c does not occur in the + string. The NUL byte terminating a string is considered to be + part of the string s. +
+ + Utfutf returns a pointer to the first occurrence of the UTF string + s2 as a UTF substring of s1, or 0 if there is none. If s2 is the + null string, utfutf returns s1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/utf/rune.c
+ /usr/local/plan9/src/lib9/utf/utfrune.c
+ +
+

SEE ALSO
+ +
+ + utf(7), tcs(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/runestrcat.html b/man/man3/runestrcat.html new file mode 100644 index 00000000..4774265c --- /dev/null +++ b/man/man3/runestrcat.html @@ -0,0 +1,107 @@ + +runestrcat(3) - Plan 9 from User Space + + + + +
+
+
RUNESTRCAT(3)RUNESTRCAT(3) +
+
+

NAME
+ +
+ + runestrcat, runestrncat, runestrcmp, runestrncmp, runestrcpy, + runestrncpy, runestrecpy, runestrlen, runestrchr, runestrrchr, + runestrdup, runestrstr – rune string operations
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + Rune* runestrcat(Rune *s1, Rune *s2) +
+ + Rune* runestrncat(Rune *s1, Rune *s2, long n) +
+ + int     runestrcmp(Rune *s1, Rune *s2) +
+ + int     runestrncmp(Rune *s1, Rune *s2, long n) +
+ + Rune* runestrcpy(Rune *s1, Rune *s2) +
+ + Rune* runestrncpy(Rune *s1, Rune *s2, long n) +
+ + Rune* runestrecpy(Rune *s1, Rune *es1, Rune *s2) +
+ + long    runestrlen(Rune *s) +
+ + Rune* runestrchr(Rune *s, Rune c) +
+ + Rune* runestrrchr(Rune *s, Rune c) +
+ + Rune* runestrdup(Rune *s) +
+ + Rune* runestrstr(Rune *s1, Rune *s2)
+ +
+

DESCRIPTION
+ +
+ + These functions are rune string analogues of the corresponding + functions in strcat(3).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + memory(3), rune(3), strcat(3)
+ +
+

BUGS
+ +
+ + The outcome of overlapping moves varies among implementations.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/sechash.html b/man/man3/sechash.html new file mode 100644 index 00000000..2e055465 --- /dev/null +++ b/man/man3/sechash.html @@ -0,0 +1,195 @@ + +sechash(3) - Plan 9 from User Space + + + + +
+
+
SECHASH(3)SECHASH(3) +
+
+

NAME
+ +
+ + md4, md5, sha1, hmac_md5, hmac_sha1, md5pickle, md5unpickle, sha1pickle, + sha1unpickle – cryptographically secure hashes
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <mp.h>
+ #include <libsec.h> +
+ + DigestState*     md4(uchar *data, ulong dlen, uchar *digest,                    DigestState + *state) +
+ + DigestState*     md5(uchar *data, ulong dlen, uchar *digest,                    DigestState + *state) +
+ + char*           md5pickle(MD5state *state) +
+ + MD5state*        md5unpickle(char *p); +
+ + DigestState*     sha1(uchar *data, ulong dlen, uchar *digest,                    DigestState + *state) +
+ + char*           sha1pickle(MD5state *state) +
+ + MD5state*        sha1unpickle(char *p); +
+ + DigestState*     hmac_md5(uchar *data, ulong dlen,
+ +
+ + +
+ + uchar *key, ulong klen,
+ uchar *digest, DigestState *state) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ DigestState*     hmac_sha1(uchar *data, ulong dlen,
+ +
+ + +
+ + uchar *key, ulong klen,
+ uchar *digest, DigestState *state)
+ +
+ +
+ +
+

DESCRIPTION
+ +
+ + +
+ + These functions implement the cryptographic hash functions MD4, + MD5, and SHA1. The output of the hash is called a 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. + +
+ + The routines md4, md5, sha1, hmac_md5, and hmac_sha1 differ only + in the length of the resulting digest and in the security of the + hash. Usage for each is the same. The first call to the routine + should have nil as the state parameter. This call returns a state + which can be used to chain subsequent calls. The last call + should have digest non-nil. 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 digest. For example, to hash + a single buffer using md5:
+ +
+ + uchar digest[MD5dlen];
+ md5(data, len, digest, nil);
+ +
+ + +
+ To chain a number of buffers together, bounded on each end by + some secret:
+ +
+ + 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);
+ +
+ + +
+ The constants MD4dlen, MD5dlen, and SHA1dlen define the lengths + of the digests. +
+ + Hmac_md5 and hmac_sha1 are used slightly differently. These hash + algorithms are keyed and require a key to be specified on every + call. The digest lengths for these hashes are MD5dlen and SHA1dlen + respectively. +
+ + The functions md5pickle and sha1pickle marshal the state of a + digest for transmission. Md5unpickle and sha1unpickle unmarshal + a pickled digest. All four routines return a pointer to a newly + malloc(3)’d object.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libsec
+ +
+

SEE ALSO
+ +
+ + aes(3), blowfish(3), des(3), elgamal(3), rc4(3), rsa(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/seek.html b/man/man3/seek.html new file mode 100644 index 00000000..a2c19651 --- /dev/null +++ b/man/man3/seek.html @@ -0,0 +1,96 @@ + +seek(3) - Plan 9 from User Space + + + + +
+
+
SEEK(3)SEEK(3) +
+
+

NAME
+ +
+ + seek – change file offset
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + vlong seek(int fd, vlong n, int type)
+ +
+

DESCRIPTION
+ +
+ + Seek sets the offset for the file associated with fd as follows:
+ +
+ + If type is 0, the offset is set to n bytes.
+ If type is 1, the pointer is set to its current location plus + n.
+ If type is 2, the pointer is set to the size of the file plus + n. +
+ + +
+ The new file offset value is returned. +
+ + Seeking in a directory is not allowed. Seeking in a pipe is a + no-op.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/seek.c
+ +
+

SEE ALSO
+ +
+ + intro(3), open(3)
+ +
+

DIAGNOSTICS
+ +
+ + Sets errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, seek is a + preprocessor macro defined as p9seek; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/sendfd.html b/man/man3/sendfd.html new file mode 100644 index 00000000..37007603 --- /dev/null +++ b/man/man3/sendfd.html @@ -0,0 +1,85 @@ + +sendfd(3) - Plan 9 from User Space + + + + +
+
+
SENDFD(3)SENDFD(3) +
+
+

NAME
+ +
+ + sendfd, recvfd – pass file descriptors along Unix domain sockets
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + int    sendfd(int socket, int fd) +
+ + int    recvfd(int socket)
+ +
+

DESCRIPTION
+ +
+ + Recvfd and sendfd can be used to pass an open file descriptor + over a Unix domain socket from one process to another. Since pipe(3) + is implemented with socketpair(2) instead of pipe(2), socket can + be a file descriptor obtained from pipe(3). +
+ + Sendfd sends the file descriptor fd along the socket to a process + calling recvfd on the other end. +
+ + It is assumed that the two sides have coordinated and agreed to + transfer a file descriptor already, so that the sendfd is met + with a recvfd instead of an ordinary read. +
+ + The file descriptor number may change on its way between processes, + but the kernel structure it represents will not.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/sendfd.c
+ +
+

SEE ALSO
+ +
+ + socketpair(2), sendmsg in send(2)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/setjmp.html b/man/man3/setjmp.html new file mode 100644 index 00000000..b22431fd --- /dev/null +++ b/man/man3/setjmp.html @@ -0,0 +1,110 @@ + +setjmp(3) - Plan 9 from User Space + + + + +
+
+
SETJMP(3)SETJMP(3) +
+
+

NAME
+ +
+ + setjmp, longjmp, notejmp – non-local goto
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int    setjmp(jmp_buf env) +
+ + void longjmp(jmp_buf env, int val) +
+ + void notejmp(void *uregs, jmp_buf env, int val)
+ +
+

DESCRIPTION
+ +
+ + These routines are useful for dealing with errors and interrupts + encountered in a low-level subroutine of a program. +
+ + Setjmp saves its stack environment in env for later use by longjmp. + It returns value 0. +
+ + Longjmp restores the environment saved by the last call of setjmp. + It then causes execution to continue as if the call of setjmp + had just returned with value val. The invoker of setjmp must not + itself have returned in the interim. All accessible data have + values as of the time longjmp was called. +
+ + Notejmp is the same as longjmp except that it is to be called + from within a note handler (see notify(3)). The uregs argument + should be the first argument passed to the note handler. +
+ + Setjmp and longjmp can also be used to switch stacks.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/jmp.c
+ +
+

SEE ALSO
+ +
+ + notify(3)
+ +
+

BUGS
+ +
+ + +
+ + Notejmp cannot recover from an address trap or bus error (page + fault) on the 680x0 architectures. +
+ + To avoid name conflicts with the underlying system, setjmp, longjmp, + notejmp, and jmp_buf are preprocessor macros defined as p9setjmp, + p9longjmp, p9notejmp, and p9jmp_buf; see intro(3). +
+ + P9setjmp is implemented as a preprocessor macro that calls sigsetjmp + (see Unix’s setjmp(3)).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/sleep.html b/man/man3/sleep.html new file mode 100644 index 00000000..6614f33a --- /dev/null +++ b/man/man3/sleep.html @@ -0,0 +1,95 @@ + +sleep(3) - Plan 9 from User Space + + + + +
+
+
SLEEP(3)SLEEP(3) +
+
+

NAME
+ +
+ + sleep, alarm – delay, ask for delayed note
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int sleep(long millisecs) +
+ + long alarm(unsigned long millisecs)
+ +
+

DESCRIPTION
+ +
+ + 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 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. +
+ + Alarm causes an alarm note (see notify(3)) to be sent to the invoking + process after the number of milliseconds given by the argument. + Successive calls to 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. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/sleep.c
+ +
+

SEE ALSO
+ +
+ + intro(3)
+ +
+

DIAGNOSTICS
+ +
+ + These functions set errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, sleep and + alarm are preprocessor macros defined as p9sleep and p9alarm; + see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/stat.html b/man/man3/stat.html new file mode 100644 index 00000000..fb79a647 --- /dev/null +++ b/man/man3/stat.html @@ -0,0 +1,244 @@ + +stat(3) - Plan 9 from User Space + + + + +
+
+
STAT(3)STAT(3) +
+
+

NAME
+ +
+ + stat, fstat, wstat, fwstat, dirstat, dirfstat, dirwstat, dirfwstat, + nulldir – get and put file status
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + int stat(char *name, uchar *edir, int nedir) +
+ + int fstat(int fd, uchar *edir, int nedir) +
+ + int wstat(char *name, uchar *edir, int nedir) +
+ + int fwstat(int fd, uchar *edir, int nedir) +
+ + Dir* dirstat(char *name) +
+ + Dir* dirfstat(int fd) +
+ + int dirwstat(char *name, Dir *dir) +
+ + int dirfwstat(int fd, Dir *dir) +
+ + void nulldir(Dir *d)
+ +
+

DESCRIPTION
+ +
+ + Given a file’s name, or an open file descriptor fd, these routines + retrieve or modify file status information. Stat, fstat, wstat, + and fwstat are the system calls; they deal with machine-independent + directory entries. Their format is defined by stat(9p). Stat and + fstat retrieve information about name or fd into edir, a buffer + of length nedir, defined in <libc.h>. Wstat and fwstat write information + back, thus changing file attributes according to the contents + of edir. The data returned from the kernel includes its leading + 16-bit length field as described in intro(9p). For symmetry, this + field must also be present when passing data to the + kernel in a call to wstat and fwstat, but its value is ignored. + +
+ + Dirstat, dirfstat, dirwstat, and dirfwstat are similar to their + counterparts, except that they operate on Dir structures:
+ +
+ + 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 <u.h> */
+ char    *name;     /* last element of path */
+ char    *uid;      /* owner name */
+ char    *gid;      /* group name */
+ char    *muid;     /* last modifier name */
+ +
+ } Dir;
+ +
+ + +
+ The returned structure is allocated by malloc(3); freeing it also + frees the associated strings. +
+ + This structure and the Qid structure are defined in <libc.h>. If + the file resides on permanent storage and is not a directory, + the length returned by 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. +
+ + Each file is the responsibility of some server: it could be a + file server, a kernel device, or a user process. Type identifies + the server type, and dev says which of a group of servers of the + same type is the one responsible for this file. Qid is a structure + containing path and vers fields: path is guaranteed to be + unique among all path names currently on the file server, and + vers changes each time the file is modified. The path is a long + long (64 bits, vlong) and the vers is an unsigned long (32 bits, + ulong). Thus, if two files have the same type, dev, and qid they + are the same file. +
+ + The bits in mode are defined by +
+ + +
+ + 0x80000000     directory
+ 0x40000000     append only
+ 0x20000000     exclusive use (locked)
+ +
+ + 0400     read permission by owner
+ 0200     write permission by owner
+ 0100     execute permission (search on directory) by owner
+ 0070     read, write, execute (search) by group
+ 0007     read, write, execute (search) by others
+ +
+ + +
+ +
+ There are constants defined in <libc.h> for these bits: DMDIR, DMAPPEND, + and DMEXCL for the first three; and DMREAD, DMWRITE, and DMEXEC + for the read, write, and execute bits for others. +
+ + The two time fields are measured in seconds since the epoch (Jan + 1 00:00 1970 GMT). Mtime is the time of the last change of content. + Similarly, atime is set whenever the contents are accessed; also, + it is set whenever mtime is set. +
+ + Uid and gid are the names of the owner and group of the file; + muid is the name of the user that last modified the file (setting + mtime). Groups are also users, but each server is free to associate + a list of users with any user name g, and that list is the set + of users in the group 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 mode is + used to check permissions. +
+ + Only some of the fields may be changed with the wstat calls. The + name can be changed by anyone with write permission in the parent + directory. The mode and mtime can be changed by the owner or the + group leader of the file’s current group. The 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 intro(9p) for more information about + permissions, users, and groups). The length can be changed by + anyone with write permission, provided the operation is implemented + by the server. (See intro(9p) for permission, user, + and group information). +
+ + Special values in the fields of the Dir passed to 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 ~0, but beware of conversions and size + mismatches when comparing values) and the empty or nil string + for string values. The routine nulldir initializes all the elements + of d to these “don’t care” values. Thus one may change the mode, + for example, by using nulldir to initialize a Dir, then setting + the mode, and then doing wstat; it is not necessary to use stat + to retrieve the initial values first. + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/dirstat.c
+ +
+

SEE ALSO
+ +
+ + intro(3), fcall(3), dirread(3), stat(9p)
+ +
+

DIAGNOSTICS
+ +
+ + The dir functions return a pointer to the data for a successful + call, or nil on error. The others return the number of bytes copied + on success, or –1 on error. All set errstr. +
+ + If the buffer for stat or fstat is too short for the returned + data, the return value will be BIT16SZ (see fcall(3)) and the + two bytes returned will contain the initial count field of the + returned data; retrying with nedir equal to that value plus BIT16SZ + (for the count itself) should succeed.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/strcat.html b/man/man3/strcat.html new file mode 100644 index 00000000..542ebd25 --- /dev/null +++ b/man/man3/strcat.html @@ -0,0 +1,203 @@ + +strcat(3) - Plan 9 from User Space + + + + +
+
+
STRCAT(3)STRCAT(3) +
+
+

NAME
+ +
+ + strcat, strncat, strcmp, strncmp, cistrcmp, cistrncmp, strcpy, + strncpy, strecpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, + strtok, strdup, strstr, cistrstr – string operations
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + char* strcat(char *s1, char *s2) +
+ + char* strncat(char *s1, char *s2, long n) +
+ + int     strcmp(char *s1, char *s2) +
+ + int     strncmp(char *s1, char *s2, long n) +
+ + int     cistrcmp(char *s1, char *s2) +
+ + int     cistrncmp(char *s1, char *s2, long n) +
+ + char* strcpy(char *s1, char *s2) +
+ + char* strecpy(char *s1, char *es1, char *s2) +
+ + char* strncpy(char *s1, char *s2, long n) +
+ + long    strlen(char *s) +
+ + char* strchr(char *s, char c) +
+ + char* strrchr(char *s, char c) +
+ + char* strpbrk(char *s1, char *s2) +
+ + long    strspn(char *s1, char *s2) +
+ + long    strcspn(char *s1, char *s2) +
+ + char* strtok(char *s1, char *s2) +
+ + char* strdup(char *s) +
+ + char* strstr(char *s1, char *s2) +
+ + char* cistrstr(char *s1, char *s2)
+ +
+

DESCRIPTION
+ +
+ + The arguments s1, s2 and s point to null-terminated strings. The + functions strcat, strncat, strcpy, strecpy, and strncpy all alter + s1. Strcat and strcpy do not check for overflow of the array pointed + to by s1. +
+ + Strcat appends a copy of string s2 to the end of string s1. Strncat + appends at most n bytes. Each returns a pointer to the null-terminated + result. +
+ + Strcmp compares its arguments and returns an integer less than, + equal to, or greater than 0, according as s1 is lexicographically + less than, equal to, or greater than s2. Strncmp makes the same + comparison but examines at most n bytes. Cistrcmp and cistrncmp + ignore ASCII case distinctions when comparing strings. + The comparisons are made with unsigned bytes. +
+ + Strcpy copies string s2 to s1, stopping after the null byte has + been copied. Strncpy copies exactly n bytes, truncating s2 or + adding null bytes to s1 if necessary. The result will not be null-terminated + if the length of s2 is n or more. Each function returns s1. +
+ + Strecpy copies bytes until a null byte has been copied, but writes + no bytes beyond es1. If any bytes are copied, s1 is terminated + by a null byte, and a pointer to that byte is returned. Otherwise, + the original s1 is returned. +
+ + Strlen returns the number of bytes in s, not including the terminating + null byte. +
+ + Strchr (strrchr) returns a pointer to the first (last) occurrence + of byte c in string s, or 0 if c does not occur in the string. + The null byte terminating a string is considered to be part of + the string. +
+ + Strpbrk returns a pointer to the first occurrence in string s1 + of any byte from string s2, 0 if no byte from s2 exists in s1. + +
+ + Strspn (strcspn) returns the length of the initial segment of + string s1 which consists entirely of bytes from (not from) string + s2. +
+ + Strtok considers the string s1 to consist of a sequence of zero + or more text tokens separated by spans of one or more bytes from + the separator string s2. The first call, with pointer s1 specified, + returns a pointer to the first byte of the first token, and will + have written a null byte into s1 immediately following the returned + token. The function keeps track of its position in the string + between separate calls; subsequent calls, signified by s1 being + 0, will work through the string s1 immediately following that + token. The separator string s2 may be different from call to call. + When no token remains in s1, 0 is returned. +
+ + Strdup returns a pointer to a distinct copy of the null-terminated + string s in space obtained from malloc(3) or 0 if no space can + be obtained. +
+ + Strstr returns a pointer to the first occurrence of s2 as a substring + of s1, or 0 if there is none. If s2 is the null string, strstr + returns s1. Cistrstr operates analogously, but ignores ASCII case + differences when comparing strings.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + memory(3), rune(3), runestrcat(3)
+ +
+

BUGS
+ +
+ + These routines know nothing about UTF. Use the routines in rune(3) + as appropriate. Note, however, that the definition of UTF guarantees + that strcmp compares UTF strings correctly. +
+ + The outcome of overlapping moves varies among implementations.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/string.html b/man/man3/string.html new file mode 100644 index 00000000..55a1673b --- /dev/null +++ b/man/man3/string.html @@ -0,0 +1,244 @@ + +string(3) - Plan 9 from User Space + + + + +
+
+
STRING(3)STRING(3) +
+
+

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, s_allocinstack, s_freeinstack, s_rdinstack – extensible + strings
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <String.h> +
+ + String*     s_new(void)
+ void        s_free(String *s)
+ String*     s_newalloc(int n)
+ String*     s_array(char *p, int n)
+ String*     s_grow(String *s, int n) +
+ + void        s_putc(String *s, int c)
+ void        s_terminate(String *s)
+ String*     s_reset(String *s)
+ String*     s_restart(String *s)
+ String*     s_append(String *s, char *p)
+ String*     s_nappend(String *s, char *p, int n)
+ String*     s_memappend(String *s, char *p, int n)
+ String*     s_copy(char *p)
+ String*     s_parse(String *s1, String *s2)
+ +
+ + void        s_tolower(String *s) +
+ + String*     s_incref(String *s)
+ String*     s_unique(String *s) +
+ + Sinstack* s_allocinstack(char *file)
+ void        s_freeinstack(Sinstack *stack)
+ char*       s_rdinstack(Sinstack *stack, String *s) +
+ + #include <bio.h> +
+ + int         s_read(Biobuf *b, String *s, int n)
+ char*       s_read_line(Biobuf *b, String *s)
+ char*       s_getline(Biobuf *b, String *s)
+ +
+

DESCRIPTION
+ +
+ + +
+ + These routines manipulate extensible strings. The basic type is + 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 + s_parse) or new characters will be added (for s_putc, + s_append, and s_nappend). The structure, and a few useful macros + are:
+ 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)
+ +
+ + S_to_c is used when code needs a reference to the character array. + Using s−>base directly is frowned upon since it exposes too much + of the implementation.
+

Allocation and freeing
+ +
+ + A string must be allocated before it can be used. One normally + does this using 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 s_newalloc instead, specifying the number + of bytes in the initial allocation. +
+ + S_free causes both the string and its character array to be freed. + +
+ + 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. +
+ + 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.
+

Filling the string
+ After its initial allocation, the string points to the beginning + of an allocated array of characters starting with NUL. +
+ + S_putc writes a character into the string at the pointer and advances + the pointer to point after it. +
+ + S_terminate writes a NUL at the pointer but doesn’t advance it. + +
+ + S_restart resets the pointer to the begining of the string but + doesn’t change the contents. +
+ + S_reset is equivalent to s_restart followed by s_terminate. +
+ + S_append and s_nappend copy characters into the string at the + pointer and advance the pointer. They also write a NUL at the + pointer without advancing the pointer beyond it. Both routines + stop copying on encountering a NUL. S_memappend is like s_nappend + but doesn’t stop at a NUL. +
+ + If you know the initial character array to be copied into a string, + you can allocate a string and copy in the bytes using s_copy. + This is the equivalent of a s_new followed by an s_append. +
+ + S_parse copies the next white space terminated token from s1 to + the end of 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. +
+ + S_tolower converts all ASCII characters in the string to lower + case.
+

Multithreading
+ +
+ + S_incref is used by multithreaded programs to avoid having the + string memory released until the last user of the string performs + an s_free. S_unique returns a unique copy of the string: if the + reference count it 1 it returns the string, otherwise it returns + an s_clone of the string.
+

Bio interaction
+ +
+ + S_read reads the requested number of characters through a 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. +
+ + 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. +
+ + S_getline reads up to the next newline, appends the input to s, + and returns a pointer to the beginning of the bytes read. Leading + spaces and tabs and the trailing newline are all discarded. S_getline + discards blank lines and lines beginning with #. S_getline ignores + newlines escaped by immediately-preceding + backslashes. +
+ + S_allocinstack allocates an input stack with the single file file + open for reading. S_freeinstack frees an input stack. S_rdinstack + reads a line from an input stack. It follows the same rules as + s_getline except that when it encounters a line of the form #include + newfile, s_getline pushes newfile onto the input stack, + postponing further reading of the current file until newfile has + been read. The input stack has a maximum depth of 32 nested include + files.
+ +

+

SOURCE
+ +
+ + /usr/local/plan9/src/libString
+ +
+

SEE ALSO
+ +
+ + bio(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/stringsize.html b/man/man3/stringsize.html new file mode 100644 index 00000000..1e8c4e91 --- /dev/null +++ b/man/man3/stringsize.html @@ -0,0 +1,116 @@ + +stringsize(3) - Plan 9 from User Space + + + + +
+
+
STRINGSIZE(3)STRINGSIZE(3) +
+
+

NAME
+ +
+ + stringsize, stringwidth, stringnwidth, runestringsize, runestringwidth, + runestringnwidth – graphical size of strings
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ +
+ + Point stringsize(Font *f, char *s)
+ +
+ + int     stringwidth(Font *f, char *s)
+ +
+ + int     stringnwidth(Font *f, char *s, int n)
+ +
+ + Point runestringsize(Font *f, Rune *s)
+ +
+ + int     runestringwidth(Font *f, Rune *s)
+ +
+ + int     runestringnwidth(Font *f, Rune *s, int n)
+ +
+

DESCRIPTION
+ +
+ + These routines compute the geometrical extent of character strings + when drawn on the display. The most straightforward, stringsize, + returns a Point representing the vector from upper left to lower + right of the NUL-terminated string s drawn in font f. Stringwidth + returns just the x component. + Stringnwidth returns the width of the first n characters of s. + +
+ + The routines beginning with rune are analogous, but accept an + array of runes rather than UTF-encoded bytes.
+ +
+

FILES
+ +
+ + /lib/font/bit    directory of fonts
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + addpt(3), cachechars(3), subfont(3), draw(3), draw(3), image(7), + font(7)
+ +
+

DIAGNOSTICS
+ +
+ + Because strings are loaded dynamically, these routines may generate + I/O to the server and produce calls to the graphics error function.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/subfont.html b/man/man3/subfont.html new file mode 100644 index 00000000..16dc216d --- /dev/null +++ b/man/man3/subfont.html @@ -0,0 +1,260 @@ + +subfont(3) - Plan 9 from User Space + + + + +
+
+
SUBFONT(3)SUBFONT(3) +
+
+

NAME
+ +
+ + allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, + subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, + strsubfontwidth, mkfont – subfont manipulation
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h> +
+ + Subfont* allocsubfont(char *name, int n, int height, int ascent,
+ +
+ + +
+ + Fontchar *info, Image *i) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ void       freesubfont(Subfont *f) +
+ + void       installsubfont(char *name, Subfont *f) +
+ + Subfont* lookupsubfont(Subfont *f) +
+ + void       uninstallsubfont(Subfont *f) +
+ + Subfont* readsubfont(Display *d, char *name, int fd, int dolock) + +
+ + Subfont* readsubfonti(Display *d, char *name, int fd, Image *im,
+ +
+ + +
+ + int dolock) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ int        writesubfont(int fd, Subfont *f) +
+ + Point      stringsubfont(Image *dst, Point p, Image *src,
+ +
+ + +
+ + Subfont *f, char *str) +
+ +
+ +
+ +
+ + +
+ + + +
+ +
+ Point      strsubfontwidth(Subfont *f, char *s) +
+ + Font*      mkfont(Subfont *f, Rune min)
+ +
+

DESCRIPTION
+ +
+ + Subfonts are the components of fonts that hold the character images. + A font comprises an array of subfonts; see cachechars(3). A new + Subfont is allocated and initialized with allocsubfont. See cachechars(3) + for the meaning of n, height, ascent, and info, and the arrangement + of characters in image i. The name is + used to identify the subfont in the subfont cache; see the descriptions + lookupsubfont and installsubfont (q.v.). The appropriate fields + of the returned Subfont structure are set to the passed arguments, + and the image is registered as a subfont with the graphics device + draw(3). Allocsubfont returns 0 on failure. +
+ + Freesubfont frees a subfont and all its associated structure including + the associated image. Since freesbufont calls free on f−>info, + if f−>info was not allocated by malloc(3) it should be zeroed before + calling subffree. +
+ + A number of subfonts are kept in external files. The convention + for naming subfont files is:
+ +
+ + /usr/local/plan9/font/name/class.size.depth +
+ + +
+ where 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 .depth extension is elided. Class + describes the range of runes encoded in the subfont: ascii, latin1, + greek, etc. +
+ + Subfonts are cached within the program, so a subfont shared between + fonts will be loaded only once. Installsubfont stores subfont + f under the given name, typically the file name from which it + was read. Uninstallsubfont removes the subfont from the cache. + Finally, lookupsubfont searches for a subfont with the given + name in the cache and returns it, or nil if no such subfont exists. + +
+ + Subfontname is used to locate subfonts given their names within + the fonts. The default version constructs a name given the cfname, + its name within the font, 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, subfontname + may be substituted by the application to provide a less file-oriented + subfont naming scheme. +
+ + The format of a subfont file is described in font(7). Briefly, + it contains a image with all the characters in it, followed by + a subfont header, followed by character information. Readsubfont + reads a subfont from the file descriptor fd. The name is used + to identify the font in the cache. The dolock argument specifies + whether + the routine should synchronize use of the Display with other processes; + for single-threaded applications it may always be zero. Readsubfonti + does the same for a subfont whose associated image is already + in memory; it is passed as the argument im. In other words, readsubfonti + reads only the header and character + information from the file descriptor. +
+ + Writesubfont writes on fd the part of a subfont file that comes + after the image. It should be preceded by a call to writeimage + (see allocimage(3)). +
+ + Stringsubfont is analogous to string (see draw(3)) for subfonts. + Rather than use the underlying font caching primitives, it calls + draw for each character. It is intended for stand-alone environments + such as operating system kernels. Strsubfontwidth returns the + width of the string s in as it would appear if drawn with + stringsubfont in Subfont f. +
+ + Mkfont takes as argument a Subfont s and returns a pointer to + a Font that maps the character images in s into the Runes min + to min+s−>n−1.
+ +
+

FILES
+ +
+ + /usr/local/plan9/font   bitmap font file tree
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), allocimage(3), draw(3), cachechars(3), image(7), + font(7)
+ +
+

DIAGNOSTICS
+ +
+ + All of the functions use the graphics error function (see graphics(3)).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/sysfatal.html b/man/man3/sysfatal.html new file mode 100644 index 00000000..15ceb0ca --- /dev/null +++ b/man/man3/sysfatal.html @@ -0,0 +1,71 @@ + +sysfatal(3) - Plan 9 from User Space + + + + +
+
+
SYSFATAL(3)SYSFATAL(3) +
+
+

NAME
+ +
+ + sysfatal – system error messages
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + void sysfatal(char *fmt, ...)
+ +
+

DESCRIPTION
+ +
+ + Sysfatal prints to standard error the name of the running program, + a colon and a space, the message described by the print(3) format + string fmt and subsequent arguments, and a newline. It then calls + exits(3) with the formatted message as argument. The program’s + name is the value of argv0, which will be set if the + program uses the arg(3) interface to process its arguments. If + argv0 is null, it is ignored and the following colon and space + are suppressed.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/sysfatal.c
+ +
+

SEE ALSO
+ +
+ + intro(3), errstr(3), the %r format in print(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/thread.html b/man/man3/thread.html new file mode 100644 index 00000000..b14d97e6 --- /dev/null +++ b/man/man3/thread.html @@ -0,0 +1,383 @@ + +thread(3) - Plan 9 from User Space + + + + +
+
+
THREAD(3)THREAD(3) +
+
+

NAME
+ +
+ + alt, chancreate, chanfree, chaninit, chanprint, chansetname, mainstacksize, + proccreate, procdata, recv, recvp, recvul, send, sendp, sendul, + nbrecv, nbrecvp, nbrecvul, nbsend, nbsendp, nbsendul, threadcreate, + threaddata, threadexec, threadexecl, threadexits, threadexitsall, + threadgetgrp, threadgetname, threadint, + threadintgrp, threadkill, threadkillgrp, threadmain, threadnotify, + threadid, threadpid, threadsetgrp, threadsetname, threadsetstate, + threadspawn, threadwaitchan, yield – thread and proc management
+ +
+

SYNOPSIS
+ +
+ + +
+ + #include <u.h>
+ #include <libc.h>
+ #include <thread.h>
+ #define    CHANEND      0
+ #define    CHANSND      1
+ #define    CHANRCV      2
+ #define    CHANNOP      3
+ #define    CHANNOBLK    4
+ typedef struct Alt Alt;
+ struct Alt {
+ +
+ + Channel *c;
+ void      *v;
+ int       op;
+ Channel **tag;
+ int       entryno;
+ char      *name;
+ +
+ };
+ +
+ + void       threadmain(int argc, char *argv[])
+ int        mainstacksize
+ int        proccreate(void (*fn)(void*), void *arg, uint stacksize)
+ int        threadcreate(void (*fn)(void*), void *arg, uint stacksize)
+ void       threadexits(char *status)
+ void       threadexitsall(char *status)
+ void       yield(void)
+ int        threadid(void)
+ int        threadgrp(void)
+ int        threadsetgrp(int group)
+ int        threadpid(int id)
+ int        threadint(int id)
+ int        threadintgrp(int group)
+ int        threadkill(int id)
+ int        threadkillgrp(int group)
+ void       threadsetname(char *name)
+ char*      threadgetname(void)
+ void**     threaddata(void)
+ void**     procdata(void)
+ int        chaninit(Channel *c, int elsize, int nel)
+ Channel* chancreate(int elsize, int nel)
+ void       chanfree(Channel *c)
+ 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        threadspawn(int fd[3], char *file, char *args[])
+ int        threadexecl(Channel *cpid, int fd[3], char *file, ...)
+ int        threadexec(Channel *cpid, int fd[3], char *file, char *args[])
+ Channel* threadwaitchan(void)
+ int        threadnotify(int (*f)(void*, char*), int in)
+ +
+

DESCRIPTION
+ +
+ + +
+ + The thread library provides parallel programming support similar + to that of the languages Alef and Newsqueak. Threads and procs + occupy a shared address space, communicating and synchronizing + through channels and shared variables. +
+ + A proc is a Plan 9 process that contains one or more cooperatively + scheduled threads. Programs using threads must replace main by + threadmain. The thread library provides a main function that sets + up a proc with a single thread executing threadmain on a stack + of size mainstacksize (default eight kilobytes). To set + mainstacksize, declare a global variable initialized to the desired + value (e.g., int mainstacksize = 1024). +
+ + Threadcreate creates a new thread in the calling proc, returning + a unique integer identifying the thread; the thread executes fn(arg) + on a stack of size stacksize. Thread stacks are allocated in shared + memory, making it valid to pass pointers to stack variables between + threads and procs. Proccreate creates a new proc, + and inside that proc creates a single thread as threadcreate would, + returning the id of the created thread. Be aware that the calling + thread may continue execution before the newly created proc and + thread are scheduled. Because of this, arg should not point to + data on the stack of a function that could return before the + new process is scheduled. +
+ + Threadexits terminates the calling thread. If the thread is the + last in its proc, threadexits also terminates the proc, using + status as the exit status. Threadexitsall terminates all procs + in the program, using status as the exit status. +
+ + When the last thread in threadmain’s proc exits, the program will + appear to its parent to have exited. The remaining procs will + still run together, but as a background program. +
+ + The threads in a proc are coroutines, scheduled nonpreemptively + in a round-robin fashion. A thread must explicitly relinquish + control of the processor before another thread in the same proc + is run. Calls that do this are yield, proccreate, threadexec, + threadexecl, threadexits, threadspawn, alt, send, and recv (and + the + calls related to send and recv--see their descriptions further on). + Procs are scheduled by the operating system. Therefore, threads + in different procs can preempt one another in arbitrary ways and + should synchronize their actions using qlocks (see lock(3)) or + channel communication. System calls such as read(3) + block the entire proc; all threads in a proc block until the system + call finishes. +
+ + 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. 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. Threadgrp returns the group id for the + current thread; threadsetgrp sets it. Threadpid returns the pid + of the Plan 9 process containing the thread identified by id, + or –1 if no such thread is found. +
+ + Threadint interrupts a thread that is blocked in a channel operation + or system call. Threadintgrp interrupts all threads with the given + group id. 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. Threadkillgrp kills all threads with the given + group id. Note that threadkill and threadkillgrp will not terminate + a thread that never relinquishes the processor. +
+ + Primarily for debugging, threads can have string names associated + with them. Threadgetname returns the current thread’s name; threadsetname + sets it. The pointer returned by threadgetname is only valid until + the next call to threadsetname. +
+ + Also for debugging, threads have a string state associated with + them. Threadsetstate sets the state string. There is no threadgetstate; + since the thread scheduler resets the state to Running every time + it runs the thread, it is only useful for debuggers to inspect + the state. +
+ + Threaddata returns a pointer to a per-thread pointer that may + be modified by threaded programs for per-thread storage. Similarly, + procdata returns a pointer to a per-proc pointer. +
+ + Threadexecl and threadexec are threaded analogues of exec and + execl (see exec(3)); on success, they replace the calling thread + and invoke the external program, never returning. (Unlike on Plan + 9, the calling thread need not be the only thread in its proc--the + other threads will continue executing.) On error, they return + –1. If cpid is not null, the pid of the invoked program will be + sent along cpid (using sendul) once the program has been started, + or –1 will be sent if an error occurs. Threadexec and threadexecl + will not access their arguments after sending a result along cpid. + Thus, programs that malloc the argv passed to threadexec + can safely free it once they have received the cpid response. + +
+ + Threadexecl and threadexec will duplicate (see dup(3)) the three + file descriptors in fd onto standard input, output, and error + for the external program and then close them in the calling thread. + Beware of code that sets
+ +
+ + fd[0] = 0;
+ fd[1] = 1;
+ fd[2] = 2;
+ +
+ + +
+ to use the current standard files. The correct code is
+ +
+ + fd[0] = dup(0, −1);
+ fd[1] = dup(1, −1);
+ fd[2] = dup(2, −1);
+ +
+ + +
+ Threadspawn is like threadexec but does not replace the current + thread. It returns the pid of the invoked program on success, + or –1 on error. +
+ + Threadwaitchan returns a channel of pointers to Waitmsg structures + (see wait(3)). When an exec’ed process exits, a pointer to a Waitmsg + is sent to this channel. These Waitmsg structures have been allocated + with malloc(3) and should be freed after use. +
+ + A Channel is a buffered or unbuffered queue for fixed-size messages. + Procs and threads send messages into the channel and recv messages + from the channel. If the channel is unbuffered, a send operation + blocks until the corresponding recv operation occurs and vice + versa. Chaninit initializes a Channel for + messages of size elsize and with a buffer holding nel messages. + If nel is zero, the channel is unbuffered. Chancreate allocates + a new channel and initializes it. Chanfree frees a channel that + is no longer used. 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 chanfree returns immediately). +
+ + The name element in the Channel structure is a description intended + for use in debugging. Chansetname sets the name. +
+ + Send sends the element pointed at by v to the channel c. If v + is null, zeros are sent. Recv receives an element from c and stores + it in v. If v is null, the received value is discarded. Send and + recv return 1 on success, –1 if interrupted. Nbsend and nbrecv + behave similarly, but return 0 rather than blocking. +
+ + Sendp, nbsendp, sendul, and nbsendul send a pointer or an unsigned + long; the channel must have been initialized with the appropriate + elsize. Recvp, nbrecvp, recvul, and nbrecvul receive a pointer + or an unsigned long; they return zero when a zero is received, + when interrupted, or (for nbrecvp and nbrecvul) when the + operation would have blocked. To distinguish between these three + cases, use recv or nbrecv. +
+ + Alt can be used to recv from or send to one of a number of channels, + as directed by an array of Alt structures, each of which describes + a potential send or receive operation. In an Alt structure, c + is the channel; v the value pointer (which may be null); and op + the operation: CHANSND for a send operation, + CHANRECV for a recv operation; CHANNOP for no operation (useful + when alt is called with a varying set of operations). The array + of Alt structures is terminated by an entry with op CHANEND or + CHANNOBLK. If at least one Alt structure can proceed, one of them + is chosen at random to be executed. Alt returns the + index of the chosen structure. If no operations can proceed and + the list is terminated with CHANNOBLK, alt returns the index of + the terminating CHANNOBLK structure. Otherwise, alt blocks until + one of the operations can proceed, eventually returning the index + of the structure executes. Alt returns –1 when + interrupted. The tag and entryno fields in the Alt structure are + used internally by alt and need not be initialized. They are not + used between alt calls. +
+ + Chanprint formats its arguments in the manner of print(3) and + sends the result to the channel c. The string delivered by chanprint + is allocated with malloc(3) and should be freed upon receipt. + +
+ + Thread library functions do not return on failure; if errors occur, + the entire program is aborted. +
+ + Threaded programs should use threadnotify in place of atnotify + (see notify(3)). +
+ + It is safe to use sysfatal(3) in threaded programs. Sysfatal will + print the error string and call threadexitsall. +
+ + It is not safe to call rfork in a threaded program, except to + call rfork(RFNOTEG) from the main proc before any other procs + have been created. To create new processes, use proccreate.
+ +
+

FILES
+ +
+ + /usr/local/plan9/acid/thread contains useful acid(1) functions + for debugging threaded programs. +
+ + /usr/local/plan9/src/libthread/test contains some example programs.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libthread
+ +
+

SEE ALSO
+ +
+ + intro(3), ioproc(3)
+ +
+

BUGS
+ +
+ + To avoid name conflicts, alt, nbrecv, nbrecvp, nbrecvul, nbsend, + nbsendp, nbsendul, recv, recvp, recvul, send, sendp, and sendul + are defined as macros that expand to chanalt, channbrecv, and + so on. Yield is defined as a macro that expands to threadyield. + See intro(3). +
+ + The implementation of threadnotify may not be correct.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/time.html b/man/man3/time.html new file mode 100644 index 00000000..de0de468 --- /dev/null +++ b/man/man3/time.html @@ -0,0 +1,79 @@ + +time(3) - Plan 9 from User Space + + + + +
+
+
TIME(3)TIME(3) +
+
+

NAME
+ +
+ + time, nsec – time in seconds and nanoseconds since epoch
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + long time(long *tp)
+ +
+ + vlong nsec(void)
+ +
+

DESCRIPTION
+ +
+ + Both time and 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 time, if tp is not zero then *tp + is also set to the answer.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/time.c
+ +
+

DIAGNOSTICS
+ +
+ + These functions set errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, time and nsec + are preprocessor macros defined as p9time and p9nsec; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/udpread.html b/man/man3/udpread.html new file mode 100644 index 00000000..e8f0d37b --- /dev/null +++ b/man/man3/udpread.html @@ -0,0 +1,105 @@ + +udpread(3) - Plan 9 from User Space + + + + +
+
+
UDPREAD(3)UDPREAD(3) +
+
+

NAME
+ +
+ + udpread, udpwrite – read and write UDP packets
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + #include <ip.h> +
+ + typedef struct Udphdr Udphdr;
+ struct Udphdr
+ {
+ +
+ + uchar    raddr[IPaddrlen];/* remote address and port */
+ uchar    laddr[IPaddrlen];/* local address and port */
+ uchar    rport[2];
+ uchar    lport[2];
+ +
+ };
+ +
+ + long      udpread(int fd, Udphdr *hdr, void *data, long n)
+ +
+ + long udpwrite(int fd, Udphdr *hdr, void *data, long n)
+ +
+

DESCRIPTION
+ +
+ + Udpread and udpwrite read and write UDP packets from the UDP network + connection established on file descriptor fd. +
+ + Udpread reads at most n bytes of packet body into data , stores + the header in hdr, and returns the number of bytes stored in data. + +
+ + Udpwrite writes the n bytes stored in data in a UDP packet with + header hdr. +
+ + Note that the Udphdr frames the addresses as local and remote + instead of source and destination. Thus the hdr filled in for + a packet read by udpread can be used unchanged in udpwrite to + send a response back to the sender of the original packet.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/udp.c
+ +
+

SEE ALSO
+ +
+ + ip(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/wait.html b/man/man3/wait.html new file mode 100644 index 00000000..84322bc2 --- /dev/null +++ b/man/man3/wait.html @@ -0,0 +1,170 @@ + +wait(3) - Plan 9 from User Space + + + + +
+
+
WAIT(3)WAIT(3) +
+
+

NAME
+ +
+ + await, awaitnohang, awaitfor, wait, waitnohang, waitfor, waitpid + – wait for a process to exit
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h> +
+ + Waitmsg*    wait(void) +
+ + Waitmsg*    waitnohang(void) +
+ + Waitmsg*    waitfor(int pid) +
+ + int         waitpid(void) +
+ + int         await(char *s, int n) +
+ + int         awaitnohang(char *s, int n) +
+ + int         awaitfor(int pid, char *s, int n)
+ +
+

DESCRIPTION
+ +
+ + Wait causes a process to wait for any child process (see fork(2) + and rfork(3)) to exit. It returns a Waitmsg holding information + about the exited child. A Waitmsg has this structure:
+ +
+ + typedef
+ struct Waitmsg
+ {
+ +
+ + int pid;               /* of loved one */
+ ulong time[3];          /* of loved one & descendants */
+ char *msg;
+ +
+ } Waitmsg;
+ +
+ + +
+ Pid is the child’s process id. The 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. Msg contains the message that the child specified + in exits(3). For a normal exit, msg[0] is zero, otherwise msg + is the exit string prefixed by the process name, a blank, the + process id, and a colon. +
+ + If there are no more children to wait for, wait returns immediately, + with return value nil. +
+ + The Waitmsg structure is allocated by malloc(3) and should be + freed after use. For programs that only need the pid of the exiting + program, waitpid returns just the pid and discards the rest of + the information. +
+ + Waitnohang is like wait but does not block if there are no more + children to wait for. Instead it returns immediately and sets + errstr. +
+ + Waitfor is like wait but waits for a particular pid. +
+ + The underlying calls are await, awaitnohang, and awaitfor, which + fill in the n-byte buffer 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. +
+ + The filled-in buffer may be parsed (after appending a NUL) using + tokenize (see getfields(3)); the resulting fields are, in order, + pid, the three times, and the exit string, which will be '' for + normal exit. If the representation is longer than 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 await will return the information about the next exiting child, + not the remainder of the truncated message. In other words, each + call to await returns the information about one child, blocking + if necessary if no child has exited. If the calling process has + no + living children, await returns −1.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/wait.c +
+ + /usr/local/plan9/src/lib9/await.c
+ +
+

SEE ALSO
+ +
+ + rfork(3), exits(3),
+ +
+

DIAGNOSTICS
+ +
+ + These routines set errstr.
+ +
+

BUGS
+ +
+ + To avoid name conflicts with the underlying system, wait, waitpid, + and waitfor are preprocessor macros defined as p9wait, p9waitpid, + and p9waitfor; see intro(3).
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/wctl.html b/man/man3/wctl.html new file mode 100644 index 00000000..071217e2 --- /dev/null +++ b/man/man3/wctl.html @@ -0,0 +1,78 @@ + +wctl(3) - Plan 9 from User Space + + + + +
+
+
WCTL(3)WCTL(3) +
+
+

NAME
+ +
+ + drawresizewindow, drawsetlabel, drawtopwindow – window management
+ +
+

SYNOPSIS
+ +
+ + #include <draw.h> +
+ + void drawresizewindow(Rectangle r) +
+ + int    drawsetlabel(Display *d, char *name) +
+ + void drawtopwindow(void)
+ +
+

DESCRIPTION
+ +
+ + These routines interact with a window manager to set the properties + of the window running the current program. They substitute for + interacting directly with the Plan 9 rio’s /dev/wctl. +
+ + Drawresizewindow requests that the program’s window be resized + to have the width and height of the rectangle r. Only the width + and height are important; the offset is ignored. +
+ + Drawsetlabel requests that the program’s window title be set to + name. +
+ + Drawtopwindow requests that the program’s window be moved above + all other windows and given the input focus.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw/x11−init.c
+ /usr/local/plan9/src/libdraw/x11−wsys.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man3/window.html b/man/man3/window.html new file mode 100644 index 00000000..83355bdd --- /dev/null +++ b/man/man3/window.html @@ -0,0 +1,241 @@ + +window(3) - Plan 9 from User Space + + + + +
+
+
WINDOW(3)WINDOW(3) +
+
+

NAME
+ +
+ + Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, + bottomnwindows, topwindow, topnwindows, originwindow – window management
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ +
+ + 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;
+ +
+ + Screen* allocscreen(Image *image, Image *fill, int public) +
+ + Screen* publicscreen(Display *d, int id, ulong chan) +
+ + int       freescreen(Screen *s) +
+ + Image*    allocwindow(Screen *s, Rectangle r, int ref, int val) +
+ + void      bottomwindow(Image *w) +
+ + void      bottomnwindows(Image **wp, int nw) +
+ + void      topwindow(Image *w) +
+ + void      topnwindows(Image **wp, int nw) +
+ + int       originwindow(Image *w, Point log, Point scr) +
+ + enum
+ {
+ +
+ + +
+ + /* refresh methods */
+ Refbackup= 0,
+ Refnone= 1,
+ Refmesg= 2
+ +
+ +
+ };
+ +
+

DESCRIPTION
+ +
+ + Windows are represented as 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. +
+ + To create windows, it is first necessary to allocate a Screen + data structure to gather them together. A Screen turns an arbitrary + image into something that may have windows upon it. It is created + by allocscreen, which takes an image upon which to place the windows + (typically display−>image), a 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 publicscreen + with the Display pointer and the id of the + published 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. Freescreen releases + a Screen, although it may not actually disappear from view until + all the windows upon it have also been + deallocated. +
+ + Unlike allocwindow, allocscreen does not initialize the appearance + of the Screen. +
+ + Windows are created by allocwindow, which takes a pointer to the + Screen upon which to create the window, a rectangle r defining + its geometry, an integer pixel value val to color the window initially, + and a refresh method ref. The refresh methods are Refbackup, which + provides backing store and is the + method used by rio(1) for its clients; 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 Refmesg, which causes messages to be + delivered to the owner of the window when it needs to be repainted. + Refmesg is not fully implemented. +
+ + The result of allocwindow is an Image pointer that may be treated + like any other image. In particular, it is freed by calling freeimage + (see allocimage(3)). The following functions, however, apply only + to windows, not regular images. +
+ + Bottomwindow pushes window w to the bottom of the stack of windows + on its Screen, perhaps obscuring it. Topwindow pulls window w + to the top, making it fully visible on its Screen. (This Screen + may itself be within a window that is not fully visible; topwindow + will not affect the stacking of this parent + window.) Bottomnwindows and Topnwindows are analogous, but push + or pull a group of nw windows listed in the array wp. The order + within wp is unaffected. +
+ + Each window is created as an Image whose Rectangle r corresponds + to the rectangle given to allocwindow when it was created. Thus, + a newly created window w resides on its Screen−>image at w−>r and + has internal coordinates w−>r. Both these may be changed by a call + to originwindow. The two + Point arguments to originwindow define the upper left corner of + the logical coordinate system (log) and screen position (scr). + Their usage is shown in the Examples section. +
+ + Rio(1) creates its client windows with backing store, Refbackup. + The graphics initialization routine, initdraw (see graphics(3)), + builds a Screen upon this, and then allocates upon that another + window indented to protect the border. That window is created + Refnone, since the backing store created by rio + protects its contents. That window is the one known in the library + by the global name screen (a historic but confusing choice).
+ +
+

EXAMPLES
+ +
+ + To move a window to the upper left corner of the display,
+ +
+ + +
+ + originwindow(w, w−>r.min, Pt(0, 0));
+ +
+ +
+ 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,
+ +
+ + +
+ + originwindow(w, Pt(0, 0), w−>r.min);
+ +
+ +
+ After this is done, 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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libdraw
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), cachechars(3), draw(3)
+ +
+

BUGS
+ +
+ + The refresh method Refmesg should be finished.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man4/9pserve.html b/man/man4/9pserve.html new file mode 100644 index 00000000..c9f2c3b7 --- /dev/null +++ b/man/man4/9pserve.html @@ -0,0 +1,79 @@ + +9pserve(4) - Plan 9 from User Space + + + + +
+
+
9PSERVE(4)9PSERVE(4) +
+
+

NAME
+ +
+ + 9pserve – announce and multiplex 9P service
+ +
+

SYNOPSIS
+ +
+ + 9pserve [ −v ] addr
+ +
+

DESCRIPTION
+ +
+ + On Plan 9, when a user-level file server mounts itself into a + name space or posts itself in /srv, the Plan 9 kernel multiplexes + the potentially many processes accessing the server into a single + 9P conversation. The user-level server need not concern itself + with how many processes are accessing it or with cleaning up + after a process when it exits unexpectedly. On Unix, 9pserve takes + the place of the Plan 9 kernel, multiplexing clients onto a single + server conversation and cleaning up after clients when they hang + up unexpectedly. +
+ + 9pserve announces a 9P service on addr and multiplexes any 9P + clients connecting to addr into a single conversation with a 9P + server on 9pserve’s standard input and output. When a client hangs + up, 9pserve flushes any outstanding 9P transactions and clunks + any outstanding fids belonging to the client. +
+ + 9pserve is typically not invoked directly; use post9pservice(3) + instead.
+ +
+

SEE ALSO
+ +
+ + intro(4), intro(9p)
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/9pserve.c
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man4/acme.html b/man/man4/acme.html new file mode 100644 index 00000000..ac310c13 --- /dev/null +++ b/man/man4/acme.html @@ -0,0 +1,268 @@ + +acme(4) - Plan 9 from User Space + + + + +
+
+
ACME(4)ACME(4) +
+
+

NAME
+ +
+ + acme – control files for text windows
+ +
+

SYNOPSIS
+ +
+ + acme [ −f varfont ] [ −F fixfont ] [ file ... ]
+ +
+

DESCRIPTION
+ +
+ + The text window system 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 acme itself. When a command is run under acme, a + directory holding these files is posted as the 9P + service acme (using 9pserve(4)). +
+ + Some of these files supply virtual versions of services available + from the underlying environment, in particular the character terminal + files in Plan 9’s cons(3). (Unlike in Plan 9’s rio(1), each command + under acme sees the same set of files; there is not a distinct + /dev/cons for each window.) Other files are unique to + acme.
+ acmeis a subdirectory used by win (see acme(1)) as a mount point + for the acme files associated with the window in which win is + running. It has no specific function under acme itself.
+ consis the standard and diagnostic output file for all commands + run under acme. (Input for commands is redirected to /dev/null.) + Text written to cons appears in a window labeled dir/+Errors, + where dir is the directory in which the command was run. The window + is created if necessary, but not until text is + +
+ + actually written.
+ +
+ consctl
+ +
+ + Is an empty unwritable file present only for compatibility; there + is no way to turn off ‘echo’, for example, under acme.
+ +
+ 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--the + 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--followed by the tag up to a newline if present. Thus + at character position 5x12 starts the name of the window. If a + file has multiple zeroxed windows open, only the most recently + used will appear in the index file.
+ +
+ label
+ +
+ + is an empty file, writable without effect, present only for compatibility + with rio.
+ +
+ new   A directory analogous to the numbered directories (q.v.). Accessing + any file in new creates a new window. Thus to cause text to appear + in a new window, write it to /dev/new/body. For more control, + open /dev/new/ctl and use the interface described below. +
+ + +
+ + Each acme window has associated a directory numbered by its ID. + Window IDs are chosen sequentially and may be discovered by the + ID command, by reading the ctl file, or indirectly through the + index file. The files in the numbered directories are as follows.
+ addrmay 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 data file. When read, it returns + the value of the address that would next be read or + +
+ + written through the data file, in the format #m,#n where m and + n are character (not byte) offsets. If m and n are identical, + the format is just #m. Thus a regular expression may be evaluated + by writing it to addr and reading it back. The addr address has + no effect on the user’s selection of text. + +
+ bodyholds contents of the window body. It may be read at any byte + offset. Text written to body is always appended; the file offset + is ignored.
+ ctl   may be read to recover the five numbers as held in the index + file, described above, plus two more fields: the width of the + window in pixels and the name of the font used in the window. + Text messages may be written to ctl to affect the window. Each + message is terminated by a newline and multiple messages + +
+ + may be sent in a single write.
+ +
+ + addr=dot     Set the addr address to that of the user’s selected text + in the window.
+ clean        Mark the window clean as though it has just been written.
+ dirty        Mark the window dirty, the opposite of clean.
+ cleartag     Remove all text in the tag after the vertical bar.
+ del          Equivalent to the Del interactive command.
+ delete       Equivalent to the Delete interactive command.
+ dot=addr     Set the user’s selected text in the window to the text + addressed by the addr address.
+ dump commandSet the command string to recreate the window from + a dump file.
+ dumpdir directory
+ Set the directory in which to run the command to recreate the + window from a dump file.
+ get          Equivalent to the Get interactive command with no arguments; + accepts no arguments.
+ limit=addr   When the ctl file is first opened, regular expression + context searches in addr addresses examine the whole file; this + message restricts subsequent searches to the current addr address.
+ mark         Cancel nomark, returning the window to the usual state wherein + each modification to the body must be undone individually.
+ name name     Set the name of the window to name.
+ nomark       Turn off automatic ‘marking’ of changes, so a set of related + changes may be undone in a single Undo interactive command.
+ noscroll     Turn off automatic ‘scrolling’ of the window to show text + written to the body.
+ put          Equivalent to the Put interactive command with no arguments; + accepts no arguments.
+ scroll       Cancel a noscroll message, returning the window to the default + state wherein each write to the body file causes the window to + ‘scroll’ to display the new text.
+ show         Guarantee at least some of the selected text is visible on + the display.
+ +
+ +
+ datais used in conjunction with addr for random access to the + contents of the body. The file offset is ignored when writing + the data file; instead the location of the data to be read or + written is determined by the state of the addr file. Text, which + must contain only whole characters (no ‘partial runes’), written + to + +
+ + data replaces the characters addressed by the addr file and sets + the address to the null string at the end of the written text. + A read from data returns as many whole characters as the read + count will permit starting at the beginning of the 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.
+ +
+ event
+ +
+ + When a window’s 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 Cut and Paste, which behave normally) have no immediate + effect on the window; it is expected that + the program reading the 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 E for writes + to the body or tag file, F for actions through the window’s other + files, K for the keyboard, and M for the mouse. The + type characters are D for text deleted from the body, d for text + deleted from the tag, I for text inserted to the body, i for text + inserted to the tag, L for a button 3 action in the body, l for + a button 3 action in the tag, X for a button 2 action in the body, + and x for a button 2 action in the tag. + 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 data file if needed. No + text is sent on a D or d message.
+ For D, d, I, and i the flag is always zero. For X and x, the flag + is a bitwise OR (reported decimally) of the following: 1 if the + text indicated is recognized as an 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.
+ For L and l, the flag is the bitwise OR of the following: 1 if + acme can interpret the action without loading a new file; 2 if + a second (post-expansion) message follows, analogous to that with + X messages; 4 if the text is a file or window name (perhaps with + address) rather than plain literal text. + For messages with the 1 bit on in the flag, writing the message + back to the 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 event file had not been open.
+ +
+ tag   holds contents of the window tag. It may be read at any byte + offset. Text written to tag is always appended; the file offset + is ignored.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/acme
+ +
+

SEE ALSO
+ +
+ + rio(1), acme(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man4/import.html b/man/man4/import.html new file mode 100644 index 00000000..e0eca5cb --- /dev/null +++ b/man/man4/import.html @@ -0,0 +1,107 @@ + +import(4) - Plan 9 from User Space + + + + +
+
+
IMPORT(4)IMPORT(4) +
+
+

NAME
+ +
+ + import – import 9P resources from another system
+ +
+

SYNOPSIS
+ +
+ + import [ −df ] [ −n ns ] [ −p prog ] [ −s service ] system
+ +
+

DESCRIPTION
+ +
+ + Import presents the 9P service service (default plumb) running + on system as a service on the local system, in the current name + space. +
+ + The −n option sets the remote name space directory where import + should expect to find service. If it is not specified, import + uses name of the local system’s name space directory. (Since name + space directories are conventionally inside /tmp, the path have + different meanings on the two systems.) +
+ + Import connects to system using ssh(1). It invokes import on the + remote system to carry out the remote side of the protocol. The + −p option specifies the path to import on the remote system, in + case it is not in the system search path. +
+ + The −d option turns on debugging. The −f option keeps import from + forking itself into the background, also useful for debugging.
+ +
+

EXAMPLE
+ +
+ + Suppose you run sam −r to the CPU server anna. Sam wants to talk + to a plumber on the local terminal, but the file names will refer + to files on anna. +
+ + To fix this problem, create a new name space directory and start + a new plumber on anna:
+ +
+ + remotens=/tmp/ns.`whoami`.on.`hostname`
+ ssh anna mkdir $remotens
+ ssh anna NAMESPACE=$remotens plumber
+ Now import that plumber to the local name space before starting + sam and 9term:
+ NAMESPACE=/tmp/ns.anna
+ mkdir $NAMESPACE
+ import −n $remotens −s plumb anna
+ sam &
+ 9term ssh anna &
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/import.c
+ +
+

SEE ALSO
+ +
+ + 9pserve(4), intro(4)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man4/index.html b/man/man4/index.html new file mode 100644 index 00000000..bef356e8 --- /dev/null +++ b/man/man4/index.html @@ -0,0 +1,49 @@ + + +Manual Section 4 - Plan 9 from User Space + + + +
+
+ +
+
+
+ Manual Section 4 - Plan 9 from User Space +
+
+
intro(4)intro – introduction to file servers +
+
+
+
9pserve(4)9pserve – announce and multiplex 9P service +
+
+
+
acme(4)acme – control files for text windows +
+
+
+
import(4)import – import 9P resources from another system +
+
+
+
plumber(4)plumber – file system for interprocess messaging +
+
+
+
ramfs(4)ramfs – memory file system +
+
+ +
+
+
+Space Glenda +
+
+		 +
+ + diff --git a/man/man4/intro.html b/man/man4/intro.html new file mode 100644 index 00000000..ec2409c0 --- /dev/null +++ b/man/man4/intro.html @@ -0,0 +1,92 @@ + +intro(4) - Plan 9 from User Space + + + + +
+
+
INTRO(4)INTRO(4) +
+
+

NAME
+ +
+ + intro – introduction to file servers
+ +
+

DESCRIPTION
+ +
+ + A Plan 9 file server provides a file tree to processes. This section + of the manual describes servers that can be mounted in a name + space to give a file-like interface to interesting services. A + file server may be a provider of a conventional file system, with + files maintained on permanent storage, or it may also be a process + that synthesizes files in some manner. +
+ + In Plan 9, the kernel mount device mnt(3) acts as a client to + the 9P servers mounted in the current name space, translating + system calls such as open(2) into 9P transactions such as open(9p). + The kernel also multiplexes the potentially many processes onto + a single 9P conversation with each server. Finally, the kernel + provides each process with its own private name space which it + can customize at will. Modern Unix systems do not provide these + niceties, so the Unix port of these Plan 9 file servers provides + them via other means. +
+ + On Unix, 9P clients do not access servers via the traditional + file system call interface. Only the Unix name space can be accessed + that way. Instead, 9P clients use the 9pclient(3) library to connect + and interact directly with particular 9P servers. The 9p(1) command-line + client is useful for interactive use and in shell + scripts. +
+ + To preserve the façade of a single 9P conversation with each server, + 9P servers invoke 9pserve(4), typically via post9pservice(3). + 9pserve announces a 9P service at a particular network address + and multiplexes the clients that connect to that address onto + a single 9P conversation with the server. +
+ + Each ported program operates in a pseudo-name space that determines + which 9P servers it is using. The name space of a ported program + is represented by a directory containing Unix domain sockets, + one for each 9P server. The directory defaults to /tmp/ns.$USER.$DISPLAY, + meaning that all programs in an X + Windows login session share a single name space. Setting the $NAMESPACE + environment variable overrides this default. The namespace(1) + command prints the current name space directory. +
+ + Occasionally it is useful to be able to connect the input or output + of a standard Unix program to a file served by a 9P server. The + new openfd(9p) 9P transaction, which depends on file descriptor + passing, provides a sufficient workaround in many cases. 9pserve’s + implementation of openfd (see also fsopenfd in + 9pclient(3)) returns the read or write end of a pipe; a helper + process transfers data between the other end of the pipe and the + 9P server. Note that since the data is being transferred via a + pipe, 9P read and write errors cannot be passed on to the Unix + program. The Unix program sees only end-of-file or a closed pipe. + +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man4/plumber.html b/man/man4/plumber.html new file mode 100644 index 00000000..83e5943f --- /dev/null +++ b/man/man4/plumber.html @@ -0,0 +1,122 @@ + +plumber(4) - Plan 9 from User Space + + + + +
+
+
PLUMBER(4)PLUMBER(4) +
+
+

NAME
+ +
+ + plumber – file system for interprocess messaging
+ +
+

SYNOPSIS
+ +
+ + plumber [ −p plumbing ]
+ +
+

DESCRIPTION
+ +
+ + The plumber is a user-level file server that receives, examines, + rewrites, and dispatches plumb(7) messages between programs. Its + behavior is programmed by a plumbing file (default $HOME/lib/plumbing) + in the format of plumb(7). +
+ + Its services are posted via 9pserve(4) as plumb. and consist of + two pre-defined files, plumb/send and plumb/rules, and a set of + output ports for dispatching messages to applications. +
+ + Programs use fswrite (see 9pclient(3)) to deliver messages to + the send file, and fsread to receive them from the corresponding + port. For example, sam(1)’s plumb menu item or the B command cause + a message to be sent to plumb/send; sam in turn reads from, by + convention, plumb/edit to receive + messages about files to open. +
+ + 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 plumb client + or plumb start rule, that rule is applied. A plumb client rule + causes the specified command to be run and the message to be held + for delivery when the port is opened. A + plumb start rule runs the command but discards the message. If + neither start or client is specified and the port is not open, + the message is discarded and a write error is returned to the + sender. +
+ + 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 plumb to rule. +
+ + The set of rules currently active may be examined by reading the + file plumb/rules; appending to this file adds new rules to the + set, while creating it (opening it with 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).
+ +
+

FILES
+ +
+ + $HOME/lib/plumbing   default rules file
+ /usr/local/plan9/plumb
+ +
+ + +
+ + directory to search for files in include statements
+ +
+ +
+ plumb               mount name for plumber(4).
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/plumb
+ +
+

SEE ALSO
+ +
+ + plumb(1), plumb(3), plumb(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man4/ramfs.html b/man/man4/ramfs.html new file mode 100644 index 00000000..7fb86f5a --- /dev/null +++ b/man/man4/ramfs.html @@ -0,0 +1,81 @@ + +ramfs(4) - Plan 9 from User Space + + + + +
+
+
RAMFS(4)RAMFS(4) +
+
+

NAME
+ +
+ + ramfs – memory file system
+ +
+

SYNOPSIS
+ +
+ + ramfs [ −i ] [ −S service ]
+ +
+

DESCRIPTION
+ +
+ + Ramfs starts a 9P file server keeping all files in memory. Initially + the file tree is empty. +
+ + By default ramfs posts its service as ramfs using 9pserve(4). + +
+ + The −S flag specifies an alternate service name for ramfs to use. + +
+ + The −i flag tells ramfs to use file descriptors 0 and 1 for its + communication channel rather than create a pipe. This makes it + possible to use ramfs as a file server on a remote machine: the + file descriptors 0 and 1 will be the network channel from ramfs + to the client machine. +
+ + 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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/ramfs.c
+ +
+

SEE ALSO
+ +
+ + 9p(3), 9pserve(4)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man5/index.html b/man/man5/index.html new file mode 100644 index 00000000..f6ea86f3 --- /dev/null +++ b/man/man5/index.html @@ -0,0 +1,28 @@ + + +Manual Section 5 - Plan 9 from User Space + + + +
+
+ +
+
+
+ Manual Section 5 - Plan 9 from User Space +
+
+
+
+ +
+
+
+Space Glenda +
+
+		 +
+ + diff --git a/man/man7/color.html b/man/man7/color.html new file mode 100644 index 00000000..262e4633 --- /dev/null +++ b/man/man7/color.html @@ -0,0 +1,169 @@ + +color(7) - Plan 9 from User Space + + + + +
+
+
COLOR(7)COLOR(7) +
+
+

NAME
+ +
+ + color – representation of pixels and colors
+ +
+

DESCRIPTION
+ +
+ + To address problems of consistency and portability among applications, + Plan 9 uses a fixed color map, called 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--mapping from a (red, + green, blue) triple to the color map and back again is easy--but + 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. + +
+ + Rather than dice the color cube into subregions of size 6×6×6 (as + in Netscape Navigator) or 8×8×4 (as in previous releases of Plan + 9), picking 1 color in each, the rgbv color map uses a 4×4×4 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. +
+ + The following function computes the 256 3-byte entries in the + color map:
+ +
+ + 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;
+ }
+ }
+ +
+ }
+ +
+ + +
+ There are 4 nested loops to pick the (red,green,blue) coordinates + of the subcube, and the value (intensity) within the subcube, + indexed by r, g, b, and v, whence the name rgbv. The peculiar + order in which the color map is indexed is designed to distribute + the grey shades uniformly through the map--the i’th grey + shade, 0<=i<=15 has index ix17, with black going to 0 and white to + 255. Therefore, when a call to 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. +
+ + The 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. +
+ + 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. +
+ + Colors may also be created with an opacity factor called alpha, + which is scaled so 0 represents fully transparent and 255 represents + opaque color. The alpha is premultiplied into the other channels, + as described in the paper by Porter and Duff cited in draw(3). + The function setalpha (see allocimage(3)) aids the + initialization of color values with non-trivial alpha. +
+ + 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. +
+ + To maintain a constant external representation, the draw(3) interface + as well as the various graphics libraries represent colors by + 32-bit numbers, as described in color(3).
+ +
+

SEE ALSO
+ +
+ + color(3), graphics(3), draw(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/face.html b/man/man7/face.html new file mode 100644 index 00000000..db220326 --- /dev/null +++ b/man/man7/face.html @@ -0,0 +1,127 @@ + +face(7) - Plan 9 from User Space + + + + +
+
+
FACE(7)FACE(7) +
+
+

NAME
+ +
+ + face – face files
+ +
+

DESCRIPTION
+ +
+ + The directories /usr/$user/lib/face and /lib/face contain a hierarchy + of images of people. In those directories are subdirectories named + by the sizes of the corresponding image files: 48x48x1 (48 by + 48 pixels, one bit per pixel); 48x48x2 (48 by 48 pixels, two (grey) + bits per pixel); 48x48x4 (48 by 48 + pixels, four (grey) bits per pixel); 48x48x8 (48 by 48 pixels, + eight (color-mapped) bits per pixel); 512x512x8 (512 by 512 pixels, + eight (color-mapped) bits per pixel); 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 image(7)). The small files are the ‘icons’ displayed + by faces and seemail (see Plan 9’s faces(1)); for depths less + than 4, their format is special. +
+ + 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:
+ +
+ + 0x9200, 0x1bb0, 0x003e,
+ +
+ + +
+ This odd format is historical and the programs that read it are + somewhat forgiving about blanks and the need for commas. +
+ + The files lib/face/*/.dict hold a correspondence between users + at machines and face files. The format is
+ +
+ + machine/user directory/file.ver
+ +
+ + +
+ The machine is the domain name of the machine sending the message, + and user the name of the user sending it. The directory is a further + subdirectory of (say) /lib/face/48x48x1, named by a single letter + corresponding to the first character of the user names. The file + is the name of the file, typically but not + always the user name, and 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 + b/bill. For example, Bill Gates might be represented by the line
+ +
+ + microsoft.com/bill b/bill.1
+ +
+ + +
+ If multiple entries exist for a user in the various .dict files, + faces chooses the highest pixel size less than or equal to that + of the display on which it is running. +
+ + Finally, or rather firstly, the file /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 + .dict files. The machine name may be a regular expression, so + for example the entry
+ +
+ + .*research\.bell−labs\.com      astro
+ +
+ + +
+ maps any of the machines in Bell Labs Research into the shorthand + name astro, which then appears as a domain name in the .dict files.
+ +
+

SEE ALSO
+ +
+ + mail(1), tweak(1), image(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/font.html b/man/man7/font.html new file mode 100644 index 00000000..a6bd6a91 --- /dev/null +++ b/man/man7/font.html @@ -0,0 +1,101 @@ + +font(7) - Plan 9 from User Space + + + + +
+
+
FONT(7)FONT(7) +
+
+

NAME
+ +
+ + font, subfont – external format for fonts and subfonts
+ +
+

SYNOPSIS
+ +
+ + #include <draw.h>
+ +
+

DESCRIPTION
+ +
+ + Fonts and subfonts are described in cachechars(3). +
+ + External fonts are described by a plain text file that can be + read using 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 readsubfont + (see graphics(3)). The minimum number of a covered range is mapped + to the specified starting position (default zero) of the corresponding + subfont. If the subfont file name does not begin with a slash, + it is taken relative to the directory containing the + font file. Each field must be followed by some white space. Each + numeric field may be C-format decimal, octal, or hexadecimal. + +
+ + External subfonts are represented in a more rigid format that + can be read and written using readsubfont and writesubfont (see + subfont(3)). The format for subfont files is: an image containing + character glyphs, followed by a subfont header, followed by character + information. The image has the format for external image + files described in image(7). The subfont header has 3 decimal + strings: n, height, and ascent. Each number is right-justified + and blank padded in 11 characters, followed by a blank. The character + info consists of n+1 6-byte entries, each giving the Fontchar + x (2 bytes, low order byte first), top, bottom, + left, and width. The x field of the last Fontchar is used to calculate + the image width of the previous character; the other fields in + the last Fontchar are irrelevant. +
+ + Note that the convention of using the character with value zero + (NUL) to represent characters of zero width (see draw(3)) means + that fonts should have, as their zeroth character, one with non-zero + width.
+ +
+

FILES
+ +
+ + /usr/local/plan9/font/*   font directories
+ +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), cachechars(3), subfont(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/image.html b/man/man7/image.html new file mode 100644 index 00000000..f81c023b --- /dev/null +++ b/man/man7/image.html @@ -0,0 +1,175 @@ + +image(7) - Plan 9 from User Space + + + + +
+
+
IMAGE(7)IMAGE(7) +
+
+

NAME
+ +
+ + image – external format for images
+ +
+

SYNOPSIS
+ +
+ + #include <draw.h>
+ +
+

DESCRIPTION
+ +
+ + Images are described in graphics(3), and the definition of pixel + values is in color(7). Fonts and images are stored in external + files in machine-independent formats. +
+ + Image files are read and written using readimage and writeimage + (see allocimage(3)),or readmemimage and writememimage (see memdraw(3)). + An uncompressed image file starts with 5 strings: chan, r.min.x, + r.min.y, r.max.x, and r.max.y. Each is right-justified and blank + padded in 11 + characters, followed by a blank. The chan value is a textual string + describing the pixel format (see strtochan in graphics(3) and + the discussion of channel descriptors below), and the rectangle + coordinates are decimal strings. The rest of the file contains + the r.max.y−r.min.y rows of pixel data. A row consists + of the byte containing pixel r.min.x and all the bytes up to and + including the byte containing pixel r.max.x-1. For images with + depth d less than eight, a pixel with x-coordinate = x will appear + as d contiguous bits in a byte, with the pixel’s high order bit + starting at the byte’s bit number 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 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. +
+ + The loadimage and unloadimage functions described in allocimage(3) + also deal with rows in this format, stored in user memory. +
+ + The channel format string is a sequence of two-character channel + descriptions, each comprising a letter (r for red, g for green, + b for blue, a for alpha, m for color-mapped, k for greyscale, + and 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 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. +
+ + 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 'r8g8b8' pixels have byte ordering blue, green, + and red within the file. See color(7) for more details of the + pixel format. +
+ + A venerable yet deprecated format replaces the channel string + with a decimal ldepth, which is the base two logarithm of the + number of bits per pixel in the image. In this case, ldepths 0, + 1, 2, and 3 correspond to channel descriptors k1, k2, k4, and + m8, respectively. +
+ + Compressed image files start with a line of text containing the + word compressed, followed by a header as described above, followed + by the image data. The data, when uncompressed, is laid out in + the usual form. +
+ + 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. +
+ + A compression block begins with two decimal strings of twelve + bytes each. The first number is one more than the 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. +
+ + 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. + +
+ + 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. +
+ + 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. +
+ + 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. + +
+ + Some small images, in particular 48×48 face files as used by seemail + (see Plan 9’s faces(1) and face(7)) and 16×16 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 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.
+ +
+

SEE ALSO
+ +
+ + jpg(1), tweak(1), graphics(3), draw(3), allocimage(3), color(7), + face(7), font(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/index.html b/man/man7/index.html new file mode 100644 index 00000000..5f61f6e5 --- /dev/null +++ b/man/man7/index.html @@ -0,0 +1,76 @@ + + +Manual Section 7 - Plan 9 from User Space + + + +
+
+ +
+
+
+ Manual Section 7 - Plan 9 from User Space +
+
+
+
+
+
color(7)color – representation of pixels and colors +
+
+
+
face(7)face – face files +
+
+
+
font(7)font, subfont – external format for fonts and subfonts +
+
+
+
image(7)image – external format for images +
+
+
+
man(7)man – macros to typeset manual +
+
+
+
map(7)map – digitized map formats +
+
+
+
ms(7)ms – macros for formatting manuscripts +
+
+
+
plot(7)plot – graphics interface +
+
+
+
plumb(7)plumb – format of plumb messages and rules +
+
+
+
regexp(7)regexp – Plan 9 regular expression notation +
+
+
+
thumbprint(7)thumbprint – public key thumbprints +
+
+
+
utf(7)UTF, Unicode, ASCII, rune – character set and format +
+
+ +
+
+
+Space Glenda +
+
+		 +
+ + diff --git a/man/man7/man.html b/man/man7/man.html new file mode 100644 index 00000000..4087e795 --- /dev/null +++ b/man/man7/man.html @@ -0,0 +1,292 @@ + +man(7) - Plan 9 from User Space + + + + +
+
+
MAN(7)MAN(7) +
+
+

NAME
+ +
+ + man – macros to typeset manual
+ +
+

SYNOPSIS
+ +
+ + nroff −man file ... +
+ + troff −man file ...
+ +
+

DESCRIPTION
+ +
+ + These macros are used to format pages of this manual. +
+ + Except in .LR and .RL requests, any text argument denoted t in + the request summary may be zero to six words. Quotes " ... " may + be used to include blanks in a ‘word’. If 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, .I + may be used to italicize a line of more than 6 words, or .SM followed + by .B to make small letters in ‘bold’ font. +
+ + 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 are ens. + +
+ + The fonts are
+ R     roman, the main font, preferred for diagnostics
+ I     italic, preferred for parameters, short names of commands, names + of manual pages, and naked function names
+ B     ‘bold’, actually the constant width font, preferred for examples, + file names, declarations, keywords, names of struct members, and + literals (numbers are rarely literals)
+ L     also the constant width font. In troff L=B; in nroff arguments + of the macros .L, .LR, and .RL are printed in quotes; preferred + only where quotes really help (e.g. lower-case literals and punctuation). + +
+ + Type font and size are reset to default values before each paragraph, + and after processing font- or size-setting macros. +
+ + The −man macros admit equations and tables in the style of eqn(1) + and tbl(1), but do not support arguments on .EQ and .TS macros. + +
+ + These strings are predefined by −man:
+ \*R   ‘®’, ‘(Reg)’ in nroff.
+ \*S   Change to default type size. \*9 The root directory of the + Plan 9 installation.
+ +
+

FILES
+ +
+ + /usr/local/plan9/tmac/tmac.an +
+ + /usr/local/plan9/tmac/tmac.antimes
+ +
+

SEE ALSO
+ +
+ + troff(1), man(1)
+ +
+

REQUESTS
+Request Cause If no      Explanation
+ +
+ + +
+ + Break Argument
+ +
+ +
+.B t     no +
+ +
+ +
+ +
+t=n.t.l.*    Text t is ‘bold’.
+.BI t    no +
+ +
+ +
+ +
+t=n.t.l.    Join words of t alternating bold and italic.
+.BR t    no +
+ +
+ +
+ +
+t=n.t.l.    Join words of t alternating bold and Roman.
+.DT      no           Restore default tabs.
+.EE      yes           End displayed example
+.EX      yes           Begin displayed example
+.HP i    yes +
+ +
+ +
+i=p.i.*     Set prevailing indent to i. Begin paragraph with hanging +indent.
+.I t     no +
+ +
+ +
+ +
+t=n.t.l.    Text t is italic.
+.IB t    no +
+ +
+ +
+ +
+t=n.t.l.    Join words of t alternating italic and bold.
+.IP x i yes +
+ +
+ +
+x=""      Same as .TP with tag x.
+.IR t    no +
+ +
+ +
+ +
+t=n.t.l.    Join words of t alternating italic and Roman.
+.L t     no +
+ +
+ +
+ +
+t=n.t.l.    Text t is literal.
+.LP      yes           Same as .PP.
+.LR t    no           Join 2 words of t alternating literal and Roman.
+.PD d    no +
+ +
+ +
+ +
+d=.4v    Interparagraph distance is d.
+.PP      yes           Begin paragraph. Set prevailing indent to default.
+.RE      yes           End of relative indent. Set prevailing indent to amount +of starting .RS.
+.RI t    no +
+ +
+ +
+ +
+t=n.t.l.    Join words of t alternating Roman and italic.
+.RL t    no           Join 2 or 3 words of t alternating Roman and literal.
+.RS i    yes +
+ +
+ +
+i=p.i.     Start relative indent, move left margin in distance i. +Set prevailing indent to default for nested indents.
+.SH t    yes +
+ +
+ +
+t=""      Subhead; reset paragraph distance.
+.SM t    no +
+ +
+ +
+ +
+t=n.t.l.    Text t is small.
+.SS t    no +
+ +
+ +
+ +
+t=""      Secondary subhead.
+.TF s    yes           Prevailing indent is wide as string s in font L; paragraph +distance is 0.
+.TH n c x      yes       Begin page named n of chapter c; x is extra commentary, +e.g. ‘local’, for page head. Set prevailing indent and tabs to +default.
+.TP i    yes +
+ +
+ +
+i=p.i.     Set prevailing indent to i. Restore default indent if +i=0. Begin indented paragraph with hanging tag given by next text +line. If tag doesn’t fit, place it on separate line.
+.1C      yes           Equalize columns and return to 1-column output
+.2C      yes           Start 2-column nofill output +
+ +* n.t.l. = next text line; p.i. = prevailing indent
+

BUGS
+ +
+ + There’s no way to fool troff into handling literal double quote + marks " in font-alternation macros, such as .BI. +
+ + There is no direct way to suppress column widows in 2-column output; + the column lengths may be adjusted by inserting .sp requests before + the closing .1C.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/map.html b/man/man7/map.html new file mode 100644 index 00000000..1ebdfbba --- /dev/null +++ b/man/man7/map.html @@ -0,0 +1,108 @@ + +map(7) - Plan 9 from User Space + + + + +
+
+
MAP(7)MAP(7) +
+
+

NAME
+ +
+ + map – digitized map formats
+ +
+

DESCRIPTION
+ +
+ + Files used by map(7) are a sequence of structures of the form: + +
+ + 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;
+ +
+ };
+ where short stands for 16-bit integers and there is no padding + within or between structs. Shorts are stored in little-endian + order, low byte first. To assure portability, map accesses them + bytewise. +
+ + Fields patchlatitude and 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. +
+ + Each segment of |n| points is connected; consecutive segments + are not necessarily related. Latitude and longitude are measured + in units of 0.0001 radian. If 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. +
+ + The patches are ordered lexicographically by patchlatitude then + patchlongitude. A printable index to the first segment of each + patch in a file named data is kept in an associated file named + data.x. Each line of an index file contains patchlatitude, 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.
+ +
+

SEE ALSO
+ +
+ + map(7)
+ The data comes from the World Data Bank I and II and U.S. Government + sources: the Census Bureau, Geological Survey, and CIA.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/ms.html b/man/man7/ms.html new file mode 100644 index 00000000..3ef5ef5d --- /dev/null +++ b/man/man7/ms.html @@ -0,0 +1,185 @@ + +ms(7) - Plan 9 from User Space + + + + +
+
+
MS(7)MS(7) +
+
+

NAME
+ +
+ + ms – macros for formatting manuscripts
+ +
+

SYNOPSIS
+ +
+ + nroff −ms [ options ] file ...
+ troff −ms [ options ] file ...
+ +
+

DESCRIPTION
+ +
+ + This package of nroff and troff(1) macro definitions provides + a canned formatting facility for technical papers in various formats. + +
+ + The macro requests are defined below. Many nroff and troff requests + are unsafe in conjunction with this package, but the following + requests may be used with impunity after the first .PP: .bp, .br, + .sp, .ls, .na. +
+ + Output of the eqn(1), tbl(1), pic(1) and grap(1) preprocessors + for equations, tables, pictures, and graphs is acceptable as input.
+ +
+

FILES
+ +
+ + /usr/local/plan9/tmac/tmac.s
+ +
+

SEE ALSO
+ +
+ + M. E. Lesk, “Typing Documents on the UNIX System: Using the –ms + Macros with Troff and Nroff”, Unix Research System Programmer’s + Manual, Tenth Edition, Volume 2.
+ eqn(1), troff(1), tbl(1), pic(1)
+ +
+

REQUESTS
+Request Initial Cause Explanation
+ +
+ + +
+ + Value Break
+ +
+ +
+.1C      yes    yes    One column format on a new page.
+.2C      no    yes    Two column format.
+.AB      no    yes    Begin abstract.
+.AE      -     yes    End abstract.
+.AI      no    yes    Author’s institution follows. Suppressed in .TM.
+.AT      no    yes    Print ‘Attached’ and turn off line filling.
+.AU x y no    yes    Author’s name follows. x is location and y is extension, +ignored except in TM.
+.B x y    no    no     Print x in boldface, append y; if no argument switch +to boldface.
+.B1      no    yes    Begin text to be enclosed in a box.
+.B2      no    yes    End boxed text.
+.BI x y no    no     Print x in bold italic and append y; if no argument +switch to bold italic.
+.BT      date no     Bottom title, automatically invoked at foot of page. +May be redefined.
+.BX x     no    no     Print x in a box.
+.CW x y no    no     Constant width font for x, append y; if no argument +switch to constant width.
+.CT      no    yes    Print ‘Copies to’ and turn off line filling.
+.DA x     nroff no     ‘Date line’ at bottom of page is x. Default is +today.
+.DE      -     yes    End displayed text. Implies .KE.
+.DS x     no    yes    Start of displayed text, to appear verbatim line-by-line: +I indented (default), L left-justified, C centered, B (block) +centered with straight left margin. Implies .KS.
+.EG      no    -      Print document in BTL format for ‘Engineer’s Notes.’ +Must be first.
+.EN      -     yes    Space after equation produced by neqn or eqn(1).
+.EQ x y -     yes    Display equation. Equation number is y. Optional +x is I, L, C as in .DS.
+.FE      -     yes    End footnote.
+.FP x     -     no     Set font positions for a family, e.g., .FP lucidasans
+.FS      no    no     Start footnote. The note will be moved to the bottom +of the page.
+.HO      -     no     ‘Bell Laboratories, Holmdel, New Jersey 07733’.
+.I x y    no    no     Italicize x, append y; if no argument switch to italic.
+.IH      no    no     ‘Bell Laboratories, Naperville, Illinois 60540’
+.IM      no    no     Print document in BTL format for an internal memorandum. +Must be first.
+.IP x y no    yes    Start indented paragraph, with hanging tag x. Indentation +is y ens (default 5).
+.KE      -     yes    End keep. Put kept text on next page if not enough room.
+.KF      no    yes    Start floating keep. If the kept text must be moved +to the next page, float later text back to this page.
+.KS      no    yes    Start keeping following text.
+.LG      no    no     Make letters larger.
+.LP      yes    yes    Start left-blocked paragraph.
+.LT      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.
+.MF      -     -      Print document in BTL format for ‘Memorandum for File.’ +Must be first.
+.MH      -     no     ‘Bell Laboratories, Murray Hill, New Jersey 07974’.
+.MR      -     -      Print document in BTL format for ‘Memorandum for Record.’ +Must be first.
+.ND date troff no     Use date supplied (if any) only in special BTL +format positions; omit from page footer.
+.NH n     -     yes    Same as .SH, with automatic section numbers like ‘1.2.3’; +n is subsection level (default 1).
+.NL      yes    no     Make letters normal size.
+.P1      -     yes    Begin program display in constant width font.
+.P2      -     yes    End program display.
+.PE      -     yes    End picture; see pic(1).
+.PF      -     yes    End picture; restore vertical position.
+.PP      no    yes    Begin paragraph. First line indented.
+.PS h w -     yes    Start picture; height and width in inches.
+.PY      -     no     ‘Bell Laboratories, Piscataway, New Jersey 08854’
+.QE      -     yes    End quoted material.
+.QP      -     yes    Begin quoted paragraph (indent both margins).
+.QS      -     yes    Begin quoted material (indent both margins).
+.R       yes    no     Roman text follows.
+.RE      -     yes    End relative indent level.
+.RP      no    -      Cover sheet and first page for released paper. Must precede +other requests.
+.RS      -     yes    Start level of relative indentation from which subsequent +indentation is measured.
+.SG x     no    yes    Insert signature(s) of author(s), ignored except +in .TM and .LT. x is the reference line (initials of author and +typist). .}f
+.SH      -     yes    Section head follows, font automatically bold.
+.SM      no    no     Make letters smaller.
+.TA x... 5...    no     Set tabs in ens. Default is 5 10 15 ...
+.TE      -     yes    End table; see tbl(1).
+.TH      -     yes    End heading section of table.
+.TL      no    yes    Title follows.
+.TM x... 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.
+.TR x     -     -      Print in BTL technical report format; report number +is x. Must be first.
+.TS x     -     yes    Begin table; if x is H table heading is repeated on +new pages.
+.UL x     -     no     Underline argument (even in troff).
+.UX y z -     no     ‘zUNIXy’; first use gives registered trademark notice.
+.WH      -     no     ‘Bell Laboratories, Whippany, New Jersey 07981’.
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/plot.html b/man/man7/plot.html new file mode 100644 index 00000000..ca64b3fd --- /dev/null +++ b/man/man7/plot.html @@ -0,0 +1,386 @@ + +plot(7) - Plan 9 from User Space + + + + +
+
+
PLOT(7)PLOT(7) +
+
+

NAME
+ +
+ + plot – graphics interface
+ +
+

DESCRIPTION
+ +
+ + Files of this format are interpreted by plot(1) to draw graphics + on the screen. A plot file is a UTF stream of instruction lines. + Arguments are delimited by spaces, tabs, or commas. Numbers may + be floating point. Punctuation marks (except :) , spaces, and + tabs at the beginning of lines are ignored. Comments run from + : to newline. Extra letters appended to a valid instruction are + ignored. Thus ...line, line, li all mean the same thing. Arguments + are interpreted as follows:
+ 1.    If an instruction requires no arguments, the rest of the line + is ignored.
+ 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 \n.
+ 3.    Between numeric arguments alphabetic characters and punctuation + marks are ignored. Thus line from 5 6 to 7 8 draws a line from + (5, 6) to (7, 8).
+ 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).
+ +
+ + move 4.5 6.77
+ vec 5.8, 5.6 7.8
+ 4.55 10.0, 3.6 4.5, 6.77
+ +
+ + +
+ The instructions are executed in order. The last designated point + in a line, move, rmove, vec, rvec, arc, or point command becomes + the ‘current point’ (X,Y) for the next command.
+

Open & Close
+ o string   Open plotting device. For troff, string specifies the + size of the plot (default is 6i).
+ cl      Close plotting device.
+

Basic Plotting Commands
+ e       Start another frame of output.
+ m x y    (move) Current point becomes x y.
+ rm dx dyCurrent point becomes X+dx Y+dy.
+ poi x yPlot the point x y and make it the current point.
+ v x y    Draw a vector from the current point to x y.
+ rv dx dyDraw vector from current point to X+dx Y+dy
+ li x1 y1 x2 y2
+ +
+ + +
+ + Draw a line from x1 y1 to x2 y2. Make the current point x2 y2.
+ +
+ +
+ t string   Place the string so that its first character is centered + on the current point (default). If string begins with \C (\R), + it is centered (right-adjusted) on the current point. A backslash + at the beginning of the string may be escaped with another backslash.
+ a x1 y1 x2 y2 xc yc r
+ +
+ + +
+ + Draw a circular arc from x1 y1 to x2 y2 with center xc yc and + radius r. If the radius is positive, the arc is drawn counterclockwise; + negative, clockwise. The starting point is exact but the ending + point is approximate.
+ +
+ +
+ ci xc yc r
+ +
+ + +
+ + Draw a circle centered at xc yc with radius r. If the range and + frame parameters do not specify a square, the ‘circle’ will be + elliptical.
+ +
+ +
+ di xc yc r
+ +
+ + +
+ + Draw a disc centered at xc yc with radius r using the filling + color (see cfill below).
+ +
+ +
+ bo x1 y1 x2 y2
+ +
+ + +
+ + Draw a box with lower left corner at x1 y1 and upper right corner + at x2 y2.
+ +
+ +
+ sb x1 y1 x2 y2
+ +
+ + +
+ + Draw a solid box with lower left corner at x1 y1 and upper right + corner at x2 y2 using the filling color (see cfill below).
+ +
+ +
+ par x1 y1 x2 y2 xg yg
+ +
+ + +
+ + Draw a parabola from x1 y1 to x2 y2 ‘guided’ by xg yg. The parabola + passes through the midpoint of the line joining xg yg with the + midpoint of the line joining x1 y1 and x2 y2 and is tangent to + the lines from xg yg to the endpoints.
+ +
+ +
+ pol { {x1 y1 ... xn yn} ... {X1 Y1 ... Xm Ym} }
+ +
+ + +
+ + Draw polygons with vertices x1 y1 ... xn yn and X1 Y1 ... Xm Ym. + If only one polygon is specified, the inner brackets are not needed.
+ +
+ +
+ fi { {x1 y1 ... xn yn} ... {X1 Y1 ... Xm Ym} }
+ +
+ + +
+ + Fill a polygon. The arguments are the same as those for 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.
+ +
+ +
+ sp { {x1 y1 ... xn yn} ... {X1 Y1 ... Xm Ym} }
+ +
+ + +
+ + Draw a parabolic spline guided by x1 y1 ... xn yn with simple + endpoints.
+ +
+ +
+ fsp { {x1 y1 ... xn yn} ... {X1 Y1 ... Xm Ym} }
+ +
+ + +
+ + Draw a parabolic spline guided by x1 y1 ... xn yn with double + first endpoint.
+ +
+ +
+ lsp { {x1 y1 ... xn yn} ... {X1 Y1 ... Xm Ym} }
+ +
+ + +
+ + Draw a parabolic spline guided by x1 y1 ... xn yn with double + last endpoint.
+ +
+ +
+ dsp { {x1 y1 ... xn yn} ... {X1 Y1 ... Xm Ym} }
+ +
+ + +
+ + Draw a parabolic spline guided by x1 y1 ... xn yn with double + endpoints.
+ +
+ +
+ csp { {x1 y1 ... xn yn} ... {X1 Y1 ... Xm Ym} }
+ in filename
+ +
+ + +
+ + (include) Take commands from filename.
+ +
+ +
+ de string { commands }
+ +
+ + +
+ + Define string as commands.
+ +
+ +
+ ca string scale
+ +
+ + +
+ + Invoke commands defined as string applying scale to all coordinates.
+ +
+ +
+

Commands Controlling the Environment
+ co string
+ +
+ + +
+ + Use color given by first character of string, one of red, yellow, + green, blue, cyan, magenta, white, and kblack. If string begins + with a digit, it is taken to be a 32-bit number specifying 8 bit + each of red, green, blue, and alpha. For example, 0xFFFF00FF denotes + solid yellow. + +
+ +
+ pe string
+ +
+ + +
+ + Use string as the style for drawing lines. The available pen styles + are: solid, dott[ed], short, long, dotd[ashed], cdash, ddash
+ +
+ +
+ cf string
+ +
+ + +
+ + Color for filling (see co, above).
+ +
+ +
+ ra x1 y1 x2 y2
+ +
+ + +
+ + The data will fall between x1 y1 and x2 y2. The plot will be magnified + or reduced to fit the device as closely as possible.
+ Range settings that exactly fill the plotting area with unity + scaling appear below for devices supported by the filters of 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. + +
+ +
+ fr px1 py1 px2 py2
+ +
+ + +
+ + Plot the data in the fraction of the display specified by px1 + py1 for lower left corner and px2 py2 for upper right corner. + Thus frame .5 0 1. .5 plots in the lower right quadrant of the + display; frame 0. 1. 1. 0. uses the whole display but inverts + the y coordinates.
+ +
+ +
+ sa      Save the current environment, and move to a new one. The new + environment inherits the old one. There are 7 levels.
+ re      Restore previous environment.
+ +

+

SEE ALSO
+ +
+ + plot(1), graph(1)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/plumb.html b/man/man7/plumb.html new file mode 100644 index 00000000..eca67a76 --- /dev/null +++ b/man/man7/plumb.html @@ -0,0 +1,357 @@ + +plumb(7) - Plan 9 from User Space + + + + +
+
+
PLUMB(7)PLUMB(7) +
+
+

NAME
+ +
+ + plumb – format of plumb messages and rules
+ +
+

SYNOPSIS
+ +
+ + #include <plumb.h>
+ +
+

DESCRIPTION
+ +
+ +

Message format
+ The messages formed by the plumb(3) library are formatted for + transmission between processes into textual form, using newlines + to separate the fields. Only the data field may contain embedded + newlines. The fields occur in a specified order, and each has + a name, corresponding to the elements of the Plumbmsg + structure, that is used in the plumbing rules. The fields, in + order, are:
+ +
+ + src     application/service generating message
+ dst     destination ‘port’ for message
+ wdir    working directory (used if data is a file name)
+ type    form of the data, e.g. text
+ attr    attributes of the message, in 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)
+ ndata   number of bytes of data
+ data    the data itself
+ +
+ At the moment, only textual data (type=text) is supported. +
+ + All fields are optional, but type should usually be set since + it describes the form of the data, and ndata must be an accurate + count (possibly zero) of the number of bytes of data. A missing + field is represented by an empty line.
+

Plumbing rules
+ The plumber (see plumb(1)) receives messages on its send port + (applications 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 /usr/$user/lib/plumbing, + which defines a set of pattern/action + rules with which to analyze, rewrite, and dispatch received messages. + +
+ + 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 plumb 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 # character + are commentary and are regarded as blank lines. +
+ + A line of the form
+ +
+ + include file
+ +
+ substitutes the contents of file for the line, much as in a C + #include statement. Unlike in C, the file name is not quoted. + If file is not an absolute path name, or one beginning ./ or ../, + file is looked for first in the directory in which the plumber + is executing, and then in /sys/lib/plumb. +
+ + When a message is received by the 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 dst field that specifies an existing port, + in which case the message is emitted, unchanged, from there. +
+ + Patterns and actions all consist of three components: an object, + a 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. +
+ + The object in a pattern is the name of an element of the message, + such as src or data, or the special case arg, which refers to + the argument component of the current rule. The object in an action + is always the word plumb. +
+ + 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.
+ +
+ + add      The object must be attr. Append the argument, which must be + a sequence of name=value pairs, to the list of attributes of the + message.
+ delete   The object must be 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.)
+ is       If the text of the object is identical to the text of the argument, + the rule matches.
+ isdir    If the text of the object is the name of an existing directory, + the rule matches and sets the variable $dir to that directory + name.
+ isfile   If the text of the object is the name of an existing file + (not a directory), the rule matches and sets the variable $file + to that file name.
+ matchesIf 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.
+ set      The value of the object is set to the value of the argument.
+ +
+ + +
+ The 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 data matches rule requires that the entire text + matches the regular expression. If, however, the message has an + attribute named 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 click attribute (a + number starting from 0) to indicate where in the textual data + the user pointed. +
+ + When the message has a click attribute, the data matches rules + extract the longest leftmost match to the regular expression that + contains or abuts the textual location identified by the 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:
+ +
+ + data matches '[a−zA−Z0−9_–./]+'
+ data matches '([a−zA−Z0−9_–./]+).(jpe?g|gif|bit|ps|pdf)'
+ +
+ 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, .jpeg. If only the second pattern + were present, a piece of text horse.gift could be misinterpreted + as an image file named horse.gif. +
+ + If a click attribute is specified in a message, it will be deleted + by the plumber before sending the message if the data matches + rules expand the selection. +
+ + The action rules all have the object plumb. There are only three + verbs for action rules:
+ +
+ + 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 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.)
+ client   If no application has the port open, the arguments to a + plumb 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.
+ start    Like client, but the message is discarded. Only one start + or client rule should be specified in a rule set.
+ +
+ + +
+ The arguments to all rules may contain quoted strings, exactly + as in rc(1). They may also contain simple string variables, identified + by a leading dollar sign $. Variables may be set, between rule + sets, by assignment statements in the style of rc. Only one variable + assignment may appear on a line. The plumber also + maintains some built-in variables:
+ +
+ + $0      The text that matched the entire regular expression in a previous + data matches rule. $1, $2, etc. refer to text matching the first, + second, etc. parenthesized subexpression.
+ $attr   The textual representation of the attributes of the message.
+ $data   The contents of the data field of the message.
+ $dir    The directory name resulting from a successful isdir rule. + If no such rule has been applied, it is the string constructed + syntactically by interpreting data as a file name in wdir.
+ $dst    The contents of the dst field of the message.
+ $file   The file name resulting from a successful isfile rule. If + no such rule has been applied, it is the string constructed syntactically + by interpreting data as a file name in wdir.
+ $type   The contents of the type field of the message.
+ $src    The contents of the src field of the message.
+ $wdir   The contents of the wdir field of the message.
+ $plan9The root directory of the Plan 9 tree (see get9root(3)).
+ +
+ +

+

EXAMPLE
+ +
+ + The following is a modest, representative file of plumbing rules.
+ # 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_?,%#~&/\−]+'
+ file='([:.][a−zA−Z0−9_?,%#~&/\−]+)*'
+ # image files go to page
+ type is text
+ data matches '[a−zA−Z0−9_\−./]+'
+ data matches '([a−zA−Z0−9_\−./]+).(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_/\−])('$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]+\.h)('$addr')?'
+ arg isfile /sys/include/$1
+ data set $file
+ attr add addr=$3
+ plumb to edit
+ plumb start window sam $file
+ +
+ + The following simple plumbing rules file is a good beginning set + of rules.
+ # to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules
+ editor = acme
+ # or editor = sam
+ include basic
+ +
+

FILES
+ +
+ + $HOME/lib/plumbing   default rules file.
+ plumb               service name for plumber(4).
+ /usr/local/plan9/plumb
+ +
+ + +
+ + directory for include files.
+ +
+ +
+ /usr/local/plan9/plumb/fileaddr
+ +
+ + +
+ + public macro definitions.
+ +
+ +
+ /usr/local/plan9/plumb/basic
+ +
+ + +
+ + basic rule set.
+ +
+ +
+ +
+

SEE ALSO
+ +
+ + plumb(1), plumb(3), plumber(4), regexp(7)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/regexp.html b/man/man7/regexp.html new file mode 100644 index 00000000..1bc2c74e --- /dev/null +++ b/man/man7/regexp.html @@ -0,0 +1,131 @@ + +regexp(7) - Plan 9 from User Space + + + + +
+
+
REGEXP(7)REGEXP(7) +
+
+

NAME
+ +
+ + regexp – Plan 9 regular expression notation
+ +
+

DESCRIPTION
+ +
+ + This manual page describes the regular expression syntax used + by the Plan 9 regular expression library regexp(3). It is the + form used by egrep(1) before egrep got complicated. +
+ + A regular expression specifies a set of strings of characters. + A member of this set of strings is said to be matched by the regular + expression. In many applications a delimiter character, commonly + /, bounds a regular expression. In the following specification + for regular expressions the word ‘character’ means any + character (rune) but newline. +
+ + The syntax for a regular expression e0 is
+ +
+ + e3:    literal | charclass | '.' | '^' | '$' | '(' e0 ')'
+ e2:    e3
+ +
+ + |    e2 REP
+ +
+ REP: '*' | '+' | '?'
+ e1:    e2
+ +
+ + |    e1 e2
+ +
+ e0:    e1
+ +
+ + |    e0 '|' e1
+ +
+ +
+ +
+ + + +
+ +
+ A literal is any non-metacharacter, or a metacharacter (one of + .*+?[]()|\^$), or the delimiter preceded by \. +
+ + A charclass is a nonempty string s bracketed [s] (or [^s]); it + matches any character in (or not in) s. A negated character class + never matches newline. A substring a−b, with a and b in ascending + order, stands for the inclusive range of characters between a + and b. In s, the metacharacters −, ], an initial ^, and the + regular expression delimiter must be preceded by a \; other metacharacters + have no special meaning and may appear unescaped. +
+ + A . matches any character. +
+ + A ^ matches the beginning of a line; $ matches the end of the + line. +
+ + The REP operators match zero or more (*), one or more (+), zero + or one (?), instances respectively of the preceding regular expression + e2. +
+ + A concatenated regular expression, e1e2, matches a match to e1 + followed by a match to e2. +
+ + An alternative regular expression, e0|e1, matches either a match + to e0 or a match to e1. +
+ + 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.
+ +
+

SEE ALSO
+ +
+ + regexp(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/thumbprint.html b/man/man7/thumbprint.html new file mode 100644 index 00000000..eccbe595 --- /dev/null +++ b/man/man7/thumbprint.html @@ -0,0 +1,68 @@ + +thumbprint(7) - Plan 9 from User Space + + + + +
+
+
THUMBPRINT(7)THUMBPRINT(7) +
+
+

NAME
+ +
+ + thumbprint – public key thumbprints
+ +
+

DESCRIPTION
+ +
+ + +
+ + Applications in Plan 9 that use public keys for authentication, + for example by calling tlsClient and okThumbprint (see pushtls(3)), + check the remote side’s public key by comparing against thumbprints + from a trusted list. The list is maintained by people who set + local policies about which servers can be trusted + for which applications, thereby playing the role taken by certificate + authorities in PKI-based systems. By convention, these lists are + stored as files in /sys/lib/tls/ and protected by normal file + system permissions. +
+ + Such a thumbprint file comprises lines made up of attribute/value + pairs of the form attr=value or attr. The first attribute must + be x509 and the second must be sha1={hexchecksumofbinarycertificate}. + All other attributes are treated as comments. The file may also + contain lines of the form #includefile +
+ + For example, a web server might have thumbprint
+ x509 sha1=8fe472d31b360a8303cd29f92bd734813cbd923c cn=*.cs.bell−labs.com
+ +
+

SEE ALSO
+ +
+ + pushtls(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man7/utf.html b/man/man7/utf.html new file mode 100644 index 00000000..a1e767ec --- /dev/null +++ b/man/man7/utf.html @@ -0,0 +1,96 @@ + +utf(7) - Plan 9 from User Space + + + + +
+
+
UTF(7)UTF(7) +
+
+

NAME
+ +
+ + UTF, Unicode, ASCII, rune – character set and format
+ +
+

DESCRIPTION
+ +
+ + The Plan 9 character set and representation are based on the Unicode + Standard and on the ISO multibyte UTF-8 encoding (Universal Character + Set Transformation Format, 8 bits wide). The Unicode Standard + represents its characters in 16 bits; UTF-8 represents such values + in an 8-bit byte stream. Throughout this + manual, UTF-8 is shortened to UTF. +
+ + In Plan 9, a 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 UTF. +
+ + UTF is designed so the 7-bit 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. +
+ + The UTF encoding of the Unicode Standard is backward compatible + with ASCII: programs presented only with ASCII work on Plan 9 + even if not written to deal with UTF, as do programs that deal + with uninterpreted byte streams. However, programs that perform + semantic processing on ASCII graphic characters must convert + from UTF to runes in order to work properly with non-ASCII input. + See rune(3). +
+ + Letting numbers be binary, a rune x is converted to a multibyte + UTF sequence as follows: +
+ + 01. x in [00000000.0bbbbbbb] → 0bbbbbbb
+ 10. x in [00000bbb.bbbbbbbb] → 110bbbbb, 10bbbbbb
+ 11. x in [bbbbbbbb.bbbbbbbb] → 1110bbbb, 10bbbbbb, 10bbbbbb
+ +
+ + Conversion 01 provides a one-byte sequence that spans the 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. +
+ + In the inverse mapping, any sequence except those described above + is incorrect and is converted to rune hexadecimal 0080.
+ +
+

SEE ALSO
+ +
+ + ascii(1), tcs(1), rune(3), The Unicode Standard.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/attach.html b/man/man9/attach.html new file mode 100644 index 00000000..fda46be2 --- /dev/null +++ b/man/man9/attach.html @@ -0,0 +1,107 @@ + +attach(9P) - Plan 9 from User Space + + + + +
+
+
ATTACH(9P)ATTACH(9P) +
+
+

NAME
+ +
+ + attach, auth – messages to establish a connection
+ +
+

SYNOPSIS
+ +
+ + size[4] Tauth tag[2] afid[4] uname[s] aname[s]
+ size[4] Rauth tag[2] aqid[13] +
+ + size[4] Tattach tag[2] fid[4] afid[4] uname[s] aname[s]
+ size[4] Rattach tag[2] qid[13]
+ +
+

DESCRIPTION
+ +
+ + +
+ + The attach message serves as a fresh introduction from a user + on the client machine to the server. The message identifies the + user (uname) and may select the file tree to access (aname). The + afid argument specifies a fid previously established by an auth + message, as described below. +
+ + As a result of the attach transaction, the client will have a + connection to the root directory of the desired file tree, represented + by fid. An error is returned if fid is already in use. The server’s + idea of the root of the file tree is represented by the returned + qid. +
+ + If the client does not wish to authenticate the connection, or + knows that authentication is not required, the afid field in the + attach message should be set to NOFID, defined as (u32int)~0 in + <fcall.h>. If the client does wish to authenticate, it must acquire + and validate an afid using an auth message before + doing the attach. +
+ + The auth message contains afid, a new fid to be established for + authentication, and the uname and aname that will be those of + the following attach message. If the server does not require authentication, + it returns Rerror to the Tauth message. +
+ + If the server does require authentication, it returns aqid defining + a file of type QTAUTH (see intro(9P)) that may be read and written + (using read and write messages in the usual way) to execute an + authentication protocol. That protocol’s definition is not part + of 9P itself. +
+ + Once the protocol is complete, the same afid is presented in the + attach message for the user, granting entry. The same validated + afid may be used for multiple attach messages with the same uname + and aname.
+ +
+

ENTRY POINTS
+ +
+ + Fsmount and fsauth (see 9pclient(3)) generate attach and auth + transactions.
+ +
+

SEE ALSO
+ +
+ + 9pclient(3), version(9P), Plan 9’s authsrv(6)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/clunk.html b/man/man9/clunk.html new file mode 100644 index 00000000..34aa001f --- /dev/null +++ b/man/man9/clunk.html @@ -0,0 +1,66 @@ + +clunk(9P) - Plan 9 from User Space + + + + +
+
+
CLUNK(9P)CLUNK(9P) +
+
+

NAME
+ +
+ + clunk – forget about a fid
+ +
+

SYNOPSIS
+ +
+ + size[4] Tclunk tag[2] fid[4]
+ size[4] Rclunk tag[2]
+ +
+

DESCRIPTION
+ +
+ + The clunk request informs the file server that the current file + represented by fid is no longer needed by the client. The actual + file is not removed on the server unless the fid had been opened + with ORCLOSE. +
+ + Once a fid has been clunked, the same fid can be reused in a new + walk or attach request. +
+ + Even if the clunk returns an error, the fid is no longer valid.
+ +
+

ENTRY POINTS
+ +
+ + Clunk transactions are generated by fsclose and fsunmount (see + 9pclient(3)) and indirectly by other actions such as failed fsopen + calls.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/error.html b/man/man9/error.html new file mode 100644 index 00000000..ed8b9c6c --- /dev/null +++ b/man/man9/error.html @@ -0,0 +1,53 @@ + +error(9P) - Plan 9 from User Space + + + + +
+
+
ERROR(9P)ERROR(9P) +
+
+

NAME
+ +
+ + error – return an error
+ +
+

SYNOPSIS
+ +
+ + size[4] Rerror tag[2] ename[s]
+ +
+

DESCRIPTION
+ +
+ + The Rerror message (there is no 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. +
+ + By convention, clients may truncate error messages after ERRMAX−1 + bytes; ERRMAX is defined in <libc.h>.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/flush.html b/man/man9/flush.html new file mode 100644 index 00000000..20544557 --- /dev/null +++ b/man/man9/flush.html @@ -0,0 +1,98 @@ + +flush(9P) - Plan 9 from User Space + + + + +
+
+
FLUSH(9P)FLUSH(9P) +
+
+

NAME
+ +
+ + flush – abort a message
+ +
+

SYNOPSIS
+ +
+ + size[4] Tflush tag[2] oldtag[2]
+ size[4] Rflush tag[2]
+ +
+

DESCRIPTION
+ +
+ + When the response to a request is no longer needed, such as when + a user interrupts a process doing a read(9p), a Tflush request + is sent to the server to purge the pending response. The message + being flushed is identified by oldtag. The semantics of flush + depends on messages arriving in order. +
+ + The server should answer the flush message immediately. If it + recognizes 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 Rflush echoing the tag (not oldtag) + of the Tflush message. A Tflush can never be + responded to by an Rerror message. +
+ + The server may respond to the pending request before responding + to the Tflush. It is possible for a client to send multiple Tflush + messages for a particular pending request. Each subsequent Tflush + must contain as oldtag the tag of the pending request (not a previous + Tflush). Should multiple Tflushes be + received for a pending request, they must be answered in order. + A Rflush for any of the multiple Tflushes 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. +
+ + When the client sends a Tflush, it must wait to receive the corresponding + Rflush before reusing oldtag for subsequent messages. If a response + to the flushed request is received before the 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, Tcreate may have created a + file and Twalk may have allocated a fid. If no response is received + before the Rflush, the flushed transaction is considered to have + been canceled, and should be treated as though it had never been + sent. +
+ + 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 Tflush, and flushing + an invalid tag.
+ +
+

ENTRY POINTS
+ +
+ + The 9pclient(3) library does not generate flush transactions.. + 9pserve(4) generates flush transactions to cancel transactions + pending when a client hangs up.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/index.html b/man/man9/index.html new file mode 100644 index 00000000..76fb6bdb --- /dev/null +++ b/man/man9/index.html @@ -0,0 +1,69 @@ + + +Manual Section 9 - Plan 9 from User Space + + + +
+
+ +
+
+
+ Manual Section 9 - Plan 9 from User Space +
+
+
intro(9P)intro – introduction to the Plan 9 File Protocol, 9P +
+
+
+
attach(9P)attach, auth – messages to establish a connection +
+
+
+
clunk(9P)clunk – forget about a fid +
+
+
+
error(9P)error – return an error +
+
+
+
flush(9P)flush – abort a message +
+
+
+
open(9P)open, create – prepare a fid for I/O on an existing or new file +
+
+
+
read(9P)read, write – transfer data from and to a file +
+
+
+
remove(9P)remove – remove a file from a server +
+
+
+
stat(9P)stat, wstat – inquire or change file attributes +
+
+
+
version(9P)version – negotiate protocol version +
+
+
+
walk(9P)walk – descend a directory hierarchy +
+
+ +
+
+
+Space Glenda +
+
+		 +
+ + diff --git a/man/man9/intro.html b/man/man9/intro.html new file mode 100644 index 00000000..226a94eb --- /dev/null +++ b/man/man9/intro.html @@ -0,0 +1,344 @@ + +intro(9P) - Plan 9 from User Space + + + + +
+
+
INTRO(9P)INTRO(9P) +
+
+

NAME
+ +
+ + intro – introduction to the Plan 9 File Protocol, 9P
+ +
+

SYNOPSIS
+ +
+ + #include <fcall.h>
+ +
+

DESCRIPTION
+ +
+ + A Plan 9 server is an agent that provides one or more hierarchical + file systems -- file trees -- that may be accessed by Plan 9 processes. + A server responds to requests by 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 file server. Another possibility for a server is + to synthesize files on demand, perhaps based on information on + data structures maintained in memory; the plumber(4) server is + an example of such a server. +
+ + A 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. +
+ + The Plan 9 File Protocol, 9P, is used for messages between clients + and servers. A client transmits requests (T-messages) to a server, + which subsequently returns replies (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 + transaction of that type. +
+ + 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, n, followed by 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 utf(7)). Text strings in 9P + messages are not NUL-terminated: n counts the bytes of UTF-8 data, + which include no final zero byte. The NUL character is illegal + in all text strings in 9P, and is therefore excluded from file + names, user names, and so on. +
+ + 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 <fcall.h>. + The next two bytes are an identifying 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 parameter[n] + where n is not a constant represents a variable-length parameter: + n[2] followed by n bytes of data forming the parameter. The + notation string[s] (using a literal s character) is shorthand + for s[2] followed by 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; fcall(3) describes routines + that convert to and from this form into a machine-dependent C + structure.
+ +
+

MESSAGES
+ +
+ + +
+ + size[4] Tversion tag[2] msize[4] version[s]
+ size[4] Rversion tag[2] msize[4] version[s]
+ size[4] Tauth tag[2] afid[4] uname[s] aname[s]
+ size[4] Rauth tag[2] aqid[13]
+ size[4] Rerror tag[2] ename[s]
+ size[4] Tflush tag[2] oldtag[2]
+ size[4] Rflush tag[2]
+ size[4] Tattach tag[2] fid[4] afid[4] uname[s] aname[s]
+ size[4] Rattach tag[2] qid[13]
+ size[4] Twalk tag[2] fid[4] newfid[4] nwname[2] nwname*(wname[s])
+ size[4] Rwalk tag[2] nwqid[2] nwqid*(wqid[13])
+ size[4] Topen tag[2] fid[4] mode[1]
+ size[4] Ropen tag[2] qid[13] iounit[4]
+ size[4] Topenfd tag[2] fid[4] mode[1]
+ size[4] Ropenfd tag[2] qid[13] iounit[4] unixfd[4]
+ size[4] Tcreate tag[2] fid[4] name[s] perm[4] mode[1]
+ size[4] Rcreate tag[2] qid[13] iounit[4]
+ size[4] Tread tag[2] fid[4] offset[8] count[4]
+ size[4] Rread tag[2] count[4] data[count]
+ size[4] Twrite tag[2] fid[4] offset[8] count[4] data[count]
+ size[4] Rwrite tag[2] count[4]
+ size[4] Tclunk tag[2] fid[4]
+ size[4] Rclunk tag[2]
+ size[4] Tremove tag[2] fid[4]
+ size[4] Rremove tag[2]
+ size[4] Tstat tag[2] fid[4]
+ size[4] Rstat tag[2] stat[n]
+ size[4] Twstat tag[2] fid[4] stat[n]
+ size[4] Rwstat tag[2] +
+ + +
+ Each T-message has a 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 NOTAG, defined as (ushort)~0 in <fcall.h>: the + client can use it, when establishing a connection, to override + tag matching in version messages. +
+ + The type of an R-message will either be one greater than the type + of the corresponding T-message or Rerror, indicating that the + request failed. In the latter case, the ename field contains a + string describing the reason for failure. +
+ + The 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 version requests + is called a session. +
+ + Most T-messages contain a 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 stat(3) calls, and so on -- all files being + manipulated by the operating system -- 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. +
+ + The fid supplied in an attach message will be taken by the server + to refer to the root of the served file tree. The 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). +
+ + Permission to attach to the service is proven by providing a special + fid, called afid, in the attach message. This afid is established + by exchanging auth messages and subsequently manipulated using + read and write messages to exchange authentication information + not defined explicitly by 9P. Once the + authentication protocol is complete, the afid is presented in + the attach to permit the user to access the service. +
+ + A 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. Walk returns a new fid that + refers to the resulting file. Usually, a client maintains a fid + for the root, and navigates by walks from the root fid. +
+ + 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. + +
+ + Replies (R-messages) to auth, attach, walk, open, and create requests + convey a 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 version, + then the eight-byte qid 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. +
+ + An existing file can be opened, or a new file may be 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 read and write. +
+ + A client should clunk any fid that is no longer needed. The remove + transaction deletes files. +
+ + Openfd is an extension used by Unix utilities to allow traditional + Unix programs to have their input or output attached to fids on + 9P servers. See openfd(9p) and 9pclient(3) for details. +
+ + The stat transaction retrieves information about the file. The + 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 + stat(3)). The owner and group identifications are textual + names. The wstat transaction allows some of a file’s properties + to be changed. +
+ + A request can be aborted with a flush request. When a server receives + a Tflush, it should not reply to the message with tag oldtag (unless + it has already replied), and it should immediately send an Rflush. + The client must wait until it gets the Rflush (even if the reply + to the original message arrives in the interim), + at which point oldtag may be reused. +
+ + 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 Rstat of the file or 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 + Rerror message should be truncated if necessary, since the string + is only advisory and in some sense arbitrary. +
+ + Most programs do not see the 9P protocol directly; on Plan 9, + calls to library routines that access files are translated by + the kernel’s mount driver into 9P messages.
+

Unix
+ On Unix, 9P services are posted as Unix domain sockets in a well-known + directory (see getns(3) and 9pserve(4)). Clients connect to these + servers using a 9P client library (see 9pclient(3)).
+ +

+

DIRECTORIES
+ +
+ + Directories are created by create with DMDIR set in the permissions + argument (see stat(9P)). The members of a directory can be found + with read(9P). All directories must support walks to the directory + .. (dot-dot) meaning parent directory, although by convention + directories contain no explicit entry for .. or . + (dot). The parent of the root directory of a server’s tree is + itself.
+ +
+

ACCESS PERMISSIONS
+ +
+ + This section describes the access permission conventions implemented + by most Plan 9 file servers. These conventions are not enforced + by the protocol and may differ between servers, especially servers + built on top of foreign operating systems. +
+ + 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 + group leader who has special privileges (see stat(9P) and Plan + 9’s users(6)). Every file request has an implicit user id (copied + from the original attach) and an implicit set of groups (every + group of which the user is a member). +
+ + Each file has an associated owner and 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 + walk in a directory is regarded as executing the directory, not + reading it. Permissions are kept in the low-order bits of the + file 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. +
+ + The file mode contains some additional attributes besides the + permissions. If bit 31 (DMDIR) is set, the file is a directory; + if bit 30 (DMAPPEND) is set, the file is append-only (offset is + ignored in writes); if bit 29 (DMEXCL) is set, the file is exclusive-use + (only one client may have it open at a time); if bit 27 (DMAUTH) + is + set, the file is an authentication file established by auth messages; + if bit 26 (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: QTDIR, QTAPPEND, QTEXCL, + (skipping one bit) QTAUTH, and QTTMP. The name QTFILE, defined + to be zero, identifies the value of the type for a plain file.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/open.html b/man/man9/open.html new file mode 100644 index 00000000..b893119b --- /dev/null +++ b/man/man9/open.html @@ -0,0 +1,154 @@ + +open(9P) - Plan 9 from User Space + + + + +
+
+
OPEN(9P)OPEN(9P) +
+
+

NAME
+ +
+ + open, create – prepare a fid for I/O on an existing or new file
+ +
+

SYNOPSIS
+ +
+ + size[4] Topen tag[2] fid[4] mode[1]
+ size[4] Ropen tag[2] qid[13] iounit[4] +
+ + size[4] Tcreate tag[2] fid[4] name[s] perm[4] mode[1]
+ size[4] Rcreate tag[2] qid[13] iounit[4]
+ +
+

DESCRIPTION
+ +
+ + The open request asks the file server to check permissions and + prepare a fid for I/O with subsequent read and write messages. + The mode field determines the type of I/O: 0 (called OREAD in + <libc.h>), 1 (OWRITE), 2 (ORDWR), and 3 (OEXEC) mean read access, + write access, read and write access, and execute + access, to be checked against the permissions for the file. In + addition, if mode has the OTRUNC (0x10) bit set, the file is to + be truncated, which requires write permission (if the file is + append-only, and permission is granted, the open succeeds but + the file will not be truncated); if the mode has the ORCLOSE (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 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 stat(9P)), only one client can have + the + file open at any time. That is, after such a file has been opened, + further opens will fail until fid has been clunked. All these + permissions are checked at the time of the open request; subsequent + changes to the permissions of files do not affect the ability + to read, write, or remove an open file. +
+ + The create request asks the file server to create a new file with + the name supplied, in the directory (dir) represented by 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 dir, and the permissions are the value of + +
+ + +
+ + perm & (~0666 | (dir.perm & 0666))
+ +
+ +
+ if a regular file is being created and
+ +
+ + +
+ + perm & (~0777 | (dir.perm & 0777))
+ +
+ +
+ if a directory is being created. This means, for example, that + if the create allows read permission to others, but the containing + directory does not, then the created file will not allow others + to read the file. +
+ + Finally, the newly created file is opened according to mode, and + fid will represent the newly opened file. Mode is not checked + against the permissions in perm. The qid for the new file is returned + with the create reply message. +
+ + Directories are created by setting the DMDIR bit (0x80000000) + in the perm. +
+ + The names . and .. are special; it is illegal to create files + with these names. +
+ + It is an error for either of these messages if the fid is already + the product of a successful open or create message. +
+ + An attempt to create a file in a directory where the given name + already exists will be rejected; in this case, the fscreate call + (see 9pclient(3)) uses open with truncation. The algorithm used + by the create system call is: first walk to the directory to contain + the file. If that fails, return an error. Next walk to the + specified file. If the walk succeeds, send a request to open and + truncate the file and return the result, successful or not. If + the 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 walk and open again. + +
+

ENTRY POINTS
+ +
+ + Fsopen and fscreate (see 9pclient(3)) both generate open messages; + only fscreate generates a create message. The iounit associated + with an open file may be discovered by calling fsiounit. +
+ + For programs that need atomic file creation, without the race + that exists in the open−create sequence described above, fscreate + does the following. If the OEXCL (0x1000) bit is set in the mode + for a fscreate call, the open message is not sent; the kernel + issues only the create. Thus, if the file exists, fscreate + will draw an error, but if it doesn’t and the fscreate call succeeds, + the process issuing the fscreate is guaranteed to be the one that + created the file.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/read.html b/man/man9/read.html new file mode 100644 index 00000000..c524d8de --- /dev/null +++ b/man/man9/read.html @@ -0,0 +1,96 @@ + +read(9P) - Plan 9 from User Space + + + + +
+
+
READ(9P)READ(9P) +
+
+

NAME
+ +
+ + read, write – transfer data from and to a file
+ +
+

SYNOPSIS
+ +
+ + size[4] Tread tag[2] fid[4] offset[8] count[4]
+ size[4] Rread tag[2] count[4] data[count] +
+ + size[4] Twrite tag[2] fid[4] offset[8] count[4] data[count]
+ size[4] Rwrite tag[2] count[4]
+ +
+

DESCRIPTION
+ +
+ + The read request asks for count bytes of data from the file identified + by fid, which must be opened for reading, starting offset bytes + after the beginning of the file. The bytes are returned with the + read reply message. +
+ + The count field in the reply indicates the number of bytes returned. + This may be less than the requested amount. If the offset field + is greater than or equal to the number of bytes in the file, a + count of zero will be returned. +
+ + For directories, read returns an integral number of directory + entries exactly as in stat (see stat(9P)), one for each member + of the directory. The read request message must have offset equal + to zero or the value of offset in the previous read on the directory, + plus the number of bytes returned in the previous + read. In other words, seeking other than to the beginning is illegal + in a directory. +
+ + The write request asks that count bytes of data be recorded in + the file identified by fid, which must be opened for writing, + starting 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 offset. Directories may not be written. +
+ + The write reply records the number of bytes actually written. + It is usually an error if this is not the same as requested. +
+ + Because 9P implementations may limit the size of individual messages, + more than one message may be produced by a single read or write + call. The iounit field returned by open(9P), if non-zero, reports + the maximum size that is guaranteed to be transferred atomically.
+ +
+

ENTRY POINTS
+ +
+ + Fsread and fswrite (see 9pclient(3)) generate the corresponding + messages. Because they take an offset parameter, the fspread and + fspwrite calls correspond more directly to the 9P messages. Although + fsseek affects the offset, it does not generate a message.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/remove.html b/man/man9/remove.html new file mode 100644 index 00000000..162db8bc --- /dev/null +++ b/man/man9/remove.html @@ -0,0 +1,70 @@ + +remove(9P) - Plan 9 from User Space + + + + +
+
+
REMOVE(9P)REMOVE(9P) +
+
+

NAME
+ +
+ + remove – remove a file from a server
+ +
+

SYNOPSIS
+ +
+ + size[4] Tremove tag[2] fid[4]
+ size[4] Rremove tag[2]
+ +
+

DESCRIPTION
+ +
+ + The remove request asks the file server both to remove the file + represented by fid and to clunk the fid, even if the remove fails. + This request will fail if the client does not have write permission + in the parent directory. +
+ + It is correct to consider remove to be a clunk with the side effect + of removing the file if permissions allow. +
+ + If a file has been opened as multiple fids, possibly on different + connections, and one fid is used to remove the file, whether the + other fids continue to provide access to the file is implementation-defined. + The Plan 9 file servers remove the file immediately: attempts + to use the other fids will yield a “phase error.” U9fs + follows the semantics of the underlying Unix file system, so other + fids typically remain usable.
+ +
+

ENTRY POINTS
+ +
+ + Fsremove (see 9pclient(3)) generates remove messages.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/stat.html b/man/man9/stat.html new file mode 100644 index 00000000..eb5c9c4a --- /dev/null +++ b/man/man9/stat.html @@ -0,0 +1,258 @@ + +stat(9P) - Plan 9 from User Space + + + + +
+
+
STAT(9P)STAT(9P) +
+
+

NAME
+ +
+ + stat, wstat – inquire or change file attributes
+ +
+

SYNOPSIS
+ +
+ + size[4] Tstat tag[2] fid[4]
+ size[4] Rstat tag[2] stat[n] +
+ + size[4] Twstat tag[2] fid[4] stat[n]
+ size[4] Rwstat tag[2]
+ +
+

DESCRIPTION
+ +
+ + The stat transaction inquires about the file identified by fid. + The reply will contain a machine-independent directory entry, + stat, laid out as follows:
+ size[2]total byte count of the following data
+ type[2]
+ +
+ + for kernel use
+ +
+ dev[4]for kernel use
+ qid.type[1]
+ +
+ + the type of the file (directory, etc.), represented as a bit vector + corresponding to the high 8 bits of the file’s mode word.
+ +
+ qid.vers[4]
+ +
+ + version number for given path
+ +
+ qid.path[8]
+ +
+ + the file server’s unique identification for the file
+ +
+ mode[4]
+ +
+ + permissions and flags
+ +
+ atime[4]
+ +
+ + last access time
+ +
+ mtime[4]
+ +
+ + last modification time
+ +
+ length[8]
+ +
+ + length of file in bytes
+ +
+ name[ s ]
+ +
+ + file name; must be / if the file is the root directory of the + server
+ +
+ uid[ s ]
+ +
+ + owner name
+ +
+ gid[ s ]
+ +
+ + group name
+ +
+ muid[ s ]
+ +
+ + name of the user who last modified the file +
+ + +
+ Integers in this encoding are in little-endian order (least significant + byte first). The convM2D and convD2M routines (see fcall(3)) convert + between directory entries and a C structure called a Dir. +
+ + The mode contains permission bits as described in intro(9P) and + the following: 0x80000000 (DMDIR, this file is a directory), 0x40000000 + (DMAPPEND, append only), 0x20000000 (DMEXCL, exclusive use), 0x04000000 + (DMTMP, temporary); these are echoed in Qid.type. Writes to append-only + files always + place their data at the end of the file; the offset in the write + message is ignored, as is the OTRUNC bit in an open. Exclusive + use files may be open for I/O by only one fid at a time across + all clients of the server. If a second open is attempted, it draws + an error. Servers may implement a timeout on the lock on an + exclusive use file: if the fid holding the file open has been + unused for an extended period (of order at least minutes), it + is reasonable to break the lock and deny the initial fid further + I/O. Temporary files are not included in nightly archives (see + Plan 9’s fossil(4)). +
+ + The two time fields are measured in seconds since the epoch (Jan + 1 00:00 1970 GMT). The mtime field reflects the time of the last + change of content (except when later changed by wstat). For a + plain file, mtime is the time of the most recent create, open + with truncation, or write; for a directory it is the time of + the most recent remove, create, or wstat of a file in the directory. + Similarly, the atime field records the last read of the contents; + also it is set whenever mtime is set. In addition, for a directory, + it is set by an attach, walk, or create, all whether successful + or not. +
+ + The muid field names the user whose actions most recently changed + the mtime of the file. +
+ + The length records the number of bytes in the file. Directories + and most files representing devices have a conventional length + of 0. +
+ + The stat request requires no special permissions. +
+ + The wstat request can change some of the file status information. + The 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 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 mode and 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 wstat; the other + defined permission and mode bits can. The 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 intro(9P) for more information about permissions, users, + and groups). None of the other data can be altered by a + wstat and attempts to change them will trigger an error. In particular, + it is illegal to attempt to change the owner of a file. (These + conditions may be relaxed when establishing the initial state + of a file server; see Plan 9’s fsconfig(8).) +
+ + Either all the changes in wstat request happen, or none of them + does: if the request succeeds, all changes were made; if it fails, + none were. +
+ + A wstat request can avoid modifying some properties of the file + by providing explicit “don’t touch” values in the 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 all the elements of the directory entry in a 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 Rwstat message + is returned. (Consider the message to mean, “make the state of + the file exactly what it claims to be.”) +
+ + A read of a directory yields an integral number of directory entries + in the machine independent encoding given above (see read(9P)). + +
+ + Note that since the stat information is sent as a 9P variable-length + datum, it is limited to a maximum of 65535 bytes.
+ +
+

ENTRY POINTS
+ +
+ + Stat messages are generated by fsdirfstat and fsdirstat (see 9pclient(3)). + +
+ + Wstat messages are generated by fsdirfwstat and fsdirwstat.
+ +
+

BUGS
+ +
+ + To make the contents of a directory, such as returned by read(9P), + easy to parse, each directory entry begins with a size field. + For consistency, the entries in Twstat and Rstat messages also + contain their size, which means the size appears twice. For example, + the Rstat message is formatted as “(4+1+2+2+n)[4] + Rstat tag[2] n[2] (n-2)[2] type[2] dev[4]...,” where n is the + value returned by convD2M.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/version.html b/man/man9/version.html new file mode 100644 index 00000000..3d382f6b --- /dev/null +++ b/man/man9/version.html @@ -0,0 +1,100 @@ + +version(9P) - Plan 9 from User Space + + + + +
+
+
VERSION(9P)VERSION(9P) +
+
+

NAME
+ +
+ + version – negotiate protocol version
+ +
+

SYNOPSIS
+ +
+ + size[4] Tversion tag[2] msize[4] version[s]
+ size[4] Rversion tag[2] msize[4] version[s]
+ +
+

DESCRIPTION
+ +
+ + The version request negotiates the protocol version and message + size to be used on the connection and initializes the connection + for I/O. Tversion must be the first message sent on the 9P connection, + and the client cannot issue any further requests until it has + received the Rversion reply. The tag should be + NOTAG (value (ushort)~0) for a version message. +
+ + The client suggests a maximum message size, 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 size field and extending through the message, + but excludes enveloping transport protocols. The + server responds with its own maximum, msize, which must be less + than or equal to the client’s value. Thenceforth, both sides of + the connection must honor this limit. +
+ + The version string identifies the level of the protocol. The string + must always begin with the two characters “9P”. If the server + does not understand the client’s version string, it should respond + with an Rversion message (not Rerror) with the version string + the 7 characters “unknown”. +
+ + 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 “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 9Pnnnn, where nnnn is less than or equal to the digits sent + by the client. +
+ + The client and server will use the protocol version defined by + the server’s response for all subsequent communication on the + connection. +
+ + A successful 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 version requests is + called a session.
+ +
+

ENTRY POINTS
+ +
+ + Fsversion (see 9pclient(3)) generates version messages; it is + called automatically by fsmount.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + diff --git a/man/man9/walk.html b/man/man9/walk.html new file mode 100644 index 00000000..32a72a9e --- /dev/null +++ b/man/man9/walk.html @@ -0,0 +1,119 @@ + +walk(9P) - Plan 9 from User Space + + + + +
+
+
WALK(9P)WALK(9P) +
+
+

NAME
+ +
+ + walk – descend a directory hierarchy
+ +
+

SYNOPSIS
+ +
+ + size[4] Twalk tag[2] fid[4] newfid[4] nwname[2] nwname*(wname[s])
+ size[4] Rwalk tag[2] nwqid[2] nwqid*(qid[13])
+ +
+

DESCRIPTION
+ +
+ + The walk request carries as arguments an existing fid and a proposed + newfid (which must not be in use unless it is the same as 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 wname. The fid must represent + a directory unless zero path name elements are specified. +
+ + The fid must be valid in the current session and must not have + been opened for I/O by an open or create message. If the full + sequence of nwname elements is walked successfully, newfid will + represent the file that results. If not, newfid (and fid) will + be unaffected. However, if newfid is in use or otherwise illegal, + an Rerror is returned. +
+ + The name “..” (dot-dot) represents the parent directory. The name + “.” (dot), meaning the current directory, is not used in the protocol. + +
+ + It is legal for nwname to be zero, in which case newfid will represent + the same file as fid and the walk will usually succeed; this is + equivalent to walking to dot. The rest of this discussion assumes + nwname is greater than zero. +
+ + The nwname path name elements wname are walked in order, “elementwise”. + For the first elementwise walk to succeed, the file identified + by fid must be a directory, and the implied user of the request + must have permission to search the directory (see intro(9P)). + Subsequent elementwise walks have equivalent + restrictions applied to the implicit fid that results from the + preceding elementwise walk. +
+ + If the first element cannot be walked for any reason, Rerror is + returned. Otherwise, the walk will return an Rwalk message containing + nwqid qids corresponding, in order, to the files that are visited + by the nwqid successful elementwise walks; nwqid is therefore + either nwname or the index of the first elementwise + walk that failed. The value of nwqid cannot be zero unless nwname + is zero. Also, nwqid will always be less than or equal to nwname. + Only if it is equal, however, will newfid be affected, in which + case newfid will represent the file reached by the final elementwise + walk requested in the message. +
+ + A walk of the name “..” in the root directory of a server is equivalent + to a walk with no name elements. +
+ + If newfid is the same as fid, the above discussion applies, with + the obvious difference that if the walk changes the state of newfid, + it also changes the state of fid; and if newfid is unaffected, + then fid is also unaffected. +
+ + 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 MAXWELEM in fcall(3). Despite this restriction, + the system imposes no limit on the number of elements in a file + name, only the number that may be transmitted in a + single message.
+ +
+

ENTRY POINTS
+ +
+ + Fswalk (see 9pclient(3)) generates walk messages. One or more + walk messages may be generated by any call that evaluates file + names: fsopen, fsopenfd, fsdirstat, fsdirwstat.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3