From cfa37a7b1131abbab2e7d339b451f5f0e3198cc8 Mon Sep 17 00:00:00 2001 From: rsc Date: Sat, 10 Apr 2004 18:53:55 +0000 Subject: Lots of man pages. --- man/man1/9nm.1 | 104 ++++ man/man1/9sed.1 | 385 +++++++++++++ man/man1/acme.1 | 683 +++++++++++++++++++++++ man/man1/ascii.1 | 161 ++++++ man/man1/basename.1 | 35 ++ man/man1/cal.1 | 46 ++ man/man1/calendar.1 | 53 ++ man/man1/cat.1 | 86 +++ man/man1/cleanname.1 | 32 ++ man/man1/cmp.1 | 57 ++ man/man1/comm.1 | 47 ++ man/man1/date.1 | 58 ++ man/man1/dc.1 | 257 +++++++++ man/man1/deroff.1 | 117 ++++ man/man1/dict.1 | 163 ++++++ man/man1/diff.1 | 155 ++++++ man/man1/echo.1 | 26 + man/man1/ed.1 | 683 +++++++++++++++++++++++ man/man1/factor.1 | 66 +++ man/man1/fmt.1 | 90 +++ man/man1/fortune.1 | 23 + man/man1/freq.1 | 40 ++ man/man1/grep.1 | 103 ++++ man/man1/hoc.1 | 144 +++++ man/man1/idiff.1 | 72 +++ man/man1/join.1 | 148 +++++ man/man1/ls.1 | 162 ++++++ man/man1/mc.1 | 40 ++ man/man1/mkdir.1 | 35 ++ man/man1/plumb.1 | 92 ++++ man/man1/rc.1 | 959 ++++++++++++++++++++++++++++++++ man/man1/rm.1 | 28 + man/man1/sam.1 | 885 ++++++++++++++++++++++++++++++ man/man1/seq.1 | 75 +++ man/man1/sleep.1 | 31 ++ man/man1/sort.1 | 260 +++++++++ man/man1/spell.1 | 96 ++++ man/man1/split.1 | 82 +++ man/man1/strings.1 | 28 + man/man1/sum.1 | 77 +++ man/man1/tail.1 | 87 +++ man/man1/tar.1 | 118 ++++ man/man1/tee.1 | 28 + man/man1/test.1 | 211 +++++++ man/man1/time.1 | 21 + man/man1/touch.1 | 35 ++ man/man1/tr.1 | 97 ++++ man/man1/uniq.1 | 59 ++ man/man1/wc.1 | 53 ++ man/man1/xd.1 | 87 +++ man/man1/yacc.1 | 167 ++++++ man/man3/9p.3 | 760 ++++++++++++++++++++++++++ man/man3/9pcmdbuf.3 | 116 ++++ man/man3/9pfid.3 | 204 +++++++ man/man3/9pfile.3 | 223 ++++++++ man/man3/abort.3 | 18 + man/man3/abs.3 | 33 ++ man/man3/access.3 | 60 ++ man/man3/addpt.3 | 188 +++++++ man/man3/aes.3 | 51 ++ man/man3/allocimage.3 | 348 ++++++++++++ man/man3/arg.3 | 124 +++++ man/man3/assert.3 | 25 + man/man3/atof.3 | 146 +++++ man/man3/auth.3 | 395 ++++++++++++++ man/man3/authsrv.3 | 223 ++++++++ man/man3/bin.3 | 99 ++++ man/man3/bio.3 | 117 ++-- man/man3/blowfish.3 | 52 ++ man/man3/cachechars.3 | 313 +++++++++++ man/man3/cleanname.3 | 34 ++ man/man3/color.3 | 56 ++ man/man3/complete.3 | 105 ++++ man/man3/cputime.3 | 34 ++ man/man3/ctype.3 | 160 ++++++ man/man3/debugger.3 | 386 +++++++++++++ man/man3/des.3 | 144 +++++ man/man3/dial.3 | 331 +++++++++++ man/man3/dirread.3 | 103 ++++ man/man3/draw.3 | 821 ++++++++++++++++++++++++++++ man/man3/dsa.3 | 132 +++++ man/man3/dup.3 | 42 ++ man/man3/elgamal.3 | 125 +++++ man/man3/encode.3 | 85 +++ man/man3/encrypt.3 | 76 +++ man/man3/errstr.3 | 85 +++ man/man3/event.3 | 384 +++++++++++++ man/man3/exec.3 | 159 ++++++ man/man3/exits.3 | 81 +++ man/man3/fcall.3 | 357 ++++++++++++ man/man3/flate.3 | 207 +++++++ man/man3/fmtinstall.3 | 117 ++-- man/man3/fork.3 | 166 ++++++ man/man3/frame.3 | 362 ++++++++++++ man/man3/genrandom.3 | 44 ++ man/man3/getcallerpc.3 | 38 ++ man/man3/getenv.3 | 44 ++ man/man3/getfcr.3 | 125 +++++ man/man3/getfields.3 | 95 ++++ man/man3/getpid.3 | 41 ++ man/man3/getuser.3 | 37 ++ man/man3/getwd.3 | 37 ++ man/man3/graphics.3 | 651 ++++++++++++++++++++++ man/man3/html.3 | 1420 ++++++++++++++++++++++++++++++++++++++++++++++++ man/man3/hypot.3 | 21 + man/man3/intmap.3 | 126 +++++ man/man3/ioproc.3 | 2 +- man/man3/ip.3 | 335 ++++++++++++ man/man3/isalpharune.3 | 10 +- man/man3/keyboard.3 | 104 ++++ man/man3/lock.3 | 232 ++++++++ man/man3/mach.3 | 393 ++++++++++++++ man/man3/malloc.3 | 207 +++++++ man/man3/memdraw.3 | 450 +++++++++++++++ man/man3/memlayer.3 | 305 +++++++++++ man/man3/mktemp.3 | 40 ++ man/man3/mouse.3 | 249 +++++++++ man/man3/mp.3 | 577 ++++++++++++++++++++ man/man3/muldiv.3 | 31 ++ man/man3/nan.3 | 44 ++ man/man3/notify.3 | 244 +++++++++ man/man3/open.3 | 148 +++++ man/man3/pipe.3 | 74 +++ man/man3/plumb.3 | 240 ++++++++ man/man3/pool.3 | 329 +++++++++++ man/man3/postnote.3 | 49 ++ man/man3/prime.3 | 100 ++++ man/man3/quote.3 | 167 ++++++ man/man3/rand.3 | 175 ++++++ man/man3/rc4.3 | 55 ++ man/man3/read.3 | 95 ++++ man/man3/readv.3 | 82 +++ man/man3/regexp.3 | 212 ++++++++ man/man3/regexp9.3 | 227 -------- man/man3/remove.3 | 31 ++ man/man3/rendezvous.3 | 57 ++ man/man3/rsa.3 | 202 +++++++ man/man3/rune.3 | 13 +- man/man3/runestrcat.3 | 14 +- man/man3/sechash.3 | 150 +++++ man/man3/seek.3 | 46 ++ man/man3/setjmp.3 | 98 ++++ man/man3/sleep.3 | 45 ++ man/man3/stat.3 | 326 +++++++++++ man/man3/strcat.3 | 268 +++++++++ man/man3/string.3 | 236 ++++++++ man/man3/stringsize.3 | 69 +++ man/man3/subfont.3 | 235 ++++++++ man/man3/symbol.3 | 436 +++++++++++++++ man/man3/thread.3 | 2 +- man/man3/time.3 | 45 ++ man/man3/wait.3 | 117 ++++ man/man7/regexp.7 | 150 +++++ man/man7/regexp9.7 | 150 ----- 154 files changed, 25749 insertions(+), 490 deletions(-) create mode 100644 man/man1/9nm.1 create mode 100644 man/man1/9sed.1 create mode 100644 man/man1/acme.1 create mode 100644 man/man1/ascii.1 create mode 100644 man/man1/basename.1 create mode 100644 man/man1/cal.1 create mode 100644 man/man1/calendar.1 create mode 100644 man/man1/cat.1 create mode 100644 man/man1/cleanname.1 create mode 100644 man/man1/cmp.1 create mode 100644 man/man1/comm.1 create mode 100644 man/man1/date.1 create mode 100644 man/man1/dc.1 create mode 100644 man/man1/deroff.1 create mode 100644 man/man1/dict.1 create mode 100644 man/man1/diff.1 create mode 100644 man/man1/echo.1 create mode 100644 man/man1/ed.1 create mode 100644 man/man1/factor.1 create mode 100644 man/man1/fmt.1 create mode 100644 man/man1/fortune.1 create mode 100644 man/man1/freq.1 create mode 100644 man/man1/grep.1 create mode 100644 man/man1/hoc.1 create mode 100644 man/man1/idiff.1 create mode 100644 man/man1/join.1 create mode 100644 man/man1/ls.1 create mode 100644 man/man1/mc.1 create mode 100644 man/man1/mkdir.1 create mode 100644 man/man1/plumb.1 create mode 100644 man/man1/rc.1 create mode 100644 man/man1/rm.1 create mode 100644 man/man1/sam.1 create mode 100644 man/man1/seq.1 create mode 100644 man/man1/sleep.1 create mode 100644 man/man1/sort.1 create mode 100644 man/man1/spell.1 create mode 100644 man/man1/split.1 create mode 100644 man/man1/strings.1 create mode 100644 man/man1/sum.1 create mode 100644 man/man1/tail.1 create mode 100644 man/man1/tar.1 create mode 100644 man/man1/tee.1 create mode 100644 man/man1/test.1 create mode 100644 man/man1/time.1 create mode 100644 man/man1/touch.1 create mode 100644 man/man1/tr.1 create mode 100644 man/man1/uniq.1 create mode 100644 man/man1/wc.1 create mode 100644 man/man1/xd.1 create mode 100644 man/man1/yacc.1 create mode 100644 man/man3/9p.3 create mode 100644 man/man3/9pcmdbuf.3 create mode 100644 man/man3/9pfid.3 create mode 100644 man/man3/9pfile.3 create mode 100644 man/man3/abort.3 create mode 100644 man/man3/abs.3 create mode 100644 man/man3/access.3 create mode 100644 man/man3/addpt.3 create mode 100644 man/man3/aes.3 create mode 100644 man/man3/allocimage.3 create mode 100644 man/man3/arg.3 create mode 100644 man/man3/assert.3 create mode 100644 man/man3/atof.3 create mode 100644 man/man3/auth.3 create mode 100644 man/man3/authsrv.3 create mode 100644 man/man3/bin.3 create mode 100644 man/man3/blowfish.3 create mode 100644 man/man3/cachechars.3 create mode 100644 man/man3/cleanname.3 create mode 100644 man/man3/color.3 create mode 100644 man/man3/complete.3 create mode 100644 man/man3/cputime.3 create mode 100644 man/man3/ctype.3 create mode 100644 man/man3/debugger.3 create mode 100644 man/man3/des.3 create mode 100644 man/man3/dial.3 create mode 100644 man/man3/dirread.3 create mode 100644 man/man3/draw.3 create mode 100644 man/man3/dsa.3 create mode 100644 man/man3/dup.3 create mode 100644 man/man3/elgamal.3 create mode 100644 man/man3/encode.3 create mode 100644 man/man3/encrypt.3 create mode 100644 man/man3/errstr.3 create mode 100644 man/man3/event.3 create mode 100644 man/man3/exec.3 create mode 100644 man/man3/exits.3 create mode 100644 man/man3/fcall.3 create mode 100644 man/man3/flate.3 create mode 100644 man/man3/fork.3 create mode 100644 man/man3/frame.3 create mode 100644 man/man3/genrandom.3 create mode 100644 man/man3/getcallerpc.3 create mode 100644 man/man3/getenv.3 create mode 100644 man/man3/getfcr.3 create mode 100644 man/man3/getfields.3 create mode 100644 man/man3/getpid.3 create mode 100644 man/man3/getuser.3 create mode 100644 man/man3/getwd.3 create mode 100644 man/man3/graphics.3 create mode 100644 man/man3/html.3 create mode 100644 man/man3/hypot.3 create mode 100644 man/man3/intmap.3 create mode 100644 man/man3/ip.3 create mode 100644 man/man3/keyboard.3 create mode 100644 man/man3/lock.3 create mode 100644 man/man3/mach.3 create mode 100644 man/man3/malloc.3 create mode 100644 man/man3/memdraw.3 create mode 100644 man/man3/memlayer.3 create mode 100644 man/man3/mktemp.3 create mode 100644 man/man3/mouse.3 create mode 100644 man/man3/mp.3 create mode 100644 man/man3/muldiv.3 create mode 100644 man/man3/nan.3 create mode 100644 man/man3/notify.3 create mode 100644 man/man3/open.3 create mode 100644 man/man3/pipe.3 create mode 100644 man/man3/plumb.3 create mode 100644 man/man3/pool.3 create mode 100644 man/man3/postnote.3 create mode 100644 man/man3/prime.3 create mode 100644 man/man3/quote.3 create mode 100644 man/man3/rand.3 create mode 100644 man/man3/rc4.3 create mode 100644 man/man3/read.3 create mode 100644 man/man3/readv.3 create mode 100644 man/man3/regexp.3 delete mode 100644 man/man3/regexp9.3 create mode 100644 man/man3/remove.3 create mode 100644 man/man3/rendezvous.3 create mode 100644 man/man3/rsa.3 create mode 100644 man/man3/sechash.3 create mode 100644 man/man3/seek.3 create mode 100644 man/man3/setjmp.3 create mode 100644 man/man3/sleep.3 create mode 100644 man/man3/stat.3 create mode 100644 man/man3/strcat.3 create mode 100644 man/man3/string.3 create mode 100644 man/man3/stringsize.3 create mode 100644 man/man3/subfont.3 create mode 100644 man/man3/symbol.3 create mode 100644 man/man3/time.3 create mode 100644 man/man3/wait.3 create mode 100644 man/man7/regexp.7 delete mode 100644 man/man7/regexp9.7 diff --git a/man/man1/9nm.1 b/man/man1/9nm.1 new file mode 100644 index 00000000..f9faad54 --- /dev/null +++ b/man/man1/9nm.1 @@ -0,0 +1,104 @@ +.TH NM 1 +.SH NAME +nm \- name list (symbol table) +.SH SYNOPSIS +.B nm +[ +.B -aghnsu +] +.I file ... +.SH DESCRIPTION +.I Nm +prints the name list of each executable or object +.I file +in the argument list. +If the +.I file +is an archive +(see +.IR ar (1)), +the name list of each file in the archive is printed. +If more than one file is given in the argument list, +the name of each file is printed at the beginning of each line. +.PP +Each symbol name is preceded by its hexadecimal +value (blanks if undefined) +and one of the letters +.TP +.B T +text segment symbol +.PD0 +.TP +.B t +static text segment symbol +.TP +.B L +leaf function text segment symbol +.TP +.B l +static leaf function text segment symbol +.TP +.B D +data segment symbol +.TP +.B d +static data segment symbol +.TP +.B B +bss segment symbol +.TP +.B b +static bss segment symbol +.TP +.B a +automatic (local) variable symbol +.TP +.B p +function parameter symbol +.TP +.B z +source file name +.TP +.B Z +source file line offset +.TP +.B f +source file name components +.PD +.PP +The output is sorted alphabetically. +.PP +Options are: +.TP +.B -a +Print all symbols; normally only user-defined text, data, +and bss segment symbols are printed. +.TP +.B -g +Print only global +.RB ( T , +.BR L , +.BR D , +.BR B ) +symbols. +.TP +.B -h +Do not print file name headers with output lines. +.TP +.B -n +Sort according to the address of the symbols. +.TP +.B -s +Don't sort; print in symbol-table order. +.TP +.B -u +Print only undefined symbols. +.SH SOURCE +.B /sys/src/cmd/nm.c +.SH SEE ALSO +.IR ar (1), +.IR 2l (1), +.IR db (1), +.IR acid (1), +.IR a.out (6) + diff --git a/man/man1/9sed.1 b/man/man1/9sed.1 new file mode 100644 index 00000000..3b5ac181 --- /dev/null +++ b/man/man1/9sed.1 @@ -0,0 +1,385 @@ +.TH SED 1 +.SH NAME +sed \- stream editor +.SH SYNOPSIS +.B sed +[ +.B -n +] +[ +.B -g +] +[ +.B -e +.I script +] +[ +.B -f +.I sfile +] +[ +.I file ... +] +.SH DESCRIPTION +.I Sed +copies the named +.I files +(standard input default) to the standard output, +edited according to a script of commands. +The +.B -f +option causes the script to be taken from file +.IR sfile ; +these options accumulate. +If there is just one +.B -e +option and no +.BR -f 's, +the flag +.B -e +may be omitted. +The +.B -n +option suppresses the default output; +.B -g +causes all substitutions to be global, as if suffixed +.BR g . +.PP +A script consists of editing commands, one per line, +of the following form: +.IP +[\fIaddress\fR [\fL,\fI address\fR] ] \fIfunction\fR [\fIargument\fR ...] +.PP +In normal operation +.I sed +cyclically copies a line of input into a +.I pattern space +(unless there is something left after +a +.L D +command), +applies in sequence +all commands whose +.I addresses +select that pattern space, +and at the end of the script copies the pattern space +to the standard output (except under +.BR -n ) +and deletes the pattern space. +.PP +An +.I address +is either a decimal number that counts +input lines cumulatively across files, a +.L $ +that +addresses the last line of input, or a context address, +.BI / regular-expression / \f1, +in the style of +.IR regexp (6), +with the added convention that +.L \en +matches a +newline embedded in the pattern space. +.PP +A command line with no addresses selects every pattern space. +.PP +A command line with +one address selects each pattern space that matches the address. +.PP +A command line with +two addresses selects the inclusive range from the first +pattern space that matches the first address through +the next pattern space that matches +the second. +(If the second address is a number less than or equal +to the line number first selected, only one +line is selected.) +Thereafter the process is repeated, looking again for the +first address. +.PP +Editing commands can be applied to non-selected pattern +spaces by use of the negation function +.L ! +(below). +.PP +An argument denoted +.I text +consists of one or more lines, +all but the last of which end with +.L \e +to hide the +newline. +Backslashes in text are treated like backslashes +in the replacement string of an +.L s +command, +and may be used to protect initial blanks and tabs +against the stripping that is done on +every script line. +.PP +An argument denoted +.I rfile +or +.I wfile +must terminate the command +line and must be preceded by exactly one blank. +Each +.I wfile +is created before processing begins. +There can be at most 120 distinct +.I wfile +arguments. +.TP \w'\fL!\ \fIfunction\fLXXX'u +.B a\e +.br +.ns +.TP +.I text +Append. +Place +.I text +on the output before +reading the next input line. +.TP +.BI b " label" +Branch to the +.B : +command bearing the +.IR label . +If +.I label +is empty, branch to the end of the script. +.TP +.B c\e +.br +.ns +.TP +.I text +Change. +Delete the pattern space. +With 0 or 1 address or at the end of a 2-address range, place +.I text +on the output. +Start the next cycle. +.TP +.B d +Delete the pattern space. +Start the next cycle. +.TP +.B D +Delete the initial segment of the +pattern space through the first newline. +Start the next cycle. +.TP +.B g +Replace the contents of the pattern space +by the contents of the hold space. +.TP +.B G +Append the contents of the hold space to the pattern space. +.TP +.B h +Replace the contents of the hold space by the contents of the pattern space. +.TP +.B H +Append the contents of the pattern space to the hold space. +.ne 3 +.TP +.B i\e +.br +.ns +.TP +.I text +Insert. +Place +.I text +on the standard output. +.TP +.B n +Copy the pattern space to the standard output. +Replace the pattern space with the next line of input. +.TP +.B N +Append the next line of input to the pattern space +with an embedded newline. +(The current line number changes.) +.TP +.B p +Print. +Copy the pattern space to the standard output. +.TP +.B P +Copy the initial segment of the pattern space through +the first newline to the standard output. +.TP +.B q +Quit. +Branch to the end of the script. +Do not start a new cycle. +.TP +.BI r " rfile" +Read the contents of +.IR rfile . +Place them on the output before reading +the next input line. +.TP +.B s/\fIregular-expression\fP/\fIreplacement\fP/\fIflags +Substitute the +.I replacement +string for instances of the +.I regular-expression +in the pattern space. +Any character may be used instead of +.LR / . +For a fuller description see +.IR regexp (6). +.I Flags +is zero or more of +.RS +.TP +.B g +Global. +Substitute for all non-overlapping instances of the +.I regular expression +rather than just the +first one. +.TP +.B p +Print the pattern space if a replacement was made. +.TP +.BI w " wfile" +Write. +Append the pattern space to +.I wfile +if a replacement +was made. +.RE +.TP +.BI t " label" +Test. +Branch to the +.L : +command bearing the +.I label +if any +substitutions have been made since the most recent +reading of an input line or execution of a +.LR t . +If +.I label +is empty, branch to the end of the script. +.TP +.B w +.I wfile +.br +Write. +Append the pattern space to +.IR wfile . +.TP +.B x +Exchange the contents of the pattern and hold spaces. +.TP +.B y/\fIstring1\fP/\fIstring2\fP/ +Transform. +Replace all occurrences of characters in +.I string1 +with the corresponding character in +.IR string2 . +The lengths of +.I +string1 +and +.I string2 +must be equal. +.TP +.BI ! "function" +Don't. +Apply the +.I function +(or group, if +.I function +is +.LR { ) +only to lines +.I not +selected by the address(es). +.TP +.BI : " label" +This command does nothing; it bears a +.I label +for +.B b +and +.B t +commands to branch to. +.TP +.B = +Place the current line number on the standard output as a line. +.TP +.B { +Execute the following commands through a matching +.L } +only when the pattern space is selected. +.TP +.B " " +An empty command is ignored. +.ne 4 +.SH EXAMPLES +.TP +.B sed 10q file +Print the first 10 lines of the file. +.TP +.B sed '/^$/d' +Delete empty lines from standard input. +.TP +.B sed 's/UNIX/& system/g' +Replace every instance of +.L UNIX +by +.LR "UNIX system" . +.PP +.EX +sed 's/ *$// \fRdrop trailing blanks\fP +/^$/d \fRdrop empty lines\fP +s/ */\e \fRreplace blanks by newlines\fP +/g +/^$/d' chapter* +.EE +.ns +.IP +Print the files +.BR chapter1 , +.BR chapter2 , +etc. one word to a line. +.PP +.EX +nroff -ms manuscript | sed ' +${ + /^$/p \fRif last line of file is empty, print it\fP +} +//N \fRif current line is empty, append next line\fP +/^\en$/D' \fRif two lines are empty, delete the first\fP +.EE +.ns +.IP +Delete all but one of each group of empty lines from a +formatted manuscript. +.SH SOURCE +.B /sys/src/cmd/sed.c +.SH SEE ALSO +.IR ed (1), +.IR grep (1), +.IR awk (1), +.IR lex (1), +.IR sam (1), +.IR regexp (6) +.br +L. E. McMahon, +`SED \(em A Non-interactive Text Editor', +Unix Research System Programmer's Manual, Volume 2. +.SH BUGS +If input is from a pipe, buffering may consume +characters beyond a line on which a +.L q +command is executed. diff --git a/man/man1/acme.1 b/man/man1/acme.1 new file mode 100644 index 00000000..5cae0036 --- /dev/null +++ b/man/man1/acme.1 @@ -0,0 +1,683 @@ +.TH ACME 1 +.SH NAME +acme, win, awd \- interactive text windows +.SH SYNOPSIS +.B acme +[ +.B -f +.I varfont +] +[ +.B -F +.I fixfont +] +[ +.B -c +.I ncol +] +[ +.B -b +] +[ +.B -l +.I file +| +.I file +\&... ] +.LP +.B win +[ +.I command +] +.LP +.B awd +[ +.I label +] +.SH DESCRIPTION +.I Acme +manages windows of text that may be edited interactively or by external programs. +The interactive interface uses the keyboard and mouse; external programs +use a set of files served by +.IR acme ; +these are discussed in +.IR acme (4). +.PP +Any named +.I files +are read into +.I acme +windows before +.I acme +accepts input. +With the +.B -l +option, the state of the entire system is loaded +from +.IR file , +which should have been created by a +.B Dump +command (q.v.), +and subsequent +.I file +names are ignored. +Plain files display as text; directories display as columnated lists of the +names of their components, as in +.B "ls -p directory|mc +except that the names of subdirectories have a slash appended. +.PP +The +.B -f +.RB ( -F ) +option sets the main font, usually variable-pitch (alternate, usually fixed-pitch); +the default is +.B /lib/font/bit/lucidasans/euro.8.font +.RB ( \&.../lucm/unicode.9.font ). +Tab intervals are set to the width of 4 (or the value of +.BR $tabstop ) +numeral zeros in the appropriate font. +.PP +.SS Windows +.I Acme +windows are in two parts: a one-line +.I tag +above a multi-line +.IR body . +The body typically contains an image of a file, as in +.IR sam (1), +or the output of a +program, as in an +.IR rio (1) +window. +The tag contains a number of +blank-separated words, followed by a vertical bar character, followed by anything. +The first word is the name of the window, typically the name of the associated +file or directory, and the other words are commands available in that window. +Any text may be added after the bar; examples are strings to search for or +commands to execute in that window. +Changes to the text left of the bar will be ignored, +unless the result is to change the name of the +window. +.PP +If a window holds a directory, the name (first word of the tag) will end with +a slash. +.SS Scrolling +Each window has a scroll bar to the left of the body. +The scroll bar behaves much as in +.IR sam (1) +or +.IR rio (1) +except that scrolling occurs when the button is pressed, rather than released, +and continues +as long as the mouse button is held down in the scroll bar. +For example, to scroll slowly through a file, +hold button 3 down near the top of the scroll bar. Moving the mouse +down the scroll bar speeds up the rate of scrolling. +.SS Layout +.I Acme +windows are arranged in columns. By default, it creates two columns when starting; +this can be overridden with the +.B -c +option. +Placement is automatic but may be adjusted +using the +.I layout box +in the upper left corner of each window and column. +Pressing and holding any mouse button in the box drags +the associated window or column. +For windows, just +clicking in the layout box grows the window in place: button 1 +grows it a little, button 2 grows it as much as it can, still leaving all other +tags in that column visible, and button 3 takes over the column completely, +temporarily hiding other windows in the column. +(They will return +.I en masse +if any of them needs attention.) +The layout box in a window is normally white; when it is black in the center, +it records that the file is `dirty': +.I Acme +believes it is modified from its original +contents. +.PP +Tags exist at the top of each column and across the whole display. +.I Acme +pre-loads them with useful commands. +Also, the tag across the top maintains a list of executing long-running commands. +.SS Typing +The behavior of typed text is similar to that in +.IR rio (1) +except that the characters are delivered to the tag or body under the mouse; there is no +`click to type'. +(The experimental option +.B -b +causes typing to go to the most recently clicked-at or made window.) +The usual backspacing conventions apply. +As in +.IR sam (1) +but not +.IR rio , +the ESC key selects the text typed since the last mouse action, +a feature particularly useful when executing commands. +A side effect is that typing ESC with text already selected is identical +to a +.B Cut +command +.RI ( q.v. ). +.PP +Most text, including the names of windows, may be edited uniformly. +The only exception is that the command names to the +left of the bar in a tag are maintained automatically; changes to them are repaired +by +.IR acme . +.SS "Directory context +Each window's tag names a directory: explicitly if the window +holds a directory; implicitly if it holds a regular file +(e.g. the directory +.B /adm +if the window holds +.BR /adm/users ). +This directory provides a +.I context +for interpreting file names in that window. +For example, the string +.B users +in a window labeled +.B /adm/ +or +.B /adm/keys +will be interpreted as the file name +.BR /adm/users . +The directory is defined purely textually, so it can be a non-existent +directory or a real directory associated with a non-existent file +(e.g. +.BR /adm/not-a-file ). +File names beginning with a slash +are assumed to be absolute file names. +.SS Errors +Windows whose names begin with +.B - +or +.B + +conventionally hold diagnostics and other data +not directly associated with files. +A window labeled +.B +Errors +receives all diagnostics produced by +.I acme +itself. +Diagnostics from commands run by +.I acme +appear in a window named +.IB directory /+Errors +where +.I directory +is identified by the context of the command. +These error windows are created when needed. +.SS "Mouse button 1 +Mouse button 1 selects text just as in +.IR sam (1) +or +.IR rio (1) , +including the usual double-clicking conventions. +.SS "Mouse button 2 +By an +action similar to selecting text with button 1, +button 2 indicates text to execute as a command. +If the indicated text has multiple white-space-separated words, +the first is the command name and the second and subsequent +are its arguments. +If button 2 is `clicked'\(emindicates a null string\(em\c +.I acme +.I expands +the indicated text to find a command to run: +if the click is within button-1-selected text, +.I acme +takes that selection as the command; +otherwise it takes the largest string of valid file name characters containing the click. +Valid file name characters are alphanumerics and +.B _ +.B . +.B - +.B + +.BR / . +This behavior is similar to double-clicking with button 1 but, +because a null command is meaningless, only a single click is required. +.PP +Some commands, all by convention starting with a capital letter, are +.I built-ins +that are executed directly by +.IR acme : +.TP +.B Cut +Delete most recently selected text and place in snarf buffer. +.TP +.B Del +Delete window. If window is dirty, instead print a warning; a second +.B Del +will succeed. +.TP +.B Delcol +Delete column and all its windows, after checking that windows are not dirty. +.TP +.B Delete +Delete window without checking for dirtiness. +.TP +.B Dump +Write the state of +.I acme +to the file name, if specified, or +.B $home/acme.dump +by default. +.TP +.B Edit +Treat the argument as a text editing command in the style of +.IR sam (1). +The full +.B Sam +language is implemented except for the commands +.BR k , +.BR n , +.BR q , +and +.BR ! . +The +.B = +command is slightly different: it includes the file name and +gives only the line address unless the command is explicitly +.BR =# . +The `current window' for the command is the body of the window in which the +.B Edit +command is executed. +Usually the +.B Edit +command would be typed in a tag; longer commands may be prepared in a +scratch window and executed, with +.B Edit +itself in the current window, using the 2-1 chord described below. +.TP +.B Exit +Exit +.I acme +after checking that windows are not dirty. +.TP +.B Font +With no arguments, change the font of the associated window from fixed-spaced to +proportional-spaced or +.I vice +.IR versa . +Given a file name argument, change the font of the window to that stored in the named file. +If the file name argument is prefixed by +.B var +.RB ( fix ), +also set the default proportional-spaced (fixed-spaced) font for future use to that font. +Other existing windows are unaffected. +.TP +.B Get +Load file into window, replacing previous contents (after checking for dirtiness as in +.BR Del ). +With no argument, use the existing file name of the window. +Given an argument, use that file but do not change the window's file name. +.TP +.B ID +Print window ID number +.RI ( q.v. ). +.TP +.B Incl +When opening `include' files +(those enclosed in +.BR <> ) +with button 3, +.I acme +searches in directories +.B /$objtype/include +and +.BR /sys/include . +.B Incl +adds its arguments to a supplementary list of include directories, analogous to +the +.B -I +option to the compilers. +This list is per-window and is inherited when windows are created by actions in that window, so +.I Incl +is most usefully applied to a directory containing relevant source. +With no arguments, +.I Incl +prints the supplementary list. +This command is largely superseded by plumbing +(see +.IR plumb (6)). +.TP +.B Kill +Send a +.B kill +note to +.IR acme -initiated +commands named as arguments. +.TP +.B Local +When prefixed to a command +run the +command in the same file name space and environment variable group as +.IR acme . +The environment of the command +is restricted but is sufficient to run +.IR bind (1), +.IR 9fs +(see +.IR srv (4)), +.IR import (4), +etc., +and to set environment variables such as +.BR $objtype . +.TP +.B Load +Restore the state of +.I acme +from a file (default +.BR $home/acme.dump ) +created by the +.B Dump +command. +.TP +.B Look +Search in body for occurrence of literal text indicated by the argument or, +if none is given, by the selected text in the body. +.TP +.B New +Make new window. With arguments, load the named files into windows. +.TP +.B Newcol +Make new column. +.TP +.B Paste +Replace most recently selected text with contents of snarf buffer. +.TP +.B Put +Write window to the named file. +With no argument, write to the file named in the tag of the window. +.TP +.B Putall +Write all dirty windows whose names indicate existing regular files. +.TP +.B Redo +Complement of +.BR Undo . +.TP +.B Send +Append selected text or snarf buffer to end of body; used mainly with +.IR win . +.TP +.B Snarf +Place selected text in snarf buffer. +.TP +.B Sort +Arrange the windows in the column from top to bottom in lexicographical +order based on their names. +.TP +.B Tab +Set the width of tab stops for this window to the value of the argument, in units of widths of the zero +character. +With no arguments, it prints the current value. +.TP +.B Undo +Undo last textual change or set of changes. +.TP +.B Zerox +Create a copy of the window containing most recently selected text. +.PP +A common place to store text for commands is in the tag; in fact +.I acme +maintains a set of commands appropriate to the state of the window +to the left of the bar in the tag. +.PP +If the text indicated with button 2 is not a recognized built-in, it is executed as +a shell command. For example, indicating +.B date +with button 2 runs +.IR date (1). +The standard +and error outputs of commands are sent to the error window associated with +the directory from which the command was run, which will be created if +necessary. +For example, in a window +.B /adm/users +executing +.B pwd +will produce the output +.B /adm +in a (possibly newly-created) window labeled +.BR /adm/+Errors ; +in a window containing +.B /sys/src/cmd/sam/sam.c +executing +.B mk +will run +.IR mk (1) +in +.BR /sys/src/cmd/sam , +producing output in a window labeled +.BR /sys/src/cmd/sam/+Errors . +The environment of such commands contains the variable +.B $% +with value set to the filename of the window in which the command is run. +.SS "Mouse button 3 +Pointing at text with button 3 instructs +.I acme +to locate or acquire the file, string, etc. described by the indicated text and +its context. +This description follows the actions taken when +button 3 is released after sweeping out some text. +In the description, +.I text +refers to the text of the original sweep or, if it was null, the result of +applying the same expansion rules that apply to button 2 actions. +.PP +If the text names an existing window, +.I acme +moves the mouse cursor to the selected text in the body of that window. +If the text names an existing file with no associated window, +.I acme +loads the file into a new window and moves the mouse there. +If the text is a file name contained in angle brackets, +.I acme +loads the indicated include file from the directory appropriate to the +suffix of the file name of the window holding the text. +(The +.B Incl +command adds directories to the standard list.) +.PP +If the text begins with a colon, it is taken to be an address, in +the style of +.IR sam (1), +within the body of the window containing the text. +The address is evaluated, the resulting text highlighted, and the mouse moved to it. +Thus, in +.IR acme , +one must type +.B :/regexp +or +.B :127 +not just +.B /regexp +or +.BR 127 . +(There is an easier way to locate literal text; see below.) +.PP +If the text is a file name followed by a colon and an address, +.I acme +loads the file and evaluates the address. For example, clicking button 3 anywhere +in the text +.B file.c:27 +will open +.BR file.c , +select line +27, and put the mouse at the beginning of the line. The rules about Error +files, directories, and so on all combine to make this an efficient way to +investigate errors from compilers, etc. +.PP +If the text is not an address or file, it is taken to +be literal text, which is then searched for in the body of the window +in which button 3 was clicked. If a match is found, it is selected and the mouse is +moved there. Thus, to search for occurrences of a word in a file, +just click button 3 on the word. Because of the rule of using the +selection as the button 3 action, subsequent clicks will find subsequent +occurrences without moving the mouse. +.PP +In all these actions, the mouse motion is not done if the text is a null string +within a non-null selected string in the tag, so that (for example) complex regular expressions +may be selected and applied repeatedly to the +body by just clicking button 3 over them. +.SS "Chords of mouse buttons +Several operations are bound to multiple-button actions. +After selecting text, with button 1 still down, pressing button 2 +executes +.B Cut +and button 3 executes +.BR Paste . +After clicking one button, the other undoes +the first; thus (while holding down button 1) 2 followed by 3 is a +.B Snarf +that leaves the file undirtied; +3 followed by 2 is a no-op. +These actions also apply to text selected by double-clicking because +the double-click expansion is made when the second +click starts, not when it ends. +.PP +Commands may be given extra arguments by a mouse chord with buttons 2 and 1. +While holding down button 2 on text to be executed as a command, clicking button 1 +appends the text last pointed to by button 1 as a distinct final argument. +For example, to search for literal +.B text +one may execute +.B Look text +with button 2 or instead point at +.B text +with button 1 in any window, release button 1, +then execute +.BR Look , +clicking button 1 while 2 is held down. +.PP +When an external command (e.g. +.IR echo (1)) +is executed this way, the extra argument is passed as expected and an +environment variable +.B $acmeaddr +is created that holds, in the form interpreted by button 3, +the fully-qualified address of the extra argument. +.SS "Support programs +.I Win +creates a new +.I acme +window and runs a +.I command +(default +.BR /bin/rc ) +in it, turning the window into something analogous to an +.IR rio (1) +window. +Executing text in a +.I win +window with button +2 is similar to using +.BR Send . +.PP +.I Awd +loads the tag line of its window with the directory in which it's running, suffixed +.BI - label +(default +.BR rc ); +it is +intended to be executed by a +.B cd +function for use in +.I win +windows. An example definition is +.EX + fn cd { builtin cd $1 && awd $sysname } +.EE +.SS "Applications and guide files +In the directory +.B /acme +live several subdirectories, each corresponding to a program or +set of related programs that employ +.I acme's +user interface. +Each subdirectory includes source, binaries, and a +.B readme +file for further information. +It also includes a +.BR guide , +a text file holding sample commands to invoke the programs. +The idea is to find an example in the guide that best matches +the job at hand, edit it to suit, and execute it. +.PP +Whenever a command is executed by +.IR acme , +the default search path includes the directory of the window containing +the command and its subdirectory +.BR $cputype . +The program directories in +.B /acme +contain appropriately labeled subdirectories of binaries, +so commands named +in the guide files will be found automatically when run. +Also, +.I acme +binds the directories +.B /acme/bin +and +.B /acme/bin/$cputype +to the end of +.B /bin +when it starts; this is where +.IR acme -specific +programs such as +.I win +and +.I awd +reside. +.SH FILES +.TF $home/acme.dump +.TP +.B $home/acme.dump +default file for +.B Dump +and +.BR Load ; +also where state is written if +.I acme +dies or is killed unexpectedly, e.g. by deleting its window. +.TP +.B /acme/*/guide +template files for applications +.TP +.B /acme/*/readme +informal documentation for applications +.TP +.B /acme/*/src +source for applications +.TP +.B /acme/*/mips +MIPS-specific binaries for applications +.SH SOURCE +.B /sys/src/cmd/acme +.br +.B /acme/bin/source/win +.br +.B /sys/src/cmd/awd.c +.SH SEE ALSO +.IR acme (4) +.br +Rob Pike, +.I +Acme: A User Interface for Programmers. +.SH BUGS +With the +.B -l +option or +.B Load +command, +the recreation of windows under control of external programs +such as +.I win +is just to rerun the command; information may be lost. diff --git a/man/man1/ascii.1 b/man/man1/ascii.1 new file mode 100644 index 00000000..47fd3550 --- /dev/null +++ b/man/man1/ascii.1 @@ -0,0 +1,161 @@ +.TH ASCII 1 +.SH NAME +ascii, unicode \- interpret ASCII, Unicode characters +.SH SYNOPSIS +.B ascii +[ +.B -8 +] +[ +.BI -oxdb n +] +[ +.B -nct +] +[ +.I text +] +.PP +.B unicode +[ +.B -nt +] +.IB hexmin - hexmax +.PP +.B unicode +[ +.B -t +] +.I hex +[ +\&... +] +.PP +.B unicode +[ +.B -n +] +.I characters +.PP +.B look +.I hex +.B /lib/unicode +.SH DESCRIPTION +.I Ascii +prints the +.SM ASCII +values corresponding to characters and +.I vice +.IR versa ; +under the +.B -8 +option, the +.SM ISO +Latin-1 extensions (codes 0200-0377) are included. +The values are interpreted in a settable numeric base; +.B -o +specifies octal, +.B -d +decimal, +.B -x +hexadecimal (the default), and +.BI -b n +base +.IR n . +.PP +With no arguments, +.I ascii +prints a table of the character set in the specified base. +Characters of +.I text +are converted to their +.SM ASCII +values, one per line. If, however, the first +.I text +argument is a valid number in the specified base, conversion +goes the opposite way. +Control characters are printed as two- or three-character mnemonics. +Other options are: +.TP +.B -n +Force numeric output. +.TP +.B -c +Force character output. +.TP +.B -t +Convert from numbers to running text; do not interpret +control characters or insert newlines. +.PP +.I Unicode +is similar; it converts between +.SM UTF +and character values from the Unicode Standard (see +.IR utf (6)). +If given a range of hexadecimal numbers, +.I unicode +prints a table of the specified Unicode characters \(em their values and +.SM UTF +representations. +Otherwise it translates from +.SM UTF +to numeric value or vice versa, +depending on the appearance of the supplied text; +the +.B -n +option forces numeric output to avoid ambiguity with numeric characters. +If converting to +.SM UTF , +the characters are printed one per line unless the +.B -t +flag is set, in which case the output is a single string +containing only the specified characters. +Unlike +.IR ascii , +.I unicode +treats no characters specially. +.PP +The output of +.I ascii +and +.I unicode +may be unhelpful if the characters printed are not available in the current font. +.PP +The file +.B /lib/unicode +contains a +table of characters and descriptions, sorted in hexadecimal order, +suitable for +.IR look (1) +on the lower case +.I hex +values of characters. +.SH EXAMPLES +.TP +.B "ascii -d" +Print the +.SM ASCII +table base 10. +.TP +.B "unicode p" +Print the hex value of `p'. +.TP +.B "unicode 2200-22f1" +Print a table of miscellaneous mathematical symbols. +.TP +.B "look 039 /lib/unicode" +See the start of the Greek alphabet's encoding in the Unicode Standard. +.SH FILES +.TF /lib/unicode +.TP +.B /lib/unicode +table of characters and descriptions. +.SH SOURCE +.B /sys/src/cmd/ascii.c +.br +.B /sys/src/cmd/unicode.c +.SH "SEE ALSO" +.IR look (1) +.IR tcs (1), +.IR utf (6), +.IR font (6) diff --git a/man/man1/basename.1 b/man/man1/basename.1 new file mode 100644 index 00000000..c72638f1 --- /dev/null +++ b/man/man1/basename.1 @@ -0,0 +1,35 @@ +.TH BASENAME 1 +.SH NAME +basename \- strip file name affixes +.SH SYNOPSIS +.B basename +[ +.B -d +] +.I string +[ +.I suffix +] +.SH DESCRIPTION +.PP +.I Basename +deletes any prefix ending in slash +.RB ( / ) +and the +.IR suffix , +if present in +.IR string , +from +.IR string , +and prints the result on the standard output. +.PP +The +.B -d +option instead prints the directory component, +that is, +.I string +up to but not including the final slash. +If the string contains no slash, +a period and newline are printed. +.SH SOURCE +.B /sys/src/cmd/basename.c diff --git a/man/man1/cal.1 b/man/man1/cal.1 new file mode 100644 index 00000000..7ac5b996 --- /dev/null +++ b/man/man1/cal.1 @@ -0,0 +1,46 @@ +.TH CAL 1 +.SH NAME +cal \- print calendar +.SH SYNOPSIS +.B cal +[ +.I month +] +[ +.I year +] +.SH DESCRIPTION +.I Cal +prints a calendar. +.I Month +is either a number from 1 to 12, +a lower case month name, +or a lower case three-letter prefix of a month name. +.I Year +can be between 1 +and 9999. +If either +.I month +or +.I year +is omitted, the current month or year is used. +If only one argument is given, and it is a number larger than 12, +a calendar for all twelve months of the given year is produced; +otherwise a calendar for just one month is printed. +The calendar +produced is that for England and her colonies. +.PP +Try +.EX + cal sep 1752 +.EE +.SH SOURCE +.B /sys/src/cmd/cal.c +.SH BUGS +The year is always considered to start in January even though this +is historically naive. +.br +Beware that +.L "cal 90" +refers to the early Christian era, +not the 20th century. diff --git a/man/man1/calendar.1 b/man/man1/calendar.1 new file mode 100644 index 00000000..e6832d3c --- /dev/null +++ b/man/man1/calendar.1 @@ -0,0 +1,53 @@ +.TH CALENDAR 1 +.SH NAME +calendar \- print upcoming events +.SH SYNOPSIS +.B calendar +[ +.B \-y +] +[ +.B \-p days +] +[ +.I file ... +] +.SH DESCRIPTION +.I Calendar +reads the named files, default +.BR /usr/$user/lib/calendar , +and writes to standard output any lines +containing today's or tomorrow's date. +Examples of recognized date formats are +"4/11", +"April 11", +"Apr 11", +"11 April", +and +"11 Apr". +All comparisons are case insensitive. +.PP +If the +.B \-y +flag is given, an attempt is made to match on year too. In this case, +dates of the forms listed above will be accepted if they are followed +by the current year (or last two digits thereof) or not a year — +digits not followed by white space or non-digits. +.PP +If the +.B \-p +flag is given, its argument is the number of days ahead to match +dates. This flag is not repeatable, and it performs no special +processing at the end of the week. +.PP +On Friday and Saturday, events through Monday are printed. +.PP +To have your calendar mailed to you every day, use +.IR cron (8). +.SH FILES +.TF /usr/$user/lib/calendar +.TP +.B /usr/$user/lib/calendar +personal calendar +.SH SOURCE +.B /sys/src/cmd/calendar.c diff --git a/man/man1/cat.1 b/man/man1/cat.1 new file mode 100644 index 00000000..eeb43bcc --- /dev/null +++ b/man/man1/cat.1 @@ -0,0 +1,86 @@ +.TH CAT 1 +.SH NAME +cat, read \- catenate files +.SH SYNOPSIS +.B cat +[ +.I file ... +] +.br +.B read +[ +.B -m +] [ +.B -n +.I nline +] [ +.I file ... +] +.SH DESCRIPTION +.I Cat +reads each +.I file +in sequence and writes it on the standard output. +Thus +.IP +.L +cat file +.LP +prints a file and +.IP +.L +cat file1 file2 >file3 +.LP +concatenates the first two files and places the result +on the third. +.PP +If no +.I file +is given, +.I cat +reads from the standard input. +Output is buffered in blocks matching the input. +.PP +.I Read +copies to standard output exactly one line from the named +.IR file , +default standard input. +It is useful in interactive +.IR rc (1) +scripts. +.PP +The +.B -m +flag causes it to continue reading and writing multiple lines until end of file; +.B -n +causes it to read no more than +.I nline +lines. +.PP +Read always executes a single +.B write +for each line of input, which can be helpful when +preparing input to programs that expect line-at-a-time data. +It never reads any more data from the input than it prints to the output. +.SH SOURCE +.B /sys/src/cmd/cat.c +.br +.B /sys/src/cmd/read.c +.SH SEE ALSO +.IR cp (1) +.SH DIAGNOSTICS +.I Read +exits with status +.B eof +on end of file or, in the +.B -n +case, if it doesn't read +.I nlines +lines. +.SH BUGS +Beware of +.L "cat a b >a" +and +.LR "cat a b >b" , +which +destroy input files before reading them. diff --git a/man/man1/cleanname.1 b/man/man1/cleanname.1 new file mode 100644 index 00000000..41c06c00 --- /dev/null +++ b/man/man1/cleanname.1 @@ -0,0 +1,32 @@ +.TH CLEANNAME 1 +.SH NAME +cleanname \- clean a path name +.SH SYNOPSIS +.B cleanname +[ +.B -d +.I pwd +] +.I names ... +.SH DESCRIPTION +For each file name argument, +.IR cleanname , +by lexical processing only, +prints the shortest equivalent string that names the same +(possibly hypothetical) file. +It eliminates multiple and trailing slashes, and it lexically +interprets +.B . +and +.B .. +directory components in the name. +If the +.B -d +option is present, +unrooted names are prefixed with +.IB pwd / +before processing. +.SH SOURCE +.B /sys/src/cmd/cleanname.c +.SH SEE ALSO +.IR cleanname (2). diff --git a/man/man1/cmp.1 b/man/man1/cmp.1 new file mode 100644 index 00000000..e48d0766 --- /dev/null +++ b/man/man1/cmp.1 @@ -0,0 +1,57 @@ +.TH CMP 1 +.SH NAME +cmp \- compare two files +.SH SYNOPSIS +.B cmp +[ +.B -lsL +] +.I file1 file2 +[ +.I offset1 +[ +.I offset2 +] +] +.SH DESCRIPTION +The two files are +compared. +A diagnostic results if the contents differ, otherwise +there is no output. +.PP +The options are: +.TP +.B l +Print the byte number (decimal) and the +differing bytes (hexadecimal) for each difference. +.TP +.B s +Print nothing for differing files, +but set the exit status. +.TP +.B L +Print the line number of the first differing byte. +.PP +If offsets are given, +comparison starts at the designated byte position +of the corresponding file. +Offsets that begin with +.B 0x +are hexadecimal; +with +.BR 0 , +octal; with anything else, decimal. +.SH SOURCE +.B /sys/src/cmd/cmp.c +.SH "SEE ALSO" +.IR diff (1) +.SH DIAGNOSTICS +If a file is inaccessible or missing, the exit status is +.LR open . +If the files are the same, the exit status is empty (true). +If they are the same except that one is longer than the other, the exit status is +.LR EOF . +Otherwise +.I cmp +reports the position of the first disagreeing byte and the exit status is +.LR differ . diff --git a/man/man1/comm.1 b/man/man1/comm.1 new file mode 100644 index 00000000..2fd883c0 --- /dev/null +++ b/man/man1/comm.1 @@ -0,0 +1,47 @@ +.TH COMM 1 +.CT 1 files +.SH NAME +comm \- select or reject lines common to two sorted files +.SH SYNOPSIS +.B comm +[ +.B -123 +] +.I file1 file2 +.SH DESCRIPTION +.I Comm +reads +.I file1 +and +.IR file2 , +which are in lexicographical order, +and produces a three column output: lines only in +.IR file1 ; +lines only in +.IR file2 ; +and lines in both files. +The file name +.L - +means the standard input. +.PP +Flag +.LR 1 , +.LR 2 , +or +.LR 3 +suppresses printing of the corresponding +column. +.SH EXAMPLE +.TP +.EX +comm -12 file1 file2 +.EE +.IP +Print lines common to two sorted files. +.SH SOURCE +.B /sys/src/cmd/comm.c +.SH "SEE ALSO" +.IR sort (1), +.IR cmp (1), +.IR diff (1), +.IR uniq (1) diff --git a/man/man1/date.1 b/man/man1/date.1 new file mode 100644 index 00000000..3d232baa --- /dev/null +++ b/man/man1/date.1 @@ -0,0 +1,58 @@ +.TH DATE 1 +.SH NAME +date, clock \- date and time +.SH SYNOPSIS +.B date +[ +.I option +] [ +.I seconds +] +.br +.B clock +.SH DESCRIPTION +Print the date, in the format +.PP +.B + Tue Aug 16 17:03:52 CDT 1977 +.PP +The options are +.TP +.B -u +Report Greenwich Mean Time (GMT) rather than local time. +.TP +.B -n +Report the date as the number of seconds since the +epoch, 00:00:00 GMT, January 1, 1970. +.PP +The conversion from Greenwich Mean Time to local time depends on the +.B $timezone +environment variable; see +.IR ctime (2). +.PP +If the optional argument +.I seconds +is present, it is used as the time to convert rather than +the real time. +.SH FILES +.TF /adm/timezone/local +.TP +.B /env/timezone +Current timezone name and adjustments. +.TP +.B /adm/timezone +A directory containing timezone tables. +.TP +.B /adm/timezone/local +Default timezone file, copied by +.IR init (8) +into +.BR /env/timezone . +.PD +.PP +.I Clock +draws a simple analog clock in its window. +.SH SOURCE +.B /sys/src/cmd/date.c +.br +.B /sys/src/cmd/clock.c diff --git a/man/man1/dc.1 b/man/man1/dc.1 new file mode 100644 index 00000000..0f2c13a5 --- /dev/null +++ b/man/man1/dc.1 @@ -0,0 +1,257 @@ +.TH DC 1 +.SH NAME +dc \- desk calculator +.SH SYNOPSIS +.B dc +[ +.I file +] +.SH DESCRIPTION +.I Dc +is an arbitrary precision desk calculator. +Ordinarily it operates on decimal integers, +but one may specify an input base, output base, +and a number of fractional digits to be maintained. +The overall structure of +.I dc +is +a stacking (reverse Polish) calculator. +If an argument is given, +input is taken from that file until its end, +then from the standard input. +The following constructions are recognized: +.TP +number +The value of the number is pushed on the stack. +A number is an unbroken string of the digits +.B 0-9A-F +or +.BR 0-9a-f . +A hexadecimal number beginning with a lower case +letter must be preceded by a zero to distinguish it +from the command associated with the letter. +It may be preceded by an underscore +.B _ +to input a +negative number. +Numbers may contain decimal points. +.TP +.L ++ - / * % ^ +Add +.LR + , +subtract +.LR - , +multiply +.LR * , +divide +.LR / , +remainder +.LR % , +or exponentiate +.L ^ +the top two values on the stack. +The two entries are popped off the stack; +the result is pushed on the stack in their place. +Any fractional part of an exponent is ignored. +.TP +.BI s x +.br +.ns +.TP +.BI S x +Pop the top of the stack and store into +a register named +.IR x , +where +.I x +may be any character. +Under operation +.B S +register +.I x +is treated as a stack and the value is pushed on it. +.TP +.BI l x +.br +.ns +.TP +.BI L x +Push the value in register +.I x +onto the stack. +The register +.I x +is not altered. +All registers start with zero value. +Under operation +.B L +register +.I x +is treated as a stack and its top value is popped onto the main stack. +.TP +.B d +Duplicate the +top value on the stack. +.TP +.B p +Print the top value on the stack. +The top value remains unchanged. +.B P +interprets the top of the stack as an +text +string, +removes it, and prints it. +.TP +.B f +Print the values on the stack. +.TP +.B q +.br +.ns +.TP +.B Q +Exit the program. +If executing a string, the recursion level is +popped by two. +Under operation +.B Q +the top value on the stack is popped and the string execution level is popped +by that value. +.TP +.B x +Treat the top element of the stack as a character string +and execute it as a string of +.I dc +commands. +.TP +.B X +Replace the number on the top of the stack with its scale factor. +.TP +.B "[ ... ]" +Put the bracketed +text +string on the top of the stack. +.TP +.PD0 +.BI < x +.TP +.BI > x +.TP +.BI = x +.PD +Pop and compare the +top two elements of the stack. +Register +.I x +is executed if they obey the stated +relation. +.TP +.B v +Replace the top element on the stack by its square root. +Any existing fractional part of the argument is taken +into account, but otherwise the scale factor is ignored. +.TP +.B ! +Interpret the rest of the line as a shell command. +.TP +.B c +Clear the stack. +.TP +.B i +The top value on the stack is popped and used as the +number base for further input. +.TP +.B I +Push the input base on the top of the stack. +.TP +.B o +The top value on the stack is popped and used as the +number base for further output. +In bases larger than 10, each `digit' prints as a group of decimal digits. +.TP +.B O +Push the output base on the top of the stack. +.TP +.B k +Pop the top of the stack, and use that value as +a non-negative scale factor: +the appropriate number of places +are printed on output, +and maintained during multiplication, division, and exponentiation. +The interaction of scale factor, +input base, and output base will be reasonable if all are changed +together. +.TP +.B z +Push the stack level onto the stack. +.TP +.B Z +Replace the number on the top of the stack with its length. +.TP +.B ? +A line of input is taken from the input source (usually the terminal) +and executed. +.TP +.B "; :" +Used by +.I bc +for array operations. +.PP +The scale factor set by +.B k +determines how many digits are kept to the right of +the decimal point. +If +.I s +is the current scale factor, +.I sa +is the scale of the first operand, +.I sb +is the scale of the second, +and +.I b +is the (integer) second operand, +results are truncated to the following scales. +.IP +.nf +\fL+\fR,\fL-\fR max(\fIsa,sb\fR) +\fL*\fR min(\fIsa\fR+\fIsb \fR, max\fR(\fIs,sa,sb\fR)) +\fL/\fI s +\fL%\fR so that dividend = divisor*quotient + remainder; remainder has sign of dividend +\fL^\fR min(\fIsa\fR\(mu|\fIb\fR|, max(\fIs,sa\fR)) +\fLv\fR max(\fIs,sa\fR) +.fi +.SH EXAMPLES +.EX +[la1+dsa*pla10>y]sy +0sa1 +lyx +.EE +.ns +.IP +Print the first ten values of +.IR n ! +.SH SOURCE +.B /sys/src/cmd/dc.c +.SH "SEE ALSO" +.IR bc (1), +.IR hoc (1) +.SH DIAGNOSTICS +.I x +.LR "is unimplemented" , +where +.I x +is an octal number: an internal error. +.br +`Out of headers' +for too many numbers being kept around. +.br +`Nesting depth' +for too many levels of nested execution. +.SH BUGS +When the input base exceeds 16, +there is no notation for digits greater than +.BR F . +.PP +Past its time. diff --git a/man/man1/deroff.1 b/man/man1/deroff.1 new file mode 100644 index 00000000..f62b174d --- /dev/null +++ b/man/man1/deroff.1 @@ -0,0 +1,117 @@ +.TH DEROFF 1 +.SH NAME +deroff, delatex \- remove formatting requests +.SH SYNOPSIS +.B deroff +[ +.I option ... +] +.I file ... +.PP +.B delatex +.I file +.SH DESCRIPTION +.I Deroff +reads each file in sequence +and removes all +.I nroff +and +.IR troff (1) +requests and non-text arguments, backslash constructions, +and constructs of preprocessors such as +.IR eqn (1), +.IR pic (1), +and +.IR tbl (1). +Remaining text is written on the standard output. +.I Deroff +follows files included by +.L .so +and +.L .nx +commands; +if a file has already been included, a +.L .so +for that file is ignored and a +.L .nx +terminates execution. +If no input file is given, +.I deroff +reads from standard input. +.PP +The options are +.TP +.B -w +Output a word list, one `word' (string of letters, digits, and +properly embedded ampersands and apostrophes, +beginning with a letter) per line. +Other characters are skipped. +Otherwise, the output follows the original, with the deletions mentioned above. +.TP +.B -_ +Like +.BR -w , +but consider underscores to be alphanumeric rather than punctuation. +.TP +.B -i +Ignore +.L .so +and +.L .nx +requests. +.TP +.BR -ms +.PD0 +.TP +.B -mm +Remove titles, attachments, etc., as well as ordinary +.IR troff +constructs, from +.IR ms (6) +or +.I mm +documents. +.PD +.TP +.B -ml +Same as +.BR -mm , +but remove lists as well. +.PP +.I Delatex +does for +.I tex +and +.I latex +(see +.IR tex (1)) +files what +.B deroff -wi +does for +.I troff +files. +.SH SOURCE +.B /sys/src/cmd/deroff.c +.br +.B /sys/src/cmd/tex/local/delatex.c +.SH "SEE ALSO" +.IR troff (1), +.IR tex (1), +.IR spell (1) +.SH BUGS +These filters are not complete interpreters of +.I troff +or +.IR tex . +For example, macro definitions containing +.L \e$ +cause chaos in +.IR deroff +when the popular +.L $$ +delimiters for +.I eqn +are in effect. +.br +Text inside macros is emitted at place of +definition, not place of call. diff --git a/man/man1/dict.1 b/man/man1/dict.1 new file mode 100644 index 00000000..5fc47634 --- /dev/null +++ b/man/man1/dict.1 @@ -0,0 +1,163 @@ +.TH DICT 7 +.SH NAME +dict \- dictionary browser +.SH SYNOPSIS +.B dict +[ +.B -k +] +[ +.B -d +.I dictname +] +[ +.B -c +.I command +] +[ +.I pattern +] +.SH DESCRIPTION +.I Dict +is a dictionary browser. +If a +.I pattern +is given on the command line, +.I dict +prints all matching entries; +otherwise it repeatedly accepts and executes commands. +The options are +.TF -d\ \fIdictname\fP +.TP +.BI -d " dictname" +Use the given dictionary. +The default is +.BR oed , +the second edition of the Oxford English Dictionary. +A list of available dictionaries is printed by option +.BR -d? . +.TP +.BI -c " command" +Execute one command and quit. +The command syntax is described below. +.TP +.B -k +Print a pronunciation key. +.PD +.PP +Patterns are regular expressions (see +.IR regexp (6)), +with an implicit leading +.L ^ +and trailing +.LR $ . +Patterns are matched against an index of headwords and variants, +to form a `match set'. +By default, both patterns and the index are folded: +upper case characters are mapped into their lower case equivalents, +and Latin accented characters are mapped into their non-accented +equivalents. +In interactive mode, there is always a `current match set' +and a `current entry' within the match set. +Commands can change either or both, as well as print the entries +or information about them. +.PP +Commands have an address followed by a command letter. +Addresses have the form: +.TF /\fIre\fP/.\fIn\fP +.TP +.BI / re / +Set the match set to all entries matching the regular expression +.IR re , +sorted in dictionary order. +Set the current entry to the first of the match set. +.TP +.BI ! re ! +Like +.BI / re / +but use exact matching, i.e., without case and accent folding. +.TP +.I n +An integer +.I n +means change the current entry to the +.IR n th +of the current match set. +.TP +.BI # n +The integer +.I n +is an absolute byte offset into the raw dictionary. +(See the +.B A +command, below.) +.TP +.IB addr + +After setting the match set and current entry according to +.IR addr , +change the match set and current entry to be the next entry +in the dictionary (not necessarily in the match set) after +the current entry. +.TP +.IB addr - +Like +.IB addr + +but go to previous dictionary entry. +.PD +.PP +The command letters come in pairs: a lower case and the +corresponding upper case letter. +The lower case version prints something about the current +entry only, and advances the current entry to the next +in the match set (wrapping around to the beginning after +the last). +The upper case version prints something about all of the +match set and resets the current entry to the beginning of +the set. +.TF \fLa,A\fP +.TP +.BR p , P +Print the whole entry. +.TP +.BR h , H +Print only the headword(s) of the entry. +.TP +.BR a , A +Print the dictionary byte offset of the entry. +.TP +.BR r , R +Print the whole entry in raw format (without translating +special characters, etc.). +.PD +.PP +If no command letter is given for the first command, +.B H +is assumed. +After an +.BR H , +the default command is +.BR p . +Otherwise, the default command is the previous command. +.SH FILES +.B /lib/dict/oed2 +.br +.B /lib/dict/oed2index +.br +Other files in +.BR /lib . +.SH "SEE ALSO" +.IR regexp (6) +.SH SOURCE +.B /sys/src/cmd/dict +.SH BUGS +A font with wide coverage of the Unicode Standard +should be used for best results. +(Try +.BR /lib/font/bit/pelm/unicode.9.font .) +.br +If the +.I pattern +doesn't begin with +a few literal characters, matching takes a long time. +.br +The dictionaries are not distributed outside Bell Labs. diff --git a/man/man1/diff.1 b/man/man1/diff.1 new file mode 100644 index 00000000..404c74f0 --- /dev/null +++ b/man/man1/diff.1 @@ -0,0 +1,155 @@ +.TH DIFF 1 +.SH NAME +diff \- differential file comparator +.SH SYNOPSIS +.B diff +[ +.B -efmnbwr +] file1 ... file2 +.SH DESCRIPTION +.I Diff +tells what lines must be changed in two files to bring them +into agreement. +If one file +is a directory, +then a file in that directory with basename the same as that of +the other file is used. +If both files are directories, similarly named files in the +two directories are compared by the method of +.I diff +for text +files and +.IR cmp (1) +otherwise. +If more than two file names are given, then each argument is compared +to the last argument as above. +The +.B -r +option causes +.I diff +to process similarly named subdirectories recursively. +When processing more than one file, +.I diff +prefixes file differences with a single line +listing the two differing files, in the form of +a +.I diff +command line. +The +.B -m +flag causes this behavior even when processing single files. +.PP +The normal output contains lines of these forms: +.IP "" 5 +.I n1 +.B a +.I n3,n4 +.br +.I n1,n2 +.B d +.I n3 +.br +.I n1,n2 +.B c +.I n3,n4 +.PP +These lines resemble +.I ed +commands to convert +.I file1 +into +.IR file2 . +The numbers after the letters pertain to +.IR file2 . +In fact, by exchanging `a' for `d' and reading backward +one may ascertain equally how to convert +.I file2 +into +.IR file1 . +As in +.IR ed , +identical pairs where +.I n1 += +.I n2 +or +.I n3 += +.I n4 +are abbreviated as a single number. +.PP +Following each of these lines come all the lines that are +affected in the first file flagged by `<', +then all the lines that are affected in the second file +flagged by `>'. +.PP +The +.B -b +option causes +trailing blanks (spaces and tabs) to be ignored +and other strings of blanks to compare equal. +The +.B -w +option causes all white-space to be removed from input lines +before applying the difference algorithm. +.PP +The +.B -n +option prefixes each range with +.IB file : \fR +and inserts a space around the +.BR a , +.BR c , +and +.B d +verbs. +The +.B -e +option produces a script of +.I "a, c" +and +.I d +commands for the editor +.IR ed , +which will recreate +.I file2 +from +.IR file1 . +The +.B -f +option produces a similar script, +not useful with +.IR ed , +in the opposite order. It may, however, be +useful as input to a stream-oriented post-processor. +.PP +Except in rare circumstances, +.I diff +finds a smallest sufficient set of file +differences. +.SH FILES +.B /tmp/diff[12] +.SH SOURCE +.B /sys/src/cmd/diff +.SH "SEE ALSO" +.IR cmp (1), +.IR comm (1), +.IR ed (1) +.SH DIAGNOSTICS +Exit status is the empty string +for no differences, +.L some +for some, +and +.L error +for trouble. +.SH BUGS +Editing scripts produced under the +.BR -e " or" +.BR -f " option are naive about" +creating lines consisting of a single `\fB.\fR'. +.br +When running +.I diff +on directories, the notion of what is a text +file is open to debate. diff --git a/man/man1/echo.1 b/man/man1/echo.1 new file mode 100644 index 00000000..86e6cd39 --- /dev/null +++ b/man/man1/echo.1 @@ -0,0 +1,26 @@ +.TH ECHO 1 +.SH NAME +echo \- print arguments +.SH SYNOPSIS +.B echo +[ +.B -n +] +[ +.I arg ... +] +.SH DESCRIPTION +.I Echo +writes its arguments separated by blanks and terminated by +a newline on the standard output. +Option +.B -n +suppresses the newline. +.SH SOURCE +.B /sys/src/cmd/echo.c +.SH DIAGNOSTICS +If +.I echo +draws an error while writing to standard output, the exit status is +.LR "write error" . +Otherwise the exit status is empty. diff --git a/man/man1/ed.1 b/man/man1/ed.1 new file mode 100644 index 00000000..adb79fb7 --- /dev/null +++ b/man/man1/ed.1 @@ -0,0 +1,683 @@ +.TH ED 1 +.SH NAME +ed \- text editor +.SH SYNOPSIS +.B ed +[ +.B - +] +[ +.B -o +] +[ +.I file +] +.SH DESCRIPTION +.I Ed +is a venerable text editor. +.PP +If a +.I file +argument is given, +.I ed +simulates an +.L e +command (see below) on that file: +it is read into +.I ed's +buffer so that it can be edited. +The options are +.TP +.B - +Suppress the printing +of character counts by +.LR e , +.LR r , +and +.L w +commands and of the confirming +.L ! +by +.L ! +commands. +.TP +.B -o +(for output piping) +Write all output to the standard error file except writing by +.L w +commands. +If no +.I file +is given, make +.B /fd/1 +the remembered file; see the +.L e +command below. +.PP +.I Ed +operates on a `buffer', a copy of the file it is editing; +changes made +in the buffer have no effect on the file until a +.L w +(write) +command is given. +The copy of the text being edited resides +in a temporary file called the +.IR buffer . +.PP +Commands to +.I ed +have a simple and regular structure: zero, one, or +two +.I addresses +followed by a single character +.IR command , +possibly +followed by parameters to the command. +These addresses specify one or more lines in the buffer. +Missing addresses are supplied by default. +.PP +In general, only one command may appear on a line. +Certain commands allow the +addition of text to the buffer. +While +.I ed +is accepting text, it is said +to be in +.I "input mode." +In this mode, no commands are recognized; +all input is merely collected. +Input mode is left by typing a period +.L . +alone at the +beginning of a line. +.PP +.I Ed +supports the +.I "regular expression" +notation described in +.IR regexp (6). +Regular expressions are used in addresses to specify +lines and in one command +(see +.I s +below) +to specify a portion of a line which is to be replaced. +If it is desired to use one of +the regular expression metacharacters as an ordinary +character, that character may be preceded by +.RB ` \e '. +This also applies to the character bounding the regular +expression (often +.LR / ) +and to +.L \e +itself. +.PP +To understand addressing in +.I ed +it is necessary to know that at any time there is a +.I "current line." +Generally, the current line is +the last line affected by a command; however, +the exact effect on the current line +is discussed under the description of +each command. +Addresses are constructed as follows. +.TP +1. +The character +.LR . , +customarily called `dot', +addresses the current line. +.TP +2. +The character +.L $ +addresses the last line of the buffer. +.TP +3. +A decimal number +.I n +addresses the +.IR n -th +line of the buffer. +.TP +4. +.BI \'x +addresses the line marked with the name +.IR x , +which must be a lower-case letter. +Lines are marked with the +.L k +command. +.TP +5. +A regular expression enclosed in slashes ( +.LR / ) +addresses +the line found by searching forward from the current line +and stopping at the first line containing a +string that matches the regular expression. +If necessary the search wraps around to the beginning of the +buffer. +.TP +6. +A regular expression enclosed in queries +.L ? +addresses +the line found by searching backward from the current line +and stopping at the first line containing +a string that matches the regular expression. +If necessary +the search wraps around to the end of the buffer. +.TP +7. +An address followed by a plus sign +.L + +or a minus sign +.L - +followed by a decimal number specifies that address plus +(resp. minus) the indicated number of lines. +The plus sign may be omitted. +.TP +8. +An address followed by +.L + +(or +.LR - ) +followed by a +regular expression enclosed in slashes specifies the first +matching line following (or preceding) that address. +The search wraps around if necessary. +The +.L + +may be omitted, so +.L 0/x/ +addresses the +.I first +line in the buffer with an +.LR x . +Enclosing the regular expression in +.L ? +reverses the search direction. +.TP +9. +If an address begins with +.L + +or +.L - +the addition or subtraction is taken with respect to the current line; +e.g.\& +.L -5 +is understood to mean +.LR .-5 . +.TP +10. +If an address ends with +.L + +or +.LR - , +then 1 is added (resp. subtracted). +As a consequence of this rule and rule 9, +the address +.L - +refers to the line before the current line. +Moreover, +trailing +.L + +and +.L - +characters +have cumulative effect, so +.L -- +refers to the current +line less 2. +.TP +11. +To maintain compatibility with earlier versions of the editor, +the character +.L ^ +in addresses is +equivalent to +.LR - . +.PP +Commands may require zero, one, or two addresses. +Commands which require no addresses regard the presence +of an address as an error. +Commands which accept one or two addresses +assume default addresses when insufficient are given. +If more addresses are given than a command requires, +the last one or two (depending on what is accepted) are used. +.PP +Addresses are separated from each other typically by a comma +.LR , . +They may also be separated by a semicolon +.LR ; . +In this case the current line +is set to +the previous address before the next address is interpreted. +If no address precedes a comma or semicolon, line 1 is assumed; +if no address follows, the last line of the buffer is assumed. +The second address of any two-address sequence +must correspond to a line following the line corresponding to the first address. +.PP +In the following list of +.I ed +commands, the default addresses +are shown in parentheses. +The parentheses are not part of +the address, but are used to show that the given addresses are +the default. +`Dot' means the current line. +.TP +.RB (\|\fL.\fP\|) \|a +.br +.ns +.TP + +.br +.ns +.TP +.B . +Read the given text +and append it after the addressed line. +Dot is left +on the last line input, if there +were any, otherwise at the addressed line. +Address +.L 0 +is legal for this command; text is placed +at the beginning of the buffer. +.TP +.RB (\|\fL.,.\fP\|) \|b [ +- ][\fIpagesize\fP][ pln\fR] +Browse. +Print a `page', normally 20 lines. +The optional +.L + +(default) or +.L - +specifies whether the next or previous +page is to be printed. +The optional +.I pagesize +is the number of lines in a page. +The optional +.LR p , +.LR n , +or +.L l +causes printing in the specified format, initially +.LR p . +Pagesize and format are remembered between +.L b +commands. +Dot is left at the last line displayed. +.TP +.RB (\|\fL.,.\fP\|) \|c +.br +.ns +.TP + +.br +.ns +.TP +.B . +Change. +Delete the addressed lines, then accept input +text to replace these lines. +Dot is left at the last line input; if there were none, +it is left at the line preceding the deleted lines. +.TP +.RB (\|\fL.,.\fP\|) \|d +Delete the addressed lines from the buffer. +Dot is set to the line following the last line deleted, or to +the last line of the buffer if the deleted lines had no successor. +.TP +.BI e " filename" +Edit. +Delete the entire contents of the buffer; +then read the named file into the buffer. +Dot is set to the last line of the buffer. +The number of characters read is typed. +The file name is remembered for possible use in later +.LR e , +.LR r , +or +.L w +commands. +If +.I filename +is missing, the remembered name is used. +.TP +.BI E " filename" +Unconditional +.LR e ; +see +.RL ` q ' +below. +.TP +.BI f " filename" +Print the currently remembered file name. +If +.I filename +is given, +the currently remembered file name is first changed to +.IR filename . +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/\fIcommand\ list\fP +.PD 0 +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/ +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP +.PD +Global. +First mark every line which matches +the given +.IR regular expression . +Then for every such line, execute the +.I command list +with dot initially set to that line. +A single command or the first of multiple commands +appears on the same line with the global command. +All lines of a multi-line list except the last line must end with +.LR \e . +The +.RB \&` \&. \&' +terminating input mode for an +.LR a , +.LR i , +.L c +command may be omitted if it would be on the +last line of the command list. +The commands +.L g +and +.L v +are not permitted in the command list. +Any character other than space or newline may +be used instead of +.L / +to delimit the regular expression. +The second and third forms mean +.BI g/ regular\ expression /p \f1. +.TP +.RB (\| .\| ) \|i +.PD 0 +.TP + +.TP +.B . +Insert the given text before the addressed line. +Dot is left at the last line input, or, if there were none, +at the line before the addressed line. +This command differs from the +.I a +command only in the placement of the +text. +.PD +.TP +.RB (\| .,.+1 \|) \|j +Join the addressed lines into a single line; +intermediate newlines are deleted. +Dot is left at the resulting line. +.TP +.RB (\|\fL.\fP\|) \|k\fIx\fP +Mark the addressed line with name +.IR x , +which must be a lower-case letter. +The address form +.BI \' x +then addresses this line. +.ne 2.5 +.TP +.RB (\|\fL.,.\fP\|) \|l +List. +Print the addressed lines in an unambiguous way: +a tab is printed as +.LR \et , +a backspace as +.LR \eb , +backslashes as +.LR \e\e , +and non-printing characters as +a backslash, an +.LR x , +and four hexadecimal digits. +Long lines are folded, +with the second and subsequent sub-lines indented one tab stop. +If the last character in the line is a blank, +it is followed by +.LR \en . +An +.L l +may be appended, like +.LR p , +to any non-I/O command. +.TP +.RB (\|\fL.,.\fP\|) \|m\fIa +Move. +Reposition the addressed lines after the line +addressed by +.IR a . +Dot is left at the last moved line. +.TP +.RB (\|\fL.,.\fP\|) \|n +Number. +Perform +.LR p , +prefixing each line with its line number and a tab. +An +.L n +may be appended, like +.LR p , +to any non-I/O command. +.TP +.RB (\|\fL.,.\fP\|) \|p +Print the addressed lines. +Dot is left at the last line printed. +A +.L p +appended to any non-I/O command causes the then current line +to be printed after the command is executed. +.TP +.RB (\|\fL.,.\fP\|) \|P +This command is a synonym for +.LR p . +.TP +.B q +Quit the editor. +No automatic write +of a file is done. +A +.L q +or +.L e +command is considered to be in error if the buffer has +been modified since the last +.LR w , +.LR q , +or +.L e +command. +.TP +.B Q +Quit unconditionally. +.TP +.RB ( $ )\|r\ \fIfilename\fP +Read in the given file after the addressed line. +If no +.I filename +is given, the remembered file name is used. +The file name is remembered if there were no +remembered file name already. +If the read is successful, the number of characters +read is printed. +Dot is left at the last line read from the file. +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/ +.PD 0 +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/g +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP +.PD +Substitute. +Search each addressed +line for an occurrence of the specified regular expression. +On each line in which +.I n +matches are found +.RI ( n +defaults to 1 if missing), +the +.IR n th +matched string is replaced by the replacement specified. +If the global replacement indicator +.L g +appears after the command, +all subsequent matches on the line are also replaced. +It is an error for the substitution to fail on all addressed lines. +Any character other than space or newline +may be used instead of +.L / +to delimit the regular expression +and the replacement. +Dot is left at the last line substituted. +The third form means +.BI s n / regular\ expression / replacement\fP/p\f1. +The second +.L / +may be omitted if the replacement is +empty. +.IP +An ampersand +.L & +appearing in the replacement +is replaced by the string matching the regular expression. +The characters +.BI \e n\f1, +where +.I n +is a digit, +are replaced by the text matched by the +.IR n -th +regular subexpression +enclosed between +.L ( +and +.LR ) . +When +nested parenthesized subexpressions +are present, +.I n +is determined by counting occurrences of +.L ( +starting from the left. +.IP +A literal +.LR & , +.LR / , +.L \e +or newline may be included in a replacement +by prefixing it with +.LR \e . +.TP +.RB (\|\fL.,.\fP\|) \|t\|\fIa +Transfer. +Copy the addressed lines +after the line addressed by +.IR a . +Dot is left at the last line of the copy. +.TP +.RB (\|\fL.,.\fP\|) \|u +Undo. +Restore the preceding contents +of the first addressed line (sic), which must be the last line +in which a substitution was made (double sic). +.TP +.RB (\|\fL1,$\fP\|) \|v/\fIregular\ expression\fP/\fIcommand\ list\fP +This command is the same as the global command +.L g +except that the command list is executed with +dot initially set to every line +.I except +those +matching the regular expression. +.TP +.RB (\|\fL1,$\fP\|) \|w " \fIfilename\fP" +Write the addressed lines to +the given file. +If the file does not exist, +it is created with mode 666 (readable and writable by everyone). +If no +.I filename +is given, the remembered file name, if any, is used. +The file name is remembered if there were no +remembered file name already. +Dot is unchanged. +If the write is successful, the number of characters written is +printed. +.TP +.RB (\|\fL1,$\fP\|) \|W " \fIfilename\fP" +Perform +.LR w , +but append to, instead of overwriting, any existing file contents. +.TP +.RB ( $ ) \|= +Print the line number of the addressed line. +Dot is unchanged. +.TP +.BI ! shell\ command +Send the remainder of the line after the +.L ! +to +.IR rc (1) +to be interpreted as a command. +Dot is unchanged. +.TP +.RB (\| .+1 )\| +An address without a command is taken as a +.L p +command. +A terminal +.L / +may be omitted from the address. +A blank line alone is equivalent to +.LR .+1p ; +it is useful +for stepping through text. +.PP +If an interrupt signal +.SM (DEL) +is sent, +.I ed +prints a +.L ? +and returns to its command level. +.PP +When reading a file, +.I ed +discards +.SM NUL +characters +and all characters after the last newline. +.SH FILES +.B /tmp/e* +.br +.B ed.hup +\ \ work is saved here if terminal hangs up +.SH SOURCE +.B /sys/src/cmd/ed.c +.SH "SEE ALSO" +.IR sam (1), +.IR sed (1), +.IR regexp (6) +.SH DIAGNOSTICS +.BI ? name +for inaccessible file; +.L ?TMP +for temporary file overflow; +.L ? +for errors in commands or other overflows. diff --git a/man/man1/factor.1 b/man/man1/factor.1 new file mode 100644 index 00000000..2d9b5a09 --- /dev/null +++ b/man/man1/factor.1 @@ -0,0 +1,66 @@ +.TH FACTOR 1 +.CT 1 numbers +.SH NAME +factor, primes \- factor a number, generate large primes +.SH SYNOPSIS +.B factor +[ +.I number +] +.PP +.B primes +[ +.I start +[ +.I finish +] +] +.SH DESCRIPTION +.I Factor +prints +.I number +and its prime factors, +each repeated the proper number of times. +The number must be positive and less than +.if n 2**54 +.if t 2\u\s754\s0\d +(about +.if n 1.8e16) +.if t 1.8\(mu10\u\s716\s0\d\|). +.PP +If no +.I number +is given, +.I factor +reads a stream of numbers from the standard input and factors them. +It exits on any input not a positive integer. +Maximum running time is proportional to +.if n sqrt(n). +.if t .I \(sr\o'n\(rn'\f1. +.PP +.PP +.I Primes +prints the prime numbers ranging from +.I start +to +.IR finish , +where +.I start +and +.I finish +are positive numbers less than +.if n 2**56. +.if t 2\u\s756\s0\d. +If +.I finish +is missing, +.I primes +prints without end; +if +.I start +is missing, it reads the starting number from the +standard input. +.SH SOURCE +.B /sys/src/cmd/factor.c +.br +.B /sys/src/cmd/primes.c diff --git a/man/man1/fmt.1 b/man/man1/fmt.1 new file mode 100644 index 00000000..51186001 --- /dev/null +++ b/man/man1/fmt.1 @@ -0,0 +1,90 @@ +.TH FMT 1 +.SH NAME +fmt, htmlfmt \- simple text formatters +.SH SYNOPSIS +.B fmt +[ +.I option ... +] +[ +.I file ... +] +.PP +.B htmlfmt +[ +.B -a +] [ +.B -c +.I charset +] [ +.B -u +.I url +] [ +.I file ... +] +.SH DESCRIPTION +.I Fmt +copies the given +.I files +(standard input by default) +to its standard output, filling and indenting lines. +The options are +.TP +.BI -l " n +Output line length is +.IR n , +including indent (default 70). +.TP +.BI -w " n +A synonym for +.BR -l . +.TP +.BI -i " n +Indent +.I n +spaces (default 0). +.TP +.BI -j +Do not join short lines: only fold long lines. +.PP +Empty lines and initial white space in input lines are preserved. +Empty lines are inserted between input files. +.PP +.I Fmt +is idempotent: it leaves already formatted text unchanged. +.PP +.I Htmlfmt +performs a similar service, but accepts as input text formatted with +HTML tags. +It accepts +.IR fmt 's +.B -l +and +.B -w +flags and also: +.TP +.BI -a +Normally +.I htmlfmt +suppresses the contents of form fields and anchors (URLs and image files); this flag +causes it to print them, in square brackets. +.TP +.BI -c " charset +change the default character set from iso-8859-1 to +.IR charset . +This is the character set assumed if there isn't one +specified by the html itself in a directive. +.TP +.BI -u " url +Use +.I url +as the base URL for the document when displaying anchors; sets +.BI -a . +.SH SOURCE +.B /sys/src/cmd/fmt.c +.PP +.B /sys/src/cmd/htmlfmt +.SH BUGS +.I Htmlfmt +makes no attempt to render the two-dimensional geometry of tables; +it just treats the table entries as plain, to-be-formatted text. diff --git a/man/man1/fortune.1 b/man/man1/fortune.1 new file mode 100644 index 00000000..dfae7186 --- /dev/null +++ b/man/man1/fortune.1 @@ -0,0 +1,23 @@ +.TH FORTUNE 1 +.SH NAME +fortune \- sample lines from a file +.SH SYNOPSIS +.B fortune +[ +.I file +] +.SH DESCRIPTION +.I Fortune +prints a one-line aphorism chosen at random. +If a +.I file +is specified, the saying is taken from that file; +otherwise it is selected from +.BR /sys/games/lib/fortunes . +.SH FILES +.B /sys/games/lib/fortunes +.br +.B /sys/games/lib/fortunes.index +\ \ fast lookup table, maintained automatically +.SH SOURCE +.B /sys/src/cmd/fortune.c diff --git a/man/man1/freq.1 b/man/man1/freq.1 new file mode 100644 index 00000000..eee4e295 --- /dev/null +++ b/man/man1/freq.1 @@ -0,0 +1,40 @@ +.TH FREQ 1 +.SH NAME +freq \- print histogram of character frequencies +.SH SYNOPSIS +.B freq +[ +.B -dxocr +] +[ +.I file ... +] +.SH DESCRIPTION +.I Freq +reads the given files (default standard input) +and prints histograms of the character frequencies. +By default, +.I freq +counts each byte as a character; +under the +.B -r +option it instead counts +.SM UTF +sequences, that is, runes. +.PP +Each non-zero entry of the table is printed preceded by the byte value, +in decimal, octal, hex, and +Unicode +character (if printable). +If any options are given, the +.BR -d , +.BR -x , +.BR -o , +.B -c +flags specify a subset of value formats: decimal, hex, octal, and +character, respectively. +.SH SOURCE +.B /sys/src/cmd/freq.c +.SH SEE ALSO +.IR utf (6), +.IR wc (1) diff --git a/man/man1/grep.1 b/man/man1/grep.1 new file mode 100644 index 00000000..a266c494 --- /dev/null +++ b/man/man1/grep.1 @@ -0,0 +1,103 @@ +.TH GREP 1 +.SH NAME +grep \- search a file for a pattern +.SH SYNOPSIS +.B grep +[ +.I option ... +] +.I pattern +[ +.I file ... +] +.SH DESCRIPTION +.I Grep\^ +searches the input +.I files\^ +(standard input default) +for lines that match the +.IR pattern , +a regular expression as defined in +.IR regexp (6) +with the addition of a newline character as an alternative +(substitute for +.BR | ) +with lowest precedence. +Normally, each line matching the pattern is `selected', +and each selected line is copied to the standard output. +The options are +.TP +.B -c +Print only a count of matching lines. +.PD 0 +.TP +.B -h +Do not print file name tags (headers) with output lines. +.TP +.B -e +The following argument is taken as a +.IR pattern . +This option makes it easy to specify patterns that +might confuse argument parsing, such as +.BR -n . +.TP +.B -i +Ignore alphabetic case distinctions. The implementation +folds into lower case all letters in the pattern and input before +interpretation. Matched lines are printed in their original form. +.TP +.B -l +(ell) Print the names of files with selected lines; don't print the lines. +.TP +.B -L +Print the names of files with no selected lines; +the converse of +.BR -l . +.TP +.B -n +Mark each printed line with its line number counted in its file. +.TP +.B -s +Produce no output, but return status. +.TP +.B -v +Reverse: print lines that do not match the pattern. +.TP +.B -f +The pattern argument is the name of a file containing regular +expressions one per line. +.TP +.B -b +Don't buffer the output: write each output line as soon as it is discovered. +.PD +.PP +Output lines are tagged by file name when there is more than one +input file. +(To force this tagging, include +.B /dev/null +as a file name argument.) +.PP +Care should be taken when +using the shell metacharacters +.B $*[^|()=\e +and newline +in +.IR pattern ; +it is safest to enclose the +entire expression +in single quotes +.BR \&\|' \|.\|.\|.\| ' . +An expression starting with '*' +will treat the rest of the expression +as literal characters. +.SH SOURCE +.B /sys/src/cmd/grep +.SH SEE ALSO +.IR ed (1), +.IR awk (1), +.IR sed (1), +.IR sam (1), +.IR regexp (6) +.SH DIAGNOSTICS +Exit status is null if any lines are selected, +or non-null when no lines are selected or an error occurs. diff --git a/man/man1/hoc.1 b/man/man1/hoc.1 new file mode 100644 index 00000000..68a42a6a --- /dev/null +++ b/man/man1/hoc.1 @@ -0,0 +1,144 @@ +.TH HOC 1 +.SH NAME +hoc \- interactive floating point language +.SH SYNOPSIS +.B hoc +[ +.I file ... +] +[ +.B -e +.I expression +] +.SH DESCRIPTION +.I Hoc +interprets a simple language for floating point arithmetic, +at about the level of BASIC, with C-like syntax and +functions. +.PP +The named +.I files +are read and interpreted in order. +If no +.I file +is given or if +.I file +is +.L - +.I hoc +interprets the standard input. +The +.B -e +option allows input to +.I hoc +to be specified on the command line, to be treated as if it appeared in a file. +.PP +.I Hoc +input consists of +.I expressions +and +.IR statements . +Expressions are evaluated and their results printed. +Statements, typically assignments and function or procedure +definitions, produce no output unless they explicitly call +.IR print . +.PP +Variable names have the usual syntax, including +.LR _ ; +the name +.L _ +by itself contains the value of the last expression evaluated. +The variables +.BR E , +.BR PI , +.BR PHI , +.BR GAMMA +and +.B DEG +are predefined; the last is 59.25..., degrees per radian. +.PP +Expressions are formed with these C-like operators, listed by +decreasing precedence. +.TP +.B ^ +exponentiation +.TP +.B ! - ++ -- +.TP +.B * / % +.TP +.B + - +.TP +.B > >= < <= == != +.TP +.B && +.TP +.B || +.TP +.B = += -= *= /= %= +.PP +Built in functions are +.BR abs , +.BR acos , +.BR asin , +.B atan +(one argument), +.BR cos , +.BR cosh , +.BR exp , +.BR int , +.BR log , +.BR log10 , +.BR sin , +.BR sinh , +.BR sqrt , +.BR tan , +and +.BR tanh . +The function +.B read(x) +reads a value into the variable +.B x +and returns 0 at EOF; +the statement +.B print +prints a list of expressions that may include +string constants such as +\fL"hello\en"\f1.\fP +.PP +Control flow statements are +.BR if - else , +.BR while , +and +.BR for , +with braces for grouping. +Newline ends a statement. +Backslash-newline is equivalent to a space. +.PP +Functions and procedures are introduced by the words +.B func +and +.BR proc ; +.B return +is used to return with a value from a function. +.SH EXAMPLES +.EX +func gcd(a, b) { + temp = abs(a) % abs(b) + if(temp == 0) return abs(b) + return gcd(b, temp) +} +for(i=1; i<12; i++) print gcd(i,12) +.EE +.SH SOURCE +.B /sys/src/cmd/hoc +.SH "SEE ALSO" +.IR bc (1), +.IR dc (1) +.br +B. W. Kernighan and R. Pike, +.I +The Unix Programming Environment, +Prentice-Hall, 1984 +.SH BUGS +Error recovery is imperfect within function and procedure definitions. diff --git a/man/man1/idiff.1 b/man/man1/idiff.1 new file mode 100644 index 00000000..5cb22600 --- /dev/null +++ b/man/man1/idiff.1 @@ -0,0 +1,72 @@ +.TH IDIFF 1 +.SH NAME +idiff \- interactive diff +.SH SYNOPSIS +.B idiff +[ +.B -bw +] +.I file1 +.I file2 +.SH DESCRIPTION +.I Idiff +interactively +merges +.I file1 +and +.IR file2 . +Wherever +.I file1 +and +.I file2 +differ, +.I idiff +displays the differences in the style of +.RB `` diff +.RB -n '' +and prompts the user to select a chunk. +Valid responses are: +.TP +.B < +Use the chunk from +.IR file1 . +.TP +.B > +Use the chunk from +.IR file2 . +.TP +.B = +Use the diff output itself. +.TP +.BR q< ", " q> ", " q= +Use the given response for all future questions. +.TP +.BI ! cmd +Execute +.I cmd +and prompt again. +.PP +.I Idiff +invokes +.IR diff (1) +to compare the files. +The +.B -b +and +.B -w +flags +are simply +passed through to +.IR diff . +.SH FILES +.B /tmp/idiff.* +.SH SOURCE +.B /sys/src/cmd/idiff.c +.SH "SEE ALSO +.IR diff (1) +.br +Kernighan and Pike, +.IR "The Unix Programming Environment" , +Prentice-Hall, 1984. +.SH BUGS +This is a poorly-written manual page. diff --git a/man/man1/join.1 b/man/man1/join.1 new file mode 100644 index 00000000..379eec7f --- /dev/null +++ b/man/man1/join.1 @@ -0,0 +1,148 @@ +.TH JOIN 1 +.CT 1 files +.SH NAME +join \- relational database operator +.SH SYNOPSIS +.B join +[ +.I options +] +.I file1 file2 +.SH DESCRIPTION +.I Join +forms, on the standard output, +a join +of the two relations specified by the lines of +.I file1 +and +.IR file2 . +If one of the file names is +.LR - , +the standard input is used. +.PP +.I File1 +and +.I file2 +must be sorted in increasing +.SM ASCII +collating +sequence on the fields +on which they are to be joined, +normally the first in each line. +.PP +There is one line in the output +for each pair of lines in +.I file1 +and +.I file2 +that have identical join fields. +The output line normally consists of the common field, +then the rest of the line from +.IR file1 , +then the rest of the line from +.IR file2 . +.PP +Input fields are normally separated spaces or tabs; +output fields by space. +In this case, multiple separators count as one, and +leading separators are discarded. +.PP +The following options are recognized, with POSIX syntax. +.TP +.BI -a " n +In addition to the normal output, +produce a line for each unpairable line in file +.IR n , +where +.I n +is 1 or 2. +.TP +.BI -v " n +Like +.BR -a , +omitting output for paired lines. +.TP +.BI -e " s +Replace empty output fields by string +.IR s . +.TP +.BI -1 " m +.br +.ns +.TP +.BI -2 " m +Join on the +.IR m th +field of +.I file1 +or +.IR file2 . +.TP +.BI -j "n m" +Archaic equivalent for +.BI - n " m"\f1. +.TP +.BI -o fields +Each output line comprises the designated fields. +The comma-separated field designators are either +.BR 0 , +meaning the join field, or have the form +.IR n . m , +where +.I n +is a file number and +.I m +is a field number. +Archaic usage allows separate arguments for field designators. +.PP +.TP +.BI -t c +Use character +.I c +as the only separator (tab character) on input and output. +Every appearance of +.I c +in a line is significant. +.SH EXAMPLES +.TP +.L +sort -t: +1 /adm/users | join -t: -1 2 -a 1 -e "" - bdays +Add birthdays to the +.B /adm/users +file, leaving unknown +birthdays empty. +The layout of +.B /adm/users +is given in +.IR users (6); +.B bdays +contains sorted lines like +.LR "ken:Feb\ 4,\ 1953" . +.TP +.L +tr : ' ' temp +.br +.ns +.TP +.L +join -1 3 -2 3 -o 1.1,2.1 temp temp | awk '$1 < $2' +Print all pairs of users with identical userids. +.SH SOURCE +.B /sys/src/cmd/join.c +.SH "SEE ALSO" +.IR sort (1), +.IR comm (1), +.IR awk (1) +.SH BUGS +With default field separation, +the collating sequence is that of +.BI "sort -b" +.BI -k y , y\f1; +with +.BR -t , +the sequence is that of +.BI "sort -t" x +.BI -k y , y\f1. +.br +One of the files must be randomly accessible. + diff --git a/man/man1/ls.1 b/man/man1/ls.1 new file mode 100644 index 00000000..e33f7273 --- /dev/null +++ b/man/man1/ls.1 @@ -0,0 +1,162 @@ +.TH LS 1 +.SH NAME +ls, lc \- list contents of directory +.SH SYNOPSIS +.B ls +[ +.B -dlmnpqrstuFQ +] +.I name ... +.PP +.B lc +[ +.B -dlmnqrstuFQ +] +.I name ... +.SH DESCRIPTION +For each directory argument, +.I ls +lists the contents of the directory; +for each file argument, +.I ls +repeats its name and any other information requested. +When no argument is given, the current directory is listed. +By default, the output is sorted alphabetically by name. +.PP +.I Lc +is the same as +.IR ls , +but sets the +.B -p +option and pipes the output through +.IR mc (1). +.PP +There are a number of options: +.TP +.B -d +If argument is a directory, list it, not +its contents. +.TP +.B -l +List in long format, giving mode (see below), file system type +(e.g., for devices, the +.B # +code letter that names it; see +.IR intro (3)), +the instance or subdevice number, owner, group, +size in bytes, and time of last modification +for each file. +.TP +.B -m +List the name of the user who most recently modified the file. +.TP +.B -n +Don't sort the listing. +.TP +.B -p +Print only the final path element of each file name. +.TP +.B -q +List the +.I qid +(see +.IR stat (2)) +of each file; the printed fields are in the order +path, version, and type. +.TP +.B -r +Reverse the order of sort. +.TP +.B -s +Give size in Kbytes for each entry. +.TP +.B -t +Sort by time modified (latest first) instead of +by name. +.TP +.B -u +Under +.B -t +sort by time of last access; +under +.B -l +print time of last access. +.TP +.B -F +Add the character +.B / +after all directory names +and the character +.B * +after all executable files. +.TP +.B -L +Print the character +.B t +before each file if it has the temporary flag set, and +.B - +otherwise. +.TP +.B -Q +By default, printed file names are quoted if they contain characters special to +.IR rc (1). +The +.B -Q +flag disables this behavior. +.PP +The mode printed under the +.B -l +option contains 11 characters, +interpreted +as follows: +the first character is +.TP +.B d +if the entry is a directory; +.PD 0 +.TP +.B a +if the entry is an append-only file; +.TP +.B - +if the entry is a plain file. +.PD +.PP +The next letter is +.B l +if the file is exclusive access (one writer or reader at a time). +.PP +The last 9 characters are interpreted +as three sets of three bits each. +The first set refers to owner permissions; +the next to permissions to others in the same user-group; +and the last to all others. +Within each set the three characters indicate +permission respectively to read, to write, or to +execute the file as a program. +For a directory, `execute' permission is interpreted +to mean permission to search the directory +for a specified file. +The permissions are indicated as follows: +.TP 3 +.B r +if the file is readable; +.PD 0 +.TP 3 +.B w +if the file is writable; +.TP 3 +.B x +if the file is executable; +.TP 3 +.B - +if none of the above permissions is granted. +.PD +.SH SOURCE +.B /sys/src/cmd/ls.c +.br +.B /rc/bin/lc +.SH SEE ALSO +.IR stat (2) +.IR mc (1) + diff --git a/man/man1/mc.1 b/man/man1/mc.1 new file mode 100644 index 00000000..c53bcca3 --- /dev/null +++ b/man/man1/mc.1 @@ -0,0 +1,40 @@ +.TH MC 1 +.SH NAME +mc \- multicolumn print +.SH SYNOPSIS +.B mc +[ +.B - +] +[ +.BI - N +] +[ +.I file ... +] +.SH DESCRIPTION +.I Mc +splits the input into as many columns as will fit in +.I N +print positions. +If run in a +.IR rio (1) +window, the default +.I N +is the number of blanks that will fit across the window; +otherwise the default +.I N +is 80. +Under option +.B - +each input line ending in a colon +.L : +is printed separately. +.SH SOURCE +.B /sys/src/cmd/mc.c +.SH "SEE ALSO" +.IR rio (1), +.IR pr (1), +.I lc +in +.IR ls (1) diff --git a/man/man1/mkdir.1 b/man/man1/mkdir.1 new file mode 100644 index 00000000..89e53eaa --- /dev/null +++ b/man/man1/mkdir.1 @@ -0,0 +1,35 @@ +.TH MKDIR 1 +.SH NAME +mkdir \- make a directory +.SH SYNOPSIS +.B mkdir +[ +.B -p +] +.I dirname ... +.SH DESCRIPTION +.I Mkdir +creates the specified directories. +It +requires write permission in the parent directory. +.PP +If the +.B -p +flag is given, +.I mkdir +creates any necessary parent directories +and does not complain if the target directory already exists. +.SH "SEE ALSO" +.IR rm (1) +.br +.IR cd +in +.IR rc (1) +.SH SOURCE +.B /sys/src/cmd/mkdir.c +.SH DIAGNOSTICS +.I Mkdir +returns null exit status if all directories were successfully made. +Otherwise it prints a diagnostic and returns +.B \&"error" +status. diff --git a/man/man1/plumb.1 b/man/man1/plumb.1 new file mode 100644 index 00000000..6c51d68b --- /dev/null +++ b/man/man1/plumb.1 @@ -0,0 +1,92 @@ +.TH PLUMB 1 +.SH NAME +plumb \- send message to plumber +.SH SYNOPSIS +.B plumb +[ +.B -p +.I plumbfile +] [ +.B -a +.I attributes +] [ +.B -s +.I source +] [ +.B -d +.I destination +] [ +.B -t +.I type +] [ +.B -w +.I directory +] +.B -i +| +.I data... +.SH DESCRIPTION +The +.I plumb +command formats and sends a plumbing message whose data +is, by default, the concatenation of the argument strings separated by blanks. +The options are: +.TP +.B -p +write the message to +.I plumbfile +(default +.BR /mnt/plumb/send ). +.TP +.B -a +set the +.B attr +field of the message (default is empty). +.TP +.B -s +set the +.B src +field of the message (default is +.BR plumb ). +.TP +.B -d +set the +.B dst +field of the message (default is empty). +.TP +.B -t +set the +.B type +field of the message (default is +.BR text ). +.TP +.B -w +set the +.B wdir +field of the message (default is the current working directory of +.IR plumb ). +.TP +.B -i +take the data from standard input rather than the argument strings. +If an +.B action= +attribute is not otherwise specified, +.I plumb +will add an +.B action=showdata +attribute to the message. +.SH FILES +.TF /usr/$user/lib/plumbing +.TP +.B /usr/$user/lib/plumbing +default rules file +.TP +.B /mnt/plumb +mount point for +.IR plumber (4). +.SH SOURCE +.B /sys/src/cmd/plumb +.SH "SEE ALSO" +.IR plumb (2), +.IR plumber (4), +.IR plumb (6) diff --git a/man/man1/rc.1 b/man/man1/rc.1 new file mode 100644 index 00000000..b296a48a --- /dev/null +++ b/man/man1/rc.1 @@ -0,0 +1,959 @@ +.TH RC 1 +.SH NAME +rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ \- command language +.SH SYNOPSIS +.B rc +[ +.B -srdiIlxepvV +] +[ +.B -c command +] +[ +.I file +[ +.I arg ... +]] +.SH DESCRIPTION +.I Rc +is the Plan 9 shell. +It executes command lines read from a terminal or a file or, with the +.B -c +flag, from +.I rc's +argument list. +.SS Command Lines +A command line is a sequence of commands, separated by ampersands or semicolons +.RB ( & +or +.BR ; ), +terminated by a newline. +The commands are executed in sequence +from left to right. +.I Rc +does not wait for a command followed by +.B & +to finish executing before starting +the following command. +Whenever a command followed by +.B & +is executed, its process id is assigned to the +.I rc +variable +.BR $apid . +Whenever a command +.I not +followed by +.B & +exits or is terminated, the +.I rc +variable +.B $status +gets the process's wait message (see +.IR wait (2)); +it will be the null string if the command was successful. +.PP +A long command line may be continued on subsequent lines by typing +a backslash +.RB ( \e ) +followed by a newline. +This sequence is treated as though it were a blank. +Backslash is not otherwise a special character. +.PP +A number-sign +.RB ( # ) +and any following characters up to (but not including) the next newline +are ignored, except in quotation marks. +.SS Simple Commands +A simple command is a sequence of arguments interspersed with I/O redirections. +If the first argument is the name of an +.I rc +function or of one of +.I rc's +built-in commands, it is executed by +.IR rc . +Otherwise if the name starts with a slash +.RB ( / ), +it must be the path name of the program to be executed. +Names containing no initial slash are searched for in +a list of directory names stored in +.BR $path . +The first executable file of the given name found +in a directory in +.B $path +is the program to be executed. +To be executable, the user must have execute permission (see +.IR stat (2)) +and the file must be either an executable binary +for the current machine's CPU type, or a shell script. +Shell scripts begin with a line containing the full path name of a shell +(usually +.BR /bin/rc ), +prefixed by +.LR #! . +.PP +The first word of a simple command cannot be a keyword unless it is +quoted or otherwise disguised. +The keywords are +.EX + for in while if not switch fn ~ ! @ +.EE +.SS Arguments and Variables +A number of constructions may be used where +.I rc's +syntax requires an argument to appear. +In many cases a construction's +value will be a list of arguments rather than a single string. +.PP +The simplest kind of argument is the unquoted word: +a sequence of one or more characters none of which is a blank, tab, +newline, or any of the following: +.EX + # ; & | ^ $ = ` ' { } ( ) < > +.EE +An unquoted word that contains any of the characters +.B * +.B ? +.B [ +is a pattern for matching against file names. +The character +.B * +matches any sequence of characters, +.B ? +matches any single character, and +.BI [ class ] +matches any character in the +.IR class . +If the first character of +.I class +is +.BR ~ , +the class is complemented. +The +.I class +may also contain pairs of characters separated by +.BR - , +standing for all characters lexically between the two. +The character +.B / +must appear explicitly in a pattern, as must the +first character of the path name components +.B . +and +.BR .. . +A pattern is replaced by a list of arguments, one for each path name matched, +except that a pattern matching no names is not replaced by the empty list, +but rather stands for itself. +Pattern matching is done after all other +operations. +Thus, +.EX + x=/tmp echo $x^/*.c +.EE +matches +.BR /tmp/*.c , +rather than matching +.B "/*.c +and then prefixing +.BR /tmp . +.PP +A quoted word is a sequence of characters surrounded by single quotes +.RB ( ' ). +A single quote is represented in a quoted word by a pair of quotes +.RB ( '' ). +.PP +Each of the following is an argument. +.PD 0 +.HP +.BI ( arguments ) +.br +The value of a sequence of arguments enclosed in parentheses is +a list comprising the members of each element of the sequence. +Argument lists have no recursive structure, although their syntax may +suggest it. +The following are entirely equivalent: +.EX + echo hi there everybody + ((echo) (hi there) everybody) +.EE +.HP +.BI $ argument +.HP +.BI $ argument ( subscript ) +.br +The +.I argument +after the +.B $ +is the name of a variable whose value is substituted. +Multiple levels +of indirection are possible, but of questionable utility. +Variable values +are lists of strings. +If +.I argument +is a number +.IR n , +the value is the +.IR n th +element of +.BR $* , +unless +.B $* +doesn't have +.I n +elements, in which case the value is empty. +If +.I argument +is followed by a parenthesized list of subscripts, the +value substituted is a list composed of the requested elements (origin 1). +The parenthesis must follow the variable name with no spaces. +Assignments to variables are described below. +.HP +.BI $# argument +.br +The value is the number of elements in the named variable. +A variable +never assigned a value has zero elements. +.HP +$"\c +.I argument +.br +The value is a single string containing the components of the named variable +separated by spaces. A variable with zero elements yields the empty string. +.HP +.BI `{ command } +.br +.I rc +executes the +.I command +and reads its standard output, splitting it into a list of arguments, +using characters in +.B $ifs +as separators. +If +.B $ifs +is not otherwise set, its value is +.BR "'\ \et\en'" . +.HP +.BI <{ command } +.HP +.BI >{ command } +.br +The +.I command +is executed asynchronously with its standard output or standard input +connected to a pipe. +The value of the argument is the name of a file +referring to the other end of the pipe. +This allows the construction of +non-linear pipelines. +For example, the following runs two commands +.B old +and +.B new +and uses +.B cmp +to compare their outputs +.EX + cmp <{old} <{new} +.EE +.HP +.IB argument ^ argument +.br +The +.B ^ +operator concatenates its two operands. +If the two operands +have the same number of components, they are concatenated pairwise. +If not, +then one operand must have one component, and the other must be non-empty, +and concatenation is distributive. +.PD +.SS Free Carets +In most circumstances, +.I rc +will insert the +.B ^ +operator automatically between words that are not separated by white space. +Whenever one of +.B $ +.B ' +.B ` +follows a quoted or unquoted word or an unquoted word follows a quoted word +with no intervening blanks or tabs, +a +.B ^ +is inserted between the two. +If an unquoted word immediately follows a +.BR $ +and contains a character other than an alphanumeric, underscore, +or +.BR * , +a +.B ^ +is inserted before the first such character. +Thus +.IP +.B cc -$flags $stem.c +.LP +is equivalent to +.IP +.B cc -^$flags $stem^.c +.SS I/O Redirections +The sequence +.BI > file +redirects the standard output file (file descriptor 1, normally the +terminal) to the named +.IR file ; +.BI >> file +appends standard output to the file. +The standard input file (file descriptor 0, also normally the terminal) +may be redirected from a file by the sequence +.BI < file \f1, +or from an inline `here document' +by the sequence +.BI << eof-marker\f1. +The contents of a here document are lines of text taken from the command +input stream up to a line containing nothing but the +.IR eof-marker , +which may be either a quoted or unquoted word. +If +.I eof-marker +is unquoted, variable names of the form +.BI $ word +have their values substituted from +.I rc's +environment. +If +.BI $ word +is followed by a caret +.RB ( ^ ), +the caret is deleted. +If +.I eof-marker +is quoted, no substitution occurs. +.PP +Redirections may be applied to a file-descriptor other than standard input +or output by qualifying the redirection operator +with a number in square brackets. +For example, the diagnostic output (file descriptor 2) +may be redirected by writing +.BR "cc junk.c >[2]junk" . +.PP +A file descriptor may be redirected to an already open descriptor by writing +.BI >[ fd0 = fd1 ] +or +.BI <[ fd0 = fd1 ]\f1. +.I Fd1 +is a previously opened file descriptor and +.I fd0 +becomes a new copy (in the sense of +.IR dup (2)) +of it. +A file descriptor may be closed by writing +.BI >[ fd0 =] +or +.BI <[ fd0 =]\f1. +.PP +Redirections are executed from left to right. +Therefore, +.B cc junk.c >/dev/null >[2=1] +and +.B cc junk.c >[2=1] >/dev/null +have different effects: the first puts standard output in +.BR /dev/null +and then puts diagnostic output in the same place, where the second +directs diagnostic output to the terminal and sends standard output to +.BR /dev/null . +.SS Compound Commands +A pair of commands separated by a pipe operator +.RB ( | ) +is a command. +The standard output of the left command is sent through a pipe +to the standard input of the right command. +The pipe operator may be decorated +to use different file descriptors. +.BI |[ fd ] +connects the output end of the pipe to file descriptor +.I fd +rather than 1. +.BI |[ fd0 = fd1 ] +connects output to +.I fd1 +of the left command and input to +.I fd0 +of the right command. +.PP +A pair of commands separated by +.B && +or +.B || +is a command. +In either case, the left command is executed and its exit status examined. +If the operator is +.B && +the right command is executed if the left command's status is null. +.B || +causes the right command to be executed if the left command's status is non-null. +.PP +The exit status of a command may be inverted (non-null is changed to null, null +is changed to non-null) by preceding it with a +.BR ! . +.PP +The +.B | +operator has highest precedence, and is left-associative (i.e. binds tighter +to the left than the right). +.B ! +has intermediate precedence, and +.B && +and +.B || +have the lowest precedence. +.PP +The unary +.B @ +operator, with precedence equal to +.BR ! , +causes its operand to be executed in a subshell. +.PP +Each of the following is a command. +.PD 0 +.HP +.B if ( +.I list +.B ) +.I command +.br +A +.I list +is a sequence of commands, separated by +.BR & , +.BR ; , +or newline. +It is executed and +if its exit status is null, the +.I command +is executed. +.HP +.B if not +.I command +.br +The immediately preceding command must have been +.BI if( list ) +.IR command . +If its condition was non-zero, the +.I command +is executed. +.HP +.BI for( name +.B in +.IB arguments ) +.I command +.HP +.BI for( name ) +.I command +.br +The +.I command +is executed once for each +.IR argument +with that argument assigned to +.IR name . +If the argument list is omitted, +.B $* +is used. +.HP +.BI while( list ) +.I command +.br +The +.I list +is executed repeatedly until its exit status is non-null. +Each time it returns null status, the +.I command +is executed. +An empty +.I list +is taken to give null status. +.HP +.BI "switch(" argument "){" list } +.br +The +.IR list +is searched for simple commands beginning with the word +.BR case . +(The search is only at the `top level' of the +.IR list . +That is, +.B cases +in nested constructs are not found.) +.I Argument +is matched against each word following +.B case +using the pattern-matching algorithm described above, except that +.B / +and the first characters of +.B . +and +.B .. +need not be matched explicitly. +When a match is found, commands in the list are executed up to the next +following +.B case +command (at the top level) or the closing brace. +.HP +.BI { list } +.br +Braces serve to alter the grouping of commands implied by operator +priorities. +The +.I body +is a sequence of commands separated by +.BR & , +.BR ; , +or newline. +.HP +.BI "fn " name { list } +.HP +.BI "fn " name +.br +The first form defines a function with the given +.IR name . +Subsequently, whenever a command whose first argument is +.I name +is encountered, the current value of +the remainder of the command's argument list will be assigned to +.BR $* , +after saving its current value, and +.I rc +will execute the +.IR list . +The second form removes +.IR name 's +function definition. +.HP +.BI "fn " note { list } +.br +.HP +.BI "fn " note +.br +A function with a special name will be called when +.I rc +receives a corresponding note; see +.IR notify (2). +The valid note names (and corresponding notes) are +.B sighup +.RB ( hangup ), +.B sigint +.RB ( interrupt ), +.BR sigalrm +.RB ( alarm ), +and +.B sigfpe +(floating point trap). +By default +.I rc +exits on receiving any signal, except when run interactively, +in which case interrupts and quits normally cause +.I rc +to stop whatever it's doing and start reading a new command. +The second form causes +.I rc +to handle a signal in the default manner. +.I Rc +recognizes an artificial note, +.BR sigexit , +which occurs when +.I rc +is about to finish executing. +.HP +.IB name = "argument command" +.br +Any command may be preceded by a sequence of assignments +interspersed with redirections. +The assignments remain in effect until the end of the command, unless +the command is empty (i.e. the assignments stand alone), in which case +they are effective until rescinded by later assignments. +.PD +.SS Built-in Commands +These commands are executed internally by +.IR rc , +usually because their execution changes or depends on +.IR rc 's +internal state. +.PD 0 +.HP +.BI . " file ..." +.br +Execute commands from +.IR file . +.B $* +is set for the duration to the remainder of the argument list following +.IR file . +.I File +is searched for using +.BR $path . +.HP +.BI builtin " command ..." +.br +Execute +.I command +as usual except that any function named +.I command +is ignored in favor of the built-in meaning. +.HP +.BI "cd [" dir "]" +.br +Change the current directory to +.IR dir . +The default argument is +.BR $home . +.I dir +is searched for in each of the directories mentioned in +.BR $cdpath . +.HP +.BI "eval [" "arg ..." "]" +.br +The arguments are concatenated separated by spaces into a single string, +read as input to +.IR rc , +and executed. +.HP +.BI "exec [" "command ..." "]" +.br +This instance of +.I rc +replaces itself with the given (non-built-in) +.IR command . +.HP +.BI "flag " f " [+-]" +.br +Either set +.RB ( + ), +clear +.RB ( - ), +or test (neither +.B + +nor +.BR - ) +the flag +.IR f , +where +.I f +is a single character, one of the command line flags (see Invocation, below). +.HP +.BI "exit [" status "]" +.br +Exit with the given exit status. +If none is given, the current value of +.B $status +is used. +.HP +.BR "rfork " [ nNeEsfFm ] +.br +Become a new process group using +.BI rfork( flags ) +where +.I flags +is composed of the bitwise OR of the +.B rfork +flags specified by the option letters +(see +.IR fork (2)). +If no +.I flags +are given, they default to +.BR ens . +The +.I flags +and their meanings are: +.B n +is +.BR RFNAMEG ; +.B N +is +.BR RFCNAMEG ; +.B e +is +.BR RFENVG ; +.B E +is +.BR RFCENVG ; +.B s +is +.BR RFNOTEG ; +.B f +is +.BR RFFDG ; +.B F +is +.BR RFCFDG ; +and +.B m +is +.BR RFNOMNT . +.HP +.BI "shift [" n "]" +.br +Delete the first +.IR n +(default 1) +elements of +.BR $* . +.HP +.BI "wait [" pid "]" +.br +Wait for the process with the given +.I pid +to exit. +If no +.I pid +is given, all outstanding processes are waited for. +.HP +.BI whatis " name ..." +.br +Print the value of each +.I name +in a form suitable for input to +.IR rc . +The output is +an assignment to any variable, +the definition of any function, +a call to +.B builtin +for any built-in command, or +the completed pathname of any executable file. +.HP +.BI ~ " subject pattern ..." +.br +The +.I subject +is matched against each +.I pattern +in sequence. +If it matches any pattern, +.B $status +is set to zero. +Otherwise, +.B $status +is set to one. +Patterns are the same as for file name matching, except that +.B / +and the first character of +.B . +and +.B .. +need not be matched explicitly. +The +.I patterns +are not subjected to +file name matching before the +.B ~ +command is executed, so they need not be enclosed in quotation marks. +.PD +.SS Environment +The +.I environment +is a list of strings made available to executing binaries by the +.B env +device +(see +.IR env (3)). +.I Rc +creates an environment entry for each variable whose value is non-empty, +and for each function. +The string for a variable entry has the variable's name followed by +.B = +and its value. +If the value has more than one component, these +are separated by ctrl-a +.RB ( '\e001' ) +characters. +The string for a function is just the +.I rc +input that defines the function. +The name of a function in the environment is the function name +preceded by +.LR fn# . +.PP +When +.I rc +starts executing it reads variable and function definitions from its +environment. +.SS Special Variables +The following variables are set or used by +.IR rc . +.PD 0 +.TP \w'\fL$promptXX'u +.B $* +Set to +.IR rc 's +argument list during initialization. +Whenever a +.B . +command or a function is executed, the current value is saved and +.B $* +receives the new argument list. +The saved value is restored on completion of the +.B . +or function. +.TP +.B $apid +Whenever a process is started asynchronously with +.BR & , +.B $apid +is set to its process id. +.TP +.B $home +The default directory for +.BR cd . +.TP +.B $ifs +The input field separators used in backquote substitutions. +If +.B $ifs +is not set in +.IR rc 's +environment, it is initialized to blank, tab and newline. +.TP +.B $path +The search path used to find commands and input files +for the +.B . +command. +If not set in the environment, it is initialized by +.BR "path=(.\ /bin)" . +Its use is discouraged; instead use +.IR bind (1) +to build a +.B /bin +containing what's needed. +.TP +.B $pid +Set during initialization to +.IR rc 's +process id. +.TP +.B $prompt +When +.I rc +is run interactively, the first component of +.B $prompt +is printed before reading each command. +The second component is printed whenever a newline is typed and more lines +are required to complete the command. +If not set in the environment, it is initialized by +.BR "prompt=('%\ '\ '\ ')" . +.TP +.B $status +Set to the wait message of the last-executed program. +(unless started with +.BR &). +.B ! +and +.B ~ +also change +.BR $status . +Its value is used to control execution in +.BR && , +.BR || , +.B if +and +.B while +commands. +When +.I rc +exits at end-of-file of its input or on executing an +.B exit +command with no argument, +.B $status +is its exit status. +.PD +.SS Invocation +If +.I rc +is started with no arguments it reads commands from standard input. +Otherwise its first non-flag argument is the name of a file from which +to read commands (but see +.B -c +below). +Subsequent arguments become the initial value of +.BR $* . +.I Rc +accepts the following command-line flags. +.PD 0 +.TP \w'\fL-c\ \fIstring\fLXX'u +.BI -c " string" +Commands are read from +.IR string . +.TP +.B -s +Print out exit status after any command where the status is non-null. +.TP +.B -e +Exit if +.B $status +is non-null after executing a simple command. +.TP +.B -i +If +.B -i +is present, or +.I rc +is given no arguments and its standard input is a terminal, +it runs interactively. +Commands are prompted for using +.BR $prompt . +.TP +.B -I +Makes sure +.I rc +is not run interactively. +.TP +.B -l +If +.B -l +is given or the first character of argument zero is +.BR - , +.I rc +reads commands from +.BR $home/lib/profile , +if it exists, before reading its normal input. +.TP +.B -p +A no-op. +.TP +.B -d +A no-op. +.TP +.B -v +Echo input on file descriptor 2 as it is read. +.TP +.B -x +Print each simple command before executing it. +.TP +.B -r +Print debugging information (internal form of commands +as they are executed). +.PD +.SH SOURCE +.B /sys/src/cmd/rc +.SH "SEE ALSO" +Tom Duff, +``Rc \- The Plan 9 Shell''. +.SH BUGS +There should be a way to match patterns against whole lists rather than +just single strings. +.br +Using +.B ~ +to check the value of +.B $status +changes +.BR $status . +.br +Functions that use here documents don't work. +.br +Free carets don't get inserted next to keywords. diff --git a/man/man1/rm.1 b/man/man1/rm.1 new file mode 100644 index 00000000..c5786f92 --- /dev/null +++ b/man/man1/rm.1 @@ -0,0 +1,28 @@ +.TH RM 1 +.SH NAME +rm \- remove files +.SH SYNOPSIS +.B rm +[ +.B -fr +] +.I file ... +.SH DESCRIPTION +.I Rm +removes files or directories. +A directory is removed only if it is empty. +Removal of a file requires write permission in its directory, +but neither read nor write permission on the file itself. +The options are +.TP +.B -f +Don't report files that can't be removed. +.TP +.B -r +Recursively delete the +entire contents of a directory +and the directory itself. +.SH SOURCE +.B /sys/src/cmd/rm.c +.SH "SEE ALSO" +.IR remove (2) diff --git a/man/man1/sam.1 b/man/man1/sam.1 new file mode 100644 index 00000000..0ba20335 --- /dev/null +++ b/man/man1/sam.1 @@ -0,0 +1,885 @@ +.TH SAM 1 +.ds a \fR*\ \fP +.SH NAME +sam, B, sam.save \- screen editor with structural regular expressions +.SH SYNOPSIS +.B sam +[ +.I option ... +] [ +.I files +] +.PP +.B sam +.B -r +.I machine +.PP +.B sam.save +.PP +.B B +[ +.BI -nnnn +] +.I file ... +.SH DESCRIPTION +.I Sam +is a multi-file editor. +It modifies a local copy of an external file. +The copy is here called a +.IR file . +The files are listed in a menu available through mouse button 3 +or the +.B n +command. +Each file has an associated name, usually the name of the +external file from which it was read, and a `modified' bit that indicates whether +the editor's file agrees with the external file. +The external file is not read into +the editor's file until it first becomes the current file\(emthat to +which editing commands apply\(emwhereupon its menu entry is printed. +The options are +.TF -rmachine +.TP +.B -d +Do not `download' the terminal part of +.IR sam . +Editing will be done with the command language only, as in +.IR ed (1). +.TP +.BI -r " machine +Run the host part remotely +on the specified machine, the terminal part locally. +.TP +.BI -s " path +Start the host part from the specified file on the remote host. +Only meaningful with the +.BI -r +option. +.TP +.BI -t " path +Start the terminal part from the specified file. Useful +for debugging. +.PD +.SS Regular expressions +Regular expressions are as in +.IR regexp (6) +with the addition of +.BR \en +to represent newlines. +A regular expression may never contain a literal newline character. +The empty +regular expression stands for the last complete expression encountered. +A regular expression in +.I sam +matches the longest leftmost substring formally +matched by the expression. +Searching in the reverse direction is equivalent +to searching backwards with the catenation operations reversed in +the expression. +.SS Addresses +An address identifies a substring in a file. +In the following, `character +.IR n ' +means the null string +after the +.IR n -th +character in the file, with 1 the +first character in the file. +`Line +.IR n ' +means the +.IR n -th +match, +starting at the beginning of the file, of the regular expression +.LR .*\en? . +All files always have a current substring, called dot, +that is the default address. +.SS Simple Addresses +.PD 0 +.TP +.BI # n +The empty string after character +.IR n ; +.B #0 +is the beginning of the file. +.TP +.I n +Line +.IR n ; +.B 0 +is the beginning of the file. +.TP +.BI / regexp / +.PD 0 +.TP +.BI ? regexp ? +The substring that matches the regular expression, +found by looking toward the end +.RB ( / ) +or beginning +.RB ( ? ) +of the file, +and if necessary continuing the search from the other end to the +starting point of the search. +The matched substring may straddle +the starting point. +When entering a pattern containing a literal question mark +for a backward search, the question mark should be +specified as a member of a class. +.PD +.TP +.B 0 +The string before the first full line. +This is not necessarily +the null string; see +.B + +and +.B - +below. +.TP +.B $ +The null string at the end of the file. +.TP +.B . +Dot. +.TP +.B \&' +The mark in the file (see the +.B k +command below). +.TP +\fB"\f2regexp\fB"\f1\f1 +Preceding a simple address (default +.BR . ), +refers to the address evaluated in the unique file whose menu line +matches the regular expression. +.PD +.SS Compound Addresses +In the following, +.I a1 +and +.I a2 +are addresses. +.TF a1+a2 +.TP +.IB a1 + a2 +The address +.I a2 +evaluated starting at the end of +.IR a1 . +.TP +.IB a1 - a2 +The address +.I a2 +evaluated looking in the reverse direction +starting at the beginning of +.IR a1 . +.TP +.IB a1 , a2 +The substring from the beginning of +.I a1 +to the end of +.IR a2 . +If +.I a1 +is missing, +.B 0 +is substituted. +If +.I a2 +is missing, +.B $ +is substituted. +.TP +.IB a1 ; a2 +Like +.IB a1 , a2\f1, +but with +.I a2 +evaluated at the end of, and dot set to, +.IR a1 . +.PD +.PP +The operators +.B + +and +.B - +are high precedence, while +.B , +and +.B ; +are low precedence. +.PP +In both +.B + +and +.B - +forms, if +.I a2 +is a line or character address with a missing +number, the number defaults to 1. +If +.I a1 +is missing, +.L . +is substituted. +If both +.I a1 +and +.I a2 +are present and distinguishable, +.B + +may be elided. +.I a2 +may be a regular +expression; if it is delimited by +.LR ? 's, +the effect of the +.B + +or +.B - +is reversed. +.PP +It is an error for a compound address to represent a malformed substring. +Some useful idioms: +.IB a1 +- +\%(\f2a1\fB-+\f1) +selects the line containing +the end (beginning) of a1. +.BI 0/ regexp / +locates the first match of the expression in the file. +(The form +.B 0;// +sets dot unnecessarily.) +.BI ./ regexp /// +finds the second following occurrence of the expression, +and +.BI .,/ regexp / +extends dot. +.SS Commands +In the following, text demarcated by slashes represents text delimited +by any printable +character except alphanumerics. +Any number of +trailing delimiters may be elided, with multiple elisions then representing +null strings, but the first delimiter must always +be present. +In any delimited text, +newline may not appear literally; +.B \en +may be typed for newline; and +.B \e/ +quotes the delimiter, here +.LR / . +Backslash is otherwise interpreted literally, except in +.B s +commands. +.PP +Most commands may be prefixed by an address to indicate their range +of operation. +Those that may not are marked with a +.L * +below. +If a command takes +an address and none is supplied, dot is used. +The sole exception is +the +.B w +command, which defaults to +.BR 0,$ . +In the description, `range' is used +to represent whatever address is supplied. +Many commands set the +value of dot as a side effect. +If so, it is always set to the `result' +of the change: the empty string for a deletion, the new text for an +insertion, etc. (but see the +.B s +and +.B e +commands). +.br +.ne 1.2i +.SS Text commands +.PD 0 +.TP +.BI a/ text / +.TP +or +.TP +.B a +.TP +.I lines of text +.TP +.B . +Insert the text into the file after the range. +Set dot. +.PD +.TP +.B c\fP +.br +.ns +.TP +.B i\fP +Same as +.BR a , +but +.B c +replaces the text, while +.B i +inserts +.I before +the range. +.TP +.B d +Delete the text in the range. +Set dot. +.TP +.BI s/ regexp / text / +Substitute +.I text +for the first match to the regular expression in the range. +Set dot to the modified range. +In +.I text +the character +.B & +stands for the string +that matched the expression. +Backslash behaves as usual unless followed by +a digit: +.BI \e d +stands for the string that matched the +subexpression begun by the +.IR d -th +left parenthesis. +If +.I s +is followed immediately by a +number +.IR n , +as in +.BR s2/x/y/ , +the +.IR n -th +match in the range is substituted. +If the +command is followed by a +.BR g , +as in +.BR s/x/y/g , +all matches in the range +are substituted. +.TP +.BI m " a1 +.br +.ns +.TP +.BI t " a1 +Move +.RB ( m ) +or copy +.RB ( t ) +the range to after +.IR a1 . +Set dot. +.SS Display commands +.PD 0 +.TP +.B p +Print the text in the range. +Set dot. +.TP +.B = +Print the line address and character address of the range. +.TP +.B =# +Print just the character address of the range. +.PD +.SS File commands +.PD 0 +.TP +.BI \*ab " file-list +Set the current file to the first file named in the list +that +.I sam +also has in its menu. +The list may be expressed +.BI < "Plan 9 command" +in which case the file names are taken as words (in the shell sense) +generated by the Plan 9 command. +.TP +.BI \*aB " file-list +Same as +.BR b , +except that file names not in the menu are entered there, +and all file names in the list are examined. +.TP +.B \*an +Print a menu of files. +The format is: +.RS +.TP 11 +.BR ' " or blank +indicating the file is modified or clean, +.TP 11 +.BR - " or \&" + +indicating the file is unread or has been read +(in the terminal, +.B * +means more than one window is open), +.TP 11 +.BR . " or blank +indicating the current file, +.TP 11 +a blank, +.TP 11 +and the file name. +.RE +.TP 0 +.BI \*aD " file-list +Delete the named files from the menu. +If no files are named, the current file is deleted. +It is an error to +.B D +a modified file, but a subsequent +.B D +will delete such a file. +.PD +.SS I/O Commands +.PD 0 +.TP +.BI \*ae " filename +Replace the file by the contents of the named external file. +Set dot to the beginning of the file. +.TP +.BI r " filename +Replace the text in the range by the contents of the named external file. +Set dot. +.TP +.BI w " filename +Write the range (default +.BR 0,$ ) +to the named external file. +.TP +.BI \*af " filename +Set the file name and print the resulting menu entry. +.PP +If the file name is absent from any of these, the current file name is used. +.B e +always sets the file name; +.B r +and +.B w +do so if the file has no name. +.TP +.BI < " Plan 9-command +Replace the range by the standard output of the +Plan 9 command. +.TP +.BI > " Plan 9-command +Send the range to the standard input of the +Plan 9 command. +.TP +.BI | " Plan 9-command +Send the range to the standard input, and replace it by +the standard output, of the +Plan 9 command. +.TP +.BI \*a! " Plan 9-command +Run the +Plan 9 command. +.TP +.BI \*acd " directory +Change working directory. +If no directory is specified, +.B $home +is used. +.PD +.PP +In any of +.BR < , +.BR > , +.B | +or +.BR ! , +if the +.I Plan 9 command +is omitted the last +.I Plan 9 command +(of any type) is substituted. +If +.I sam +is +.I downloaded +(using the mouse and raster display, i.e. not using option +.BR -d ), +.B ! +sets standard input to +.BR /dev/null , +and otherwise +unassigned output +.RB ( stdout +for +.B ! +and +.BR > , +.B stderr +for all) is placed in +.B /tmp/sam.err +and the first few lines are printed. +.SS Loops and Conditionals +.PD 0 +.TP +.BI x/ regexp / " command +For each match of the regular expression in the range, run the command +with dot set to the match. +Set dot to the last match. +If the regular +expression and its slashes are omitted, +.L /.*\en/ +is assumed. +Null string matches potentially occur before every character +of the range and at the end of the range. +.TP +.BI y/ regexp / " command +Like +.BR x , +but run the command for each substring that lies before, between, +or after +the matches that would be generated by +.BR x . +There is no default regular expression. +Null substrings potentially occur before every character +in the range. +.TP +.BI \*aX/ regexp / " command +For each file whose menu entry matches the regular expression, +make that the current file and +run the command. +If the expression is omitted, the command is run +in every file. +.TP +.BI \*aY/ regexp / " command +Same as +.BR X , +but for files that do not match the regular expression, +and the expression is required. +.TP +.BI g/ regexp / " command +.br +.ns +.TP +.BI v/ regexp / " command +If the range contains +.RB ( g ) +or does not contain +.RB ( v ) +a match for the expression, +set dot to the range and run the command. +.PP +These may be nested arbitrarily deeply, but only one instance of either +.B X +or +.B Y +may appear in a \%single command. +An empty command in an +.B x +or +.B y +defaults to +.BR p ; +an empty command in +.B X +or +.B Y +defaults to +.BR f . +.B g +and +.B v +do not have defaults. +.PD +.SS Miscellany +.TF (empty) +.TP +.B k +Set the current file's mark to the range. Does not set dot. +.TP +.B \*aq +Quit. +It is an error to quit with modified files, but a second +.B q +will succeed. +.TP +.BI \*au " n +Undo the last +.I n +(default 1) +top-level commands that changed the contents or name of the +current file, and any other file whose most recent change was simultaneous +with the current file's change. +Successive +.BR u 's +move further back in time. +The only commands for which u is ineffective are +.BR cd , +.BR u , +.BR q , +.B w +and +.BR D . +If +.I n +is negative, +.B u +`redoes,' undoing the undo, going forwards in time again. +.TP +(empty) +If the range is explicit, set dot to the range. +If +.I sam +is downloaded, the resulting dot is selected on the screen; +otherwise it is printed. +If no address is specified (the +command is a newline) dot is extended in either direction to +line boundaries and printed. +If dot is thereby unchanged, it is set to +.B .+1 +and printed. +.PD +.SS Grouping and multiple changes +Commands may be grouped by enclosing them in braces +.BR {} . +Commands within the braces must appear on separate lines (no backslashes are +required between commands). +Semantically, an opening brace is like a command: +it takes an (optional) address and sets dot for each sub-command. +Commands within the braces are executed sequentially, but changes made +by one command are not visible to other commands (see the next +paragraph). +Braces may be nested arbitrarily. +.PP +When a command makes a number of changes to a file, as in +.BR x/re/c/text/ , +the addresses of all changes to the file are computed in the original file. +If the changes are in sequence, +they are applied to the file. +Successive insertions at the same address are catenated into a single +insertion composed of the several insertions in the order applied. +.SS The terminal +What follows refers to behavior of +.I sam +when downloaded, that is, when +operating as a display editor on a raster display. +This is the default +behavior; invoking +.I sam +with the +.B -d +(no download) option provides access +to the command language only. +.PP +Each file may have zero or more windows open. +Each window is equivalent +and is updated simultaneously with changes in other windows on the same file. +Each window has an independent value of dot, indicated by a highlighted +substring on the display. +Dot may be in a region not within +the window. +There is usually a `current window', +marked with a dark border, to which typed text and editing +commands apply. +Text may be typed and edited as in +.IR rio (1); +also the escape key (ESC) selects (sets dot to) text typed +since the last mouse button hit. +.PP +The button 3 menu controls window operations. +The top of the menu +provides the following operators, each of which uses one or +more +.IR rio -like +cursors to prompt for selection of a window or sweeping +of a rectangle. +`Sweeping' a null rectangle gets a large window, disjoint +from the command window or the whole screen, depending on +where the null rectangle is. +.TF resize +.TP +.B new +Create a new, empty file. +.TP +.B zerox +Create a copy of an existing window. +.TP +.B resize +As in +.IR rio . +.TP +.B close +Delete the window. +In the last window of a file, +.B close +is equivalent to a +.B D +for the file. +.TP +.B write +Equivalent to a +.B w +for the file. +.PD +.PP +Below these operators is a list of available files, starting with +.BR ~~sam~~ , +the command window. +Selecting a file from the list makes the most recently +used window on that file current, unless it is already current, in which +case selections cycle through the open windows. +If no windows are open +on the file, the user is prompted to open one. +Files other than +.B ~~sam~~ +are marked with one of the characters +.B -+* +according as zero, one, or more windows +are open on the file. +A further mark +.L . +appears on the file in the current window and +a single quote, +.BR ' , +on a file modified since last write. +.PP +The command window, created automatically when +.B sam +starts, is an ordinary window except that text typed to it +is interpreted as commands for the editor rather than passive text, +and text printed by editor commands appears in it. +The behavior is like +.IR rio , +with an `output point' that separates commands being typed from +previous output. +Commands typed in the command window apply to the +current open file\(emthe file in the most recently +current window. +.SS Manipulating text +Button 1 changes selection, much like +.IR rio . +Pointing to a non-current window with button 1 makes it current; +within the current window, button 1 selects text, thus setting dot. +Double-clicking selects text to the boundaries of words, lines, +quoted strings or bracketed strings, depending on the text at the click. +.PP +Button 2 provides a menu of editing commands: +.TF /regexp +.TP +.B cut +Delete dot and save the deleted text in the snarf buffer. +.TP +.B paste +Replace the text in dot by the contents of the snarf buffer. +.TP +.B snarf +Save the text in dot in the snarf buffer. +.TP +.B plumb +Send the text in the selection as a plumb +message. If the selection is empty, +the white-space-delimited block of text is sent as a plumb message +with a +.B click +attribute defining where the selection lies (see +.IR plumb (6)). +.TP +.B look +Search forward for the next occurrence of the literal text in dot. +If dot is the null string, the text in the snarf buffer is +used. +The snarf buffer is unaffected. +.TP +.B +Exchange snarf buffers with +.IR rio . +.TP +.BI / regexp +Search forward for the next match of the last regular expression +typed in a command. +(Not in command window.) +.TP +.B send +Send the text in dot, or the snarf buffer if +dot is the null string, as if it were typed to the command window. +Saves the sent text in the snarf buffer. +(Command window only.) +.PD +.SS External communication +.I Sam +listens to the +.B edit +plumb port. +If plumbing is not active, +on invocation +.I sam +creates a named pipe +.BI /srv/sam. user +which acts as an additional source of commands. Characters written to +the named pipe are treated as if they had been typed in the command window. +.PP +.I B +is a shell-level command that causes an instance of +.I sam +running on the same terminal to load the named +.IR files . +.I B +uses either plumbing or the named pipe, whichever service is available. +If plumbing is not enabled, +the option allows a line number to be specified for +the initial position to display in the last named file +(plumbing provides a more general mechanism for this ability). +.SS Abnormal termination +If +.I sam +terminates other than by a +.B q +command (by hangup, deleting its window, etc.), modified +files are saved in an +executable file, +.BR $home/sam.save . +This program, when executed, asks whether to write +each file back to a external file. +The answer +.L y +causes writing; anything else skips the file. +.SH FILES +.TF /sys/src/cmd/samterm +.TP +.B $home/sam.save +.TP +.B $home/sam.err +.TP +.B /sys/lib/samsave +the program called to unpack +.BR $home/sam.save . +.SH SOURCE +.TF /sys/src/cmd/samterm +.TP +.B /sys/src/cmd/sam +source for +.I sam +itself +.TP +.B /sys/src/cmd/samterm +source for the separate terminal part +.TP +.B /rc/bin/B +.SH SEE ALSO +.IR ed (1), +.IR sed (1), +.IR grep (1), +.IR rio (1), +.IR regexp (6). +.PP +Rob Pike, +``The text editor sam''. diff --git a/man/man1/seq.1 b/man/man1/seq.1 new file mode 100644 index 00000000..60d1f12a --- /dev/null +++ b/man/man1/seq.1 @@ -0,0 +1,75 @@ +.TH SEQ 1 +.SH NAME +seq \- print sequences of numbers +.SH SYNOPSIS +.B seq +[ +.B -w +] +[ +.BI -f format +] +[ +.I first +[ +.I incr +] +] +.I last +.SH DESCRIPTION +.I Seq +prints a sequence of numbers, one per line, from +.I first +(default 1) to as near +.I last +as possible, in increments of +.I incr +(default 1). +The loop is: +.sp +.EX + for(val = min; val <= max; val += incr) print val; +.EE +.sp +The numbers are interpreted as floating point. +.PP +Normally integer values are printed as decimal integers. +The options are +.TP "\w'\fL-f \fIformat\fLXX'u" +.BI -f format +Use the +.IR print (2)-style +.I format +.IR print +for printing each (floating point) number. +The default is +.LR %g . +.TP +.B -w +Equalize the widths of all numbers by padding with +leading zeros as necessary. +Not effective with option +.BR -f , +nor with numbers in exponential notation. +.SH EXAMPLES +.TP +.L +seq 0 .05 .1 +Print +.BR "0 0.05 0.1" +(on separate lines). +.TP +.L +seq -w 0 .05 .1 +Print +.BR "0.00 0.05 0.10" . +.SH SOURCE +.B /sys/src/cmd/seq.c +.SH BUGS +Option +.B -w +always surveys every value in advance. +Thus +.L +seq -w 1000000000 +is a painful way to get an `infinite' sequence. diff --git a/man/man1/sleep.1 b/man/man1/sleep.1 new file mode 100644 index 00000000..61169e96 --- /dev/null +++ b/man/man1/sleep.1 @@ -0,0 +1,31 @@ +.TH SLEEP 1 +.SH NAME +sleep \- suspend execution for an interval +.SH SYNOPSIS +.B sleep +.I time +.SH DESCRIPTION +.I Sleep +suspends execution for +.I time +seconds. +.SH EXAMPLES +Execute a command +100 seconds hence. +.IP +.EX +{sleep 100; command}& +.EE +.PP +Repeat a command every 30 seconds. +.IP +.EX +while (){ + command + sleep 30 +} +.EE +.SH SOURCE +.B /sys/src/cmd/sleep.c +.SH "SEE ALSO" +.IR sleep (2) diff --git a/man/man1/sort.1 b/man/man1/sort.1 new file mode 100644 index 00000000..6dded61a --- /dev/null +++ b/man/man1/sort.1 @@ -0,0 +1,260 @@ +.TH SORT 1 +.SH NAME +sort \- sort and/or merge files +.SH SYNOPSIS +.B sort +[ +.BI -cmuMbdf\&inrwt x +] +[ +.BI + pos1 +[ +.BI - pos2 +] ... +] ... +[ +.B -k +.I pos1 +[ +.I ,pos2 +] +] ... +[ +.B -o +.I output +] +[ +.B -T +.I dir +\&... +] +[ +.I option +\&... +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Sort\^ +sorts +lines of all the +.I files +together and writes the result on +the standard output. +If no input files are named, the standard input is sorted. +.PP +The default sort key is an entire line. +Default ordering is +lexicographic by runes. +The ordering is affected globally by the following options, +one or more of which may appear. +.TP +.B -M +Compare as months. +The first three +non-white space characters +of the field +are folded +to upper case +and compared +so that +.L JAN +precedes +.LR FEB , +etc. +Invalid fields +compare low to +.LR JAN . +.TP +.B -b +Ignore leading white space (spaces and tabs) in field comparisons. +.TP +.B -d +`Phone directory' order: +only letters, +accented letters, +digits and white space +are significant in comparisons. +.TP +.B -f +Fold lower case +letters onto upper case. +Accented characters are folded to their +non-accented upper case form. +.TP +.B -i +Ignore characters outside the +.SM ASCII +range 040-0176 +in non-numeric comparisons. +.TP +.B -w +Like +.BR -i , +but ignore only tabs and spaces. +.TP +.B -n +An initial numeric string, +consisting of optional white space, +optional plus or minus sign, +and zero or more digits with optional decimal point, +is sorted by arithmetic value. +.TP +.B -g +Numbers, like +.B -n +but with optional +.BR e -style +exponents, are sorted by value. +.TP +.B -r +Reverse the sense of comparisons. +.TP +.BI -t x\^ +`Tab character' separating fields is +.IR x . +.PP +The notation +.BI + "pos1\| " - pos2\^ +restricts a sort key to a field beginning at +.I pos1\^ +and ending just before +.IR pos2 . +.I Pos1\^ +and +.I pos2\^ +each have the form +.IB m . n\f1, +optionally followed by one or more of the flags +.BR Mbdfginr , +where +.I m\^ +tells a number of fields to skip from the beginning of the line and +.I n\^ +tells a number of characters to skip further. +If any flags are present they override all the global +ordering options for this key. +A missing +.BI \&. n\^ +means +.BR \&.0 ; +a missing +.BI - pos2\^ +means the end of the line. +Under the +.BI -t x\^ +option, fields are strings separated by +.IR x ; +otherwise fields are +non-empty strings separated by white space. +White space before a field +is part of the field, except under option +.BR -b . +A +.B b +flag may be attached independently to +.IR pos1 +and +.IR pos2. +.PP +The notation +.B -k +.IR pos1 [, pos2 ] +is how POSIX +.I sort +defines fields: +.I pos1 +and +.I pos2 +have the same format but different meanings. +The value of +.I m\^ +is origin 1 instead of origin 0 +and a missing +.BI \&. n\^ +in +.I pos2 +is the end of the field. +.PP +When there are multiple sort keys, later keys +are compared only after all earlier keys +compare equal. +Lines that otherwise compare equal are ordered +with all bytes significant. +.PP +These option arguments are also understood: +.TP \w'\fL-z\fIrecsize\fLXX'u +.B -c +Check that the single input file is sorted according to the ordering rules; +give no output unless the file is out of sort. +.TP +.B -m +Merge; assume the input files are already sorted. +.TP +.B -u +Suppress all but one in each +set of equal lines. +Ignored bytes +and bytes outside keys +do not participate in +this comparison. +.TP +.B -o +The next argument is the name of an output file +to use instead of the standard output. +This file may be the same as one of the inputs. +.TP +.BI -T dir +Put temporary files in +.I dir +rather than in +.BR /tmp . +.ne 4 +.SH EXAMPLES +.TP +.L sort -u +0f +0 list +Print in alphabetical order all the unique spellings +in a list of words +where capitalized words differ from uncapitalized. +.TP +.L sort -t: +1 /adm/users +Print the users file +sorted by user name +(the second colon-separated field). +.TP +.L sort -umM dates +Print the first instance of each month in an already sorted file. +Options +.B -um +with just one input file make the choice of a +unique representative from a set of equal lines predictable. +.TP +.L +grep -n '^' input | sort -t: +1f +0n | sed 's/[0-9]*://' +A stable sort: input lines that compare equal will +come out in their original order. +.SH FILES +.BI /tmp/sort. . +.SH SOURCE +.B /sys/src/cmd/sort.c +.SH SEE ALSO +.IR uniq (1), +.IR look (1) +.SH DIAGNOSTICS +.I Sort +comments and exits with non-null status for various trouble +conditions and for disorder discovered under option +.BR -c . +.SH BUGS +An external null character can be confused +with an internally generated end-of-field character. +The result can make a sub-field not sort +less than a longer field. +.PP +Some of the options, e.g. +.B -i +and +.BR -M , +are hopelessly provincial. diff --git a/man/man1/spell.1 b/man/man1/spell.1 new file mode 100644 index 00000000..8298452c --- /dev/null +++ b/man/man1/spell.1 @@ -0,0 +1,96 @@ +.TH SPELL 1 +.SH NAME +spell, sprog \- find spelling errors +.SH SYNOPSIS +.B spell +[ +.I options +] +\&... +[ +.I file +] +\&... +.PP +.B sprog +[ +.I options +] +[ +.B -f +.I file +] +.SH DESCRIPTION +.I Spell +looks up words from the named +.I files +(standard input default) +in a spelling list and places +possible misspellings\(emwords +not sanctioned there\(emon the standard output. +.PP +.I Spell +ignores constructs of +.IR troff (1) +and its standard preprocessors. +It understands these options: +.TP +.B -b +Check British spelling. +.TP +.B -v +Print all words not literally in the spelling list, with +derivations. +.TP +.B -x +Print, marked with +.LR = , +every stem as it is looked up in the spelling list, +along with its affix classes. +.PP +As a matter of policy, +.I spell +does not admit multiple spellings of the same word. +Variants that follow general rules are preferred +over those that don't, even when the unruly spelling is +more common. +Thus, in American usage, `modelled', `sizeable', and `judgment' are +rejected in favor of `modeled', `sizable', and `judgement'. +Agglutinated variants are shunned: `crewmember' and `backyard' +cede to `crew member' and `back yard' (noun) or `back-yard' +(adjective). +.SH FILES +.TF /sys/lib/brspell +.TP +.B /sys/lib/amspell +American spelling list +.TP +.B /sys/lib/brspell +British spelling list +.TP +.B /bin/aux/sprog +The actual spelling checker. +It expects one word per line on standard input, +and takes the same arguments as +.IR spell . +.SH SOURCE +.TF /sys/src/cmd/spell +.TP +.B /rc/bin/spell +the script +.TP +.B /sys/src/cmd/spell +source for +.I sprog +.SH SEE ALSO +.IR deroff (1) +.SH BUGS +The heuristics of +.IR deroff (1) +used to excise formatting information are imperfect. +.br +The spelling list's coverage is uneven; +in particular biology, medicine, and chemistry, and +perforce proper names, +not to mention languages other than English, +are covered very lightly. diff --git a/man/man1/split.1 b/man/man1/split.1 new file mode 100644 index 00000000..ffb012d7 --- /dev/null +++ b/man/man1/split.1 @@ -0,0 +1,82 @@ +.TH SPLIT 1 +.CT 1 files +.SH NAME +split \- split a file into pieces +.SH SYNOPSIS +.B split +[ +.I option ... +] +[ +.I file +] +.SH DESCRIPTION +.I Split +reads +.I file +(standard input by default) +and writes it in pieces of 1000 +lines per output file. +The names of the +output files are +.BR xaa , +.BR xab , +and so on to +.BR xzz . +The options are +.TP +.BI -n " n" +Split into +.IR n -line +pieces. +.TP +.BI -l " n" +Synonym for +.B -n +.IR n , +a nod to Unix's syntax. +.TP +.BI -e " expression" +File divisions occur at each line +that matches a regular +.IR expression ; +see +.IR regexp (6). +Multiple +.B -e +options may appear. +If a subexpression of +.I expression +is contained in parentheses +.BR ( ... ) , +the output file name is the portion of the +line which matches the subexpression. +.TP +.BI -f " stem +Use +.I stem +instead of +.B x +in output file names. +.TP +.BI -s " suffix +Append +.I suffix +to names identified under +.BR -e . +.TP +.B -x +Exclude the matched input line from the output file. +.TP +.B -i +Ignore case in option +.BR -e ; +force output file names (excluding the suffix) +to lower case. +.SH SOURCE +.B /sys/src/cmd/split.c +.SH SEE ALSO +.IR sed (1), +.IR awk (1), +.IR grep (1), +.IR regexp (6) diff --git a/man/man1/strings.1 b/man/man1/strings.1 new file mode 100644 index 00000000..d72ffbb1 --- /dev/null +++ b/man/man1/strings.1 @@ -0,0 +1,28 @@ +.TH STRINGS 1 +.SH NAME +strings \- extract printable strings +.SH SYNOPSIS +.B strings +[ +.I file ... +] +.SH DESCRIPTION +.I Strings +finds and prints strings containing 6 or more +consecutive printable UTF-encoded characters +in a (typically) binary file, default +standard input. +Printable characters are taken to be +.SM ASCII +characters from blank through tilde (hexadecimal 20 through 7E), inclusive, +and +all other characters from value 00A0 to FFFF. +Strings reports +the decimal offset within the file at which the string starts and the text +of the string. If the string is longer than 70 runes the line is +terminated by three dots and the printing is resumed on the next +line with the offset of the continuation line. +.SH SOURCE +.B /sys/src/cmd/strings.c +.SH SEE ALSO +.IR nm (1) diff --git a/man/man1/sum.1 b/man/man1/sum.1 new file mode 100644 index 00000000..d981c8c7 --- /dev/null +++ b/man/man1/sum.1 @@ -0,0 +1,77 @@ +.TH SUM 1 +.SH NAME +sum, md5sum, sha1sum \- sum and count blocks in a file +.SH SYNOPSIS +.B sum +[ +.B -5r +] +[ +.I file ... +] +.PP +.B md5sum +[ +.I file ... +] +.PP +.B sha1sum +[ +.I file ... +] +.SH DESCRIPTION +By default, +.I sum +calculates and prints a 32-bit hexadecimal checksum, +a byte count, +and the name of +each +.IR file . +The checksum is also a function of the input length. +If no files are given, +the standard input is +summed. +Other summing algorithms are available. +The options are +.TP +.B -r +Sum with the algorithm of System V's +.B "sum -r" +and print the length (in 1K blocks) of the input. +.TP +.B -5 +Sum with System V's default algorithm +and print the length (in 512-byte blocks) of the input. +.PP +.I Sum +is typically used to look for bad spots, +to validate a file communicated over +some transmission line or +as a quick way to determine if two files on different machines might be the same. +.PP +.B Md5sum +computes the 32 hex digit RSA Data Security, Inc. MD5 Message-Digest Algorithm +described in RFC1321. +If no +.I files +are given, +the standard input is +summed. +.PP +.B Sha1sum +computes the 40 hex digit National Institute of Standards and Technology SHA1 secure hash algorithm +described in FIPS PUB 180-1. +If no +.I files +are given, +the standard input is +summed. +.SH SOURCE +.B /sys/src/cmd/sum.c +.br +.B /sys/src/cmd/md5sum.c +.br +.B /sys/src/cmd/sha1sum.c +.SH "SEE ALSO" +.IR cmp (1), +.IR wc (1) diff --git a/man/man1/tail.1 b/man/man1/tail.1 new file mode 100644 index 00000000..b2d880b6 --- /dev/null +++ b/man/man1/tail.1 @@ -0,0 +1,87 @@ +.TH TAIL 1 +.SH NAME +tail \- deliver the last part of a file +.SH SYNOPSIS +.B tail +[ +.BR +- \fInumber\fP[ lbc ][ rf ] +] +[ +.I file +] +.PP +.B tail +[ +.B -fr +] +[ +.B -n +.I nlines +] +[ +.B -c +.I nbytes +] +[ +.I file +] +.SH DESCRIPTION +.I Tail +copies the named file to the standard output beginning +at a designated place. +If no file is named, the standard input is copied. +.PP +Copying begins at position +.BI + number +measured from the beginning, or +.BI - number +from the end of the input. +.I Number +is counted in lines, 1K blocks or bytes, +according to the appended flag +.LR l , +.LR b , +or +.LR c . +Default is +.B -10l +(ten ell). +.PP +The further flag +.L r +causes tail to print lines from the end of the file in reverse order; +.L f +(follow) causes +.IR tail , +after printing to the end, to keep watch and +print further data as it appears. +.PP +The second syntax is that promulgated by POSIX, where +the +.I numbers +rather than the options are signed. +.SH EXAMPLES +.TP +.B tail file +Print the last 10 lines of a file. +.TP +.B tail +0f file +Print a file, and continue to watch +data accumulate as it grows. +.TP +.B sed 10q file +Print the first 10 lines of a file. +.SH SOURCE +.B /sys/src/cmd/tail.c +.SH BUGS +Tails relative to the end of the file +are treasured up in a buffer, and thus +are limited in length. +.br +According to custom, option +.BI + number +counts lines from 1, and counts +blocks and bytes from 0. +.br +.I Tail +is ignorant of UTF. diff --git a/man/man1/tar.1 b/man/man1/tar.1 new file mode 100644 index 00000000..8ef56d06 --- /dev/null +++ b/man/man1/tar.1 @@ -0,0 +1,118 @@ +.TH TAR 1 +.SH NAME +tar \- archiver +.SH SYNOPSIS +.B tar +.I key +[ +.I file ... +] +.SH DESCRIPTION +.PP +.I Tar +saves and restores file trees. +It is most often used to transport a tree of files from one +system to another. +The +.I key +is a string that contains +at most one function letter plus optional modifiers. +Other arguments to the command are names of +files or directories to be dumped or restored. +A directory name implies all the contained +files and subdirectories (recursively). +.PP +The function is one of the following letters: +.TP +.B c +Create a new archive with the given files as contents. +.TP +.B x +Extract the named files from the archive. +If a file is a directory, the directory is extracted recursively. +Modes are restored if possible. +If no file argument is given, extract the entire archive. +If the archive contains multiple entries for a file, +the latest one wins. +.TP +.B t +List all occurrences of each +.I file +in the archive, or of all files if there are no +.I file +arguments. +.TP +.B r +The named files +are appended to the archive. +.PP +The modifiers are: +.TP +.B v +(verbose) +Print the name of each file treated +preceded by the function letter. +With +.BR t , +give more details about the +archive entries. +.TP +.B f +Use the next argument as the name of the archive instead of +the default standard input (for keys +.B x +and +.BR t ) +or standard output (for keys +.B c +and +.BR r ). +.TP +.B u +Use the next (numeric) argument as the user id for files in +the output archive. This is only useful when moving files to +a non-Plan 9 system. +.TP +.B g +Use the next (numeric) argument as the group id for files in +the output archive. +.TP +.B p +Create archive in POSIX ustar format, +which raises the maximum pathname length from 100 to 256 bytes. +Ustar archives are recognised automatically by +.I tar +when reading archives. +.TP +.B R +When extracting, ignore leading slash on file names, +i.e., extract all files relative to the current directory. +.TP +.B T +Modifies the behavior of +.B x +to set the mode and modified time +of each file to that specified in the archive. +.SH EXAMPLES +.I Tar +can be used to copy hierarchies thus: +.IP +.EX +@{cd fromdir && tar cp .} | @{cd todir && tar xT} +.EE +.SH SOURCE +.B /sys/src/cmd/tar.c +.SH SEE ALSO +.IR ar (1), +.IR bundle (1), +.IR tapefs (1) +.SH BUGS +There is no way to ask for any but the last +occurrence of a file. +.br +File path names are limited to +100 characters +(256 when using ustar format). +.br +The tar format allows specification of links and symbolic links, +concepts foreign to Plan 9: they are ignored. diff --git a/man/man1/tee.1 b/man/man1/tee.1 new file mode 100644 index 00000000..d237fb7f --- /dev/null +++ b/man/man1/tee.1 @@ -0,0 +1,28 @@ +.TH TEE 1 +.SH NAME +tee \- pipe fitting +.SH SYNOPSIS +.B tee +[ +.B -i +] +[ +.B -a +] +.I files +.SH DESCRIPTION +.I Tee +transcribes the standard input to the standard +output and makes copies in the +.IR files . +The options are +.TP +.B -i +Ignore interrupts. +.TP +.B -a +Append the output to the +.I files +rather than rewriting them. +.SH SOURCE +.B /sys/src/cmd/tee.c diff --git a/man/man1/test.1 b/man/man1/test.1 new file mode 100644 index 00000000..86f0cd34 --- /dev/null +++ b/man/man1/test.1 @@ -0,0 +1,211 @@ +.TH TEST 1 +.SH NAME +test \- set status according to condition +.SH SYNOPSIS +.B test +.I expr +.SH DESCRIPTION +.I Test +evaluates the expression +.IR expr . +If the value is true the exit status is null; otherwise the +exit status is non-null. +If there are no arguments the exit status is non-null. +.PP +The following primitives are used to construct +.IR expr . +.TP "\w'\fIn1 \fL-eq \fIn2\fLXX'u" +.BI -r " file" +True if the file exists (is accessible) and is readable. +.PD0 +.TP +.BI -w " file" +True if the file exists and is writable. +.TP +.BI -x " file" +True if the file exists and has execute permission. +.TP +.BI -e " file +True if the file exists. +.TP +.BI -f " file" +True if the file exists and is a plain file. +.TP +.BI -d " file" +True if the file exists and is a directory. +.TP +.BI -s " file" +True if the file exists and has a size greater than zero. +.TP +.BI -t " fildes +True if the open file whose file descriptor number is +.I fildes +(1 by default) +is the same file as +.BR /dev/cons . +.TP +.BI -A " file" +True if the file exists and is append-only. +.TP +.BI -L " file" +True if the file exists and is exclusive-use. +.TP +.BI -T "file" +True if the file exists and is temporary. +.TP +.IB s1 " = " s2 +True +if the strings +.I s1 +and +.I s2 +are identical. +.TP +.IB s1 " != " s2 +True +if the strings +.I s1 +and +.I s2 +are not identical. +.TP +s1 +True if +.I s1 +is not the null string. +(Deprecated.) +.TP +.BI -n " s1" +True if the length of string +.I s1 +is non-zero. +.TP +.BI -z " s1" +True if the length of string +.I s1 +is zero. +.TP +.IB n1 " -eq " n2 +True if the integers +.I n1 +and +.I n2 +are arithmetically equal. +Any of the comparisons +.BR -ne , +.BR -gt , +.BR -ge , +.BR -lt , +or +.BR -le +may be used in place of +.BR -eq . +The (nonstandard) construct +.BI -l " string\f1, +meaning the length of +.IR string , +may be used in place of an integer. +.TP +.IB a " -nt " b +True if file +.I a +is newer than (modified after) file +.IR b . +.TP +.IB a " -ot " b +True if file +.I a +is older than (modified before) file +.IR b . +.TP +.IB f " -older " t +True if file +.I f +is older than (modified before) time +.IR t . +If +.I t +is a integer followed by the letters +.BR y (years), +.BR M (months), +.BR d (days), +.BR h (hours), +.BR m (minutes), +or +.BR s (seconds), +it represents current time minus the specified time. +If there is no letter, it represents seconds since +epoch. +You can also concatenate mixed units. For example, +.B 3d12h +means three days and twelve hours ago. +.PD +.PP +These primaries may be combined with the +following operators: +.TP "\w'\fL( \fIexpr\fL )XX'u" +.B ! +unary negation operator +.PD0 +.TP +.B -o +binary +.I or +operator +.TP +.B -a +binary +.I and +operator; higher precedence than +.BR -o +.TP +.BI "( " expr " )" +parentheses for grouping. +.PD +.PP +The primitives +.BR -b , +.BR -u , +.BR -g , +and +.BR -s +return false; they are recognized for compatibility with POSIX. +.PP +Notice that all the operators and flags are separate +arguments to +.IR test . +Notice also that parentheses and equal signs are meaningful +to +.I rc +and must be enclosed in quotes. +.SH EXAMPLES +.I Test +is a dubious way to check for specific character strings: +it uses a process to do what an +.IR rc (1) +match or switch statement can do. +The first example is not only inefficient but wrong, because +.I test +understands the purported string +.B \&"-c" +as an option. +.IP +.EX +if (test $1 '=' "-c") echo OK # wrong! +.EE +.LP +A better way is +.IP +.EX +if (~ $1 -c) echo OK +.EE +.PP +Test whether +.L abc +is in the current directory. +.IP +.B test -f abc -o -d abc +.SH SOURCE +.B /sys/src/cmd/test.c +.SH "SEE ALSO" +.IR rc (1) diff --git a/man/man1/time.1 b/man/man1/time.1 new file mode 100644 index 00000000..2c6b834b --- /dev/null +++ b/man/man1/time.1 @@ -0,0 +1,21 @@ +.TH TIME 1 +.SH NAME +time \- time a command +.SH SYNOPSIS +.B time +.I command +[ +.I arg ... +] +.SH DESCRIPTION +The +.I command +is executed with the given arguments; after it is complete, +.I time +reports on standard error the program's elapsed user time, +system time, and real time, in seconds, +followed by the command line. +.SH SOURCE +.B /sys/src/cmd/time.c +.SH "SEE ALSO" +.IR prof (1) diff --git a/man/man1/touch.1 b/man/man1/touch.1 new file mode 100644 index 00000000..ac5937ec --- /dev/null +++ b/man/man1/touch.1 @@ -0,0 +1,35 @@ +.TH TOUCH 1 +.SH NAME +touch \- set modification date of a file +.SH SYNOPSIS +.B touch +[ +.B -c +] +[ +.B -t +.I time +] +.I file ... +.SH DESCRIPTION +.I Touch +attempts to set the modification time of the +.I files +to +.I time +(by default, the current time). +If a +.I file +does not exist, +it will be created unless option +.B -c +is present. +.SH SOURCE +.B /sys/src/cmd/touch.c +.SH SEE ALSO +.IR ls (1), +.IR stat (2), +.IR chmod (1) +.SH BUGS +.I Touch +will not touch directories. diff --git a/man/man1/tr.1 b/man/man1/tr.1 new file mode 100644 index 00000000..0e11f5b9 --- /dev/null +++ b/man/man1/tr.1 @@ -0,0 +1,97 @@ +.TH TR 1 +.SH NAME +tr \- translate characters +.SH SYNOPSIS +.B tr +[ +.B -cds +] +[ +.I string1 +[ +.I string2 +] +] +.SH DESCRIPTION +.I Tr +copies the standard input to the standard output with +substitution or deletion of selected characters (runes). +Input characters found in +.I string1 +are mapped into the corresponding characters of +.IR string2 . +When +.I string2 +is short it is padded to the length of +.I string1 +by duplicating its last character. +Any combination of the options +.B -cds +may be used: +.TP +.B -c +Complement +.IR string1 : +replace it with a lexicographically ordered +list of all other characters. +.TP +.B -d +Delete from input all characters in +.IR string1 . +.TP +.B -s +Squeeze repeated output characters that occur in +.I string2 +to single characters. +.PP +In either string a noninitial sequence +.BI - x\f1, +where +.I x +is any character (possibly quoted), stands for +a range of characters: +a possibly empty sequence of codes running from +the successor of the previous code up through +the code for +.IR x . +The character +.L \e +followed by 1, 2 or 3 octal digits stands for the +character whose +16-bit +value is given by those digits. +The character sequence +.L \ex +followed by 1, 2, 3, or 4 hexadecimal digits stands +for the character whose +16-bit value is given by those digits. +A +.L \e +followed by any other character stands +for that character. +.SH EXAMPLES +Replace all upper-case +.SM ASCII +letters by lower-case. +.IP +.EX +tr A-Z a-z lower +.EE +.PP +Create a list of all +the words in +.L file1 +one per line in +.LR file2 , +where a word is taken to be a maximal string of alphabetics. +.I String2 +is given as a quoted newline. +.IP +.EX +tr -cs A-Za-z ' +\&' file2 +.EE +.SH SOURCE +.B /sys/src/cmd/tr.c +.SH "SEE ALSO" +.IR sed (1) diff --git a/man/man1/uniq.1 b/man/man1/uniq.1 new file mode 100644 index 00000000..65fcd49f --- /dev/null +++ b/man/man1/uniq.1 @@ -0,0 +1,59 @@ +.TH UNIQ 1 +.SH NAME +uniq \- report repeated lines in a file +.SH SYNOPSIS +.B uniq +[ +.B -udc +[ +.BI +- num +] +] +[ +.I file +] +.SH DESCRIPTION +.I Uniq +copies the input +.IR file , +or the standard input, to the +standard output, comparing adjacent lines. +In the normal case, the second and succeeding copies +of repeated lines are +removed. +Repeated lines must be adjacent +in order to be found. +.TP +.B -u +Print unique lines. +.TP +.B -d +Print (one copy of) duplicated lines. +.TP +.B -c +Prefix a repetition count and a tab to each output line. +Implies +.B -u +and +.BR -d . +.TP +.BI - num +The first +.IR num +fields +together with any blanks before each are ignored. +A field is defined as a string of non-space, non-tab characters +separated by tabs and spaces from its neighbors. +.TP +.BI + num +The first +.IR num +characters are ignored. +Fields are skipped before characters. +.SH SOURCE +.B /sys/src/cmd/uniq.c +.SH "SEE ALSO" +.IR sort (1) +.SH BUGS +Field selection and comparison should be compatible with +.IR sort (1). diff --git a/man/man1/wc.1 b/man/man1/wc.1 new file mode 100644 index 00000000..1c9768fc --- /dev/null +++ b/man/man1/wc.1 @@ -0,0 +1,53 @@ +.TH WC 1 +.SH NAME +wc \- word count +.SH SYNOPSIS +.B wc +[ +.B -lwrbc +] +[ +.I file ... +] +.SH DESCRIPTION +.I Wc +counts lines, words, runes, syntactically-invalid +.SM UTF +codes and bytes in the named +.IR files , +or in the standard input if no file is named. +A word is a maximal string of characters +delimited by spaces, tabs or newlines. +The count of runes includes invalid codes. +.PP +If the optional argument is present, +just the specified counts (lines, words, runes, broken +.SM UTF +codes or bytes) +are selected by the letters +.BR l , +.BR w , +.BR r , +.BR b , +or +.BR c . +Otherwise, lines, words and bytes +.RB ( -lwc ) +are reported. +.SH SOURCE +.B /sys/src/cmd/wc.c +.SH BUGS +The Unicode Standard has many blank characters scattered through it, +but +.I wc +looks for only +.SM ASCII +space, tab and newline. +.br +.I Wc +should have options to count suboptimal +.SM UTF +codes +and bytes that cannot occur in any +.SM UTF +code. diff --git a/man/man1/xd.1 b/man/man1/xd.1 new file mode 100644 index 00000000..cc2d394f --- /dev/null +++ b/man/man1/xd.1 @@ -0,0 +1,87 @@ +.TH XD 1 +.SH NAME +xd \- hex, octal, decimal, or ASCII dump +.SH SYNOPSIS +.B xd +[ +.I option ... +] +[ +.BI - "format ... +] [ +.I file ... +] +.SH DESCRIPTION +.I Xd +concatenates and dumps the +.I files +(standard input by default) +in one or more formats. +Groups of 16 bytes are printed in each of the named formats, one +format per line. +Each line of output is prefixed by its address (byte offset) +in the input file. +The first line of output for each group is zero-padded; subsequent are blank-padded. +.PP +Formats other than +.B -c +are specified by pairs of characters telling size and style, +.L 4x +by default. +The sizes are +.TP \w'2\ or\ w\ \ \ 'u +.BR 1 " or " b +1-byte units. +.PD0 +.TP +.BR 2 " or " w +2-byte big-endian units. +.TP +.BR 4 " or " l +4-byte big-endian units. +.TP +.BR 8 " or " v +8-byte big-endian units. +.PD +.PP +The styles are +.TP 0 +.B o +Octal. +.PD0 +.TP +.B x +Hexadecimal. +.TP +.B d +Decimal. +.PD +.PP +Other options are +.TP \w'\fL-a\fIstyle\fLXX'u +.B -c +Format as +.B 1x +but print +.SM ASCII +representations or C escape sequences where possible. +.TP +.BI -a style +Print file addresses in the given style (and size 4). +.TP +.B -u +(Unbuffered) Flush the output buffer after each 16-byte sequence. +.TP +.B -s +Reverse (swab) the order of bytes in each group of 4 before printing. +.TP +.B -r +Print repeating groups of identical 16-byte sequences as the first group +followed by an asterisk. +.SH SOURCE +.B /sys/src/cmd/xd.c +.SH "SEE ALSO" +.IR db (1) +.SH BUGS +The various output formats don't line up properly in the output of +.IR xd . diff --git a/man/man1/yacc.1 b/man/man1/yacc.1 new file mode 100644 index 00000000..a965f953 --- /dev/null +++ b/man/man1/yacc.1 @@ -0,0 +1,167 @@ +.TH YACC 1 +.SH NAME +yacc \- yet another compiler-compiler +.SH SYNOPSIS +.B yacc +[ +.I option ... +] +.I grammar +.SH DESCRIPTION +.I Yacc +converts a context-free grammar and translation code +into a set of +tables for an LR(1) parser and translator. +The grammar may be ambiguous; +specified precedence rules are used to break ambiguities. +.PP +The output file, +.BR y.tab.c , +must be compiled by the C compiler +to produce a program +.LR yyparse . +This program must be loaded with a lexical analyzer function, +.B yylex(void) +(often generated by +.IR lex (1)), +with a +.B main(int argc, char *argv[]) +program, and with an error handling routine, +.BR yyerror(char*) . +.PP +The options are +.TP "\w'\fL-o \fIoutput\fLXX'u" +.BI -o " output +Direct output to the specified file instead of +.BR y.tab.c . +.TP +.BI -D n +Create file +.BR y.debug , +containing diagnostic messages. +To incorporate them in the parser, compile it with preprocessor symbol +.B yydebug +defined. +The amount of +diagnostic output from the parser is regulated by +value +.IR n . +The value 0 reports errors; 1 reports reductions; +higher values (up to 4) include more information about +state transitions. +.TP +.B -v +Create file +.BR y.output , +containing a description of the parsing tables and of +conflicts arising from ambiguities in the grammar. +.TP +.B -d +Create file +.BR y.tab.h , +containing +.B #define +statements that associate +.IR yacc -assigned +`token codes' with user-declared `token names'. +Include it in source files other than +.B y.tab.c +to give access to the token codes. +.TP +.BI -s " stem +Change the prefix +.L y +of the file names +.BR y.tab.c , +.BR y.tab.h , +.BR y.debug , +and +.B y.output +to +.IR stem . +.TP +.B -S +Write a parser that uses +Stdio +instead of the +.B print +routines in libc. +.PP +The specification of +.I yacc +itself is essentially the same as the UNIX version +described in the references mentioned below. +Besides the +.B -D +option, the main relevant differences are: +.IP +The interface to the C environment is by default through +.B +rather than +.BR ; +the +.B -S +option reverses this. +.IP +The parser accepts +.SM UTF +input text (see +.IR utf (6)), +which has a couple of effects. +First, the return value of +.B yylex() +no longer fits in a +.BR short ; +second, the starting value for non-terminals is now 0xE000 rather than 257. +.IP +The generated parser can be recursive: actions can call +.IR yyparse , +for example to implement a sort of +.B #include +statement in an interpreter. +.IP +Finally, some undocumented inner workings of the parser have been +changed, which may affect programs that know too much about its structure. +.SH FILES +.TF /sys/lib/yaccpars +.TP +.B y.output +.TP +.B y.tab.c +.TP +.B y.tab.h +.TP +.B y.debug +.TP +.B y.tmp.* +temporary file +.TP +.B y.acts.* +temporary file +.TP +.B /sys/lib/yaccpar +parser prototype +.TP +.B /sys/lib/yaccpars +parser prototype using stdio +.SH SOURCE +.B /sys/src/cmd/yacc.c +.SH "SEE ALSO" +.IR lex (1) +.br +S. C. Johnson and R. Sethi, +``Yacc: A parser generator'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2 +.br +B. W. Kernighan and Rob Pike, +.I +The UNIX Programming Environment, +Prentice Hall, 1984 +.SH BUGS +The parser may not have full information when it writes to +.B y.debug +so that the names of the tokens returned by +.L yylex +may be missing. diff --git a/man/man3/9p.3 b/man/man3/9p.3 new file mode 100644 index 00000000..48d029ef --- /dev/null +++ b/man/man3/9p.3 @@ -0,0 +1,760 @@ +.TH 9P 3 +.SH NAME +Srv, +dirread9p, +emalloc9p, +erealloc9p, +estrdup9p, +postfd, +postmountsrv, +readbuf, +readstr, +respond, +threadpostmountsrv, +srv \- 9P file service +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fL1234'u +\w'\fLTree* 'u +typedef struct Srv { + Tree* tree; + + void (*attach)(Req *r); + void (*auth)(Req *r); + void (*open)(Req *r); + void (*create)(Req *r); + void (*read)(Req *r); + void (*write)(Req *r); + void (*remove)(Req *r); + void (*flush)(Req *r); + void (*stat)(Req *r); + void (*wstat)(Req *r); + void (*walk)(Req *r); + + char* (*walk1)(Fid *fid, char *name, Qid *qid); + char* (*clone)(Fid *oldfid, Fid *newfid); + + void (*destroyfid)(Fid *fid); + void (*destroyreq)(Req *r); + void (*end)(Srv *s); + void* aux; + + int infd; + int outfd; + int srvfd; + int nopipe; +} Srv; +.fi +.PP +.nf +.ft L +.ta \w'\fLvoid* 'u +int srv(Srv *s) +void postmountsrv(Srv *s, char *name, char *mtpt, int flag) +void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag) +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) +.fi +.PP +.nf +.ft L +.ta \w'\fLvoid* 'u +void* emalloc9p(ulong n) +void* erealloc9p(void *v, ulong n) +char* estrdup9p(char *s) +.fi +.PP +.nf +.ft L +extern int chatty9p; +.fi +.SH DESCRIPTION +The function +.I srv +serves a 9P session by reading requests from +.BR s->infd , +dispatching them to the function pointers kept in +.BR Srv , +and +writing the responses to +.BR s->outfd . +(Typically, +.I postmountsrv +or +.I threadpostmountsrv +initializes the +.B infd +and +.B outfd +structure members. See the description below.) +.PP +.B Req +and +.B Fid +structures are allocated one-to-one with uncompleted +requests and active fids, and are described in +.IR 9pfid (2). +.PP +The behavior of +.I srv +depends on whether there is a file tree +(see +.IR 9pfile (2)) +associated with the server, that is, +whether the +.B tree +element is nonzero. +The differences are made explicit in the +discussion of the service loop below. +The +.B aux +element is the client's, to do with as it pleases. +.PP +.I Srv +does not return until the 9P conversation is finished. +Since it is usually run in a separate process so that +the caller can exit, the service loop has little chance +to return gracefully on out of memory errors. +It calls +.IR emalloc9p , +.IR erealloc9p , +and +.I estrdup9p +to obtain its memory. +The default implementations of these functions +act as +.IR malloc , +.IR realloc , +and +.I strdup +but abort the program if they run out of memory. +If alternate behavior is desired, clients can link against +alternate implementations of these functions. +.PP +.I Postmountsrv +and +.I threadpostmountsrv +are wrappers that create a separate process in which to run +.IR srv . +They do the following: +.IP +If +.IB s -> nopipe +is zero (the common case), +initialize +.IB s -> infd +and +.IB s -> outfd +to be one end of a freshly allocated pipe, +with +.IB s -> srvfd +initialized as the other end. +.IP +If +.B name +is non-nil, call +.BI postfd( s -> srvfd , +.IB name ) +to post +.IB s -> srvfd +as +.BI /srv/ name . +.IP +Fork a child process via +.I rfork +(see +.IR fork (2)) +or +.I procrfork +(see +.IR thread (2)), +using the +.BR RFFDG , +.RR RFNOTEG , +.BR RFNAMEG , +and +.BR RFMEM +flags. +The child process +calls +.IB close( s -> srvfd ) +and then +.IB srv( s ) \fR; +it will exit once +.I srv +returns. +.IP +If +.I mtpt +is non-nil, +call +.BI amount( s -> srvfd, +.IB mtpt , +.IB flag , +\fB"")\fR; +otherwise, close +.IB s -> srvfd \fR. +.IP +The parent returns to the caller. +.LP +If any error occurs during +this process, the entire process is terminated by calling +.I sysfatal +(see +.IR perror (2)). +.SS Service functions +The functions in a +.B Srv +structure named after 9P transactions +are called to satisfy requests as they arrive. +If a function is provided, it +.I must +arrange for +.I respond +to be called when the request is satisfied. +The only parameter of each service function +is a +.B Req* +parameter (say +.IR r ). +The incoming request parameters are stored in +.IB r -> ifcall \fR; +.IB r -> fid +and +.IB r -> newfid +are pointers to +.B Fid +structures corresponding to the +numeric fids in +.IB r -> ifcall \fR; +similarly, +.IB r -> oldreq +is the +.B Req +structure corresponding to +.IB r -> ifcall.oldtag \fR. +The outgoing response data should be stored in +.IB r -> ofcall \fR. +The one exception to this rule is that +.I stat +should fill in +.IB r -> d +rather than +.IB r -> ofcall.stat \fR: +the library will convert the structure into the machine-independent +wire representation. +Similarly, +.I wstat +may consult +.IB r -> d +rather than decoding +.IB r -> ifcall . stat +itself. +When a request has been handled, +.I respond +should be called with +.I r +and an error string. +If the request was satisfied successfully, the error +string should be a nil pointer. +Note that it is permissible for a function to return +without itself calling +.IR respond , +as long as it has arranged for +.I respond +to be called at some point in the future +by another proc sharing its address space, +but see the discussion of +.I flush +below. +Once +.I respond +has been called, the +.B Req* +as well as any pointers it once contained must +be considered freed and not referenced. +.PP +If the service loop detects an error in a request +(e.g., an attempt to reuse an extant fid, an open of +an already open fid, a read from a fid opened for write, etc.) +it will reply with an error without consulting +the service functions. +.PP +The service loop provided by +.I srv +(and indirectly by +.I postmountsrv +and +.IR threadpostmountsrv ) +is single-threaded. +If it is expected that some requests might +block, arranging for alternate processes +to handle them is suggested. +.PP +The constraints on the service functions are as follows. +These constraints are checked while the server executes. +If a service function fails to do something it ought to have, +.I srv +will call +.I endsrv +and then abort. +.TP +.I Auth +If authentication is desired, +the +.I auth +function should record that +.I afid +is the new authentication fid and +set +.I afid->qid +and +.IR ofcall.qid . +.I Auth +may be nil, in which case it will be treated as having +responded with the error +.RI `` "argv0: authentication not required" ,'' +where +.I argv0 +is the program name variable as set by +.I ARGBEGIN +(see +.IR arg (2)). +.TP +.I Attach +The +.I attach +function should check the authentication state of +.I afid +if desired, +and set +.IB r -> fid -> qid +and +.I ofcall.qid +to the qid of the file system root. +.I Attach +may be nil only if file trees are in use; +in this case, the qid will be filled from the root +of the tree, and no authentication will be done. +.TP +.I Walk +If file trees are in use, +.I walk +is handled internally, and +.IB srv -> walk +is never called. +.IP +If file trees are not in use, +.I walk +should consult +.IB r -> ifcall . wname +and +.IB r -> ifcall . nwname \fR, +filling in +.IB ofcall . qid +and +.IB ofcall . nqid \fR, +and also copying any necessary +.I aux +state from +.IB r -> fid +to +.IB r -> newfid +when the two are different. +As long as +.I walk +sets +.IB ofcall . nqid +appropriately, it can +.I respond +with a nil error string even when 9P +demands an error +.RI ( e.g. , +in the case of a short walk); +the library detects error conditions and handles them appropriately. +.IP +Because implementing the full walk message is intricate and +prone to error, the helper routine +.I walkandclone +will handle the request given pointers to two functions +.I walk1 +and (optionally) +.I clone . +.IR Clone , +if non-nil, is called to signal the creation of +.I newfid +from +.IR oldfid . +Typically a +.I clone +routine will copy or increment a reference count in +.IR oldfid 's +.I aux +element. +.I Walk1 +should walk +.I fid +to +.IR name , +initializing +.IB fid -> qid +to the new path's qid. +Both should return nil +on success or an error message on error. +.I Walkandclone +will call +.I respond +after handling the request. +.TP +.I Walk1\fR, \fPClone +If the client provides functions +.IB srv -> walk1 +and (optionally) +.IB srv -> clone \fR, +the 9P service loop will call +.I walkandclone +with these functions to handle the request. +Unlike the +.I walk1 +above, +.IB srv -> walk1 +must fill in both +.IB fid -> qid +and +.BI * qid +with the new qid on a successful walk. +.TP +.I Open +If file trees are in use, the file +metadata will be consulted on open, create, remove, and wstat +to see if the requester has the appropriate permissions. +If not, an error will be sent back without consulting a service function. +.PP +If not using file trees or the user has the appropriate permissions, +.I open +is called with +.IB r -> ofcall . qid +already initialized to the one stored in the +.B Fid +structure (that is, the one returned in the previous walk). +If the qid changes, both should be updated. +.TP +.I Create +The +.I create +function must fill in +both +.IB r -> fid -> qid +and +.IB r -> ofcall . qid +on success. +When using file trees, +.I create +should allocate a new +.B File +with +.IR createfile ; +note that +.I createfile +may return nil (because, say, the file already exists). +If the +.I create +function is nil, +.I srv +behaves as though it were a function that always responded +with the error ``create prohibited''. +.TP +.I Remove +.I Remove +should mark the file as removed, whether +by calling +.I removefile +when using file trees, or by updating an internal data structure. +In general it is not a good idea to clean up the +.I aux +information associated with the corresponding +.B File +at this time, to avoid memory errors if other +fids have references to that file. +Instead, it is suggested that +.I remove +simply mark the file as removed (so that further +operations on it know to fail) and wait until the +file tree's destroy function is called to reclaim the +.I aux +pointer. +If not using file trees, it is prudent to take the +analogous measures. +If +.I remove +is not provided, all remove requests will draw +``remove prohibited'' errors. +.TP +.I Read +The +.I read +function must be provided; it fills +.IB r -> ofcall . data +with at most +.IB r -> ifcall . count +bytes of data from offset +.IB r -> ifcall . offset +of the file. +It also sets +.IB r -> ofcall . count +to the number of bytes being returned. +If using file trees, +.I srv +will handle reads of directories internally, only +calling +.I read +for requests on files. +.I Readstr +and +.I readbuf +are useful for satisfying read requests on a string or buffer. +Consulting the request in +.IB r -> ifcall \fR, +they fill +.IB r -> ofcall . data +and set +.IB r -> ofcall . count \fR; +they do not call +.IB respond . +Similarly, +.I dirread9p +can be used to handle directory reads in servers +not using file trees. +The passed +.I gen +function will be called as necessary to +fill +.I dir +with information for the +.IR n th +entry in the directory. +The string pointers placed in +.I dir +should be fresh copies +made with +.IR estrdup9p ; +they will be freed by +.I dirread9p +after each successful call to +.IR gen . +.I Gen +should return zero if it successfully filled +.IR dir , +minus one on end of directory. +.TP +.I Write +The +.I write +function is similar but need not be provided. +If it is not, all writes will draw +``write prohibited'' errors. +Otherwise, +.I write +should attempt to write the +.IB r -> ifcall . count +bytes of +.IB r -> ifcall . data +to offset +.IB r -> ifcall . offset +of the file, setting +.IB r -> ofcall . count +to the number of bytes actually written. +Most programs consider it an error to +write less than the requested amount. +.TP +.I Stat +.I Stat +should fill +.IB r -> d +with the stat information for +.IB r -> fid \fR. +If using file trees, +.IB r -> d +will have been initialized with the stat info from +the tree, and +.I stat +itself may be nil. +.TP +.I Wstat +The +.I wstat +consults +.IB r -> d +in changing the metadata for +.IB r -> fid +as described in +.IR stat (5). +When using file trees, +.I srv +will take care to check that the request satisfies +the permissions outlined in +.IR stat (5). +Otherwise +.I wstat +should take care to enforce permissions +where appropriate. +.TP +.I Flush +Single-threaded servers, which always call +.I respond +before returning from the service functions, +need not provide a +.I flush +implementation: +.I flush +is only necessary in multithreaded programs, +which arrange for +.I respond +to be called asynchronously. +.I Flush +should cause the request +.IB r -> oldreq +to be cancelled or hurried along. +If +.I oldreq +is cancelled, this should be signalled by calling +.I respond +on +.I oldreq +with error string +.RB ` interrupted '. +.I Flush +must respond to +.I r +with a nil error string. +.I Flush +may respond to +.I r +before forcing a response to +.IB r -> oldreq \fR. +In this case, the library will delay sending +the +.I Rflush +message until the response to +.IB r -> oldreq +has been sent. +.PD +.PP +.IR Destroyfid , +.IR destroyreq , +and +.I end +are auxiliary functions, not called in direct response to 9P requests. +.TP +.I Destroyfid +When a +.BR Fid 's +reference count drops to zero +.RI ( i.e., +it has been clunked and there are no outstanding +requests referring to it), +.I destroyfid +is called to allow the program to dispose +of the +.IB fid -> aux +pointer. +.TP +.I Destroyreq +Similarly, when a +.BR Req 's +reference count drops to zero +.RI ( i.e. , +it has been handled via +.I respond +and other outstanding pointers to it have been closed), +.I destroyreq +is called to allow the program to dispose of the +.IB r -> aux +pointer. +.TP +.I End +Once the 9P service loop has finished +(end of file been reached on the service pipe +or a bad message has been read), +.I end +is called (if provided) to allow any final cleanup. +For example, it was used by the Palm Pilot synchronization +file system (never finished) to gracefully terminate the serial conversation once +the file system had been unmounted. +After calling +.IR end , +the service loop (which runs in a separate process +from its caller) terminates using +.I _exits +(see +.IR exits (2)). +.PD +.PP +If the +.B chatty9p +flag is at least one, +a transcript of the 9P session is printed +on standard error. +If the +.B chatty9p +flag is greater than one, +additional unspecified debugging output is generated. +By convention, servers written using this library +accept the +.B -D +option to increment +.BR chatty9p . +.SH EXAMPLES +.IR Archfs (4), +.IR cdfs (4), +.IR nntpfs (4), +.IR snap (4), +and +.B /sys/src/lib9p/ramfs.c +are good examples of simple single-threaded file servers. +.IR Webfs (4) +and +.I sshnet +(see +.IR ssh (1)) +are good examples of multithreaded file servers. +.PP +In general, the +.B File +interface is appropriate for maintaining arbitrary file trees (as in +.IR ramfs ). +The +.B File +interface is best avoided when the +tree structure is easily generated as necessary; +this is true when the tree is highly structured (as in +.I cdfs +and +.IR nntpfs ) +or is maintained elsewhere. +.SH SOURCE +.B /sys/src/lib9p +.SH SEE ALSO +.IR 9pfid (2), +.IR 9pfile (2), +.IR srv (3), +.IR intro (5) +.SH BUGS +The switch to 9P2000 was taken as an opportunity to tidy +much of the interface; we promise to avoid such gratuitous change +in the future. diff --git a/man/man3/9pcmdbuf.3 b/man/man3/9pcmdbuf.3 new file mode 100644 index 00000000..ccb5419b --- /dev/null +++ b/man/man3/9pcmdbuf.3 @@ -0,0 +1,116 @@ +.TH 9PCMDBUF 3 +.SH NAME +Cmdbuf, parsecmd, respondcmderror, lookupcmd \- control message parsing +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fL1234'u +\w'\fL12345678'u +typedef struct Cmdbuf +{ + char *buf; + char **f; + int nf; +} Cmdbuf; + +typedef struct Cmdtab +{ + int index; + char *cmd; + int narg; +}; + +Cmdbuf *parsecmd(char *p, int n) +Cmdtab *lookupcmd(Cmdbuf *cb, Cmdtab *tab, int ntab) +void respondcmderror(Req *r, Cmdbuf *cb, char *fmt, ...) +.fi +.SH DESCRIPTION +These data structures and functions provide parsing of textual control messages. +.PP +.I Parsecmd +treats the +.I n +bytes at +.I p +(which need not be NUL-terminated) as a UTF string and splits it +using +.IR tokenize (2). +It returns a +.B Cmdbuf +structure holding pointers to each field in the message. +.PP +.I Lookupcmd +walks through the array +.IR ctab , +which has +.I ntab +entries, +looking for the first +.B Cmdtab +that matches the parsed command. +(If the parsed command is empty, +.I lookupcmd +returns nil immediately.) +A +.B Cmdtab +matches the command if +.I cmd +is equal to +.IB cb -> f [0] +or if +.I cmd +is +.LR * . +Once a matching +.B Cmdtab +has been found, if +.I narg +is not zero, then the parsed command +must have exactly +.I narg +fields (including the command string itself). +If the command has the wrong number of arguments, +.I lookupcmd +returns nil. +Otherwise, it returns a pointer to the +.B Cmdtab +entry. +If +.I lookupcmd +does not find a matching command at all, +it returns nil. +Whenever +.I lookupcmd +returns nil, it sets the system error string. +.PP +.I Respondcmderror +resoponds to request +.I r +with an error of the form +`\fIfmt\fB:\fI cmd\fR,' +where +.I fmt +is the formatted string and +.I cmd +is a reconstruction of the parsed command. +Fmt +is often simply +.B "%r" . +.SH EXAMPLES +This interface is not used in any distributed 9P servers. +It was lifted from the Plan 9 kernel. +Almost any kernel driver +.RB ( /sys/src/9/*/dev*.c ) +is a good example. +.SH SOURCE +.B /sys/src/lib9p/parse.c +.SH SEE ALSO +.IR 9p (2) diff --git a/man/man3/9pfid.3 b/man/man3/9pfid.3 new file mode 100644 index 00000000..ac0f2bfc --- /dev/null +++ b/man/man3/9pfid.3 @@ -0,0 +1,204 @@ +.TH 9PFID 3 +.SH NAME +Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, removefid, +Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq, lookupreq, removereq \- 9P fid, request tracking +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fL 'u +\w'\fLulong 'u +typedef struct Fid +{ + ulong fid; + char omode; /* -1 if not open */ + char *uid; + Qid qid; + File *file; + void *aux; + \fI...\fP +} Fid; +.fi +.PP +.ft L +.nf +.ta \w'\fL 'u +\w'\fLulong 'u +typedef struct Req +{ + ulong tag; + Fcall ifcall; + Fcall ofcall; + Req *oldreq; + void *aux; + \fI...\fP +} Req; +.fi +.PP +.ft L +.nf +.ta \w'\fLFidpool* 'u +Fidpool* allocfidpool(void (*destroy)(Fid*)) +void freefidpool(Fidpool *p) +Fid* allocfid(Fidpool *p, ulong fid) +Fid* lookupfid(Fidpool *p, ulong fid) +void closefid(Fid *f) +void removefid(Fid *f) +.fi +.PP +.ft L +.nf +.ta \w'\fLReqpool* 'u +Reqpool* allocreqpool(void (*destroy)(Req*)) +void freereqpool(Reqpool *p) +Req* allocreq(Reqpool *p, ulong tag) +Req* lookupreq(Reqpool *p, ulong tag) +void closereq(Req *f) +void removereq(Req *r) +.fi +.SH DESCRIPTION +These routines provide management of +.B Fid +and +.B Req +structures from +.BR Fidpool s +and +.BR Reqpool s. +They are primarily used by the 9P server loop +described in +.IR 9p (2). +.PP +.B Fid +structures are intended to represent +active fids in a 9P connection, as +.B Chan +structures do in the Plan 9 kernel. +The +.B fid +element is the integer fid used in the 9P +connection. +.B Omode +is the mode under which the fid was opened, or +.B -1 +if this fid has not been opened yet. +Note that in addition to the values +.BR OREAD , +.BR OWRITE , +and +.BR ORDWR , +.B omode +can contain the various flags permissible in +an open call. +To ignore the flags, use +.BR omode&OMASK . +.B Omode +should not be changed by the client. +The fid derives from a successful authentication by +.BR uid . +.B Qid +contains the qid returned in the last successful +.B walk +or +.B create +transaction involving the fid. +In a file tree-based server, the +.BR Fid 's +.B file +element points at a +.B File +structure +(see +.IR 9pfile (2)) +corresponding to the fid. +The +.B aux +member is intended for use by the +client to hold information specific to a particular +.BR Fid . +With the exception of +.BR aux , +these elements should be treated +as read-only by the client. +.PP +.I Allocfidpool +creates a new +.BR Fidpool . +.I Freefidpool +destroys such a pool. +.I Allocfid +returns a new +.B Fid +whose fid number is +.IR fid . +There must not already be an extant +.B Fid +with that number in the pool. +Once a +.B Fid +has been allocated, it can be looked up by +fid number using +.IR lookupfid . +.BR Fid s +are reference counted: both +.I allocfid +and +.I lookupfid +increment the reference count on the +.B Fid +structure before +returning. +When a reference to a +.B Fid +is no longer needed, +.I closefid +should be called to note the destruction of the reference. +When the last reference to a +.B Fid +is removed, if +.I destroy +(supplied when creating the fid pool) +is not zero, it is called with the +.B Fid +as a parameter. +It should perform whatever cleanup is necessary +regarding the +.B aux +element. +.I Removefid +is equivalent to +.I closefid +but also removes the +.B Fid +from the pool. +Note that due to lingering references, +the return of +.I removefid +may not mean that +.I destroy +has been called. +.PP +.IR Allocreqpool , +.IR freereqpool , +.IR allocreq , +.IR lookupreq , +.IR closereq , +and +.I removereq +are analogous but +operate on +.BR Reqpool s +and +.B Req +structures. +.SH SOURCE +.B /sys/src/lib9p +.SH SEE ALSO +.IR 9p (2), +.IR 9pfile (2) diff --git a/man/man3/9pfile.3 b/man/man3/9pfile.3 new file mode 100644 index 00000000..f374743e --- /dev/null +++ b/man/man3/9pfile.3 @@ -0,0 +1,223 @@ +.TH 9PFILE 3 +.SH NAME +Tree, alloctree, freetree, +File, createfile, closefile, removefile, walkfile, +opendirfile, readdirfile, closedirfile, hasperm \- in-memory file hierarchy +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fLFile 'u +typedef struct File +{ + Ref; + Dir; + void *aux; + \fI...\fP +} File; +.fi +.PP +.ft L +.nf +.ta \w'\fLTree 'u +typedef struct Tree +{ + File *root; + \fI...\fP +} Tree; +.fi +.PP +.ft L +.nf +.ta \w'\fLReaddir* 'u +4n +4n +Tree* alloctree(char *uid, char *gid, ulong mode, + void (*destroy)(File*)) +void freetree(Tree *tree) +File* createfile(File *dir, char *name, char *uid, + ulong mode, void *aux) +int removefile(File *file) +void closefile(File *file) +File* walkfile(File *dir, char *path) +Readdir* opendirfile(File *dir) +long readdirfile(Readdir *rdir, char *buf, long n) +void closedirfile(Readdir *rdir) +int hasperm(File *file, char *uid, int p) +.fi +.SH DESCRIPTION +.BR File s +and +.BR Tree s +provide an in-memory file hierarchy +intended for use in 9P file servers. +.PP +.I Alloctree +creates a new tree of files, and +.I freetree +destroys it. +The root of the tree +(also the +.B root +element in the structure) +will have mode +.I mode +and be owned by user +.I uid +and group +.IR gid . +.I Destroy +is used when freeing +.B File +structures and is described later. +.PP +.BR File s +(including directories) +other than the root are created using +.IR createfile , +which attempts to create a file named +.I name +in the directory +.IR dir . +If created, the file will have owner +.I uid +and have a group inherited from +the directory. +.I Mode +and the permissions of +.I dir +are used to calculate the permission bits for +the file as described in +.IR open (5). +It is permissible for +.I name +to be a slash-separated path rather than a single element. +.PP +.I Removefile +removes a file from the file tree. +The file will not be freed until the last +reference to it has been removed. +Directories may only be removed when empty. +.I Removefile +returns zero on success, \-1 on error. +It is correct to consider +.I removefile +to be +.I closefile +with the side effect of removing the file +when possible. +.PP +.I Walkfile +evaluates +.I path +relative to the directory +.IR dir , +returning the resulting file, +or zero if the named file or any intermediate element +does not exist. +.PP +The +.B File +structure's +.B aux +pointer may be used by the client +for +.RB per- File +storage. +.BR File s +are reference-counted: if not zero, +.I destroy +(specified in the call to +.IR alloctree ) +will be called for each file when its +last reference is removed or when the tree is freed. +.I Destroy +should take care of any necessary cleanup related to +.BR aux . +When creating new file references by copying pointers, +call +.I incref +(see +.IR lock (2)) +to update the reference count. +To note the removal of a reference to a file, call +.IR closefile . +.I Createfile +and +.I walkfile +return new references. +.IR Removefile , +.IR closefile , +and +.I walkfile +(but not +.IR createfile ) +consume the passed reference. +.PP +Directories may be read, yielding a directory entry structure +(see +.IR stat (5)) +for each file in the directory. +In order to allow concurrent reading of directories, +clients must obtain a +.B Readdir +structure by calling +.I opendirfile +on a directory. +Subsequent calls to +.I readdirfile +will each yield an integral number of machine-independent +stat buffers, until end of directory. +When finished, call +.I closedirfile +to free the +.BR Readdir . +.PP +.I Hasperm +does simplistic permission checking; it assumes only +one-user groups named by uid and returns non-zero if +.I uid +has permission +.I p +(a bitwise-or of +.BR AREAD , +.BR AWRITE +and +.BR AEXEC ) +according to +.IB file ->mode \fR. +9P servers written using +.B File +trees will do standard permission checks automatically; +.I hasperm +may be called explicitly to do additional checks. +A 9P server may link against a different +.I hasperm +implementation to provide more complex groups. +.SH EXAMPLE +The following code correctly handles references +when elementwise walking a path and creating a file. +.IP +.EX +f = tree->root; +incref(f); +for(i=0; i +.br +.B #include +.PP +.nf +.B +void abort(void) +.fi +.SH DESCRIPTION +.I Abort +causes an access fault, causing the current process to enter the `Broken' state. +The process can then be inspected by a debugger. +.SH SOURCE +.B /sys/src/libc/9sys/abort.c diff --git a/man/man3/abs.3 b/man/man3/abs.3 new file mode 100644 index 00000000..79ec4a3c --- /dev/null +++ b/man/man3/abs.3 @@ -0,0 +1,33 @@ +.TH ABS 3 +.SH NAME +abs, labs \- integer absolute values +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int abs(int a) +.PP +.B +long labs(long a) +.SH DESCRIPTION +.I Abs +returns +the absolute value of integer +.IR a , +and +.I labs +does the same for a long. +.SH SOURCE +.B /sys/src/libc/port/abs.c +.SH SEE ALSO +.IR floor (2) +for +.I fabs +.SH DIAGNOSTICS +.I Abs +and +.I labs +return +the most negative integer or long when the true result is unrepresentable. diff --git a/man/man3/access.3 b/man/man3/access.3 new file mode 100644 index 00000000..a892cdea --- /dev/null +++ b/man/man3/access.3 @@ -0,0 +1,60 @@ +.TH ACCESS 3 +.SH NAME +access \- determine accessibility of file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int access(char *name, int mode) +.SH DESCRIPTION +.I Access +evaluates the given +file +.I name +for accessibility. +If \fImode\fL&4\fR +is nonzero, +read permission is expected; +if \fImode\fL&2\fR, +write permission; +if \fImode\fL&1\fR, +execute permission. +If \fImode\fL==0\fR, +the file merely need exist. +In any case +all directories leading to the file +must permit searches. +Zero is returned if the desired access is permitted, +\-1 if not. +.PP +Only access for open is checked. +A file may look executable, but +.IR exec (2) +will fail unless it is in proper format. +.PP +The include file +.F +defines +.BR AEXIST =0, +.BR AEXEC =1, +.BR AWRITE =2, +and +.BR AREAD =4. +.PP +.SH SOURCE +.B /sys/src/libc/9sys/access.c +.SH SEE ALSO +.IR stat (2) +.SH DIAGNOSTICS +Sets +.IR errstr . +.SH BUGS +Since file permissions are checked by the server and group information +is not known to the client, +.I access +must open the file to check permissions. +(It calls +.IR stat (2) +to check simple existence.) diff --git a/man/man3/addpt.3 b/man/man3/addpt.3 new file mode 100644 index 00000000..81476f43 --- /dev/null +++ b/man/man3/addpt.3 @@ -0,0 +1,188 @@ +.TH ADDPT 3 +.SH NAME +addpt, subpt, mulpt, divpt, rectaddpt, rectsubpt, insetrect, canonrect, eqpt, eqrect, ptinrect, rectinrect, rectXrect, rectclip, combinerect, Dx, Dy, Pt, Rect, Rpt \- arithmetic on points and rectangles +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +Point addpt(Point p, Point q) +.PP +.B +Point subpt(Point p, Point q) +.PP +.B +Point mulpt(Point p, int a) +.PP +.B +Point divpt(Point p, int a) +.PP +.B +Rectangle rectaddpt(Rectangle r, Point p) +.PP +.B +Rectangle rectsubpt(Rectangle r, Point p) +.PP +.B +Rectangle insetrect(Rectangle r, int n) +.PP +.B +Rectangle canonrect(Rectangle r) +.PP +.B +int eqpt(Point p, Point q) +.PP +.B +int eqrect(Rectangle r, Rectangle s) +.PP +.B +int ptinrect(Point p, Rectangle r) +.PP +.B +int rectinrect(Rectangle r, Rectangle s) +.PP +.B +int rectXrect(Rectangle r, Rectangle s) +.PP +.B +int rectclip(Rectangle *rp, Rectangle b) +.PP +.B +void combinerect(Rectangle *rp, Rectangle b) +.PP +.B +int Dx(Rectangle r) +.PP +.B +int Dy(Rectangle r) +.PP +.B +Point Pt(int x, int y) +.PP +.B +Rectangle Rect(int x0, int y0, int x1, int y1) +.PP +.B +Rectangle Rpt(Point p, Point q) +.SH DESCRIPTION +The functions +.IR Pt , +.I Rect +and +.I Rpt +construct geometrical data types from their components. +.PP +.I Addpt +returns the Point +sum of its arguments: +.BI Pt( p .x+ q .x, +.IB p .y+ q .y) \f1. +.I Subpt +returns the Point +difference of its arguments: +.BI Pt( p .x- q .x, +.IB p .y- q .y) \f1. +.I Mulpt +returns the Point +.BI Pt( p .x* a , +.IB p .y* a ) \f1. +.I Divpt +returns the Point +.BI Pt( p .x/ a , +.IB p .y/ a ) \f1. +.PP +.I Rectaddpt +returns the Rectangle +.BI Rect(add( r .min, +.IB p ) \f1, +.BI add( r .max, +.IB p )) \f1; +.I rectsubpt +returns the Rectangle +.BI Rpt(sub( r .min, +.IB p ), +.BI sub( r .max, +.IB p ))\fR. +.PP +.I Insetrect +returns the Rectangle +.BI Rect( r .min.x+ n \f1, +.IB r .min.y+ n \f1, +.IB r .max.x- n \f1, +.IB r .max.y- n ) \f1. +.PP +.I Canonrect +returns a rectangle with the same extent as +.IR r , +canonicalized so that +.B min.x +≤ +.BR max.x , +and +.B min.y +≤ +.BR max.y . +.PP +.I Eqpt +compares its argument Points and returns +0 if unequal, +1 if equal. +.I Eqrect +does the same for its argument Rectangles. +.PP +.I Ptinrect +returns 1 if +.I p +is a point within +.IR r , +and 0 otherwise. +.PP +.I Rectinrect +returns 1 if all the pixels in +.I r +are also in +.IR s , +and 0 otherwise. +.PP +.I RectXrect +returns 1 if +.I r +and +.I s +share any point, and 0 otherwise. +.PP +.I Rectclip +clips in place +the Rectangle pointed to by +.I rp +so that it is completely contained within +.IR b . +The return value is 1 if any part of +.RI * rp +is within +.IR b . +Otherwise, the return value is 0 and +.RI * rp +is unchanged. +.PP +.I Combinerect +overwrites +.B *rp +with the smallest rectangle sufficient to cover all the pixels of +.B *rp +and +.BR b . +.PP +The functions +.I Dx +and +.I Dy +give the width (Δx) and height (Δy) of a Rectangle. +They are implemented as macros. +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2) diff --git a/man/man3/aes.3 b/man/man3/aes.3 new file mode 100644 index 00000000..6b23c861 --- /dev/null +++ b/man/man3/aes.3 @@ -0,0 +1,51 @@ +.TH AES 3 +.SH NAME +setupAESstate, aesCBCencrypt, aesCBCdecrypt - advanced encryption standard (rijndael) +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void setupAESstate(AESstate *s, uchar key[], int keybytes, uchar *ivec) +.PP +.B +void aesCBCencrypt(uchar*, int, AESstate*) +.PP +.B +void aesCBCdecrypt(uchar*, int, AESstate*) +.PP +.SH DESCRIPTION +.PP +DES is being replaced by Rijndael, also known as AES, as the preferred +block ciper. +.IR setupAESstate , +.IR aesCBCencrypt , +and +.I aesCBCdecrypt +implement cipher block chaining encryption. +.I Keybytes +should be 16, 24, or 32. +The initialization vector +.I ivec +of +.I AESbsize +bytes should random enough to be unlikely to be reused but does not need to be +cryptographically strongly unpredictable. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR blowfish (2), +.IR des (2), +.IR dsa (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/man/man3/allocimage.3 b/man/man3/allocimage.3 new file mode 100644 index 00000000..f7eb2ff5 --- /dev/null +++ b/man/man3/allocimage.3 @@ -0,0 +1,348 @@ +.TH ALLOCIMAGE 3 +.SH NAME +allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline \- allocating, freeing, reading, writing images +.SH SYNOPSIS +.nf +.PP +.B +#include +.B +#include +.B +#include +.PP +.ta \w'\fLImage 'u +.B +Image *allocimage(Display *d, Rectangle r, +.br +.B + ulong chan, int repl, int col) +.PP +.B +Image *allocimagemix(Display *d, ulong one, ulong three) +.PP +.B +void freeimage(Image *i) +.PP +.B +int nameimage(Image *i, char *name, int in) +.PP +.B +Image *namedimage(Display *d, char *name) +.PP +.B +ulong setalpha(ulong color, uchar alpha) +.PP +.B +int loadimage(Image *i, Rectangle r, uchar *data, int ndata) +.PP +.B +int cloadimage(Image *i, Rectangle r, uchar *data, int ndata) +.PP +.B +int unloadimage(Image *i, Rectangle r, uchar *data, int ndata) +.PP +.B +Image *readimage(Display *d, int fd, int dolock) +.PP +.B +int writeimage(int fd, Image *i, int dolock) +.PP +.B +int bytesperline(Rectangle r, int d) +.PP +.B +int wordsperline(Rectangle r, int d) +.PP +.nf +.B +enum +.nf +.ft L +.ta +4n +20 +{ + DOpaque = 0xFFFFFFFF, + DTransparent = 0x00000000, + DBlack = 0x000000FF, + DWhite = 0xFFFFFFFF, + DRed = 0xFF0000FF, + DGreen = 0x00FF00FF, + DBlue = 0x0000FFFF, + DCyan = 0x00FFFFFF, + DMagenta = 0xFF00FFFF, + DYellow = 0xFFFF00FF, + DPaleyellow = 0xFFFFAAFF, + DDarkyellow = 0xEEEE9EFF, + DDarkgreen = 0x448844FF, + DPalegreen = 0xAAFFAAFF, + DMedgreen = 0x88CC88FF, + DDarkblue = 0x000055FF, + DPalebluegreen = 0xAAFFFFFF, + DPaleblue = 0x0000BBFF, + DBluegreen = 0x008888FF, + DGreygreen = 0x55AAAAFF, + DPalegreygreen = 0x9EEEEEFF, + DYellowgreen = 0x99994CFF, + DMedblue = 0x000099FF, + DGreyblue = 0x005DBBFF, + DPalegreyblue = 0x4993DDFF, + DPurpleblue = 0x8888CCFF, + + DNotacolor = 0xFFFFFF00, + DNofill = DNotacolor, + +}; +.fi +.SH DESCRIPTION +A new +.B Image +on +.B Display +.B d +is allocated with +.BR allocimage ; +it will have the rectangle, pixel channel format, +and replication flag +given by its arguments. +Convenient pixel channels like +.BR GREY1 , +.BR GREY2 , +.BR CMAP8 , +.BR RGB16 , +.BR RGB24 , +and +.BR RGBA32 +are predefined. +All the new image's pixels will have initial value +.IR col . +If +.I col +is +.BR DNofill , +no initialization is done. +Representative useful values of color are predefined: +.BR DBlack , +.BR DWhite , +.BR DRed , +and so on. +Colors are specified by 32-bit numbers comprising, +from most to least significant byte, +8-bit values for red, green, blue, and alpha. +The values correspond to illumination, so 0 is black and 255 is white. +Similarly, for alpha 0 is transparent and 255 is opaque. +The +.I id +field will have been set to the identifying number used by +.B /dev/draw +(see +.IR draw (3)), +and the +.I cache +field will be zero. +If +.I repl +is true, the clip rectangle is set to a very large region; if false, it is set to +.IR r . +The +.I depth +field will be set to the number of bits per pixel specified +by the channel descriptor +(see +.IR image (6)). +.I Allocimage +returns 0 if the server has run out of image memory. +.PP +.I Allocimagemix +is used to allocate background colors. +On 8-bit color-mapped displays, it +returns a 2×2 replicated image with one pixel colored +the color +.I one +and the other three with +.IR three . +(This simulates a wider range of tones than can be represented by a single pixel +value on a color-mapped display.) +On true color displays, it returns a 1×1 replicated image +whose pixel is the result of mixing the two colors in +a one to three ratio. +.PP +.I Freeimage +frees the resources used by its argument image. +.PP +.I Nameimage +publishes in the server the image +.I i +under the given +.IR name . +If +.I in +is non-zero, the image is published; otherwise +.I i +must be already named +.I name +and it is withdrawn from publication. +.I Namedimage +returns a reference to the image published under the given +.I name +on +.B Display +.IR d . +These routines permit unrelated applications sharing a display to share an image; +for example they provide the mechanism behind +.B getwindow +(see +.IR graphics (2)). +.PP +The RGB values in a color are +.I premultiplied +by the alpha value; for example, a 50% red is +.B 0x7F00007F +not +.BR 0xFF00007F . +The function +.I setalpha +performs the alpha computation on a given +.BR color , +ignoring its initial alpha value, multiplying the components by the supplied +.BR alpha . +For example, to make a 50% red color value, one could execute +.B setalpha(DRed, +.BR 0x7F) . +.PP +The remaining functions deal with moving groups of pixel +values between image and user space or external files. +There is a fixed format for the exchange and storage of +image data +(see +.IR image (6)). +.PP +.I Unloadimage +reads a rectangle of pixels from image +.I i +into +.IR data , +whose length is specified by +.IR ndata . +It is an error if +.I ndata +is too small to accommodate the pixels. +.PP +.I Loadimage +replaces the specified rectangle in image +.I i +with the +.I ndata +bytes of +.IR data . +.PP +The pixels are presented one horizontal line at a time, +starting with the top-left pixel of +.IR r . +In the data processed by these routines, each scan line starts with a new byte in the array, +leaving the last byte of the previous line partially empty, if necessary. +Pixels are packed as tightly as possible within +.IR data , +regardless of the rectangle being extracted. +Bytes are filled from most to least significant bit order, +as the +.I x +coordinate increases, aligned so +.IR x =0 +would appear as the leftmost pixel of its byte. +Thus, for +.B depth +1, the pixel at +.I x +offset 165 within the rectangle will be in a +.I data +byte at bit-position +.B 0x04 +regardless of the overall +rectangle: 165 mod 8 equals 5, and +.B "0x80\ >>\ 5" +equals +.BR 0x04 . +.PP +.B Cloadimage +does the same as +.IR loadimage , +but for +.I ndata +bytes of compressed image +.I data +(see +.IR image (6)). +On each call to +.IR cloadimage, +the +.I data +must be at the beginning of a compressed data block, in particular, +it should start with the +.B y +coordinate and data length for the block. +.PP +.IR Loadimage , +.IR cloadimage , +and +.I unloadimage +return the number of bytes copied. +.PP +.I Readimage +creates an image from data contained in an external file (see +.IR image (6) +for the file format); +.I fd +is a file descriptor obtained by opening such a file for reading. +The returned image is allocated using +.IR allocimage . +The +.I dolock +flag specifies whether the +.B Display +should be synchronized for multithreaded access; single-threaded +programs can leave it zero. +.PP +.I Writeimage +writes image +.I i +onto file descriptor +.IR fd , +which should be open for writing. +The format is as described for +.IR readimage . +.PP +.I Readimage +and +.I writeimage +do not close +.IR fd . +.PP +.I Bytesperline +and +.I wordsperline +return the number of bytes or words occupied in memory by one scan line of rectangle +.I r +in an image with +.I d +bits per pixel. +.SH EXAMPLE +To allocate a single-pixel replicated image that may be used to paint a region red, +.EX + red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed); +.EE +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR graphics (2), +.IR draw (2), +.IR draw (3), +.IR image (6) +.SH DIAGNOSTICS +These functions return pointer 0 or integer \-1 on failure, usually due to insufficient +memory. +.PP +May set +.IR errstr . +.SH BUGS +.B Depth +must be a divisor or multiple of 8. diff --git a/man/man3/arg.3 b/man/man3/arg.3 new file mode 100644 index 00000000..9036cdbc --- /dev/null +++ b/man/man3/arg.3 @@ -0,0 +1,124 @@ +.TH ARG 3 +.SH NAME +ARGBEGIN, ARGEND, ARGC, ARGF, EARGF, arginit, argopt \- process option letters from argv +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B ARGBEGIN { +.B char *ARGF(); +.B char *EARGF(code); +.B Rune ARGC(); +.B } ARGEND +.PP +.B extern char *argv0; +.SH DESCRIPTION +These macros assume the names +.I argc +and +.I argv +are in scope; see +.IR exec (2). +.I ARGBEGIN +and +.I ARGEND +surround code for processing program options. +The code +should be the cases of a C switch on +option characters; +it is executed once for each option character. +Options end after an argument +.BR -- , +before an argument +.BR - , +or before an argument that doesn't begin with +.BR - . +.PP +The function macro +.I ARGC +returns the current option character, as an integer. +.PP +The function macro +.I ARGF +returns the current option argument: +a pointer to the rest of the option string if not empty, +or the next argument in +.I argv +if any, or 0. +.I ARGF +must be called just once for each option +that takes an argument. +The macro +.I EARGF +is like +.I ARGF +but instead of returning zero +runs +.I code +and, if that returns, calls +.IR abort (2). +A typical value for +.I code +is +.BR usage() , +as in +.BR EARGF(usage()) . +.PP +After +.IR ARGBEGIN , +.I argv0 +is a copy of +.BR argv[0] +(conventionally the name of the program). +.PP +After +.IR ARGEND , +.I argv +points at a zero-terminated list of the remaining +.I argc +arguments. +.SH EXAMPLE +This C program can take option +.B b +and option +.BR f , +which requires an argument. +.IP +.EX +.ta \w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u +#include +#include +void +main(int argc, char *argv[]) +{ + char *f; + print("%s", argv[0]); + ARGBEGIN { + case 'b': + print(" -b"); + break; + case 'f': + print(" -f(%s)", (f=ARGF())? f: "no arg"); + break; + default: + print(" badflag('%c')", ARGC()); + } ARGEND + print(" %d args:", argc); + while(*argv) + print(" '%s'", *argv++); + print("\en"); + exits(nil); +} +.EE +.PP +Here is the output from running the command +.B +prog -bffile1 -r -f file2 arg1 arg2 +.IP +.B +prog -b -f(file1) badflag('r') -f(file2) 2 args: 'arg1' 'arg2' +.PP +.SH SOURCE +.B /sys/include/libc.h diff --git a/man/man3/assert.3 b/man/man3/assert.3 new file mode 100644 index 00000000..135560f5 --- /dev/null +++ b/man/man3/assert.3 @@ -0,0 +1,25 @@ +.TH ASSERT 3 +.SH NAME +assert \- check program invariants +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +#define assert if(cond);else _assert("cond") +.PP +.B +void _assert(int cond) +.SH DESCRIPTION +.I Assert +is a preprocessor macro that +(via +.IR _assert ) +prints a message and calls +.I abort +when +.I cond +is false. +.SH SOURCE +.B /sys/src/libc/port/_assert.c diff --git a/man/man3/atof.3 b/man/man3/atof.3 new file mode 100644 index 00000000..9f7e7759 --- /dev/null +++ b/man/man3/atof.3 @@ -0,0 +1,146 @@ +.TH ATOF 3 +.SH NAME +atof, atoi, atol, atoll, charstod, strtod, strtol, strtoll, strtoul, strtoull \- convert text to numbers +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.ta \w'\fLdouble 'u +.B +double atof(char *nptr) +.PP +.B +int atoi(char *nptr) +.PP +.B +long atol(char *nptr) +.PP +.B +vlong atoll(char *nptr) +.PP +.B +double charstod(int (*f)(void *), void *a) +.PP +.B +double strtod(char *nptr, char **rptr) +.PP +.B +long strtol(char *nptr, char **rptr, int base) +.PP +.B +vlong strtoll(char *nptr, char **rptr, int base) +.PP +.B +ulong strtoul(char *nptr, char **rptr, int base) +.PP +.B +vlong strtoull(char *nptr, char **rptr, int base) +.fi +.SH DESCRIPTION +.IR Atof , +.IR atoi , +.IR atol , +and +.I atoll +convert a string pointed to by +.I nptr +to floating, integer, long integer, and long long integer +.RB ( vlong ) +representation respectively. +The first unrecognized character ends the string. +Leading C escapes are understood, as in +.I strtol +with +.I base +zero (described below). +.PP +.I Atof +recognizes an optional string of tabs and spaces, +then an optional sign, then +a string of digits optionally containing a decimal +point, then an optional +.L e +or +.L E +followed +by an optionally signed integer. +.PP +.I Atoi +and +.I atol +recognize an optional string of tabs and spaces, +then an optional sign, then a string of +decimal digits. +.PP +.IR Strtod , +.IR strtol , +.IR strtoll , +.IR strtoul , +and +.I strtoull +behave similarly to +.I atof +and +.I atol +and, if +.I rptr +is not zero, set +.I *rptr +to point to the input character +immediately after the string converted. +.PP +.IR Strtol , +.IR strtoll , +.IR strtoul , +and +.IR strtoull +interpret the digit string in the specified +.IR base , +from 2 to 36, +each digit being less than the base. +Digits with value over 9 are represented by letters, +a-z or A-Z. +If +.I base +is 0, the input is interpreted as an integral constant in +the style of C (with no suffixed type indicators): +numbers are octal if they begin with +.LR 0 , +hexadecimal if they begin with +.L 0x +or +.LR 0X , +otherwise decimal. +.PP +.I Charstod +interprets floating point numbers in the manner of +.IR atof , +but gets successive characters by calling +.BR (*\fIf\fP)(a) . +The last call to +.I f +terminates the scan, so it must have returned a character that +is not a legal continuation of a number. +Therefore, it may be necessary to back up the input stream one character +after calling +.IR charstod . +.SH SOURCE +.B /sys/src/libc/port +.SH SEE ALSO +.IR fscanf (2) +.SH DIAGNOSTICS +Zero is returned if the beginning of the input string is not +interpretable as a number; even in this case, +.I rptr +will be updated. +.br +These routines set +.IR errstr . +.SH BUGS +.I Atoi +and +.I atol +accept octal and hexadecimal numbers in the style of C, +contrary to the ANSI specification. diff --git a/man/man3/auth.3 b/man/man3/auth.3 new file mode 100644 index 00000000..cec79ce7 --- /dev/null +++ b/man/man3/auth.3 @@ -0,0 +1,395 @@ +.TH AUTH 3 +.SH NAME +amount, newns, addns, login, noworld, auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc, auth_rpc, auth_getkey, amount_getkey, auth_freeAI, auth_chuid, auth_challenge, auth_response, auth_freechal, auth_respond, auth_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +#include +.fi +.ta 11n +4n +4n +4n +4n +4n +4n +.PP +.B +int newns(char *user, char *nsfile); +.PP +.B +int addns(char *user, char *nsfile); +.PP +.B +int amount(int fd, char *old, int flag, char *aname); +.PP +.B +int login(char *user, char *password, char *namespace); +.PP +.B +int noworld(char *user); +.PP +.B +AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...); +.PP +.B +AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey, +.br +.B char *params); +.PP +.B +AuthRpc* auth_allocrpc(int afd); +.PP +.B +void auth_freerpc(AuthRpc *rpc); +.PP +.B +uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n); +.PP +.B +int auth_getkey(char *proto, char *dom); +.PP +.B +int (*amount_getkey)(char*, char*); +.PP +.B +void auth_freeAI(AuthInfo *ai); +.PP +.B +int auth_chuid(AuthInfo *ai, char *ns); +.PP +.B +Chalstate* auth_challenge(char *fmt, ...); +.PP +.B +AuthInfo* auth_response(Chalstate*); +.PP +.B +void auth_freechal(Chalstate*); +.PP +.B +int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...); +.PP +.B +AuthInfo* auth_userpasswd(char*user, char*password); +.PP +.B +UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...); +.PP +.B +AuthInfo* auth_getinfo(int fd); +.SH DESCRIPTION +.PP +This library, in concert with +.IR factotum (4), +is used to authenticate users. +It provides the primary interface to +.IR factotum . +.PP +.I Newns +builds a name space for +.IR user . +It opens the file +.I nsfile +.RB ( /lib/namespace +is used if +.I nsfile +is null), +copies the old environment, erases the current name space, +sets the environment variables +.B user +and +.BR home , +and interprets the commands in +.IR nsfile . +The format of +.I nsfile +is described in +.IR namespace (6). +.PP +.I Addns +also interprets and executes the commands in +.IR nsfile . +Unlike +.I newns +it applies the command to the current name space +rather than starting from scratch. +.PP +.I Amount +is like +.I mount +but performs any authentication required. +It should be used instead of +.I mount +whenever the file server being mounted requires authentication. +See +.IR bind (2) +for a definition of the arguments to +.I mount +and +.IR amount . +.PP +.I Login +changes the user id of the process +.I user +and recreates the namespace using the file +.I namespace +(default +.BR /lib/nnamespace ). +It uses +.I auth_userpassword +and +.IR auth_chuid . +.PP +.I Noworld +returns 1 if the user is in the group +.B noworld +in +.BR /adm/users . +Otherwise, it returns 0. +.I Noworld +is used by telnetd and ftpd to provide sandboxed +access for some users. +.PP +The following routines use the +.B AuthInfo +structure returned after a successful authentication by +.IR factotum (4). +.PP +.ne 8 +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +typedef struct +{ + char *cuid; /* caller id */ + char *suid; /* server id */ + char *cap; /* capability */ + int nsecret; /* length of secret */ + uchar *secret; /* secret */ +} AuthInfo; +.EE +.sp +The fields +.B cuid +and +.B suid +point to the authenticated ids of the client and server. +.B Cap +is a capability returned only to the server. +It can be passed to the +.IR cap (3) +device to change the user id of the process. +.B Secret +is an +.BR nsecret -byte +shared secret that can be used by the client and server to +create encryption and hashing keys for the rest of the +conversation. +.PP +.I Auth_proxy +proxies an authentication conversation between a remote +server reading and writing +.I fd +and a +.I factotum +file. The +.I factotum +file used is +.BR /mnt/factotum/rpc . +An +.B sprint +(see +.IR print (2)) +of +.I fmt +and the variable arg list yields a key template (see +.IR factotum (4)) +specifying the key to use. +The template must specify at least the protocol ( +.BI proto= xxx ) +and the role (either +.B role=client +or +.BR role=server ). +.I Auth_proxy +either returns an allocated +.B AuthInfo +structure, or sets the error string and +returns nil. +.PP +.I Fauth_proxy +can be used instead of +.I auth_proxy +if a single connection to +.I factotum +will be used for multiple authentications. +This is necessary, for example, for +.I newns +which must open the +.I factotum +file before wiping out the namespace. +.I Fauth_proxy +takes as an argument a pointer to an +.B AuthRPC +structure which contains an fd for an open connection to +.I factotum +in addition to storage and state information for +the protocol. +An +.B AuthRPC +structure is obtained by calling +.I auth_allocrpc +with the fd of an open +.I factotum +connection. +It is freed using +.IR auth_freerpc . +Individual commands can be sent to +.IR factotum (4) +by invoking +.IR auth_rpc . +.PP +Both +.I auth_proxy +and +.I fauth_proxy +take a pointer to a routine, +.IR getkey , +to invoke should +.I factotum +not posess a key for the authentication. If +.I getkey +is nil, the authentication fails. +.I Getkey +is called with a key template for the desired +key. +We have provided a generic routine, +.IR auth_getkey , +which queries the user for +the key information and passes it to +.IR factotum . +This is the default for the global variable, +.IR amount_getkey , +which holds a pointer to the key prompting routine used by +.IR amount . +.PP +.I Auth_chuid +uses the +.B cuid +and +.B cap +fields of an +.B AuthInfo +structure to change the user id of the current +process and uses +.IR ns , +default +.BR /lib/namespace , +to build it a new name space. +.PP +.I Auth_challenge +and +.I auth_response +perform challenge/response protocols with +.IR factotum . +State between the challenge and response phase are +kept in the +.B Chalstate +structure: +.sp +.EX +struct Chalstate +{ + char *user; + char chal[MAXCHLEN]; + int nchal; + void *resp; + int nresp; + +/* for implementation only */ + int afd; + AuthRpc *rpc; + char userbuf[MAXNAMELEN]; + int userinchal; +}; +.EE +.sp +.I Auth_challenge +requires a key template generated by an +.B sprint +of +.I fmt +and the variable arguments. It must contain the protocol +(\fBproto=\fIxxx\fR) +and depending on the protocol, the user name ( +.BI user= xxx \fR).\fP +.B P9cr +and +.B vnc +expect the user specified as an attribute in +the key template and +.BR apop , +.BR cram , +and +.BR chap +expect it in the +.B user +field of the arg to +.IR auth_response . +For all protocols, the response is returned +to +.I auth_response +in the +.I resp +field of the +.BR Chalstate . +.I Chalstate.nresp +must be the length of the response. +.PP +Supply to +.I auth_respond +a challenge string and the fmt and args specifying a key, +and it will use +.I factotum +to return the proper user and response. +.PP +.I Auth_userpasswd +verifies a simple user/password pair. +.I Auth_getuserpasswd +retrieves a user/password pair from +.I factotum +if permitted. +.PP +.I Auth_getinfo +reads an +.B AuthInfo +message from +.I fd +and converts it into a structure. It is only +used by the other routines in this library when +communicating with +.IR factotum . +.PP +.ne 8 +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +typedef struct UserPasswd { + char *user; + char *passwd; +} UserPasswd; +.EE +.sp +.PP +.I Auth_freeAI +is used to free an +.B AuthInfo +structure returned by one of these routines. +Similary +.I auth_freechal +frees a challenge/response state. +.SH SOURCE +.B /sys/src/libauth +.SH SEE ALSO +.IR factotum (4), +.IR authsrv (2), +.IR bind (2) +.SH DIAGNOSTICS +These routines set +.IR errstr . diff --git a/man/man3/authsrv.3 b/man/man3/authsrv.3 new file mode 100644 index 00000000..65aebefb --- /dev/null +++ b/man/man3/authsrv.3 @@ -0,0 +1,223 @@ +.TH AUTHSRV 3 +.SH NAME +authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp \- routines for communicating with authentication servers +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +#include +.fi +.ta 8n +4n +4n +4n +4n +4n +4n +.PP +.B +int authdial(char *netroot, char *ad); +.PP +.B +int passtokey(char key[DESKEYLEN], char *password) +.PP +.B +uchar nvcsum(void *mem, int len) +.PP +.B +int readnvram(Nvrsafe *nv, int flag); +.PPP +.B +int convT2M(Ticket *t, char *msg, char *key) +.PP +.B +void convM2T(char *msg, Ticket *t, char *key) +.PP +.B +int convA2M(Authenticator *a, char *msg, char *key) +.PP +.B +void convM2A(char *msg, Authenticator *a, char *key) +.PP +.B +int convTR2M(Ticketreq *tr, char *msg) +.PP +.B +void convM2TR(char *msg, Ticketreq *tr) +.PP +.B +int convPR2M(Passwordreq *pr, char *msg, char *key) +.PP +.B +void convM2PR(char *msg, Passwordreq *pr, char *key) +.PP +.B +int _asgetticket(int fd, char *trbuf, char *tbuf); +.PP +.B +int _asrdresp(int fd, char *buf, int len); +.SH DESCRIPTION +.PP +.I Authdial +dials an authentication server over the +network rooted at +.IR net , +default +.BR /net . +The authentication domain, +.IR ad , +specifies which server to call. +If +.I ad +is non-nil, +the connection server +.B cs +(see +.IR ndb (8)) +is queried for an entry which contains +.B authdom=\fIad\fP +or +.BR dom=\fIad\fP , +the former having precedence, +and which also contains an +.B auth +attribute. +The string dialed is then +.I netroot\fP!\fIserver\fP!ticket +where +.I server +is the value of the +.B auth +attribute. +If no entry is found, the error string is +set to ``no authentication server found'' +and -1 is returned. +If +.I authdom +is nil, the string +.IB netroot !$auth! ticket +is used to make the call. +.PP +.I Passtokey +converts +.I password +into a DES key and stores the result in +.IR key . +It returns 0 if +.I password +could not be converted, +and 1 otherwise. +.PP +.I Readnvram +reads authentication information into the structure: +.EX +.ta 4n +4n +8n +4n +4n +4n +4n + struct Nvrsafe + { + char machkey[DESKEYLEN]; + uchar machsum; + char authkey[DESKEYLEN]; + uchar authsum; + char config[CONFIGLEN]; + uchar configsum; + char authid[ANAMELEN]; + uchar authidsum; + char authdom[DOMLEN]; + uchar authdomsum; + }; +.EE +.PP +On Sparc, MIPS, and SGI machines this information is +in non-volatile ram, accessible in the file +.BR #r/nvram . +On x86s and Alphas +.I readnvram +successively opens the following areas stopping with the +first to succeed: +.PP +\- the partition named by the +.B $nvram +environment variable +(commonly set via +.IR plan9.ini (8)) +.br +\- the partition +.B #S/sdC0/nvram +.br +\- a file called +.B plan9.nvr +in the partition +.B #S/sdC0/9fat +.br +\- the partition +.B #S/sd00/nvram +.br +\- a file called +.B plan9.nvr +in the partition +.B #S/sd00/9fat +.br +\- a file called +.B plan9.nvr +on a DOS floppy in drive 0 +.br +\- a file called +.B plan9.nvr +on a DOS floppy in drive 1 +.PP +The +.IR nvcsum s +of the fields +.BR machkey , +.BR authid , +and +.B authdom +must match their respective checksum or that field is zeroed. +If +.I flag +is +.B NVwrite +or at least one checksum fails and +.I flag +is +.BR NVwriteonerr , +.I readnvram +will prompt for new values on +.B #c/cons +and then write them back to the storage area. +.PP +.IR ConvT2M , +.IR convA2M , +.IR convTR2M , +and +.I convPR2M +convert tickets, authenticators, ticket requests, and password change request +structures into transmittable messages. +.IR ConvM2T , +.IR convM2A , +.IR convM2TR , +and +.I convM2PR +are used to convert them back. +.I Key +is used for encrypting the message before transmission and decrypting +after reception. +.PP +The routine +.I _asgetresp +receives either a character array or an error string. +On error, it sets errstr and returns -1. If successful, +it returns the number of bytes received. +.PP +The routine +.I _asgetticket +sends a ticket request message and then uses +.I _asgetresp +to recieve an answer. +.SH SOURCE +.B /sys/src/libauthsrv +.SH SEE ALSO +.IR passwd (1), +.IR cons (3), +.IR dial (2), +.IR authsrv (6), +.SH DIAGNOSTICS +These routines set +.IR errstr . +Integer-valued functions return -1 on error. diff --git a/man/man3/bin.3 b/man/man3/bin.3 new file mode 100644 index 00000000..12ca065c --- /dev/null +++ b/man/man3/bin.3 @@ -0,0 +1,99 @@ +.TH BIN 3 +.SH NAME +binalloc, bingrow, binfree \- grouped memory allocation +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid* 'u +.PP +.B +typedef struct Bin Bin; +.PP +.B +void *binalloc(Bin **bp, ulong size, int clr); +.PP +.B +void *bingrow(Bin **bp, void *op, ulong osize, +.br +.B + ulong size, int clr); +.PP +.B +void binfree(Bin **bp); +.SH DESCRIPTION +These routines provide simple grouped memory allocation and deallocation. +Items allocated with +.I binalloc +are added to the +.I Bin +pointed to by +.IR bp . +All items in a bin may be freed with one call to +.IR binfree ; +there is no way to free a single item. +.PP +.I Binalloc +returns a pointer to a new block of at least +.I size +bytes. +The block is suitably aligned for storage of any type of object. +No two active pointers from +.I binalloc +will have the same value. +The call +.B binalloc(0) +returns a valid pointer rather than null. +If +.I clr +is non-zero, the allocated memory is set to 0; +otherwise, the contents are undefined. +.PP +.I Bingrow +is used to extend the size of a block of memory returned by +.IR binalloc . +.I Bp +must point to the same bin group used to allocate the original block, +and +.I osize +must be the last size used to allocate or grow the block. +A pointer to a block of at least +.I size +bytes is returned, with the same contents in the first +.I osize +locations. +If +.I clr +is non-zero, the remaining bytes are set to 0, +and are undefined otherwise. +If +.I op +is +.BR nil , +it and +.I osize +are ignored, and the result is the same as calling +.IR binalloc . +.PP +.I Binalloc +and +.I bingrow +allocate large chunks of memory using +.IR malloc (2) +and return pieces of these chunks. +The chunks are +.IR free 'd +upon a call to +.IR binfree . +.SH SOURCE +.B /sys/src/libbin +.SH SEE ALSO +.IR malloc (2) +.SH DIAGNOSTICS +.I binalloc +and +.I bingrow +return 0 if there is no available memory. diff --git a/man/man3/bio.3 b/man/man3/bio.3 index cf504631..8be1034a 100644 --- a/man/man3/bio.3 +++ b/man/man3/bio.3 @@ -1,9 +1,12 @@ .TH BIO 3 .SH NAME -Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetd, Bungetc, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output +Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output .SH SYNOPSIS .ta \w'Biobuf* 'u -.B #include +.B #include +.br +.B #include +.br .B #include .PP .B @@ -13,64 +16,67 @@ Biobuf* Bopen(char *file, int mode) int Binit(Biobuf *bp, int fd, int mode) .PP .B -int Bterm(Biobuf *bp) +int Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size) .PP .B -int Bprint(Biobuf *bp, char *format, ...) +int Bterm(Biobufhdr *bp) .PP .B -int Bvprint(Biobuf *bp, char *format, va_list arglist); +int Bprint(Biobufhdr *bp, char *format, ...) .PP .B -void* Brdline(Biobuf *bp, int delim) +int Bvprint(Biobufhdr *bp, char *format, va_list arglist); .PP .B -char* Brdstr(Biobuf *bp, int delim, int nulldelim) +void* Brdline(Biobufhdr *bp, int delim) .PP .B -int Blinelen(Biobuf *bp) +char* Brdstr(Biobufhdr *bp, int delim, int nulldelim) .PP .B -off_t Boffset(Biobuf *bp) +int Blinelen(Biobufhdr *bp) .PP .B -int Bfildes(Biobuf *bp) +vlong Boffset(Biobufhdr *bp) .PP .B -int Bgetc(Biobuf *bp) +int Bfildes(Biobufhdr *bp) +.PP +.B +int Bgetc(Biobufhdr *bp) .PP .B long Bgetrune(Biobufhdr *bp) .PP .B -int Bgetd(Biobuf *bp, double *d) +int Bgetd(Biobufhdr *bp, double *d) .PP .B -int Bungetc(Biobuf *bp) +int Bungetc(Biobufhdr *bp) .PP .B int Bungetrune(Biobufhdr *bp) .PP .B -off_t Bseek(Biobuf *bp, off_t n, int type) +vlong Bseek(Biobufhdr *bp, vlong n, int type) .PP .B -int Bputc(Biobuf *bp, int c) +int Bputc(Biobufhdr *bp, int c) .PP .B int Bputrune(Biobufhdr *bp, long c) .PP .B -long Bread(Biobuf *bp, void *addr, long nbytes) +long Bread(Biobufhdr *bp, void *addr, long nbytes) .PP .B -long Bwrite(Biobuf *bp, void *addr, long nbytes) +long Bwrite(Biobufhdr *bp, void *addr, long nbytes) .PP .B -int Bflush(Biobuf *bp) +int Bflush(Biobufhdr *bp) .PP .B -int Bbuffered(Biobuf *bp) +int Bbuffered(Biobufhdr *bp) .PP .SH DESCRIPTION These routines implement fast buffered I/O. @@ -80,20 +86,40 @@ I/O on different file descriptors is independent. opens .I file for mode -.B O_RDONLY +.B OREAD or creates for mode -.BR O_WRONLY . +.BR OWRITE . It calls -.IR malloc (3) +.IR malloc (2) to allocate a buffer. .PP .I Binit -initializes a buffer +initializes a standard size buffer, type +.IR Biobuf , with the open file descriptor passed in by the user. +.I Binits +initializes a non-standard size buffer, type +.IR Biobufhdr , +with the open file descriptor, +buffer area, and buffer size passed in +by the user. +.I Biobuf +and +.I Biobufhdr +are related by the declaration: +.IP +.EX +typedef struct Biobuf Biobuf; +struct Biobuf +{ + Biobufhdr; + uchar b[Bungetsize+Bsize]; +}; +.EE .PP Arguments -of types pointer to Biobuf and pointer to Biobuf +of types pointer to Biobuf and pointer to Biobufhdr can be used interchangeably in the following routines. .PP .IR Bopen , @@ -133,7 +159,7 @@ of the most recent string returned by .PP .I Brdstr returns a -.IR malloc (3)-allocated +.IR malloc (2)-allocated buffer containing the next line of input delimited by .IR delim , terminated by a NUL (0) byte. @@ -152,14 +178,14 @@ the return value of will be the length of the returned buffer, excluding the NUL. .PP .I Bgetc -returns the next byte from +returns the next character from .IR bp , or a negative value at end of file. .I Bungetc may be called immediately after .I Bgetc -to allow the same byte to be reread. +to allow the same character to be reread. .PP .I Bgetrune calls @@ -183,8 +209,9 @@ may back up a maximum of five bytes. .PP .I Bgetd uses -.I fmtcharstod -(undocumented) +.I charstod +(see +.IR atof (2)) and .I Bgetc to read the formatted @@ -205,7 +232,7 @@ and a negative value is returned if a read error occurred. .PP .I Bseek applies -.IR lseek (2) +.IR seek (2) to .IR bp . It returns the new file offset. @@ -279,25 +306,13 @@ 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. -.PP -This library uses -.IR fmt (3) -for diagnostic messages about internal errors, -as well as for the implementation of -.I Bprint -and -.IR Bvprint . -It uses -.IR utf (3) -for the implementation of -.I Bgetrune -and -.IR Bputrune . +.SH SOURCE +.B /sys/src/libbio .SH SEE ALSO -.IR atexit (3). .IR open (2), -.IR print (3), -.IR utf (7) +.IR print (2), +.IR exits (2), +.IR utf (6), .SH DIAGNOSTICS .I Bio routines that return integers yield @@ -307,11 +322,9 @@ if is not the descriptor of an open file. .I Bopen returns zero if the file cannot be opened in the given mode. -.SH HISTORY -The -.IR bio (3) -library originally appeared in Plan 9. -This is a port of the Plan 9 bio library. +All routines set +.I errstr +on error. .SH BUGS .I Brdline returns an error on strings longer than the buffer associated diff --git a/man/man3/blowfish.3 b/man/man3/blowfish.3 new file mode 100644 index 00000000..8f0472dd --- /dev/null +++ b/man/man3/blowfish.3 @@ -0,0 +1,52 @@ +.TH BLOWFISH 3 +.SH NAME +setupBFstate, bfCBCencrypt, bfCBCdecrypt, bfECBencrypt, bfECBdecrypt - blowfish encryption +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void setupBFstate(BFstate *s, uchar key[], int keybytes, +.B + uchar *ivec) +.PP +.B +void bfCBCencrypt(uchar *data, int len, BFstate *s) +.PP +.B +void bfCBCdecrypt(uchar *data, int len, BFstate *s) +.PP +.B +void bfECBencrypt(uchar *data, int len, BFstate *s) +.PP +.B +void bfECBdecrypt(uchar *data, int len, BFstate *s) +.SH DESCRIPTION +.PP +Blowfish is Bruce Schneier's symmetric block cipher. It supports +variable length keys from 32 to 448 bits and has a block size of 64 +bits. Both CBC and ECB modes are supported. +.PP +setupBFstate takes a BFstate structure, a key of at most 56 bytes, the +length of the key in bytes, and an initialization vector of 8 bytes +(set to all zeroes if argument is nil). The encryption and decryption +functions take a BFstate structure, a data buffer, and a length, which +must be a multiple of eight bytes as padding is currently unsupported. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR des (2), +.IR dsa (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/man/man3/cachechars.3 b/man/man3/cachechars.3 new file mode 100644 index 00000000..8c18046d --- /dev/null +++ b/man/man3/cachechars.3 @@ -0,0 +1,313 @@ +.TH CACHECHARS 3 +.SH NAME +cachechars, agefont, loadchar, Subfont, Fontchar, Font \- font utilities +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLCacheinfo 'u +.PP +.B +int cachechars(Font *f, char **s, Rune **r, ushort *c, int max, +.PP +.B + int *widp, char **sfname) +.PP +.B +int loadchar(Font *f, Rune r, Cacheinfo *c, int h, +.PP +.B + int noclr, char **sfname) +.PP +.B +void agefont(Font *f) +.SH DESCRIPTION +A +.I Font +may contain too many characters to hold in memory +simultaneously. +The graphics library and draw device (see +.IR draw (3)) +cooperate to solve this problem by maintaining a cache of recently used +character images. +The details of this cooperation need not be known by most programs: +.I initdraw +and its associated +.I font +variable, +.IR openfont , +.IR stringwidth , +.IR string , +and +.I freefont +are sufficient for most purposes. +The routines described below are used internally by the graphics library +to maintain the font cache. +.PP +A +.B Subfont +is a set of images for a contiguous range of characters, stored as a single +image +with the characters +placed side-by-side on a common baseline. +It is described by the following data structures. +.IP +.EX +.ta 6n +\w'Fontchar 'u +\w'bottom; 'u +typedef +struct Fontchar { + int x; /* left edge of bits */ + uchar top; /* first non-zero scan-line */ + uchar bottom; /* last non-zero scan-line */ + char left; /* offset of baseline */ + uchar width; /* width of baseline */ +} Fontchar; + +typedef +struct Subfont { + char *name; + short n; /* number of chars in subfont */ + uchar height; /* height of image */ + char ascent; /* top of image to baseline */ + Fontchar *info; /* n+1 Fontchars */ + Image *bits; /* of font */ +} Subfont; +.EE +.PP +The image fills the rectangle +\fL(0, 0, \fIw\fP, height)\fR, +where +.I w +is the sum of the horizontal extents (of non-zero pixels) +for all characters. +The pixels to be displayed for character +.I c +are in the rectangle +\fL(\fIi\fP->x, \fIi\fP->top, (\fIi\fP+1)->x, \%\fIi\fP->bottom)\fR +where +.I i +is +.B +&subfont->info[\fIc\fP]\fR. +When a character is displayed at +.B Point +.B p +in an image, +the character rectangle is placed at +.BI (p.x+ i ->left, +.B p.y) +and the next character of the string is displayed at +.BI (p.x+ i ->width, +.BR p.y) . +The baseline of the characters is +.L ascent +rows down from the top of the subfont image. +The +.L info +array has +.B n+1 +elements, one each for characters 0 to +.BR n-1 +plus an additional entry so the size of the last character +can be calculated. +Thus the width, +.IR w , +of the +.B Image +associated with a +.B Subfont +.B s +is +.BR s->info[s->n].x . +.PP +A +.B Font +consists of an overall height and ascent +and a collection of subfonts together with the ranges of runes (see +.IR utf (6)) +they represent. +Fonts are described by the following structures. +.IP +.EX +.ta 6n +\w'Cacheinfo 'u +\w'height; 'u +typedef +struct Cachefont { + Rune min; /* value of 0th char in subfont */ + Rune max; /* value+1 of last char in subfont */ + int offset; /* posn in subfont of char at min */ + char *name; /* stored in font */ + char *subfontname; /* to access subfont */ +} Cachefont; + +typedef +struct Cacheinfo { + ushort x; /* left edge of bits */ + uchar width; /* width of baseline */ + schar left; /* offset of baseline */ + Rune value; /* of char at this slot in cache */ + ushort age; +} Cacheinfo; + +typedef +struct Cachesubf { + ulong age; /* for replacement */ + Cachefont *cf; /* font info that owns us */ + Subfont *f; /* attached subfont */ +} Cachesubf; + +typedef +struct Font { + char *name; + Display *display; + short height; /* max ht of image;interline space*/ + short ascent; /* top of image to baseline */ + short width; /* widest so far; used in caching */ + short nsub; /* number of subfonts */ + ulong age; /* increasing counter; for LRU */ + int ncache; /* size of cache */ + int nsubf; /* size of subfont list */ + Cacheinfo *cache; + Cachesubf *subf; + Cachefont **sub; /* as read from file */ + Image *cacheimage; +} Font; +.EE +.PP +The +.LR height +and +.LR ascent +fields of Font are described in +.IR graphics (2). +.L Sub +contains +.L nsub +pointers to +.BR Cachefonts . +A +.B Cachefont +connects runes +.L min +through +.LR max , +inclusive, to the subfont +with file name +.LR name ; +it corresponds to a line of the file describing the font. +.PP +The characters +are taken from the subfont starting at character number +.L offset +(usually zero) in the subfont, permitting selection of parts of subfonts. +Thus +the image for rune +.I r +is found in position +.IB r -min+offset +of the subfont. +.PP +For each font, the library, with support from the +graphics server, +maintains a cache of +subfonts and a cache of recently used +character images. +The +.B subf +and +.B cache +fields are used by the library to maintain these caches. +The +.L width +of a font is the maximum of the horizontal extents of the characters +in the cache. +.I String +draws a string by loading the cache and emitting a sequence of +cache indices to draw. +.I Cachechars +guarantees the images for the characters pointed to by +.I *s +or +.I *r +(one of these must be nil in each call) +are in the cache of +.IR f . +It calls +.I loadchar +to put missing characters into the cache. +.I Cachechars +translates the character string into a set of cache indices +which it loads into the array +.IR c , +up to a maximum of +.I n +indices or the length of the string. +.I Cachechars +returns in +.I c +the number of cache indices emitted, +updates +.I *s +to point to the next character to be processed, and sets +.I *widp +to the total width of the characters processed. +.I Cachechars +may return before the end of the string if it cannot +proceed without destroying active data in the caches. +If it needs to load a new subfont, it will fill +.B *sfname +with the name of the subfont it needs and return \-1. +It can return zero if it is unable to make progress because +it cannot resize the caches. +.PP +.I Loadchar +loads a character image into the character cache. +Then it tells the graphics server to copy the character +into position +.I h +in the character cache. +If the current font +.L width +is smaller than the horizontal extent of the character being loaded, +.I loadfont +clears the cache and resets it to +accept characters with the bigger width, unless +.I noclr +is set, in which case it just returns \-1. +If the character does not exist in the font at all, +.I loadfont +returns 0; if it is unable to load the character +without destroying cached information, it returns \-1, +updating +.B *sfname +as described above. +It returns 1 to indicate success. +.PP +The +.L age +fields record when +subfonts and characters have been used. +The font +.L age +is increased every time the font is used +.RI ( agefont +does this). +A character or subfont +.L age +is set to the font age at each use. +Thus, characters or subfonts with small ages are the best candidates +for replacement when the cache is full. +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR allocimage (2), +.IR draw (2), +.IR subfont (2), +.IR image (6), +.IR font (6) +.SH DIAGNOSTICS +All of the functions use the graphics error function (see +.IR graphics (2)). diff --git a/man/man3/cleanname.3 b/man/man3/cleanname.3 new file mode 100644 index 00000000..7decd18d --- /dev/null +++ b/man/man3/cleanname.3 @@ -0,0 +1,34 @@ +.TH CLEANNAME 3 +.SH NAME +cleanname \- clean a path name +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.B +char* cleanname(char *filename) +.SH DESCRIPTION +.I Cleanname +takes a +.I filename +and by lexical processing only returns the shortest string that names the same (possibly +hypothetical) file. +It eliminates multiple and trailing slashes, and it lexically interprets +.B . +and +.B .. +directory components in the name. +The string is overwritten in place. +.PP +The shortest string +.I cleanname +can return is two bytes: the null-terminated string +\f(CW"."\f1. +Therefore +.I filename +must contain room for at least two bytes. +.SH SOURCE +.B /sys/src/libc/port/cleanname.c +.SH SEE ALSO +.IR cleanname (1) diff --git a/man/man3/color.3 b/man/man3/color.3 new file mode 100644 index 00000000..91d34a62 --- /dev/null +++ b/man/man3/color.3 @@ -0,0 +1,56 @@ +.TH COLOR 3 +.SH NAME +cmap2rgb, cmap2rgba, rgb2cmap \- colors and color maps +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +int rgb2cmap(int red, int green, int blue) +.PP +.B +int cmap2rgb(int col) +.PP +.B +int cmap2rgba(int col) +.SH DESCRIPTION +These routines convert between `true color' red/green/blue triples and the Plan 9 color map. +See +.IR color (6) +for a description of RGBV, the standard color map. +.PP +.I Rgb2cmap +takes a trio of color values, scaled from 0 (no intensity) to 255 (full intensity), +and returns the index of the color in RGBV closest to that represented +by those values. +.PP +.I Cmap2rgb +decomposes the color of RGBV index +.I col +and returns a 24-bit integer with the low 8 bits representing the blue value, +the next 8 representing green, and the next 8 representing red. +.I Cmap2rgba +decomposes the color of RGBV index +.I col +and returns a 32-bit integer with the low 8 bits representing an alpha value, +defined to be 255, +and the next 8 representing blue, then green, then red, as for +.I cmap2rgba +shifted up 8 bits. +This 32-bit representation is the format used by +.IR draw (2) +and +.IR memdraw (2) +library routines that +take colors as arguments. +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR allocimage (2), +.IR draw (2), +.IR image (6), +.IR color (6) diff --git a/man/man3/complete.3 b/man/man3/complete.3 new file mode 100644 index 00000000..1f5b866d --- /dev/null +++ b/man/man3/complete.3 @@ -0,0 +1,105 @@ +.TH COMPLETE 3 +.SH NAME +complete \- file name completion +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ft L +.nf +.ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u +typedef struct Completion Completion; +struct Completion{ + uchar advance; /* whether forward progress has been made */ + uchar complete; /* whether the completion now represents a file or directory */ + char *string; /* the string to advance, suffixed " " or "/" for file or directory */ + int nmatch; /* number of files that matched */ + int nfile; /* number of files returned */ + char **filename; /* their names */ +}; + +.fi +.PP +.B +.ta \w'\fLchar* 'u + +.PP +.B +Completion* complete(char *dir, char *s); +.PP +.B +void freecompletion(Completion *c); +.SH DESCRIPTION +The +.I complete +function implements file name completion. +Given a directory +.I dir +and a string +.IR s , +it returns an analysis of the file names in that directory that begin with the string +.IR s . +The fields +.B nmatch +and +.B nfile +will be set to the number of files that match the prefix and +.B filename +will be filled in with their names. +If the file named is a directory, a slash character will be appended to it. +.PP +If no files match the string, +.B nmatch +will be zero, but +.I complete +will return the full set of files in the directory, with +.I nfile +set to their number. +.PP +The flag +.B advance +reports whether the string +.I s +can be extended without changing the set of files that match. If true, +.B string +will be set to the extension; that is, the value of +.B string +may be appended to +.I s +by the caller to extend the embryonic file name unambiguously. +.PP +The flag +.B complete +reports whether the extended file name uniquely identifies a file. +If true, +.B string +will be suffixed with a blank, or a slash and a blank, +depending on whether the resulting file name identifies a plain file or a directory. +.PP +The +.I freecompletion +function frees a +.B Completion +structure and its contents. +.PP +In +.IR rio (1) +and +.IR acme (1), +file name completion is triggered by a control-F character or an Insert character. +.SH SOURCE +.B /sys/src/libcomplete +.SH SEE ALSO +.IR rio (1), +.IR acme (1) +.SH DIAGNOSTICS +The +.I complete +function returns a null pointer and sets +.I errstr +if the directory is unreadable or there is some other error. +.SH BUGS +The behavior of file name completion should be controlled by the plumber. diff --git a/man/man3/cputime.3 b/man/man3/cputime.3 new file mode 100644 index 00000000..badea40c --- /dev/null +++ b/man/man3/cputime.3 @@ -0,0 +1,34 @@ +.TH CPUTIME 3 +.SH NAME +cputime, times \- cpu time in this process and children +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLdouble 'u +.B +int times(long t[4]) +.PP +.B +double cputime(void) +.SH DESCRIPTION +If +.I t +is non-null, +.I times +fills it in +with the number of milliseconds spent in user code, system calls, +child processes in user code, and child processes in system calls. +.I Cputime +returns the sum of those same times, converted to seconds. +.I Times +returns the elapsed real time, in milliseconds, that the process has been running. +.PP +These functions read +.BR /dev/cputime , +opening that file when they are first called. +.SH SOURCE +.B /sys/src/libc/9sys +.SH SEE ALSO +.IR cons (3) diff --git a/man/man3/ctype.3 b/man/man3/ctype.3 new file mode 100644 index 00000000..f00d040e --- /dev/null +++ b/man/man3/ctype.3 @@ -0,0 +1,160 @@ +.TH CTYPE 3 +.SH NAME +isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, isgraph, iscntrl, isascii, toascii, _toupper, _tolower, toupper, tolower \- ASCII character classification +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.if t .2C +.B isalpha(c) +.PP +.B isupper(c) +.PP +.B islower(c) +.PP +.B isdigit(c) +.PP +.B isxdigit(c) +.PP +.B isalnum(c) +.PP +.B isspace(c) +.PP +.B ispunct(c) +.PP +.B isprint(c) +.PP +.B isgraph(c) +.PP +.B iscntrl(c) +.PP +.B isascii(c) +.PP +.B _toupper(c) +.PP +.B _tolower(c) +.PP +.B toupper(c) +.PP +.B tolower(c) +.PP +.B toascii(c) +.if t .1C +.SH DESCRIPTION +These macros classify +.SM ASCII\c +-coded integer values +by table lookup. +Each is a predicate returning nonzero for true, +zero for false. +.I Isascii +is defined on all integer values; the rest +are defined only where +.I isascii +is true and on the single non-\c +.SM ASCII +value +.BR EOF ; +see +.IR fopen (2). +.TP "\w'isalnum 'u" +.I isalpha +.I c +is a letter, a\-z or A\-Z +.TP +.I isupper +.I c +is an upper case letter, A\-Z +.TP +.I islower +.I c +is a lower case letter, a\-z +.TP +.I isdigit +.I c +is a digit, 0\-9 +.TP +.I isxdigit +.I c +is a hexadecimal digit, 0\-9 or a\-f or A\-F +.TP +.I isalnum +.I c +is an alphanumeric character, a\-z or A\-Z or 0\-9 +.TP +.I isspace +.I c +is a space, horizontal tab, newline, vertical tab, formfeed, or carriage return +(0x20, 0x9, 0xA, 0xB, 0xC, 0xD) +.TP +.I ispunct +.I c +is a punctuation character +(one of +.L +!"#$%&'()*+,-./:;<=>?@[\e]^_`{|}~\fR) +.TP +.I isprint +.I c +is a printing character, 0x20 (space) +through 0x7E (tilde) +.TP +.I isgraph +.I c +is a visible printing character, 0x21 (exclamation) through 0x7E +(tilde) +.TP +.I iscntrl +.I c +is a delete character, 0x7F, +or ordinary control character, 0x0 through 0x1F +.TP +.I isascii +.I c +is an +.SM ASCII +character, 0x0 through 0x7F +.PP +.I Toascii +is not a classification macro; +it converts its argument to +.SM ASCII +range by +.IR and ing +with 0x7F. +.PP +If +.I c +is an upper case letter, +.I tolower +returns the lower case version of the character; +otherwise it returns the original character. +.I Toupper +is similar, returning the upper case version of a character +or the original character. +.I Tolower +and +.I toupper +are functions; +.I _tolower +and +.I _toupper +are corresponding macros which should only be used when it +is known that the argument is upper case or lower case, respectively. +.SH SOURCE +.TF /sys/src/libc/port/ctype.c +.TP +.B /sys/include/ctype.h +for the macros. +.TP +.B /sys/src/libc/port/ctype.c +for the tables. +.SH "SEE ALSO +.IR isalpharune (2) +.SH BUGS +These macros are +.SM ASCII \c +-centric. diff --git a/man/man3/debugger.3 b/man/man3/debugger.3 new file mode 100644 index 00000000..2bfee9c5 --- /dev/null +++ b/man/man3/debugger.3 @@ -0,0 +1,386 @@ +.TH DEBUGGER 3 +.SH NAME +cisctrace, risctrace, ciscframe, riscframe, localaddr, symoff, +fpformat, beieee80ftos, beieeesftos, beieeedftos, leieee80ftos, +leieeesftos, leieeedftos, ieeesftos, ieeedftos \- machine-independent debugger functions +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLmachines 'u +.nf +.B +int cisctrace(Map *map, ulong pc, ulong sp, ulong link, +.B + Tracer trace) +.PP +.nf +.B +int risctrace(Map *map, ulong pc, ulong sp, ulong link, +.B + Tracer trace) +.PP +.nf +.B +ulong ciscframe(Map *map, ulong addr, ulong pc, ulong sp, +.B + ulong link) +.PP +.nf +.B +ulong riscframe(Map *map, ulong addr, ulong pc, ulong sp, +.B + ulong link) +.PP +.nf +.B +int localaddr(Map *map, char *fn, char *var, long *ret, +.B + Rgetter rget) +.PP +.B +int symoff(char *buf, int n, long addr, int type) +.PP +.B +int fpformat(Map *map, Reglist *rp, char *buf, int n, int code) +.PP +.B +int beieee80ftos(char *buf, int n, void *fp) +.PP +.B +int beieeesftos(char *buf, int n, void *fp) +.PP +.B +int beieeedftos(char *buf, int n, void *fp) +.PP +.B +int leieee80ftos(char *buf, int n, void *fp) +.PP +.B +int leieeesftos(char *buf, int n, void *fp) +.PP +.B +int leieeedftos(char *buf, int n, void *fp) +.PP +.B +int ieeesftos(char *buf, int n, ulong f) +.PP +.B +int ieeedftos(char *buf, int n, ulong high, ulong low) +.PP +.B +extern Machdata *machdata; +.SH DESCRIPTION +These functions provide machine-independent implementations +of common debugger functions. +Many of the functions assume that global variables +.I mach +and +.I machdata +point to the +.I Mach +and +.I Machdata +data structures describing the target architecture. +The former contains machine parameters and a description of +the register set; it is usually +set by invoking +.I crackhdr +(see +.IR mach (2)) +to interpret the header of an executable. +The +.I Machdata +structure +is primarily a jump table specifying +functions appropriate for processing an +executable image for a given architecture. +Each application is responsible for setting +.I machdata +to the address of the +.I Machdata +structure for the target architecture. +Many of the functions described here are not +called directly; instead, they are invoked +indirectly through the +.I Machdata +jump table. +.PP +These functions must retrieve data and register contents +from an executing image. The +.I Map +(see +.IR mach (2)) +data structure +supports the consistent retrieval of data, but +no uniform access mechanism exists for registers. +The application passes the address of a register +retrieval function as an argument to those functions +requiring register values. +This function, called an +.IR Rgetter , +is of the form +.PP +.RS +.B "ulong rget(Map *map, char *name); +.RE +.PP +It returns the contents of a register when given +the address of a +.I Map +associated with an executing image and the name of the register. +.PP +.I Cisctrace +and +.I risctrace +unwind the stack for up to 40 levels or until the frame for +.I main +is found. They return the +count of the number of levels unwound. These functions +process stacks conforming to the generic compiler model for +.SM RISC +and +.SM CISC +architectures, respectively. +.I Map +is the address of a +.I Map +data structure associated with the image +of an executing process. +.IR Sp , +.I pc +and +.I link +are starting values for the stack pointer, program counter, and +link register from which the unwinding is to take place. Normally, they are +the current contents of the appropriate +registers but they can be any values defining a legitimate +process context, for example, an alternate stack in a +multi-threaded process. +.I Trace +is the address of an application-supplied function to be called +on each iteration as the frame unwinds. The prototype of this +function is: +.PP +.RS +.B "void tracer(Map *map, ulong pc, ulong fp, Symbol *s); +.RE +.PP +where +.I Map +is the +.I Map +pointer passed to +.I cisctrace +or +.I risctrace +and +.I pc +and +.I fp +are the program counter and frame pointer. +.I S +is the address of a +.I Symbol +structure, as defined in +.IR symbol (2), +containing the symbol table information for the +function owning the frame (i.e., the function that +caused the frame to be instantiated). +.PP +.I Ciscframe +and +.I riscframe +calculate the frame pointer associated with +a function. They are suitable for +programs conforming to the +.SM CISC +and +.SM RISC +stack models. +.I Map +is the address of a +.I Map +associated with the memory image of an executing +process. +.I Addr +is the entry point of the desired function. +.IR Pc , +.I sp +and +.I link +are the program counter, stack pointer and link register of +an execution context. As with the stack trace +functions, these can be the current values of the +registers or any legitimate execution context. +The value of the frame pointer is returned. A return +value of zero indicates an error. +.PP +.I Localaddr +fills the location +pointed to by +.I ret +with the address of a local variable. +.I Map +is the address of a +.I Map +associated with an executing memory image. +.I Fn +and +.I var +are pointers to the names of the function and variable of interest. +.I Rget +is the address of a register retrieval function. +If both +.I fn +and +.I var +are non-zero, the frame for function +.I fn +is calculated and the address of the automatic or +argument named +.I var +in that frame is returned. +If +.I var +is zero, the address of the +frame for function +.I fn +is returned. +In all cases, the frame for the function named +.I fn +must be instantiated somewhere on the current stack. +If there are multiple frames for the function (that is, if +it is recursive), the most recent frame is used. +The search starts from the context defined by the +current value of the program counter and stack pointer. +If a valid address is found, +.I localaddr +returns 1. A negative return indicates an error in +resolving the address. +.PP +.I Symoff +converts a virtual address to a symbolic reference. The +string containing that reference is of +the form `name+offset', where `name' is the name of the +nearest symbol with an address less than +or equal to the target address and `offset' is the hexadecimal offset +beyond that symbol. If `offset' is zero, only the name of +the symbol is printed. If no symbol is found within 4,096 +bytes of the address, the address is formatted as a hexadecimal +address. +.I Buf +is the address of a buffer of +.I n +characters to receive the formatted string. +.I Addr +is the address to be converted. +.I Type +is the type code of the search space: +.BR CTEXT , +.BR CDATA , +or +.BR CANY . +.I Symoff +returns the length of the formatted string contained in +.IR buf . +.PP +.I Fpformat +converts the contents of a floating point register to a +string. +.I Map +is the address of a +.I Map +associated with an executing process. +.I Rp +is the address of a +.I Reglist +data structure describing the desired register. +.I Buf +is the address of a buffer of +.I n +characters to hold the resulting string. +.I Code +must be either +.B F +or +.BR f, +selecting double +or single precision, respectively. If +.I code +is +.BR F , +the contents of the specified register and +the following register +are interpreted as a double precision floating point +number; this +is only meaningful for architectures that implement +double precision floats by combining adjacent +single precision registers. +For +.I code +.BR f , +the specified register is formatted +as a single precision float. +.I Fpformat +returns 1 if the number is successfully converted or \-1 +in the case of an error. +.PP +.IR Beieee80ftos , +.I beieeesftos +and +.I beieeedftos +convert big-endian 80-bit extended, 32-bit single precision, +and 64-bit double precision floating point values to +a string. +.IR Leieee80ftos , +.IR leieeesftos , +and +.I leieeedftos +are the little-endian counterparts. +.I Buf +is the address of a buffer of +.I n +characters to receive the formatted string. +.I Fp +is the address of the floating point value to be +converted. These functions return the length of +the resulting string. +.PP +.I Ieeesftos +converts the 32-bit single precision floating point value +.IR f , +to a string in +.IR buf , +a buffer of +.I n +bytes. It returns the length of the resulting string. +.PP +.I Ieeedftos +converts a 64-bit double precision floating point value +to a character string. +.I Buf +is the address of a buffer of +.I n +characters to hold the resulting string. +.I High +and +.I low +contain the most and least significant 32 bits of +the floating point value, respectively. +.I Ieeedftos +returns the number of characters in the resulting string. +.SH SOURCE +.B /sys/src/libmach +.SH "SEE ALSO" +.IR mach (2), +.IR symbol (2), +.IR errstr (2) +.SH DIAGNOSTICS +Set +.IR errstr . diff --git a/man/man3/des.3 b/man/man3/des.3 new file mode 100644 index 00000000..c99fd578 --- /dev/null +++ b/man/man3/des.3 @@ -0,0 +1,144 @@ +.TH DES 3 +.SH NAME +setupDESstate, des_key_setup, block_cipher, desCBCencrypt, desCBCdecrypt, desECBencrypt, desECBdecrypt, des3CBCencrypt, des3CBCdecrypt, des3ECBencrypt, des3ECBdecrypt, key_setup, des56to64, des64to56, setupDES3state, triple_block_cipher, - single and triple digital encryption standard +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void des_key_setup(uchar key[8], ulong schedule[32]) +.PP +.B +void block_cipher(ulong *schedule, uchar *data, +.B + int decrypting) +.PP +.B +void setupDESstate(DESstate *s, uchar key[8], uchar *ivec) +.PP +.B +void desCBCencrypt(uchar*, int, DESstate*) +.PP +.B +void desCBCdecrypt(uchar*, int, DESstate*) +.PP +.B +void desECBencrypt(uchar*, int, DESstate*) +.PP +.B +void desECBdecrypt(uchar*, int, DESstate*) +.PP +.B +void triple_block_cipher(ulong keys[3][32], uchar*, int) +.PP +.B +void setupDES3state(DES3state *s, uchar key[3][8], +.B + uchar *ivec) +.PP +.B +void des3CBCencrypt(uchar*, int, DES3state*) +.PP +.B +void des3CBCdecrypt(uchar*, int, DES3state*) +.PP +.B +void des3ECBencrypt(uchar*, int, DES3state*) +.PP +.B +void des3ECBdecrypt(uchar*, int, DES3state*) +.PP +.B +void key_setup(uchar[7], ulong[32]) +.PP +.B +void des56to64(uchar *k56, uchar *k64) +.PP +.B +void des64to56(uchar *k64, uchar *k56) +.SH DESCRIPTION +.PP +The Digital Encryption Standard (DES) +is a shared key or symmetric encryption using either +a 56 bit key for single DES or three 56 bit keys for triple des. +The keys are encoded into 64 bits where every eight bit +is parity. +.PP +The basic DES function, +.IR block_cipher , +works on a block of 8 bytes, converting them in place. +It takes a key schedule, a pointer to the block, and +a flag indicating encrypting (0) or decrypting (1). +The key schedule is created from the key using +.IR des_key_setup . +.PP +Since it is a bit awkward, +.I block_cipher +is rarely called directly. Instead, one normally uses +routines that encrypt larger buffers of data and +which may chain the encryption state from one buffer +to the next. +These routines keep track of the state of the +encryption using a +.B DESstate +structure that contains the key schedule and any chained +state. +.I SetupDESstate +sets up the +.B DESstate +structure using the key and an 8 byte initialization vector. +.PP +Electronic code book, using +.I desECBencrypt +and +.IR desECBdecrypt , +is the less secure mode. The encryption of each 8 bytes +does not depend on the encryption of any other. +Hence the encryption is a substitution +cipher using 64 bit characters. +.PP +Cipher block chaining mode, using +.I desCBCencrypt +and +.IR desCBCdecrypt , +is more secure. Every block encrypted depends on the initialization +vector and all blocks encrypted before it. +.PP +For both CBC and ECB modes, a stream of data can be encrypted as +multiple buffers. However, all buffers except the last must +be a multiple of 8 bytes to ensure successful decryption of +the stream. +.PP +There are equivalent triple DES functions for each of the +DES functions. +.PP +In the past Plan 9 used a 56 bit or 7 byte +format for DES keys. To be compatible with the rest +of the world, we've abandoned this format. +There are two functions: +.I des56to64 +and +.I des64to56 +to convert back and forth between the two formats. +Also a key schedule can be set up from the 7 byte format +using +.IR key_setup . +.PP +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR dsa (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/man/man3/dial.3 b/man/man3/dial.3 new file mode 100644 index 00000000..fe1837c9 --- /dev/null +++ b/man/man3/dial.3 @@ -0,0 +1,331 @@ +.TH DIAL 3 +.SH NAME +dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- make and break network connections +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int dial(char *addr, char *local, char *dir, int *cfdp) +.PP +.B +int hangup(int ctl) +.PP +.B +int announce(char *addr, char *dir) +.PP +.B +int listen(char *dir, char *newdir) +.PP +.B +int accept(int ctl, char *dir) +.PP +.B +int reject(int ctl, char *dir, char *cause) +.PP +.B +char* netmkaddr(char *addr, char *defnet, char *defservice) +.PP +.B +void setnetmtpt(char *to, int tolen, char *from) +.PP +.B +NetConnInfo* getnetconninfo(char *conndir, int fd) +.PP +.B +void freenetconninfo(NetConnINfo*) +.SH DESCRIPTION +For these routines, +.I addr +is a network address of the form +.IB network ! netaddr ! service\f1, +.IB network ! netaddr\f1, +or simply +.IR netaddr . +.I Network +is any directory listed in +.B /net +or the special token, +.BR net . +.B Net +is a free variable that stands for any network in common +between the source and the host +.IR netaddr . +.I Netaddr +can be a host name, a domain name, a network address, +or a meta-name of the form +.BI $ attribute\f1, +which +is replaced by +.I value +from the value-attribute pair +.IB attribute = value +most closely associated with the source host in the +network data base (see +.IR ndb (6)). +.PP +If a connection attempt is successful and +.I dir +is non-zero, +the path name of a +.I line directory +that has files for accessing the connection +is copied into +.IR dir . +The path name is guaranteed to be less than 40 +bytes long. +One line directory exists for each possible connection. +The +.B data +file in the line directory should be used to communicate with the destination. +The +.B ctl +file in the line directory can be used to send commands to the line. +See +.IR ip (3) +for messages that can be written to the +.B ctl +file. +The last close of the +.B data +or +.B ctl +file will close the connection. +.PP +.I Dial +makes a call to destination +.I addr +on a multiplexed network. +If the network in +.I addr +is +.BR net , +.I dial +will try in succession all +networks in common between source and destination +until a call succeeds. +It returns a file descriptor open for reading and writing the +.B data +file in the line directory. +The +.B addr +file in the line directory contains the address called. +If the network allows the local address to be set, +as is the case with UDP and TCP port numbers, and +.IR local +is non-zero, the local address will be set to +.IR local . +If +.I cfdp +is non-zero, +.BI * cfdp +is set to a file descriptor open for reading and +writing the control file. +.PP +.I Hangup +is a means of forcing a connection to hang up without +closing the +.B ctl +and +.B data +files. +.P +.I Announce +and +.I listen +are the complements of +.IR dial . +.I Announce +establishes a network +name to which calls can be made. +Like +.IR dial , +.I announce +returns an open +.B ctl +file. +The +.I netaddr +used in announce may be a local address or an asterisk, +to indicate all local addresses, e.g. +.BR tcp!*!echo . +The +.I listen +routine takes as its first argument the +.I dir +of a previous +.IR announce . +When a call is received, +.I listen +returns an open +.B ctl +file for the line the call was received on. +It sets +.I newdir +to the path name of the new line directory. +.I Accept +accepts a call received by +.IR listen , +while +.I reject +refuses the call because of +.IR cause . +.I Accept +returns a file descriptor for the data file opened +.BR ORDWR . +.PP +.I Netmkaddr +makes an address suitable for dialing or announcing. +It takes an address along with a default network and service to use +if they are not specified in the address. +It returns a pointer to static data holding the actual address to use. +.PP +.I Getnetconninfo +returns a structure containing information about a +network connection. The structure is: +.EX + typedef struct NetConnInfo NetConnInfo; + struct NetConnInfo + { + char *dir; /* connection directory */ + char *root; /* network root */ + char *spec; /* binding spec */ + char *lsys; /* local system */ + char *lserv; /* local service */ + char *rsys; /* remote system */ + char *rserv; /* remote service */ + }; +.EE +.PP +The information is obtained from the connection directory, +.IR conndir . +If +.I conndir +is nil, the directory is obtained by performing +.IR fd2path (2) +on +.IR fd . +.I Getnetconninfo +returns either a completely specified structure, or +nil if either the structure can't be allocated or the +network directory can't be determined. +The structure +is freed using +.IR freenetconninfo . +.PP +.I Setnetmtpt +copies the name of the network mount point into +the buffer +.IR to , +whose length is +.IR tolen . +It exists to merge two pre-existing conventions for specifying +the mount point. +Commands that take a network mount point as a parameter +(such as +.BR dns , +.BR cs +(see +.IR ndb (8)), +and +.IR ipconfig (8)) +should now call +.IR setnetmtpt . +If +.I from +is +.BR nil , +the mount point is set to the default, +.BR /net . +If +.I from +points to a string starting with a slash, +the mount point is that path. +Otherwise, the mount point is the string pointed to by +.I from +appended to the string +.BR /net . +The last form is obsolete and is should be avoided. +It exists only to aid in conversion. +.SH EXAMPLES +Make a call and return an open file descriptor to +use for communications: +.IP +.EX +int callkremvax(void) +{ + return dial("kremvax", 0, 0, 0); +} +.EE +.PP +Call the local authentication server: +.IP +.EX +int dialauth(char *service) +{ + return dial(netmkaddr("$auth", 0, service), 0, 0, 0); +} +.EE +.PP +Announce as +.B kremvax +on TCP/IP and +loop forever receiving calls and echoing back +to the caller anything sent: +.IP +.EX +int +bekremvax(void) +{ + int dfd, acfd, lcfd; + char adir[40], ldir[40]; + int n; + char buf[256]; + + acfd = announce("tcp!*!7", adir); + if(acfd < 0) + return -1; + for(;;){ + /* listen for a call */ + lcfd = listen(adir, ldir); + if(lcfd < 0) + return -1; + /* fork a process to echo */ + switch(fork()){ + case -1: + perror("forking"); + close(lcfd); + break; + case 0: + /* accept the call and open the data file */ + dfd = accept(lcfd, ldir); + if(dfd < 0) + return -1; + + /* echo until EOF */ + while((n = read(dfd, buf, sizeof(buf))) > 0) + write(dfd, buf, n); + exits(0); + default: + close(lcfd); + break; + } + } +} +.EE +.SH SOURCE +.BR /sys/src/libc/9sys , +.B /sys/src/libc/port +.SH "SEE ALSO" +.IR auth (2), +.IR ip (3), +.IR ndb (8) +.SH DIAGNOSTICS +.IR Dial , +.IR announce , +and +.I listen +return \-1 if they fail. +.I Hangup +returns nonzero if it fails. diff --git a/man/man3/dirread.3 b/man/man3/dirread.3 new file mode 100644 index 00000000..a7bd2ede --- /dev/null +++ b/man/man3/dirread.3 @@ -0,0 +1,103 @@ +.TH DIRREAD 3 +.SH NAME +dirread, dirreadall \- read directory +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +long dirread(int fd, Dir **buf) +.PP +.B +long dirreadall(int fd, Dir **buf) +.PP +.B +#define STATMAX 65535U +.PP +.B +#define DIRMAX (sizeof(Dir)+STATMAX) +.SH DESCRIPTION +The data returned by a +.IR read (2) +on a directory is a set of complete directory entries +in a machine-independent format, exactly equivalent to +the result of a +.IR stat (2) +on each file or subdirectory in the directory. +.I Dirread +decodes the directory entries into a machine-dependent form. +It reads from +.IR fd +and unpacks the data into an array of +.B Dir +structures +whose address is returned in +.B *buf +(see +.IR stat (2) +for the layout of a +.BR Dir ). +The array is allocated with +.IR malloc (2) +each time +.I dirread +is called. +.PP +.I Dirreadall +is like +.IR dirread , +but reads in the entire directory; by contrast, +.I dirread +steps through a directory one +.IR read (2) +at a time. +.PP +Directory entries have variable length. +A successful +.I read +of a directory always returns an integral number of complete directory entries; +.I dirread +always returns complete +.B Dir +structures. +See +.IR read (5) +for more information. +.PP +The constant +.B STATMAX +is the maximum size that a directory entry can occupy. +The constant +.B DIRMAX +is an upper limit on the size necessary to hold a +.B Dir +structure and all the associated data. +.PP +.I Dirread +and +.I dirreadall +return the number of +.B Dir +structures filled in +.BR buf . +The file offset is advanced by the number of bytes actually read. +.SH SOURCE +.B /sys/src/libc/9sys/dirread.c +.SH SEE ALSO +.IR intro (2), +.IR open (2), +.IR read (2) +.SH DIAGNOSTICS +.I Dirread +and +.I Dirreadall +return zero for end of file and a negative value for error. +In either case, +.B *buf +is set to +.B nil +so the pointer can always be freed with impunity. +.PP +These functions set +.IR errstr . diff --git a/man/man3/draw.3 b/man/man3/draw.3 new file mode 100644 index 00000000..3cf27ec0 --- /dev/null +++ b/man/man3/draw.3 @@ -0,0 +1,821 @@ +.TH DRAW 3 +.SH NAME +Image, draw, gendraw, drawreplxy, drawrepl, +replclipr, line, poly, fillpoly, bezier, bezspline, fillbezier, fillbezspline, ellipse, +fillellipse, arc, fillarc, icossin, icossin2, border, string, stringn, +runestring, runestringn, stringbg, stringnbg, runestringbg, +runestringnbg, _string, ARROW, drawsetdebug \- graphics functions +.de PB +.PP +.ft L +.nf +.. +.SH SYNOPSIS +.de PB +.PP +.ft L +.nf +.. +.PB +#include +#include +#include +.PB +typedef +struct Image +{ + Display *display; /* display holding data */ + int id; /* id of system-held Image */ + Rectangle r; /* rectangle in data area, local coords */ + Rectangle clipr; /* clipping region */ + ulong chan; /* pixel channel format descriptor */ + int depth; /* number of bits per pixel */ + int repl; /* flag: data replicates to tile clipr */ + Screen *screen; /* 0 if not a window */ + Image *next; /* next in list of windows */ +} Image; +.PB +typedef enum +{ + /* Porter-Duff compositing operators */ + Clear = 0, +.sp 0.1 + SinD = 8, + DinS = 4, + SoutD = 2, + DoutS = 1, +.sp 0.1 + S = SinD|SoutD, + SoverD = SinD|SoutD|DoutS, + SatopD = SinD|DoutS, + SxorD = SoutD|DoutS, +.sp 0.1 + D = DinS|DoutS, + DoverS = DinS|DoutS|SoutD, + DatopS = DinS|SoutD, + DxorS = DoutS|SoutD, /* == SxorD */ +.sp 0.1 + Ncomp = 12, +} Drawop; +.PB +.PD 0 +.ta +\w'\fL 'u +\w'\fL 'u +6n +4n +void draw(Image *dst, Rectangle r, Image *src, + Image *mask, Point p) +.PB +void drawop(Image *dst, Rectangle r, Image *src, + Image *mask, Point p, Drawop op) +.PB +void gendraw(Image *dst, Rectangle r, Image *src, Point sp, + Image *mask, Point mp) +.PB +void gendrawop(Image *dst, Rectangle r, Image *src, Point sp, + Image *mask, Point mp, Drawop op) +.PB +int drawreplxy(int min, int max, int x) +.PB +Point drawrepl(Rectangle r, Point p) +.PB +void replclipr(Image *i, int repl, Rectangle clipr) +.PB +void line(Image *dst, Point p0, Point p1, int end0, int end1, + int radius, Image *src, Point sp) +.PB +void lineop(Image *dst, Point p0, Point p1, int end0, int end1, + int radius, Image *src, Point sp, Drawop op) +.PB +void poly(Image *dst, Point *p, int np, int end0, int end1, + int radius, Image *src, Point sp) +.PB +void polyop(Image *dst, Point *p, int np, int end0, int end1, + int radius, Image *src, Point sp, Drawop op) +.PB +void fillpoly(Image *dst, Point *p, int np, int wind, + Image *src, Point sp) +.PB +void fillpolyop(Image *dst, Point *p, int np, int wind, + Image *src, Point sp, Drawop op) +.PB +int bezier(Image *dst, Point p0, Point p1, Point p2, Point p3, + int end0, int end1, int radius, Image *src, Point sp) +.PB +int bezierop(Image *dst, Point p0, Point p1, Point p2, Point p3, + int end0, int end1, int radius, Image *src, Point sp, + Drawop op) +.PB +int bezspline(Image *dst, Point *pt, int npt, int end0, int end1, + int radius, Image *src, Point sp) +.PB +int bezsplineop(Image *dst, Point *pt, int npt, int end0, int end1, + int radius, Image *src, Point sp, Drawop op) +.PB +int bezsplinepts(Point *pt, int npt, Point **pp) +.PB +int fillbezier(Image *dst, Point p0, Point p1, Point p2, Point p3, + int w, Image *src, Point sp) +.PB +int fillbezierop(Image *dst, Point p0, Point p1, Point p2, Point p3, + int w, Image *src, Point sp, Drawop op) +.PB +int fillbezspline(Image *dst, Point *pt, int npt, int w, + Image *src, Point sp) +.PB +int fillbezsplineop(Image *dst, Point *pt, int npt, int w, + Image *src, Point sp, Drawop op) +.PB +void ellipse(Image *dst, Point c, int a, int b, int thick, + Image *src, Point sp) +.PB +void ellipseop(Image *dst, Point c, int a, int b, int thick, + Image *src, Point sp, Drawop op) +.PB +void fillellipse(Image *dst, Point c, int a, int b, + Image *src, Point sp) +.PB +void fillellipseop(Image *dst, Point c, int a, int b, + Image *src, Point sp, Drawop op) +.PB +void arc(Image *dst, Point c, int a, int b, int thick, + Image *src, Point sp, int alpha, int phi) +.PB +void arcop(Image *dst, Point c, int a, int b, int thick, + Image *src, Point sp, int alpha, int phi, Drawop op) +.PB +void fillarc(Image *dst, Point c, int a, int b, Image *src, + Point sp, int alpha, int phi) +.PB +void fillarcop(Image *dst, Point c, int a, int b, Image *src, + Point sp, int alpha, int phi, Drawop op) +.PB +int icossin(int deg, int *cosp, int *sinp) +.PB +int icossin2(int x, int y, int *cosp, int *sinp) +.PB +void border(Image *dst, Rectangle r, int i, Image *color, Point sp) +.br +.PB +Point string(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s) +.PB +Point stringop(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, Drawop op) +.PB +Point stringn(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, int len) +.PB +Point stringnop(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, int len, Drawop op) +.PB +Point runestring(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r) +.PB +Point runestringop(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, Drawop op) +.PB +Point runestringn(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, int len) +.PB +Point runestringnop(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, int len, Drawop op) +.PB +Point stringbg(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, Image *bg, Point bgp) +.PB +Point stringbgop(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, Image *bg, Point bgp, Drawop op) +.PB +Point stringnbg(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, int len, Image *bg, Point bgp) +.PB +Point stringnbgop(Image *dst, Point p, Image *src, Point sp, + Font *f, char *s, int len, Image *bg, Point bgp, Drawop op) +.PB +Point runestringbg(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, Image *bg, Point bgp) +.PB +Point runestringbgop(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, Image *bg, Point bgp, Drawop op) +.PB +Point runestringnbg(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, int len, Image *bg, Point bgp) +.PB +Point runestringnbgop(Image *dst, Point p, Image *src, Point sp, + Font *f, Rune *r, int len, Image *bg, Point bgp, Drawop op) +.PB +Point _string(Image *dst, Point p, Image *src, + Point sp, Font *f, char *s, Rune *r, int len, + Rectangle clipr, Image *bg, Point bgp, Drawop op) +.PB +void drawsetdebug(int on) +.PD +.PB +enum +{ + /* line ends */ + Endsquare = 0, + Enddisc = 1, + Endarrow = 2, + Endmask = 0x1F +}; +.PB +#define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23)) +.SH DESCRIPTION +The +.B Image +type defines rectangular pictures and the methods to draw upon them; +it is also the building block for higher level objects such as +windows and fonts. +In particular, a window is represented as an +.BR Image ; +no special operators are needed to draw on a window. +.PP +.TP 10 +.B r +The coordinates of the rectangle in the plane for which the +.B Image +has defined pixel values. +It should not be modified after the image is created. +.TP +.B clipr +The clipping rectangle: operations that read or write +the image will not access pixels outside +.BR clipr . +Frequently, +.B clipr +is the same as +.BR r , +but it may differ; see in particular the discussion of +.BR repl . +The clipping region may be modified dynamically using +.I replclipr +.RI ( q.v. ). +.TP +.B chan +The pixel channel format descriptor, as described in +.IR image (6). +The value should not be modified after the image is created. +.TP +.B depth +The +number of bits per pixel in the picture; +it is identically +.B chantodepth(chan) +(see +.IR graphics (2)) +and is provided as a convenience. +The value should not be modified after the image is created. +.TP +.B repl +A boolean value specifying whether the image is tiled to cover +the plane when used as a source for a drawing operation. +If +.B repl +is zero, operations are restricted to the intersection of +.B r +and +.BR clipr . +If +.B repl +is set, +.B r +defines the tile to be replicated and +.B clipr +defines the portion of the plane covered by the tiling, in other words, +.B r +is replicated to cover +.BR clipr ; +in such cases +.B r +and +.B clipr +are independent. +.IP +For example, a replicated image with +.B r +set to ((0,\ 0),\ (1,\ 1)) and +.B clipr +set to ((0,\ 0),\ (100,\ 100)), +with the single pixel of +.B r +set to blue, +behaves identically to an image with +.B r +and +.B clipr +both set to ((0,\ 0),\ (100,\ 100)) and all pixels set to blue. +However, +the first image requires far less memory. +The replication flag may be modified dynamically using +.I replclipr +.RI ( q.v. ). +.PP +Most of the drawing functions come in two forms: +a basic form, and an extended form that takes an extra +.B Drawop +to specify a Porter-Duff compositing operator to use. +The basic forms assume the operator is +.BR SoverD , +which suffices for the vast majority of applications. +The extended forms are named by adding an +.RB - op +suffix to the basic form. +Only the basic forms are listed below. +.TP +.BI draw( dst\fP,\fP\ r\fP,\fP\ src\fP,\fP\ mask\fP,\fP\ p ) +.I Draw +is the standard drawing function. +Only those pixels within the intersection of +.IB dst ->r +and +.IB dst ->clipr +will be affected; +.I draw +ignores +.IB dst ->repl\fR. +The operation proceeds as follows +(this is a description of the behavior, not the implementation): +.RS +.IP 1. +If +.B repl +is set in +.I src +or +.IR mask , +replicate their contents to fill +their clip rectangles. +.IP 2. +Translate +.I src +and +.I mask +so +.I p +is aligned with +.IB r .min\fR. +.IP 3. +Set +.I r +to the intersection of +.I r +and +.IB dst ->r\fR. +.IP 4. +Intersect +.I r +with +.IB src ->clipr\fR. +If +.IB src ->repl +is false, also intersect +.I r +with +.IB src ->r\fR. +.IP 5. +Intersect +.I r +with +.IB mask ->clipr\fR. +If +.IB mask ->repl +is false, also intersect +.I r +with +.IB mask ->r\fR. +.IP 6. +For each location in +.IR r , +combine the +.I dst +pixel with the +.I src +pixel using the alpha value +corresponding to the +.I mask +pixel. +If the +.I mask +has an explicit alpha channel, the alpha value +corresponding to the +.I mask +pixel is simply that pixel's alpha channel. +Otherwise, the alpha value is the NTSC greyscale equivalent +of the color value, with white meaning opaque and black transparent. +In terms of the Porter-Duff compositing algebra, +.I draw +replaces the +.I dst +pixels with +.RI ( src +in +.IR mask ) +over +.IR dst . +(In the extended form, +``over'' is replaced by +.IR op ). +.RE +.IP +The various +pixel channel formats +involved need not be identical. +If the channels involved are smaller than 8-bits, they will +be promoted before the calculation by replicating the extant bits; +after the calculation, they will be truncated to their proper sizes. +.TP +\f5gendraw(\f2dst\fP, \f2r\fP, \f2src\fP, \f2p0\fP, \f2mask\fP, \f2p1\f5)\fP +Similar to +.I draw +except that +.I gendraw +aligns the source and mask differently: +.I src +is aligned so +.I p0 +corresponds to +.IB r .min +and +.I mask +is aligned so +.I p1 +corresponds to +.IB r .min . +For most purposes with simple masks and source images, +.B draw +is sufficient, but +.B gendraw +is the general operator and the one all other drawing primitives are built upon. +.TP +.BI drawreplxy( min , max , x\f5) +Clips +.I x +to be in the half-open interval [\fImin\fP, \fImax\fP) by adding +or subtracting a multiple of \fImax-min\fP. +.TP +.BI drawrepl( r , p ) +Clips the point \fIp\fP to be within the rectangle \fIr\fP +by translating the point horizontally by an integer multiple of rectangle width +and vertically by the height. +.TP +.BI replclipr( i , repl , clipr\f5) +Because the image data is stored on the server, local modifications to the +.B Image +data structure itself will have no effect. +.I Repclipr +modifies the local +.B Image +data structure's +.B repl +and +.B clipr +fields, and notifies the server of their modification. +.TP +\f5line(\f2dst\fP, \f2p0\fP, \f2p1\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +Line +draws in +.I dst +a line of width +.RI 1+2* thick +pixels joining points +.I p0 +and +.IR p1 . +The line is drawn using pixels from the +.I src +image aligned so +.I sp +in the source corresponds to +.I p0 +in the destination. +The line touches both +.I p0 +and +.IR p1 , +and +.I end0 +and +.I end1 +specify how the ends of the line are drawn. +.B Endsquare +terminates the line perpendicularly to the direction of the line; a thick line with +.B Endsquare +on both ends will be a rectangle. +.B Enddisc +terminates the line by drawing a disc of diameter +.RI 1+2* thick +centered on the end point. +.B Endarrow +terminates the line with an arrowhead whose tip touches the endpoint. +.IP +The macro +.B ARROW +permits explicit control of the shape of the arrow. +If all three parameters are zero, it produces the default arrowhead, +otherwise, +.I a +sets the distance along line from end of the regular line to tip, +.I b +sets the distance along line from the barb to the tip, +and +.I c +sets the distance perpendicular to the line from edge of line to the tip of the barb, +all in pixels. +.IP +.I Line +and the other geometrical operators are equivalent to calls to +.I gendraw +using a mask produced by the geometric procedure. +.TP +\f5poly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.I Poly +draws a general polygon; it +is conceptually equivalent to a series of calls to +.I line +joining adjacent points in the +array of +.B Points +.IR p , +which has +.I np +elements. +The ends of the polygon are specified as in +.IR line ; +interior lines are terminated with +.B Enddisc +to make smooth joins. +The source is aligned so +.I sp +corresponds to +.IB p [0]\f1. +.TP +\f5fillpoly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2wind\fP, \f2src\fP, \f2sp\fP) +.I Fillpoly +is like +.I poly +but fills in the resulting polygon rather than outlining it. +The source is aligned so +.I sp +corresponds to +.IB p [0]\f1. +The winding rule parameter +.I wind +resolves ambiguities about what to fill if the polygon is self-intersecting. +If +.I wind +is +.BR ~0 , +a pixel is inside the polygon if the polygon's winding number about the point +is non-zero. +If +.I wind +is +.BR 1 , +a pixel is inside if the winding number is odd. +Complementary values (0 or ~1) cause outside pixels to be filled. +The meaning of other values is undefined. +The polygon is closed with a line if necessary. +.TP +\f5bezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.I Bezier +draws the +cubic Bezier curve defined by +.B Points +.IR a , +.IR b , +.IR c , +and +.IR d . +The end styles are determined by +.I end0 +and +.IR end1 ; +the thickness of the curve is +.RI 1+2* thick . +The source is aligned so +.I sp +in +.I src +corresponds to +.I a +in +.IR dst . +.TP +\f5bezspline(\f2dst\fP, \f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.I Bezspline +takes the same arguments as +.I poly +but draws a quadratic B-spline (despite its name) rather than a polygon. +If the first and last points in +.I p +are equal, the spline has periodic end conditions. +.TP +\f5bezsplinepts(\f2pt\fP, \f2npt\fP, \f2pp\fP) +.I Bezsplinepts +returns in +.I pp +a list of points making up the open polygon that +.I bezspline +would draw. +The caller is responsible for freeing +.IR *pp . +.TP +\f5fillbezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2wind\fP, \f2src\fP, \f2sp\fP) +.I Fillbezier +is to +.I bezier +as +.I fillpoly +is to +.IR poly . +.TP +\f5fillbezspline(\f2dst\fP, \f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP) +.I Fillbezspline +is like +.I fillpoly +but fills the quadratic B-spline rather than the polygon outlined by +.IR p . +The spline is closed with a line if necessary. +.TP +\f5ellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.I Ellipse +draws in +.I dst +an ellipse centered on +.I c +with horizontal and vertical semiaxes +.I a +and +.IR b . +The source is aligned so +.I sp +in +.I src +corresponds to +.I c +in +.IR dst . +The ellipse is drawn with thickness +.RI 1+2* thick . +.TP +\f5fillellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP) +.I Fillellipse +is like +.I ellipse +but fills the ellipse rather than outlining it. +.TP +\f5arc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP) +.I Arc +is like +.IR ellipse , +but draws only that portion of the ellipse starting at angle +.I alpha +and extending through an angle of +.IR phi . +The angles are measured in degrees counterclockwise from the positive +.I x +axis. +.TP +\f5fillarc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP) +.I Fillarc +is like +.IR arc , +but fills the sector with the source color. +.TP +\f5icossin(\f2deg\fP, \f2cosp\fP, \f2sinp\fP) +.I Icossin +stores in +.BI * cosp +and +.BI * sinp +scaled integers representing the cosine and sine of the angle +.IR deg , +measured in integer degrees. +The values are scaled so cos(0) is 1024. +.TP +\f5icossin2(\f2x\fP, \f2y\fP, \f2cosp\fP, \f2sinp\fP) +.I Icossin2 +is analogous to +.IR icossin, +with the angle represented not in degrees but implicitly by the point +.RI ( x , y ). +It is to +.I icossin +what +.B atan2 +is to +.B atan +(see +.IR sin (2)). +.TP +.BI border( dst\fP,\fP\ r\fP,\fP\ i\fP,\fP\ color\fP,\fP\ sp\fP) +.I Border +draws an outline of rectangle +.I r +in the specified +.IR color . +The outline has width +.IR i ; +if positive, the border goes inside the rectangle; negative, outside. +The source is aligned so +.I sp +corresponds to +.IB r .min . +.TP +.BI string( dst\fP,\fP\ p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ s ) +.I String +draws in +.I dst +characters specified by the string +.I s +and +.IR font ; +it is equivalent to a series of calls to +.I gendraw +using source +.I src +and masks determined by the character shapes. +The text is positioned with the left of the first character at +.IB p .x +and the top of the line of text at +.IB p .y\f1. +The source is positioned so +.I sp +in +.I src +corresponds to +.I p +in +.IR dst . +.I String +returns a +.B Point +that is the position of the next character that would be drawn if the string were longer. +.IP +For characters with undefined +or zero-width images in the font, the character at font position 0 (NUL) is drawn. +.IP +The other string routines are variants of this basic form, and +have names that encode their variant behavior. +Routines whose names contain +.B rune +accept a string of Runes rather than +.SM UTF\c +-encoded bytes. +Routines ending in +.B n +accept an argument, +.IR n , +that defines the number of characters to draw rather than accepting a NUL-terminated +string. +Routines containing +.B bg +draw the background behind the characters in the specified color +.RI ( bg ) +and +alignment +.RI ( bgp ); +normally the text is drawn leaving the background intact. +.IP +The routine +.I _string +captures all this behavior into a single operator. Whether it draws a +.SM UTF +string +or Rune string depends on whether +.I s +or +.I r +is null (the string length is always determined by +.IR len ). +If +.I bg +is non-null, it is used as a background color. +The +.I clipr +argument allows further management of clipping when drawing the string; +it is intersected with the usual clipping rectangles to further limit the extent of the text. +.TP +.BI drawsetdebug( on ) +Turns on or off debugging output (usually +to a serial line) according to whether +.I on +is non-zero. +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR stringsize (2), +.IR color (6), +.IR utf (6), +.IR addpt (2) +.PP +T. Porter, T. Duff. +``Compositing Digital Images'', +.I "Computer Graphics +(Proc. SIGGRAPH), 18:3, pp. 253-259, 1984. +.SH DIAGNOSTICS +These routines call the graphics error function on fatal errors. +.SH BUGS +Anti-aliased characters can be drawn by defining a font +with multiple bits per pixel, but there are +no anti-aliasing geometric primitives. diff --git a/man/man3/dsa.3 b/man/man3/dsa.3 new file mode 100644 index 00000000..5535164e --- /dev/null +++ b/man/man3/dsa.3 @@ -0,0 +1,132 @@ +.TH DSA 3 +.SH NAME +dsagen, dsasign, dsaverify, dsapuballoc, dsapubfree, dsaprivalloc, dsaprivfree, dsasigalloc, dsasigfree, dsaprivtopub - digital signature algorithm +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +DSApriv* dsagen(DSApub *opub) +.PP +.B +DSAsig* dsasign(DSApriv *k, mpint *m) +.PP +.B +int dsaverify(DSApub *k, DSAsig *sig, mpint *m) +.PP +.B +DSApub* dsapuballoc(void) +.PP +.B +void dsapubfree(DSApub*) +.PP +.B +DSApriv* dsaprivalloc(void) +.PP +.B +void dsaprivfree(DSApriv*) +.PP +.B +DSAsig* dsasigalloc(void) +.PP +.B +void dsasigfree(DSAsig*) +.PP +.B +DSApub* dsaprivtopub(DSApriv*) +.SH DESCRIPTION +.PP +DSA is the NIST approved digital signature algorithm. The owner of a key publishes +the public part of the key: +.EX + struct DSApub + { + mpint *p; // modulus + mpint *q; // group order, q divides p-1 + mpint *alpha; // group generator + mpint *key; // alpha**secret mod p + }; +.EE +This part can be used for verifying signatures (with +.IR dsaverify ) +created by the owner. +The owner signs (with +.IR dsasign ) +using his private key: +.EX + struct DSApriv + { + DSApub pub; + mpint *secret; // (decryption key) + }; +.EE +.PP +Keys are generated using +.IR dsagen . +If +.IR dsagen 's +argument +.I opub +is +.BR nil , +a key is created using a new +.B p +and +.B q +generated by +.IR DSAprimes (2). +Otherwise, +.B p +and +.B q +are copied from the old key. +.PP +.I Dsaprivtopub +returns a newly allocated copy of the public key +corresponding to the private key. +.PP +The routines +.IR dsapuballoc , +.IR dsapubfree , +.IR dsaprivalloc , +and +.I dsaprivfree +are provided to manage key storage. +.PP +.I Dsasign +signs message +.I m +using a private key +.I k +yielding a +.EX + struct DSAsig + { + mpint *r, *s; + }; +.EE +.I Dsaverify +returns 0 if the signature is valid and \-1 if not. +.PP +The routines +.I dsasigalloc +and +.I dsasigfree +are provided to manage signature storage. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/man/man3/dup.3 b/man/man3/dup.3 new file mode 100644 index 00000000..83f98fe1 --- /dev/null +++ b/man/man3/dup.3 @@ -0,0 +1,42 @@ +.TH DUP 3 +.SH NAME +dup \- duplicate an open file descriptor +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int dup(int oldfd, int newfd) +.SH DESCRIPTION +Given a file descriptor, +.IR oldfd , +referring to an open file, +.I dup +returns a new file descriptor referring to the same file. +.PP +If +.I newfd +is \-1 the system chooses the lowest available file descriptor. +Otherwise, +.I dup +will use +.I newfd +for the new file descriptor +(closing any old file associated with +.IR newfd ). +File descriptors are allocated dynamically, +so to prevent unwarranted growth of the file descriptor table, +.I dup +requires that +.I newfd +be no greater than 20 more than the highest file descriptor ever used by +the program. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR dup (3) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/man/man3/elgamal.3 b/man/man3/elgamal.3 new file mode 100644 index 00000000..8298c7d8 --- /dev/null +++ b/man/man3/elgamal.3 @@ -0,0 +1,125 @@ +.TH ELGAMAL 3 +.SH NAME +eggen, egencrypt, egdecrypt, egsign, egverify, egpuballoc, egpubfree, egprivalloc, egprivfree, egsigalloc, egsigfree, egprivtopub - elgamal encryption +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +EGpriv* eggen(int nlen, int nrep) +.PP +.B +mpint* egencrypt(EGpub *k, mpint *in, mpint *out) +.PP +.B +mpint* egdecrypt(EGpriv *k, mpint *in, mpint *out) +.PP +.B +EGsig* egsign(EGpriv *k, mpint *m) +.PP +.B +int egverify(EGpub *k, EGsig *sig, mpint *m) +.PP +.B +EGpub* egpuballoc(void) +.PP +.B +void egpubfree(EGpub*) +.PP +.B +EGpriv* egprivalloc(void) +.PP +.B +void egprivfree(EGpriv*) +.PP +.B +EGsig* egsigalloc(void) +.PP +.B +void egsigfree(EGsig*) +.PP +.B +EGpub* egprivtopub(EGpriv*) +.SH DESCRIPTION +.PP +Elgamal is a public key encryption and signature algorithm. The owner of a key publishes +the public part of the key: +.EX + struct EGpub + { + mpint *p; // modulus + mpint *alpha; // generator + mpint *key; // (encryption key) alpha**secret mod p + }; +.EE +This part can be used for encrypting data (with +.IR egencrypt ) +to be sent to the owner. +The owner decrypts (with +.IR egdecrypt ) +using his private key: +.EX + struct EGpriv + { + EGpub pub; + mpint *secret; // (decryption key) + }; +.EE +.PP +Keys are generated using +.IR eggen . +.I Eggen +takes both bit length of the modulus +and the number of repetitions of the Miller-Rabin +primality test to run. If the latter is 0, it does the default number +of rounds. +.I Egprivtopub +returns a newly allocated copy of the public key +corresponding to the private key. +.PP +The routines +.IR egpuballoc , +.IR egpubfree , +.IR egprivalloc , +and +.I egprivfree +are provided to manage key storage. +.PP +.I Egsign +signs message +.I m +using a private key +.I k +yielding a +.EX + struct EGsig + { + mpint *r, *s; + }; +.EE +.I Egverify +returns 0 if the signature is valid and \-1 if not. +.PP +The routines +.I egsigalloc +and +.I egsigfree +are provided to manage signature storage. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR dsa (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/man/man3/encode.3 b/man/man3/encode.3 new file mode 100644 index 00000000..f101b273 --- /dev/null +++ b/man/man3/encode.3 @@ -0,0 +1,85 @@ +.TH ENCODE 3 +.SH NAME +dec64, enc64, dec32, enc32, dec16, enc16, encodefmt \- encoding byte arrays as strings +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int dec64(uchar *out, int lim, char *in, int n) +.PP +.B +int enc64(char *out, int lim, uchar *in, int n) +.PP +.B +int dec32(uchar *out, int lim, char *in, int n) +.PP +.B +int enc32(char *out, int lim, uchar *in, int n) +.PP +.B +int dec16(uchar *out, int lim, char *in, int n) +.PP +.B +int enc16(char *out, int lim, uchar *in, int n) +.PP +.B +int encodefmt(Fmt*) +.SH DESCRIPTION +.PP +.IR Enc16 , +.I enc32 +and +.I enc64 +create null terminated strings. They return the size of the +encoded string (without the null) or -1 if the encoding fails. +The encoding fails if +.IR lim , +the length of the output buffer, is too small. +.PP +.IR Dec16 , +.I dec32 +and +.I dec64 +return the number of bytes decoded or -1 if the decoding fails. +The decoding fails if the output buffer is not large enough or, +for base 32, if the input buffer length is not a multiple +of 8. +.PP +.I Encodefmt +can be used with +.IR fmtinstall (2) +and +.IR print (2) +to print encoded representations of byte arrays. +The verbs are +.TP +.B H +base 16 (i.e. hexadecimal). The default encoding is +in upper case. The +.B l +flag forces lower case. +.TP +.B < +base 32 +.TP +.B [ +base 64 (same as MIME) +.PD +.PP +The length of the array is specified as +.IR f2 . +For example, to display a 15 byte array as hex: +.EX + + char x[15]; + + fmtinstall('H', encodefmt); + print("%.*H\\n", sizeof x, x); + +.EE +.SH SOURCE +.B /sys/src/libc/port/u32.c +.br +.B /sys/src/libc/port/u64.c diff --git a/man/man3/encrypt.3 b/man/man3/encrypt.3 new file mode 100644 index 00000000..18e026cb --- /dev/null +++ b/man/man3/encrypt.3 @@ -0,0 +1,76 @@ +.TH ENCRYPT 3 +.SH NAME +encrypt, decrypt, netcrypt \- DES encryption +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int encrypt(void *key, void *data, int len) +.PP +.B +int decrypt(void *key, void *data, int len) +.PP +.B +int netcrypt(void *key, void *data) +.SH DESCRIPTION +.I Encrypt +and +.I decrypt +perform DES encryption and decryption. +.I Key +is an array of +.B DESKEYLEN +(defined as 7 in +.BR ) +bytes containing the encryption key. +.I Data +is an array of +.I len +bytes; +it must be at least 8 bytes long. +The bytes are encrypted or decrypted in place. +.PP +The DES algorithm encrypts an individual 8-byte block of data. +.I Encrypt +uses the following method to encrypt data longer than 8 bytes. +The first 8 bytes are encrypted as usual. +The last byte of the encrypted result +is prefixed to the next 7 unencrypted bytes to make the next 8 +bytes to encrypt. +This is repeated until fewer than 7 bytes remain unencrypted. +Any remaining unencrypted bytes are encrypted with enough of the preceding +encrypted bytes to make a full 8-byte block. +.I Decrypt +uses the inverse algorithm. +.PP +.I Netcrypt +performs the same encryption as a SecureNet Key. +.I Data +points to an +.SM ASCII +string of decimal digits with numeric value between 0 and 10000. +These digits are copied into an 8-byte buffer with trailing binary zero fill +and encrypted as one DES block. +The first four bytes are each formatted as two digit +.SM ASCII +hexadecimal numbers, +and the string is copied into +.IR data . +.SH SOURCE +.B /sys/src/libc/port +.SH DIAGNOSTICS +These routines return 1 if the data was encrypted, +and 0 if the encryption fails. +.I Encrypt +and +.I decrypt +fail if the data passed is less than 8 bytes long. +.I Netcrypt +can fail if it is passed invalid data. +.SH SEE ALSO +.IR securenet (8) +.SH BUGS +The implementation is broken in a way that makes +it unsuitable for anything but authentication. diff --git a/man/man3/errstr.3 b/man/man3/errstr.3 new file mode 100644 index 00000000..556a0d9d --- /dev/null +++ b/man/man3/errstr.3 @@ -0,0 +1,85 @@ +.TH ERRSTR 3 +.SH NAME +errstr, rerrstr, werrstr \- description of last system call error +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int errstr(char *err, uint nerr) +.PP +.B +void rerrstr(char *err, uint nerr) +.PP +.B +void werrstr(char *fmt, ...) +.SH DESCRIPTION +When a system call fails it returns \-1 and +records a null terminated string describing the error in a per-process buffer. +.I Errstr +swaps the contents of that buffer with the contents of the array +.IR err . +.I Errstr +will write at most +.I nerr +bytes into +.IR err ; +if the per-process error string does not fit, +it is silently truncated at a UTF character boundary. +The returned string is NUL-terminated. +Usually +.I errstr +will be called with an empty string, +but the exchange property provides a mechanism for +libraries to set the return value for the next call to +.IR errstr . +.PP +The per-process buffer is +.B ERRMAX +bytes long. Any error string provided by the user will +be truncated at +.B ERRMAX-1 +bytes. +.B ERRMAX +is defined in +.BR . +.PP +If no system call has generated an error since the last call to +.I errstr +with an empty string, +the result is an empty string. +.PP +The verb +.B r +in +.IR print (2) +calls +.I errstr +and outputs the error string. +.PP +.I Rerrstr +reads the error string but does not modify the per-process buffer, so +a subsequent +.I errstr +will recover the same string. +.PP +.I Werrstr +takes a +.I print +style format as its argument and uses it to format +a string to pass to +.IR errstr . +The string returned from +.I errstr +is discarded. +.SH SOURCE +.B /sys/src/libc/9syscall +.br +.B /sys/src/libc/9sys/werrstr.c +.SH DIAGNOSTICS +.I Errstr +always returns 0. +.SH SEE ALSO +.IR intro (2), +.IR perror (2) diff --git a/man/man3/event.3 b/man/man3/event.3 new file mode 100644 index 00000000..9a71ddc3 --- /dev/null +++ b/man/man3/event.3 @@ -0,0 +1,384 @@ +.TH EVENT 3 +.SH NAME +event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu \- graphics events +.SH SYNOPSIS +.nf +.PP +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.ta \w'\fLRectangle 'u +.PP +.B +void einit(ulong keys) +.PP +.B +ulong event(Event *e) +.PP +.B +Mouse emouse(void) +.PP +.B +int ekbd(void) +.PP +.B +int ecanmouse(void) +.PP +.B +int ecankbd(void) +.PP +.B +int ereadmouse(Mouse *m) +.PP +.B +int eatomouse(Mouse *m, char *buf, int n) +.PP +.B +ulong estart(ulong key, int fd, int n) +.PP +.B +ulong estartfn(int id, ulong key, int fd, int n, +.B + int (*fn)(Event*, uchar*, int)) +.PP +.B +ulong etimer(ulong key, int n) +.PP +.B +ulong eread(ulong keys, Event *e) +.PP +.B +int ecanread(ulong keys) +.PP +.B +void eresized(int new) +.PP +.B +Rectangle egetrect(int but, Mouse *m) +.PP +.B +void edrawgetrect(Rectangle r, int up) +.PP +.B +int emenuhit(int but, Mouse *m, Menu *menu) +.PP +.PP +.B +int emoveto(Point p) +.PP +.PP +.B +int esetcursor(Cursor *c) +.PP +.B +extern Mouse *mouse +.PP +.B +enum{ +.B + Emouse = 1, +.B + Ekeyboard = 2, +.B +}; +.PP +.SH DESCRIPTION +These routines provide an interface to multiple sources of input for unthreaded +programs. +Threaded programs (see +.IR thread (2)) +should instead use the threaded mouse and keyboard interface described +in +.IR mouse (2) +and +.IR keyboard (2). +.PP +.I Einit +must be called first. +If the argument to +.I einit +has the +.B Emouse +and +.B Ekeyboard +bits set, +the mouse and keyboard events will be enabled; +in this case, +.IR initdraw +(see +.IR graphics (2)) +must have already been called. +The user must provide a function called +.IR eresized +to be called whenever the window in which the process +is running has been resized; the argument +.I new +is a flag specifying whether the program must call +.I getwindow +(see +.IR graphics (2)) +to re-establish a connection to its window. +After resizing (and perhaps calling +.IR getwindow ), +the global variable +.B screen +will be updated to point to the new window's +.B Image +structure. +.PP +As characters are typed on the keyboard, they are read by the +event mechanism and put in a queue. +.I Ekbd +returns the next rune from the queue, blocking until the +queue is non-empty. +The characters are read in raw mode +(see +.IR cons (3)), +so they are available as soon as a complete rune is typed. +.PP +When the mouse moves or a mouse button is pressed or released, +a new mouse event is queued by the event mechanism. +.I Emouse +returns the next mouse event from the queue, blocking until the +queue is non-empty. +.I Emouse +returns a +.B Mouse +structure: +.IP +.EX +.ta 6n +\w'Point 'u +struct Mouse +{ + int buttons; + Point xy; + ulong msec; +}; +.EE +.PP +.B Buttons&1 +is set when the left mouse button is pressed, +.B buttons&2 +when the middle button is pressed, +and +.B buttons&4 +when the right button is pressed. +The current mouse position is always returned in +.BR xy . +.B Msec +is a time stamp in units of milliseconds. +.PP +.I Ecankbd +and +.I ecanmouse +return non-zero when there are keyboard or mouse events available +to be read. +.PP +.I Ereadmouse +reads the next mouse event from the file descriptor connected to the mouse, +converts the textual data into a +.B Mouse +structure by calling +.I eatomouse +with the buffer and count from the read call, +and returns the number of bytes read, or \-1 for an error. +.PP +.I Estart +can be used to register additional file descriptors to scan for input. +It takes as arguments the file descriptor to register, +the maximum length of an event message on that descriptor, +and a key to be used in accessing the event. +The key must be a power of 2 and must not conflict with any previous keys. +If a zero key is given, a key will be allocated and returned. +.I Estartfn +is similar to +.IR estart , +but processes the data received by calling +.I fn +before returning the event to the user. +The function +.I fn +is called with the +.B id +of the event; it should return +.B id +if the event is to be passed to the user, +.B 0 +if it is to be ignored. +The variable +.B Event.v +can be used by +.I fn +to attach an arbitrary data item to the returned +.B Event +structure. +.B +Ekeyboard +and +.B Emouse +are the keyboard and mouse event keys. +.PP +.I Etimer +starts a repeating timer with a period of +.I n +milliseconds; it returns the timer event key, or zero if it fails. +Only one timer can be started. +Extra timer events are not queued and the timer channel has no associated data. +.PP +.I Eread +waits for the next event specified by the mask +.I keys +of event keys submitted to +.IR estart . +It fills in the appropriate field of the argument +.B Event +structure, which looks like: +.IP +.EX +struct Event +{ + int kbdc; + Mouse mouse; + int n; + void *v; + uchar data[EMAXMSG]; +}; +.EE +.PP +.B Data +is an array which is large enough to hold a 9P message. +.I Eread +returns the key for the event which was chosen. +For example, if a mouse event was read, +.B Emouse +will be returned. +.PP +.I Event +waits for the next event of any kind. +The return is the same as for +.IR eread . +.PP +As described in +.IR graphics (2), +the graphics functions are buffered. +.IR Event , +.IR eread , +.IR emouse , +and +.I ekbd +all cause a buffer flush unless there is an event of the +appropriate type already queued. +.PP +.I Ecanread +checks whether a call to +.B eread(keys) +would block, returning 0 if it would, 1 if it would not. +.PP +.I Getrect +prompts the user to sweep a rectangle. +It should be called with +.I m +holding the mouse event that triggered the +.I egetrect +(or, if none, a +.B Mouse +with +.B buttons +set to 7). +It changes to the sweep cursor, +waits for the buttons all to be released, +and then waits for button number +.I but +to be pressed, marking the initial corner. +If another button is pressed instead, +.I egetrect +returns a rectangle +with zero for both corners, after +waiting for all the buttons to be released. +Otherwise, +.I egetrect +continually draws the swept rectangle +until the button is released again, and returns the swept rectangle. +The mouse structure pointed to by +.I m +will contain the final mouse event. +.PP +.I Egetrect +uses successive calls to +.I edrawgetrect +to maintain the red rectangle showing the sweep-in-progress. +The rectangle to be drawn is specified by +.I rc +and the +.I up +parameter says whether to draw (1) or erase (0) the rectangle. +.PP +.I Emenuhit +displays a menu and returns a selected menu item number. +It should be called with +.I m +holding the mouse event that triggered the +.IR emenuhit ; +it will call +.I emouse +to update it. +A +.B Menu +is a structure: +.IP +.EX +struct Menu +{ + char **item; + char *(*gen)(int); + int lasthit; +}; +.EE +.PP +If +.B item +is nonzero, it should be a null-terminated array of the character strings +to be displayed as menu items. +Otherwise, +.B gen +should be a function that, given an item number, returns the character +string for that item, or zero if the number is past the end of the list. +Items are numbered starting at zero. +.I Menuhit +waits until +.I but +is released, and then returns the number of the selection, +or \-1 for no selection. +The +.I m +argument is filled in with the final mouse event. +.PP +.I Emoveto +moves the mouse cursor to the position +.B p +on the screen. +.PP +.I Esetcursor +changes the cursor image to that described by the +.B Cursor +.I c +(see +.IR mouse (2)). +If +.B c +is nil, it restores the image to the default arrow. +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR rio (1), +.IR graphics (2), +.IR plumb (2), +.IR cons (3), +.IR draw (3) diff --git a/man/man3/exec.3 b/man/man3/exec.3 new file mode 100644 index 00000000..5ce9583a --- /dev/null +++ b/man/man3/exec.3 @@ -0,0 +1,159 @@ +.TH EXEC 3 +.SH NAME +exec, execl, _clock, _privates, _nprivates \- execute a file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +int exec(char *name, char* argv[]) +.PP +.B +int execl(char *name, ...) +.PP +.B +long *_clock; +.PP +.B +void **_privates; +.PP +.B +int _nprivates; +.fi +.SH DESCRIPTION +.I Exec +and +.I execl +overlay the calling process with the named file, then +transfer to the entry point of the image of the file. +.PP +.I Name +points to the name of the file +to be executed; it must not be a directory, and the permissions +must allow the current user to execute it +(see +.IR stat (2)). +It should also be a valid binary image, as defined in the +.IR a.out (6) +for the current machine architecture, +or a shell script +(see +.IR rc (1)). +The first line of a +shell script must begin with +.L #! +followed by the name of the program to interpret the file +and any initial arguments to that program, for example +.IP +.EX +#!/bin/rc +ls | mc +.EE +.PP +When a C program is executed, +it is called as follows: +.IP +.EX +void main(int argc, char *argv[]) +.EE +.PP +.I Argv +is a copy of the array of argument pointers passed to +.IR exec ; +that array must end in a null pointer, and +.I argc +is the number of elements before the null pointer. +By convention, the first argument should be the name of +the program to be executed. +.I Execl +is like +.I exec +except that +.I argv +will be an array of the parameters that follow +.I name +in the call. The last argument to +.I execl +must be a null pointer. +.PP +For a file beginning +.BR #! , +the arguments passed to the program +.RB ( /bin/rc +in the example above) will be the name of the file being +executed, any arguments on the +.B #! +line, the name of the file again, +and finally the second and subsequent arguments given to the original +.I exec +call. +The result honors the two conventions of a program accepting as argument +a file to be interpreted and +.B argv[0] +naming the file being +executed. +.PP +Most attributes of the calling process are carried +into the result; in particular, +files remain open across +.I exec +(except those opened with +.B OCEXEC +OR'd +into the open mode; see +.IR open (2)); +and the working directory and environment +(see +.IR env (3)) +remain the same. +However, a newly +.I exec'ed +process has no notification handler +(see +.IR notify (2)). +.PP +When the new program begins, the global cell +.B _clock +is set to the address of a cell that keeps approximate time +expended by the process at user level. +The time is measured in milliseconds but is updated at +a system-dependent lower rate. +This clock is typically used by the profiler but is available +to all programs. +.PP +The global cell +.B _privates +points to an array of +.B _nprivates +elements of per-process private data. +This storage is private for each process, even if the processes share data segments. +.PP +The above conventions apply to C programs; the raw system +interface to the new image is as follows: +the word pointed to by the stack pointer is +.BR argc ; +the words beyond that are the zeroth and subsequent elements +of +.BR argv , +followed by a terminating null pointer; and +the return register (e.g. +.B R0 +on the 68020) contains the address of the clock. +.SH SOURCE +.B /sys/src/libc/9syscall +.br +.B /sys/src/libc/port/execl.c +.SH SEE ALSO +.IR prof (1), +.IR intro (2), +.IR stat (2) +.SH DIAGNOSTICS +If these functions fail, they return and set +.IR errstr . +There can be no return from a successful +.I exec +or +.IR execl ; +the calling image is lost. diff --git a/man/man3/exits.3 b/man/man3/exits.3 new file mode 100644 index 00000000..c242cb0e --- /dev/null +++ b/man/man3/exits.3 @@ -0,0 +1,81 @@ +.TH EXITS 3 +.SH NAME +exits, _exits, atexit, atexitdont, terminate \- terminate process, process cleanup +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +void _exits(char *msg) +.B +void exits(char *msg) +.PP +.B +int atexit(void(*)(void)) +.PP +.B +void atexitdont(void(*)(void)) +.fi +.SH DESCRIPTION +.I Exits +is the conventional way to terminate a process. +.I _Exits +is the underlying system call. +They +can never return. +.PP +.I Msg +conventionally includes a brief (maximum length +.BR ERRLEN ) +explanation of the reason for +exiting, or a null pointer or empty string to indicate normal termination. +The string is passed to the parent process, prefixed by the name and process +id of the exiting process, when the parent does a +.IR wait (2). +.PP +Before calling +.I _exits +with +.I msg +as an argument, +.I exits +calls in reverse order all the functions +recorded by +.IR atexit . +.PP +.I Atexit +records +.I fn +as a function to be called by +.IR exits . +It returns zero if it failed, +nonzero otherwise. +A typical use is to register a cleanup routine for an I/O package. +To simplify programs that fork or share memory, +.I exits +only calls those +.IR atexit -registered +functions that were registered by the same +process as that calling +.IR exits . +.PP +Calling +.I atexit +twice (or more) with the same function argument causes +.I exits +to invoke the function twice (or more). +.PP +There is a limit to the number of exit functions +that will be recorded; +.I atexit +returns 0 if that limit has been reached. +.PP +.I Atexitdont +cancels a previous registration of an exit function. +.SH SOURCE +.B /sys/src/libc/port/atexit.c +.SH "SEE ALSO" +.IR fork (2), +.IR wait (2) diff --git a/man/man3/fcall.3 b/man/man3/fcall.3 new file mode 100644 index 00000000..1219cf20 --- /dev/null +++ b/man/man3/fcall.3 @@ -0,0 +1,357 @@ +.TH FCALL 3 +.SH NAME +Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeS2M, sizeD2M \- interface to Plan 9 File protocol +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.br +.B #include +.PP +.B +uint convS2M(Fcall *f, uchar *ap, uint nap) +.PP +.B +uint convD2M(Dir *d, uchar *ap, uint nap) +.PP +.B +uint convM2S(uchar *ap, uint nap, Fcall *f) +.PP +.B +uint convM2D(uchar *ap, uint nap, Dir *d, char *strs) +.PP +.B +int dirfmt(Fmt*) +.PP +.B +int fcallfmt(Fmt*) +.PP +.B +int dirmodefmt(Fmt*) +.PP +.B +int read9pmsg(int fd, uchar *buf, uint nbuf) +.PP +.B +int statcheck(uchar *buf, uint nbuf) +.PP +.B +uint sizeS2M(Fcall *f) +.PP +.B +uint sizeD2M(Dir *d) +.SH DESCRIPTION +These +routines convert messages in the machine-independent format of +the Plan 9 file protocol, +9P, to and from a more convenient form, +an +.B Fcall +structure: +.PP +.EX +.if n .ta 4n +6n +5n +6n +18n +4n +.if t .ta \w'xxxx'u +\w'short 'u +\w'xxxx'u +\w'ushort 'u +\w'ticket[TICKETLEN]; 'u +\w'/* 'u +#define MAXWELEM 16 + +typedef +struct Fcall +{ + uchar type; + u32int fid; + ushort tag; + union { + struct { + u32int msize; /* Tversion, Rversion */ + char *version; /* Tversion, Rversion */ + }; + struct { + ushort oldtag; /* Tflush */ + }; + struct { + char *ename; /* Rerror */ + }; + struct { + Qid qid; /* Rattach, Ropen, Rcreate */ + u32int iounit; /* Ropen, Rcreate */ + }; + struct { + Qid aqid; /* Rauth */ + }; + struct { + u32int afid; /* Tauth, Tattach */ + char *uname; /* Tauth, Tattach */ + char *aname; /* Tauth, Tattach */ + }; + struct { + u32int perm; /* Tcreate */ + char *name; /* Tcreate */ + uchar mode; /* Tcreate, Topen */ + }; + struct { + u32int newfid; /* Twalk */ + ushort nwname; /* Twalk */ + char *wname[MAXWELEM]; /* Twalk */ + }; + struct { + ushort nwqid; /* Rwalk */ + Qid wqid[MAXWELEM]; /* Rwalk */ + }; + struct { + vlong offset; /* Tread, Twrite */ + u32int count; /* Tread, Twrite, Rread */ + char *data; /* Twrite, Rread */ + }; + struct { + ushort nstat; /* Twstat, Rstat */ + uchar *stat; /* Twstat, Rstat */ + }; + }; +} Fcall; +.EE +.EX + +/* these are implemented as macros */ + +uchar GBIT8(uchar*) +ushort GBIT16(uchar*) +ulong GBIT32(uchar*) +vlong GBIT64(uchar*) + +void PBIT8(uchar*, uchar) +void PBIT16(uchar*, ushort) +void PBIT32(uchar*, ulong) +void PBIT64(uchar*, vlong) + +#define BIT8SZ 1 +#define BIT16SZ 2 +#define BIT32SZ 4 +#define BIT64SZ 8 +.EE +.PP +This structure is defined in +.BR . +See section 5 +for a full description of 9P messages and their encoding. +For all message types, the +.B type +field of an +.B Fcall +holds one of +.BR Tversion , +.BR Rversion , +.BR Tattach , +.BR Rattach , +etc. (defined in an enumerated type in +.BR ). +.B Fid +is used by most messages, and +.B tag +is used by all messages. +The other fields are used selectively by the message types +given in comments. +.PP +.I ConvM2S +takes a 9P message at +.I ap +of length +.IR nap , +and uses it to fill in +.B Fcall +structure +.IR f . +If the passed message +including any data for +.B Twrite +and +.B Rread +messages +is formatted properly, +the return value is the number of bytes the message occupied in the buffer +.IR ap , +which will always be less than or equal to +.IR nap ; +otherwise it is 0. +For +.B Twrite +and +.B Tread +messages, +.B data +is set to a pointer into the argument message, +not a copy. +.PP +.I ConvS2M +does the reverse conversion, turning +.I f +into a message starting at +.IR ap . +The length of the resulting message is returned. +For +.B Twrite +and +.B Rread +messages, +.B count +bytes starting at +.B data +are copied into the message. +.PP +The constant +.B IOHDRSZ +is a suitable amount of buffer to reserve for storing +the 9P header; +the data portion of a +.B Twrite +or +.B Rread +will be no more than the buffer size negotiated in the +.BR Tversion/Rversion +exchange, minus +.BR IOHDRSZ . +.PP +The routine +.I sizeS2M +returns the number of bytes required to store the machine-independent representation of the +.B Fcall +structure +.IR f , +including its initial 32-bit size field. +In other words, it reports the number of bytes produced +by a successful call to +.IR convS2M . +.PP +Another structure is +.BR Dir , +used by the routines described in +.IR stat (2). +.I ConvM2D +converts the machine-independent form starting at +.I ap +into +.IR d +and returns the length of the machine-independent encoding. +The strings in the returned +.B Dir +structure are stored at successive locations starting at +.BR strs . +Usually +.B strs +will point to storage immediately after the +.B Dir +itself. +It can also be a +.B nil +pointer, in which case the string pointers in the returned +.B Dir +are all +.BR nil ; +however, the return value still includes their length. +.PP +.I ConvD2M +does the reverse translation, +also returning the length of the encoding. +If the buffer is too short, the return value will be +.B BIT16SZ +and the correct size will be returned in the first +.B BIT16SZ +bytes. +(If the buffer is less that +.BR BIT16SZ , +the return value is zero; therefore a correct test for +complete packing of the message is that the return value is +greater than +.BR BIT16SZ ). +The macro +.B GBIT16 +can be used to extract the correct value. +The related macros with different sizes retrieve the corresponding-sized quantities. +.B PBIT16 +and its brethren place values in messages. +With the exception of handling short buffers in +.IR convD2M , +these macros are not usually needed except by internal routines. +.PP +Analogous to +.IR sizeS2M , +.I sizeD2M +returns the number of bytes required to store the machine-independent representation of the +.B Dir +structure +.IR d , +including its initial 16-bit size field. +.PP +The routine +.B statcheck +checks whether the +.I nbuf +bytes of +.I buf +contain a validly formatted machine-independent +.B Dir +entry suitable as an argument, for example, for the +.B wstat +(see +.IR stat (2)) +system call. +It checks that the sizes of all the elements of the the entry sum to exactly +.IR nbuf , +which is a simple but effective test of validity. +.I Nbuf +and +.I buf +should include the second two-byte (16-bit) length field that precedes the entry when +formatted in a 9P message (see +.IR stat (5)); +in other words, +.I nbuf +is 2 plus the sum of the sizes of the entry itself. +.I Statcheck +also verifies that the length field has the correct value (that is, +.IB nbuf -2\f1). +It returns +.B 0 +for a valid entry and +.B -1 +for an incorrectly formatted entry. +.PP +.IR Dirfmt , +.IR fcallfmt , +and +.I dirmodefmt +are formatting routines, suitable for +.IR fmtinstall (2). +They convert +.BR Dir* , +.BR Fcall* , +and +.BR long +values into string representations of the directory buffer, +.B Fcall +buffer, +or file mode value. +.I Fcallfmt +assumes that +.I dirfmt +has been installed with format letter +.L D +and +.I dirmodefmt +with format letter +.LR M . +.PP +.I Read9pmsg +calls +.IR read (2) +multiple times, if necessary, to read an entire 9P message into +.BR buf . +The return value is 0 for end of file, or -1 for error; it does not return +partial messages. +.SH SOURCE +.B /sys/src/libc/9sys +.SH SEE ALSO +.IR intro (2), +.IR 9p (2), +.IR stat (2), +.IR intro (5) diff --git a/man/man3/flate.3 b/man/man3/flate.3 new file mode 100644 index 00000000..816875fd --- /dev/null +++ b/man/man3/flate.3 @@ -0,0 +1,207 @@ +.TH FLATE 3 +.SH NAME +deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, flateerr, mkcrctab, blockcrc, adler32 \- deflate compression +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'ulongmm'u +.PP +.B +int deflateinit(void) +.PP +.B +int deflate(void *wr, int (*w)(void*,void*,int), +.br +.B + void *rr, int (*r)(void*,void*,int), +.br +.B + int level, int debug) +.PP +.B +int deflatezlib(void *wr, int (*w)(void*,void*,int), +.br +.B + void *rr, int (*r)(void*,void*,int), +.br +.B + int level, int debug) +.PP +.B +int deflateblock(uchar *dst, int dsize, +.br +.B + uchar *src, int ssize, +.br +.B + int level, int debug) +.PP +.B +int deflatezlibblock(uchar *dst, int dsize, +.br +.B + uchar *src, int ssize, +.br +.B + int level, int debug) +.PP +.B +int inflateinit(void) +.PP +.B +int inflate(void *wr, int (*w)(void*, void*, int), +.br +.B + void *getr, int (*get)(void*)) +.PP +.B +int inflatezlib(void *wr, int (*w)(void*, void*, int), +.br +.B + void *getr, int (*get)(void*)) +.PP +.B +int inflateblock(uchar *dst, int dsize, +.br +.B + uchar *src, int ssize) +.PP +.B +int inflatezlibblock(uchar *dst, int dsize, +.br +.B + uchar *src, int ssize) +.PP +.B +char *flateerr(int error) +.PP +.B +ulong *mkcrctab(ulong poly) +.PP +.B +ulong blockcrc(ulong *tab, ulong crc, void *buf, int n) +.PP +.B +ulong adler32(ulong adler, void *buf, int n) +.SH DESCRIPTION +These routines compress and decompress data using the deflate compression algorithm, +which is used for most gzip, zip, and zlib files. +.PP +.I Deflate +compresses input data retrieved by calls to +.I r +with arguments +.IR rr , +an input buffer, and a count of bytes to read. +.I R +should return the number of bytes read; +end of input is signaled by returning zero, an input error by +returning a negative number. +The compressed output is written to +.I w +with arguments +.IR wr , +the output data, and the number of bytes to write. +.I W +should return the number of bytes written; +writing fewer than the requested number of bytes is an error. +.I Level +indicates the amount of computation deflate should do while compressing the data. +Higher +.I levels +usually take more time and produce smaller outputs. +Valid values are 1 to 9, inclusive; 6 is a good compromise. +If +.I debug +is non-zero, cryptic debugging information is produced on standard error. +.PP +.I Inflate +reverses the process, converting compressed data into uncompressed output. +Input is retrieved one byte at a time by calling +.I get +with the argument +.IR getr . +End of input of signaled by returning a negative value. +The uncompressed output is written to +.IR w , +which has the same interface as for +.IR deflate . +.PP +.I +Deflateblock +and +.I inflateblock +operate on blocks of memory but are otherwise similar to +.I deflate +and +.IR inflate . +.PP +The zlib functions are similar, but operate on files with a zlib header and trailer. +.PP +.I Deflateinit +or +.I inflateinit +must be called once before any call to the corresponding routines. +.PP +If the above routines fail, +they return a negative number indicating the problem. +The possible values are +.IR FlateNoMem , +.IR FlateInputFail , +.IR FlateOutputFail , +.IR FlateCorrupted , +and +.IR FlateInternal . +.I Flateerr +converts the number into a printable message. +.I FlateOk +is defined to be zero, +the successful return value for +.IR deflateinit , +.IR deflate , +.IR deflatezlib , +.IR inflateinit , +.IR inflate , +and +.IR inflatezlib . +The block functions return the number of bytes produced when they succeed. +.PP +.I Mkcrctab +allocates +(using +.IR malloc (2)), +initializes, and returns a table for rapid computation of 32 bit CRC values using the polynomial +.IR poly . +.I Blockcrc +uses +.IR tab , +a table returned by +.IR mkcrctab , +to update +.I crc +for the +.I n +bytes of data in +.IR buf , +and returns the new value. +.I Crc +should initially be zero. +.I Blockcrc +pre-conditions and post-conditions +.I crc +by ones complementation. +.PP +.I Adler32 +updates the Adler 32-bit checksum of the +.I n +butes of data in +.IR buf. +The initial value of +.I adler +(that is, its value after seeing zero bytes) should be 1. +.SH SOURCE +.B /sys/src/libflate diff --git a/man/man3/fmtinstall.3 b/man/man3/fmtinstall.3 index 2a0e55bf..90d487db 100644 --- a/man/man3/fmtinstall.3 +++ b/man/man3/fmtinstall.3 @@ -1,22 +1,17 @@ .TH FMTINSTALL 3 -.de EX -.nf -.ft B -.. -.de EE -.fi -.ft R -.. .SH NAME -fmtinstall, dofmt, fmtprint, fmtvprint, fmtstrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush \- support for user-defined print formats and output routines +fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, runefmtstrinit, runefmtstrflush, errfmt \- support for user-defined print formats and output routines .SH SYNOPSIS -.B #include +.B #include +.br +.B #include .PP .ft L .nf .ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u typedef struct Fmt Fmt; struct Fmt{ + uchar runes; /* output buffer is runes or chars? */ void *start; /* of buffer */ void *to; /* current place in the buffer */ void *stop; /* end of the buffer; overwritten if flush fails */ @@ -24,10 +19,10 @@ struct Fmt{ void *farg; /* to make flush a closure */ int nfmt; /* num chars formatted so far */ va_list args; /* args passed to dofmt */ - int r; /* % format character */ + int r; /* % format Rune */ int width; int prec; - unsigned long flags; + ulong flags; }; enum{ @@ -43,10 +38,8 @@ enum{ FmtLong = FmtShort << 1, FmtVLong = FmtLong << 1, FmtComma = FmtVLong << 1, - FmtByte = FmtComma << 1, - FmtLDouble = FmtByte << 1, - FmtFlag = FmtLDouble << 1 + FmtFlag = FmtComma << 1 }; .fi .PP @@ -65,6 +58,13 @@ int fmtstrinit(Fmt *f); .PP .B char* fmtstrflush(Fmt *f); +.PP +.B +int runefmtstrinit(Fmt *f); +.PP +.B +Rune* runefmtstrflush(Fmt *f); + .PP .B int fmtinstall(int c, int (*fn)(Fmt*)); @@ -73,6 +73,9 @@ int fmtinstall(int c, int (*fn)(Fmt*)); int dofmt(Fmt *f, char *fmt); .PP .B +int dorfmt(Fmt*, Rune *fmt); +.PP +.B int fmtprint(Fmt *f, char *fmt, ...); .PP .B @@ -83,18 +86,24 @@ int fmtrune(Fmt *f, int r); .PP .B int fmtstrcpy(Fmt *f, char *s); +.PP +.B +int fmtrunestrcpy(Fmt *f, Rune *s); +.PP +.B +int errfmt(Fmt *f); .SH DESCRIPTION The interface described here allows the construction of custom -.IR print (3) +.IR print (2) verbs and output routines. In essence, they provide access to the workings of the formatted print code. .PP The -.IR print (3) +.IR print (2) suite maintains its state with a data structure called .BR Fmt . A typical call to -.IR print (3) +.IR print (2) or its relatives initializes a .B Fmt structure, passes it to subsidiary routines to process the output, @@ -106,7 +115,7 @@ are unimportant to outside users, except insofar as the general design influences the interface. The .B Fmt -records +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 @@ -142,15 +151,15 @@ Then call or .IR fmtvprint to generate the output. -These behave just like +These behave like .B fprint (see -.IR print (3)) +.IR print (2)) or .B vfprint except that the characters are buffered until .I fmtfdflush -is called. +is called and the return value is either 0 or \-1. A typical example of this sequence appears in the Examples section. .PP The same basic sequence applies when outputting to an allocated string: @@ -166,6 +175,10 @@ to generate the output. Finally, .I fmtstrflush will return the allocated string, which should be freed after use. +To output to a rune string, use +.I runefmtstrinit +and +.IR runefmtstrflush . Regardless of the output style or type, .I fmtprint or @@ -194,7 +207,7 @@ In are the width and precision, and .IB fp ->flags the decoded flags for the verb (see -.IR print (3) +.IR print (2) for a description of these items). The standard flag values are: .B FmtSign @@ -211,12 +224,8 @@ The standard flag values are: .RB ( l ), .B FmtShort .RB ( h ), -.B FmtByte -.RB ( hh ), .B FmtUnsigned .RB ( u ), -.B FmtLDouble -.RB ( L ), and .B FmtVLong .RB ( ll ). @@ -242,8 +251,7 @@ If .IB fp ->r is a flag, .I fn -should return a negative value: -the negation of one of the above flag values, or some otherwise unused power of two. +should return one. All interpretation of .IB fp ->width\f1, .IB fp ->prec\f1, @@ -259,30 +267,47 @@ and may be called to help prepare output in custom conversion routines. However, these functions clear the width, precision, and flags. -The function +Both functions return 0 for success and \-1 for failure. +.PP +The functions .I dofmt -is the underlying formatter; it -uses the existing contents of +and +.I dorfmt +are the underlying formatters; they +use the existing contents of .B Fmt and should be called only by sophisticated conversion routines. -All these routines return the number of characters +These routines return the number of characters (bytes of UTF or runes) produced. .PP Some internal functions may be useful to format primitive types. They honor the width, precision and flags as described in -.IR print (3). +.IR print (2). .I Fmtrune formats a single character .BR r . .I Fmtstrcpy formats a string +.BR s ; +.I fmtrunestrcpy +formats a rune string .BR s . +.I Errfmt +formats the system error string. All these routines return zero for successful execution. +Conversion routines that call these functions will work properly +regardless of whether the output is bytes or runes. +.PP +.IR 2c (1) +describes the C directive +.B #pragma +.B varargck +that can be used to provide type-checking for custom print verbs and output routines. .SH EXAMPLES This function prints an error message with a variable number of arguments and then quits. Compared to the corresponding example in -.IR print (3), +.IR print (2), this version uses a smaller buffer, will never truncate the output message, but might generate multiple .B write @@ -290,6 +315,7 @@ system calls to produce its output. .IP .EX .ta 6n +6n +6n +6n +6n +6n +6n +6n +6n +#pragma varargck argpos error 1 void fatal(char *fmt, ...) { @@ -316,6 +342,8 @@ struct { double r, i; } Complex; +#pragma varargck type "X" Complex + int Xfmt(Fmt *f) { @@ -327,20 +355,19 @@ Xfmt(Fmt *f) main(...) { - Complex x; - - x.r = 1.5; - x.i = -2.3; + Complex x = (Complex){ 1.5, -2.3 }; fmtinstall('X', Xfmt); print("x = %X\en", x); } .EE +.SH SOURCE +.B /sys/src/libc/fmt .SH SEE ALSO -.IR print (3) -.SH HISTORY -This formatted print library originally -appeared as part of the Plan 9 C library. +.IR print (2), +.IR utf (6), +.IR errstr (2) +.SH DIAGNOSTICS +These routines return negative numbers or nil for errors and set +.IR errstr . .SH BUGS -The Plan 9 version supports Unicode strings and produces UTF output. -This version assumes that characters are always represented by 1-byte values. diff --git a/man/man3/fork.3 b/man/man3/fork.3 new file mode 100644 index 00000000..9f305fd7 --- /dev/null +++ b/man/man3/fork.3 @@ -0,0 +1,166 @@ +.TH FORK 3 +.SH NAME +fork, rfork \- manipulate process resources +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +int fork(void) +.PP +.B +int rfork(int flags) +.fi +.SH DESCRIPTION +Forking is the only way new processes are created. +The +.I flags +argument to +.I rfork +selects which resources of the +invoking process (parent) are shared +by the new process (child) or initialized to +their default values. +The resources include +the file name space, +the open file descriptor table (which, when shared, permits processes +to open and close files for other processes), +the set of environment variables +(see +.IR env (3)), +the note group +(the set of processes that receive notes written to a member's +.B notepg +file; +see +.IR proc (3)), +the set of rendezvous tags +(see +.IR rendezvous (2)); +and open files. +.I Flags +is the logical OR of some subset of +.TF RFCNAMEG +.TP +.B RFPROC +If set a new process is created; otherwise changes affect the +current process. +.TP +.B RFNOWAIT +If set, the child process will be dissociated from the parent. Upon +exit the child will leave no +.B Waitmsg +(see +.IR wait (2)) +for the parent to collect. +.TP +.B RFNAMEG +If set, the new process inherits a copy of the parent's name space; +otherwise the new process shares the parent's name space. +Is mutually exclusive with +.BR RFCNAMEG . +.TP +.B RFCNAMEG +If set, the new process starts with a clean name space. A new +name space must be built from a mount of an open file descriptor. +Is mutually exclusive with +.BR RFNAMEG . +.TP +.B RFNOMNT +If set, subsequent mounts into the new name space and dereferencing +of pathnames starting with +.B # +are disallowed. +.TP +.B RFENVG +If set, the environment variables are copied; +otherwise the two processes share environment variables. +Is mutually exclusive with +.BR RFCENVG . +.TP +.B RFCENVG +If set, the new process starts with an empty environment. +Is mutually exclusive with +.BR RFENVG . +.TP +.B RFNOTEG +Each process is a member of a group of processes that all +receive notes when a note is written to any of their +.B notepg +files (see +.IR proc (3)). +The group of a new process is by default the same as its parent, but if +.B RFNOTEG +is set (regardless of +.BR RFPROC ), +the process becomes the first in a new group, isolated from +previous processes. +.TP +.B RFFDG +If set, the invoker's file descriptor table (see +.IR intro (2)) +is copied; otherwise the two processes share a +single table. +.TP +.B RFCFDG +If set, the new process starts with a clean file descriptor table. +Is mutually exclusive with +.BR RFFDG . +.TP +.B RFREND +If set, the process will be unable to +.IR rendezvous (2) +with any of its ancestors; its children will, however, be able to +.B rendezvous +with it. In effect, +.B RFREND +makes the process the first in a group of processes that share a space for +.B rendezvous +tags. +.TP +.B RFMEM +If set, the child and the parent will share +.B data +and +.B bss +segments. +Otherwise, the child inherits a copy of those segments. +Other segment types, in particular stack segments, will be unaffected. +May be set only with +.BR RFPROC . +.PD +.PP +File descriptors in a shared file descriptor table are kept +open until either they are explicitly closed +or all processes sharing the table exit. +.PP +If +.B RFPROC +is set, the +value returned in the parent process +is the process id +of the child process; the value returned in the child is zero. +Without +.BR RFPROC , +the return value is zero. +Process ids range from 1 to the maximum integer +.RB ( int ) +value. +.I Rfork +will sleep, if necessary, until required process resources are available. +.PP +.I Fork +is just a call of +.BR rfork(RFFDG|RFREND|RFPROC) . +.SH SOURCE +.B /sys/src/libc/9syscall +.br +.B /sys/src/libc/9sys/fork.c +.SH SEE ALSO +.IR intro (2), +.IR proc (3), +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/man/man3/frame.3 b/man/man3/frame.3 new file mode 100644 index 00000000..8ee03e17 --- /dev/null +++ b/man/man3/frame.3 @@ -0,0 +1,362 @@ +.TH FRAME 3 +.SH NAME +frinit, frsetrects, frinittick, frclear, frcharofpt, frptofchar, frinsert, frdelete, frselect, frtick, frselectpaint, frdrawsel, frdrawsel0, frgetmouse \- frames of text +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.PP +.B +void frinit(Frame *f, Rectangle r, Font *ft, Image *b, Image **cols) +.PP +.B +void frsetrects(Frame *f, Rectangle r, Image *b) +.PP +.B +void frinittick(Frame *f) +.PP +.B +void frclear(Frame *f, int resize) +.PP +.B +ulong frcharofpt(Frame *f, Point pt) +.PP +.B +Point frptofchar(Frame *f, ulong p) +.PP +.B +void frinsert(Frame *f, Rune *r0, Rune *r1, ulong p) +.PP +.B +int frdelete(Frame *f, ulong p0, ulong p1) +.PP +.B +void frselect(Frame *f, Mousectl *m) +.PP +.B +void frtick(Frame *f, Point pt, int up) +.PP +.B +void frselectpaint(Frame *f, Point p0, Point p1, Image *col) +.PP +.B +void frdrawsel(Frame *f, Point pt0, ulong p0, ulong p1, +.B + int highlighted) +.PP +.B +void frdrawsel0(Frame *f, Point pt0, ulong p0, ulong p1, +.B + Image *back, Image *text) +.PP +.ft L +enum{ + BACK, + HIGH, + BORD, + TEXT, + HTEXT, + NCOL +}; +.fi +.SH DESCRIPTION +This library supports +.I frames +of editable text in a single font on raster displays, such as in +.IR sam (1) +and +.IR rio (1). +Frames may hold any character except NUL (0). +Long lines are folded and tabs are at fixed intervals. +.PP +The user-visible data structure, a +.BR Frame , +is defined in +.BR : +.IP +.EX +.ta 6n +\w'Rectangle 'u +\w'lastlinefull; 'u +typedef struct Frame Frame; +struct Frame +{ + Font *font; /* of chars in the frame */ + Display *display; /* on which frame appears */ + Image *b; /* on which frame appears */ + Image *cols[NCOL]; /* text and background colors */ + Rectangle r; /* in which text appears */ + Rectangle entire; /* of full frame */ + Frbox *box; + ulong p0, p1; /* selection */ + ushort nbox, nalloc; + ushort maxtab; /* max size of tab, in pixels */ + ushort nchars; /* # runes in frame */ + ushort nlines; /* # lines with text */ + ushort maxlines; /* total # lines in frame */ + ushort lastlinefull; /* last line fills frame */ + ushort modified; /* changed since frselect() */ + Image *tick; /* typing tick */ + Image *tickback; /* saved image under tick */ + int ticked; /* flag: is tick onscreen? */ +}; +.EE +.PP +.B Frbox +is an internal type and is not used by the interface. +.B P0 +and +.B p1 +may be changed by the application provided the selection routines are called +afterwards to maintain a consistent display. +.I Maxtab +determines the size of tab stops. +.I Frinit +sets it to 8 times the width of a +.B 0 +(zero) +character in the font; +it may be changed before any text is added to the frame. +The other elements of the structure are maintained by the library and +should not be modified directly. +.PP +The text within frames +is not directly addressable; +instead frames are designed to work alongside +another structure that holds the text. +The typical application is to display a section of a longer document such +as a text file or terminal session. +Usually the program will keep its own copy of the +text in the window (probably as +an array of +.BR Runes ) +and pass components of this text to the frame routines to +display the visible portion. +Only the text that is visible is held by the +.BR Frame ; +the application must check +.BR maxlines , +.BR nlines , +and +.B lastlinefull +to determine, for example, whether new text needs to be appended +at the end of the +.B Frame +after calling +.I frdelete +(q.v.). +.PP +There are no routines in the library to allocate +.BR Frames ; +instead the interface assumes that +.B Frames +will be components of larger structures. +.I Frinit +prepares the +.B Frame +.I f +so characters drawn in it will appear +in the single +.B Font +.IR ft . +It then calls +.I frsetrects +and +.I frinittick +to initialize the geometry for the +.BR Frame . +The +.B Image +.I b +is where the +.B Frame +is to be drawn; +.B Rectangle +.I r +defines the limit of the portion of the +.B Image +the text will occupy. +The +.B Image +pointer +may be null, allowing the other routines to be called to maintain the +associated data structure in, for example, an obscured window. +.PP +The array of +.B Images +cols sets the colors in which text and borders will be drawn. The background of the frame will be drawn in +.BR cols[BACK] ; +the background of highlighted text in +.BR cols[HIGH] ; +borders and scroll bar in +.BR cols[BORD] ; +regular text in +.BR cols[TEXT] ; +and highlighted text in +.BR cols[HTEXT] . +.PP +.I Frclear +frees the internal structures associated with +.IR f , +permitting another +.I frinit +or +.I frsetrects +on the +.BR Frame . +It does not clear the associated display. +If +.I f +is to be deallocated, the associated +.B Font +and +.B Image +must be freed separately. +The +.B resize +argument should be non-zero if the frame is to be redrawn with +a different font; otherwise the frame will maintain some +data structures associated with the font. +.PP +To resize a +.BR Frame , +use +.I frclear +and +.I frinit +and then +.I frinsert +(q.v.) to recreate the display. +If a +.B Frame +is being moved but not resized, that is, if the shape of its containing +rectangle is unchanged, it is sufficient to use +.IR draw (2) +to copy the containing rectangle from the old to the new location and then call +.I frsetrects +to establish the new geometry. +(It is unnecessary to call +.I frinittick +unless the font size has changed.) +No redrawing is necessary. +.PP +.B Frames +hold text as runes, +not as bytes. +.I Frptofchar +returns the location of the upper left corner of the +.I p'th +rune, starting from 0, in the +.B Frame +.IR f . +If +.I f +holds fewer than +.I p +runes, +.I frptofchar +returns the location of the upper right corner of the last character in +.IR f . +.I Frcharofpt +is the inverse: it +returns the index of the closest rune whose image's upper left corner +is up and to the left of +.IR pt . +.PP +.I Frinsert +inserts into +.B Frame +.I f +starting at rune index +.I p +the runes between +.I r0 +and +.IR r1 . +If a NUL (0) character +is inserted, chaos will ensue. +Tabs and newlines +are handled by the library, but all other characters, +including control characters, are just displayed. +For example, backspaces are printed; to erase +a character, use +.IR frdelete . +.PP +.I Frdelete +deletes from the +.B Frame +the text between +.I p0 +and +.IR p1 ; +.I p1 +points at the first rune beyond the deletion. +.PP +.I Frselect +tracks the mouse to select a contiguous string of text in the +.BR Frame . +When called, a mouse button is typically down. +.I Frselect +will return when the button state has changed (some buttons may +still be down) and will set +.IB f ->p0 +and +.IB f ->p1 +to the selected range of text. +.PP +Programs that wish to manage the selection themselves have several routines to help. +They involve the maintenance of the `tick', the vertical line indicating a null selection +between characters, and the colored region representing a non-null selection. +.I Frtick +draws (if +.I up +is non-zero) or removes (if +.I up +is zero) the tick at the screen position indicated by +.IR pt . +.I Frdrawsel +repaints a section of the frame, delimited by character positions +.I p0 +and +.IR p1 , +either with plain background or +entirely highlighted, according to the flag +.IR highlighted , +managing the tick appropriately. +The point +.I pt0 +is the geometrical location of +.I p0 +on the screen; like all of the selection-helper routines' +.B Point +arguments, it must be a value generated by +.IR frptofchar . +.I Frdrawsel0 +is a lower-level routine, taking as arguments a background color, +.IR back , +and text color, +.IR text . +It assumes that the tick is being handled (removed beforehand, replaced afterwards, as required) +by its caller. +.I Frselectpaint +uses a solid color, +.IR col , +to paint a region of the frame defined by the +.B Points +.I p0 +and +.IR p1 . +.SH SOURCE +.B /sys/src/libframe +.SH SEE ALSO +.IR graphics (2), +.IR draw (2), +.IR cachechars (2). diff --git a/man/man3/genrandom.3 b/man/man3/genrandom.3 new file mode 100644 index 00000000..b4ce49af --- /dev/null +++ b/man/man3/genrandom.3 @@ -0,0 +1,44 @@ +.TH GENRANDOM 3 +.SH NAME +genrandom, prng \- random number generation +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void genrandom(uchar *buf, int nbytes) +.PP +.B +void prng(uchar *buf, int nbytes) +.SH DESCRIPTION +.PP +Most security software requires a source of random or, at the +very least, unguessable numbers. +.PP +.I Genrandom +fills a buffer with bytes from the X9.17 pseudo-random +number generator. The X9.17 generator is seeded by 24 +truly random bytes read from +.BR /dev/random . +.PP +.I Prng +uses the native +.IR rand (2) +pseudo-random number generator to fill the buffer. Used with +.IR srand , +this function can produce a reproducible stream of pseudo random +numbers useful in testing. +.PP +Both functions may be passed to +.I mprand +(see +.IR mp (2)). +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2) diff --git a/man/man3/getcallerpc.3 b/man/man3/getcallerpc.3 new file mode 100644 index 00000000..8fc86d8c --- /dev/null +++ b/man/man3/getcallerpc.3 @@ -0,0 +1,38 @@ +.TH GETCALLERPC 3 +.SH NAME +getcallerpc \- fetch return PC of current function +.SH SYNOPSIS +.br +.B #include +.br +.B #include +.PP +.B ulong getcallerpc(void *firstarg) +.SH DESCRIPTION +.I Getcallerpc +is a portable way to discover the PC to which the current function will return. +.I Firstarg +should be a pointer to the first argument to the function in question. +.SH EXAMPLE +.IP +.EX +void +printpc(ulong arg) +{ + print("Called from %.8lux\en", getcallerpc(&arg)); +} + +void +main(int argc, char *argv[]) +{ + printpc(0); + printpc(0); + printpc(0); +} +.EE +.SH SOURCE +.B /sys/src/libc/$objtype/getcallerpc.[cs] +.SH BUGS +The +.I firstarg +parameter should not be necessary. diff --git a/man/man3/getenv.3 b/man/man3/getenv.3 new file mode 100644 index 00000000..2d6b90c4 --- /dev/null +++ b/man/man3/getenv.3 @@ -0,0 +1,44 @@ +.TH GETENV 3 +.SH NAME +getenv, putenv \- access environment variables +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +char* getenv(char *name) +.br +.B +int putenv(char *name, char *val) +.fi +.SH DESCRIPTION +.I Getenv +reads the contents of +.BI /env/ name +(see +.IR env (3)) +into memory allocated with +.IR malloc (2), +0-terminates it, +and returns a pointer to that area. +If no file exists, 0 +is returned. +.PP +.I Putenv +creates the file +.BI /env/ name +and writes the string +.I val +to it. The terminating +.B 0 +is not written. +If the file value cannot be written, \-1 is returned. +.SH SOURCE +.B /sys/src/libc/9sys +.SH SEE ALSO +.IR env (3) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/man/man3/getfcr.3 b/man/man3/getfcr.3 new file mode 100644 index 00000000..42634634 --- /dev/null +++ b/man/man3/getfcr.3 @@ -0,0 +1,125 @@ +.TH GETFCR 3 +.SH NAME +getfcr, setfcr, getfsr, setfsr \- control floating point +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +ulong getfcr(void) +.PP +.B +void setfcr(ulong fcr) +.PP +.B +ulong getfsr(void) +.PP +.B +void setfsr(ulong fsr) +.SH DESCRIPTION +These routines provide a fairly portable interface to control the +rounding and exception characteristics of IEEE 754 floating point units. +In effect, they define a pair of pseudo-registers, the floating +point control register, +.BR fcr , +which affects rounding, precision, and exceptions, and the +floating point status register, +.BR fsr , +which holds the accrued exception bits. +Each register has a +.I get +routine to retrieve its value, a +.I set +routine to modify it, +and macros that identify its contents. +.PP +The +.B fcr +contains bits that, when set, halt execution upon exceptions: +.B FPINEX +(enable inexact exceptions), +.B FPOVFL +(enable overflow exceptions), +.B FPUNFL +(enable underflow exceptions), +.B FPZDIV +(enable zero divide exceptions), and +.B FPINVAL +(enable invalid operation exceptions). +Rounding is controlled by installing in +.BR fcr , +under mask +.BR FPRMASK , +one of the values +.B FPRNR +(round to nearest), +.B FPRZ +(round towards zero), +.B FPRPINF +(round towards positive infinity), and +.B FPRNINF +(round towards negative infinity). +Precision is controlled by installing in +.BR fcr , +under mask +.BR FPPMASK , +one of the values +.B FPPEXT +(extended precision), +.B FPPSGL +(single precision), and +.B FPPDBL +(double precision). +.PP +The +.B fsr +holds the accrued exception bits +.BR FPAINEX , +.BR FPAOVFL , +.BR FPAUNFL , +.BR FPAZDIV , +and +.BR FPAINVAL , +corresponding to the +.B fsr +bits without the +.B A +in the name. +.PP +Not all machines support all modes. If the corresponding mask +is zero, the machine does not support the rounding or precision modes. +On some machines it is not possible to clear selective accrued +exception bits; a +.I setfsr +clears them all. +The exception bits defined here work on all architectures. +By default, the initial state is equivalent to +.IP +.EX +setfcr(FPPDBL|FPRNR|FPINVAL|FPZDIV|FPOVFL); +.EE +.PP +The default state of the floating point unit is fixed for a given +architecture but is undefined across Plan 9: the default is +to provide what the hardware does most efficiently. +Use these routines +if you need guaranteed behavior. +Also, gradual underflow is not available on some machines. +.SH EXAMPLE +To enable overflow traps and make sure registers are rounded +to double precision (for example on the MC68020, where the +internal registers are 80 bits long): +.EX +.IP +.ft L +ulong fcr; +fcr = getfcr(); +fcr |= FPOVFL; +fcr &= ~FPPMASK; +fcr |= FPPDBL; +setfcr(fcr); +.ft +.EE +.SH SOURCE +.B /sys/src/libc/$objtype/getfcr.s diff --git a/man/man3/getfields.3 b/man/man3/getfields.3 new file mode 100644 index 00000000..f3612761 --- /dev/null +++ b/man/man3/getfields.3 @@ -0,0 +1,95 @@ +.TH GETFIELDS 3 +.SH NAME +getfields, gettokens, tokenize \- break a string into fields +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLchar* \fP'u +.B +int getfields(char *str, char **args, int maxargs, int multiflag, +.br +.B + char *delims) +.PP +.B +int gettokens(char *str, char **args, int maxargs, char *delims) +.PP +.B +int tokenize(char *str, char **args, int maxargs) +.SH DESCRIPTION +.I Getfields +places into the array +.I args +pointers to the first +.I maxargs +fields of the null terminated +.SM UTF +string +.IR str . +Delimiters between these fields are set to null. +.PP +Fields are substrings of +.I str +whose definition depends on the value of +.IR multiflag. +If +.I multiflag +is zero, +adjacent fields are separated by exactly one delimiter. +For example +.EX + + getfields("#alice#bob##charles###", arg, 3, 0, "#"); + +.EE +yields three substrings: +null-string , +.BR "alice" , +and +.BR "bob##charles###" . +If the +.I multiflag +argument is not zero, +a field is a non-empty string of non-delimiters. +For example +.EX + + getfields("#alice#bob##charles###", arg, 3, 1, "#"); + +.EE +yields the three substrings: +.BR "alice" , +.BR "bob" , +and +.BR "charles###" . +.PP +Getfields returns the number of fields pointed to. +.PP +.I Gettokens +is the same as +.I getfields +with +.I multiflag +non-zero, +except that fields may be quoted using single quotes, in the manner +of +.IR rc (1). +See +.IR quote (2) +for related quote-handling software. +.PP +.I Tokenize +is +.I gettokens +with +.I delims +set to \f5"\et\er\en "\fP. +.SH SOURCE +.B /sys/src/libc/port/tokenize.c +.SH SEE ALSO +.I strtok +in +.IR strcat (2), +.IR quote (2). diff --git a/man/man3/getpid.3 b/man/man3/getpid.3 new file mode 100644 index 00000000..c2075df0 --- /dev/null +++ b/man/man3/getpid.3 @@ -0,0 +1,41 @@ +.TH GETPID 3 +.SH NAME +getpid, getppid \- get process ids +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int getpid(void) +.PP +.B +int getppid(void) +.SH DESCRIPTION +.I Getpid +reads +.B /dev/pid +(see +.IR cons (3)) +and converts it to get the process id of the current process, +a number guaranteed to be unique among all running processes on the machine +executing +.IR getpid . +.PP +.I Getppid +reads +.B /dev/ppid +(see +.IR cons (3)) +and converts it to get the id of the parent of the current process. +.SH SOURCE +.B /sys/src/libc/9sys +.SH SEE ALSO +.IR intro (2), +.IR cons (3), +.IR proc (3) +.SH DIAGNOSTICS +Returns 0 and +sets +.I errstr +if unsuccessful. diff --git a/man/man3/getuser.3 b/man/man3/getuser.3 new file mode 100644 index 00000000..b98f76e0 --- /dev/null +++ b/man/man3/getuser.3 @@ -0,0 +1,37 @@ +.TH GETUSER 3 +.SH NAME +getuser, sysname \- get user or system name +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +char* getuser(void) +.PP +.B +char* sysname(void) +.SH DESCRIPTION +.I Getuser +returns a pointer to static data which contains the +null-terminated +name of the user who +owns the current process. +.I Getuser +reads +.B /dev/user +to find the name. +.PP +.I Sysname +provides the same service for the file +.BR #c/sysname , +which contains the name of the machine. +Unlike +.IR getuser , +.I sysname +caches the string, reading the file only once. +.SH SOURCE +.B /sys/src/libc/port/getuser.c +.SH SEE ALSO +.IR intro (2), +.IR cons (3) diff --git a/man/man3/getwd.3 b/man/man3/getwd.3 new file mode 100644 index 00000000..021e5cd9 --- /dev/null +++ b/man/man3/getwd.3 @@ -0,0 +1,37 @@ +.TH GETWD 3 +.SH NAME +getwd \- get current directory +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +char* getwd(char *buf, int size) +.SH DESCRIPTION +.I Getwd +fills +.I buf +with a null-terminated string representing the current directory +and returns +.IR buf . +.PP +.I Getwd +places no more than +.I size +bytes in the buffer provided. +.SH SOURCE +.B /sys/src/libc/9sys/getwd.c +.SH "SEE ALSO" +.IR pwd (1), +.IR fd2path (2) +.SH DIAGNOSTICS +On error, zero is returned. +.IR Errstr (2) +may be consulted for more information. +.SH BUGS +Although the name returned by +.I getwd +is guaranteed to be the path used to reach the directory, +if the name space has changed underfoot, the name may be +incorrect. diff --git a/man/man3/graphics.3 b/man/man3/graphics.3 new file mode 100644 index 00000000..f7f6a5a9 --- /dev/null +++ b/man/man3/graphics.3 @@ -0,0 +1,651 @@ +.TH GRAPHICS 3 +.SH NAME +Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth \- interactive graphics +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +#include +#include +.ft P +.PP +.ta \w'\fLFont* 'u +.B +int initdraw(void (*errfun)(Display*, char*), char *font, +.B + char *label) +.PP +.B +int geninitdraw(char *devdir, void(*errfun)(Display*, char*), +.PP +.B + char *font, char *label, char *mousedir, char *windir, +.B + int ref) +.PP +.B +int newwindow(char *str) +.PP +.B +void drawerror(Display *d, char *msg) +.PP +.B +Display* initdisplay(char *devdir, char *win, void(*errfun)(Display*, char*)) +.PP +.B +void closedisplay(Display *d) +.PP +.B +Font* getdefont(Display *d) +.PP +.B +int flushimage(Display *d, int vis) +.PP +.B +int bufimage(Display *d, int n) +.PP +.B +int lockdisplay(Display *d) +.PP +.B +int unlockdisplay(Display *d) +.PP +.B +int getwindow(Display *d, int ref) +.PP +.B +int gengetwindow(Display *d, char *winname, +.br +.B + Image **ip, Screen **sp, int ref) +.PP +.B +void cursorswitch(Cursor *curs) +.PP +.B +void cursorset(Point p) +.PP +.B +Font* openfont(Display *d, char *name) +.PP +.B +Font* buildfont(Display *d, char *desc, char *name) +.PP +.B +void freefont(Font *f) +.PP +.B +int Pfmt(Fmt*) +.PP +.B +int Rfmt(Fmt*) +.PP +.B +ulong strtochan(char *s) +.PP +.B +char* chantostr(char *s, ulong chan) +.PP +.B +int chantodepth(ulong chan) +.PP +.B +extern Display *display +.PP +.B +extern Image *screen +.PP +.B +extern Screen *_screen +.PP +.B +extern Font *font +.fi +.SH DESCRIPTION +A +.B Display +structure represents a connection to the graphics device, +.IR draw (3), +holding all graphics resources associated with the connection, +including in particular raster image data in use by the client program. +The structure is defined (in part) as: +.IP +.EX +.ta 6n +10n +typedef +struct Display +{ + ... + void (*error)(Display*, char*); + ... + Image *black; + Image *white; + Image *opaque; + Image *transparent; + Image *image; + Font *defaultfont; + Subfont *defaultsubfont; + ... +}; +.EE +.PP +A +.B Point +is a location in an Image +(see below and +.IR draw (2)), +such as the display, and is defined as: +.IP +.EX +.ta 6n +typedef +struct Point { + int x; + int y; +} Point; +.EE +.PP +The coordinate system has +.I x +increasing to the right and +.I y +increasing down. +.PP +A +.B Rectangle +is a rectangular area in an image. +.IP +.EX +.ta 6n +typedef +struct Rectangle { + Point min; /* upper left */ + Point max; /* lower right */ +} Rectangle; +.EE +.PP +By definition, +.BR min.x ≤ max.x +and +.BR min.y ≤ max.y . +By convention, the right (maximum +.IR x ) +and bottom (maximum +.IR y ) +edges are +excluded from the represented rectangle, so abutting rectangles have no +points in common. +Thus, +.B max +contains the coordinates of the first point beyond the rectangle. +.PP +The +.B Image +data structure is defined in +.IR draw (2). +.PP +A +.B Font +is a set of character images, indexed by runes (see +.IR utf (6)). +The images are organized into +.BR Subfonts , +each containing the images for a small, contiguous set of runes. +The detailed format of these data structures, +which are described in detail in +.IR cachechars (2), +is immaterial for most applications. +.B Font +and +.B Subfont +structures contain two interrelated fields: +.LR ascent , +the distance from the top of the highest character +(actually the top of the image holding all the characters) +to the baseline, +and +.LR height , +the distance from the top of the highest character to the bottom of +the lowest character (and hence, the interline spacing). +See +.IR cachechars (2) +for more details. +.PP +.I Buildfont +parses the font description in the buffer +.BR desc , +returning a +.B Font* +pointer that can be used by +.B string +(see +.IR draw (2)) +to draw characters from the font. +.I Openfont +does the same, but reads the description +from the named file. +.I Freefont +frees a font. +The convention for naming font files is: +.IP +.B /lib/font/bit/\fIname\fP/\fIrange\fP.\fIsize\fP.font +.PD +.PP +where +.I size +is approximately the height in pixels of the lower case letters +(without ascenders or descenders). +.I Range +gives some indication of which characters will be available: for example +.BR ascii , +.BR latin1 , +.BR euro , +or +.BR unicode . +.B Euro +includes most European languages, punctuation marks, the International Phonetic +Alphabet, etc., but no Oriental languages. +.B Unicode +includes every character for which appropriate-sized images exist on the system. +.PP +A +.I Cursor +is defined: +.IP +.EX +.ta 6n +\w'Point 'u +typedef struct +Cursor { + Point offset; + uchar clr[2*16]; + uchar set[2*16]; +} Cursor; +.EE +.PP +The arrays are arranged in rows, two bytes per row, left to +right in big-endian order to give 16 rows +of 16 bits each. +A cursor is displayed on the screen by adding +.B offset +to the current mouse position, using +.B clr +as a mask to draw white at the pixels where +.B clr +is one, and then drawing black at the pixels where +.B set +is one. +.PP +The routine +.I initdraw +connects to the display; it returns \-1 if it fails and sets the error string. +.I Initdraw +sets up the global variables +.B display +(the +.B Display +structure representing the connection), +.B screen +(an +.B Image +representing the display memory itself or, if +.IR rio (1) +is running, the client's window), +and +.B font +(the default font for text). +The arguments to +.I initdraw +include a +.IR label , +which is written to +.B /dev/label +if non-nil +so that it can be used to identify the window when hidden (see +.IR rio (1)). +The font is created by reading the named +.I font +file. If +.B font +is null, +.I initdraw +reads the file named in the environment variable +.BR $font ; +if +.B $font +is not set, it imports the default (usually minimal) +font from the operating system. +The global +.I font +will be set to point to the resulting +.B Font +structure. +The +.I errfun +argument is a +.I graphics error function +to call in the event of a fatal error in the library; it must never return. +Its arguments are the +display pointer and an error string. +If +.I errfun +is nil, the library provides a default, called +.IR drawerror . +Another effect of +.I initdraw +is that it installs +.IR print (2) +formats +.I Pfmt +and +.I Rfmt +as +.L %P +and +.L %R +for printing +.B Points +and +.BR Rectangles . +.PP +The +.I geninitdraw +function provides a less automated way to establish a connection, for programs +that wish to connect to multiple displays. +.I Devdir +is the name of the directory containing the device files for the display +(if nil, default +.BR /dev ); +.IR errfun , +.IR font , +and +.I label +are as in +.IR initdraw ; +.I mousedir +and +.I windir +are the directories holding the +.B mouse +and +.B winname +files; and +.I ref +specifies the refresh function to be used to create the window, if running under +.IR rio (1) +(see +.IR window (2)). +.PP +The function +.I newwindow +may be called before +.I initdraw +or +.IR geninitdraw +to cause the program to occupy a newly created window rather than take over the one in +which it is running when it starts. +The +.I str +argument, if non-null, is concatenated to the string \f5\&"new\ "\fP +that is used to create the window (see +.IR rio (4)). +For example, +.B newwindow("-hide -dy 100") +will cause the program to run in a newly created, hidden window +100 pixels high. +.PP +.I Initdisplay +is part of +.IR geninitdraw ; +it sets up the display structures but does not allocate any fonts or call +.IR getwindow . +The arguments are similar to those of +.IR initdraw ; +.I win +names the directory, default +.BR /dev , +in which the files associated with the window reside. +.I Closedisplay +disconnects the display and frees the associated data structures. +.I Getdefont +builds a +.B Font +structure from in-core data describing a default font. +None of these routines is needed by most programs, since +.I initdraw +calls them as needed. +.PP +The data structures associated with the display must be protected in a multi-process program, +because they assume only one process will be using them at a time. +Multi-process programs should set +.B display->locking +to +.BR 1 , +to notify the library to use a locking protocol for its own accesses, +and call +.I lockdisplay +and +.I unlockdisplay +around any calls to the graphics library that will cause messages to be sent to the display device. +.I Initdraw +and +.I geninitdraw +initialize the display to the locked state. +.PP +.I Getwindow +returns a pointer to the window associated with the application; it is called +automatically by +.I initdraw +to establish the +.B screen +pointer but must be called after each resizing of the window to restore +the library's connection to the window. +If +.B rio +is not running, it returns +.BR display->image ; +otherwise it negotiates with +.B rio +by looking in +.B /dev/winname +to find the name of the window and opening it using +.B namedimage +(see +.IR allocimage (2)). +The resulting window will be created using the refresh method +.I ref +(see +.IR window (2)); +this should almost always be +.B Refnone +because +.B rio +provides backing store for the window. +.PP +.I Getwindow +overwrites the global variables +.BR screen , +a pointer to the +.B Image +defining the window (or the overall display, if no window system is running); and +.BR _screen , +a pointer to the +.B Screen +representing the root of the window's hierarchy. (See +.IR window (2). +The overloading of the +.B screen +word is an unfortunate historical accident.) +.I Getwindow +arranges that +.B screen +point to the portion of the window inside the border; +sophisticated clients may use +.B _screen +to make further subwindows. +Programs desiring multiple independent windows +may use the mechanisms of +.IR rio (4) +to create more windows (usually by a fresh mount of the window sytem +in a directory other than +.BR /dev ), +then use +.I gengetwindow +to connect to them. +.IR Gengetwindow 's +extra arguments are the full path of the window's +.B winname +file and pointers to be overwritten with the values of the `global' +.B Image +and +.B Screen +variables for the new window. +.PP +The mouse cursor is always displayed. +The initial cursor is an arrow. +.I Cursorswitch +causes the argument cursor to be displayed instead. +A zero argument causes a switch back to the arrow cursor. +.I Cursorset +moves the mouse cursor to position +.IR p , +provided (if in a window) that the requesting program is +executing in the current window and the mouse is within +the window boundaries; otherwise +.I cursorset +is a no-op. +.PP +The graphics functions described in +.IR draw (2), +.IR allocimage (2), +.IR cachechars (2), +and +.IR subfont (2) +are implemented by writing commands to files under +.B /dev/draw +(see +.IR draw (3)); +the writes are buffered, so the functions may not take effect immediately. +.I Flushimage +flushes the buffer, doing all pending graphics operations. +If +.I vis +is non-zero, any changes are also copied from the `soft screen' (if any) in the +driver to the visible frame buffer. +The various allocation routines in the library flush automatically, as does the event +package (see +.IR event (2)); +most programs do not need to call +.IR flushimage . +It returns \-1 on error. +.PP +.I Bufimage +is used to allocate space for +.I n +bytes in the display buffer. +It is used by all the graphics routines to send messages to the display. +.PP +The functions +.I strtochan +and +.I chantostr +convert between the channel descriptor strings +used by +.IR image (6) +and the internal +.B ulong +representation +used by the graphics protocol +(see +.IR draw (3)'s +.B b +message). +.B Chantostr +writes at most nine bytes into the buffer pointed at by +.I s +and returns +.I s +on success, +0 +on failure. +.B Chantodepth +returns the number of bits per pixel used by the +format specified by +.IR chan . +Both +.B chantodepth +and +.B strtochan +return 0 when presented +with bad input. +.SH EXAMPLES +To reconnect to the window after a resize event, +.IP +.EX +if(getwindow(display, Refnone) < 0) + sysfatal("resize failed: %r"); +.EE +.PP +To create and set up a new +.IR rio (1) +window, +.IP +.EX +Image *screen2; +Screen *_screen2; + +srvwsys = getenv("wsys"); +if(srvwsys == nil) + sysfatal("can't find $wsys: %r"); +rfork(RFNAMEG); /* keep mount of rio private */ + +fd = open(srvwsys, ORDWR); +if(fd < 0) + sysfatal("can't open $wsys: %r"); + +/* mount creates window; see \f2rio\fP(4) */ +if(mount(fd, -1, "/tmp", MREPL, "new -dx 300-dy 200") < 0) + sysfatal("can't mount new window: %r"); +if(gengetwindow(display, "/tmp/winname", + &screen2, &_screen2, Refnone) < 0) + sysfatal("resize failed: %r"); + +/* now open /tmp/cons, /tmp/mouse */ +\&... +.EE +.SH FILES +.BR /lib/font/bit " directory of fonts +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR rio (1), +.IR addpt (2), +.IR allocimage (2), +.IR cachechars (2), +.IR subfont (2), +.IR draw (2), +.IR event (2), +.IR frame (2), +.IR print (2), +.IR window (2), +.IR draw (3), +.IR rio (4), +.IR image (6), +.IR font (6) +.SH DIAGNOSTICS +An error function may call +.IR errstr (2) +for further diagnostics. +.SH BUGS +The names +.B clr +and +.B set +in the +.B Cursor +structure are reminders of an archaic color map +and might be more appropriately called +.B white +and +.BR black . diff --git a/man/man3/html.3 b/man/man3/html.3 new file mode 100644 index 00000000..8de7b121 --- /dev/null +++ b/man/man3/html.3 @@ -0,0 +1,1420 @@ +.TH HTML 3 +.SH NAME +parsehtml, +printitems, +validitems, +freeitems, +freedocinfo, +dimenkind, +dimenspec, +targetid, +targetname, +fromStr, +toStr +\- HTML parser +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +#include +.ft P +.PP +.ta \w'\fLToken* 'u +.B +Item* parsehtml(uchar* data, int datalen, Rune* src, int mtype, +.B + int chset, Docinfo** pdi) +.PP +.B +void printitems(Item* items, char* msg) +.PP +.B +int validitems(Item* items) +.PP +.B +void freeitems(Item* items) +.PP +.B +void freedocinfo(Docinfo* d) +.PP +.B +int dimenkind(Dimen d) +.PP +.B +int dimenspec(Dimen d) +.PP +.B +int targetid(Rune* s) +.PP +.B +Rune* targetname(int targid) +.PP +.B +uchar* fromStr(Rune* buf, int n, int chset) +.PP +.B +Rune* toStr(uchar* buf, int n, int chset) +.SH DESCRIPTION +.PP +This library implements a parser for HTML 4.0 documents. +The parsed HTML is converted into an intermediate representation that +describes how the formatted HTML should be laid out. +.PP +.I Parsehtml +parses an entire HTML document contained in the buffer +.I data +and having length +.IR datalen . +The URL of the document should be passed in as +.IR src . +.I Mtype +is the media type of the document, which should be either +.B TextHtml +or +.BR TextPlain . +The character set of the document is described in +.IR chset , +which can be one of +.BR US_Ascii , +.BR ISO_8859_1 , +.B UTF_8 +or +.BR Unicode . +The return value is a linked list of +.B Item +structures, described in detail below. +As a side effect, +.BI * pdi +is set to point to a newly created +.B Docinfo +structure, containing information pertaining to the entire document. +.PP +The library expects two allocation routines to be provided by the +caller, +.B emalloc +and +.BR erealloc . +These routines are analogous to the standard malloc and realloc routines, +except that they should not return if the memory allocation fails. +In addition, +.B emalloc +is required to zero the memory. +.PP +For debugging purposes, +.I printitems +may be called to display the contents of an item list; individual items may +be printed using the +.B %I +print verb, installed on the first call to +.IR parsehtml . +.I validitems +traverses the item list, checking that all of the pointers are valid. +It returns +.B 1 +is everything is ok, and +.B 0 +if an error was found. +Normally, one would not call these routines directly. +Instead, one sets the global variable +.I dbgbuild +and the library calls them automatically. +One can also set +.IR warn , +to cause the library to print a warning whenever it finds a problem with the +input document, and +.IR dbglex , +to print debugging information in the lexer. +.PP +When an item list is finished with, it should be freed with +.IR freeitems . +Then, +.I freedocinfo +should be called on the pointer returned in +.BI * pdi\f1. +.PP +.I Dimenkind +and +.I dimenspec +are provided to interpret the +.B Dimen +type, as described in the section +.IR "Dimension Specifications" . +.PP +Frame target names are mapped to integer ids via a global, permanent mapping. +To find the value for a given name, call +.IR targetid , +which allocates a new id if the name hasn't been seen before. +The name of a given, known id may be retrieved using +.IR targetname . +The library predefines +.BR FTtop , +.BR FTself , +.B FTparent +and +.BR FTblank . +.PP +The library handles all text as Unicode strings (type +.BR Rune* ). +Character set conversion is provided by +.I fromStr +and +.IR toStr . +.I FromStr +takes +.I n +Unicode characters from +.I buf +and converts them to the character set described by +.IR chset . +.I ToStr +takes +.I n +bytes from +.IR buf , +interpretted as belonging to character set +.IR chset , +and converts them to a Unicode string. +Both routines null-terminate the result, and use +.B emalloc +to allocate space for it. +.SS Items +The return value of +.I parsehtml +is a linked list of variant structures, +with the generic portion described by the following definition: +.PP +.EX +.ta 6n +\w'Genattr* 'u +typedef struct Item Item; +struct Item +{ + Item* next; + int width; + int height; + int ascent; + int anchorid; + int state; + Genattr* genattr; + int tag; +}; +.EE +.PP +The field +.B next +points to the successor in the linked list of items, while +.BR width , +.BR height , +and +.B ascent +are intended for use by the caller as part of the layout process. +.BR Anchorid , +if non-zero, gives the integer id assigned by the parser to the anchor that +this item is in (see section +.IR Anchors ). +.B State +is a collection of flags and values described as follows: +.PP +.EX +.ta 6n +\w'IFindentshift = 'u +enum +{ + IFbrk = 0x80000000, + IFbrksp = 0x40000000, + IFnobrk = 0x20000000, + IFcleft = 0x10000000, + IFcright = 0x08000000, + IFwrap = 0x04000000, + IFhang = 0x02000000, + IFrjust = 0x01000000, + IFcjust = 0x00800000, + IFsmap = 0x00400000, + IFindentshift = 8, + IFindentmask = (255< +element. +.B Background +is as described in the section +.IR "Background Specifications" , +and +.B backgrounditem +is set to be an image item for the document's background image (if given as a URL), +or else nil. +.B Text +gives the default foregound text color of the document, +.B link +the unvisited hyperlink color, +.B vlink +the visited hyperlink color, and +.B alink +the color for highlighting hyperlinks (all in 24-bit RGB format). +.B Target +is the default target frame id. +.B Chset +and +.B mediatype +are as for the +.I chset +and +.I mtype +parameters to +.IR parsehtml . +.B Scripttype +is the type of any scripts contained in the document, and is always +.BR TextJavascript . +.B Hasscripts +is set if the document contains any scripts. +Scripting is currently unsupported. +.B Refresh +is the contents of a +.B "" +tag, if any. +.B Kidinfo +is set if this document is a frameset (see section +.IR Frames ). +.B Frameid +is this document's frame id. +.PP +.B Anchors +is a list of hyperlinks contained in the document, +and +.B dests +is a list of hyperlink destinations within the page (see the following section for details). +.BR Forms , +.B tables +and +.B maps +are lists of the various forms, tables and client-side maps contained +in the document, as described in subsequent sections. +.B Images +is a list of all the image items in the document. +.SS Anchors +.PP +The library builds two lists for all of the +.B +elements (anchors) in a document. +Each anchor is assigned a unique anchor id within the document. +For anchors which are hyperlinks (the +.B href +attribute was supplied), the following structure is defined: +.PP +.EX +.ta 6n +\w'Anchor* 'u +typedef struct Anchor Anchor; +struct Anchor +{ + Anchor* next; + int index; + Rune* name; + Rune* href; + int target; +}; +.EE +.PP +.B Next +points to the next anchor in the list (the head of this list is +.BR Docinfo.anchors ). +.B Index +is the anchor id; each item within this hyperlink is tagged with this value +in its +.B anchorid +field. +.B Name +and +.B href +are the values of the correspondingly named attributes of the anchor +(in particular, href is the URL to go to). +.B Target +is the value of the target attribute (if provided) converted to a frame id. +.PP +Destinations within the document (anchors with the name attribute set) +are held in the +.B Docinfo.dests +list, using the following structure: +.PP +.EX +.ta 6n +\w'DestAnchor* 'u +typedef struct DestAnchor DestAnchor; +struct DestAnchor +{ + DestAnchor* next; + int index; + Rune* name; + Item* item; +}; +.EE +.PP +.B Next +is the next element of the list, +.B index +is the anchor id, +.B name +is the value of the name attribute, and +.B item +is points to the item within the parsed document that should be considered +to be the destination. +.SS Forms +.PP +Any forms within a document are kept in a list, headed by +.BR Docinfo.forms . +The elements of this list are as follows: +.PP +.EX +.ta 6n +\w'Formfield* 'u +typedef struct Form Form; +struct Form +{ + Form* next; + int formid; + Rune* name; + Rune* action; + int target; + int method; + int nfields; + Formfield* fields; +}; +.EE +.PP +.B Next +points to the next form in the list. +.B Formid +is a serial number for the form within the document. +.B Name +is the value of the form's name or id attribute. +.B Action +is the value of any action attribute. +.B Target +is the value of the target attribute (if any) converted to a frame target id. +.B Method +is one of +.B HGet +or +.BR HPost . +.B Nfields +is the number of fields in the form, and +.B fields +is a linked list of the actual fields. +.PP +The individual fields in a form are described by the following structure: +.PP +.EX +.ta 6n +\w'Formfield* 'u +typedef struct Formfield Formfield; +struct Formfield +{ + Formfield* next; + int ftype; + int fieldid; + Form* form; + Rune* name; + Rune* value; + int size; + int maxlength; + int rows; + int cols; + uchar flags; + Option* options; + Item* image; + int ctlid; + SEvent* events; +}; +.EE +.PP +Here, +.B next +points to the next field in the list. +.B Ftype +is the type of the field, which can be one of +.BR Ftext , +.BR Fpassword , +.BR Fcheckbox , +.BR Fradio , +.BR Fsubmit , +.BR Fhidden , +.BR Fimage , +.BR Freset , +.BR Ffile , +.BR Fbutton , +.B Fselect +or +.BR Ftextarea . +.B Fieldid +is a serial number for the field within the form. +.B Form +points back to the form containing this field. +.BR Name , +.BR value , +.BR size , +.BR maxlength , +.B rows +and +.B cols +each contain the values of corresponding attributes of the field, if present. +.B Flags +contains per-field flags, of which +.B FFchecked +and +.B FFmultiple +are defined. +.B Image +is only used for fields of type +.BR Fimage ; +it points to an image item containing the image to be displayed. +.B Ctlid +is reserved for use by the caller, typically to store a unique id +of an associated control used to implement the field. +.B Events +is the same as the corresponding field of the generic attributes +associated with the item containing this field. +.B Options +is only used by fields of type +.BR Fselect ; +it consists of a list of possible options that may be selected for that +field, using the following structure: +.PP +.EX +.ta 6n +\w'Option* 'u +typedef struct Option Option; +struct Option +{ + Option* next; + int selected; + Rune* value; + Rune* display; +}; +.EE +.PP +.B Next +points to the next element of the list. +.B Selected +is set if this option is to be displayed initially. +.B Value +is the value to send when the form is submitted if this option is selected. +.B Display +is the string to display on the screen for this option. +.SS Tables +.PP +The library builds a list of all the tables in the document, +headed by +.BR Docinfo.tables . +Each element of this list has the following format: +.PP +.EX +.ta 6n +\w'Tablecell*** 'u +typedef struct Table Table; +struct Table +{ + Table* next; + int tableid; + Tablerow* rows; + int nrow; + Tablecol* cols; + int ncol; + Tablecell* cells; + int ncell; + Tablecell*** grid; + Align align; + Dimen width; + int border; + int cellspacing; + int cellpadding; + Background background; + Item* caption; + uchar caption_place; + Lay* caption_lay; + int totw; + int toth; + int caph; + int availw; + Token* tabletok; + uchar flags; +}; +.EE +.PP +.B Next +points to the next element in the list of tables. +.B Tableid +is a serial number for the table within the document. +.B Rows +is an array of row specifications (described below) and +.B nrow +is the number of elements in this array. +Similarly, +.B cols +is an array of column specifications, and +.B ncol +the size of this array. +.B Cells +is a list of all cells within the table (structure described below) +and +.B ncell +is the number of elements in this list. +Note that a cell may span multiple rows and/or columns, thus +.B ncell +may be smaller than +.BR nrow*ncol . +.B Grid +is a two-dimensional array of cells within the table; the cell +at row +.B i +and column +.B j +is +.BR Table.grid[i][j] . +A cell that spans multiple rows and/or columns will +be referenced by +.B grid +multiple times, however it will only occur once in +.BR cells . +.B Align +gives the alignment specification for the entire table, +and +.B width +gives the requested width as a dimension specification. +.BR Border , +.B cellspacing +and +.B cellpadding +give the values of the corresponding attributes for the table, +and +.B background +gives the requested background for the table. +.B Caption +is a linked list of items to be displayed as the caption of the +table, either above or below depending on whether +.B caption_place +is +.B ALtop +or +.BR ALbottom . +Most of the remaining fields are reserved for use by the caller, +except +.BR tabletok , +which is reserved for internal use. +The type +.B Lay +is not defined by the library; the caller can provide its +own definition. +.PP +The +.B Tablecol +structure is defined for use by the caller. +The library ensures that the correct number of these +is allocated, but leaves them blank. +The fields are as follows: +.PP +.EX +.ta 6n +\w'Point 'u +typedef struct Tablecol Tablecol; +struct Tablecol +{ + int width; + Align align; + Point pos; +}; +.EE +.PP +The rows in the table are specified as follows: +.PP +.EX +.ta 6n +\w'Background 'u +typedef struct Tablerow Tablerow; +struct Tablerow +{ + Tablerow* next; + Tablecell* cells; + int height; + int ascent; + Align align; + Background background; + Point pos; + uchar flags; +}; +.EE +.PP +.B Next +is only used during parsing; it should be ignored by the caller. +.B Cells +provides a list of all the cells in a row, linked through their +.B nextinrow +fields (see below). +.BR Height , +.B ascent +and +.B pos +are reserved for use by the caller. +.B Align +is the alignment specification for the row, and +.B background +is the background to use, if specified. +.B Flags +is used by the parser; ignore this field. +.PP +The individual cells of the table are described as follows: +.PP +.EX +.ta 6n +\w'Background 'u +typedef struct Tablecell Tablecell; +struct Tablecell +{ + Tablecell* next; + Tablecell* nextinrow; + int cellid; + Item* content; + Lay* lay; + int rowspan; + int colspan; + Align align; + uchar flags; + Dimen wspec; + int hspec; + Background background; + int minw; + int maxw; + int ascent; + int row; + int col; + Point pos; +}; +.EE +.PP +.B Next +is used to link together the list of all cells within a table +.RB ( Table.cells ), +whereas +.B nextinrow +is used to link together all the cells within a single row +.RB ( Tablerow.cells ). +.B Cellid +provides a serial number for the cell within the table. +.B Content +is a linked list of the items to be laid out within the cell. +.B Lay +is reserved for the user to describe how these items have +been laid out. +.B Rowspan +and +.B colspan +are the number of rows and columns spanned by this cell, +respectively. +.B Align +is the alignment specification for the cell. +.B Flags +is some combination of +.BR TFparsing , +.B TFnowrap +and +.B TFisth +or'd together. +Here +.B TFparsing +is used internally by the parser, and should be ignored. +.B TFnowrap +means that the contents of the cell should not be +wrapped if they don't fit the available width, +rather, the table should be expanded if need be +(this is set when the nowrap attribute is supplied). +.B TFisth +means that the cell was created by the +.B +element (rather than the +.B +element), +indicating that it is a header cell rather than a data cell. +.B Wspec +provides a suggested width as a dimension specification, +and +.B hspec +provides a suggested height in pixels. +.B Background +gives a background specification for the individual cell. +.BR Minw , +.BR maxw , +.B ascent +and +.B pos +are reserved for use by the caller during layout. +.B Row +and +.B col +give the indices of the row and column of the top left-hand +corner of the cell within the table grid. +.SS Client-side Maps +.PP +The library builds a list of client-side maps, headed by +.BR Docinfo.maps , +and having the following structure: +.PP +.EX +.ta 6n +\w'Rune* 'u +typedef struct Map Map; +struct Map +{ + Map* next; + Rune* name; + Area* areas; +}; +.EE +.PP +.B Next +points to the next element in the list, +.B name +is the name of the map (use to bind it to an image), and +.B areas +is a list of the areas within the image that comprise the map, +using the following structure: +.PP +.EX +.ta 6n +\w'Dimen* 'u +typedef struct Area Area; +struct Area +{ + Area* next; + int shape; + Rune* href; + int target; + Dimen* coords; + int ncoords; +}; +.EE +.PP +.B Next +points to the next element in the map's list of areas. +.B Shape +describes the shape of the area, and is one of +.BR SHrect , +.B SHcircle +or +.BR SHpoly . +.B Href +is the URL associated with this area in its role as +a hypertext link, and +.B target +is the target frame it should be loaded in. +.B Coords +is an array of coordinates for the shape, and +.B ncoords +is the size of this array (number of elements). +.SS Frames +.PP +If the +.B Docinfo.kidinfo +field is set, the document is a frameset. +In this case, it is typical for +.I parsehtml +to return nil, as a document which is a frameset should have no actual +items that need to be laid out (such will appear only in subsidiary documents). +It is possible that items will be returned by a malformed document; the caller +should check for this and free any such items. +.PP +The +.B Kidinfo +structure itself reflects the fact that framesets can be nested within a document. +If is defined as follows: +.PP +.EX +.ta 6n +\w'Kidinfo* 'u +typedef struct Kidinfo Kidinfo; +struct Kidinfo +{ + Kidinfo* next; + int isframeset; + + // fields for "frame" + Rune* src; + Rune* name; + int marginw; + int marginh; + int framebd; + int flags; + + // fields for "frameset" + Dimen* rows; + int nrows; + Dimen* cols; + int ncols; + Kidinfo* kidinfos; + Kidinfo* nextframeset; +}; +.EE +.PP +.B Next +is only used if this structure is part of a containing frameset; it points to the next +element in the list of children of that frameset. +.B Isframeset +is set when this structure represents a frameset; if clear, it is an individual frame. +.PP +Some fields are used only for framesets. +.B Rows +is an array of dimension specifications for rows in the frameset, and +.B nrows +is the length of this array. +.B Cols +is the corresponding array for columns, of length +.BR ncols . +.B Kidinfos +points to a list of components contained within this frameset, each +of which may be a frameset or a frame. +.B Nextframeset +is only used during parsing, and should be ignored. +.PP +The remaining fields are used if the structure describes a frame, not a frameset. +.B Src +provides the URL for the document that should be initially loaded into this frame. +Note that this may be a relative URL, in which case it should be interpretted +using the containing document's URL as the base. +.B Name +gives the name of the frame, typically supplied via a name attribute in the HTML. +If no name was given, the library allocates one. +.BR Marginw , +.B marginh +and +.B framebd +are the values of the marginwidth, marginheight and frameborder attributes, respectively. +.B Flags +can contain some combination of the following: +.B FRnoresize +(the frame had the noresize attribute set, and the user should not be allowed to resize it), +.B FRnoscroll +(the frame should not have any scroll bars), +.B FRhscroll +(the frame should have a horizontal scroll bar), +.B FRvscroll +(the frame should have a vertical scroll bar), +.B FRhscrollauto +(the frame should be automatically given a horizontal scroll bar if its contents +would not otherwise fit), and +.B FRvscrollauto +(the frame gets a vertical scrollbar only if required). +.SH SOURCE +.B /sys/src/libhtml +.SH SEE ALSO +.IR fmt (1) +.PP +W3C World Wide Web Consortium, +``HTML 4.01 Specification''. +.SH BUGS +The entire HTML document must be loaded into memory before +any of it can be parsed. diff --git a/man/man3/hypot.3 b/man/man3/hypot.3 new file mode 100644 index 00000000..f8a3062c --- /dev/null +++ b/man/man3/hypot.3 @@ -0,0 +1,21 @@ +.TH HYPOT 3 +.SH NAME +hypot \- Euclidean distance +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +double hypot(double x, double y) +.fi +.SH DESCRIPTION +.I Hypot +returns +.EX + sqrt(x*x + y*y) +.EE +taking precautions against unwarranted overflows. +.SH SOURCE +.B /sys/src/libc/port/hypot.c diff --git a/man/man3/intmap.3 b/man/man3/intmap.3 new file mode 100644 index 00000000..bc43a71a --- /dev/null +++ b/man/man3/intmap.3 @@ -0,0 +1,126 @@ +.TH INTMAP 3 +.SH NAME +Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey, +deletekey \- integer to data structure maps +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fLIntmap* 'u +Intmap* allocmap(void (*inc)(void*)) +void freemap(Intmap *map, void (*dec)(void*)) +void* lookupkey(Intmap *map, ulong key) +void* insertkey(Intmap *map, ulong key, void *val) +int caninsertkey(Intmap *map, ulong key, void *val) +void* lookupkey(Intmap *map, ulong key) +void* deletekey(Intmap *map, ulong key) +.fi +.SH DESCRIPTION +An +.B Intmap +is an arbitrary mapping from integers to pointers. +.I Allocmap +creates a new map, and +.I freemap +destroys it. +The +.I inc +function is called each time a new pointer is added +to the map; similarly, +.I dec +is called on each pointer left in the map +when it is being freed. +Typically these functions maintain reference counts. +New entries are added to the map by calling +.IR insertkey , +which will return the previous value +associated with the given +.IR key , +or zero if there was no previous value. +.I Caninsertkey +is like +.I insertkey +but only inserts +.I val +if there is no current mapping. +It returns 1 if +.I val +was inserted, 0 otherwise. +.I Lookupkey +returns the pointer associated with +.IR key , +or zero if there is no such pointer. +.I Deletekey +removes the entry for +.I id +from the map, returning the +associated pointer, if any. +.PP +Concurrent access to +.BR Intmap s +is safe, +moderated via a +.B QLock +stored in the +.B Intmap +structure. +.PP +In anticipation of the storage of reference-counted +structures, an increment function +.I inc +may be specified +at map creation time. +.I Lookupkey +calls +.I inc +(if non-zero) +on pointers before returning them. +If the reference count adjustments were +left to the caller (and thus not protected by the lock), +it would be possible to accidentally reclaim a structure +if, for example, it was deleted from the map and its +reference count decremented between the return +of +.I insertkey +and the external increment. +.IR Insertkey +and +.IR caninsertkey +do +.I not +call +.I inc +when inserting +.I val +into the map, nor do +.I insertkey +or +.I deletekey +call +.I inc +when returning old map entries. +The rationale is that calling +an insertion function transfers responsibility for the reference +to the map, and responsibility is given back via the return value of +.I deletekey +or the next +.IR insertkey . +.PP +.BR Intmap s +are used by the 9P library to implement +.BR Fidpool s +and +.BR Reqpool s. +.SH SOURCE +.B /sys/src/lib9p/intmap.c +.SH SEE ALSO +.IR 9p (2), +.IR 9pfid (2). diff --git a/man/man3/ioproc.3 b/man/man3/ioproc.3 index 1cada2de..b6f1ce53 100644 --- a/man/man3/ioproc.3 +++ b/man/man3/ioproc.3 @@ -1,4 +1,4 @@ -.TH IOPROC 2 +.TH IOPROC 3 .SH NAME closeioproc, iocall, diff --git a/man/man3/ip.3 b/man/man3/ip.3 new file mode 100644 index 00000000..54c9f4dd --- /dev/null +++ b/man/man3/ip.3 @@ -0,0 +1,335 @@ +.TH IP 3 +.SH NAME +eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, hnputl, hnputs, ptclbsum, readipifc \- Internet protocol +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +int eipfmt(Fmt*) +.PP +.B +ulong parseip(uchar *ipaddr, char *str) +.PP +.B +ulong parseipmask(uchar *ipaddr, char *str) +.PP +.B +char* v4parseip(uchar *ipaddr, char *str) +.PP +.B +ulong v4parsecidr(uchar *addr, uchar *mask, char *str) +.PP +.B +int parseether(uchar *eaddr, char *str) +.PP +.B +int myetheraddr(uchar *eaddr, char *dev) +.PP +.B +int myipaddr(uchar *ipaddr, char *net) +.PP +.B +void maskip(uchar *from, uchar *mask, uchar *to) +.PP +.B +int equivip(uchar *ipaddr1, uchar *ipaddr2) +.PP +.B +uchar* defmask(uchar *ipaddr) +.PP +.B +int isv4(uchar *ipaddr) +.PP +.B +void v4tov6(uchar *ipv6, uchar *ipv4) +.PP +.B +void v6tov4(uchar *ipv4, uchar *ipv6) +.PP +.B +ushort nhgets(void *p) +.PP +.B +uint nhgetl(void *p) +.PP +.B +void hnputs(void *p, ushort v) +.PP +.B +void hnputl(void *p, uint v) +.PP +.B +ushort ptclbsum(uchar *a, int n) +.PP +.B +Ipifc* readipifc(char *net, Ipifc *ifc, int index) +.PP +.B +uchar IPv4bcast[IPaddrlen]; +.PP +.B +uchar IPv4allsys[IPaddrlen]; +.PP +.B +uchar IPv4allrouter[IPaddrlen]; +.PP +.B +uchar IPallbits[IPaddrlen]; +.PP +.B +uchar IPnoaddr[IPaddrlen]; +.PP +.B +uchar v4prefix[IPaddrlen]; +.SH DESCRIPTION +These routines are used by Internet Protocol (IP) programs to +manipulate IP and Ethernet addresses. +Plan 9, by default, uses V6 format IP addresses. Since V4 +addresses fit into the V6 space, all IP addresses can be represented. +IP addresses are stored as a string of 16 +.B unsigned +.BR chars , +Ethernet +addresses as 6 +.B unsigned +.BR chars . +Either V4 or V6 string representation can be used for IP addresses. +For V4 addresses, the representation can be (up to) 4 decimal +integers from 0 to 255 separated by periods. +For V6 addresses, the representation is (up to) 8 hex integers +from 0x0 to 0xFFFF separated by colons. +Strings of 0 integers can be elided using two colons. +For example, +.B FFFF::1111 +is equivalent to +.BR FFFF:0:0:0:0:0:0:1111 . +The string representation for IP masks is a superset of the +address representation. It includes slash notation that indicates +the number of leading 1 bits in the mask. Thus, a +V4 class C mask can be represented as +.BR FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00 , +.BR 255.255.255.0 , +or +.BR /120. +The string representation of Ethernet addresses is exactly +12 hexadecimal digits. +.PP +.I Eipfmt +is a +.IR print (2) +formatter for Ethernet (verb +.BR E ) +addresses, +IP V6 (verb +.BR I ) +addresses, +IP V4 (verb +.BR V ) +addresses, +and IP V6 (verb +.BR M ) +masks. +.PP +.I Parseip +converts a string pointed to by +.I str +to a 16-byte IP address starting at +.IR ipaddr . +As a concession to backwards compatibility, +if the string is a V4 address, the return value +is an unsigned long integer containing the big-endian V4 address. +If not, the return value is 6. +.I Parseipmask +converts a string pointed to by +.I str +to a 6-byte IP mask starting at +.IR ipaddr . +It too returns an unsigned long big-endian V4 address or 6. +Both routines return -1 on errors. +.PP +.I V4parseip +converts a string pointed to by +.I str +to a 4-byte V4 IP address starting at +.IR ipaddr . +.PP +.I V4parsecidr +converts a string of the form +addr/mask, pointed to by +.IR str , +to a 4-byte V4 IP address starting at +.I ipaddr +and a 4-byte V4 IP mask starting at +.IR mask . +.PP +.I Myipaddr +returns the first valid IP address in +the IP stack rooted at +.IR net . +.PP +.I Parseether +converts a string pointed to by +.I str +to a 6-byte Ethernet address starting at +.IR eaddr . +.I Myetheraddr +reads the Ethernet address string from file +.IB dev /1/stats +and parses it into +.IR eaddr . +Both routines return a negative number on errors. +.PP +.I Maskip +places the bit-wise AND of the IP addresses pointed +to by its first two arguments into the buffer pointed +to by the third. +.PP +.I Equivip +returns non-zero if the IP addresses pointed to by its two +arguments are equal. +.PP +.I Defmask +returns the standard class A, B, or C mask for +.IR ipaddr . +.PP +.I Isv4 +returns non-zero if the V6 address is in the V4 space, that is, +if it starts with +.BR 0:0:0:0:0:0:FFFF . +.I V4tov6 +converts the V4 address, +.IR v4ip , +to a V6 address and puts the result in +.IR v6ip . +.I V6tov4 +converts the V6 address, +.IR v6ip , +to a V4 address and puts the result in +.IR v4ip . +.PP +.I Hnputs +and +.I hnputl +are used to store 16-bit and 32-bit integers into IP big-endian form. +.I Nhgets +and +.I nhgetl +convert big-endian 2 and 4 byte quantities into integers. +.PP +.I Pctlbsum +returns the one's complement checksum used in IP protocols, typically invoked as +.EX +hnputs(hdr->cksum, ~ptclbsum(data, len) & 0xffff); +.EE +.PP +A number of standard IP addresses in V6 format are also defined. They +are: +.IP \f5IPv4bcast +the V4 broadcast address +.IP \f5IPv4allsys +the V4 all systems multicast address +.IP \f5IPv4allrouter +the V4 all routers multicast address +.IP \f5IPallbits +the V6 all bits on address +.IP \f5IPnoaddr +the V6 null address, all zeros +.IP \f5v4prefix +the IP V6 prefix to all embedded V4 addresses +.PP +.I Readipifc +returns information about +a particular interface (\fIindex\fP >= 0) +or all IP interfaces (\fIindex\fP < 0) +configured under a +mount point +.IR net , +default +.BR /net . +Each interface is described by one +.I Ipifc +structure which in turn points to a linked list of +.IR Iplifc +structures describing the addresses assigned +to this interface. +If the list +.IR ifc +is supplied, +that list is freed. +Thus, subsequent calls can be used +to free the list returned by the previous call. +.I Ipifc +is: +.PP +.EX +typedef struct Ipifc +{ + Ipifc *next; + Iplifc *lifc; /* local addressses */ + + /* per ip interface */ + int index; /* number of interface in ipifc dir */ + char dev[64]; /* associated physical device */ + int mtu; /* max transfer unit */ + + long validlt; /* valid life time */ + long preflt; /* preferred life time */ + uchar sendra6; /* on == send router adv */ + uchar recvra6; /* on == rcv router adv */ + + ulong pktin; /* packets read */ + ulong pktout; /* packets written */ + ulong errin; /* read errors */ + ulong errout; /* write errors */ + Ipv6rp rp; /* route advertisement params */ +} Ipifc; +.EE +.PP +.I Iplifc +is: +.PP +.EX +struct Iplifc +{ + Iplifc *next; + + uchar ip[IPaddrlen]; + uchar mask[IPaddrlen]; + uchar net[IPaddrlen]; /* ip & mask */ + ulong preflt; /* preferred lifetime */ + ulong validlt; /* valid lifetime */ +}; +.EE +.PP +.I Ipv6rp +is: +struct Ipv6rp +{ + int mflag; + int oflag; + int maxraint; /* max route adv interval */ + int minraint; /* min route adv interval */ + int linkmtu; + int reachtime; + int rxmitra; + int ttl; + int routerlt; +}; +.PP +.I Dev +contains the first 64 bytes of the device configured with this +interface. +.I Net +is +.IB ip & mask +if the network is multipoint or +the remote address if the network is +point to point. +.SH SOURCE +.B /sys/src/libip +.SH SEE ALSO +.IR print (2) diff --git a/man/man3/isalpharune.3 b/man/man3/isalpharune.3 index f9f58cde..322a2111 100644 --- a/man/man3/isalpharune.3 +++ b/man/man3/isalpharune.3 @@ -2,7 +2,9 @@ .SH NAME isalpharune, islowerrune, isspacerune, istitlerune, isupperrune, tolowerrune, totitlerune, toupperrune \- Unicode character classes and cases .SH SYNOPSIS -.B #include +.B #include +.br +.B #include .PP .B int isalpharune(Rune c) @@ -33,7 +35,7 @@ in particular a subset of their properties as defined in the Unicode standard. Unicode defines some characters as alphabetic and specifies three cases: upper, lower, and title. Analogously to -.IR ctype (3) +.IR ctype (2) for .SM ASCII\c , @@ -42,6 +44,8 @@ test types and modify cases for Unicode characters. The names are self-explanatory. .PP The case-conversion routines return the character unchanged if it has no case. +.SH SOURCE +.B /sys/src/libc/port/runetype.c .SH "SEE ALSO -.IR ctype (3) , +.IR ctype (2) , .IR "The Unicode Standard" . diff --git a/man/man3/keyboard.3 b/man/man3/keyboard.3 new file mode 100644 index 00000000..b123406c --- /dev/null +++ b/man/man3/keyboard.3 @@ -0,0 +1,104 @@ +.TH KEYBOARD 3 +.SH NAME +initkeyboard, ctlkeyboard, closekeyboard \- keyboard control +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.B +#include +.PP +.B +Keyboardctl *initkeyboard(char *file) +.PP +.B +int ctlkeyboard(Keyboardctl *kc, char *msg) +.PP +.B +void closekeyboard(Keyboard *kc) +.SH DESCRIPTION +These functions access and control a keyboard interface +for character-at-a-time I/O in a multi-threaded environment, usually in combination with +.IR mouse (2). +They use the message-passing +.B Channel +interface in the threads library +(see +.IR thread (2)); +programs that wish a more event-driven, single-threaded approach should use +.IR event (2). +.PP +.I Initkeyboard +opens a connection to the keyboard and returns a +.B Keyboardctl +structure: +.IP +.EX +.ta 6n +\w'Channel 'u +\w'consfd; 'u +typedef struct Keyboardct Keyboardctl; +struct Keyboardctl +{ + Channel *c; /* chan(Rune[20]) */ + + char *file; + int consfd; /* to cons file */ + int ctlfd; /* to ctl file */ + int pid; /* of slave proc */ +}; +.EE +.PP +The argument to +.I initkeyboard +is a +.I file +naming the device file from which characters may be read, +typically +.BR /dev/cons . +If +.I file +is nil, +.B /dev/cons +is assumed. +.PP +Once the +.B Keyboardctl +is set up a +message containing a +.BR Rune +will be sent on the +.B Channel +.B Keyboardctl.c +to report each character read from the device. +.PP +.I Ctlkeyboard +is used to set the state of the interface, typically to turn raw mode on and off +(see +.IR cons (3)). +It writes the string +.I msg +to the control file associated with the device, which is assumed to be the regular device file name +with the string +.B ctl +appended. +.PP +.I Closekeyboard +closes the file descriptors associated with the keyboard, kills the slave processes, +and frees the +.B Keyboardctl +structure. +.PP +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR draw (2), +.IR event (2), +.IR thread (2). +.SH BUGS +Because the interface delivers complete runes, +there is no way to report lesser actions such as +shift keys or even individual bytes. diff --git a/man/man3/lock.3 b/man/man3/lock.3 new file mode 100644 index 00000000..7b970127 --- /dev/null +++ b/man/man3/lock.3 @@ -0,0 +1,232 @@ +.TH LOCK 3 +.SH NAME +lock, canlock, unlock, +qlock, canqlock, qunlock, +rlock, canrlock, runlock, +wlock, canwlock, wunlock, +rsleep, rwakeup, rwakeupall +incref, decref +\- spin locks, queueing rendezvous locks, reader-writer locks, rendezvous points, and reference counts +.SH SYNOPSIS +.ft L +.nf +#include +#include +.PP +.ft L +.nf +void lock(Lock *l) +int canlock(Lock *l) +void unlock(Lock *l) +.PP +.ft L +.nf +void qlock(QLock *l) +int canqlock(QLock *l) +void qunlock(QLock *l) +.PP +.ft L +.nf +void rlock(RWLock *l) +int canrlock(RWLock *l) +void runlock(RWLock *l) +.PP +.ft L +.nf +void wlock(RWLock *l) +int canwlock(RWLock *l) +void wunlock(RWLock *l) +.PP +.ft L +.nf +typedef struct Rendez { + QLock *l; + \fI...\fP +} Rendez; +.PP +.ft L +.nf +void rsleep(Rendez *r) +int rwakeup(Rendez *r) +int rwakeupall(Rendez *r) +.PP +.ft L +#include +.PP +.ft L +.nf +typedef struct Ref { + long ref; +} Ref; +.PP +.ft L +.nf +void incref(Ref*) +long decref(Ref*) +.fi +.SH DESCRIPTION +These routines are used to synchronize processes sharing memory. +.PP +.B Locks +are spin locks, +.B QLocks +and +.B RWLocks +are different types of queueing rendezvous locks, +and +.B Rendezes +are rendezvous points. +.PP +Locks and rendezvous points work in regular programs as +well as programs that use the thread library +(see +.IR thread (2)). +The thread library replaces the +.IR rendezvous (2) +system call +with its own implementation, +.IR threadrendezvous , +so that threads as well as processes may be synchronized by locking calls +in threaded programs. +.PP +Used carelessly, spin locks can be expensive and can easily generate deadlocks. +Their use is discouraged, especially in programs that use the +thread library because they prevent context switches between threads. +.PP +.I Lock +blocks until the lock has been obtained. +.I Canlock +is non-blocking. +It tries to obtain a lock and returns a non-zero value if it +was successful, 0 otherwise. +.I Unlock +releases a lock. +.PP +.B QLocks +have the same interface but are not spin locks; instead if the lock is taken +.I qlock +will suspend execution of the calling task until it is released. +.PP +Although +.B Locks +are the more primitive lock, they have limitations; for example, +they cannot synchronize between tasks in the same +.IR proc . +Use +.B QLocks +instead. +.PP +.B RWLocks +manage access to a data structure that has distinct readers and writers. +.I Rlock +grants read access; +.I runlock +releases it. +.I Wlock +grants write access; +.I wunlock +releases it. +.I Canrlock +and +.I canwlock +are the non-blocking versions. +There may be any number of simultaneous readers, +but only one writer. +Moreover, +if write access is granted no one may have +read access until write access is released. +.PP +All types of lock should be initialized to all zeros before use; this +puts them in the unlocked state. +.PP +.B Rendezes +are rendezvous points. Each +.B Rendez +.I r +is protected by a +.B QLock +.IB r -> l \fR, +which must be held by the callers of +.IR rsleep , +.IR rwakeup , +and +.IR rwakeupall . +.I Rsleep +atomically releases +.IB r -> l +and suspends execution of the calling task. +After resuming execution, +.I rsleep +will reacquire +.IB r -> l +before returning. +If any processes are sleeping on +.IR r , +.I rwakeup +wakes one of them. +it returns 1 if a process was awakened, 0 if not. +.I Rwakeupall +wakes all processes sleeping on +.IR r , +returning the number of processes awakened. +.I Rwakeup +and +.I rwakeupall +do not release +.IB r -> l +and do not suspend execution of the current task. +.PP +Before use, +.B Rendezes +should be initialized to all zeros except for +.IB r -> l +pointer, which should point at the +.B QLock +that will guard +.IR r . +.PP +A +.B Ref +contains a +.B long +that can be incremented and decremented atomically: +.I Incref +increments the +.I Ref +in one atomic operation. +.I Decref +atomically decrements the +.B Ref +and returns zero if the resulting value is zero, non-zero otherwise. +.SH SOURCE +.B /sys/src/libc/port/lock.c +.br +.B /sys/src/libc/9sys/qlock.c +.br +.B /sys/src/libthread/ref.c +.SH SEE ALSO +.I rfork +in +.IR fork (2) +.SH BUGS +.B Locks +are not strictly spin locks. +After each unsuccessful attempt, +.I lock +calls +.B sleep(0) +to yield the CPU; this handles the common case +where some other process holds the lock. +After a thousand unsuccessful attempts, +.I lock +sleeps for 100ms between attempts. +Another another thousand unsuccessful attempts, +.I lock +sleeps for a full second between attempts. +.B Locks +are not intended to be held for long periods of time. +The 100ms and full second sleeps are only heuristics to +avoid tying up the CPU when a process deadlocks. +As discussed above, +if a lock is to be held for much more than a few instructions, +the queueing lock types should be almost always be used. diff --git a/man/man3/mach.3 b/man/man3/mach.3 new file mode 100644 index 00000000..82313e62 --- /dev/null +++ b/man/man3/mach.3 @@ -0,0 +1,393 @@ +.TH MACH 3 +.SH NAME +crackhdr, machbytype, machbyname, newmap, setmap, findseg, unusemap, +loadmap, attachproc, get1, get2, get4, get8, put1, put2, put4, put8, +beswab, beswal, beswav, leswab, leswal, leswav \- machine-independent access to executable files +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLmachines 'u +.B +int crackhdr(int fd, Fhdr *fp) +.PP +.B +void machbytype(int type) +.PP +.B +int machbyname(char *name) +.PP +.B +Map *newmap(Map *map, int n) +.PP +.B +int setmap(Map *map, int fd, ulong base, ulong end, +.PP +.B + ulong foffset, char *name) +.PP +.B +int findseg(Map *map, char *name) +.PP +.B +void unusemap(Map *map, int seg) +.PP +.B +Map *loadmap(Map *map, int fd, Fhdr *fp) +.PP +.B +Map *attachproc(int pid, int kflag, int corefd, Fhdr *fp) +.PP +.B +int get1(Map *map, ulong addr, uchar *buf, int n) +.PP +.B +int get2(Map *map, ulong addr, ushort *val) +.PP +.B +int get4(Map *map, ulong addr, long *val) +.PP +.B +int get8(Map *map, ulong addr, vlong *val) +.PP +.B +int put1(Map *map, ulong addr, uchar *buf, int n) +.PP +.B +int put2(Map *map, ulong addr, ushort val) +.PP +.B +int put4(Map *map, ulong addr, long val) +.PP +.B +int put8(Map *map, ulong addr, vlong val) +.PP +.B +ushort beswab(ushort val) +.PP +.B +long beswal(long val) +.PP +.B +long beswav(vlong val) +.PP +.B +ushort leswab(ushort val) +.PP +.B +long leswal(long val) +.PP +.B +long leswav(vlong val) +.PP +.B +extern Mach mach; +.PP +.B +extern Machdata machdata; +.SH DESCRIPTION +These functions provide +a processor-independent interface for accessing +the executable files or executing images of all +architectures. +Related library functions described in +.IR symbol (2) +and +.IR object (2) +provide similar access to symbol tables and object files. +.PP +An +.I executable +is a file containing an executable program or the +.B text +file of the +.B /proc +file system associated with an executing process as +described in +.IR proc (3). +After opening an executable, an application +invokes a library function which parses the +file header, +determines the target architecture and +initializes data structures with parameters +and pointers to functions appropriate for +that architecture. Next, the application +invokes functions to construct one or more +.IR maps , +data structures that translate references +in the address space of the executable +to offsets in the file. Each +.I map +comprises one or more +.BR segments , +each associating a non-overlapping range of +memory addresses with a logical section of +the executable. +Other library functions then use a map +and the architecture-specific data structures +to provide a generic interface to the +processor-dependent data. +.PP +.I Crackhdr +interprets the header of the executable +associated with +the open file descriptor +.IR fd . +It loads the data structure +.I fp +with a machine-independent description +of the header information and +points global variable +.I mach +to the +.B Mach +data structure containing processor-dependent parameters +of the target architecture. +.PP +.I Machbytype +selects architecture-specific data structures and parameter +values based on +the code stored in the +field named +.I type +in the +.B Fhdr +data structure. +.I Machbyname +performs the same selection based +on the name of a processor class; see +.IR 2c (1) +for a list of valid names. +Both functions point global variables +.I mach +and +.I machdata +to the +.I Mach +and +.I Machdata +data structures appropriate for the +target architecture and load global variable +.I asstype +with the proper disassembler type code. +.PP +.I Newmap +creates an empty map with +.I n +segments. +If +.I map +is zero, the new map is dynamically +allocated, otherwise it is assumed to +point to an existing dynamically allocated map whose +size is adjusted, as necessary. +A zero return value indicates an allocation error. +.PP +.I Setmap +loads the first unused segment in +.I map +with the +segment mapping parameters. +.I Fd +is an open file descriptor associated with +an executable. +.I Base +and +.I end +contain the lowest and highest virtual addresses +mapped by the segment. +.I Foffset +is the offset to the start of the segment in the file. +.I Name +is a name to be attached to the segment. +.PP +.I Findseg +returns the index of the the +segment named +.I name +in +.IR map . +A return of -1 indicates that no +segment matches +.IR name . +.PP +.I Unusemap +marks segment number +.I seg +in map +.I map +unused. Other +segments in the map remain unaffected. +.PP +.I Loadmap +initializes a default map containing +segments named `text' and `data' that +map the instruction and data segments +of the executable described in the +.B Fhdr +structure pointed to by +.IR fp . +Usually that structure was loaded by +.IR crackhdr +and can be passed to this function without +modification. +If +.I map +is non-zero, that map, which must have been +dynamically allocated, is resized to contain two segments; +otherwise a new map is allocated. +This function returns zero if allocation fails. +.I Loadmap +is usually used to build a map for accessing +a static executable, for example, an executable +program file. +.PP +.I Attachproc +constructs a map for accessing a +running process. It +returns the address of a +.I Map +containing segments mapping the +address space of the running process +whose process ID is +.BR pid . +If +.B kflag +is non-zero, the process is assumed to be +a kernel process. +.B Corefd +is an file descriptor opened to +.BR /proc/\fIpid\fP/mem . +.B Fp +points to the +.I Fhdr +structure describing the header +of the executable. For most architectures +the resulting +.I Map +contains four segments named `text', `data', +`regs' and `fpregs'. The latter two provide access to +the general and floating point registers, respectively. +If the executable is a kernel process (indicated by a +non-zero +.B kflag +argument), the data segment extends to the maximum +supported address, currently 0xffffffff, and the +register sets are read-only. In user-level programs, +the data segment extends to the +top of the stack or 0x7fffffff if the stack top +cannot be found, and the register sets are readable +and writable. +.I Attachproc +returns zero if it is unable to build the map +for the specified process. +.PP +.IR Get1 , +.IR get2 , +.IR get4 , +and +.I get8 +retrieve the data stored at address +.I addr +in the executable associated +with +.IR map . +.I Get1 +retrieves +.I n +bytes of data beginning at +.I addr +into +.IR buf . +.IR Get2 , +.I get4 +and +.I get8 +retrieve 16-bit, 32-bit and 64-bit values respectively, +into the location pointed to by +.IR val . +The value is byte-swapped if the source +byte order differs from that of the current architecture. +This implies that the value returned by +.IR get2 , +.IR get4 , +and +.I get8 +may not be the same as the byte sequences +returned by +.I get1 +when +.I n +is two, four or eight; the former may be byte-swapped, the +latter reflects the byte order of the target architecture. +If the file descriptor associated with the applicable segment in +.I map +is negative, the address itself is placed in the +return location. These functions return the number +of bytes read or a \-1 when there is an error. +.PP +.IR Put1 , +.IR put2 , +.IR put4 , +and +.I put8 +write to +the executable associated with +.IR map . +The address is translated using the +map parameters and multi-byte quantities are +byte-swapped, if necessary, before they are written. +.I Put1 +transfers +.I n +bytes stored at +.IR buf ; +.IR put2 , +.IR put4 , +and +.I put8 +write the 16-bit, 32-bit or 64-bit quantity contained in +.IR val , +respectively. The number of bytes transferred is returned. +A \-1 return value indicates an error. +.PP +.IR Beswab , +.IR beswal , +and +.I beswav +return the +.BR ushort , +.BR long , +and +.B vlong +big-endian representation of +.IR val , +respectively. +.IR Leswab , +.IR leswal , +and +.I leswav +return the little-endian representation of the +.BR ushort , +.BR long , +and +.B vlong +contained in +.IR val . +.SH SOURCE +.B /sys/src/libmach +.SH "SEE ALSO" +.IR 2c (1), +.IR symbol (2), +.IR object (2), +.IR errstr (2), +.IR proc (3), +.IR a.out (6) +.SH DIAGNOSTICS +These routines set +.IR errstr . diff --git a/man/man3/malloc.3 b/man/man3/malloc.3 new file mode 100644 index 00000000..c75ef29d --- /dev/null +++ b/man/man3/malloc.3 @@ -0,0 +1,207 @@ +.TH MALLOC 3 +.SH NAME +malloc, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock \- memory allocator +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid* 'u +.B +void* malloc(ulong size) +.PP +.B +void* mallocz(ulong size, int clr) +.PP +.B +void free(void *ptr) +.PP +.B +void* realloc(void *ptr, ulong size) +.PP +.B +void* calloc(ulong nelem, ulong elsize) +.PP +.B +ulong msize(void *ptr) +.PP +.B +void setmalloctag(void *ptr, ulong tag) +.PP +.B +ulong getmalloctag(void *ptr, ulong tag) +.PP +.B +void setrealloctag(void *ptr, ulong tag) +.PP +.B +ulong getrealloctag(void *ptr, ulong tag) +.PP +.B +void* malloctopoolblock(void*) +.PP +.SH DESCRIPTION +.I Malloc +and +.I free +provide a simple memory allocation package. +.I Malloc +returns a pointer to a new block of at least +.I size +bytes. +The block is suitably aligned for storage of any type of object. +No two active pointers from +.I malloc +will have the same value. +The call +.B malloc(0) +returns a valid pointer rather than null. +.PP +The argument to +.I free +is a pointer to a block previously allocated by +.IR malloc ; +this space is made available for further allocation. +It is legal to free a null pointer; the effect is a no-op. +The contents of the space returned by +.I malloc +are undefined. +.I Mallocz +behaves as +.IR malloc , +except that if +.I clr +is non-zero, the memory returned will be zeroed. +.PP +.I Realloc +changes the size of the block pointed to by +.I ptr +to +.I size +bytes and returns a pointer to the (possibly moved) +block. +The contents will be unchanged up to the +lesser of the new and old sizes. +.I Realloc +takes on special meanings when one or both arguments are zero: +.TP +.B "realloc(0,\ size) +means +.LR malloc(size) ; +returns a pointer to the newly-allocated memory +.TP +.B "realloc(ptr,\ 0) +means +.LR free(ptr) ; +returns null +.TP +.B "realloc(0,\ 0) +no-op; returns null +.PD +.PP +.I Calloc +allocates space for +an array of +.I nelem +elements of size +.IR elsize . +The space is initialized to zeros. +.I Free +frees such a block. +.PP +When a block is allocated, sometimes there is some extra unused space at the end. +.I Msize +grows the block to encompass this unused space and returns the new number +of bytes that may be used. +.PP +The memory allocator maintains two word-sized fields +associated with each block, the ``malloc tag'' and the ``realloc tag''. +By convention, the malloc tag is the PC that allocated the block, +and the realloc tag the PC that last reallocated the block. +These may be set or examined with +.IR setmalloctag , +.IR getmalloctag , +.IR setrealloctag , +and +.IR getrealloctag . +When allocating blocks directly with +.I malloc +and +.IR realloc , +these tags will be set properly. +If a custom allocator wrapper is used, +the allocator wrapper can set the tags +itself (usually by passing the result of +.IR getcallerpc (2) +to +.IR setmalloctag ) +to provide more useful information about +the source of allocation. +.PP +.I Malloctopoolblock +takes the address of a block returned by +.I malloc +and returns the address of the corresponding +block allocated by the +.IR pool (2) +routines. +.SH SOURCE +.B /sys/src/libc/port/malloc.c +.SH SEE ALSO +.IR leak (1), +.I trump +(in +.IR acid (1)), +.IR brk (2), +.IR getcallerpc (2), +.IR pool (2) +.SH DIAGNOSTICS +.I Malloc, realloc +and +.I calloc +return 0 if there is no available memory. +.I Errstr +is likely to be set. +If the allocated blocks have no malloc or realloc tags, +.I getmalloctag +and +.I getrealloctag +return +.BR ~0 . +.PP +After including +.BR pool.h , +the call +.B poolcheck(mainmem) +can be used to scan the storage arena for inconsistencies +such as data written beyond the bounds of allocated blocks. +It is often useful to combine this with with setting +.EX + mainmem->flags |= POOL_NOREUSE; +.EE +at the beginning of your program. +This will cause malloc not to reallocate blocks even +once they are freed; +.B poolcheck(mainmem) +will then detect writes to freed blocks. +.PP +The +.I trump +library for +.I acid +can be used to obtain traces of malloc execution; see +.IR acid (1). +.SH BUGS +The different specification of +.I calloc +is bizarre. +.PP +User errors can corrupt the storage arena. +The most common gaffes are (1) freeing an already freed block, +(2) storing beyond the bounds of an allocated block, and (3) +freeing data that was not obtained from the allocator. +When +.I malloc +and +.I free +detect such corruption, they abort. diff --git a/man/man3/memdraw.3 b/man/man3/memdraw.3 new file mode 100644 index 00000000..2d94742f --- /dev/null +++ b/man/man3/memdraw.3 @@ -0,0 +1,450 @@ +.TH MEMDRAW 3 +.SH NAME +Memimage, +Memdata, +Memdrawparam, +memimageinit, +wordaddr, +byteaddr, +memimagemove, +allocmemimage, +allocmemimaged, +readmemimage, +creadmemimage, +writememimage, +freememimage, +memsetchan, +loadmemimage, +cloadmemimage, +unloadmemimage, +memfillcolor, +memarc, +mempoly, +memellipse, +memfillpoly, +memimageline, +memimagedraw, +drawclip, +memlinebbox, +memlineendsize, +allocmemsubfont, +openmemsubfont, +freememsubfont, +memsubfontwidth, +getmemdefont, +memimagestring, +iprint, +hwdraw \- drawing routines for memory-resident images +.SH SYNOPSIS +.nf +.B #include +.nf +.B #include +.B #include +.B #include +.B #include +.PP +.ft L +typedef struct Memdata +{ + ulong *base; /* allocated data pointer */ + uchar *bdata; /* first byte of actual data; word-aligned */ + int ref; /* number of Memimages using this data */ + void* imref; /* last image that pointed at this */ + int allocd; /* is this malloc'd? */ +} Memdata; + +enum { + Frepl = 1<<0, /* is replicated */ + Fsimple = 1<<1, /* is 1x1 */ + Fgrey = 1<<2, /* is grey */ + Falpha = 1<<3, /* has explicit alpha */ + Fcmap = 1<<4, /* has cmap channel */ + Fbytes = 1<<5, /* has only 8-bit channels */ +}; + +typedef struct Memimage +{ + Rectangle r; /* rectangle in data area, local coords */ + Rectangle clipr; /* clipping region */ + int depth; /* number of bits of storage per pixel */ + int nchan; /* number of channels */ + ulong chan; /* channel descriptions */ + + Memdata *data; /* pointer to data */ + int zero; /* data->bdata+zero==&byte containing (0,0) */ + ulong width; /* width in words of a single scan line */ + Memlayer *layer; /* nil if not a layer*/ + ulong flags; + \fI...\fP +} Memimage; + +typedef struct Memdrawparam +{ + Memimage *dst; + Rectangle r; + Memimage *src; + Rectangle sr; + Memimage *mask; + Rectangle mr; + \fI...\fP +} Memdrawparam; + +.ta \w'\fLMemsubfont* 'u +int drawdebug; +.ft +.PP +.ft L +.nf +void memimageinit(void) +ulong* wordaddr(Memimage *i, Point p) +uchar* byteaddr(Memimage *i, Point p) +void memimagemove(void *from, void *to) +.PP +.ft L +.nf +Memimage* allocmemimage(Rectangle r, ulong chan) +Memimage* allocmemimaged(Rectangle r, ulong chan, Memdata *data) +Memimage* readmemimage(int fd) +Memimage* creadmemimage(int fd) +int writememimage(int fd, Memimage *i) +void freememimage(Memimage *i) +int memsetchan(Memimage*, ulong) +.PP +.ft L +.nf +int loadmemimage(Memimage *i, Rectangle r, + uchar *buf, int nbuf) +int cloadmemimage(Memimage *i, Rectangle r, + uchar *buf, int nbuf) +int unloadmemimage(Memimage *i, Rectangle r, + uchar *buf, int nbuf) +void memfillcolor(Memimage *i, ulong color) +.PP +.ft L +.nf +void memarc(Memimage *dst, Point c, int a, int b, int thick, + Memimage *src, Point sp, int alpha, int phi, Drawop op) +void mempoly(Memimage *dst, Point *p, int np, int end0, + int end1, int radius, Memimage *src, Point sp, Drawop op) +void memellipse(Memimage *dst, Point c, int a, int b, + int thick, Memimage *src, Point sp, Drawop op) +void memfillpoly(Memimage *dst, Point *p, int np, int wind, + Memimage *src, Point sp, Drawop op) +void memimageline(Memimage *dst, Point p0, Point p1, int end0, + int end1, int radius, Memimage *src, Point sp, Drawop op) +void memimagedraw(Memimage *dst, Rectangle r, Memimage *src, + Point sp, Memimage *mask, Point mp, Drawop op) +.PP +.ft L +.nf +int drawclip(Memimage *dst, Rectangle *dr, Memimage *src, + Point *sp, Memimage *mask, Point *mp, + Rectangle *sr, Rectangle *mr) +Rectangle memlinebbox(Point p0, Point p1, int end0, int end1, + int radius) +int memlineendsize(int end) +.PP +.ft L +.nf +Memsubfont* allocmemsubfont(char *name, int n, int height, + int ascent, Fontchar *info, Memimage *i) +Memsubfont* openmemsubfont(char *name) +void freememsubfont(Memsubfont *f) +Point memsubfontwidth(Memsubfont *f, char *s) +Memsubfont* getmemdefont(void) +Point memimagestring(Memimage *dst, Point p, Memimage *color, + Point cp, Memsubfont *f, char *cs, Drawop op) +.PP +.ft L +.nf +int iprint(char *fmt, ...) +int hwdraw(Memdrawparam *param) +.ft R +.SH DESCRIPTION +The +.B Memimage +type defines memory-resident rectangular pictures and the methods to draw upon them; +.BR Memimage s +differ from +.BR Image s +(see +.IR draw (2)) +in that they are manipulated directly in user memory rather than by +RPCs to the +.B /dev/draw +hierarchy. +The +.Bmemdraw +library is the basis for the kernel +.IR draw (3) +driver and also used by a number of programs that must manipulate +images without a display. +.PP +The +.BR r, +.BR clipr , +.BR depth , +.BR nchan , +and +.BR chan +structure elements are identical to +the ones of the same name +in the +.B Image +structure. +.PP +The +.B flags +element of the +.B Memimage +structure holds a number of bits of information about the image. +In particular, it subsumes the +purpose of the +.B repl +element of +.B Image +structures. +.PP +.I Memimageinit +initializes various static data that the library depends on, +as well as the replicated solid color images +.BR memopaque , +.BR memtransparent , +.BR memblack , +and +.BR memwhite . +It should be called before referring to any of these images +and before calling any of the other library functions. +.PP +Each +.B Memimage +points at a +.B Memdata +structure that in turn points at the actual pixel data for the image. +This allows multiple images to be associated with the same +.BR Memdata . +The first word of the data pointed at by +the +.B base +element of +.B Memdata +points back at the +.B Memdata +structure, so that the +memory allocator (see +.IR pool (2)) +can compact image memory +using +.IR memimagemove . +.PP +Because images can have different coordinate systems, +the +.B zero +element of the +.B Memimage +structure contains the offset that must be added +to the +.B bdata +element of the corresponding +.B Memdata +structure in order to yield a pointer to the data for the pixel (0,0). +Adding +.BR width +machine words +to this pointer moves it down one scan line. +The +.B depth +element can be used to determine how to move the +pointer horizontally. +Note that this method works even for images whose rectangles +do not include the origin, although one should only dereference +pointers corresponding to pixels within the image rectangle. +.I Wordaddr +and +.IR byteaddr +perform these calculations, +returning pointers to the word and byte, respectively, +that contain the beginning of the data for a given pixel. +.PP +.I Allocmemimage +allocages +images with a given rectangle and channel descriptor +(see +.B strtochan +in +.IR graphics (2)), +creating a fresh +.B Memdata +structure and associated storage. +.I Allocmemimaged +is similar but uses the supplied +.I Memdata +structure rather than a new one. +The +.I readmemimage +function reads an uncompressed bitmap +from the given file descriptor, +while +.I creadmemimage +reads a compressed bitmap. +.I Writememimage +writes a compressed representation of +.I i +to file descriptor +.IR fd . +For more on bitmap formats, see +.IR image (6). +.I Freememimage +frees images returned by any of these routines. +The +.B Memimage +structure contains some tables that are used +to store precomputed values depending on the channel descriptor. +.I Memsetchan +updates the +.B chan +element of the structure as well as these tables, +returning \-1 if passed a bad channel descriptor. +.PP +.I Loadmemimage +and +.I cloadmemimage +replace the pixel data for a given rectangle of an image +with the given buffer of uncompressed or compressed +data, respectively. +When calling +.IR cloadmemimage , +the buffer must contain an +integral number of +compressed chunks of data that exactly cover the rectangle. +.I Unloadmemimage +retrieves the uncompressed pixel data for a given rectangle of an image. +All three return the number of bytes consumed on success, +and \-1 in case of an error. +.PP +.I Memfillcolor +fills an image with the given color, a 32-bit number as +described in +.IR color (2). +.PP +.IR Memarc , +.IR mempoly , +.IR memellipse , +.IR memfillpoly , +.IR memimageline , +and +.I memimagedraw +are identical to the +.IR arc , +.IR poly , +.IR ellipse , +.IR fillpoly , +.IR line , +and +.IR gendraw , +routines described in +.IR draw (2), +except that they operate on +.BR Memimage s +rather than +.BR Image s. +Similarly, +.IR allocmemsubfont , +.IR openmemsubfont , +.IR freememsubfont , +.IR memsubfontwidth , +.IR getmemdefont , +and +.I memimagestring +are the +.B Memimage +analogues of +.IR allocsubfont , +.IR openfont , +.IR freesubfont , +.IR strsubfontwidth , +.IR getdefont , +and +.B string +(see +.IR subfont (2) +and +.IR graphics (2)), +except that they operate +only on +.BR Memsubfont s +rather than +.BR Font s. +.PP +.I Drawclip +takes the images involved in a draw operation, +together with the destination rectangle +.B dr +and source +and mask alignment points +.B sp +and +.BR mp , +and +clips them according to the clipping rectangles of the images involved. +It also fills in the rectangles +.B sr +and +.B mr +with rectangles congruent to the returned destination rectangle +but translated so the upper left corners are the returned +.B sp +and +.BR mp . +.I Drawclip +returns zero when the clipped rectangle is empty. +.I Memlinebbox +returns a conservative bounding box containing a line between +two points +with given end styles +and radius. +.I Memlineendsize +calculates the extra length added to a line by attaching +an end of a given style. +.PP +The +.I hwdraw +and +.I iprint +functions are no-op stubs that may be overridden by clients +of the library. +.I Hwdraw +is called at each call to +.I memimagedraw +with the current request's parameters. +If it can satisfy the request, it should do so +and return 1. +If it cannot satisfy the request, it should return 0. +This allows (for instance) the kernel to take advantage +of hardware acceleration. +.I Iprint +should format and print its arguments; +it is given much debugging output when +the global integer variable +.B drawdebug +is non-zero. +In the kernel, +.I iprint +prints to a serial line rather than the screen, for obvious reasons. +.SH SOURCE +.B /sys/src/libmemdraw +.SH SEE ALSO +.IR addpt (2), +.IR color (2), +.IR draw (2), +.IR graphics (2), +.IR memlayer (2), +.IR stringsize (2), +.IR subfont (2), +.IR color (6), +.IR utf (6) +.SH BUGS +.I Memimagestring +is unusual in using a subfont rather than a font, +and in having no parameter to align the source. diff --git a/man/man3/memlayer.3 b/man/man3/memlayer.3 new file mode 100644 index 00000000..4acadf53 --- /dev/null +++ b/man/man3/memlayer.3 @@ -0,0 +1,305 @@ +.TH MEMLAYER 3 +.SH NAME +memdraw, memlalloc, memldelete, memlexpose, memlfree, memlhide, memline, memlnorefresh, memload, memunload, memlorigin, memlsetrefresh, memltofront, memltofrontn, memltorear, memltorearn \- windows of memory-resident images +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ft L +typedef struct Memscreen Memscreen; +typedef struct Memlayer Memlayer; +typedef void (*Refreshfn)(Memimage*, Rectangle, void*); +.ta 4n +\w'\fLRefreshfn 'u +\w'\fL*frontmost; 'u + +struct Memscreen +{ + Memimage *frontmost; /* frontmost layer on screen */ + Memimage *rearmost; /* rearmost layer on screen */ + Memimage *image; /* upon which all layers are drawn */ + Memimage *fill; /* if non-zero, picture to use when repainting */ +}; + +struct Memlayer +{ + Rectangle screenr; /* true position of layer on screen */ + Point delta; /* add delta to go from image coords to screen */ + Memscreen *screen; /* screen this layer belongs to */ + Memimage *front; /* window in front of this one */ + Memimage *rear; /* window behind this one*/ + int clear; /* layer is fully visible */ + Memimage *save; /* save area for obscured parts */ + Refreshfn refreshfn; /* fn to refresh obscured parts if save==nil */ + void *refreshptr; /* argument to refreshfn */ +}; +.ft +.ta \w'\fLMemimage* 'u +.PP +.B +Memimage* memlalloc(Memscreen *s, Rectangle r, Refreshfn fn, void *arg, ulong col) +.PP +.B void memlnorefresh(Memimage *i, Rectangle r, void *arg) +.PP +.B +int memlsetrefresh(Memimage *i, Refreshfn fn, void *arg) +.PP +.B +int memldelete(Memimage *i) +.PP +.B +int memlfree(Memimage *i) +.PP +.B +int memlexpose(Memimage *i, Rectangle r) +.PP +.B +int memlhide(Memimage *i, Rectangle r) +.PP +.B +void memltofront(Memimage *i) +.PP +.B +void memltofrontn(Memimage**ia, int n) +.PP +.B +void memltorear(Memimage *i) +.PP +.B +void memltorearn(Memimage **ia , int n) +.PP +.B +int memlorigin(Memimage *i, Point log, Point phys) +.PP +.B +void memdraw(Image *dst, Rectangle r, +.br +.B + Image *src, Point sp, Image *mask, Point mp, Drawop op) +.fi +.B +int memload(Memimage *i, Rectangle r, +.br +.B + uchar *buf, int n, int iscompressed) +.PP +.B +int memunload(Memimage *i, Rectangle r, +.br +.B + uchar *buf, int n) +.PP +.SH DESCRIPTION +These functions build upon the +.IR memdraw (2) +interface to maintain overlapping graphical windows on in-memory images. +They are used by the kernel to implement the windows interface presented by +.IR draw (3) +and +.IR window (2) +and probably have little use outside of the kernel. +.PP +The basic function is to extend the definition of a +.B Memimage +(see +.IR memdraw (2)) +to include overlapping windows defined by the +.B Memlayer +type. +The first fields of the +.B Memlayer +structure are identical to those in +.BR Memimage , +permitting a function that expects a +.B Memimage +to be passed a +.BR Memlayer , +and vice versa. +Both structures have a +.B save +field, which is nil in a +.B Memimage +and points to `backing store' in a +.BR Memlayer . +The layer routines accept +.B Memimages +or +.BR Memlayers ; +if the image is a +.B Memimage +the underlying +.B Memimage +routine is called; otherwise the layer routines recursively +subdivide the geometry, reducing the operation into a smaller +component that ultimately can be performed on a +.BR Memimage , +either the display on which the window appears, or the backing store. +.PP +.B Memlayers +are associated with a +.B Memscreen +that holds the data structures to maintain the windows and connects +them to the associated +.BR image . +The +.B fill +color is used to paint the background when a window is deleted. +There is no function to establish a +.BR Memscreen ; +to create one, allocate the memory, zero +.B frontmost +and +.BR rearmost , +set +.B fill +to a valid fill color or image, and set +.B image +to the +.B Memimage +(or +.BR Memlayer ) +on which the windows will be displayed. +.PP +.I Memlalloc +allocates a +.B Memlayer +of size +.I r +on +.B Memscreen +.IR s . +If +.I col +is not +.BR DNofill , +the new window will be initialized by painting it that color. +.PP +The refresh function +.I fn +and associated argument +.I arg +will be called by routines in the library to restore portions of the window +uncovered due to another window being deleted or this window being pulled to the front of the stack. +The function, when called, +receives a pointer to the image (window) being refreshed, the rectangle that has been uncovered, +and the +.I arg +recorded when the window was created. +A couple of predefined functions provide built-in management methods: +.I memlnorefresh +does no backup at all, useful for making efficient temporary windows; +while a +.I nil +function specifies that the backing store +.RB ( Memlayer.save ) +will be used to keep the obscured data. +Other functions may be provided by the client. +.I Memlsetrefresh +allows one to change the function associated with the window. +.PP +.I Memldelete +deletes the window +.IR i , +restoring the underlying display. +.I Memlfree +frees the data structures without unlinking the window from the associated +.B Memscreen +or doing any graphics. +.PP +.I Memlexpose +restores rectangle +.I r +within the window, using the backing store or appropriate refresh method. +.I Memlhide +goes the other way, backing up +.I r +so that that portion of the screen may be modified without losing the data in this window. +.PP +.I Memltofront +pulls +.I i +to the front of the stack of windows, making it fully visible. +.I Memltofrontn +pulls the +.I n +windows in the array +.I ia +to the front as a group, leaving their internal order unaffected. +.I Memltorear +and +.I memltorearn +push the windows to the rear. +.PP +.I Memlorigin +changes the coordinate systems associated with the window +.IR i . +The points +.I log +and +.I phys +represent the upper left corner +.RB ( min ) +of the window's internal coordinate system and its physical location on the screen. +Changing +.I log +changes the interpretation of coordinates within the window; for example, setting it to +(0,\ 0) makes the upper left corner of the window appear to be the origin of the coordinate +system, regardless of its position on the screen. +Changing +.I phys +changes the physical location of the window on the screen. +When a window is created, its logical and physical coordinates are the same, so +.EX + memlorigin(i, i->r.min, i->r.min) +.EE +would be a no-op. +.PP +.I Memdraw +and +.I memline +are implemented in the layer library but provide the main entry points for drawing on +memory-resident windows. +They have the signatures of +.I memimagedraw +and +.I memimageline +(see +.IR memdraw (2)) +but accept +.B Memlayer +or +.B Memimage +arguments both. +.PP +.I Memload +and +.I memunload +are similarly layer-savvy versions of +.I loadmemimage +and +.IR unloadmemimage . +The +.I iscompressed +flag to +.I memload +specifies whether the +.I n +bytes of data in +.I buf +are in compressed image format +(see +.IR image (6)). +.SH SOURCE +.B /sys/src/libmemlayer +.SH SEE ALSO +.IR graphics (2), +.IR memdraw (2), +.IR stringsize (2), +.IR window (2), +.IR draw (3) diff --git a/man/man3/mktemp.3 b/man/man3/mktemp.3 new file mode 100644 index 00000000..7ad6660e --- /dev/null +++ b/man/man3/mktemp.3 @@ -0,0 +1,40 @@ +.TH MKTEMP 3 +.SH NAME +mktemp \- make a unique file name +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +char* mktemp(char *template) +.fi +.SH DESCRIPTION +.I Mktemp +replaces +.I template +by a unique file name, and returns the +address of the template. +The template should look like a file name with eleven trailing +.LR X s. +The +.LR X s +are replaced by a letter followed by the current process id. +Letters from +.L a +to +.L z +are tried until a name that can be accessed +(see +.IR access (2)) +is generated. +If no such name can be generated, +.I mktemp +returns +\f5"/"\f1 . +.SH SOURCE +.B /sys/src/libc/port/mktemp.c +.SH "SEE ALSO" +.IR getpid (2), +.IR access (2) diff --git a/man/man3/mouse.3 b/man/man3/mouse.3 new file mode 100644 index 00000000..68e8a05e --- /dev/null +++ b/man/man3/mouse.3 @@ -0,0 +1,249 @@ +.TH MOUSE 3 +.SH NAME +initmouse, readmouse, closemouse, moveto, cursorswitch, getrect, drawgetrect, menuhit, setcursor \- mouse control +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.PP +.B +Mousectl *initmouse(char *file, Image *i) +.PP +.B +int readmouse(Mousectl *mc) +.PP +.B +int atomouse(); +.PP +.B +void closemouse(Mousectl *mc) +.PP +.B +void moveto(Mousectl *mc, Point pt) +.PP +.B +void setcursor(Mousectl *mc, Cursor *c) +.PP +.B +Rectangle getrect(int but, Mousectl *mc) +.PP +.B +void drawgetrect(Rectangle r, int up) +.PP +.B +int menuhit(int but, Mousectl *mc, Menu *menu, Screen *scr) +.fi +.SH DESCRIPTION +These functions access and control a mouse in a multi-threaded environment. +They use the message-passing +.B Channel +interface in the threads library +(see +.IR thread (2)); +programs that wish a more event-driven, single-threaded approach should use +.IR event (2). +.PP +The state of the mouse is recorded in a structure, +.BR Mouse , +defined in +.BR : +.IP +.EX +.ta 6n +\w'Rectangle 'u +\w'buttons; 'u +typedef struct Mouse Mouse; +struct Mouse +{ + int buttons; /* bit array: LMR=124 */ + Point xy; + ulong msec; +}; +.EE +.PP +The +.B Point +.B xy +records the position of the cursor, +.B buttons +the state of the buttons (three bits representing, from bit 0 up, the buttons from left to right, +0 if the button is released, 1 if it is pressed), +and +.BR msec , +a millisecond time stamp. +.PP +The routine +.B initmouse +returns a structure through which one may access the mouse: +.IP +.EX +typedef struct Mousectl Mousectl; +struct Mousectl +{ + Mouse; + Channel *c; /* chan(Mouse)[16] */ + Channel *resizec; /* chan(int)[2] */ + + char *file; + int mfd; /* to mouse file */ + int cfd; /* to cursor file */ + int pid; /* of slave proc */ + Image* image; /* of associated window/display */ +}; +.EE +.PP +The arguments to +.I initmouse +are a +.I file +naming the device file connected to the mouse and an +.I Image +(see +.IR draw (2)) +on which the mouse will be visible. +Typically the file is +nil, +which requests the default +.BR /dev/mouse ; +and the image is the window in which the program is running, held in the variable +.B screen +after a call to +.IR initdraw . +.PP +Once the +.B Mousectl +is set up, +mouse motion will be reported by messages of type +.B Mouse +sent on the +.B Channel +.BR Mousectl.c . +Typically, a message will be sent every time a read of +.B /dev/mouse +succeeds, which is every time the state of the mouse changes. +.PP +When the window is resized, a message is sent on +.BR Mousectl.resizec . +The actual value sent may be discarded; the receipt of the message +tells the program that it should call +.B getwindow +(see +.IR graphics (2)) +to reconnect to the window. +.PP +.I Readmouse +updates the +.B Mouse +structure held in the +.BR Mousectl , +blocking if the state has not changed since the last +.I readmouse +or message sent on the channel. +It calls +.B flushimage +(see +.IR graphics (2)) +before blocking, so any buffered graphics requests are displayed. +.PP +.I Closemouse +closes the file descriptors associated with the mouse, kills the slave processes, +and frees the +.B Mousectl +structure. +.PP +.I Moveto +moves the mouse cursor on the display to the position specified by +.IR pt . +.PP +.I Setcursor +sets the image of the cursor to that specified by +.IR c . +If +.I c +is nil, the cursor is set to the default. +The format of the cursor data is spelled out in +.B +and described in +.IR graphics (2). +.PP +.I Getrect +returns the dimensions of a rectangle swept by the user, using the mouse, +in the manner +.IR rio (1) +or +.IR sam (1) +uses to create a new window. +The +.I but +argument specifies which button the user must press to sweep the window; +any other button press cancels the action. +The returned rectangle is all zeros if the user cancels. +.PP +.I Getrect +uses successive calls to +.I drawgetrect +to maintain the red rectangle showing the sweep-in-progress. +The rectangle to be drawn is specified by +.I rc +and the +.I up +parameter says whether to draw (1) or erase (0) the rectangle. +.PP +.I Menuhit +provides a simple menu mechanism. +It uses a +.B Menu +structure defined in +.BR : +.IP +.EX +typedef struct Menu Menu; +struct Menu +{ + char **item; + char *(*gen)(int); + int lasthit; +}; +.EE +.PP +.IR Menuhit +behaves the same as its namesake +.I emenuhit +described in +.IR event (2), +with two exceptions. +First, it uses a +.B Mousectl +to access the mouse rather than using the event interface; +and second, +it creates the menu as a true window on the +.B Screen +.I scr +(see +.IR window (2)), +permitting the menu to be displayed in parallel with other activities on the display. +If +.I scr +is null, +.I menuhit +behaves like +.IR emenuhit , +creating backing store for the menu, writing the menu directly on the display, and +restoring the display when the menu is removed. +.PP +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR draw (2), +.IR event (2), +.IR keyboard (2), +.IR thread (2). diff --git a/man/man3/mp.3 b/man/man3/mp.3 new file mode 100644 index 00000000..57136de4 --- /dev/null +++ b/man/man3/mp.3 @@ -0,0 +1,577 @@ +.TH MP 3 +.SH NAME + +mpsetminbits, mpnew, mpfree, mpbits, mpnorm, mpcopy, mpassign, mprand, strtomp, mpfmt,mptoa, betomp, mptobe, letomp, mptole, mptoui, uitomp, mptoi, itomp, uvtomp, mptouv, vtomp, mptov, mpdigdiv, mpadd, mpsub, mpleft, mpright, mpmul, mpexp, mpmod, mpdiv, mpcmp, mpextendedgcd, mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, crtpre, crtin, crtout, crtprefree, crtresfree \- extended precision arithmetic +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +mpint* mpnew(int n) +.PP +.B +void mpfree(mpint *b) +.PP +.B +void mpsetminbits(int n) +.PP +.B +void mpbits(mpint *b, int n) +.PP +.B +void mpnorm(mpint *b) +.PP +.B +mpint* mpcopy(mpint *b) +.PP +.B +void mpassign(mpint *old, mpint *new) +.PP +.B +mpint* mprand(int bits, void (*gen)(uchar*, int), mpint *b) +.PP +.B +mpint* strtomp(char *buf, char **rptr, int base, mpint *b) +.PP +.B +char* mptoa(mpint *b, int base, char *buf, int blen) +.PP +.B +int mpfmt(Fmt*) +.PP +.B +mpint* betomp(uchar *buf, uint blen, mpint *b) +.PP +.B +int mptobe(mpint *b, uchar *buf, uint blen, uchar **bufp) +.PP +.B +mpint* letomp(uchar *buf, uint blen, mpint *b) +.PP +.B +int mptole(mpint *b, uchar *buf, uint blen, uchar **bufp) +.PP +.B +uint mptoui(mpint*) +.PP +.B +mpint* uitomp(uint, mpint*) +.PP +.B +int mptoi(mpint*) +.PP +.B +mpint* itomp(int, mpint*) +.PP +.B +mpint* vtomp(vlong, mpint*) +.PP +.B +vlong mptov(mpint*) +.PP +.B +mpint* uvtomp(uvlong, mpint*) +.PP +.B +uvlong mptouv(mpint*) +.PP +.B +void mpadd(mpint *b1, mpint *b2, mpint *sum) +.PP +.B +void mpmagadd(mpint *b1, mpint *b2, mpint *sum) +.PP +.B +void mpsub(mpint *b1, mpint *b2, mpint *diff) +.PP +.B +void mpmagsub(mpint *b1, mpint *b2, mpint *diff) +.PP +.B +void mpleft(mpint *b, int shift, mpint *res) +.PP +.B +void mpright(mpint *b, int shift, mpint *res) +.PP +.B +void mpmul(mpint *b1, mpint *b2, mpint *prod) +.PP +.B +void mpexp(mpint *b, mpint *e, mpint *m, mpint *res) +.PP +.B +void mpmod(mpint *b, mpint *m, mpint *remainder) +.PP +.B +void mpdiv(mpint *dividend, mpint *divisor, mpint *quotient, mpint *remainder) +.PP +.B +int mpcmp(mpint *b1, mpint *b2) +.PP +.B +int mpmagcmp(mpint *b1, mpint *b2) +.PP +.B +void mpextendedgcd(mpint *a, mpint *b, mpint *d, mpint *x, mpint *y) +.PP +.B +void mpinvert(mpint *b, mpint *m, mpint *res) +.PP +.B +int mpsignif(mpint *b) +.PP +.B +int mplowbits0(mpint *b) +.PP +.B +void mpdigdiv(mpdigit *dividend, mpdigit divisor, mpdigit *quotient) +.PP +.B +void mpvecadd(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit *sum) +.PP +.B +void mpvecsub(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit *diff) +.PP +.B +void mpvecdigmuladd(mpdigit *b, int n, mpdigit m, mpdigit *p) +.PP +.B +int mpvecdigmulsub(mpdigit *b, int n, mpdigit m, mpdigit *p) +.PP +.B +void mpvecmul(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit *p) +.PP +.B +int mpveccmp(mpdigit *a, int alen, mpdigit *b, int blen) +.PP +.B +CRTpre* crtpre(int nfactors, mpint **factors) +.PP +.B +CRTres* crtin(CRTpre *crt, mpint *x) +.PP +.B +void crtout(CRTpre *crt, CRTres *r, mpint *x) +.PP +.B +void crtprefree(CRTpre *cre) +.PP +.B +void crtresfree(CRTres *res) +.PP +.B +mpint *mpzero, *mpone, *mptwo +.SH DESCRIPTION +.PP +These routines perform extended precision integer arithmetic. +The basic type is +.BR mpint , +which points to an array of +.BR mpdigit s, +stored in little-endian order: +.sp +.EX +typedef struct mpint mpint; +struct mpint +{ + int sign; /* +1 or -1 */ + int size; /* allocated digits */ + int top; /* significant digits */ + mpdigit *p; + char flags; +}; +.EE +.PP +The sign of 0 is +1. +.PP +The size of +.B mpdigit +is architecture-dependent and defined in +.BR /$cputype/include/u.h . +.BR Mpint s +are dynamically allocated and must be explicitly freed. Operations +grow the array of digits as needed. +.PP +In general, the result parameters are last in the +argument list. +.PP +Routines that return an +.B mpint +will allocate the +.B mpint +if the result parameter is +.BR nil . +This includes +.IR strtomp , +.IR itomp , +.IR uitomp , +and +.IR btomp . +These functions, in addition to +.I mpnew +and +.IR mpcopy , +will return +.B nil +if the allocation fails. +.PP +Input and result parameters may point to the same +.BR mpint . +The routines check and copy where necessary. +.PP +.I Mpnew +creates an +.B mpint +with an initial allocation of +.I n +bits. +If +.I n +is zero, the allocation will be whatever was specified in the +last call to +.I mpsetminbits +or to the initial value, 1056. +.I Mpfree +frees an +.BR mpint . +.I Mpbits +grows the allocation of +.I b +to fit at least +.I n +bits. If +.B b->top +doesn't cover +.I n +bits it increases it to do so. +Unless you are writing new basic operations, you +can restrict yourself to +.B mpnew(0) +and +.BR mpfree(b) . +.PP +.I Mpnorm +normalizes the representation by trimming any high order zero +digits. All routines except +.B mpbits +return normalized results. +.PP +.I Mpcopy +creates a new +.B mpint +with the same value as +.I b +while +.I mpassign +sets the value of +.I new +to be that of +.IR old . +.PP +.I Mprand +creates an +.I n +bit random number using the generator +.IR gen . +.I Gen +takes a pointer to a string of uchar's and the number +to fill in. +.PP +.I Strtomp +and +.I mptoa +convert between +.SM ASCII +and +.B mpint +representations using the base indicated. +Only the bases 10, 16, 32, and 64 are +supported. Anything else defaults to 16. +.IR Strtomp +skips any leading spaces or tabs. +.IR Strtomp 's +scan stops when encountering a digit not valid in the +base. If +.I rptr +is not zero, +.I *rptr +is set to point to the character immediately after the +string converted. +If the parse pterminates before any digits are found, +.I strtomp +return +.BR nil . +.I Mptoa +returns a pointer to the filled buffer. +If the parameter +.I buf +is +.BR nil , +the buffer is allocated. +.I Mpfmt +can be used with +.IR fmtinstall (2) +and +.IR print (2) +to print hexadecimal representations of +.BR mpint s. +.PP +.I Mptobe +and +.I mptole +convert an +.I mpint +to a byte array. The former creates a big endian representation, +the latter a little endian one. +If the destination +.I buf +is not +.BR nil , +it specifies the buffer of length +.I blen +for the result. If the representation +is less than +.I blen +bytes, the rest of the buffer is zero filled. +If +.I buf +is +.BR nil , +then a buffer is allocated and a pointer to it is +deposited in the location pointed to by +.IR bufp . +Sign is ignored in these conversions, i.e., the byte +array version is always positive. +.PP +.IR Betomp , +and +.I letomp +convert from a big or little endian byte array at +.I buf +of length +.I blen +to an +.IR mpint . +If +.I b +is not +.IR nil , +it refers to a preallocated +.I mpint +for the result. +If +.I b +is +.BR nil , +a new integer is allocated and returned as the result. +.PP +The integer conversions are: +.TF Mptouv +.TP +.I mptoui +.BR mpint -> "unsigned int" +.TP +.I uitomp +.BR "unsigned int" -> mpint +.TP +.I mptoi +.BR mpint -> "int" +.TP +.I itomp +.BR "int" -> mpint +.TP +.I mptouv +.BR mpint -> "unsigned vlong" +.TP +.I uvtomp +.BR "unsigned vlong" -> mpint +.TP +.I mptov +.BR mpint -> "vlong" +.TP +.I vtomp +.BR "vlong" -> mpint +.PD +.PP +When converting to the base integer types, if the integer is too large, +the largest integer of the appropriate sign +and size is returned. +.PP +The mathematical functions are: +.TF mpmagadd +.TP +.I mpadd +.BR "sum = b1 + b2" . +.TP +.I mpmagadd +.BR "sum = abs(b1) + abs(b2)" . +.TP +.I mpsub +.BR "diff = b1 - b2" . +.TP +.I mpmagsub +.BR "diff = abs(b1) - abs(b2)" . +.TP +.I mpleft +.BR "res = b<>shift" . +.TP +.I mpmul +.BR "prod = b1*b2" . +.TP +.I mpexp +if +.I m +is nil, +.BR "res = b**e" . +Otherwise, +.BR "res = b**e mod m" . +.TP +.I mpmod +.BR "remainder = b % m" . +.TP +.I mpdiv +.BR "quotient = dividend/divisor" . +.BR "remainder = dividend % divisor" . +.TP +.I mpcmp +returns -1, 0, or +1 as +.I b1 +is less than, equal to, or greater than +.IR b2 . +.TP +.I mpmagcmp +the same as +.I mpcmp +but ignores the sign and just compares magnitudes. +.PD +.PP +.I Mpextendedgcd +computes the greatest common denominator, +.IR d , +of +.I a +and +.IR b . +It also computes +.I x +and +.I y +such that +.BR "a*x + b*y = d" . +Both +.I a +and +.I b +are required to be positive. +If called with negative arguments, it will +return a gcd of 0. +.PP +.I Mpinverse +computes the multiplicative inverse of +.I b +.B mod +.IR m . +.PP +.I Mpsignif +returns the bit offset of the left most 1 bit in +.IR b . +.I Mplowbits0 +returns the bit offset of the right most 1 bit. +For example, for 0x14, +.I mpsignif +would return 4 and +.I mplowbits0 +would return 2. +.PP +The remaining routines all work on arrays of +.B mpdigit +rather than +.BR mpint 's. +They are the basis of all the other routines. They are separated out +to allow them to be rewritten in assembler for each architecture. There +is also a portable C version for each one. +.TF mpvecdigmuladd +.TP +.I mpdigdiv +.BR "quotient = dividend[0:1] / divisor" . +.TP +.I mpvecadd +.BR "sum[0:alen] = a[0:alen-1] + b[0:blen-1]" . +We assume alen >= blen and that sum has room for alen+1 digits. +.TP +.I mpvecsub +.BR "diff[0:alen-1] = a[0:alen-1] - b[0:blen-1]" . +We assume that alen >= blen and that diff has room for alen digits. +.TP +.I mpvecdigmuladd +.BR "p[0:n] += m * b[0:n-1]" . +This multiplies a an array of digits times a scalar and adds it to another array. +We assume p has room for n+1 digits. +.TP +.I mpvecdigmulsub +.BR "p[0:n] -= m * b[0:n-1]" . +This multiplies a an array of digits times a scalar and subtracts it fromo another array. +We assume p has room for n+1 digits. It returns +1 is the result is positive and +-1 if negative. +.TP +.I mpvecmul +.BR "p[0:alen*blen] = a[0:alen-1] * b[0:blen-1]" . +We assume that p has room for alen*blen+1 digits. +.TP +.I mpveccmp +This returns -1, 0, or +1 as a - b is negative, 0, or positive. +.PD +.PP +.IR mptwo , +.I mpone +and +.I mpzero +are the constants 2, 1 and 0. These cannot be freed. +.SS "Chinese remainder theorem +.PP +When computing in a non-prime modulus, +.IR n, +it is possible to perform the computations on the residues modulo the prime +factors of +.I n +instead. Since these numbers are smaller, multiplication and exponentiation +can be much faster. +.PP +.I Crtin +computes the residues of +.I x +and returns them in a newly allocated structure: +.EX + typedef struct CRTres CRTres; + { + int n; // number of residues + mpint *r[n]; // residues + }; +.EE +.PP +.I Crtout +takes a residue representation of a number and converts it back into +the number. It also frees the residue structure. +.PP +.I Crepre +saves a copy of the factors and precomputes the constants necessary +for converting the residue form back into a number modulo +the product of the factors. It returns a newly allocated structure +containing values. +.PP +.I Crtprefree +and +.I crtresfree +free +.I CRTpre +and +.I CRTres +structures respectively. +.SH SOURCE +.B /sys/src/libmp diff --git a/man/man3/muldiv.3 b/man/man3/muldiv.3 new file mode 100644 index 00000000..3bc6dda9 --- /dev/null +++ b/man/man3/muldiv.3 @@ -0,0 +1,31 @@ +.TH MULDIV 3 +.SH NAME +muldiv, umuldiv \- high-precision multiplication and division +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +long muldiv(long a, long b, long c) +.PP +.B +ulong umuldiv(ulong a, ulong b, ulong c) +.SH DESCRIPTION +.I Muldiv +returns +.BR a*b/c , +using a +.B vlong +to hold the intermediate result. +.I Umuldiv +is the equivalent for unsigned integers. +They can be used to scale integer values without worry about +overflowing the intermediate result. +.PP +On some architectures, these routines can generate a trap if the +final result does not fit in a +.B long +or +.BR ulong ; +on others they will silently truncate. diff --git a/man/man3/nan.3 b/man/man3/nan.3 new file mode 100644 index 00000000..b0280125 --- /dev/null +++ b/man/man3/nan.3 @@ -0,0 +1,44 @@ +.TH NAN 3 +.SH NAME +NaN, Inf, isNaN, isInf \- not-a-number and infinity functions +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLdouble 'u +.B +double NaN(void) +.PP +.B +double Inf(int) +.PP +.B +int isNaN(double) +.PP +.B +int isInf(double, int) +.SH DESCRIPTION +The IEEE floating point standard defines values called +`not-a-number' and positive and negative `infinity'. +These values can be produced by such things as overflow +and division by zero. +Also, the library functions sometimes return them when +the arguments are not in the domain, or the result is +out of range. +.PP +.I NaN +returns a double that is not-a-number. +.I IsNaN +returns true if its argument is not-a-number. +.PP +.IR Inf ( i ) +returns positive infinity if +.I i +is greater than or equal to zero, +else negative infinity. +.I IsInf +returns true if its first argument is infinity +with the same sign as the second argument. +.SH SOURCE +.B /sys/src/libc/port/nan.c diff --git a/man/man3/notify.3 b/man/man3/notify.3 new file mode 100644 index 00000000..5ab083c4 --- /dev/null +++ b/man/man3/notify.3 @@ -0,0 +1,244 @@ +.TH NOTIFY 3 +.SH NAME +notify, noted, atnotify \- handle asynchronous process notification +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int notify(void (*f)(void*, char*)) +.PP +.B +int noted(int v) +.PP +.B +int atnotify(int (*f)(void*, char*), int in) +.SH DESCRIPTION +When a process raises an exceptional condition such as dividing by zero +or writing on a closed pipe, a +.I note +is posted to communicate the exception. +A note may also be posted by a +.I write +(see +.IR read (2)) +to the process's +.BI /proc/ n /note +file or to the +.BI /proc/ m /notepg +file of a process in the same process group (see +.IR proc (3)). +When the note is received +the behavior of the process depends on the origin of the note. +If the note was posted by an external process, +the process receiving the note exits; +if generated by the system the note string, +preceded by the name +and id of the process and the string +\fL"suicide: "\fP, +is printed on the process's standard error file +and the +process is suspended in the +.B Broken +state for debugging. +.PP +These default actions may be overridden. +The +.I notify +function registers a +.I "notification handler +to be called within the process when a note is received. +The argument to +.I notify +replaces the previous handler, if any. +An argument of zero cancels a previous handler, +restoring the default action. +A +.IR fork (2) +system call leaves the handler registered in +both the parent and the child; +.IR exec (2) +restores the default behavior. +Handlers may not perform floating point operations. +.PP +After a note is posted, +the handler is called with two arguments: +the first is a pointer to a +.B Ureg +structure (defined in +.BR /$objtype/include/ureg.h ) +giving the current values of registers; +the second is a pointer to the note itself, +a null-terminated string with no more than +.L ERRLEN +characters in it including the terminal NUL. +The +.B Ureg +argument is usually not needed; it is provided to help recover from traps such +as floating point exceptions. +Its use and layout are machine- and system-specific. +.PP +A notification handler must finish either by exiting the program or by calling +.IR noted ; +if the handler returns the behavior +is undefined and probably erroneous. +Until the program calls +.IR noted , +any further externally-generated notes +(e.g., +.B hangup +or +.BR alarm ) +will be held off, and any further notes generated by +erroneous behavior by the program +(such as divide by zero) will kill the program. +The argument to +.I noted +defines the action to take: +.B NDFLT +instructs the system to perform the default action +as if the handler had never been registered; +.B NCONT +instructs the system to resume the process +at the point it was notified. +In neither case does +.I noted +return to the handler. +If the note interrupted an incomplete system call, +that call returns an error (with error string +.BR interrupted ) +after the process resumes. +A notification handler can also jump out to an environment +set up with +.I setjmp +using the +.I notejmp +function (see +.IR setjmp (2)), +which is implemented by modifying the saved state and calling +.BR noted(NCONT) . +.PP +Regardless of the origin of the note or the presence of a handler, +if the process is being debugged +(see +.IR proc (3)) +the arrival of a note puts the process in the +.B Stopped +state and awakens the debugger. +.PP +Rather than using the system calls +.I notify +and +.IR noted , +most programs should use +.I atnotify +to register notification handlers. +The parameter +.I in +is non-zero to register the function +.IR f , +and zero to cancel registration. +A handler must return a non-zero number +if the note was recognized (and resolved); +otherwise it must return zero. +When the system posts a note to the process, +each handler registered with +.I atnotify +is called with arguments as +described above +until one of the handlers returns non-zero. +Then +.I noted +is called with argument +.BR NCONT . +If no registered function returns non-zero, +.I atnotify +calls +.I noted +with argument +.BR NDFLT . +.PP +.I Noted +has two other possible values for its argument. +.B NSAVE +returns from the handler and clears the note, enabling the receipt of another, +but does not return to the program. +Instead it starts a new handler with the same stack, stack pointer, +and arguments as the +original, at the address recorded in the program counter of the +.B Ureg +structure. Typically, the program counter will be overridden by the +first note handler to be the address of a separate function; +.B NSAVE +is then a `trampoline' to that handler. +That handler may executed +.B noted(NRSTR) +to return to the original program, usually after restoring the original program +counter. +.B NRSTR +is identical to +.BR NCONT +except that it can only be executed after an +.BR NSAVE . +.B NSAVE +and +.B NRSTR +are designed to improve the emulation of signals by the ANSI C/POSIX +environment; their use elsewhere is discouraged. +.PP +The set of notes a process may receive is system-dependent, but there +is a common set that includes: +.PP +.RS 3n +.nf +.ta \w'\fLsys: write on closed pipe \fP'u +\fINote\fP \fIMeaning\fP +\fLinterrupt\fP user interrupt (DEL key) +\fLhangup\fP I/O connection closed +\fLalarm\fP alarm expired +\fLsys: breakpoint\fP breakpoint instruction +\fLsys: bad address\fP system call address argument out of range +\fLsys: odd address\fP system call address argument unaligned +\fLsys: bad sys call\fP system call number out of range +\fLsys: odd stack\fP system call user stack unaligned +\fLsys: write on closed pipe\fP write on closed pipe +\fLsys: fp: \fIfptrap\f1 floating point exception +\fLsys: trap: \fItrap\f1 other exception (see below) +.fi +.RE +.PP +The notes prefixed +.B sys: +are generated by the operating system. +They are suffixed by the user program counter in format +.BR pc=0x1234 . +If the note is due to a floating point exception, just before the +.BR pc +is the address of the offending instruction in format +.BR fppc=0x1234 . +Notes are limited to +.B ERRLEN +bytes; if they would be longer they are truncated but the +.B pc +is always reported correctly. +.PP +The types and syntax of the +.I trap +and +.I fptrap +portions of the notes are machine-dependent. +.SH SOURCE +.B /sys/src/libc/9syscall +.br +.B /sys/src/libc/port/atnotify.c +.SH SEE ALSO +.IR intro (2), +.I notejmp +in +.IR setjmp (2) +.SH BUGS +Since +.IR exec (2) +discards the notification handler, there is a window +of vulnerability to notes in a new process. diff --git a/man/man3/open.3 b/man/man3/open.3 new file mode 100644 index 00000000..4bc887b6 --- /dev/null +++ b/man/man3/open.3 @@ -0,0 +1,148 @@ +.TH OPEN 3 +.SH NAME +open, create, close \- open a file for reading or writing, create file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int open(char *file, int omode) +.PP +.B +int create(char *file, int omode, ulong perm) +.PP +.B +int close(int fd) +.SH DESCRIPTION +.I Open +opens the +.I file +for I/O and returns an associated file descriptor. +.I Omode +is one of +.BR OREAD , +.BR OWRITE , +.BR ORDWR , +or +.BR OEXEC , +asking for permission to read, write, read and write, or execute, respectively. +In addition, there are three values that can be ORed with the +.IR omode : +.B OTRUNC +says to truncate the file +to zero length before opening it; +.B OCEXEC +says to close the file when an +.IR exec (2) +or +.I execl +system call is made; +and +.B ORCLOSE +says to remove the file when it is closed (by everyone who has a copy of the file descriptor). +.I Open +fails if the file does not exist or the user does not have +permission to open it for the requested purpose +(see +.IR stat (2) +for a description of permissions). +The user must have write permission on the +.I file +if the +.B OTRUNC +bit is set. +For the +.I open +system call +(unlike the implicit +.I open +in +.IR exec (2)), +.B OEXEC +is actually identical to +.BR OREAD . +.PP +.I Create +creates a new +.I file +or prepares to rewrite an existing +.IR file , +opens it according to +.I omode +(as described for +.IR open ), +and returns an associated file descriptor. +If the file is new, +the owner is set to the userid of the creating process group; +the group to that of the containing directory; +the permissions to +.I perm +ANDed with the permissions of the containing directory. +If the file already exists, +it is truncated to 0 length, +and the permissions, owner, and group remain unchanged. +The created file is a directory if the +.B DMDIR +bit is set in +.IR perm , +an exclusive-use file if the +.B DMEXCL +bit is set, and an append-only file if the +.B DMAPPEND +bit is set. +Exclusive-use files may be open for I/O by only one client at a time, +but the file descriptor may become invalid if no I/O is done +for an extended period; see +.IR open (5). +.PP +.I Create +fails if the path up to the last element of +.I file +cannot be evaluated, if the user doesn't have write permission +in the final directory, if the file already exists and +does not permit the access defined by +.IR omode , +of if there there are no free file descriptors. +In the last case, the file may be created even when +an error is returned. +If the file is new and the directory in which it is created is +a union directory (see +.IR intro (2)) +then the constituent directory where the file is created +depends on the structure of the union: see +.IR bind (2). +.PP +Since +.I create +may succeed even if the file exists, a special mechanism is necessary +for those applications that require an atomic create operation. +If the +.B OEXCL +.RB ( 0x1000 ) +bit is set in the +.I mode +for a +.IR create, +the call succeeds only if the file does not already exist; +see +.IR open (5) +for details. +.PP +.I Close +closes the file associated with a file descriptor. +Provided the file descriptor is a valid open descriptor, +.I close +is guaranteed to close it; there will be no error. +Files are closed automatically upon termination of a process; +.I close +allows the file descriptor to be reused. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR bind (2), +.IR stat (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/man/man3/pipe.3 b/man/man3/pipe.3 new file mode 100644 index 00000000..85bdfb2e --- /dev/null +++ b/man/man3/pipe.3 @@ -0,0 +1,74 @@ +.TH PIPE 3 +.SH NAME +pipe \- create an interprocess channel +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int pipe(int fd[2]) +.SH DESCRIPTION +.I Pipe +creates a buffered channel for interprocess I/O communication. +Two file descriptors are returned in +.IR fd . +Data written to +.B fd[1] +is available for reading from +.B fd[0] +and data written to +.B fd[0] +is available for reading from +.BR fd[1] . +.PP +After the pipe has been established, +cooperating processes +created by subsequent +.IR fork (2) +calls may pass data through the +pipe with +.I read +and +.I write +calls. +The bytes placed on a pipe +by one +.I write +are contiguous even if many processes are writing. +Write boundaries are preserved: each read terminates +when the read buffer is full or after reading the last byte +of a write, whichever comes first. +.PP +The number of bytes available to a +.IR read (2) +is reported +in the +.B Length +field returned by +.I fstat +or +.I dirfstat +on a pipe (see +.IR stat (2)). +.PP +When all the data has been read from a pipe and the writer has closed the pipe or exited, +.IR read (2) +will return 0 bytes. Writes to a pipe with no reader will generate a note +.BR "sys: write on closed pipe" . +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR read (2), +.IR pipe (3) +.SH DIAGNOSTICS +Sets +.IR errstr . +.SH BUGS +If a read or a write of a pipe is interrupted, some unknown +number of bytes may have been transferred. +.br +When a read from a pipe returns 0 bytes, it usually means end of file +but is indistinguishable from reading the result of an explicit +write of zero bytes. diff --git a/man/man3/plumb.3 b/man/man3/plumb.3 new file mode 100644 index 00000000..e51a658f --- /dev/null +++ b/man/man3/plumb.3 @@ -0,0 +1,240 @@ +.TH PLUMB 3 +.SH NAME +eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLPlumbattr* 'u +.PP +.B +int plumbopen(char *port, int omode) +.PP +.B +int plumbsend(int fd, Plumbmsg *m) +.PP +.B +int plumbsendtext(int fd, char *src, char *dst, char *wdir, char *data) +.PP +.B +void plumbfree(Plumbmsg *m) +.PP +.B +Plumbmsg* plumbrecv(int fd) +.PP +.B +char* plumbpack(Plumbmsg *m, int *np) +.PP +.B +Plumbmsg* plumbunpack(char *buf, int n) +.PP +.B +Plumbmsg* plumbunpackpartial(char *buf, int n, int *morep) +.PP +.B +char* plumbpackattr(Plumbattr *a) +.PP +.B +Plumbattr* plumbunpackattr(char *a) +.PP +.B +char* plumblookup(Plumbattr *a, char *name) +.PP +.B +Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new) +.PP +.B +Plumbattr* plumbdelattr(Plumbattra *a, char *name) +.PP +.B +int eplumb(int key, char *port) +.SH DESCRIPTION +These routines manipulate +.IR plumb (6) +messages, transmitting them, receiving them, and +converting them between text and these data structures: +.IP +.EX +.ta 6n +\w'\fLPlumbattr 'u +\w'ndata; 'u +typedef +struct Plumbmsg +{ + char *src; + char *dst; + char *wdir; + char *type; + Plumbattr *attr; + int ndata; + char *data; +} Plumbmsg; + +typedef +struct Plumbattr +{ + char *name; + char *value; + Plumbattr *next; +} Plumbattr; +.EE +.PP +.I Plumbopen +opens the named plumb +.IR port , +using +.IR open (2) +mode +.IR omode . +If +.I port +begins with a slash, it is taken as a literal file name; +otherwise +.I plumbopen +searches for the location of the +.IR plumber (4) +service and opens the port there. +.PP +For programs using the +.IR event (2) +interface, +.I eplumb +registers, using the given +.IR key , +receipt of messages from the named +.IR port . +.PP +.I Plumbsend +formats and writes message +.I m +to the file descriptor +.IR fd , +which will usually be the result of +.B plumbopen("send", +.BR OWRITE) . +.I Plumbsendtext +is a simplified version for text-only messages; it assumes +.B type +is +.BR text , +sets +.B attr +to nil, +and sets +.B ndata +to +.BI strlen( data )\f1. +.PP +.I Plumbfree +frees all the data associated with the message +.IR m , +all the components of which must therefore have been allocated with +.IR malloc (2). +.PP +.I Plumbrecv +returns the next message available on the file descriptor +.IR fd , +or nil for error. +.PP +.I Plumbpack +encodes message +.I m +as a character string in the format of +.IR plumb (6) , +setting +.BI * np +to the length in bytes of the string. +.I Plumbunpack +does the inverse, translating the +.I n +bytes of +.I buf +into a +.BR Plumbmsg . +.PP +.I Plumbunpackpartial +enables unpacking of messages that arrive in pieces. +The first call to +.I plumbunpackpartial +for a given message must be sufficient to unpack the header; +subsequent calls permit unpacking messages with long data sections. +For each call, +.I buf +points to the beginning of the complete message received so far, and +.I n +reports the total number of bytes received for that message. +If the message is complete, the return value will be as in +.IR plumbunpack . +If not, and +.I morep +is not null, the return value will be +.B nil +and +.BR * morep +will be set to the number of bytes remaining to be read for this message to be complete +(recall that the byte count is in the header). +Those bytes should be read by the caller, placed at location +.IB buf + n \f1, +and the message unpacked again. +If an error is encountered, the return value will be +.B nil +and +.BI * morep +will be zero. +.PP +.I Plumbpackattr +converts the list +.I a +of +.B Plumbattr +structures into a null-terminated string. +If an attribute value contains white space, quote characters, or equal signs, +the value will be quoted appropriately. +A newline character will terminate processing. +.I Plumbunpackattr +converts the null-terminated string +.I a +back into a list of +.I Plumbattr +structures. +.PP +.I Plumblookup +searches the +.B Plumbattr +list +.I a +for an attribute with the given +.I name +and returns the associated value. +The returned string is the original value, not a copy. +If the attribute has no value, the returned value will be the empty string; +if the attribute does not occur in the list at all, the value will be nil. +.PP +.I Plumbaddattr +appends the +.I new +.B Plumbattr +(which may be a list) to the attribute list +.IR a +and returns the new list. +.I Plumbattr +searches the list +.I a +for the first attribute with name +.I name +and deletes it from the list, returning the resulting list. +.I Plumbdelattr +is a no-op if no such attribute exists. +.SH SOURCE +.B /sys/src/libplumb +.SH SEE ALSO +.IR plumb (1), +.IR event (2), +.IR plumber (4), +.IR plumb (6) +.SH DIAGNOSTICS +When appropriate, including when a +.I plumbsend +fails, these routine set +.IR errstr . diff --git a/man/man3/pool.3 b/man/man3/pool.3 new file mode 100644 index 00000000..0c9a8d49 --- /dev/null +++ b/man/man3/pool.3 @@ -0,0 +1,329 @@ +.TH POOL 3 +.SH NAME +poolalloc, poolfree, poolmsize, poolrealloc, poolcompact, poolcheck, poolblockcheck, +pooldump \- general memory management routines +.SH SYNOPSIS +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B +void* poolalloc(Pool* pool, ulong size) +.PP +.B +void poolfree(Pool* pool, void* ptr) +.PP +.B +ulong poolmsize(Pool* pool, void* ptr) +.PP +.B +void* poolrealloc(Pool* pool, void* ptr, ulong size) +.PP +.B +void poolcompact(Pool* pool) +.PP +.B +void poolcheck(Pool *pool) +.PP +.B +void poolblockcheck(Pool *pool, void *ptr) +.PP +.B +void pooldump(Pool *pool); +.SH DESCRIPTION +These routines provide a general memory management facility. +Memory is retrieved from a coarser allocator (e.g. +.I sbrk +or the kernel's +.IR xalloc ) +and then allocated to callers. +The routines are locked and thus may safely be used in +multiprocess programs. +.PP +.I Poolalloc +attempts to allocate a block of size +.BR size ; +it returns a pointer to the block when successful and nil otherwise. +The call +.B "poolalloc(0) +returns a non-nil pointer. +.I Poolfree +returns an allocated block to the pool. +It is an error to free a block more than once or to free a +pointer not returned by +.IR poolalloc . +The call +.B "poolfree(nil) +is legal and is a no-op. +.I Poolrealloc +attempts to resize to +.B nsize +bytes the block associated with +.BR ptr , +which must have been previously returned by +.I poolalloc +or +.IR poolrealloc . +If the block's size can be adjusted, a (possibly different) pointer to the new block is returned. +The contents up to the lesser of the old and new sizes are unchanged. +After a successful call to +.IR poolrealloc , +the return value should be used rather than +.B ptr +to access the block. +If the request cannot be satisfied, +.I poolrealloc +returns nil, and the old pointer remains valid. +.PP +When blocks are allocated, there is often some extra space left at the end +that would usually go unused. +.IR Poolmsize +grows the block to encompass this extra space and returns the new size. +.PP +The +.I poolblockcheck +and +.I poolcheck +routines validate a single allocated block or the entire pool, respectively. +They call +.B panic +(see below) +if corruption is detected. +.I Pooldump +prints a summary line for every block in the +pool, using the +.B print +function (see below). +.PP +The +.B Pool +structure itself provides much of the setup interface. +.IP +.EX +.ta \w'\fL 'u +\w'\fLulong 'u +\w'\fLlastcompact; 'u +typedef struct Pool Pool; +struct Pool { + char* name; + ulong maxsize; /* of entire Pool */ + ulong cursize; /* of Pool */ + ulong curfree; /* total free bytes in Pool */ + ulong curalloc; /* total allocated bytes in Pool */ + ulong minarena; /* smallest size of new arena */ + ulong quantum; /* allocated blocks should be multiple of */ + ulong minblock; /* smallest newly allocated block */ + int flags; + int nfree; /* number of calls to free */ + int lastcompact; /* nfree at time of last poolcompact */ + void* (*alloc)(ulong); + int (*merge)(void*, void*); + void (*move)(void* from, void* to); + void (*lock)(Pool*); + void (*unlock)(Pool*); + void (*print)(Pool*, char*, ...); + void (*panic)(Pool*, char*, ...); + void (*logstack)(Pool*); + void* private; +}; +.ta \w'\fL 'u +\w'POOL_ANTAGONISM 'u +enum { /* flags */ + POOL_ANTAGONISM = 1<<0, + POOL_PARANOIA = 1<<1, + POOL_VERBOSITY = 1<<2, + POOL_DEBUGGING = 1<<3, + POOL_LOGGING = 1<<4, + POOL_TOLERANCE = 1<<5, + POOL_NOREUSE = 1<<6, +}; +.EE +.PP +The pool obtains arenas of memory to manage by calling the the given +.B alloc +routine. +The total number of requested bytes will not exceed +.BR maxsize . +Each allocation request will be for at least +.B minarena +bytes. +.PP +When a new arena is allocated, the pool routines try to +merge it with the surrounding arenas, in an attempt to combat fragmentation. +If +.B merge +is non-nil, it is called with the addresses of two blocks from +.B alloc +that the pool routines suspect might be adjacent. +If they are not mergeable, +.B merge +must return zero. +If they are mergeable, +.B merge +should merge them into one block in its own bookkeeping +and return non-zero. +.PP +To ease fragmentation and make +block reuse easier, the sizes requested of the pool routines are rounded up to a multiple of +.B quantum +before +the carrying out requests. +If, after rounding, the block size is still less than +.B minblock +bytes, +.B minblock +will be used as the block size. +.PP +.I Poolcompact +defragments the pool, moving blocks in order to aggregate +the free space. +Each time it moves a block, it notifies the +.B move +routine that the contents have moved. +At the time that +.B move +is called, the contents have already moved, +so +.B from +should never be dereferenced. +If no +.B move +routine is supplied (i.e. it is nil), then calling +.I poolcompact +is a no-op. +.PP +When the pool routines need to allocate a new arena but cannot, +either because +.B alloc +has returned nil or because doing so would use more than +.B maxsize +bytes, +.I poolcompact +is called once to defragment the memory +and the request is retried. +.PP +.I Pools +are protected by the pool routines calling +.B lock +(when non-nil) +before modifying the pool, and +calling +.B unlock +when finished. +.PP +When internal corruption is detected, +.B panic +is called with a +.IR print (2) +style argument that specifies what happened. +It is assumed that +.B panic +never returns. +When the pool routines wish to convey a message +to the caller (usually because logging is turned on; see below), +.B print +is called, also with a +.IR print (2) +style argument. +.PP +.B Flags +is a bit vector that tweaks the behavior of the pool routines +in various ways. +Most are useful for debugging in one way or another. +When +.B POOL_ANTAGONISM +is set, +.I poolalloc +fills blocks with non-zero garbage before releasing them to the user, +and +.I poolfree +fills the blocks on receipt. +This tickles both user programs and the innards of the allocator. +Specifically, each 32-bit word of the memory is marked with a pointer value exclusive-or'ed +with a constant. +The pointer value is the pointer to the beginning of the allocated block +and the constant varies in order to distinguish different markings. +Freed blocks use the constant +.BR 0xF7000000 , +newly allocated blocks +.BR 0xF9000000 , +and newly created unallocated blocks +.BR 0xF1000000 . +For example, if +.B POOL_ANTAGONISM +is set and +.I poolalloc +returns a block starting at +.BR 0x00012345 , +each word of the block will contain the value +.BR 0xF90012345 . +Recognizing these numbers in memory-related crashes can +help diagnose things like double-frees or dangling pointers. +.PP +Setting +.B POOL_PARANOIA +causes the allocator to walk the entire pool whenever locking or unlocking itself, +looking for corruption. +This slows runtime by a few orders of magnitude +when many blocks are in use. +If +.B POOL_VERBOSITY +is set, +the entire pool structure is printed +(via +.BR print ) +each time the pool is locked or unlocked. +.B POOL_DEBUGGING +enables internal +debugging output, +whose format is unspecified and volatile. +It should not be used by most programs. +When +.B POOL_LOGGING +is set, a single line is printed via +.B print +at the beginning and end of each pool call. +If +.B logstack +is not nil, +it will be called as well. +This provides a mechanism for external programs to search for leaks. +(See +.IR leak (1) +for one such program.) +.PP +The pool routines are strict about the amount of space callers use. +If even a single byte is written past the end of the allotted space of a block, they +will notice when that block is next used in a call to +.I poolrealloc +or +.I free +(or at the next entry into the allocator, when +.B POOL_PARANOIA +is set), +and +.B panic +will be called. +Since forgetting to allocate space for the +terminating NUL on strings is such a common error, +if +.B POOL_TOLERANCE +is set and a single NUL is found written past the end of a block, +.B print +will be called with a notification, but +.B panic +will not be. +.PP +When +.B POOL_NOREUSE +is set, +.B poolfree +fills the passed block with garbage rather than +return it to the free pool. +.SH SOURCE +.B /sys/src/libc/port/pool.c +.SH SEE ALSO +.IR malloc (2), +.IR brk (2) +.PP +.B /sys/src/libc/port/malloc.c +is a complete example. diff --git a/man/man3/postnote.3 b/man/man3/postnote.3 new file mode 100644 index 00000000..20766da1 --- /dev/null +++ b/man/man3/postnote.3 @@ -0,0 +1,49 @@ +.TH POSTNOTE 3 +.SH NAME +postnote \- send a note to a process or process group +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +int postnote(int who, int pid, char *note) +.fi +.SH DESCRIPTION +.I Postnote +sends a note to a process or process group. +If +.I who +is +.BR PNPROC , +then +.I note +is written to +.BI /proc/ pid /note\f1. +If +.I who +is +.BI PNGROUP , +the note is delivered to the +process group by writing +.I note +to +.BI /proc/ pid /notepg\f1. +For +.B PNGROUP +only, if the calling process is in the target group, the note is +.I not +delivered to that process. +.PP +If the write is successful, zero is returned. +Otherwise \-1 is returned. +.SH SOURCE +.B /sys/src/libc/9sys/postnote.c +.SH "SEE ALSO" +.IR notify (2), +.IR intro (2), +.IR proc (3) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/man/man3/prime.3 b/man/man3/prime.3 new file mode 100644 index 00000000..be9fabe6 --- /dev/null +++ b/man/man3/prime.3 @@ -0,0 +1,100 @@ +.TH PRIME 3 +.SH NAME +genprime, gensafeprime, genstrongprime, DSAprimes, probably_prime, smallprimetest \- prime number generation +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +int smallprimetest(mpint *p) +.PP +.B +int probably_prime(mpint *p, int nrep) +.PP +.B +void genprime(mpint *p, int n, int nrep) +.PP +.B +void gensafeprime(mpint *p, mpint *alpha, int n, int accuracy) +.PP +.B +void genstrongprime(mpint *p, int n, int nrep) +.PP +.B +void DSAprimes(mpint *q, mpint *p, uchar seed[SHA1dlen]) +.SH DESCRIPTION +.PP +Public key algorithms abound in prime numbers. The following routines +generate primes or test numbers for primality. +.PP +.I Smallprimetest +checks for divisibility by the first 10000 primes. It returns 0 +if +.I p +is not divisible by the primes and \-1 if it is. +.PP +.I Probably_prime +uses the Miller-Rabin test to test +.IR p . +It returns non-zero if +.I P +is probably prime. The probability of it not being prime is +1/4**\fInrep\fR. +.PP +.I Genprime +generates a random +.I n +bit prime. Since it uses the Miller-Rabin test, +.I nrep +is the repetition count passed to +.IR probably_prime . +.I Gensafegprime +generates an +.IR n -bit +prime +.I p +and a generator +.I alpha +of the multiplicative group of integers mod \fIp\fR; +there is a prime \fIq\fR such that \fIp-1=2*q\fR. +.I Genstrongprime +generates a prime, +.IR p , +with the following properties: +.IP \- +(\fIp\fR-1)/2 is prime. Therefore +.IR p -1 +has a large prime factor, +.IR p '. +.IP \- +.IR p '-1 +has a large prime factor +.IP \- +.IR p +1 +has a large prime factor +.PP +.I DSAprimes +generates two primes, +.I q +and +.IR p, +using the NIST recommended algorithm for DSA primes. +.I q +divides +.IR p -1. +The random seed used is also returned, so that skeptics +can later confirm the computation. Be patient; this is a +slow algorithm. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR aes (2) +.IR blowfish (2), +.IR des (2), +.IR elgamal (2), +.IR rsa (2), diff --git a/man/man3/quote.3 b/man/man3/quote.3 new file mode 100644 index 00000000..8f5ccede --- /dev/null +++ b/man/man3/quote.3 @@ -0,0 +1,167 @@ +.TH QUOTE 3 +.SH NAME +quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote, needsrcquote \- quoted character strings +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +char *quotestrdup(char *s) +.PP +.B +Rune *quoterunestrdup(Rune *s) +.PP +.B +char *unquotestrdup(char *s) +.PP +.B +Rune *unquoterunestrdup(Rune *s) +.PP +.B +int quotestrfmt(Fmt*) +.PP +.B +int quoterunestrfmt(Fmt*) +.PP +.B +void quotefmtinstall(void) +.PP +.B +int (*doquote)(int c) +.PP +.B +int needsrcquote(int c) +.PP +.SH DESCRIPTION +These routines manipulate character strings, either adding or removing +quotes as necessary. +In the quoted form, the strings are in the style of +.IR rc (1) , +with single quotes surrounding the string. +Embedded single quotes are indicated by a doubled single quote. +For instance, +.IP +.EX +Don't worry! +.EE +.PP +when quoted becomes +.IP +.EX +\&'Don''t worry!' +.EE +.PP +The empty string is represented by two quotes, +.BR '' . +.PP +The first four functions act as variants of +.B strdup +(see +.IR strcat (2)). +Each returns a +freshly allocated copy of the string, created using +.IR malloc (2). +.I Quotestrdup +returns a quoted copy of +.IR s , +while +.I unquotestrdup +returns a copy of +.IR s +with the quotes evaluated. +The +.I rune +versions of these functions do the same for +.CW Rune +strings (see +.IR runestrcat (2)). +.PP +The string returned by +.I quotestrdup +or +.I quoterunestrdup +has the following properties: +.TP +1. +If the original string +.IR s +is empty, the returned string is +.BR '' . +.TP +2. +If +.I s +contains no quotes, blanks, or control characters, +the returned string is identical to +.IR s . +.TP +3. +If +.I s +needs quotes to be added, the first character of the returned +string will be a quote. +For example, +.B hello\ world +becomes +.B \&'hello\ world' +not +.BR hello'\ 'world . +.PP +The function pointer +.I doquote +is +.B nil +by default. +If it is non-nil, characters are passed to that function to see if they should +be quoted. +This mechanism allows programs to specify that +characters other than blanks, control characters, or quotes be quoted. +Regardless of the return value of +.IR *doquote , +blanks, control characters, and quotes are always quoted. +.I Needsrcquote +is provided as a +.I doquote +function that flags any character special to +.IR rc (1). +.PP +.I Quotestrfmt +and +.I quoterunestrfmt +are +.IR print (2) +formatting routines that produce quoted strings as output. +They may be installed by hand, but +.I quotefmtinstall +installs them under the standard format characters +.B q +and +.BR Q . +(They are not installed automatically.) +If the format string includes the alternate format character +.BR # , +for example +.BR %#q , +the printed string will always be quoted; otherwise quotes will only be provided if necessary +to avoid ambiguity. +In +.B +there are +.B #pragma +statements so the compiler can type-check uses of +.B %q +and +.B %Q +in +.IR print (2) +format strings. +.SH SOURCE +.B /sys/src/libc/port/quote.c +.br +.B /sys/src/libc/fmt/fmtquote.c +.SH "SEE ALSO +.IR rc (1), +.IR malloc (2), +.IR print (2), +.IR strcat (2) diff --git a/man/man3/rand.3 b/man/man3/rand.3 new file mode 100644 index 00000000..a6296e9a --- /dev/null +++ b/man/man3/rand.3 @@ -0,0 +1,175 @@ +.TH RAND 3 +.SH NAME +rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, fastrand, nfastrand \- random number generator +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLdouble 'u +.B +int rand(void) +.PP +.B +long lrand(void) +.PP +.B +double frand(void) +.PP +.B +int nrand(int val) +.PP +.B +long lnrand(long val) +.PP +.B +void srand(long seed) +.PP +.B +ulong truerand(void) +.PP +.B +ulong ntruerand(ulong val) +.sp +.B #include +.br +.B #include +.PP +.B +void genrandom(uchar *buf, int nbytes) +.PP +.B +void prng(uchar *buf, int nbytes) +.PP +.B +ulong fastrand(void) +.PP +.B +ulong nfastrand(ulong val) +.SH DESCRIPTION +.I Rand +returns a uniform pseudo-random +number +.IR x , +.RI 0≤ x <2\u\s715\s10\d. +.PP +.I Lrand +returns a uniform +.B long +.IR x , +.RI 0≤ x <2\u\s731\s10\d. +.PP +.I Frand +returns a uniform +.B double +.IR x , +.RI 0.0≤ x <1.0, +This function calls +.I lrand +twice to generate a number with as many as 62 significant bits of mantissa. +.PP +.I Nrand +returns a uniform integer +.IR x , +.RI 0≤ x < val. +.I Lnrand +is the same, but returns a +.BR long . +.PP +The algorithm is additive feedback with: +.IP +x[n] = (x[n\(mi273] + x[n\(mi607]) mod +.if t 2\u\s731\s0\d +.if n 2^31 +.LP +giving a period of +.if t 2\u\s730\s10\d \(mu (2\u\s7607\s10\d \- 1). +.if n 2^30 × (2^607 - 1). +.PP +The generators are initialized by calling +.I srand +with whatever you like as argument. +To get a different starting value each time, +.IP +.L +srand(time(0)) +.LP +will work as long as it is not called more often +than once per second. +Calling +.IP +.L +srand(1) +.LP +will initialize the generators to their +starting state. +.PP +.I Truerand +returns a random unsigned long read from +.BR /dev/random . +Due to the nature of +.BR /dev/random , +truerand can only return a few hundred bits a +second. +.PP +.I Ntruerand +returns a uniform random integer +.IR x , +.RI 0≤ x < val ≤ 2\u\s732\s10\d-1. +.PP +.I Genrandom +fills a buffer with bytes from the X9.17 pseudo-random +number generator. The X9.17 generator is seeded by 24 +truly random bytes read from +.BR /dev/random . +.PP +.I Prng +uses the native +.IR rand (2) +pseudo-random number generator to fill the buffer. Used with +.IR srand , +this function can produce a reproducible stream of pseudo random +numbers useful in testing. +.PP +Both +.I genrandom +and +.I prng +may be passed to +.I mprand +(see +.IR mp (2)). +.PP +.I Fastrand +uses +.I genrandom +to return a uniform +.B "unsigned long +.IR x , +.RI 0≤ x < 2\u\s732\s10\d-1. +.PP +.I Nfastrand +uses +.I genrandom +to return a uniform +.B "unsigned long +.IR x , +.RI 0≤ x < val ≤ 2\u\s732\s10\d-1. +.SH SOURCE +.B /sys/src/libc/port/*rand.c +.br +.B /sys/src/libc/9sys/truerand.c +.br +.B /sys/src/libsec/port/genrandom.c +.br +.B /sys/src/libsec/port/prng.c +.br +.B /sys/src/libsec/port/*fastrand.c +.SH "SEE ALSO +.IR cons (3), +.IR mp (2), +.SH BUGS +.I Truerand +and +.I ntruerand +maintain a static file descriptor. diff --git a/man/man3/rc4.3 b/man/man3/rc4.3 new file mode 100644 index 00000000..fb0c94db --- /dev/null +++ b/man/man3/rc4.3 @@ -0,0 +1,55 @@ +.TH RC4 3 +.SH NAME +setupRC4state, rc4, rc4skip, rc4back - alleged rc4 encryption +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void setupRC4state(RC4state *s, uchar *seed, int slen) +.PP +.B +void rc4(RC4state *s, uchar *data, int dlen) +.PP +.B +void rc4skip(RC4state *s, int nbytes) +.PP +.B +void rc4back(RC4state *s, int nbytes) +.SH DESCRIPTION +.PP +This is an algorithm alleged to be Rivest's RC4 encryption function. It is +a pseudo-random number generator with a 256 byte state and a long +cycle. The input buffer is XOR'd with the output of the +generator both to encrypt and to decrypt. The seed, entered +using +.IR setupRC4state , +can be any length. The generator can be run forward using +.IR rc4 , +skip over bytes using +.I rc4skip +to account lost transmissions, +or run backwards using +.I rc4back +to cover retransmitted data. +The +.I RC4state +structure keeps track of the algorithm. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR dsa (2), +.IR elgamal (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/man/man3/read.3 b/man/man3/read.3 new file mode 100644 index 00000000..ab1979a8 --- /dev/null +++ b/man/man3/read.3 @@ -0,0 +1,95 @@ +.TH READ 3 +.SH NAME +read, readn, write, pread, pwrite \- read or write file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +long read(int fd, void *buf, long nbytes) +.PP +.B +long readn(int fd, void *buf, long nbytes) +.PP +.B +long write(int fd, void *buf, long nbytes) +.PP +.B +long pread(int fd, void *buf, long nbytes, vlong offset) +.PP +.B +long pwrite(int fd, void *buf, long nbytes, vlong offset) +.SH DESCRIPTION +.I Read +reads +.I nbytes +bytes of data +from the offset in the file associated with +.I fd +into memory at +.IR buf . +The offset is advanced by the number of bytes read. +It is not guaranteed +that all +.I nbytes +bytes will be read; for example +if the file refers to the console, at most one line +will be returned. +In any event the number of bytes read is returned. +A return value of +0 is conventionally interpreted as end of file. +.PP +.I Readn +is just like read, but does successive +.I read +calls until +.I nbytes +have been read, or a read system call +returns a non-positive count. +.PP +.I Write +writes +.I nbytes +bytes of data starting at +.I buf +to the file associated with +.I fd +at the file offset. +The offset is advanced by the number of bytes written. +The number of characters actually written is returned. +It should be regarded as an error +if this is not the same as requested. +.PP +.I Pread +and +.I Pwrite +equivalent to a +.IR seek (2) +to +.I offset +followed by a +.I read +or +.IR write . +By combining the operations in a single atomic call, they more closely +match the 9P protocol +(see +.IR intro (5)) +and, more important, +permit multiprocess programs to execute multiple concurrent +read and write operations on the same file descriptor +without interference. +.SH SOURCE +.B /sys/src/libc/9syscall +.br +.B /sys/src/libc/port/readn.c +.SH SEE ALSO +.IR intro (2), +.IR open (2), +.IR dup (2), +.IR pipe (2), +.IR readv (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/man/man3/readv.3 b/man/man3/readv.3 new file mode 100644 index 00000000..76615389 --- /dev/null +++ b/man/man3/readv.3 @@ -0,0 +1,82 @@ +.TH READV 3 +.SH NAME +readv, writev, preadv, pwritev \- scatter/gather read and write +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.ft L +typedef +struct IOchunk +{ + void *addr; + ulong len; +} IOchunk; +.fi +.PP +.B +long readv(int fd, IOchunk *io, int nio) +.PP +.B +long preadv(int fd, IOchunk *io, int nio, vlong off) +.PP +.B +long writev(int fd, IOchunk *io, int nio) +.PP +.B +long pwritev(int fd, IOchunk *io, int nio, vlong off) +.SH DESCRIPTION +These functions supplement the standard read and write operations of +.IR read (2) +with facilities for scatter/gather I/O. +The set of I/O buffers is collected into an array of +.B IOchunk +structures passed as an argument. +.PP +.I Readv +reads data from +.I fd +and returns the total number of bytes received. +The received data is stored in the successive +.I nio +elements of the +.B IOchunk +array, storing +.IB io [0].len +bytes at +.IB io [0].addr\f1, +the next +.IB io [1].len +at +.IB io [1].addr\f1, +and so on. +.I Preadv +does the same, but implicitly seeks to I/O offset +.I off +by analogy with +.IR readv . +.PP +.I Writev +and +.I pwritev +are the analogous write routines. +.SH SOURCE +.B /sys/src/libc/9sys/readv.c +.br +.B /sys/src/libc/9sys/writev.c +.SH SEE ALSO +.IR intro (2), +.IR read (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . +.SH BUGS +The implementations use +.IR malloc (2) +to build a single buffer for a standard call to +.B read +or +.BR write . +They are placeholders for possible future system calls. diff --git a/man/man3/regexp.3 b/man/man3/regexp.3 new file mode 100644 index 00000000..13c974c3 --- /dev/null +++ b/man/man3/regexp.3 @@ -0,0 +1,212 @@ +.TH REGEXP 3 +.SH NAME +regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, regerror \- regular expression +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLRegprog 'u +.B +Reprog *regcomp(char *exp) +.PP +.B +Reprog *regcomplit(char *exp) +.PP +.B +Reprog *regcompnl(char *exp) +.PP +.nf +.B +int regexec(Reprog *prog, char *string, Resub *match, int msize) +.PP +.nf +.B +void regsub(char *source, char *dest, int dlen, Resub *match, int msize) +.PP +.nf +.B +int rregexec(Reprog *prog, Rune *string, Resub *match, int msize) +.PP +.nf +.B +void rregsub(Rune *source, Rune *dest, int dlen, Resub *match, int msize) +.PP +.B +void regerror(char *msg) +.SH DESCRIPTION +.I Regcomp +compiles a +regular expression and returns +a pointer to the generated description. +The space is allocated by +.IR malloc (2) +and may be released by +.IR free . +Regular expressions are exactly as in +.IR regexp (6). +.PP +.I Regcomplit +is like +.I regcomp +except that all characters are treated literally. +.I Regcompnl +is like +.I regcomp +except that the +.B . +metacharacter matches all characters, including newlines. +.PP +.I Regexec +matches a null-terminated +.I string +against the compiled regular expression in +.IR prog . +If it matches, +.I regexec +returns +.B 1 +and fills in the array +.I match +with character pointers to the substrings of +.I string +that correspond to the +parenthesized subexpressions of +.IR exp : +.BI match[ i ].sp +points to the beginning and +.BI match[ i ].ep +points just beyond +the end of the +.IR i th +substring. +(Subexpression +.I i +begins at the +.IR i th +left parenthesis, counting from 1.) +Pointers in +.B match[0] +pick out the substring that corresponds to +the whole regular expression. +Unused elements of +.I match +are filled with zeros. +Matches involving +.LR * , +.LR + , +and +.L ? +are extended as far as possible. +The number of array elements in +.I match +is given by +.IR msize . +The structure of elements of +.I match +is: +.IP +.EX +typedef struct { + union { + char *sp; + Rune *rsp; + }; + union { + char *ep; + Rune *rep; + }; +} Resub; +.EE +.LP +If +.B match[0].sp +is nonzero on entry, +.I regexec +starts matching at that point within +.IR string . +If +.B match[0].ep +is nonzero on entry, +the last character matched is the one +preceding that point. +.PP +.I Regsub +places in +.I dest +a substitution instance of +.I source +in the context of the last +.I regexec +performed using +.IR match . +Each instance of +.BI \e n\f1, +where +.I n +is a digit, is replaced by the +string delimited by +.BI match[ n ].sp +and +.BI match[ n ].ep\f1. +Each instance of +.L & +is replaced by the string delimited by +.B match[0].sp +and +.BR match[0].ep . +The substitution will always be null terminated and +trimmed to fit into dlen bytes. +.PP +.IR Regerror , +called whenever an error is detected in +.IR regcomp , +writes the string +.I msg +on the standard error file and exits. +.I Regerror +can be replaced to perform +special error processing. +If the user supplied +.I regerror +returns rather than exits, +.I regcomp +will return 0. +.PP +.I Rregexec +and +.I rregsub +are variants of +.I regexec +and +.I regsub +that use strings of +.B Runes +instead of strings of +.BR chars . +With these routines, the +.I rsp +and +.I rep +fields of the +.I match +array elements should be used. +.SH SOURCE +.B /sys/src/libregexp +.SH "SEE ALSO" +.IR grep (1) +.SH DIAGNOSTICS +.I Regcomp +returns +.B 0 +for an illegal expression +or other failure. +.I Regexec +returns 0 +if +.I string +is not matched. +.SH BUGS +There is no way to specify or match a NUL character; NULs terminate patterns and strings. diff --git a/man/man3/regexp9.3 b/man/man3/regexp9.3 deleted file mode 100644 index f2603562..00000000 --- a/man/man3/regexp9.3 +++ /dev/null @@ -1,227 +0,0 @@ -.TH REGEXP9 3 -.de EX -.nf -.ft B -.. -.de EE -.fi -.ft R -.. -.de LR -.if t .BR \\$1 \\$2 -.if n .RB ` \\$1 '\\$2 -.. -.de L -.nh -.if t .B \\$1 -.if n .RB ` \\$1 ' -.. -.SH NAME -regcomp, regcomplit, regcompnl, regexec, regsub, regerror \- Plan 9 regular expression library -.SH SYNOPSIS -.B #include -.PP -.ta \w'\fLRegprog 'u -.B -Reprog *regcomp(char *exp) -.PP -.B -Reprog *regcomplit(char *exp) -.PP -.B -Reprog *regcompnl(char *exp) -.PP -.nf -.B -int regexec(Reprog *prog, char *string, Resub *match, int msize) -.PP -.nf -.B -void regsub(char *source, char *dest, int dlen, Resub *match, int msize) -.PP -.nf -.B -int rregexec(Reprog *prog, Rune *string, Resub *match, int msize) -.PP -.nf -.B -void rregsub(Rune *source, Rune *dest, int dlen, Resub *match, int msize) -.PP -.B -void regerror(char *msg) -.SH DESCRIPTION -.I Regcomp -compiles a -regular expression and returns -a pointer to the generated description. -The space is allocated by -.IR malloc (3) -and may be released by -.IR free . -Regular expressions are exactly as in -.IR regexp9 (7). -.PP -.I Regcomplit -is like -.I regcomp -except that all characters are treated literally. -.I Regcompnl -is like -.I regcomp -except that the -.B . -metacharacter matches all characters, including newlines. -.PP -.I Regexec -matches a null-terminated -.I string -against the compiled regular expression in -.IR prog . -If it matches, -.I regexec -returns -.B 1 -and fills in the array -.I match -with character pointers to the substrings of -.I string -that correspond to the -parenthesized subexpressions of -.IR exp : -.BI match[ i ].sp -points to the beginning and -.BI match[ i ].ep -points just beyond -the end of the -.IR i th -substring. -(Subexpression -.I i -begins at the -.IR i th -left parenthesis, counting from 1.) -Pointers in -.B match[0] -pick out the substring that corresponds to -the whole regular expression. -Unused elements of -.I match -are filled with zeros. -Matches involving -.LR * , -.LR + , -and -.L ? -are extended as far as possible. -The number of array elements in -.I match -is given by -.IR msize . -The structure of elements of -.I match -is: -.IP -.EX -typedef struct { - union { - char *sp; - Rune *rsp; - } s; - union { - char *ep; - Rune *rep; - } e; -} Resub; -.EE -.LP -If -.B match[0].s.sp -is nonzero on entry, -.I regexec -starts matching at that point within -.IR string . -If -.B match[0].e.ep -is nonzero on entry, -the last character matched is the one -preceding that point. -.PP -.I Regsub -places in -.I dest -a substitution instance of -.I source -in the context of the last -.I regexec -performed using -.IR match . -Each instance of -.BI \e n\f1, -where -.I n -is a digit, is replaced by the -string delimited by -.BI match[ n ].s.sp -and -.BI match[ n ].e.ep\f1. -Each instance of -.L & -is replaced by the string delimited by -.B match[0].s.sp -and -.BR match[0].e.ep . -The substitution will always be null terminated and -trimmed to fit into dlen bytes. -.PP -.IR Regerror , -called whenever an error is detected in -.IR regcomp , -writes the string -.I msg -on the standard error file and exits. -.I Regerror -can be replaced to perform -special error processing. -If the user supplied -.I regerror -returns rather than exits, -.I regcomp -will return 0. -.PP -.I Rregexec -and -.I rregsub -are variants of -.I regexec -and -.I regsub -that use strings of -.B Runes -instead of strings of -.BR chars . -With these routines, the -.I rsp -and -.I rep -fields of the -.I match -array elements should be used. -.SH "SEE ALSO" -.IR grep (1), -.IR regexp9 (7) -.SH DIAGNOSTICS -.I Regcomp -returns -.B 0 -for an illegal expression -or other failure. -.I Regexec -returns 0 -if -.I string -is not matched. -.SH HISTORY -This particular regular expression was first written by Rob Pike for Plan 9. -It has also appeared as part of the Inferno operating system. -.SH BUGS -There is no way to specify or match a NUL character; NULs terminate patterns and strings. diff --git a/man/man3/remove.3 b/man/man3/remove.3 new file mode 100644 index 00000000..73896c4f --- /dev/null +++ b/man/man3/remove.3 @@ -0,0 +1,31 @@ +.TH REMOVE 3 +.SH NAME +remove \- remove a file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int remove(char *file) +.SH DESCRIPTION +.I Remove +removes +.I file +from the directory containing it and discards the contents of the file. +The user must have write permission in the containing directory. +If +.I file +is a directory, it must be empty. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR remove (5), +the description of +.B ORCLOSE +in +.IR open (2). +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/man/man3/rendezvous.3 b/man/man3/rendezvous.3 new file mode 100644 index 00000000..54cb6b6d --- /dev/null +++ b/man/man3/rendezvous.3 @@ -0,0 +1,57 @@ +.TH RENDEZVOUS 3 +.SH NAME +rendezvous \- user level process synchronization +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +ulong rendezvous(ulong tag, ulong value) +.SH DESCRIPTION +The rendezvous system call allows two processes to synchronize and +exchange a value. +In conjunction with the shared memory system calls +(see +.IR segattach (2) +and +.IR fork (2)), +it enables parallel programs to control their scheduling. +.PP +Two processes wishing to synchronize call +.I rendezvous +with a common +.IR tag , +typically an address in +memory they share. +One process will arrive at the rendezvous first; +it suspends execution until a second arrives. +When a second process meets the rendezvous +the +.I value +arguments are exchanged between the processes and returned +as the result of the respective +.I rendezvous +system calls. +Both processes are awakened when +the rendezvous succeeds. +.PP +The set of tag values which two processes may use to rendezvous\(emtheir tag space\(emis +inherited when a process forks, unless +.B RFREND +is set in the argument to +.BR rfork ; +see +.IR fork (2). +.PP +If a rendezvous is interrupted the return value is +.BR ~0 , +so that value should not be used in normal communication. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR segattach (2), +.IR fork (2) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/man/man3/rsa.3 b/man/man3/rsa.3 new file mode 100644 index 00000000..58537bfa --- /dev/null +++ b/man/man3/rsa.3 @@ -0,0 +1,202 @@ +.TH RSA 3 +.SH NAME +asn1dump, +asn1toRSApriv, +decodepem, +rsadecrypt, +rsaencrypt, +rsagen, +rsaprivalloc, +rsaprivfree, +rsaprivtopub, +rsapuballoc, +rsapubfree, +X509toRSApub, +X509gen, +X509verify \- RSA encryption algorithm +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +RSApriv* rsagen(int nlen, int elen, int nrep) +.PP +.B +mpint* rsaencrypt(RSApub *k, mpint *in, mpint *out) +.PP +.B +mpint* rsadecrypt(RSApriv *k, mpint *in, mpint *out) +.PP +.B +RSApub* rsapuballoc(void) +.PP +.B +void rsapubfree(RSApub*) +.PP +.B +RSApriv* rsaprivalloc(void) +.PP +.B +void rsaprivfree(RSApriv*) +.PP +.B +RSApub* rsaprivtopub(RSApriv*) +.PP +.B +RSApub* X509toRSApub(uchar *cert, int ncert, char *name, int nname) +.PP +.B +RSApriv* asn1toRSApriv(uchar *priv, int npriv) +.PP +.B +void asn1dump(uchar *der, int len) +.PP +.B +uchar* decodepem(char *s, char *type, int *len) +.PP +.B +uchar* X509gen(RSApriv *priv, char *subj, ulong valid[2], int *certlen); +.PP +.B +uchar* X509req(RSApriv *priv, char *subj, int *certlen); +.PP +.B +char* X509verify(uchar *cert, int ncert, RSApub *pk) +.SH DESCRIPTION +.PP +RSA is a public key encryption algorithm. The owner of a key publishes +the public part of the key: +.EX + struct RSApub + { + mpint *n; // modulus + mpint *ek; // exp (encryption key) + }; +.EE +This part can be used for encrypting data (with +.IR rsaencrypt ) +to be sent to the owner. +The owner decrypts (with +.IR rsadecrypt ) +using his private key: +.EX + struct RSApriv + { + RSApub pub; + mpint *dk; // exp (decryption key) + + // precomputed crt values + mpint *p; + mpint *q; + mpint *kp; // k mod p-1 + mpint *kq; // k mod q-1 + mpint *c2; // for converting residues to number + }; +.EE +.PP +Keys are generated using +.IR rsagen . +.I Rsagen +takes both bit length of the modulus, the bit length of the +public key exponent, and the number of repetitions of the Miller-Rabin +primality test to run. If the latter is 0, it does the default number +of rounds. +.I Rsagen +returns a newly allocated structure containing both +public and private keys. +.I Rsaprivtopub +returns a newly allocated copy of the public key +corresponding to the private key. +.PP +The routines +.IR rsaalloc , +.IR rsafree , +.IR rsapuballoc , +.IR rsapubfree , +.IR rsaprivalloc , +and +.I rsaprivfree +are provided to aid in user provided key I/O. +.PP +Given a binary X.509 +.IR cert , +the routine +.I X509toRSApub +returns the public key and, if +.I name +is not nil, the CN part of the Distinguished Name of the +certificate's Subject. +(This is conventionally a userid or a host DNS name.) +No verification is done of the certificate signature; the +caller should check the fingerprint, +.IR sha1(cert) , +against a table or check the certificate by other means. +X.509 certificates are often stored in PEM format; use +.I dec64 +to convert to binary before computing the fingerprint or calling +.IR X509toRSApub . +For the special case of +certificates signed by a known trusted key +(in a single step, without certificate chains) +.I X509verify +checks the signature on +.IR cert . +It returns nil if successful, else an error string. +.PP +.I X509gen +creates a self-signed X.509 certificate, given an RSA keypair +.IR priv , +a issuer/subject string +.IR subj , +and the starting and ending validity dates, +.IR valid . +Length of the allocated binary certificate is stored in +.IR certlen . +The subject line is conventionally of the form +.EX + "C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric" +.EE +using the quoting conventions of +.IR tokenize (2). +.PP +.I Asn1toRSApriv +converts an ASN1 formatted RSA private key into the corresponding +.B RSApriv +structure. +.PP +.I Asn1dump +prints an ASN1 object to standard output. +.PP +.I Decodepem +takes a zero terminated string, +.IR s , +and decodes the PEM (privacy-enhanced mail) formatted section for +.I type +within it. +If successful, it returns the decoded section and sets +.BI * len +to its decoded length. +If not, it returns +.BR nil , +and +.BI * len +is undefined. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR dsa (2), +.IR elgamal (2), +.IR rc4 (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2), +.IR x509 (8) diff --git a/man/man3/rune.3 b/man/man3/rune.3 index 7ce978ae..120563be 100644 --- a/man/man3/rune.3 +++ b/man/man3/rune.3 @@ -3,7 +3,9 @@ runetochar, chartorune, runelen, runenlen, fullrune, utfecpy, utflen, utfnlen, utfrune, utfrrune, utfutf \- rune/UTF conversion .SH SYNOPSIS .ta \w'\fLchar*xx'u -.B #include +.B #include +.br +.B #include .PP .B int runetochar(char *s, Rune *r) @@ -179,9 +181,10 @@ is the null string, .I utfutf returns .IR s1 . -.SH HISTORY -These routines were written by Rob Pike and Ken Thompson -and first appeared in Plan 9. +.SH SOURCE +.B /sys/src/libc/port/rune.c +.br +.B /sys/src/libc/port/utfrune.c .SH SEE ALSO -.IR utf (7), +.IR utf (6), .IR tcs (1) diff --git a/man/man3/runestrcat.3 b/man/man3/runestrcat.3 index c012e59e..57c587cf 100644 --- a/man/man3/runestrcat.3 +++ b/man/man3/runestrcat.3 @@ -13,7 +13,9 @@ runestrrchr, runestrdup, runestrstr \- rune string operations .SH SYNOPSIS -.B #include +.B #include +.br +.B #include .PP .ta \w'\fLRune* \fP'u .B @@ -54,12 +56,12 @@ Rune* runestrstr(Rune *s1, Rune *s2) .SH DESCRIPTION These functions are rune string analogues of the corresponding functions in -.IR strcat (3). -.SH HISTORY -These routines first appeared in Plan 9. +.IR strcat (2). +.SH SOURCE +.B /sys/src/libc/port .SH SEE ALSO -.IR memmove (3), -.IR rune (3), +.IR memory (2), +.IR rune (2), .IR strcat (2) .SH BUGS The outcome of overlapping moves varies among implementations. diff --git a/man/man3/sechash.3 b/man/man3/sechash.3 new file mode 100644 index 00000000..a7342564 --- /dev/null +++ b/man/man3/sechash.3 @@ -0,0 +1,150 @@ +.TH SECHASH 3 +.SH NAME +md4, md5, sha1, hmac_md5, hmac_sha1, md5pickle, md5unpickle, sha1pickle, sha1unpickle \- cryptographically secure hashes +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +DigestState* md4(uchar *data, ulong dlen, uchar *digest, +.B + DigestState *state) +.PP +.B +DigestState* md5(uchar *data, ulong dlen, uchar *digest, +.B + DigestState *state) +.PP +.B +char* md5pickle(MD5state *state) +.PP +.B +MD5state* md5unpickle(char *p); +.PP +.B +DigestState* sha1(uchar *data, ulong dlen, uchar *digest, +.B + DigestState *state) +.PP +.B +char* sha1pickle(MD5state *state) +.PP +.B +MD5state* sha1unpickle(char *p); +.PP +.B +DigestState* hmac_md5(uchar *data, ulong dlen, +.br +.B + uchar *key, ulong klen, +.br +.B + uchar *digest, DigestState *state) +.PP +.B +DigestState* hmac_sha1(uchar *data, ulong dlen, +.br +.B + uchar *key, ulong klen, +.br +.B + uchar *digest, DigestState *state) +.SH DESCRIPTION +.PP +We support several secure hash functions. The output of the +hash is called a +.IR digest . +A hash is secure if, given the hashed data and the digest, +it is difficult to predict the change to the digest resulting +from some change to the data without rehashing +the whole data. Therefore, if a secret is part of the hashed +data, the digest can be used as an integrity check of the data by anyone +possessing the secret. +.PP +The routines +.IR md4 , +.IR md5 , +.IR sha1 , +.IR hmac_md5 , +and +.I hmac_sha1 +differ only in the length of the resulting digest +and in the security of the hash. Usage for each is the same. +The first call to the routine should have +.B nil +as the +.I state +parameter. This call returns a state which can be used to chain +subsequent calls. +The last call should have digest non-\fBnil\fR. +.I Digest +must point to a buffer of at least the size of the digest produced. +This last call will free the state and copy the result into +.IR digest . +For example, to hash a single buffer using +.IR md5 : +.EX + + uchar digest[MD5dlen]; + + md5(data, len, digest, nil); +.EE +.PP +To chain a number of buffers together, +bounded on each end by some secret: +.EX + + char buf[256]; + uchar digest[MD5dlen]; + DigestState *s; + + s = md5("my password", 11, nil, nil); + while((n = read(fd, buf, 256)) > 0) + md5(buf, n, nil, s); + md5("drowssap ym", 11, digest, s); +.EE +.PP +The constants +.IR MD4dlen , +.IR MD5dlen , +and +.I SHA1dlen +define the lengths of the digests. +.PP +.I Hmac_md5 +and +.I hmac_sha1 +are used slightly differently. These hash algorithms are keyed and require +a key to be specified on every call. +The digest lengths for these hashes are +.I MD5dlen +and +.I SHA1dlen +respectively. +.PP +The functions +.I md5pickle +and +.I sha1pickle +marshal the state of a digest for transmission. +.I Md5unpickle +and +.I sha1unpickle +unmarshal a pickled digest. +All four routines return a pointer to a newly +.IR malloc (2)'d +object. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2) diff --git a/man/man3/seek.3 b/man/man3/seek.3 new file mode 100644 index 00000000..ae3d9ef9 --- /dev/null +++ b/man/man3/seek.3 @@ -0,0 +1,46 @@ +.TH SEEK 3 +.SH NAME +seek \- change file offset +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +vlong seek(int fd, vlong n, int type) +.SH DESCRIPTION +.I Seek +sets the offset for the file +associated with +.I fd +as follows: +.IP +If +.I type +is 0, the offset is set to +.I n +bytes. +.IP +If +.I type +is 1, the pointer is set to its current location plus +.IR n . +.IP +If +.I type +is 2, the pointer is set to the size of the +file plus +.IR n . +.PP +The new file offset value is returned. +.PP +Seeking in a directory is not allowed. +Seeking in a pipe is a no-op. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR open (2) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/man/man3/setjmp.3 b/man/man3/setjmp.3 new file mode 100644 index 00000000..093d18f9 --- /dev/null +++ b/man/man3/setjmp.3 @@ -0,0 +1,98 @@ +.TH SETJMP 3 +.SH NAME +setjmp, longjmp, notejmp \- non-local goto +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid 'u +.B +int setjmp(jmp_buf env) +.PP +.B +void longjmp(jmp_buf env, int val) +.PP +.B +void notejmp(void *uregs, jmp_buf env, int val) +.SH DESCRIPTION +These routines are useful for dealing with errors +and interrupts encountered in +a low-level subroutine of a program. +.PP +.I Setjmp +saves its stack environment in +.I env +for later use by +.IR longjmp . +It returns value 0. +.PP +.I Longjmp +restores the environment saved by the last call of +.IR setjmp . +It then causes execution to +continue as if the call of +.I setjmp +had just returned with value +.IR val . +The invoker of +.I setjmp +must not itself have returned in the interim. +All accessible data have values as of the time +.I longjmp +was called. +.PP +.I Notejmp +is the same as +.I longjmp +except that it is to be called from within a note handler (see +.IR notify (2)). +The +.I uregs +argument should be the first argument passed to the note handler. +.PP +.I Setjmp +and +.I longjmp +can also be used to switch stacks. +Defined in +.B +are several macros that can be used to build +.B jmp_bufs +by hand. The following code establishes a +.B jmp_buf +.i label +that may be called by +.I longjmp +to begin execution in a function +.BR f +with 1024 bytes of stack: +.IP +.EX +#include +#include + +jmp_buf label; +#define NSTACK 1024 +char stack[NSTACK]; + +void +setlabel(void) +{ + label[JMPBUFPC] = ((ulong)f+JMPBUFDPC); + /* -2 leaves room for old pc and new pc in frame */ + label[JMPBUFSP = + (ulong)(&stack[NSTACK-2*sizeof(ulong*)]); +} +.EE +.SH SOURCE +.B /sys/src/libc/$objtype/setjmp.s +.br +.B /sys/src/libc/$objtype/notejmp.c +.SH SEE ALSO +.IR notify (2) +.SH BUGS +.PP +.I Notejmp +cannot recover from an address trap or bus error (page fault) on the 680x0 +architectures. diff --git a/man/man3/sleep.3 b/man/man3/sleep.3 new file mode 100644 index 00000000..d73f1eee --- /dev/null +++ b/man/man3/sleep.3 @@ -0,0 +1,45 @@ +.TH SLEEP 3 +.SH NAME +sleep, alarm \- delay, ask for delayed note +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int sleep(long millisecs) +.PP +.B +long alarm(unsigned long millisecs) +.SH DESCRIPTION +.I Sleep +suspends the current process for the number +of milliseconds specified by the argument. +The actual suspension time may be a little more or less than +the requested time. If +.I millisecs +is 0, the process +gives up the CPU if another process is waiting to run, returning +immediately if not. +Sleep returns \-1 if interrupted, 0 otherwise. +.PP +.I Alarm +causes an +.B alarm +note (see +.IR notify (2)) +to be sent to the invoking process after the number of milliseconds +given by the argument. +Successive calls to +.I alarm +reset the alarm clock. +A zero argument clears the alarm. +The return value is the amount of time previously remaining in +the alarm clock. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/man/man3/stat.3 b/man/man3/stat.3 new file mode 100644 index 00000000..c6f8c2e4 --- /dev/null +++ b/man/man3/stat.3 @@ -0,0 +1,326 @@ +.TH STAT 3 +.SH NAME +stat, fstat, wstat, fwstat, dirstat, dirfstat, dirwstat, dirfwstat, nulldir \- get and put file status +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int stat(char *name, uchar *edir, int nedir) +.PP +.B +int fstat(int fd, uchar *edir, int nedir) +.PP +.B +int wstat(char *name, uchar *edir, int nedir) +.PP +.B +int fwstat(int fd, uchar *edir, int nedir) +.PP +.B +Dir* dirstat(char *name) +.PP +.B +Dir* dirfstat(int fd) +.PP +.B +int dirwstat(char *name, Dir *dir) +.PP +.B +int dirfwstat(int fd, Dir *dir) +.PP +.B +void nulldir(Dir *d) +.SH DESCRIPTION +Given a file's +.IR name , +or an open file descriptor +.IR fd , +these routines retrieve or modify file status information. +.IR Stat , +.IR fstat , +.IR wstat , +and +.I fwstat +are the system calls; they deal with machine-independent +.IR "directory entries" . +Their format is defined by +.IR stat (5). +.I Stat +and +.I fstat +retrieve information about +.I name +or +.I fd +into +.IR edir , +a buffer of length +.IR nedir , +defined in +.BR . +.I Wstat +and +.I fwstat +write information back, thus changing file attributes according to the contents of +.IR edir . +The data returned from the kernel includes its leading 16-bit length field +as described in +.IR intro (5). +For symmetry, this field must also be present when passing data to the kernel in a call to +.I wstat +and +.IR fwstat , +but its value is ignored. +.PP +.IR Dirstat , +.IR dirfstat , +.IR dirwstat , +and +.I dirfwstat +are similar to their counterparts, except that they +operate on +.I Dir +structures: +.IP +.EX +.ta 6n +\w'ulong 'u +\w'mtime; 'u +typedef +struct Dir { + /* system-modified data */ + uint type; /* server type */ + uint dev; /* server subtype */ + /* file data */ + Qid qid; /* unique id from server */ + ulong mode; /* permissions */ + ulong atime; /* last read time */ + ulong mtime; /* last write time */ + vlong length; /* file length: see */ + char *name; /* last element of path */ + char *uid; /* owner name */ + char *gid; /* group name */ + char *muid; /* last modifier name */ +} Dir; +.EE +.PP +The returned structure is allocated by +.IR malloc (2); +freeing it also frees the associated strings. +.PP +This structure and +the +.B Qid +structure +are defined in +.BR . +If the file resides on permanent storage and is not a directory, +the length returned by +.I stat +is the number of bytes in the file. +For directories, the length returned is zero. +For files that are streams (e.g., pipes and network connections), +the length is the number of bytes that can be read without blocking. +.PP +Each file is the responsibility of some +.IR server : +it could be a file server, a kernel device, or a user process. +.B Type +identifies the server type, and +.B dev +says which of a group of servers of the same type is the one +responsible for this file. +.B Qid +is a structure containing +.B path +and +.B vers +fields: +.B path +is guaranteed to be +unique among all path names currently on the file server, and +.B vers +changes each time the file is modified. +The +.B path +is a +.B long +.B long +(64 bits, +.BR vlong ) +and the +.B vers +is an +.B unsigned long +(32 bits, +.BR ulong ). +Thus, if two files have the same +.BR type , +.BR dev , +and +.B qid +they are the same file. +.PP +The bits in +.B mode +are defined by +.PP +.ta 6n +\w'\fL0x80000000 'u +.nf +\fL 0x80000000\fP directory +\fL 0x40000000\fP append only +\fL 0x20000000\fP exclusive use (locked) + +\fL 0400\fP read permission by owner +\fL 0200\fP write permission by owner +\fL 0100\fP execute permission (search on directory) by owner +\fL 0070\fP read, write, execute (search) by group +\fL 0007\fP read, write, execute (search) by others +.fi +.PP +There are constants defined in +.B +for these bits: +.BR DMDIR , +.BR DMAPPEND , +and +.B DMEXCL +for the first three; and +.BR DMREAD , +.BR DMWRITE , +and +.B DMEXEC +for the read, write, and execute bits for others. +.PP +The two time fields are measured in seconds since the epoch +(Jan 1 00:00 1970 GMT). +.B Mtime +is the time of the last change of content. +Similarly, +.B atime +is set whenever the contents are accessed; +also, it is set whenever +.B mtime +is set. +.PP +.B Uid +and +.B gid +are the names of the owner and group of the file; +.B muid +is the name of the user that last modified the file (setting +.BR mtime ). +Groups are also users, but each server is free to associate +a list of users with any user name +.IR g , +and that list is the +set of users in the group +.IR g . +When an initial attachment is made to a server, +the user string in the process group is communicated to the server. +Thus, the server knows, for any given file access, whether the accessing +process is the owner of, or in the group of, the file. +This selects which sets of three bits in +.B mode +is used to check permissions. +.PP +Only some of the fields may be changed with the +.I wstat +calls. +The +.B name +can be changed by anyone with write permission in the parent directory. +The +.B mode +and +.B mtime +can be changed by the owner or the group leader of the file's current +group. +The +.I gid +can be changed: by the owner if also a member of the new group; or +by the group leader of the file's current group +if also leader of the new group +(see +.IR intro (5) +for more information about permissions and +.IR users (6) +for users and groups). +The +.B length +can be changed by anyone with write permission, provided the operation +is implemented by the server. +(See +.IR intro (5) +for permission information, and +.IR users (6) +for user and group information). +.PP +Special values in the fields of the +.B Dir +passed to +.I wstat +indicate that the field is not intended to be changed by the call. +The values are the maximum unsigned integer of appropriate size +for integral values (usually +.BR ~0 , +but beware of conversions and size mismatches +when comparing values) and the empty or nil string for string values. +The routine +.I nulldir +initializes all the elements of +.I d +to these ``don't care'' values. +Thus one may change the mode, for example, by using +.I nulldir +to initialize a +.BR Dir , +then setting the mode, and then doing +.IR wstat ; +it is not necessary to use +.I stat +to retrieve the initial values first. +.SH SOURCE +.TF /sys/src/libc/9syscall +.TP +.B /sys/src/libc/9syscall +for the +.RB non- dir +routines +.TP +.B /sys/src/libc/9sys +for the routines prefixed +.B dir +.SH SEE ALSO +.IR intro (2), +.IR fcall (2), +.IR dirread (2), +.IR stat (5) +.SH DIAGNOSTICS +The +.I dir +functions return a pointer to the data for a successful call, or +.B nil +on error. +The others +return the number of bytes copied on success, or \-1 on error. +All set +.IR errstr . +.PP +If the buffer for +.I stat +or +.I fstat +is too short for the returned data, the return value will be +.B BIT16SZ +(see +.IR fcall (2)) +and the two bytes +returned will contain the initial count field of the +returned data; +retrying with +.B nedir +equal to +that value plus +.B BIT16SZ +(for the count itself) should succeed. diff --git a/man/man3/strcat.3 b/man/man3/strcat.3 new file mode 100644 index 00000000..fe717fbc --- /dev/null +++ b/man/man3/strcat.3 @@ -0,0 +1,268 @@ +.TH STRCAT 3 +.SH NAME +strcat, strncat, strcmp, strncmp, cistrcmp, cistrncmp, strcpy, strncpy, strecpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok, strdup, strstr, cistrstr \- string operations +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLchar* \fP'u +.B +char* strcat(char *s1, char *s2) +.PP +.B +char* strncat(char *s1, char *s2, long n) +.PP +.B +int strcmp(char *s1, char *s2) +.PP +.B +int strncmp(char *s1, char *s2, long n) +.PP +.B +int cistrcmp(char *s1, char *s2) +.PP +.B +int cistrncmp(char *s1, char *s2, long n) +.PP +.B +char* strcpy(char *s1, char *s2) +.PP +.B +char* strecpy(char *s1, char *es1, char *s2) +.PP +.B +char* strncpy(char *s1, char *s2, long n) +.PP +.B +long strlen(char *s) +.PP +.B +char* strchr(char *s, char c) +.PP +.B +char* strrchr(char *s, char c) +.PP +.B +char* strpbrk(char *s1, char *s2) +.PP +.B +long strspn(char *s1, char *s2) +.PP +.B +long strcspn(char *s1, char *s2) +.PP +.B +char* strtok(char *s1, char *s2) +.PP +.B +char* strdup(char *s) +.PP +.B +char* strstr(char *s1, char *s2) +.PP +.B +char* cistrstr(char *s1, char *s2) +.SH DESCRIPTION +The arguments +.I s1, s2 +and +.I s +point to null-terminated strings. +The functions +.IR strcat , +.IR strncat , +.IR strcpy , +.IR strecpy , +and +.I strncpy +all alter +.IR s1 . +.I Strcat +and +.I strcpy +do not check for overflow of +the array pointed to by +.IR s1 . +.PP +.I Strcat +appends a copy of string +.I s2 +to the end of string +.IR s1 . +.I Strncat +appends at most +.I n +bytes. +Each returns a pointer to the null-terminated result. +.PP +.I Strcmp +compares its arguments and returns an integer +less than, equal to, or greater than 0, +according as +.I s1 +is lexicographically less than, equal to, or +greater than +.IR s2 . +.I Strncmp +makes the same comparison but examines at most +.I n +bytes. +.I Cistrcmp +and +.I cistrncmp +ignore ASCII case distinctions when comparing strings. +The comparisons are made with unsigned bytes. +.PP +.I Strcpy +copies string +.I s2 +to +.IR s1 , +stopping after the null byte has been copied. +.I Strncpy +copies exactly +.I n +bytes, +truncating +.I s2 +or adding +null bytes to +.I s1 +if necessary. +The result will not be null-terminated if the length +of +.I s2 +is +.I n +or more. +Each function returns +.IR s1 . +.PP +.I Strecpy +copies bytes until a null byte has been copied, but writes no bytes beyond +.IR es1 . +If any bytes are copied, +.I s1 +is terminated by a null byte, and a pointer to that byte is returned. +Otherwise, the original +.I s1 +is returned. +.PP +.I Strlen +returns the number of bytes in +.IR s , +not including the terminating null byte. +.PP +.I Strchr +.RI ( strrchr ) +returns a pointer to the first (last) +occurrence of byte +.I c +in string +.IR s , +or +.L 0 +if +.I c +does not occur in the string. +The null byte terminating a string is considered to +be part of the string. +.PP +.I Strpbrk +returns a pointer to the first occurrence in string +.I s1 +of any byte from string +.IR s2 , +.L 0 +if no byte from +.I s2 +exists in +.IR s1 . +.PP +.I Strspn +.RI ( strcspn ) +returns the length of the initial segment of string +.I s1 +which consists entirely of bytes from (not from) string +.IR s2 . +.PP +.I Strtok +considers the string +.I s1 +to consist of a sequence of zero or more text tokens separated +by spans of one or more bytes from the separator string +.IR s2 . +The first call, with pointer +.I s1 +specified, returns a pointer to the first byte of the first +token, and will have written a +null byte into +.I s1 +immediately following the returned token. +The function +keeps track of its position in the string +between separate calls; subsequent calls, +signified by +.I s1 +being +.LR 0 , +will work through the string +.I s1 +immediately following that token. +The separator string +.I s2 +may be different from call to call. +When no token remains in +.IR s1 , +.L 0 +is returned. +.PP +.I Strdup +returns a pointer to a distinct copy of the null-terminated string +.I s +in space obtained from +.IR malloc (2) +or +.L 0 +if no space can be obtained. +.PP +.I Strstr +returns a pointer to the first occurrence of +.I s2 +as a substring of +.IR s1 , +or 0 if there is none. +If +.I s2 +is the null string, +.I strstr +returns +.IR s1 . +.I Cistrstr +operates analogously, but ignores ASCII case differences when comparing strings. +.SH SOURCE +All these routines have portable C implementations in +.BR /sys/src/libc/port . +Many also have machine-dependent assembly language +implementations in +.BR /sys/src/libc/$objtype . +.SH SEE ALSO +.IR memory (2), +.IR rune (2), +.IR runestrcat (2) +.SH BUGS +These routines know nothing about +.SM UTF. +Use the routines in +.IR rune (2) +as appropriate. +Note, however, that the definition of +.SM UTF +guarantees that +.I strcmp +compares +.SM UTF +strings correctly. +.PP +The outcome of overlapping moves varies among implementations. diff --git a/man/man3/string.3 b/man/man3/string.3 new file mode 100644 index 00000000..93044a8a --- /dev/null +++ b/man/man3/string.3 @@ -0,0 +1,236 @@ +.TH STRING 3 +.SH NAME +s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, s_getline \- extensible strings +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +String* s_new(void) +.br +.B +void s_free(String *s) +.br +.B +String* s_newalloc(int n) +.br +.B +String* s_array(char *p, int n) +.br +.B +String* s_grow(String *s, int n) +.PP +.B +void s_putc(String *s, int c) +.br +.B +void s_terminate(String *s) +.br +.B +String* s_reset(String *s) +.br +.B +String* s_restart(String *s) +.br +.B +String* s_append(String *s, char *p) +.br +.B +String* s_nappend(String *s, char *p, int n) +.br +.B +String* s_memappend(String *s, char *p, int n) +.br +.B +String* s_copy(char *p) +.br +.B +String* s_parse(String *s1, String *s2) +.br +.PP +.B +void s_tolower(String *s) +.PP +.B +String* s_incref(String *s) +.br +.B +String* s_unique(String *s) +.PP +.B +#include +.PP +.B +int s_read(Biobuf *b, String *s, int n) +.br +.B +char* s_read_line(Biobuf *b, String *s) +.br +.B +char* s_getline(Biobuf *b, String *s) +.SH DESCRIPTION +.PP +These routines manipulate extensible strings. +The basic type is +.BR String , +which points to an array of characters. The string +maintains pointers to the beginning and end of the allocated +array. In addition a finger pointer keeps track of where +parsing will start (for +.IR s_parse ) +or new characters will be added (for +.IR s_putc , +.IR s_append , +and +.IR s_nappend ). +The structure, and a few useful macros are: +.sp +.EX +typedef struct String { + Lock; + char *base; /* base of String */ + char *end; /* end of allocated space+1 */ + char *ptr; /* ptr into String */ + ... +} String; + +#define s_to_c(s) ((s)->base) +#define s_len(s) ((s)->ptr-(s)->base) +#define s_clone(s) s_copy((s)->base) +.EE +.PP +.I S_to_c +is used when code needs a reference to the character array. +Using +.B s->base +directly is frowned upon since it exposes too much of the implementation. +.SS "allocation and freeing +.PP +A string must be allocated before it can be used. +One normally does this using +.IR s_new , +giving the string an initial allocation of +128 bytes. +If you know that the string will need to grow much +longer, you can use +.I s_newalloc +instead, specifying the number of bytes in the +initial allocation. +.PP +.I S_free +causes both the string and its character array to be freed. +.PP +.I S_grow +grows a string's allocation by a fixed amount. It is useful if +you are reading directly into a string's character array but should +be avoided if possible. +.PP +.I S_array +is used to create a constant array, that is, one whose contents +won't change. It points directly to the character array +given as an argument. Tread lightly when using this call. +.SS "Filling the string +After its initial allocation, the string points to the beginning +of an allocated array of characters starting with +.SM NUL. +.PP +.I S_putc +writes a character into the string at the +pointer and advances the pointer to point after it. +.PP +.I S_terminate +writes a +.SM NUL +at the pointer but doesn't advance it. +.PP +.I S_restart +resets the pointer to the begining of the string but doesn't change the contents. +.PP +.I S_reset +is equivalent to +.I s_restart +followed by +.IR s_terminate . +.PP +.I S_append +and +.I s_nappend +copy characters into the string at the pointer and +advance the pointer. They also write a +.SM NUL +at +the pointer without advancing the pointer beyond it. +Both routines stop copying on encountering a +.SM NUL. +.I S_memappend +is like +.I s_nappend +but doesn't stop at a +.SM NUL. +.PP +If you know the initial character array to be copied into a string, +you can allocate a string and copy in the bytes using +.IR s_copy . +This is the equivalent of a +.I s_new +followed by an +.IR s_append . +.PP +.I S_parse +copies the next white space terminated token from +.I s1 +to +the end of +.IR s2 . +White space is defined as space, tab, +and newline. Both single and double quoted strings are treated as +a single token. The bounding quotes are not copied. +There is no escape mechanism. +.PP +.I S_tolower +converts all +.SM ASCII +characters in the string to lower case. +.SS Multithreading +.PP +.I S_incref +is used by multithreaded programs to avoid having the string memory +released until the last user of the string performs an +.IR s_free . +.I S_unique +returns a unique copy of the string: if the reference count it +1 it returns the string, otherwise it returns an +.I s_clone +of the string. +.SS "Bio interaction +.PP +.I S_read +reads the requested number of characters through a +.I Biobuf +into a string. The string is grown as necessary. +An eof or error terminates the read. +The number of bytes read is returned. +The string is null terminated. +.PP +.I S_read_line +reads up to and including the next newline and returns +a pointer to the beginning of the bytes read. +An eof or error terminates the read. +The string is null terminated. +.PP +.I S_getline +reads up to the next newline and returns +a pointer to the beginning of the bytes read. Leading +spaces and tabs and the trailing newline are all discarded. +.I S_getline +will recursively read through files included with +.B #include +and discard all other lines beginning with +.BR # . +.SH SOURCE +.B /sys/src/libString +.SH SEE ALSO +.IR bio (2) diff --git a/man/man3/stringsize.3 b/man/man3/stringsize.3 new file mode 100644 index 00000000..3ae28231 --- /dev/null +++ b/man/man3/stringsize.3 @@ -0,0 +1,69 @@ +.TH STRINGSIZE 3 +.SH NAME +stringsize, stringwidth, stringnwidth, runestringsize, runestringwidth, runestringnwidth \- graphical size of strings +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +#include +.ft P +.ta \w'\fLPoint 'u +.PP +.B +Point stringsize(Font *f, char *s) +.PP +.B +int stringwidth(Font *f, char *s) +.PP +.B +int stringnwidth(Font *f, char *s, int n) +.PP +.B +Point runestringsize(Font *f, Rune *s) +.PP +.B +int runestringwidth(Font *f, Rune *s) +.PP +.B +int runestringnwidth(Font *f, Rune *s, int n) +.SH DESCRIPTION +These routines compute the geometrical extent of character strings when drawn on the display. The most straightforward, +.BR stringsize , +returns a +.B Point +representing the vector from upper left to lower right of the NUL-terminated string +.I s +drawn in font +.IR f . +.B Stringwidth +returns just the +.I x +component. +.B Stringnwidth +returns the width of the first +.I n +characters of +.IR s . +.PP +The routines beginning with +.B rune +are analogous, but accept an array of runes rather than +.SM UTF\c +-encoded bytes. +.SH FILES +.BR /lib/font/bit " directory of fonts +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR addpt (2), +.IR cachechars (2), +.IR subfont (2), +.IR draw (2), +.IR draw (3), +.IR image (6), +.IR font (6) +.SH DIAGNOSTICS +Because strings are loaded dynamically, these routines may generate I/O +to the server and produce calls to the graphics error function. diff --git a/man/man3/subfont.3 b/man/man3/subfont.3 new file mode 100644 index 00000000..3802333b --- /dev/null +++ b/man/man3/subfont.3 @@ -0,0 +1,235 @@ +.TH SUBFONT 3 +.SH NAME +allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, strsubfontwidth, mkfont \- subfont manipulation +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLSubfont* 'u +.B +Subfont* allocsubfont(char *name, int n, int height, int ascent, +.br +.B + Fontchar *info, Image *i) +.PP +.B +void freesubfont(Subfont *f) +.PP +.B +void installsubfont(char *name, Subfont *f) +.PP +.B +Subfont* lookupsubfont(Subfont *f) +.PP +.B +void uninstallsubfont(Subfont *f) +.PP +.B +Subfont* readsubfont(Display *d, char *name, int fd, int dolock) +.PP +.B +Subfont* readsubfonti(Display *d, char *name, int fd, Image *im, +.br +.B + int dolock) +.PP +.B +int writesubfont(int fd, Subfont *f) +.PP +.B +Point stringsubfont(Image *dst, Point p, Image *src, +.br +.B + Subfont *f, char *str) +.PP +.B +Point strsubfontwidth(Subfont *f, char *s) +.PP +.B +Font* mkfont(Subfont *f, Rune min) +.SH DESCRIPTION +Subfonts are the components of fonts that hold the character images. +A font comprises an array of subfonts; see +.IR cachechars (2). +A new +.B Subfont +is allocated and initialized with +.IR allocsubfont . +See +.IR cachechars (2) +for the meaning of +.IR n , +.IR height , +.IR ascent , +and +.IR info , +and the arrangement of characters in +image +.IR i . +The +.I name +is used to identify the subfont in the subfont cache; see the descriptions +.I lookupsubfont +and +.IR installsubfont +.RI ( q.v. ). +The appropriate fields of the returned +.B Subfont +structure are set to +the passed arguments, and the image is registered as a subfont +with the graphics device +.IR draw (3). +.I Allocsubfont +returns 0 on failure. +.PP +.I Freesubfont +frees a subfont and all its associated structure including the +associated image. +Since +.I freesbufont +calls +.I free +on +.BR f->info , +if +.B f->info +was not allocated by +.IR malloc (2) +it should be zeroed before calling +.IR subffree . +.PP +A number of subfonts are kept in external files. +The convention for naming subfont files is: +.IP +.B /lib/font/bit/\fIname\fP/\fIclass\fP.\fIsize\fP.\fIdepth +.PD +.PP +where +.I size +is approximately the height in pixels of the lower case letters +(without ascenders or descenders). +If there is only one version of the subfont, the +.BI \&. depth +extension is elided. +.I Class +describes the range of runes encoded in the subfont: +.BR ascii , +.BR latin1 , +.BR greek , +etc. +.PP +Subfonts are cached within the program, so a subfont shared between fonts will be loaded only once. +.I Installsubfont +stores subfont +.I f +under the given +.IR name , +typically the file name from which it was read. +.I Uninstallsubfont +removes the subfont from the cache. +Finally, +.I lookupsubfont +searches for a subfont with the given +.I name +in the cache and returns it, or nil if no such subfont exists. +.PP +.I Subfontname +is used to locate subfonts given their names within the fonts. +The default version constructs a name given the +.IR cfname , +its name within the font, +.IR fname , +the name of the font, and the maximum depth suitable for this subfont. +This interface allows a partially specified name within a font to be resolved +at run-time to the name of a file holding a suitable subfont. +Although it is principally a routine internal to the library, +.I subfontname +may be substituted by the application to provide a less file-oriented subfont naming scheme. +.PP +The format of a subfont file is described in +.IR font (6). +Briefly, it contains a image with all the characters in it, +followed by a subfont header, followed by character information. +.I Readsubfont +reads a subfont from the file descriptor +.IR fd . +The +.I name +is used to identify the font in the cache. +The +.I dolock +argument specifies whether the routine should synchronize +use of the +.I Display +with other processes; for single-threaded applications it may +always be zero. +.I Readsubfonti +does the same for a subfont whose associated image is already in memory; it is passed as the +argument +.IR im . +In other words, +.I readsubfonti +reads only the header and character information from the file descriptor. +.PP +.I Writesubfont +writes on +.I fd +the part of a subfont file that comes after the image. It should be preceded by +a call to +.IR writeimage +(see +.IR allocimage (2)). +.PP +.I Stringsubfont +is analogous to +.B string +(see +.IR draw (2)) +for subfonts. Rather than use the underlying font caching primitives, +it calls +.B draw +for each character. +It is intended for stand-alone environments such as operating system kernels. +.I Strsubfontwidth +returns the width of the string +.I s +in +as it would appear if drawn with +.I stringsubfont +in +.B Subfont +.BR f . +.PP +.I Mkfont +takes as argument a +.B Subfont +.I s +and returns a pointer to a +.B Font +that maps the character images in +.I s +into the +.B Runes +.I min +to +.IB min + s ->n-1\f1. +.SH FILES +.TF /lib/font/bit +.TP +.B /lib/font/bit +bitmap font file tree +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR allocimage (2), +.IR draw (2), +.IR cachechars (2), +.IR image (6), +.IR font (6) +.SH DIAGNOSTICS +All of the functions use the graphics error function (see +.IR graphics (2)). diff --git a/man/man3/symbol.3 b/man/man3/symbol.3 new file mode 100644 index 00000000..f22590ae --- /dev/null +++ b/man/man3/symbol.3 @@ -0,0 +1,436 @@ +.TH SYMBOL 3 +.SH NAME +syminit, getsym, symbase, pc2sp, pc2line, textseg, line2addr, lookup, findlocal, +getauto, findsym, localsym, globalsym, textsym, file2pc, fileelem, filesym, +fileline, fnbound \- symbol table access functions +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLmachines 'u +.B +int syminit(int fd, Fhdr *fp) +.PP +.B +Sym *getsym(int index) +.PP +.B +Sym *symbase(long *nsyms) +.PP +.B +int fileelem(Sym **fp, uchar *encname, char *buf, int n) +.PP +.B +int filesym(int index, char *buf, int n) +.PP +.B +long pc2sp(ulong pc) +.PP +.B +long pc2line(ulong pc) +.PP +.B +void textseg(ulong base, Fhdr *fp) +.PP +.B +long line2addr(ulong line, ulong basepc) +.PP +.B +int lookup(char *fn, char *var, Symbol *s) +.PP +.B +int findlocal(Symbol *s1, char *name, Symbol *s2) +.PP +.B +int getauto(Symbol *s1, int off, int class, Symbol *s2) +.PP +.B +int findsym(long addr, int class, Symbol *s) +.PP +.B +int localsym(Symbol *s, int index) +.PP +.B +int globalsym(Symbol *s, int index) +.PP +.B +int textsym(Symbol *s, int index) +.PP +.B +long file2pc(char *file, ulong line) +.PP +.B +int fileline(char *str, int n, ulong addr) +.PP +.B +int fnbound(long addr, ulong *bounds) +.SH DESCRIPTION +These functions provide machine-independent access to the +symbol table of an executable file or executing process. +The latter is accessible by opening the device +.B /proc/\fIpid\fP/text +as described in +.IR proc (3). +.IR Mach (2) +and +.IR object (2) +describe additional library functions +for processing executable and object files. +.PP +.IR Syminit , +.IR getsym , +.IR symbase , +.IR fileelem , +.IR pc2sp , +.IR pc2line , +and +.I line2addr +process the symbol table contained in an executable file +or the +.B text +image of an executing program. +The symbol table is stored internally as an array of +.B Sym +data structures as defined in +.IR a.out (6). +.PP +.I Syminit +uses the data in the +.B Fhdr +structure filled by +.I crackhdr +(see +.IR mach (2)) +to read the raw symbol tables from the open file descriptor +.IR fd . +It returns the count of the number of symbols +or \-1 if an error occurs. +.PP +.I Getsym +returns the address of the +.IR i th +.B Sym +structure or zero if +.I index +is out of range. +.PP +.I Symbase +returns the address of the first +.B Sym +structure in the symbol table. The number of +entries in the symbol table is returned in +.IR nsyms . +.PP +.I Fileelem +converts a file name, encoded as described in +.IR a.out (6), +to a character string. +.I Fp +is the base of +an array of pointers to file path components ordered by path index. +.I Encname +is the address of an array of encoded +file path components in the form of a +.B z +symbol table entry. +.I Buf +and +.I n +specify the +address of a receiving character buffer and its length. +.I Fileelem +returns the length of the null-terminated string +that is at most +.IR n \-1 +bytes long. +.PP +.I Filesym +is a higher-level interface to +.IR fileelem . +It fills +.I buf +with the name of the +.IR i th +file and returns the length of the null-terminated string +that is at most +.IR n \-1 +bytes long. +File names are retrieved in no particular order, although +the order of retrieval does not vary from one pass to the next. +A zero is returned when +.I index +is too large or too small or an error occurs during file name +conversion. +.PP +.I Pc2sp +returns an offset associated with +a given value of the program counter. Adding this offset +to the current value of the stack pointer gives the address +of the current stack frame. This approach only applies +to the 68020 architecture; other architectures +use a fixed stack frame offset by a constant contained +in a dummy local variable (called +.BR .frame ) +in the symbol table. +.PP +.I Pc2line +returns the line number of the statement associated +with the instruction address +.IR pc . +The +line number is the absolute line number in the +source file as seen by the compiler after pre-processing; the +original line number in the source file may be derived from this +value using the history stacks contained in the symbol table. +.PP +.I Pc2sp +and +.I pc2line +must know the start and end addresses of the text segment +for proper operation. These values are calculated from the +file header by function +.IR syminit . +If the text segment address is changed, the application +program must invoke +.I textseg +to recalculate the boundaries of the segment. +.I Base +is the new base address of the text segment and +.I fp +points to the +.I Fhdr +data structure filled by +.IR crackhdr . +.PP +.I Line2addr +converts a line number to an instruction address. The +first argument is the absolute line number in +a file. Since a line number does not uniquely identify +an instruction location (e.g., every source file has line 1), +a second argument specifies a text address +from which the search begins. Usually this +is the address of the first function in the file of interest. +.PP +.IR Pc2sp , +.IR pc2line , +and +.I line2addr +return \-1 in the case of an error. +.PP +.IR Lookup , +.IR findlocal , +.IR getauto , +.IR findsym , +.IR localsym , +.IR globalsym , +.IR textsym , +.IR file2pc , +and +.I fileline +operate on data structures riding above the raw symbol table. +These data structures occupy memory +and impose a startup penalty but speed retrievals +and provide higher-level access to the basic symbol +table data. +.I Syminit +must be called +prior to using these functions. +The +.B Symbol +data structure: +.IP +.EX +typedef struct { + void *handle; /* private */ + struct { + char *name; + long value; + char type; + char class; + }; +} Symbol; +.EE +.LP +describes a symbol table entry. +The +.B value +field contains the offset of the symbol within its +address space: global variables relative to the beginning +of the data segment, text beyond the start of the text +segment, and automatic variables and parameters relative +to the stack frame. The +.B type +field contains the type of the symbol as defined in +.IR a.out (6). +The +.B class +field assigns the symbol to a general class; +.BR CTEXT , +.BR CDATA , +.BR CAUTO , +and +.B CPARAM +are the most popular. +.PP +.I Lookup +fills a +.B Symbol +structure with symbol table information. Global variables +and functions are represented by a single name; local variables +and parameters are uniquely specified by a function and +variable name pair. Arguments +.I fn +and +.I var +contain the +name of a function and variable, respectively. +If both +are non-zero, the symbol table is searched for a parameter +or automatic variable. If only +.I var +is +zero, the text symbol table is searched for function +.IR fn . +If only +.I fn +is zero, the global variable table +is searched for +.IR var . +.PP +.I Findlocal +fills +.I s2 +with the symbol table data of the automatic variable +or parameter matching +.IR name . +.I S1 +is a +.B Symbol +data structure describing a function or a local variable; +the latter resolves to its owning function. +.PP +.I Getauto +searches the local symbols associated with function +.I s1 +for an automatic variable or parameter located at stack +offset +.IR off . +.I Class +selects the class of +variable: +.B CAUTO +or +.BR CPARAM . +.I S2 +is the address of a +.B Symbol +data structure to receive the symbol table information +of the desired symbol. +.PP +.I Findsym +returns the symbol table entry of type +.I class +stored near +.IR addr . +The selected symbol is a global variable or function +with address nearest to and less than or equal to +.IR addr . +Class specification +.B CDATA +searches only the global variable symbol table; class +.B CTEXT +limits the search to the text symbol table. +Class specification +.B CANY +searches the text table first, then the global table. +.PP +.I Localsym +returns the +.IR i th +local variable in the function +associated with +.IR s . +.I S +may reference a function or a local variable; the latter +resolves to its owning function. +If the +.IR i th +local symbol exists, +.I s +is filled with the data describing it. +.PP +.I Globalsym +loads +.I s +with the symbol table information of the +.IR i th +global variable. +.PP +.I Textsym +loads +.I s +with the symbol table information of the +.IR i th +text symbol. The text symbols are ordered +by increasing address. +.PP +.I File2pc +returns a text address associated with +.I line +in file +.IR file , +or -1 on an error. +.PP +.I Fileline +converts text address +.I addr +to its equivalent +line number in a source file. The result, +a null terminated character string of +the form +.LR file:line , +is placed in buffer +.I str +of +.I n +bytes. +.PP +.I Fnbound +returns the start and end addresses of the function containing +the text address supplied as the first argument. The second +argument is an array of two unsigned longs; +.I fnbound +places the bounding addresses of the function in the first +and second elements of this array. The start address is the +address of the first instruction of the function; the end +address is the address of the start of the next function +in memory, so it is beyond the end of the target function. +.I Fnbound +returns 1 if the address is within a text function, or zero +if the address selects no function. +.PP +Functions +.I file2pc +and +.I fileline +may produce inaccurate results when applied to +optimized code. +.PP +Unless otherwise specified, all functions return 1 +on success, or 0 on error. When an error occurs, +a message describing it is stored in the system +error buffer where it is available via +.IR errstr . +.SH SOURCE +.B /sys/src/libmach +.SH "SEE ALSO" +.IR mach (2), +.IR object (2), +.IR errstr (2), +.IR proc (3), +.IR a.out (6) diff --git a/man/man3/thread.3 b/man/man3/thread.3 index 3009ac84..dce6d812 100644 --- a/man/man3/thread.3 +++ b/man/man3/thread.3 @@ -1,4 +1,4 @@ -.TH THREAD 2 +.TH THREAD 3 .SH NAME alt, chancreate, diff --git a/man/man3/time.3 b/man/man3/time.3 new file mode 100644 index 00000000..e5983954 --- /dev/null +++ b/man/man3/time.3 @@ -0,0 +1,45 @@ +.TH TIME 3 +.SH NAME +time, nsec \- time in seconds and nanoseconds since epoch +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +long time(long *tp) +.PP +.B +vlong nsec(void) +.SH DESCRIPTION +Both +.I time +and +.I nsec +return the time since the epoch 00:00:00 GMT, Jan. 1, 1970. +The return value of the former is in seconds and the latter in nanoseconds. +For +.IR time , +if +.I tp +is not zero then +.BI * tp +is also set to the answer. +.PP +These functions work by reading +.BR /dev/bintime , +opening that file when +.I they +are first called. +.SH SOURCE +.B /sys/src/libc/9sys/time.c +.br +.B /sys/src/libc/9sys/nsec.c +.SH SEE ALSO +.IR cons (3) +.SH DIAGNOSTICS +Sets +.IR errstr . +.SH BUGS +These routines maintain a static file descriptor. diff --git a/man/man3/wait.3 b/man/man3/wait.3 new file mode 100644 index 00000000..d29fc719 --- /dev/null +++ b/man/man3/wait.3 @@ -0,0 +1,117 @@ +.TH WAIT 3 +.SH NAME +await, wait, waitpid \- wait for a process to exit +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +Waitmsg* wait(void) +.PP +.B +int waitpid(void) +.PP +.B +int await(char *s, int n) +.SH DESCRIPTION +.I Wait +causes a process to wait for any child process (see +.IR fork (2)) +to exit. +It returns a +.B Waitmsg +holding +information about the exited child. +A +.B Waitmsg +has this structure: +.IP +.EX +.ta 6n +\w'long 'u +\w'msg[ERRLEN]; 'u +typedef +struct Waitmsg +{ + int pid; /* of loved one */ + ulong time[3]; /* of loved one & descendants */ + char *msg; +} Waitmsg; +.EE +.PP +.B Pid +is the child's +process id. +The +.B time +array contains the time the child and its descendants spent in user code, +the time spent in system calls, and the child's elapsed real time, +all in units of milliseconds. +.B Msg +contains the message that the child specified in +.IR exits (2). +For a normal exit, +.B msg[0] +is zero, +otherwise +.B msg +is the exit string +prefixed by the process name, a blank, the process id, and a colon. +.PP +If there are no more children to wait for, +.I wait +returns immediately, with return value nil. +.PP +The +.B Waitmsg +structure is allocated by +.IR malloc (2) +and should be freed after use. +For programs that only need the pid of the exiting program, +.I waitpid +returns just the pid and discards the rest of the information. +.PP +The underlying system call is +.IR await , +which fills in the n-byte buffer +.I s +with a textual representation of the pid, times, and exit string. +There is no terminal NUL. +The return value is the length, in bytes, of the data. +.PP +The buffer filled in by +.I await +may be parsed (after appending a NUL) using +.IR tokenize +(see +.IR getfields (2)); +the resulting fields are, in order, pid, the three times, and the exit string, +which will be +.B '' +for normal exit. +If the representation is longer than +.I n +bytes, it is truncated but, if possible, properly formatted. +The information that does not fit in the buffer is discarded, so +a subsequent call to +.I await +will return the information about the next exiting child, not the remainder +of the truncated message. +In other words, each call to +.I await +returns the information about one child, blocking if necessary if no child has exited. +If the calling process has no living children, +.I await +returns +.BR -1 . +.SH SOURCE +.B /sys/src/libc/9syscall +.SH "SEE ALSO" +.IR fork (2), +.IR exits (2), +the +.B wait +file in +.IR proc (3) +.SH DIAGNOSTICS +These routines set +.IR errstr . diff --git a/man/man7/regexp.7 b/man/man7/regexp.7 new file mode 100644 index 00000000..14a90d0f --- /dev/null +++ b/man/man7/regexp.7 @@ -0,0 +1,150 @@ +.TH REGEXP9 7 +.de EX +.nf +.ft B +.. +.de EE +.fi +.ft R +.. +.de LR +.if t .BR \\$1 \\$2 +.if n .RB ` \\$1 '\\$2 +.. +.de L +.nh +.if t .B \\$1 +.if n .RB ` \\$1 ' +.. +.SH NAME +regexp9 \- Plan 9 regular expression notation +.SH DESCRIPTION +This manual page describes the regular expression +syntax used by the Plan 9 regular expression library +.IR regexp9 (3). +It is the form used by +.IR egrep (1) +before +.I egrep +got complicated. +.PP +A +.I "regular expression" +specifies +a set of strings of characters. +A member of this set of strings is said to be +.I matched +by the regular expression. In many applications +a delimiter character, commonly +.LR / , +bounds a regular expression. +In the following specification for regular expressions +the word `character' means any character (rune) but newline. +.PP +The syntax for a regular expression +.B e0 +is +.IP +.EX +e3: literal | charclass | '.' | '^' | '$' | '(' e0 ')' + +e2: e3 + | e2 REP + +REP: '*' | '+' | '?' + +e1: e2 + | e1 e2 + +e0: e1 + | e0 '|' e1 +.EE +.PP +A +.B literal +is any non-metacharacter, or a metacharacter +(one of +.BR .*+?[]()|\e^$ ), +or the delimiter +preceded by +.LR \e . +.PP +A +.B charclass +is a nonempty string +.I s +bracketed +.BI [ \|s\| ] +(or +.BI [^ s\| ]\fR); +it matches any character in (or not in) +.IR s . +A negated character class never +matches newline. +A substring +.IB a - b\f1, +with +.I a +and +.I b +in ascending +order, stands for the inclusive +range of +characters between +.I a +and +.IR b . +In +.IR s , +the metacharacters +.LR - , +.LR ] , +an initial +.LR ^ , +and the regular expression delimiter +must be preceded by a +.LR \e ; +other metacharacters +have no special meaning and +may appear unescaped. +.PP +A +.L . +matches any character. +.PP +A +.L ^ +matches the beginning of a line; +.L $ +matches the end of the line. +.PP +The +.B REP +operators match zero or more +.RB ( * ), +one or more +.RB ( + ), +zero or one +.RB ( ? ), +instances respectively of the preceding regular expression +.BR e2 . +.PP +A concatenated regular expression, +.BR "e1\|e2" , +matches a match to +.B e1 +followed by a match to +.BR e2 . +.PP +An alternative regular expression, +.BR "e0\||\|e1" , +matches either a match to +.B e0 +or a match to +.BR e1 . +.PP +A match to any part of a regular expression +extends as far as possible without preventing +a match to the remainder of the regular expression. +.SH "SEE ALSO" +.IR regexp9 (3) diff --git a/man/man7/regexp9.7 b/man/man7/regexp9.7 deleted file mode 100644 index 14a90d0f..00000000 --- a/man/man7/regexp9.7 +++ /dev/null @@ -1,150 +0,0 @@ -.TH REGEXP9 7 -.de EX -.nf -.ft B -.. -.de EE -.fi -.ft R -.. -.de LR -.if t .BR \\$1 \\$2 -.if n .RB ` \\$1 '\\$2 -.. -.de L -.nh -.if t .B \\$1 -.if n .RB ` \\$1 ' -.. -.SH NAME -regexp9 \- Plan 9 regular expression notation -.SH DESCRIPTION -This manual page describes the regular expression -syntax used by the Plan 9 regular expression library -.IR regexp9 (3). -It is the form used by -.IR egrep (1) -before -.I egrep -got complicated. -.PP -A -.I "regular expression" -specifies -a set of strings of characters. -A member of this set of strings is said to be -.I matched -by the regular expression. In many applications -a delimiter character, commonly -.LR / , -bounds a regular expression. -In the following specification for regular expressions -the word `character' means any character (rune) but newline. -.PP -The syntax for a regular expression -.B e0 -is -.IP -.EX -e3: literal | charclass | '.' | '^' | '$' | '(' e0 ')' - -e2: e3 - | e2 REP - -REP: '*' | '+' | '?' - -e1: e2 - | e1 e2 - -e0: e1 - | e0 '|' e1 -.EE -.PP -A -.B literal -is any non-metacharacter, or a metacharacter -(one of -.BR .*+?[]()|\e^$ ), -or the delimiter -preceded by -.LR \e . -.PP -A -.B charclass -is a nonempty string -.I s -bracketed -.BI [ \|s\| ] -(or -.BI [^ s\| ]\fR); -it matches any character in (or not in) -.IR s . -A negated character class never -matches newline. -A substring -.IB a - b\f1, -with -.I a -and -.I b -in ascending -order, stands for the inclusive -range of -characters between -.I a -and -.IR b . -In -.IR s , -the metacharacters -.LR - , -.LR ] , -an initial -.LR ^ , -and the regular expression delimiter -must be preceded by a -.LR \e ; -other metacharacters -have no special meaning and -may appear unescaped. -.PP -A -.L . -matches any character. -.PP -A -.L ^ -matches the beginning of a line; -.L $ -matches the end of the line. -.PP -The -.B REP -operators match zero or more -.RB ( * ), -one or more -.RB ( + ), -zero or one -.RB ( ? ), -instances respectively of the preceding regular expression -.BR e2 . -.PP -A concatenated regular expression, -.BR "e1\|e2" , -matches a match to -.B e1 -followed by a match to -.BR e2 . -.PP -An alternative regular expression, -.BR "e0\||\|e1" , -matches either a match to -.B e0 -or a match to -.BR e1 . -.PP -A match to any part of a regular expression -extends as far as possible without preventing -a match to the remainder of the regular expression. -.SH "SEE ALSO" -.IR regexp9 (3) -- cgit v1.2.3