Some man pages.
diff --git a/man/man1/9c.1 b/man/man1/9c.1 new file mode 100644 index 0000000..6745ae3 --- /dev/null +++ b/man/man1/9c.1
@@ -0,0 +1,175 @@ +.TH 9C 1 +.SH NAME +9c, 9a, 9l, 9ar \- C compiler, assembler, linker, archiver +.SH SYNOPSIS +.B 9c +.I file +\&... +.PP +.B 9a +.I file +\&... +.PP +.B 9l +[ +.I -o +.I target +] +.I object +\&... +[ +.I library +\&... +] +[ +.BI -L path +\&... +] +[ +.BI -l library +\&... +] +.PP +.B 9ar +.I key +[ +.I posname +] +.I afile +[ +.I file +\&... +] +.SH DESCRIPTION +These programs are shell scripts that invoke the appropriate standard tools +for the current operating system and architecture. +One can use them to write portable recipes for mkfiles. +.PP +.I 9c +compiles the named C +.I files +into object files for the current system. +The system C compiler is invoked with warnings enabled, +with the symbol +.B PLAN9PORT +is defined in the C preprocessor, and with +.B $PLAN9/include +on the include path. +.PP +.I 9c +also defines +.B __sun__ +on SunOS systems and +.B __Linux26__ +on Linux systems with 2.6-series kernels. +.PP +.I 9a +assembles the named files into object files for the current system. +Unlike some system assemblers, it does +.I not +promise to run the C preprocessor on the source files. +.PP +.I 9l +links the named object files and libraries to create the target executable. +Each +.B -l +option specifies that a library named +.BI lib library .a +be found and linked. +The +.B -L +option adds directories to the library search path. +.I 9l +invokes the system linker with +.B $PLAN9/lib +already on the library search path. +.PP +.I 9ar +maintains object file archives called libraries. +The exact set of valid command keys varies from system to system, +but +.I 9ar +always provides the following key characters: +.TP +.B d +Delete +.I files +from the archive file. +.TP +.B r +Replace +.I files +in the archive file, or add them if missing. +.TP +.B t +List a table of contents of the archive. +If names are given, only those files are listed. +.TP +.B x +Extract the named files. +If no names are given, all files in the archive are +extracted. +In neither case does +.B x +alter the archive file. +.TP +.B v +Verbose. +Give a file-by-file +description of the making of a +new archive file from the old archive and the constituent files. +With +.BR t , +give a long listing of all information about the files, +somewhat like a listing by +.IR ls (1), +showing +.br +.ns +.IP +.B + mode uid/gid size date name +.TP +.B c +Create. +Normally +.I 9ar +will create a new archive when +.I afile +does not exist, and give a warning. +Option +.B c +discards any old contents and suppresses the warning. +.PD +.PP +When a +.BR d , +.BR r , +or +.BR m +.I key +is specified, +.I 9ar +inserts a table of contents, required by the linker, at +the front of the library. +The table of contents is +rebuilt whenever the archive is modified. +.SH EXAMPLE +.TP +.L +9c file1.c file2.c file3.c +Compile three C source files. +.TP +.L +9a file4.s +Assemble one assembler source file. +.TP +.L +9ar rvc lib.a file[12].o +Archive the first two object files into a library. +.L +9l -o prog file3.o file4.o lib.a +Link the final two object files and any necessary objects from the library +into an executable. +.SH SOURCE +.B /usr/local/plan9/bin
diff --git a/man/man1/9p.1 b/man/man1/9p.1 new file mode 100644 index 0000000..199c26b --- /dev/null +++ b/man/man1/9p.1
@@ -0,0 +1,125 @@ +.TH 9P 1 +.SH NAME +9p \- read and write files on a 9P server +.SH SYNOPSIS +.B 9p +[ +.B -a +.I addr +] +.B read +.I path +.br +.B 9p +[ +.B -a +.I addr +] +.B readfd +.I path +.PP +.B 9p +[ +.B -a +.I addr +] +.B write +.I path +.br +.B 9p +[ +.B -a +.I addr +] +.B writefd +.I path +.PP +.B 9p +[ +.B -a +.I addr +] +.B stat +.I path +.SH DESCRIPTION +.I 9p +is a trivial 9P client that can access a single file on a 9P server. +It can be useful for manual interaction with a 9P server or for +accessing simple 9P services from within shell scripts. +.PP +The first argument is a command, one of: +.TP +.B read +print the contents of +.I path +to standard output +.TP +.B write +write data on standard input to +.I path +.TP +.BR readfd ", " writefd +like +.B read +and +.B write +but use +.IR openfd (9p) +instead of +.IR open ; +this masks errors and is mainly useful for debugging +the implementation of +.I openfd +.TP +.B stat +execute +.I stat (9p) +on +.I path +and print the result +.PD +.PP +.I 9p +dials +.I address +to connect to the 9P server. +If the +.B -a +option is not given, +.I 9p +requires the +.I path +to be of the form +.IB service / subpath \fR; +it connects to the Unix domain socket +.I service +in the name space directory +(see +.IR intro (4)) +and then accesses +.IR subpath . +.SH EXAMPLE +To update +.IR plumber (4)'s +copy of your plumbing rules after editing +.BR $HOME/lib/plumbing : +.IP +.EX +cat $HOME/lib/plumbing | 9p write plumb/rules +.EE +.PP +To display the contents of the current +.IR acme (4) +window (specified by the environment variable +.BR $winid ) +on standard output: +.IP +.EX +9p read acme/$winid/body +.EE +.SH SOURCE +.B /usr/local/plan9/src/cmd/9p.c +.SH SEE ALSO +.IR intro (4), +.IR intro (9p), +.IR 9pclient (3)
diff --git a/man/man1/9term.1 b/man/man1/9term.1 index 932a067..ebb9bd7 100644 --- a/man/man1/9term.1 +++ b/man/man1/9term.1
@@ -12,7 +12,7 @@ ] [ .I cmd -... +\&... ] .PP .B label @@ -272,7 +272,9 @@ The .B plumb menu item sends the contents of the selection (not the snarf buffer) to the -.IR plumber (1). +.I plumber +(see +.IR plumb (1)). If the selection is empty, it sends the white-space-delimited text containing the selection (typing cursor). A typical use of this feature is to tell the editor to find the source of an error
diff --git a/man/man1/INDEX b/man/man1/INDEX new file mode 100644 index 0000000..de03a62 --- /dev/null +++ b/man/man1/INDEX
@@ -0,0 +1,170 @@ +9a 9c.1 +9ar 9c.1 +9c 9c.1 +9l 9c.1 +9p 9p.1 +9term 9term.1 +label 9term.1 +acid acid.1 +acidtypes acid.1 +acme acme.1 +awd acme.1 +win acme.1 +ascii ascii.1 +unicode ascii.1 +astro astro.1 +basename basename.1 +bc bc.1 +bundle bundle.1 +cal cal.1 +calendar calendar.1 +cat cat.1 +read cat.1 +cleanname cleanname.1 +cmp cmp.1 +colors colors.1 +getmap colors.1 +comm comm.1 +core core.1 +crop crop.1 +iconv crop.1 +clock date.1 +date date.1 +db db.1 +dc dc.1 +delatex deroff.1 +deroff deroff.1 +dict dict.1 +diff diff.1 +doctype doctype.1 +echo echo.1 +ed ed.1 +eqn eqn.1 +factor factor.1 +primes factor.1 +fmt fmt.1 +htmlfmt fmt.1 +fortune fortune.1 +freq freq.1 +fsize fsize.1 +mtime fsize.1 +grap grap.1 +graph graph.1 +g grep.1 +grep grep.1 +gview gview.1 + +bunzip2 gzip.1 +bzip2 gzip.1 +gunzip gzip.1 +gzip gzip.1 +unzip gzip.1 +zip gzip.1 +hoc hoc.1 +idiff idiff.1 +join join.1 +bmp jpg.1 +gif jpg.1 +ico jpg.1 +jpg jpg.1 +png jpg.1 +ppm jpg.1 +togif jpg.1 +toico jpg.1 +topng jpg.1 +toppm jpg.1 +yuv jpg.1 +kill kill.1 +slay kill.1 +start kill.1 +stop kill.1 +awd label.1 +label label.1 +lex lex.1 +look look.1 +lc ls.1 +ls ls.1 +lookman man.1 +man man.1 +map map.1 +mapdemo map.1 +mc mc.1 +membername mk.1 +mk mk.1 +mkdir mkdir.1 +namespace namespace.1 +news news.1 +p p.1 +img page.1 +page page.1 +psv page.1 +pic pic.1 +tpic pic.1 +plot plot.1 +plumb plumb.1 +pr pr.1 +proof proof.1 +ps ps.1 +psu ps.1 +pbd pwd.1 +pwd pwd.1 +. rc.1 +cd rc.1 +eval rc.1 +exec rc.1 +exit rc.1 +flag rc.1 +rc rc.1 +rfork rc.1 +shift rc.1 +wait rc.1 +whatis rc.1 +~ rc.1 +rio rio.1 +rm rm.1 +B sam.1 +E sam.1 +sam sam.1 +sam.save sam.1 +samsave sam.1 +samterm sam.1 +scat scat.1 +aescbc secstore.1 +ipso secstore.1 +secstore secstore.1 +9sed sed.1 +sed sed.1 +seq seq.1 +sleep sleep.1 +sort sort.1 +spell spell.1 +sprog spell.1 +split split.1 +src src.1 +stats stats.1 +strings strings.1 +md5sum sum.1 +sha1sum sum.1 +sum sum.1 +tail tail.1 +tbl tbl.1 +tcs tcs.1 +tee tee.1 +test test.1 +time time.1 +touch touch.1 +tr tr.1 +nroff troff.1 +troff troff.1 +tweak tweak.1 +uniq uniq.1 +units units.1 +vac vac.1 +wc wc.1 +web web.1 +wmail web.1 +" wintext.1 +"" wintext.1 +wintext wintext.1 +xd xd.1 +yacc yacc.1
diff --git a/man/man1/acid.1 b/man/man1/acid.1 index 2d1523a..1f7c264 100644 --- a/man/man1/acid.1 +++ b/man/man1/acid.1
@@ -26,7 +26,7 @@ .I prefix ] .I file -... +\&... .\" .PP .\" .B acid .\" .B -l @@ -69,17 +69,9 @@ .TP .BI -m " machine Assume instructions are for the given CPU type -(one of -.BR 3210 , -.BR 386 , -etc., as listed in -.IR 2c (1), -or -.B sunsparc -or -.B mipsco -for the manufacturer-defined instruction notation for those processors) -instead of using the magic number to select +(see +.IR mach (3)) +instead of using the executable header to select the CPU type. .TP .BI -k @@ -100,9 +92,17 @@ If the function .IR acidinit () is defined, it will be invoked after all modules have been loaded. -See -.IR 2c (1) -for information about creating +Then the function +.IR acidmap () +will be invoked if defined. +.B /usr/local/plan9/acid/port +provides a definition of +.I acidmap +that attaches all the shared libraries being used by the target process +and then runs +.I acidtypes +.RI ( q.v. ) +to create .I acid functions for examining data structures. .SS Language
diff --git a/man/man1/acme.1 b/man/man1/acme.1 index 359799b..6f16273 100644 --- a/man/man1/acme.1 +++ b/man/man1/acme.1
@@ -345,7 +345,7 @@ prints the supplementary list. This command is largely superseded by plumbing (see -.IR plumb (6)). +.IR plumb (7)). .TP .B Kill Send a @@ -355,20 +355,30 @@ commands named as arguments. .TP .B Local -When prefixed to a command -run the -command in the same file name space and environment variable group as -.IR acme . -The environment of the command -is restricted but is sufficient to run -.IR bind (1), -.IR 9fs -(see -.IR srv (4)), -.IR import (4), -etc., -and to set environment variables such as -.BR $objtype . +In the Plan 9 +.IR acme , +this prefix causes a command to be run in +.IR acme 's own +file name space and environment variable group. +On Unix this is impossible. +.B Local +is recognized as a prefix, but has no effect on the command being executed. +.\" .TP +.\" .B Local +.\" When prefixed to a command +.\" run the +.\" command in the same file name space and environment variable group as +.\" .IR acme . +.\" The environment of the command +.\" is restricted but is sufficient to run +.\" .IR bind (1), +.\" .IR 9fs +.\" (see +.\" .IR srv (4)), +.\" .IR import (4), +.\" etc., +.\" and to set environment variables such as +.\" .BR $objtype . .TP .B Load Restore the state of @@ -662,9 +672,9 @@ .SH SOURCE .B /usr/local/plan9/src/cmd/acme .br -.B /acme/bin/source/win +.B /usr/local/plan9/src/cmd/9term/win.c .br -.B /usr/local/plan9/src/cmd/awd.c +.B /usr/local/plan9/bin/awd .SH SEE ALSO .IR acme (4) .br
diff --git a/man/man1/ascii.1 b/man/man1/ascii.1 index 05cec0f..20a4302 100644 --- a/man/man1/ascii.1 +++ b/man/man1/ascii.1
@@ -91,7 +91,7 @@ is similar; it converts between .SM UTF and character values from the Unicode Standard (see -.IR utf (6)). +.IR utf (7)). If given a range of hexadecimal numbers, .I unicode prints a table of the specified Unicode characters \(em their values and @@ -157,5 +157,5 @@ .SH "SEE ALSO" .IR look (1) .IR tcs (1), -.IR utf (6), -.IR font (6) +.IR utf (7), +.IR font (7)
diff --git a/man/man1/astro.1 b/man/man1/astro.1 new file mode 100644 index 0000000..e2502f9 --- /dev/null +++ b/man/man1/astro.1
@@ -0,0 +1,122 @@ +.TH ASTRO 1 +.SH NAME +astro \- print astronomical information +.SH SYNOPSIS +.B astro +[ +.B -dlpsatokm +] +[ +.B -c +n +] +[ +.B -C +d +] +[ +.B -e +.I obj1 +.I obj2 +] +.SH DESCRIPTION +.I Astro +reports upcoming celestial events, by default for 24 hours starting now. +The options are: +.TP +.B d +Read the starting date. +A prompt gives the input +format. +.TP +.B l +Read the north latitude, west longitude, and elevation of the observation point. +A prompt gives the input format. +If +.B l +is missing, the initial position is read from the file +.BR /lib/sky/here . +.TP +.B c +Report for +.I n +(default 1) successive days. +.TP +.B C +Used with +.BR -c , +set the interval to +.B d +days (or fractions of days). +.TP +.B e +Report distance between the centers of +objects, in arc seconds, during eclipses or occultations involving +.I obj1 +and +.IR obj2 . +.TP +.B p +Print the positions of objects at the +given time rather than searching for interesting +conjunctions. +For each, the name is followed by +the right ascension (hours, minutes, seconds), +declination (degrees, minutes, seconds), +azimuth (degrees), +elevation (degrees), +and semidiameter (arc seconds). +For the sun and moon, the magnitude is also printed. +The first line of output presents the date and time, +sidereal time, and the latitude, longitude, and elevation. +.TP +.B s +Print output in English words suitable for speech synthesizers. +.TP +.B a +Include a list of artificial earth satellites for interesting events. +(There are no orbital elements for the satellites, so this option +is not usable.) +.TP +.B t +Read +ΔT +from standard input. +ΔT +is the difference between ephemeris and +universal time (seconds) due to the slowing of the earth's rotation. +ΔT +is normally calculated from an empirical formula. +This option is needed only for very accurate timing of +occultations, eclipses, etc. +.TP +.B o +Search for stellar occultations. +.TP +.B k +Print times in local time (`kitchen clock') +as described in the +.B timezone +environment variable. +.TP +.B m +Includes a single comet in the list of objects. +This is modified (in the source) to refer to an approaching comet +but in steady state +usually refers to the last interesting comet (currently Hale-Bopp, C/1995 O1). +.SH FILES +.TF /lib/sky/estartab +.TP +.B /lib/sky/estartab +ecliptic star data +.TP +.B /lib/sky/here +default latitude (N), longitude (W), and elevation (meters) +.SH SOURCE +.B /usr/local/plan9/src/cmd/astro +.SH SEE ALSO +.IR scat (1) +.SH BUGS +The +.B k +option reverts to GMT outside of 1970-2036.
diff --git a/man/man1/bc.1 b/man/man1/bc.1 new file mode 100644 index 0000000..9bb0f08 --- /dev/null +++ b/man/man1/bc.1
@@ -0,0 +1,292 @@ +.TH BC 1 +.SH NAME +bc \- arbitrary-precision arithmetic language +.SH SYNOPSIS +.B bc +[ +.B -c +] +[ +.B -l +] +[ +.B -s +] +[ +.I file ... +] +.SH DESCRIPTION +.I Bc +is an interactive processor for a language that resembles +C but provides arithmetic on numbers of arbitrary length with up +to 100 digits right of the decimal point. +It takes input from any files given, then reads +the standard input. +The +.B -l +argument stands for the name +of an arbitrary precision math library. +The +.B -s +argument suppresses the automatic display +of calculation results; all output is via the +.B print +command. +.PP +The following syntax for +.I bc +programs is like that of C; +.I L +means letter +.BR a - z , +.I E +means expression, +.I S +means statement. +.TF length(E) +.TP +Lexical +.RS +.HP +comments are enclosed in +.B /* */ +.HP +newlines end statements +.RE +.TP +Names +.IP +simple variables: +.I L +.br +array elements: +.IB L [ E ] +.br +The words +.BR ibase , +.BR obase , +and +.B scale +.TP +Other operands +.IP +arbitrarily long numbers with optional sign and decimal point. +.RS +.TP +.BI ( E ) +.TP +.BI sqrt( E ) +.TP +.BI length( E ) +number of significant decimal digits +.TP +.BI scale( E ) +number of digits right of decimal point +.TP +.IB L ( E , ... ,\fIE\fP) +function call +.RE +.TP +Operators +.RS +.HP +.B "+ - * / % ^\ " +.RB ( % +is remainder; +.B ^ +is power) +.HP +.B "++ --\ " +.TP +.B "== <= >= != < >" +.TP +.B "= += -= *= /= %= ^=" +.RE +.TP +Statements +.RS +.br +.I E +.br +.B { +.I S +.B ; +\&... +.B ; +.I S +.B } +.br +.B "print" +.I E +.br +.B "if (" +.I E +.B ) +.I S +.br +.B "while (" +.I E +.B ) +.I S +.br +.B "for (" +.I E +.B ; +.I E +.B ; +.I E +.B ")" +.I S +.br +null statement +.br +.B break +.br +.B quit +.br +\fL"\fRtext\fL"\fR +.RE +.TP +Function definitions +.RS +.br +.B define +.I L +.B ( +.I L +.B , +\&... +.B , +.I L +.B ){ +.PD0 +.br +.B auto +.I L +.B , +\&... +.B , +.I L +.br +.I S +.B ; +\&... +.B ; +.I S +.br +.B return +.I E +.LP +.B } +.RE +.TP +Functions in +.B -l +math library +.RS +.TP +.BI s( x ) +sine +.TP +.BI c( x ) +cosine +.TP +.BI e( x ) +exponential +.TP +.BI l( x ) +log +.TP +.BI a( x ) +arctangent +.TP +.BI j( "n, x" ) +Bessel function +.RE +.PP +.DT +All function arguments are passed by value. +.PD +.PP +The value of an expression at the top level is printed +unless the main operator is an assignment or the +.B -s +command line argument is given. +Text in quotes, which may include newlines, is always printed. +Either semicolons or newlines may separate statements. +Assignment to +.B scale +influences the number of digits to be retained on arithmetic +operations in the manner of +.IR dc (1). +Assignments to +.B ibase +or +.B obase +set the input and output number radix respectively. +.PP +The same letter may be used as an array, a function, +and a simple variable simultaneously. +All variables are global to the program. +Automatic variables are pushed down during function calls. +In a declaration of an array as a function argument +or automatic variable +empty square brackets must follow the array name. +.PP +.I Bc +is actually a preprocessor for +.IR dc (1), +which it invokes automatically, unless the +.B -c +(compile only) +option is present. +In this case the +.I dc +input is sent to the standard output instead. +.SH EXAMPLE +Define a function to compute an approximate value of +the exponential. +Use it to print 10 values. +(The exponential function in the library gives better answers.) +.PP +.EX +scale = 20 +define e(x) { + auto a, b, c, i, s + a = 1 + b = 1 + s = 1 + for(i=1; 1; i++) { + a *= x + b *= i + c = a/b + if(c == 0) return s + s += c + } +} +for(i=1; i<=10; i++) print e(i) +.EE +.SH FILES +.B /sys/lib/bclib +mathematical library +.SH SOURCE +.B /usr/local/plan9/src/cmd/bc.y +.SH "SEE ALSO" +.IR dc (1), +.IR hoc (1) +.SH BUGS +No +.LR && , +.LR || , +or +.L ! +operators. +.br +A +.L for +statement must have all three +.LR E s. +.br +A +.L quit +is interpreted when read, not when executed.
diff --git a/man/man1/bundle.1 b/man/man1/bundle.1 new file mode 100644 index 0000000..c56e943 --- /dev/null +++ b/man/man1/bundle.1
@@ -0,0 +1,57 @@ +.TH BUNDLE 1 +.SH NAME +bundle \- collect files for distribution +.SH SYNOPSIS +.B bundle +.I file ... +.SH DESCRIPTION +.I Bundle +writes on its standard output a shell script for +.IR rc (1) +or a Bourne shell +which, when executed, +will recreate the original +.IR files . +Its main use is for distributing small numbers of text files by +.IR mail (1). +.PP +Although less refined than standard archives from +.I 9ar +(see +.IR 9c (1)) +or +.IR tar (1), +a +.IR bundle +file +is self-documenting and complete; little preparation is required on +the receiving machine. +.SH EXAMPLES +.TP +.L +bundle mkfile *.[ch] | mail kremvax!boris +Send a makefile to Boris together with related +.L .c +and +.L .h +files. +Upon receiving the mail, Boris may save the file sans postmark, +say in +.BR gift/horse , +then do +.TP +.L +cd gift; rc horse; mk +.SH SOURCE +.B /usr/local/plan9/bin/bundle +.SH SEE ALSO +.I 9ar +(in +.IR 9c (1)), +.IR tar (1), +.IR mail (1) +.SH BUGS +.I Bundle +will not create directories and is unsatisfactory for non-text files. +.br +Beware of gift horses.
diff --git a/man/man1/cat.1 b/man/man1/cat.1 index 3b24bdd..d2b8d5c 100644 --- a/man/man1/cat.1 +++ b/man/man1/cat.1
@@ -1,6 +1,6 @@ .TH CAT 1 .SH NAME -cat, read \- catenate files +cat, read, nobs \- catenate files .SH SYNOPSIS .B cat [ @@ -16,6 +16,11 @@ ] [ .I file ... ] +.br +nobs +[ +.I file ... +] .SH DESCRIPTION .I Cat reads each @@ -57,15 +62,32 @@ .I nline lines. .PP -Read always executes a single +.I Read +always executes a single .B write for each line of input, which can be helpful when preparing input to programs that expect line-at-a-time data. It never reads any more data from the input than it prints to the output. +.PP +.I Nobs +copies the named files to +standard output except that it removes all backspace +characters and the characters that precede them. +It is useful to use as +.B $PAGER +with the Unix version of +.IR man (1) +when run inside a +.I win +(see +.IR acme (1)) +window. .SH SOURCE .B /usr/local/plan9/src/cmd/cat.c .br .B /usr/local/plan9/src/cmd/read.c +.br +.B /usr/local/plan9/bin/nobs .SH SEE ALSO .IR cp (1) .SH DIAGNOSTICS
diff --git a/man/man1/cleanname.1 b/man/man1/cleanname.1 index d017ce5..d219138 100644 --- a/man/man1/cleanname.1 +++ b/man/man1/cleanname.1
@@ -29,4 +29,4 @@ .SH SOURCE .B /usr/local/plan9/src/cmd/cleanname.c .SH SEE ALSO -.IR cleanname (2). +.IR cleanname (3).
diff --git a/man/man1/colors.1 b/man/man1/colors.1 new file mode 100644 index 0000000..ea33e9a --- /dev/null +++ b/man/man1/colors.1
@@ -0,0 +1,73 @@ +.TH COLORS 1 +.SH NAME +getmap, colors \- display color map +.SH SYNOPSIS +.PP +.B colors +[ +.B -r +.B -x +] +.PP +.B getmap +[ +.I colormap +] +.SH DESCRIPTION +.I Colors +presents a grid showing the colors in the current color map. +If the display is true color, +.I colors +shows a grid of the RGBV color map +(see +.IR color (7)). +.PP +Clicking mouse button 1 over a color in the grid will display the map index for that color, +its +red, green, and blue components, +and the 32-bit hexadecimal color value as defined in +.IR allocimage (3). +If the +.B -x +option is specified, the components will also be listed in hexadecimal. +.PP +The +.B -r +option instead shows, in the same form, a grey-scale ramp. +.PP +A menu on mouse button 3 contains a single entry, to exit the program. +.PP +On 8-bit color-mapped displays, +.I getmap +loads the display's color map (default +.BR rgbv ). +The named +.I colormap +can be a file in the current directory or in the standard repository +.BR /lib/cmap . +It can also be a string of the form +.B gamma +or +.BI gamma N\f1 , +where +.I N +is a floating point value for the gamma, defining the contrast for a monochrome map. +Similarly, +.B rgamma +and +.BI rgamma N +define a reverse-video monochrome map. +Finally, the names +.B screen +or +.B display +or +.B vga +are taken as synonyms for the current color map stored in the display hardware. +.SH FILES +.B /lib/cmap +directory of color map files +.SH SOURCE +.B /usr/local/plan9/src/cmd/draw/colors.c +.SH SEE ALSO +.IR color (7)
diff --git a/man/man1/core.1 b/man/man1/core.1 new file mode 100644 index 0000000..3c2c0d4 --- /dev/null +++ b/man/man1/core.1
@@ -0,0 +1,46 @@ +.TH CORE 1 +.SH NAME +core \- print information about dead processes +.SH SYNOPSIS +.B core +[ +.I dir +| +.I corefile +]... +.SH DESCRIPTION +.I Core +prints information about dead processes that have +been saved as core dumps. +.PP +Core reads its arguments in order. +If a directory is encountered, +.I core +reads every core file named +.B core.* +or +.B *.core +in that directory. +.PP +For each core file read, +.I core +prints the date and time the core was generated, +the command that generated it, and a short stack trace +at the time of the core dump. +.PP +If no arguments are given, +.I core +searches the directory +.B $COREDIR +for core files; +if +.B $COREDIR +is not set, +.I core +searches the current directory. +.SH SOURCE +.B /usr/local/plan9/src/cmd/core.c +.SH "SEE ALSO +.IR acid (1), +.IR db (1), +.IR core (5)
diff --git a/man/man1/crop.1 b/man/man1/crop.1 new file mode 100644 index 0000000..2804ece --- /dev/null +++ b/man/man1/crop.1
@@ -0,0 +1,147 @@ +.TH CROP 1 +.SH NAME +crop, iconv \- frame, crop, and convert image +.SH SYNOPSIS +.B crop +[ +.BI -c +.I red +.I green +.I blue +] +[ +.B -i +.I n +| +.B -x +.I dx +| +.B -y +.I dy +| +.B -r +.I minx +.I miny +.I maxx +.I maxy +] +[ +.B -t +.I tx +.I ty +] +[ +.B -b +.I red +.I green +.I blue +] +[ +.I file +] +.PP +.B iconv +[ +.B -u +] [ +.B -c +.I chandesc +] +[ +.I file +] +.SH DESCRIPTION +.I Crop +reads an +.IR image (7) +file (default standard input), crops it, and writes it as a compressed +.IR image (7) +file to standard output. +There are two ways to specify a crop, by color value or by geometry. +They may be combined in a single run of +.IR crop , +in which case the color value crop will be done first. +.PP +The +.B -c +option takes a red-green-blue triplet as described in +.IR color (3). +(For example, white +is +.B 255 +.B 255 +.BR 255 .) +The corresponding color is used as a value to be cut from the outer +edge of the picture; that is, the image is cropped to remove the maximal +outside rectangular strip in which every pixel has the specified color. +.PP +The +.B -i +option insets the image rectangle by a constant amount, +.IR n , +which may be negative to generate extra space around the image. +The +.B -x +and +.B -y +options are similar, but apply only to the +.I x +or +.I y +coordinates of the image. +.PP +The +.B -r +option specifies an exact rectangle. +.PP +The +.B -t +option specifies that the image's coordinate system should +be translated by +.IR tx , +.IR ty +as the last step of processing. +.PP +The +.B -b +option specifies a background color to be used to fill around the image +if the cropped image is larger than the original, such as if the +.B -i +option is given a negative argument. +This can be used to draw a monochrome frame around the image. +The default color is black. +.PP +.I Iconv +changes the format of pixels in the image +.I file +(default standard input) and writes the resulting image to standard output. +Pixels in the image are converted according to the channel descriptor +.IR chandesc , +(see +.IR image (7)). +For example, to convert a 4-bit-per-pixel grey-scale image to an 8-bit-per-pixel +color-mapped image, +.I chandesc +should be +.BR m8 . +If +.I chandesc +is not given, the format is unchanged. +The output image is by default compressed; the +.B -u +option turns off the compression. +.SH EXAMPLE +To crop white edges off the picture and add a ten-pixel pink border, +.IP +.EX +crop -c 255 255 255 -i -10 -b 255 150 150 imagefile > cropped +.EE +.SH SOURCE +.B /usr/local/plan9/src/cmd/draw/crop.c +.SH SEE ALSO +.IR image (7), +.IR color (3) +.SH BUGS +.I Iconv +should be able to do Floyd-Steinberg error diffusion or dithering +when converting to small image depths.
diff --git a/man/man1/date.1 b/man/man1/date.1 index cdc0228..45440e6 100644 --- a/man/man1/date.1 +++ b/man/man1/date.1
@@ -8,8 +8,8 @@ ] [ .I seconds ] -.br -.B clock +.\" .br +.\" .B clock .SH DESCRIPTION Print the date, in the format .PP @@ -28,31 +28,31 @@ The conversion from Greenwich Mean Time to local time depends on the .B $timezone environment variable; see -.IR ctime (2). +.IR ctime (3). .PP If the optional argument .I seconds is present, it is used as the time to convert rather than the real time. -.SH FILES -.TF /adm/timezone/local -.TP -.B /env/timezone -Current timezone name and adjustments. -.TP -.B /adm/timezone -A directory containing timezone tables. -.TP -.B /adm/timezone/local -Default timezone file, copied by -.IR init (8) -into -.BR /env/timezone . -.PD -.PP -.I Clock -draws a simple analog clock in its window. +.\" .SH FILES +.\" .TF /adm/timezone/local +.\" .TP +.\" .B /env/timezone +.\" Current timezone name and adjustments. +.\" .TP +.\" .B /adm/timezone +.\" A directory containing timezone tables. +.\" .TP +.\" .B /adm/timezone/local +.\" Default timezone file, copied by +.\" .IR init (8) +.\" into +.\" .BR /env/timezone . +.\" .PD +.\" .PP +.\" .I Clock +.\" draws a simple analog clock in its window. .SH SOURCE .B /usr/local/plan9/src/cmd/date.c -.br -.B /usr/local/plan9/src/cmd/clock.c +.\" .br +.\" .B /usr/local/plan9/src/cmd/draw/clock.c
diff --git a/man/man1/db.1 b/man/man1/db.1 index 10d38cb..b802100 100644 --- a/man/man1/db.1 +++ b/man/man1/db.1
@@ -33,9 +33,7 @@ A .I pid gives the id of an executing process to be accessed via -.IR ptrace (2) -or -.IR proc (5). +.IR ptrace (2). A .I corefile specifies the name of a core dump (see @@ -949,7 +947,6 @@ Beware that local variables may be stored in registers; see the BUGS section. .SH "SEE ALSO" -.IR 9nm (1), .IR acid (1) .SH SOURCE .B /usr/local/plan9/src/cmd/db
diff --git a/man/man1/deroff.1 b/man/man1/deroff.1 index 2097a80..18d6228 100644 --- a/man/man1/deroff.1 +++ b/man/man1/deroff.1
@@ -67,7 +67,7 @@ Remove titles, attachments, etc., as well as ordinary .IR troff constructs, from -.IR ms (6) +.IR ms (7) or .I mm documents. @@ -93,7 +93,7 @@ .SH SOURCE .B /usr/local/plan9/src/cmd/deroff.c .br -.B /usr/local/plan9/src/cmd/tex/local/delatex.c +.B /usr/local/plan9/src/cmd/delatex.lx .SH "SEE ALSO" .IR troff (1), .IR tex (1),
diff --git a/man/man1/dict.1 b/man/man1/dict.1 index 1665ea7..3c01c71 100644 --- a/man/man1/dict.1 +++ b/man/man1/dict.1
@@ -1,4 +1,4 @@ -.TH DICT 7 +.TH DICT 1 .SH NAME dict \- dictionary browser .SH SYNOPSIS @@ -46,7 +46,7 @@ .PD .PP Patterns are regular expressions (see -.IR regexp (6)), +.IR regexp (7)), with an implicit leading .L ^ and trailing @@ -146,18 +146,22 @@ Other files in .BR /lib . .SH "SEE ALSO" -.IR regexp (6) +.IR regexp (7) .SH SOURCE .B /usr/local/plan9/src/cmd/dict .SH BUGS A font with wide coverage of the Unicode Standard should be used for best results. (Try -.BR /lib/font/bit/pelm/unicode.9.font .) -.br +.BR /usr/local/plan9/font/pelm/unicode.9.font .) +.PP If the .I pattern doesn't begin with a few literal characters, matching takes a long time. -.br -The dictionaries are not distributed outside Bell Labs. +.PP +The dictionaries are not distributed outside Bell Labs, +though see +.B /usr/local/plan9/dict/README +for information on using free dictionaries prepared +by Project Gutenberg.
diff --git a/man/man1/doctype.1 b/man/man1/doctype.1 new file mode 100644 index 0000000..cb339ae --- /dev/null +++ b/man/man1/doctype.1
@@ -0,0 +1,56 @@ +.TH DOCTYPE 1 +.SH NAME +doctype \- intuit command line for formatting a document +.SH SYNOPSIS +.B doctype +[ +.I option ... +] [ +.I file +] +\&... +.SH DESCRIPTION +.I Doctype +examines a +.IR troff (1) +input file to deduce the appropriate text formatting command +and prints it on standard output. +.I Doctype +recognizes input for +.IR troff (1), +related preprocessors like +.IR eqn (1), +and the +.IR ms (7) +and +.I mm +macro packages. +.PP +Option +.B -n +invokes +.I nroff +instead of +.IR troff . +Other options are passed to +.IR troff . +.SH EXAMPLES +.TP +.L +eval `{doctype chapter.?} | lp +Typeset files named +.BR chapter.0 , +.BR chapter.1 , +\&... +.SH SOURCE +.B /usr/local/plan9/bin/doctype +.SH SEE ALSO +.IR troff (1), +.IR eqn (1), +.IR tbl (1), +.IR pic (1), +.IR grap (1), +.IR ms (7), +.IR man (7) +.SH BUGS +In true A.I. style, its best guesses are inspired rather than accurate.
diff --git a/man/man1/ed.1 b/man/man1/ed.1 index 7b88f11..b61972b 100644 --- a/man/man1/ed.1 +++ b/man/man1/ed.1
@@ -96,7 +96,7 @@ supports the .I "regular expression" notation described in -.IR regexp (6). +.IR regexp (7). Regular expressions are used in addresses to specify lines and in one command (see @@ -673,7 +673,7 @@ .SH "SEE ALSO" .IR sam (1), .IR sed (1), -.IR regexp (6) +.IR regexp (7) .SH DIAGNOSTICS .BI ? name for inaccessible file;
diff --git a/man/man1/eqn.1 b/man/man1/eqn.1 index 7c917cd..2d91449 100644 --- a/man/man1/eqn.1 +++ b/man/man1/eqn.1
@@ -316,7 +316,7 @@ .B /sys/lib/troff/font/devutf font descriptions for PostScript .SH SOURCE -.B /sys/src/cmd/eqn +.B /usr/local/plan9/src/cmd/eqn .SH "SEE ALSO" .IR troff (1), .IR tbl (1)
diff --git a/man/man1/freq.1 b/man/man1/freq.1 index fd326a2..853e479 100644 --- a/man/man1/freq.1 +++ b/man/man1/freq.1
@@ -36,5 +36,5 @@ .SH SOURCE .B /usr/local/plan9/src/cmd/freq.c .SH SEE ALSO -.IR utf (6), +.IR utf (7), .IR wc (1)
diff --git a/man/man1/fsize.1 b/man/man1/fsize.1 new file mode 100644 index 0000000..cabe7f3 --- /dev/null +++ b/man/man1/fsize.1
@@ -0,0 +1,22 @@ +.TH FSIZE 1 +.SH NAME +fsize, mtime \- print file information +.SH SYNOPSIS +.B fsize +.I file ... +.PP +.B mtime +.I file ... +.SH DESCRIPTION +.I Fsize +prints the name and size of each of the files. +.PP +.I Mtime +prints the name and modification time (in seconds since the epoch) +of each of the files. +.SH SOURCE +.B /usr/local/plan9/src/cmd/fsize.c +.br +.B /usr/local/plan9/src/cmd/mtime.c +.SH BUGS +The output formats of the two programs are different.
diff --git a/man/man1/grap.1 b/man/man1/grap.1 index b098f82..8fbfaaa 100644 --- a/man/man1/grap.1 +++ b/man/man1/grap.1
@@ -404,7 +404,7 @@ .B /sys/lib/grap.defines definitions of standard plotting characters, e.g., bullet .SH SOURCE -.B /sys/src/cmd/grap +.B /usr/local/plan9/src/cmd/grap .SH "SEE ALSO" .IR pic (1), .IR troff (1)
diff --git a/man/man1/graph.1 b/man/man1/graph.1 index 4cdc6b2..f105d87 100644 --- a/man/man1/graph.1 +++ b/man/man1/graph.1
@@ -135,7 +135,7 @@ the axis is reversed. .SH SOURCE -.B /sys/src/cmd/graph +.B /usr/local/plan9/src/cmd/graph .SH "SEE ALSO" .IR plot (1), .IR grap (1)
diff --git a/man/man1/grep.1 b/man/man1/grep.1 index e58d0d9..b8cb431 100644 --- a/man/man1/grep.1 +++ b/man/man1/grep.1
@@ -1,6 +1,6 @@ .TH GREP 1 .SH NAME -grep \- search a file for a pattern +grep, g \- search a file for a pattern .SH SYNOPSIS .B grep [ @@ -10,6 +10,14 @@ [ .I file ... ] +.B g +[ +.I option ... +] +.I pattern +[ +.I file ... +] .SH DESCRIPTION .I Grep\^ searches the input @@ -18,7 +26,7 @@ for lines that match the .IR pattern , a regular expression as defined in -.IR regexp (6) +.IR regexp (7) with the addition of a newline character as an alternative (substitute for .BR | ) @@ -90,14 +98,26 @@ An expression starting with '*' will treat the rest of the expression as literal characters. +.PP +.I G +invokes grep with +.B -n +and forces tagging of output lines by file name. +If no files are listed, it searches all files matching +.IP +.EX +*.C *.b *.c *.h *.m *.cc *.java *.py *.tex *.ms +.EE .SH SOURCE .B /usr/local/plan9/src/cmd/grep +.br +.B /usr/local/plan9/bin/g .SH SEE ALSO .IR ed (1), .IR awk (1), .IR sed (1), .IR sam (1), -.IR regexp (6) +.IR regexp (7) .SH DIAGNOSTICS Exit status is null if any lines are selected, or non-null when no lines are selected or an error occurs.
diff --git a/man/man1/gzip.1 b/man/man1/gzip.1 new file mode 100644 index 0000000..5888689 --- /dev/null +++ b/man/man1/gzip.1
@@ -0,0 +1,160 @@ +.TH GZIP 1 +.SH NAME +gzip, gunzip, bzip2, bunzip2, zip, unzip, \- compress and expand data +.SH SYNOPSIS +.B gzip +.RB [ -cvD [ 1-9 ]] +.RI [ file +.BR ... ] +.PP +.B gunzip +.RB [ -ctTvD ] +.RI [ file +.BR ... ] +.PP +.B bzip2 +.RB [ -cvD [ 1-9 ]] +.RI [ file +.BR ... ] +.PP +.B bunzip2 +.RB [ -cvD ] +.RI [ file +.BR ... ] +.PP +.B zip +.RB [ -vD [ 1-9 ]] +.RB [ -f +.IR zipfile ] +.I file +.RB [ ... ] +.PP +.B unzip +.RB [ -cistTvD ] +.RB [ -f +.IR zipfile ] +.IR [ file +.BR ... ] +.SH DESCRIPTION +.PP +.I Gzip +encodes files with a hybrid Lempel-Ziv 1977 and Huffman compression algorithm +known as +.BR deflate . +Most of the time, the resulting file is smaller, +and will never be much bigger. +Output files are named by taking the last path element of each file argument +and appending +.BR .gz ; +if the resulting name ends with +.BR .tar.gz , +it is converted to +.B .tgz +instead. +.I Gunzip +reverses the process. +Its output files are named by taking the last path element of each file argument, +converting +.B .tgz +to +.BR .tar.gz , +and stripping any +.BR .gz ; +the resulting name must be different from the original name. +.PP +.I Bzip2 +and +.I bunzip2 +are similar in interface to +.I gzip +and +.IR gunzip , +but use a modified Burrows-Wheeler block sorting +compression algorithm. +The default suffix for output files is +.BR .bz2 , +with +.B .tar.bz2 +becoming +.BR .tbz . +.I Bunzip2 +recognizes the extension +.B .tbz2 +as a synonym for +.BR .tbz . +.PP +.I Zip +encodes the named files and places the results into the archive +.IR zipfile , +or the standard output if no file is given. +.I Unzip +extracts files from an archive created by +.IR zip . +If no files are named as arguments, all of files in the archive are extracted. +A directory's name implies all recursively contained files and subdirectories. +.PP +None of these programs removes the original files. +If the process fails, the faulty output files are removed. +.PP +The options are: +.TP 1i +.B -c +Write to standard output rather than creating an output file. +.TP +.B -i +Convert all archive file names to lower case. +.TP +.B -s +Streaming mode. Looks at the file data adjacent to each compressed file +rather than seeking in the central file directory. +This is the mode used by +.I unzip +if no +.I zipfile +is specified. +If +.B -s +is given, +.B -T +is ignored. +.TP +.B -t +List matching files in the archive rather than extracting them. +.TP +.B -T +Set the output time to that specified in the archive. +.TP +.BR -1 " .. " -9 +Sets the compression level. +.B -1 +is tuned for speed, +.B -9 +for minimal output size. +The best compromise is +.BR -6 , +the default. +.TP +.B -v +Produce more descriptive output. +With +.BR -t , +adds the uncompressed size in bytes and the modification time to the output. +Without +.BR -t , +prints the names of files on standard error as they are compressed or decompressed. +.TP +.B -D +Produce debugging output. +.SH SOURCE +.B /usr/local/plan9/src/cmd/gzip +.br +.B /usr/local/plan9/src/cmd/bzip2 +.SH SEE ALSO +.IR tar (1), +.IR compress (1) +.SH BUGS +.I Unzip +can only extract files which are uncompressed or compressed +with the +.B deflate +compression scheme. Recent zip files fall into this category.
diff --git a/man/man1/join.1 b/man/man1/join.1 index 2cf079f..841d077 100644 --- a/man/man1/join.1 +++ b/man/man1/join.1
@@ -106,21 +106,21 @@ .SH EXAMPLES .TP .L -sort -t: +1 /adm/users | join -t: -1 2 -a 1 -e "" - bdays +sort /etc/passwd | join -t: -1 1 -a 1 -e "" - bdays Add birthdays to the -.B /adm/users +.B /etc/passwd file, leaving unknown birthdays empty. The layout of .B /adm/users is given in -.IR users (6); +.IR passwd (5); .B bdays contains sorted lines like .LR "ken:Feb\ 4,\ 1953" . .TP .L -tr : ' ' </adm/users | sort -k 3 3 >temp +tr : ' ' </etc/passwd | sort -k 3 3 >temp .br .ns .TP @@ -145,4 +145,3 @@ .BI -k y , y\f1. .br One of the files must be randomly accessible. -
diff --git a/man/man1/jpg.1 b/man/man1/jpg.1 new file mode 100644 index 0000000..b81490b --- /dev/null +++ b/man/man1/jpg.1
@@ -0,0 +1,243 @@ +.TH JPG 1 +.SH NAME +jpg, gif, png, ppm, bmp, yuv, ico, togif, toppm, topng, toico \- view and convert pictures +.SH SYNOPSIS +.B jpg +[ +.B -39cdefFkJrtv +] [ +.I file ... +] +.br +.B gif +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B png +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B ppm +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B bmp +[ +.I file +] +.br +.B yuv +[ +.I file +] +.PP +.B togif +[ +.B -c +.I comment +] [ +.B -l +.I loopcount +] [ +.B -d +.I msec +] [ +.B -t +.I transindex +] [ +.I file ... +[ +.B -d +.I msec +] +.I file ... +] +.br +.B toppm +[ +.B -c +.I comment +] [ +.I file +] +.br +.B topng +[ +.B -c +.I comment +] [ +[ +.B -g +.I gamma +] [ +.I file +] +.PP +.B ico +[ +.I file +] +.br +.B toico +[ +.I file ... +] +.SH DESCRIPTION +These programs read, display, and write image files in public formats. +.IR Jpg , +.IR gif , +.IR png , +.IR ppm , +.IR bmp , +and +.IR yuv . +read files in the corresponding formats and, by default, display +them in the current window; options cause them instead to convert the images +to Plan 9 image format and write them to standard output. +.IR Togif , +.IR Toppm , +and +.I topng +read Plan 9 images files, convert them to GIF, PPM, or PNG, and write them to standard output. +.PP +The default behavior of +.IR jpg , +.IR gif , +and +.IR ppm +is to display the +.IR file , +or standard input if no file is named. +Once a file is displayed, typing a character causes the program to display the next image. +Typing a +.BR q , +DEL, or control-D exits the program. +For a more user-friendly interface, use +.IR page (1), +which invokes these programs to convert the images to standard format, +displays them, and offers scrolling, panning, and menu-driven navigation among the files. +.PP +These programs share many options: +.TP +.B -e +Disable Floyd-Steinberg error diffusion, which is used to improve the appearance +of images on color-mapped displays, typically with 8 bits per pixel. +Primarily useful for debugging; if the display has true RGB color, the image +will be displayed in full glory. +.TP +.B -k +Convert and display the image as a black and white (really grey-scale) image. +.TP +.B -v +Convert the image to an RGBV color-mapped image, even if the +display has true RGB color. +.TP +.B -d +Suppress display of the image; this is set automatically by +any of the following options: +.TP +.B -c +Convert the image to a Plan 9 representation, as defined by +.IR image (7), +and write it to standard output. +.TP +.B -9 +Like +.BR -c , +but produce an uncompressed image. +This saves processing time, particularly when the output is +being piped to another program such as +.IR page (1), +since it avoids compression and decompression. +.TP +.B -t +Convert the image, if it is in color, to a true color RGB image. +.TP +.B -3 +Like +.BR -t , +but force the image to RGB even if it is originally grey-scale. +.PD +.PP +.I Jpg +has two extra options used to process the output of the LML +video card: +.TP +.B -f +Merge two adjacent images, which represent the two fields of a video picture, +into a single image. +.TP +.B -F +The input is a motion JPEG file, with multiple images representing frames of the movie. Sets +.BR -f . +.PD +.PP +The +.IR togif +and +.IR toppm +programs go the other way: they convert from Plan 9 images to GIF and PPM, +and have no display capability. +Both accept an option +.B -c +to set the comment field of the resulting file. +If there is only one input picture, +.I togif +converts the image to GIF format. +If there are many +.IR files , +though, it will assemble them into an animated GIF file. +The options control this process: +.TP +.BI -l loopcount +By default, the animation will loop forever; +.I loopcount +specifies how many times to loop. +A value of zero means loop forever and a negative value means +to stop after playing the sequence once. +.TP +.BI -d msec +By default, the images are displayed as fast as they can be rendered. +This option specifies the time, in milliseconds, to pause while +displaying the next named +.IR file . +.PP +.I Gif +translates files that contain a `transparency' index by attaching +an alpha channel to the converted image. +.PP +.I Ico +displays a Windows icon (.ico) file. If no file is +specified, +.I ico +reads from standard input. +Icon files +contain sets of icons represeted by an image and a mask. +Clicking the right button pops up a menu that lets you +write any icon's image as a Plan 9 image (\fIwidth\fBx\fIheight\fB.image), +write any icon's mask as a Plan 9 image (\fIwidth\fBx\fIheight\fB.mask), +or exit. Selecting one of the write menu items yields a sight cursor. +Move the sight over the icon and right click again to write. +.PP +.I Toico +takes a list of Plan 9 image files (or standard input) and creates +a single icon file. The masks in the icon file will be the white +space in the image. The icon file is written to standard output. +.SH SOURCE +.B /usr/local/plan9/src/cmd/jpg +.SH "SEE ALSO" +.IR page (1), +.IR image (7). +.SH BUGS +Writing an animated GIF using +.I togif +is a clumsy undertaking.
diff --git a/man/man1/kill.1 b/man/man1/kill.1 new file mode 100644 index 0000000..c7d5ff9 --- /dev/null +++ b/man/man1/kill.1
@@ -0,0 +1,69 @@ +.TH KILL 1 +.SH NAME +kill, slay, start, stop \- print commands to manipulate processes +.SH SYNOPSIS +.B kill +.I name ... +.PP +.B slay +.I name ... +.PP +.B start +.I name ... +.PP +.B stop +.I name ... +.PP +.B broke +[ +.I user +] +.SH DESCRIPTION +.I Kill +prints commands that will cause all processes with +.I name +and owned by the current user to be terminated. +Each command is commented with an output line from +.IR ps (1) +describing the process that would be killed. +Use the +.B send +command of +.IR 9term (1), +or pipe the output of +.I kill +into +.IR rc (1) +or +.IR sh (1) +to execute the commands. +.PP +.I Kill +suggests sending a Unix +.B TERM +signal to the process; +sending a +.B KILL +signal is a surer, if heavy handed, kill, +but is necessary if the offending process is +ignoring signals. +The +.I slay +command prints commands to do this. +.PP +.I Stop +prints commands to pause execution of processes +by sending them the +.B STOP +signal. +.PP +.I Start +prints commands to restart stopped processes by sending them +the +.B CONT +signal. +.SH SOURCE +.B /usr/local/plan9/bin +.SH "SEE ALSO" +.IR ps (1), +.IR notify (3)
diff --git a/man/man1/label.1 b/man/man1/label.1 new file mode 100644 index 0000000..0caf8d5 --- /dev/null +++ b/man/man1/label.1
@@ -0,0 +1,71 @@ +.TH LABEL 1 +.SH NAME +label, awd \- set window label +.SH SYNOPSIS +.B label +.I string +.br +.B awd +.SH DESCRIPTION +.I Label +sets the label of the current +.I win +(see +.IR acme (1)) +or X terminal window +.RI ( e.g., +.IR 9term (1) +or +.IR xterm (1)) +by echoing a special control sequence to standard output. +.PP +.I Acme +and +.I 9term +windows assume the label is a directory name. +When unrooted file names are plumbed in the window, +they are evaluated relative to the directory named in the label. +.SH EXAMPLE +One can use the following +.IR sh (1) +function to keep the label up-to-date in response to +.I cd +commands: +.IP +.EX +_cd () { + \ecd "$@" && + case $- in + *i*) + awd + esac +} +alias cd=_cd +cd . +.EE +.PP +.IR Rc (1) +installs a similar +.B fn +.B cd +at startup if there is not already a function named +.BR cd : +.IP +.EX +fn cd { + builtin cd $1 && flag i && awd +} +.EE +.SH SOURCE +.B /usr/local/plan9/bin/label +.br +.B /usr/local/plan9/bin/awd +.SH BUGS +.I Awd +is also documented in +.IR acme (1). +.PP +.I Awd +does not append the +.BI - label +suffix that it does on Plan 9.
diff --git a/man/man1/lex.1 b/man/man1/lex.1 new file mode 100644 index 0000000..7021e8d --- /dev/null +++ b/man/man1/lex.1
@@ -0,0 +1,81 @@ +.TH LEX 1 +.SH NAME +lex \- generator of lexical analysis programs +.SH SYNOPSIS +.B lex +[ +.B -tvn9 +] +[ +.I file ... +] +.SH DESCRIPTION +.I Lex +generates programs to be used in simple lexical analysis of text. +The input +.I files +(standard input default) +contain regular expressions +to be searched for and actions written in C to be executed when +expressions are found. +.PP +A C source program, +.B lex.yy.c +is generated. +This program, when run, copies unrecognized portions of +the input to the output, +and executes the associated +C action for each regular expression that is recognized. +.PP +The options have the following meanings. +.TP +.B -t +Place the result on the standard output instead of in file +.BR lex.yy.c . +.TP +.B -v +Print a one-line summary of statistics of the generated analyzer. +.TP +.B -n +Opposite of +.BR -v ; +.B -n +is default. +.TP +.B -9 +Adds code to be able to compile through the native C compilers. +.SH EXAMPLES +This program converts upper case to lower, +removes blanks at the end of lines, +and replaces multiple blanks by single blanks. +.PP +.EX +%% +[A-Z] putchar(yytext[0]+\'a\'-\'A\'); +[ ]+$ +[ ]+ putchar(\' \'); +.EE +.SH FILES +.TF /sys/lib/lex/ncform +.TP +.B lex.yy.c +output +.TP +.B /sys/lib/lex/ncform +template +.SH "SEE ALSO" +.IR yacc (1), +.IR sed (1) +.br +M. E. Lesk and E. Schmidt, +`LEX\(emLexical Analyzer Generator', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.SH SOURCE +.B /usr/local/plan9/src/cmd/lex +.SH BUGS +Cannot handle +.SM UTF. +.br +The asteroid to kill this dinosaur is still in orbit.
diff --git a/man/man1/look.1 b/man/man1/look.1 new file mode 100644 index 0000000..e06e842 --- /dev/null +++ b/man/man1/look.1
@@ -0,0 +1,86 @@ +.TH LOOK 1 +.SH NAME +look \- find lines in a sorted list +.SH SYNOPSIS +.B look +[ +.BI -dfnixt c +] +[ +.I string +] +[ +.I file +] +.SH DESCRIPTION +.I Look +consults a sorted +.I file +and prints all lines that begin with +.IR string . +It uses binary search. +.PP +The following options are recognized. +Options +.B dfnt +affect comparisons as in +.IR sort (1). +.TP +.B -i +Interactive. +There is no +.I string +argument; instead +.I look +takes lines from the standard input as strings to be looked up. +.TP +.B -x +Exact. +Print only lines of the file whose key matches +.I string +exactly. +.TP +.B -d +`Directory' order: +only letters, digits, +tabs and blanks participate in comparisons. +.TP +.B -f +Fold. +Upper case letters compare equal to lower case. +.TP +.B -n +Numeric comparison with initial string of digits, optional minus sign, +and optional decimal point. +.TP +.BR -t [ \f2c\f1 ] +Character +.I c +terminates the sort key in the +.IR file . +By default, tab terminates the key. If +.I c +is missing the entire line comprises the key. +.PP +If no +.I file +is specified, +.B /lib/words +is assumed, with collating sequence +.BR df . +.SH FILES +.B /lib/words +.SH SOURCE +.B /usr/local/plan9/src/cmd/look.c +.SH "SEE ALSO" +.IR sort (1), +.IR grep (1) +.SH DIAGNOSTICS +The exit status is +.B \&"not found" +if no match is found, and +.B \&"no dictionary" +if +.I file +or the default dictionary cannot be opened. +
diff --git a/man/man1/ls.1 b/man/man1/ls.1 index 35981ab..4cea25b 100644 --- a/man/man1/ls.1 +++ b/man/man1/ls.1
@@ -10,7 +10,7 @@ .PP .B lc [ -.B -dlmnqrstuFQ +.B -dlmnpqrstuFQ ] .I name ... .SH DESCRIPTION @@ -60,7 +60,7 @@ List the .I qid (see -.IR stat (2)) +.IR stat (3)) of each file; the printed fields are in the order path, version, and type. .TP @@ -157,6 +157,6 @@ .br .B /usr/local/plan9/bin/lc .SH SEE ALSO -.IR stat (2) +.IR stat (3) .IR mc (1)
diff --git a/man/man1/man.1 b/man/man1/man.1 new file mode 100644 index 0000000..7b86584 --- /dev/null +++ b/man/man1/man.1
@@ -0,0 +1,105 @@ +.TH MAN 1 +.SH NAME +man, lookman \- print or find pages of this manual +.SH SYNOPSIS +.B man +[ +.I option ... +] +[ +.I section ... +] +.I title ... +.PP +.B lookman +.I key ... +.PP +.B sig +.I function ... +.SH DESCRIPTION +.I Man +locates and prints pages of this manual named +.I title +in the specified +.IR sections . +.I Title +is given in lower case. +Each +.I section +is a number; +pages marked (2S), for example, +belong to chapter 2. +If no +.I section +is specified, pages +in all sections are printed. +Any name from the +.SM NAME +section at the top of the page will serve as a +.IR title . +.PP +The options are: +.TP +.B -p +Run +.IR proof (1) +on the specified man pages. +.TP +.B -P +Run +.IR page (1) +on the specified man pages. +.TP +.B -t +Run +.I troff +and send its output +to standard output. +.TP +.B -n +(Default) +Print the pages on the standard output using +.IR nroff . +.PP +.B Lookman +prints the names of all manual sections that contain +all of the +.I key +words given on the command line. +.PP +.B Sig +prints the signature (i.e. C definition) of the +.IR function 's +given on the command line. +.SH FILES +.TF /sys/lib/man/lookman/index +.TP +.B /sys/man/?/* +.I troff +source for manual; this page is +.B /sys/man/1/man +.TP +.B /sys/man/?/INDEX +indices searched to find pages corresponding to titles +.TP +.B /sys/lib/man/secindex +command to make an index for a given section +.TP +.B /sys/lib/man/lookman/index +index for +.I lookman +.SH SOURCE +.B /usr/local/plan9/bin/9man +.br +.B /usr/local/plan9/bin/lookman +.SH "SEE ALSO" +.IR proof (1) +.SH BUGS +The manual was intended to be typeset; some detail is sacrificed on text terminals. +.br +There is no automatic mechanism to keep the indices up to date. +.br +Except for special cases, it doesn't recognize things that should be run through +.I tbl +and/or +.IR eqn .
diff --git a/man/man1/map.1 b/man/man1/map.1 new file mode 100644 index 0000000..cc73075 --- /dev/null +++ b/man/man1/map.1
@@ -0,0 +1,675 @@ +.TH MAP 1 +.SH NAME +map, mapdemo \- draw maps on various projections +.SH SYNOPSIS +.B map +.I projection +[ +.I option ... +] +.PP +.B mapdemo +.PP +.SH DESCRIPTION +.I Map +prepares on the standard output a +map suitable for display by any +plotting filter described in +.IR plot (1). +A menu of projections is produced in response to an unknown +.IR projection . +.I Mapdemo +is a short course in mapping. +.PP +The default data for +.I map +are world shorelines. +Option +.B -f +accesses more detailed data +classified by feature. +.TP +.BR -f " [ \fIfeature\fR ... ]" +Features are ranked 1 (default) to 4 from major to minor. +Higher-numbered ranks include all lower-numbered ones. +Features are +.RS +.TF country[1-3] +.TP +.BR shore [ 1 - 4 ] +seacoasts, lakes, and islands; option +.B -f +always shows +.B shore1 +.TP +.BR ilake [ 1 - 2 ] +intermittent lakes +.TP +.BR river [ 1 - 4 ] +rivers +.TP +.BR iriver [ 1 - 3 ] +intermittent rivers +.TP +.BR canal [ 1 - 3 ] +.BR 3 =irrigation +canals +.TP +.BR glacier +.TP +.BR iceshelf [ 12 ] +.TP +.BR reef +.TP +.BR saltpan [ 12 ] +.TP +.BR country [ 1 - 3 ] +.BR 2 =disputed +boundaries, +.BR 3 =indefinite +boundaries +.TP +.BR state +states and provinces (US and Canada only) +.PD +.RE +.PP +In other options +coordinates are in degrees, with north latitude +and west longitude counted as positive. +.TP 0 +.BI -l " S N E W" +Set the southern and northern latitude +and the eastern and western longitude limits. +Missing arguments are filled out from the list +\-90, 90, \-180, 180, +or lesser limits suitable to the +projection at hand. +.TP +.BI -k " S N E W +Set the scale as if for a map with limits +.B -l +.I "S N E W"\f1. +Do not consider any +.B -l +or +.B -w +option in setting scale. +.TP +.BI -o " lat lon rot" +Orient the map in a nonstandard position. +Imagine a transparent gridded sphere around the globe. +Turn the overlay about the North Pole +so that the Prime Meridian (longitude 0) +of the overlay coincides with meridian +.I lon +on the globe. +Then tilt the North Pole of the +overlay along its Prime Meridian to latitude +.I lat +on the globe. +Finally again turn the +overlay about its `North Pole' so +that its Prime Meridian coincides with the previous position +of meridian +.IR rot . +Project the map in +the standard form appropriate to the overlay, but presenting +information from the underlying globe. +Missing arguments are filled out from the list +90, 0, 0. +In the absence of +.BR - o , +the orientation is 90, 0, +.IR m , +where +.I m +is the middle of the longitude range. +.TP +.BI -w " S N E W" +Window the map by the specified latitudes +and longitudes in the tilted, rotated coordinate system. +Missing arguments are filled out from the list \-90, 90, \-180, 180. +(It is wise to give an encompassing +.B -l +option with +.BR -w . +Otherwise for small windows computing time +varies inversely with area!) +.TP +.BI -d " n" +For speed, plot only every +.IR n th +point. +.TP +.B -r +Reverse left and right +(good for star charts and inside-out views). +.ns +.TP +.B -v +Verso. +Switch to a normally suppressed sheet of the map, such as the +back side of the earth in orthographic projection. +.TP +.B -s1 +.br +.ns +.TP +.B -s2 +Superpose; outputs for a +.B -s1 +map (no closing) and a +.B -s2 +map (no opening) may be concatenated. +.TP +.BI -g " dlat dlon res" +Grid spacings are +.IR dlat , +.IR dlon . +Zero spacing means no grid. +Missing +.I dlat +is taken to be zero. +Missing +.I dlon +is taken the same as +.IR dlat . +Grid lines are drawn to a resolution of +.I res +(2° or less by default). +In the absence of +.BR - g , +grid spacing is 10°. +.TP +.BI -p " lat lon extent" +Position the point +.I lat, lon +at the center of the plotting area. +Scale the map so that the height (and width) of the +nominal plotting area is +.I extent +times the size of one degree of latitude +at the center. +By default maps are scaled and positioned +to fit within the plotting area. +An +.I extent +overrides option +.BR -k . +.TP +.BI -c " x y rot" +After all other positioning and scaling operations +have been performed, rotate the image +.I rot +degrees counterclockwise about the center +and move the center to position +.IR x , +.IR y , +where the nominal plotting area is +.RI \-1≤ x ≤1, +.RI \-1≤ y ≤1. +Missing arguments are taken to be 0. +.BR -x +Allow the map to extend outside the nominal plotting area. +.TP +.BR -m " [ \fIfile\fP ... ]" +Use +map data from named files. +If no files are named, omit map data. +Names that do not exist as pathnames are looked up in +a standard directory, which contains, in addition to the +data for +.BR -f , +.RS +.LP +.TF counties +.TP +.B world +World Data Bank I (default) +.TP +.B states +US map from Census Bureau +.TP +.B counties +US map from Census Bureau +.PD +.RE +.IP +The environment variables +.B MAP +and +.B MAPDIR +change the default +map and default directory. +.TP +.BI -b " \fR[\fPlat0 lon0 lat1 lon1\fR... ]" +Suppress the drawing of the normal boundary +(defined by options +.BR -l +and +.BR -w ). +Coordinates, if present, define the vertices of a +polygon to which the map is clipped. +If only two vertices are given, they are taken to be the +diagonal of a rectangle. +To draw the polygon, give its vertices as a +.B -u +track. +.TP +.BI -t " file ..." +The +.I files +contain lists of points, +given as latitude-longitude pairs in degrees. +If the first file is named +.LR - , +the standard input is taken instead. +The points of each list are plotted as connected `tracks'. +.IP +Points in a track file may be followed by label strings. +A label breaks the track. +A label may be prefixed by +\fL"\fR, +.LR : , +or +.L ! +and is terminated by a newline. +An unprefixed string or a string prefixed with +.L +" +is displayed at the designated point. +The first word of a +.L : +or +.L ! +string names a special symbol (see option +.BR -y ). +An optional numerical second word is a scale factor +for the size of the symbol, 1 by default. +A +.L : +symbol is aligned with its top to the north; a +.L ! +symbol is aligned vertically on the page. +.TP +.BI -u " file ..." +Same as +.BR -t , +except the tracks are +unbroken lines. +.RB ( -t +tracks appear as dot-dashed lines if the plotting filter supports them.) +.TP +.BI -y " file +The +.I file +contains +.IR plot (7)-style +data for +.L : +or +.L ! +labels in +.B -t +or +.B -u +files. +Each symbol is defined by a comment +.BI : name +then a sequence of +.L m +and +.L v +commands. +Coordinates (0,0) fall on the plotting point. +Default scaling is as if the nominal plotting range were +.LR "ra -1 -1 1 1" ; +.L ra +commands in +.I file +change the scaling. +.SS Projections +Equatorial projections centered on the Prime Meridian +(longitude 0). +Parallels are straight horizontal lines. +.PP +.PD 0 +.TP 1.5i +.B mercator +equally spaced straight meridians, conformal, +straight compass courses +.TP +.B sinusoidal +equally spaced parallels, +equal-area, same as +.LR "bonne 0" . +.TP +.BI cylequalarea " lat0" +equally spaced straight meridians, equal-area, +true scale on +.I lat0 +.TP +.B cylindrical +central projection on tangent cylinder +.TP +.BI rectangular " lat0" +equally spaced parallels, equally spaced straight meridians, true scale on +.I lat0 +.TP +.BI gall " lat0" +parallels spaced stereographically on prime meridian, equally spaced straight +meridians, true scale on +.I lat0 +.TP +.B mollweide +(homalographic) equal-area, hemisphere is a circle +.br +.B gilbert() +sphere conformally mapped on hemisphere and viewed orthographically +.TP +.B gilbert +globe mapped conformally on hemisphere, viewed orthographically +.PD +.PP +Azimuthal projections centered on the North Pole. +Parallels are concentric circles. +Meridians are equally spaced radial lines. +.PP +.PD 0 +.TP 1.5i +.B azequidistant +equally spaced parallels, +true distances from pole +.TP +.B azequalarea +equal-area +.TP +.B gnomonic +central projection on tangent plane, +straight great circles +.TP +.BI perspective " dist" +viewed along earth's axis +.I dist +earth radii from center of earth +.TP +.B orthographic +viewed from infinity +.TP +.B stereographic +conformal, projected from opposite pole +.TP +.B laue +.IR radius " = tan(2\(mu" colatitude ), +used in X-ray crystallography +.TP +.BI fisheye " n" +stereographic seen from just inside medium with refractive index +.I n +.TP +.BI newyorker " r" +.IR radius " = log(" colatitude / r ): +.I New Yorker +map from viewing pedestal of radius +.I r +degrees +.PD +.PP +Polar conic projections symmetric about the Prime Meridian. +Parallels are segments of concentric circles. +Except in the Bonne projection, +meridians are equally spaced radial +lines orthogonal to the parallels. +.PP +.PD 0 +.TP 1.5i +.BI conic " lat0" +central projection on cone tangent at +.I lat0 +.TP +.BI simpleconic " lat0 lat1" +equally spaced parallels, true scale on +.I lat0 +and +.I lat1 +.TP +.BI lambert " lat0 lat1" +conformal, true scale on +.I lat0 +and +.I lat1 +.TP +.BI albers " lat0 lat1" +equal-area, true scale on +.I lat0 +and +.I lat1 +.TP +.BI bonne " lat0" +equally spaced parallels, equal-area, +parallel +.I lat0 +developed from tangent cone +.PD +.PP +Projections with bilateral symmetry about +the Prime Meridian +and the equator. +.PP +.PD 0 +.TP 1.5i +.B polyconic +parallels developed from tangent cones, +equally spaced along Prime Meridian +.TP +.B aitoff +equal-area projection of globe onto 2-to-1 +ellipse, based on +.I azequalarea +.TP +.B lagrange +conformal, maps whole sphere into a circle +.TP +.BI bicentric " lon0" +points plotted at true azimuth from two +centers on the equator at longitudes +.IR ±lon0 , +great circles are straight lines +(a stretched +.IR gnomonic +) +.TP +.BI elliptic " lon0" +points plotted at true distance from +two centers on the equator at longitudes +.I ±lon0 +.TP +.B globular +hemisphere is circle, +circular arc meridians equally spaced on equator, +circular arc parallels equally spaced on 0- and 90-degree meridians +.TP +.B vandergrinten +sphere is circle, +meridians as in +.IR globular , +circular arc parallels resemble +.I mercator +.PD +.PP +Doubly periodic conformal projections. +.PP +.TP 1.5i +.B guyou +W and E hemispheres are square +.PD 0 +.TP +.B square +world is square with Poles +at diagonally opposite corners +.TP +.B tetra +map on tetrahedron with edge +tangent to Prime Meridian at S Pole, +unfolded into equilateral triangle +.TP +.B hex +world is hexagon centered +on N Pole, N and S hemispheres are equilateral +triangles +.PD +.PP +Miscellaneous projections. +.PP +.PD 0 +.TP 1.5i +.BI harrison " dist angle" +oblique perspective from above the North Pole, +.I dist +earth radii from center of earth, looking +along the Date Line +.I angle +degrees off vertical +.TP +.BI trapezoidal " lat0 lat1" +equally spaced parallels, +straight meridians equally spaced along parallels, +true scale at +.I lat0 +and +.I lat1 +on Prime Meridian +.PD +.br +.B lune(lat,angle) +conformal, polar cap above latitude +.I lat +maps to convex lune with given +.I angle +at 90\(deE and 90\(deW +.PP +Retroazimuthal projections. +At every point the angle between vertical and a straight line to +`Mecca', latitude +.I lat0 +on the prime meridian, +is the true bearing of Mecca. +.PP +.PD 0 +.TP 1.5i +.BI mecca " lat0" +equally spaced vertical meridians +.TP +.BI homing " lat0" +distances to Mecca are true +.PD +.PP +Maps based on the spheroid. +Of geodetic quality, these projections do not make sense +for tilted orientations. +For descriptions, see corresponding maps above. +.PP +.PD 0 +.TP 1.5i +.B sp_mercator +.TP +.BI sp_albers " lat0 lat1" +.SH EXAMPLES +.TP +.L +map perspective 1.025 -o 40.75 74 +A view looking down on New York from 100 miles +(0.025 of the 4000-mile earth radius) up. +The job can be done faster by limiting the map so as not to `plot' +the invisible part of the world: +.LR "map perspective 1.025 -o 40.75 74 -l 20 60 30 100". +A circular border can be forced by adding option +.LR "-w 77.33" . +(Latitude 77.33° falls just inside a polar cap of +opening angle arccos(1/1.025) = 12.6804°.) +.TP +.L +map mercator -o 49.25 -106 180 +An `equatorial' map of the earth +centered on New York. +The pole of the map is placed 90\(de away (40.75+49.25=90) +on the +other side of the earth. +A 180° twist around the pole of the map arranges that the +`Prime Meridian' of the map runs from the pole of the +map over the North Pole to New York +instead of down the back side of the earth. +The same effect can be had from +.L +map mercator -o 130.75 74 +.TP +.L +map albers 28 45 -l 20 50 60 130 -m states +A customary curved-latitude map of the United States. +.TP +.L +map harrison 2 30 -l -90 90 120 240 -o 90 0 0 +A fan view covering 60° on either +side of the Date Line, as seen from one earth radius +above the North Pole gazing at the +earth's limb, which is 30° off vertical. +The +.B -o +option overrides the default +.BR "-o 90 0 180" , +which would rotate +the scene to behind the observer. +.SH FILES +.TF /lib/map/[1-4]?? +.TP +.B /lib/map/[1-4]?? +World Data Bank II, for +.B -f +.TP +.B /lib/map/* +maps for +.B -m +.TP +.B /lib/map/*.x +map indexes +.TP +.B /bin/aux/mapd +Map driver program +.SH SOURCE +.B /usr/local/plan9/src/cmd/map +.SH "SEE ALSO" +.IR map (7), +.IR plot (1) +.SH DIAGNOSTICS +`Map seems to be empty'\(ema coarse survey found +zero extent within the +.B -l +and +.BR -w +bounds; for maps of limited extent +the grid resolution, +.IR res , +or the limits may have to be refined. +.SH BUGS +Windows (option +.BR -w ) +cannot cross the Date Line. +No borders appear along edges arising from +visibility limits. +Segments that cross a border are dropped, not clipped. +Excessively large scale or +.B -d +setting may cause long line segments to be dropped. +.I Map +tries to draw grid lines dotted and +.B -t +tracks dot-dashed. +As very few plotting filters properly support +curved textured lines, these lines are likely to +appear solid. +The west-longitude-positive convention +betrays Yankee chauvinism. +.I Gilbert +should be a map from sphere to sphere, independent of +the mapping from sphere to plane.
diff --git a/man/man1/mc.1 b/man/man1/mc.1 index 1618bef..ac53520 100644 --- a/man/man1/mc.1 +++ b/man/man1/mc.1
@@ -18,7 +18,10 @@ .I N print positions. If run in a -.IR rio (1) +.IR 9term (1), +.IR xterm (1), +or +.IR acme (1) window, the default .I N is the number of blanks that will fit across the window; @@ -31,9 +34,12 @@ .L : is printed separately. .SH SOURCE -.B /usr/local/plan9/src/cmd/mc.c +.B /usr/local/plan9/src/cmd/draw/mc.c .SH "SEE ALSO" -.IR rio (1), +.IR 9term (1), +.IR acme (1), +.IR acme (4), +.IR xterm (1), .IR pr (1), .I lc in
diff --git a/man/man1/mk.1 b/man/man1/mk.1 new file mode 100644 index 0000000..59b1d0e --- /dev/null +++ b/man/man1/mk.1
@@ -0,0 +1,682 @@ +.TH MK 1 +.de EX +.nf +.ft B +.. +.de EE +.fi +.ft R +.. +.de LR +.if t .BR \\$1 \\$2 +.if n .RB ` \\$1 '\\$2 +.. +.de L +.nh +.if t .B \\$1 +.if n .RB ` \\$1 ' +.. +.SH NAME +mk, membername \- maintain (make) related files +.SH SYNOPSIS +.B mk +[ +.B -f +.I mkfile +] ... +[ +.I option ... +] +[ +.I target ... +] +.PP +.B membername +.IR lib ( object ) +\&... +.SH DESCRIPTION +.I Mk +uses the dependency rules specified in +.I mkfile +to control the update (usually by compilation) of +.I targets +(usually files) +from the source files upon which they depend. +The +.I mkfile +(default +.LR mkfile ) +contains a +.I rule +for each target that identifies the files and other +targets upon which it depends and an +.IR sh (1) +script, a +.IR recipe , +to update the target. +The script is run if the target does not exist +or if it is older than any of the files it depends on. +.I Mkfile +may also contain +.I meta-rules +that define actions for updating implicit targets. +If no +.I target +is specified, the target of the first rule (not meta-rule) in +.I mkfile +is updated. +.PP +The environment variable +.B $NPROC +determines how many targets may be updated simultaneously; +Some operating systems, e.g., Plan 9, set +.B $NPROC +automatically to the number of CPUs on the current machine. +.PP +Options are: +.TP \w'\fL-d[egp]\ 'u +.B -a +Assume all targets to be out of date. +Thus, everything is updated. +.PD 0 +.TP +.BR -d [ egp ] +Produce debugging output +.RB ( p +is for parsing, +.B g +for graph building, +.B e +for execution). +.TP +.B -e +Explain why each target is made. +.TP +.B -i +Force any missing intermediate targets to be made. +.TP +.B -k +Do as much work as possible in the face of errors. +.TP +.B -n +Print, but do not execute, the commands +needed to update the targets. +.TP +.B -s +Make the command line arguments sequentially rather than in parallel. +.TP +.B -t +Touch (update the modified date of) file targets, without +executing any recipes. +.TP +.BI -w target1 , target2,... +Pretend the modify time for each +.I target +is the current time; useful in conjunction with +.B -n +to learn what updates would be triggered by +modifying the +.IR targets . +.PD +.SS The \fLmkfile\fP +A +.I mkfile +consists of +.I assignments +(described under `Environment') and +.IR rules . +A rule contains +.I targets +and a +.IR tail . +A target is a literal string +and is normally a file name. +The tail contains zero or more +.I prerequisites +and an optional +.IR recipe , +which is an +.B shell +script. +Each line of the recipe must begin with white space. +A rule takes the form +.IP +.EX +target: prereq1 prereq2 + \f2recipe using\fP prereq1, prereq2 \f2to build\fP target +.EE +.PP +When the recipe is executed, +the first character on every line is elided. +.PP +After the colon on the target line, a rule may specify +.IR attributes , +described below. +.PP +A +.I meta-rule +has a target of the form +.IB A % B +where +.I A +and +.I B +are (possibly empty) strings. +A meta-rule acts as a rule for any potential target whose +name matches +.IB A % B +with +.B % +replaced by an arbitrary string, called the +.IR stem . +In interpreting a meta-rule, +the stem is substituted for all occurrences of +.B % +in the prerequisite names. +In the recipe of a meta-rule, the environment variable +.B $stem +contains the string matched by the +.BR % . +For example, a meta-rule to compile a C program using +.IR 9c (1) +might be: +.IP +.EX +%: %.c + 9c -c $stem.c + 9l -o $stem $stem.o +.EE +.PP +Meta-rules may contain an ampersand +.B & +rather than a percent sign +.BR % . +A +.B % +matches a maximal length string of any characters; +an +.B & +matches a maximal length string of any characters except period +or slash. +.PP +The text of the +.I mkfile +is processed as follows. +Lines beginning with +.B < +followed by a file name are replaced by the contents of the named +file. +Lines beginning with +.B "<|" +followed by a file name are replaced by the output +of the execution of the named +file. +Blank lines and comments, which run from unquoted +.B # +characters to the following newline, are deleted. +The character sequence backslash-newline is deleted, +so long lines in +.I mkfile +may be folded. +Non-recipe lines are processed by substituting for +.BI `{ command } +the output of the +.I command +when run by +.IR sh . +References to variables are replaced by the variables' values. +Special characters may be quoted using single quotes +.BR \&'' +as in +.IR sh (1). +.PP +Assignments and rules are distinguished by +the first unquoted occurrence of +.B : +(rule) +or +.B = +(assignment). +.PP +A later rule may modify or override an existing rule under the +following conditions: +.TP +\- +If the targets of the rules exactly match and one rule +contains only a prerequisite clause and no recipe, the +clause is added to the prerequisites of the other rule. +If either or both targets are virtual, the recipe is +always executed. +.TP +\- +If the targets of the rules match exactly and the +prerequisites do not match and both rules +contain recipes, +.I mk +reports an ``ambiguous recipe'' error. +.TP +\- +If the target and prerequisites of both rules match exactly, +the second rule overrides the first. +.SS Environment +Rules may make use of +shell +environment variables. +A legal reference of the form +.B $OBJ +or +.B ${name} +is expanded as in +.IR sh (1). +A reference of the form +.BI ${name: A % B = C\fL%\fID\fL}\fR, +where +.I A, B, C, D +are (possibly empty) strings, +has the value formed by expanding +.B $name +and substituting +.I C +for +.I A +and +.I D +for +.I B +in each word in +.B $name +that matches pattern +.IB A % B\f1. +.PP +Variables can be set by +assignments of the form +.I + var\fL=\fR[\fIattr\fL=\fR]\fIvalue\fR +.br +Blanks in the +.I value +break it into words. +Such variables are exported +to the environment of +recipes as they are executed, unless +.BR U , +the only legal attribute +.IR attr , +is present. +The initial value of a variable is +taken from (in increasing order of precedence) +the default values below, +.I mk's +environment, the +.IR mkfiles , +and any command line assignment as an argument to +.IR mk . +A variable assignment argument overrides the first (but not any subsequent) +assignment to that variable. +The variable +.B MKFLAGS +contains all the option arguments (arguments starting with +.L - +or containing +.LR = ) +and +.B MKARGS +contains all the targets in the call to +.IR mk . +.PP +Dynamic information may be included in the mkfile by using a line of the form +.IP +\fR<|\fIcommand\fR \fIargs\fR +.LP +This runs the command +.I command +with the given arguments +.I args +and pipes its standard output to +.I mk +to be included as part of the mkfile. For instance, the Inferno kernels +use this technique +to run a shell command with an awk script and a configuration +file as arguments in order for +the +.I awk +script to process the file and output a set of variables and their values. +.SS Execution +.PP +During execution, +.I mk +determines which targets must be updated, and in what order, +to build the +.I names +specified on the command line. +It then runs the associated recipes. +.PP +A target is considered up to date if it has no prerequisites or +if all its prerequisites are up to date and it is newer +than all its prerequisites. +Once the recipe for a target has executed, the target is +considered up to date. +.PP +The date stamp +used to determine if a target is up to date is computed +differently for different types of targets. +If a target is +.I virtual +(the target of a rule with the +.B V +attribute), +its date stamp is initially zero; when the target is +updated the date stamp is set to +the most recent date stamp of its prerequisites. +Otherwise, if a target does not exist as a file, +its date stamp is set to the most recent date stamp of its prerequisites, +or zero if it has no prerequisites. +Otherwise, the target is the name of a file and +the target's date stamp is always that file's modification date. +The date stamp is computed when the target is needed in +the execution of a rule; it is not a static value. +.PP +Nonexistent targets that have prerequisites +and are themselves prerequisites are treated specially. +Such a target +.I t +is given the date stamp of its most recent prerequisite +and if this causes all the targets which have +.I t +as a prerequisite to be up to date, +.I t +is considered up to date. +Otherwise, +.I t +is made in the normal fashion. +The +.B -i +flag overrides this special treatment. +.PP +Files may be made in any order that respects +the preceding restrictions. +.PP +A recipe is executed by supplying the recipe as standard input to +the command +.BR /bin/sh . +(Note that unlike +.IR make , +.I mk +feeds the entire recipe to the shell rather than running each line +of the recipe separately.) +The environment is augmented by the following variables: +.TP 14 +.B $alltarget +all the targets of this rule. +.TP +.B $newprereq +the prerequisites that caused this rule to execute. +.TP +.B $newmember +the prerequisites that are members of an aggregate +that caused this rule to execute. +When the prerequisites of a rule are members of an +aggregate, +.B $newprereq +contains the name of the aggregate and out of date +members, while +.B $newmember +contains only the name of the members. +.TP +.B $nproc +the process slot for this recipe. +It satisfies +.RB 0≤ $nproc < $NPROC . +.TP +.B $pid +the process id for the +.I mk +executing the recipe. +.TP +.B $prereq +all the prerequisites for this rule. +.TP +.B $stem +if this is a meta-rule, +.B $stem +is the string that matched +.B % +or +.BR & . +Otherwise, it is empty. +For regular expression meta-rules (see below), the variables +.LR stem0 ", ...," +.L stem9 +are set to the corresponding subexpressions. +.TP +.B $target +the targets for this rule that need to be remade. +.PP +These variables are available only during the execution of a recipe, +not while evaluating the +.IR mkfile . +.PP +Unless the rule has the +.B Q +attribute, +the recipe is printed prior to execution +with recognizable environment variables expanded. +Commands returning error status +cause +.I mk +to terminate. +.PP +Recipes and backquoted +.B rc +commands in places such as assignments +execute in a copy of +.I mk's +environment; changes they make to +environment variables are not visible from +.IR mk . +.PP +Variable substitution in a rule is done when +the rule is read; variable substitution in the recipe is done +when the recipe is executed. For example: +.IP +.EX +bar=a.c +foo: $bar + $CC -o foo $bar +bar=b.c +.EE +.PP +will compile +.B b.c +into +.BR foo , +if +.B a.c +is newer than +.BR foo . +.SS Aggregates +Names of the form +.IR a ( b ) +refer to member +.I b +of the aggregate +.IR a . +Currently, the only aggregates supported are +.I 9ar +(see +.IR 9c (1)) +archives. +.PP +.I Membername +echoes just the member names of a list of aggregate names. +It is useful in recipes like: +.EX +OFILES=a.o b.o +libc.a(%):N: % +libc.a: ${OFILES:%=libc.a(%)} + 9ar rvc libc.a `membername $newprereq` +.EE +which re-archives only the new object files. +.SS Attributes +The colon separating the target from the prerequisites +may be +immediately followed by +.I attributes +and another colon. +The attributes are: +.TP +.B D +If the recipe exits with a non-null status, the target is deleted. +.TP +.B E +Continue execution if the recipe draws errors. +.TP +.B N +If there is no recipe, the target has its time updated. +.TP +.B n +The rule is a meta-rule that cannot be a target of a virtual rule. +Only files match the pattern in the target. +.TP +.B P +The characters after the +.B P +until the terminating +.B : +are taken as a program name. +It will be invoked as +.B "sh -c prog 'arg1' 'arg2'" +and should return a zero exit status +if and only if arg1 is up to date with respect to arg2. +Date stamps are still propagated in the normal way. +.TP +.B Q +The recipe is not printed prior to execution. +.TP +.B R +The rule is a meta-rule using regular expressions. +In the rule, +.B % +has no special meaning. +The target is interpreted as a regular expression as defined in +.IR regexp (7). +The prerequisites may contain references +to subexpressions in form +.BI \e n\f1, +as in the substitute command of +.IR sed (1). +.TP +.B U +The targets are considered to have been updated +even if the recipe did not do so. +.TP +.B V +The targets of this rule are marked as virtual. +They are distinct from files of the same name. +.PD +.SH EXAMPLES +A simple mkfile to compile a program: +.IP +.EX +.ta 8n +8n +8n +8n +8n +8n +8n +</$objtype/mkfile + +prog: a.$O b.$O c.$O + $LD $LDFLAGS -o $target $prereq + +%.$O: %.c + $CC $CFLAGS $stem.c +.EE +.PP +Override flag settings in the mkfile: +.IP +.EX +% mk target 'CFLAGS=-S -w' +.EE +.PP +Maintain a library: +.IP +.EX +libc.a(%.$O):N: %.$O +libc.a: libc.a(abs.$O) libc.a(access.$O) libc.a(alarm.$O) ... + ar r libc.a $newmember +.EE +.PP +String expression variables to derive names from a master list: +.IP +.EX +NAMES=alloc arc bquote builtins expand main match mk var word +OBJ=${NAMES:%=%.$O} +.EE +.PP +Regular expression meta-rules: +.IP +.EX +([^/]*)/(.*)\e.$O:R: \e1/\e2.c + cd $stem1; $CC $CFLAGS $stem2.c +.EE +.PP +A correct way to deal with +.IR yacc (1) +grammars. +The file +.B lex.c +includes the file +.B x.tab.h +rather than +.B y.tab.h +in order to reflect changes in content, not just modification time. +.IP +.EX +lex.$O: x.tab.h +x.tab.h: y.tab.h + cmp -s x.tab.h y.tab.h || cp y.tab.h x.tab.h +y.tab.c y.tab.h: gram.y + $YACC -d gram.y +.EE +.PP +The above example could also use the +.B P +attribute for the +.B x.tab.h +rule: +.IP +.EX +x.tab.h:Pcmp -s: y.tab.h + cp y.tab.h x.tab.h +.EE +.SH SEE ALSO +.IR sh (1), +.IR regexp9 (7) +.PP +A. Hume, +``Mk: a Successor to Make'' +(Tenth Edition Research Unix Manuals). +.PP +Andrew G. Hume and Bob Flandrena, +``Maintaining Files on Plan 9 with Mk''. +DOCPREFIX/doc/mk.pdf +.SH HISTORY +Andrew Hume wrote +.I mk +for Tenth Edition Research Unix. +It was later ported to Plan 9. +This software is a port of the Plan 9 version back to Unix. +.SH BUGS +Identical recipes for regular expression meta-rules only have one target. +.br +Seemingly appropriate input like +.B CFLAGS=-DHZ=60 +is parsed as an erroneous attribute; correct it by inserting +a space after the first +.LR = . +.br +The recipes printed by +.I mk +before being passed to +.I sh +for execution are sometimes erroneously expanded +for printing. Don't trust what's printed; rely +on what +.I sh +does.
diff --git a/man/man1/namespace.1 b/man/man1/namespace.1 new file mode 100644 index 0000000..45f443b --- /dev/null +++ b/man/man1/namespace.1
@@ -0,0 +1,14 @@ +.TH NAMESPACE 1 +.SH NAME +namespace \- print name space directory +.SH SYNOPSIS +.B namespace +.SH DESCRIPTION +.I Namespace +prints the directory representing the current name space. +See +.IR intro (4). +.SH SOURCE +.B /usr/local/plan9/src/cmd/namespace.c +.SH SEE ALSO +.IR getns (3)
diff --git a/man/man1/news.1 b/man/man1/news.1 new file mode 100644 index 0000000..bce5e18 --- /dev/null +++ b/man/man1/news.1
@@ -0,0 +1,63 @@ +.TH NEWS 1 +.SH NAME +news \- print news items +.SH SYNOPSIS +.B news +[ +.B -a +] +[ +.B -n +] +[ +.I item ... +] +.SH DESCRIPTION +When invoked without options, +this simple local news service +prints files that have appeared in +.BR /lib/news +since last reading, most recent first, +with each preceded by an appropriate header. +The time of reading is recorded. +The options are +.TP +.B -a +Print all items, regardless of currency. +The recorded time is not changed. +.TP +.B -n +Report the names of the current items without +printing their contents, and without changing +the recorded time. +.PP +Other arguments +select particular news items. +.PP +To post a news item, create a file in +.BR /lib/news . +.PP +You may arrange to receive news automatically by +registering your mail address in +.BR /sys/lib/subscribers . +A daemon mails recent news +to all addresses on the list. +.PP +Empty news items, and news items named +.B core +or +.B dead.letter +are ignored. +.SH FILES +.TF /sys/lib/subscribers +.TP +.B /lib/news/* +articles +.TP +.B $HOME/lib/newstime +modify time is time news was last read +.TP +.B /sys/lib/subscribers +who gets news mailed to them +.SH SOURCE +.B /usr/local/plan9/src/cmd/news.c
diff --git a/man/man1/p.1 b/man/man1/p.1 new file mode 100644 index 0000000..e98134e --- /dev/null +++ b/man/man1/p.1
@@ -0,0 +1,33 @@ +.TH P 1 +.SH NAME +p \- paginate +.SH SYNOPSIS +.B p +[ +.BI - number +] +[ +.I file ... +] +.SH DESCRIPTION +.I P +copies its standard input, or the named files if given, +to its standard output, +stopping at the end of every 22nd line, and between files, +to wait for a newline from the user. +The option sets the +.I number +of lines on a page. +.PP +While waiting for a newline, +.I p +interprets the commands: +.TP +.B ! +Pass the rest of the line to the shell as a command. +.TP +.B q +Quit. +.PP +.SH SOURCE +.B /usr/local/plan9/src/cmd/p.c
diff --git a/man/man1/page.1 b/man/man1/page.1 new file mode 100644 index 0000000..eb4fed5 --- /dev/null +++ b/man/man1/page.1
@@ -0,0 +1,56 @@ +.TH PAGE 1 +.SH NAME +img, psv \- view +FAX, +image, graphic, PostScript, PDF, and +typesetter output +files +.SH SYNOPSIS +.B page +[ +.B -abirPRvVw +] +[ +.B -p +.I ppi +] +[ +.IR file ... +] +.PP +.B img +.I file.bit +.PP +.B psv +.I file.ps +.PP +.B psv +.I file.pdf +.SH DESCRIPTION +Plan 9's +.IR page (1) +is not ported. +.PP +.I Img +is a simple image viewer for Plan 9 images +(see +.IR image (7)). +.PP +.I Psv +is a PostScript and PDF viewer. +It is a streamlined interface to +.IR gv (1). +.PP +To view troff output, use +.IR proof (1). +.SH "SEE ALSO +.IR gs (1), +.IR gv (1) +.IR jpg (1), +.IR proof (1), +.IR tex (1), +.IR troff (1) +.SH SOURCE +.B /usr/local/plan9/src/cmd/draw/img.c +.br +.B /usr/local/plan9/bin/psv
diff --git a/man/man1/pic.1 b/man/man1/pic.1 index 685de68..ae84569 100644 --- a/man/man1/pic.1 +++ b/man/man1/pic.1
@@ -331,7 +331,7 @@ for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 } .PE .SH SOURCE -.B /sys/src/cmd/pic +.B /usr/local/plan9/src/cmd/pic .SH "SEE ALSO" .IR grap (1), .IR doctype (1),
diff --git a/man/man1/plot.1 b/man/man1/plot.1 index cd1a1b8..e26dac6 100644 --- a/man/man1/plot.1 +++ b/man/man1/plot.1
@@ -9,7 +9,7 @@ .SH DESCRIPTION .I Plot interprets plotting instructions (see -.IR plot (6)) +.IR plot (7)) from the .I files or standard input, @@ -31,7 +31,7 @@ .TP .BI -c " col" Set the foreground color (see -.IR plot (6) +.IR plot (7) for color names). .TP .BI -f " fill" @@ -55,7 +55,7 @@ By default it uses a 512×512 window in the middle of the screen. .SH SOURCE -.B /sys/src/cmd/plot +.B /usr/local/plan9/src/cmd/plot .SH "SEE ALSO" .IR rio (1), -.IR plot (6) +.IR plot (7)
diff --git a/man/man1/plumb.1 b/man/man1/plumb.1 index 0cee82d..c296a1e 100644 --- a/man/man1/plumb.1 +++ b/man/man1/plumb.1
@@ -87,6 +87,6 @@ .SH SOURCE .B /usr/local/plan9/src/cmd/plumb .SH "SEE ALSO" -.IR plumb (2), +.IR plumb (3), .IR plumber (4), -.IR plumb (6) +.IR plumb (7)
diff --git a/man/man1/pr.1 b/man/man1/pr.1 new file mode 100644 index 0000000..ce8dc68 --- /dev/null +++ b/man/man1/pr.1
@@ -0,0 +1,110 @@ +.TH PR 1 +.SH NAME +pr \- print file +.SH SYNOPSIS +.B pr +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Pr +produces a printed listing of one or more +.I files +on its standard output. +The output is separated into pages headed by a date, +the name of the file or a specified header, and the page number. +With no file arguments, +.I pr +prints its standard input. +.PP +Options apply to all following files but may be reset +between files: +.TP +.BI - n +Produce +.IR n -column +output. +.TP +.BI + n +Begin printing with page +.IR n . +.TP +.B -b +Balance columns on last page, in case of multi-column output. +.TP +.B -d +Double space. +.TP +.BI -e n +Set the tab stops for input text every +.I n +spaces. +.TP +.B -h +Take the next argument as a page header +.RI ( file +by default). +.TP +.BI -i n +Replace sequences of blanks in the output +by tabs, using tab stops set every +.I n +spaces. +.TP +.BI -f +Use form feeds to separate pages. +.TP +.BI -l n +Take the length of the page to be +.I n +lines instead of the default 66. +.TP +.B -m +Print all +.I files +simultaneously, +each in one column. +.TP +.BI -n m +Number the lines of each +.IR file . +The numeric argument +.IR m , +default 5, +sets the width of the line-number field. +.TP +.BI -o n +Offset the left margin +.I n +character positions. +.TP +.BI -p +Pad each file printed to an odd number of pages. +For two-sided printers, +this will ensure each file will start a new page. +.TP +.BI -s c +Separate columns by the single character +.I c +instead of aligning them with white space. +A missing +.I c +is taken to be a tab. +.TP +.B -t +Do not print the 5-line header or the +5-line trailer normally supplied for each page. +.TP +.BI -w n +For multi-column output, +take the width of the page to be +.I n +characters instead of the default 72. +.SH SOURCE +.B /usr/local/plan9/src/cmd/pr.c +.SH "SEE ALSO" +.IR cat (1), +.IR lp (1)
diff --git a/man/man1/proof.1 b/man/man1/proof.1 new file mode 100644 index 0000000..01e8e35 --- /dev/null +++ b/man/man1/proof.1
@@ -0,0 +1,134 @@ +.TH PROOF 1 +.SH NAME +proof \- troff output interpreter +.SH SYNOPSIS +.B proof +[ +.BI -m mag +] +[ +.BI -/ nview +] +[ +.B -F +.I dir +] +[ +.B -d +] +[ +.I file +] +.SH DESCRIPTION +.I Proof +reads +.IR troff (1) +intermediate language from +.I file +or standard input +and simulates the resulting pages on the screen. +.PP +After a page of text is displayed, +.I proof +pauses for a command from the keyboard. +The typed commands are: +.TP \w'newline\ \ \ 'u +newline +Go on to next page of text. +.TP +.B - +Go back to the previous page. +.TP +.B q +Quit. +.TP +.BI p n +Print page +.IR n . +An out-of-bounds page number means the end nearer to that number; +a missing number means the current page; +a signed number means an offset to the current page. +.TP +.I n +Same as +.BI p n\f1. +.TP +.B c +Clear the screen, then wait for another command. +.TP +.BI m mag +Change the magnification at which the output is printed. +Normally it is printed with magnification .9; +.IR mag "=.5" +shrinks it to half size; +.IR mag "=2" +doubles the size. +.TP +.BI x val +Move everything +.I val +screen pixels to the right (left, if +.I val +is negative). +.TP +.BI y val +Move everything +.I val +screen pixels down (up, if +.I val +is negative). +.TP +.BI / nview +Split the window into +.I nview +pieces. The current page goes into the rightmost, bottommost piece, +and previous pages are shown in the other pieces. +.TP +.BI "-F " dir +Use +.I dir +for fonts instead of +.BR /lib/font/bit . +.TP +.B d +Toggle the debug flag. +.PD +.PP +These commands are also available, under slightly different form, +from a menu on button 3. The +.B pan +menu item allows arbitrary positioning of the page: +after selecting +.BR pan , +press the mouse button again and hold it down while moving +the page to the desired location. The page will be redisplayed +in its entirety when the button is released. +Mouse button 1 also pans, without the need for selecting from a menu. +.PP +The +.BR m , +.BR x , +.BR y , +.BR F , +.BR / , +and +.B d +commands are also available as command line options. +.SH FILES +.TF /lib/font/bit/MAP +.TP +.B /lib/font/bit/* +fonts +.TP +.B /lib/font/bit/MAP +how to convert troff output fonts and character names +into screen fonts and character numbers +.SH SOURCE +.B /usr/local/plan9/src/cmd/proof +.SH SEE ALSO +.IR lp (1), +.IR gs (1), +.IR page (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual''
diff --git a/man/man1/ps.1 b/man/man1/ps.1 new file mode 100644 index 0000000..9cfcb2e --- /dev/null +++ b/man/man1/ps.1
@@ -0,0 +1,107 @@ +.TH PS 1 +.SH NAME +ps, psu \- process status +.SH SYNOPSIS +.B ps +[ +.B -pa +] +.PP +.B psu +[ +.B -pa +] +[ +.I user +] +.SH DESCRIPTION +.I Ps +prints information about processes. +.I Psu +prints only information about processes started by +.I user +(default +.BR $USER ). +.PP +For each process reported, +the user, +process id, +user time, +system time, +size, +state, +and command name are printed. +State is one of the following: +.TP \w'\fLno\ \fIresource\ \ \ 'u +.B Moribund +Process has exited and is about to have its +resources reclaimed. +.TP +.B Ready +on the queue of processes ready to be run. +.TP +.B Scheding +about to be run. +.TP +.B Running +running. +.TP +.B Queueing +waiting on a queue for a resource. +.TP +.B Wakeme +waiting for I/O or some other kernel event to wake it up. +.TP +.B Broken +dead of unnatural causes; lingering +so that it can be examined. +.TP +.B Stopped +stopped. +.TP +.B Stopwait +waiting for another process to stop. +.TP +.B Fault +servicing a page fault. +.TP +.B Idle +waiting for something to do (kernel processes only). +.TP +.B New +being created. +.TP +.B Pageout +paging out some other process. +.TP +.I Syscall +performing the named system call. +.TP +.BI no " resource +waiting for more of a critical +.IR resource . +.TP +.BI wchan +waiting on the named wait channel +(on a Unix kernel). +.PD +.PP +With the +.B -p +flag, +.I ps +also prints, after the system time, the baseline and current priorities of each process. +.PP +The +.B -a +flag causes +.I ps +to print the arguments for the process. Newlines in arguments will be translated to spaces for display. +.SH SOURCE +.B /usr/local/plan9/bin/ps +.br +.B /usr/local/plan9/bin/psu +.SH "SEE ALSO" +.IR acid (1), +.IR db (1), +.IR kill (1)
diff --git a/man/man1/psfonts.1 b/man/man1/psfonts.1 new file mode 100644 index 0000000..19f3de8 --- /dev/null +++ b/man/man1/psfonts.1
@@ -0,0 +1,125 @@ +.TH PSFONTS 1 +.SH NAME +psfonts, psdownload \- add necessary fonts to PostScript document for printing +.SH SYNOPSIS +.B psfonts +[ +.I files ... +] +.PP +.B psdownload +[ +.B options +] +[ +.I files ... +] +.SH DESCRIPTION +Plan 9's +.IR troff (1) +and +.IR tr2post (1) +use non-standard PostScript fonts +(found in +.BR /usr/local/plan9/postscript/font ). +Before sending PostScript output from +.I tr2post +to a standard printer, code implementing +the non-standard fonts must be added to the PostScript. +.PP +.I Psfonts +copies +.I files +(or standard input) +to standard output, adding necessary PostScript fonts. +.PP +.I Psdownload +is the more general program used to implement +.IR psfonts . +The options are: +.TP +.BI -c " comment +Expect the fonts used in the document to be listed in +a comment beginning with this string +(default +.BR %%DocumentFonts: ). +.TP +.BI -f " atend +Expect extra fonts comments at the end of the document, +so read the entire input before starting output +(by default this only happens if a +.B %%DocumentFonts: +.B (atend) +comment is encountered). +.TP +.BI -m " mapfile +Use +.I mapfile +to translate from PostScript font names to files. +Each line in the map has two white space-separated +fields: a font name and the corresponding file. +If +.I mapfile +is not a rooted path, it is evaluated relative to the +.I fontdir +(see +.B -H +below). +.TP +.BI -p " printer +Set the name of the printer. +This option is deprecated. Its only effect is to override the +.B -r +option, causing +.IB fontdir /printers/ printer +to be used as the resident fonts list. +.TP +.BI -r " residentfonts +Read a list of fonts assumed to be on the printer +(not necessary to re-download) from the file +.IR residentfonts . +If +.I residentfonts +is not a rooted path, it is evaluated relative to the +.I fontdir +(see +.B -H +below). +.TP +.BI -H " fontdir +Set the directory that is assumed to contain the PostScript fonts +and information about printers +(see +.BR -m , +.BR -p , +and +.B -r +above; +default +.BR /usr/local/plan9/postscript/font ). +.TP +.BI -T " tmpdir +Use +.I tmpdir +for storing temporary files +(default +.BR /var/tmp ). +.B +.TP +.BI -D +Produce copious amounts of debugging information on standard error. +.TP +.BI -I +Continue running even after fatal errors occur. +.PD +.SH EXAMPLE +See +.IR tr2post (1) +for an example. +.SH SOURCE +.B /usr/local/plan9/bin/psfonts +.br +.B /usr/local/plan9/src/cmd/postscript/download +.SH SEE ALSO +.IR troff (1), +.IR tr2post (1)
diff --git a/man/man1/pwd.1 b/man/man1/pwd.1 new file mode 100644 index 0000000..a154379 --- /dev/null +++ b/man/man1/pwd.1
@@ -0,0 +1,26 @@ +.TH PWD 1 +.SH NAME +pwd, pbd \- working directory +.SH SYNOPSIS +.B pwd +.br +.B pbd +.SH DESCRIPTION +.I Pwd +prints the path name of the working (current) directory. +.PP +.I Pbd +prints the base name of the working (current) directory. +It prints no final newline and is intended for applications +such as constructing shell prompts. +.SH SOURCE +.B /usr/local/plan9/src/cmd/pbd.c +.SH SEE ALSO +.I cd +in +.IR rc (1), +.IR getwd (3) +.SH BUGS +.I Pwd +is not provided. +Unix already provides one.
diff --git a/man/man1/rc.1 b/man/man1/rc.1 index b294bee..51a2b22 100644 --- a/man/man1/rc.1 +++ b/man/man1/rc.1
@@ -50,7 +50,7 @@ variable .B $status gets the process's wait message (see -.IR wait (2)); +.IR wait (3)); it will be the null string if the command was successful. .PP A long command line may be continued on subsequent lines by typing @@ -83,7 +83,7 @@ .B $path is the program to be executed. To be executable, the user must have execute permission (see -.IR stat (2)) +.IR stat (3)) and the file must be either an executable binary for the current machine's CPU type, or a shell script. Shell scripts begin with a line containing the full path name of a shell @@ -349,7 +349,7 @@ is a previously opened file descriptor and .I fd0 becomes a new copy (in the sense of -.IR dup (2)) +.IR dup (3)) of it. A file descriptor may be closed by writing .BI >[ fd0 =] @@ -542,7 +542,7 @@ A function with a special name will be called when .I rc receives a corresponding note; see -.IR notify (2). +.IR notify (3). The valid note names (and corresponding notes) are .B sighup .RB ( hangup ), @@ -757,10 +757,7 @@ The .I environment is a list of strings made available to executing binaries by the -.B env -device -(see -.IR env (3)). +kernel. .I Rc creates an environment entry for each variable whose value is non-empty, and for each function. @@ -768,7 +765,7 @@ .B = and its value. If the value has more than one component, these -are separated by ctrl-a +are separated by SOH .RB ( '\e001' ) characters. The string for a function is just the @@ -824,12 +821,23 @@ .B . command. If not set in the environment, it is initialized by +parsing the +.B $PATH +variable +(as in +.IR sh (1)) +or by .BR "path=(.\ /bin)" . -Its use is discouraged; instead use -.IR bind (1) -to build a -.B /bin -containing what's needed. +The variables +.B $path +and +.B $PATH +are maintained together: changes to one will be reflected in the other. +.\" Its use is discouraged; instead use +.\" .IR bind (1) +.\" to build a +.\" .B /bin +.\" containing what's needed. .TP .B $pid Set during initialization to
diff --git a/man/man1/rio.1 b/man/man1/rio.1 index 9af90e8..4e30e58 100644 --- a/man/man1/rio.1 +++ b/man/man1/rio.1
@@ -1,54 +1,101 @@ -.if t .ds 85 8\(12 -.if n .ds 85 8-1/2 .TH RIO 1 .SH NAME rio \- rio-like Window Manager for X .SH SYNOPSIS .B rio [ -.B \-grey -] [ -.B \-version -] [ .B \-font -.I fname -] [ +.I fontname +] +[ +.B \-grey +] +[ +.B \-s +] +[ .B \-term .I termprog -] [ -.BR exit | restart +] +[ +.B \-version +] +[ +.B \-virtuals +.I num +] +[ +.B exit +| +.B restart ] .SH DESCRIPTION +.if t .ds 85 8\(12 +.if n .ds 85 8-1/2 .I Rio is a window manager for X which attempts to emulate the window management policies of Plan 9's .I rio window manager. +Rio is derived from David Hogan's \*(85. .PP The .B \-grey -option makes the background light grey, as does \*(85. -Use this option for maximum authenticity. +option makes the background stippled grey, the default X11 background, +instead of solid grey, the Plan 9 background. +.PP +The .B \-font -.I fname +option sets the font in .IR rio 's menu to .IR fname , overriding the default. +Unlike the other programs in the Plan 9 ports, rio expects this +font to be an X11 font rather than a Plan 9 font. +.PP +The .B \-term -.I termprog +option specifies an alternative program to run when the .I New menu item is selected. +The default is to try +.IR 9term (1) +and then to fall back to +.IR xterm (1). +The +.B \-s +option causes +.I rio +to add +.B -s +to +.IR 9term 's +command-line, starting the window in scrolling mode. +.PP +The .B \-version +option prints the current version on standard error, then exits. .PP -To make +The +.B \-virtuals +option sets the number of virtual screens (the default is 1, +and the maximum is 12). +.PP +If the argument +.B exit +or +.B restart +is given, +it is sent to an already-running +.IR rio , +causing the extant .I rio -exit, you have to run -.B "rio exit" -on the command line. There is no ``exit'' menu item. +to exit or restart. +.SS Using rio .PP One window is .IR current , @@ -130,7 +177,16 @@ Pressing button 1 or 2 over a window's border allows one to move the corresponding edge or corner, while button 3 moves the whole window. -.PD +.PP +When the mouse cursor points to the background area +and +.I rio +has been started with multiple virtual screens using the +.B \-virtuals +option, +clicking button 2 brings up a menu to select a virtual screen to view. +Scrolling the mouse wheel while the cursor points at the background +will cycle through the virtual screens. .SH BUGS In Plan 9's @@ -154,4 +210,4 @@ There is a currently a compiled-in limit of 128 hidden windows. .SH "SEE ALSO" .IR 9term (1), -.IR xterm (1). +.IR xterm (1)
diff --git a/man/man1/rm.1 b/man/man1/rm.1 index 9789396..a2ab0d1 100644 --- a/man/man1/rm.1 +++ b/man/man1/rm.1
@@ -25,4 +25,4 @@ .SH SOURCE .B /usr/local/plan9/src/cmd/rm.c .SH "SEE ALSO" -.IR remove (2) +.IR remove (3)
diff --git a/man/man1/sam.1 b/man/man1/sam.1 index b4194b4..e2085ad 100644 --- a/man/man1/sam.1 +++ b/man/man1/sam.1
@@ -1,7 +1,7 @@ .TH SAM 1 .ds a \fR*\ \fP .SH NAME -sam, B, sam.save \- screen editor with structural regular expressions +sam, B, E, sam.save, samterm, samsave \- screen editor with structural regular expressions .SH SYNOPSIS .B sam [ @@ -17,10 +17,8 @@ .B sam.save .PP .B B -[ -.BI -nnnn -] -.I file ... +.IB file \fR[\fP: line \fR] +\&... .SH DESCRIPTION .I Sam is a multi-file editor. @@ -62,7 +60,7 @@ .PD .SS Regular expressions Regular expressions are as in -.IR regexp (6) +.IR regexp (7) with the addition of .BR \en to represent newlines. @@ -791,7 +789,7 @@ with a .B click attribute defining where the selection lies (see -.IR plumb (6)). +.IR plumb (7)). .TP .B look Search forward for the next occurrence of the literal text in dot. @@ -838,6 +836,20 @@ the option allows a line number to be specified for the initial position to display in the last named file (plumbing provides a more general mechanism for this ability). +.PP +.I E +is a shell-level command that can be used as +.B $EDITOR +in a Unix environment. +It runs +.I B +on +.I file +and then waits to exit until +.I file +is changed, which is taken as a signal that +.I file +is done being edited. .SS Abnormal termination If .I sam @@ -879,7 +891,7 @@ .IR sed (1), .IR grep (1), .IR rio (1), -.IR regexp (6). +.IR regexp (7). .PP Rob Pike, ``The text editor sam''.
diff --git a/man/man1/scat.1 b/man/man1/scat.1 index d9bf8db..8840c1d 100644 --- a/man/man1/scat.1 +++ b/man/man1/scat.1
@@ -1,4 +1,4 @@ -.TH SCAT 7 +.TH SCAT 1 .SH NAME scat \- sky catalogue and Digitized Sky Survey .SH SYNOPSIS @@ -10,7 +10,7 @@ and implements database-like manipulations on sets of such objects. It also provides an interface to -.IR astro (7) +.IR astro (1) to plot the locations of solar system objects. Finally, it displays images from the Space Telescope Science Institute's @@ -119,7 +119,7 @@ and .B comet refer to the earth's penumbra at lunar distance and the comet installed in the current -.IR astro (7). +.IR astro (1). The output is the planet's name, right ascension and declination, azimuth and altitude, and phase for the moon and sun, as shown by .BR astro . @@ -182,7 +182,7 @@ .TP .BI astro " option" Run -.IR astro (7) +.IR astro (1) with the specified .I options (to which will be appended @@ -322,9 +322,9 @@ .SH FILES .B /lib/sky/*.scat .SH SOURCE -.B /sys/src/cmd/scat +.B /usr/local/plan9/src/cmd/scat .SH SEE ALSO -.IR astro (7) +.IR astro (1) .br .B /lib/sky/constelnames\ \ the three-letter abbreviations of the constellation names.
diff --git a/man/man1/secstore.1 b/man/man1/secstore.1 new file mode 100644 index 0000000..862857d --- /dev/null +++ b/man/man1/secstore.1
@@ -0,0 +1,212 @@ +.TH SECSTORE 1 +.SH NAME +aescbc, secstore, ipso \- secstore commands +.SH SYNOPSIS +.B secstore +[ +.B -s +.I server +] +[ +.B -(g|G) +.I getfile +] +[ +.B -p +.I putfile +] +[ +.B -r +.I rmfile +] +[ +.B -c +] +[ +.B -u +.I user +] +[ +.B -v +] +[ +.B -i +] +.PP +.B aescbc +-e +.I <cleartext +.I >ciphertext +.br +.B aescbc +-d +.I <ciphertext +.I >cleartext +.PP +.B ipso +[ +.B -a -e -l -f -s +] [ +.I file +\&... +] +.PP +.SH DESCRIPTION +.PP +.I Secstore +authenticates to the server +using a password and optionally a hardware token, +then saves or retrieves a file. +This is intended to be a credentials store (public/private keypairs, +passwords, and other secrets) for a factotum. +.PP +Option +.B -p +stores a file on the secstore. +.PP +Option +.B -g +retrieves a file to the local directory; +option +.B -G +writes it to standard output instead. +Specifying +.I getfile +of . will send to standard output +a list of remote files with dates, lengths and SHA1 hashes. +.PP +Option +.B -r +removes a file from the secstore. +.PP +Option +.B -c +prompts for a password change. +.PP +Option +.B -v +produces more verbose output, in particular providing a few +bits of feedback to help the user detect mistyping. +.PP +Option +.B -i +says that the password should be read from standard input +instead of from +.BR /dev/cons . +.PP +Option +.B -n +says that the password should be read from NVRAM +instead of from +.BR /dev/cons . +This option is unsupported. +.PP +The server is +.BR tcp!$auth!5356 , +or the server specified by option +.BR -s . +.PP +For example, to add a secret to the file read by +.IR factotum (4) +at startup, open a new window, type +.sp +.EX + % ramfs -p; cd /tmp + % auth/secstore -g factotum + secstore password: + % echo 'key proto=apop dom=x.com user=ehg !password=hi' >> factotum + % auth/secstore -p factotum + secstore password: + % read -m factotum > /mnt/factotum/ctl +.EE +.PP +and delete the window. +The first line creates an ephemeral memory-resident workspace, +invisible to others and automatically removed when the window is deleted. +The next three commands fetch the persistent copy of the secrets, +append a new secret, +and save the updated file back to secstore. +The final command loads the new secret into the running factotum. +.PP +The +.I ipso +command packages this sequence into a convenient script to simplify editing of +.I files +stored on a secure store. +It copies the named +.I files +into a local +.IR ramfs (4) +and invokes +.IR acme (1) +on them. When the editor exits, +.I ipso +prompts the user to confirm copying modifed or newly created files back to +.I secstore. +If no +.I file +is mentioned, +.I ipso +grabs all the user's files from +.I secstore +for editing. +.PP +By default, ipso will edit the +.I secstore +files and, if +one of them is named +.BR factotum , +flush your current keys from factotum and load +the new ones from the file. +If you supply any of the +.BR -e , +.BR -f , +or +.BR -l +options, +.I ipso +will just perform the operations you requested, i.e., +edit, flush, and/or load. +.PP +The +.B -s +option of +.I ipso +invokes +.IR sam (1) +as the editor insted of +.BR acme ; +the +.B -a +option provides a similar service for files encrypted by +.I aescbc +.RI ( q.v. ). +With the +.B -a +option, the full rooted pathname of the +.I file +must be specified and all +.I files +must be encrypted with the same key. +Also with +.BR -a , +newly created files are ignored. +.PP +.I Aescbc +encrypts and decrypts using AES (Rijndael) in cipher +block chaining (CBC) mode. +.SH SOURCE +.B /usr/local/plan9/src/cmd/secstore +.SH SEE ALSO +.IR factotum (4), +Plan 9's \fIsecstore\fR(8) +.SH BUGS +There is deliberately no backup of files on the secstore, so +.B -r +(or a disk crash) is irrevocable. You are advised to store +important secrets in a second location. +.PP +When using +.IR ipso , +secrets will appear as plain text in the editor window, +so use the command in private.
diff --git a/man/man1/sed.1 b/man/man1/sed.1 new file mode 100644 index 0000000..4e9ac33 --- /dev/null +++ b/man/man1/sed.1
@@ -0,0 +1,385 @@ +.TH SED 1 +.SH NAME +9sed \- stream editor +.SH SYNOPSIS +.B 9sed +[ +.B -n +] +[ +.B -g +] +[ +.B -e +.I script +] +[ +.B -f +.I sfile +] +[ +.I file ... +] +.SH DESCRIPTION +.I Sed +copies the named +.I files +(standard input default) to the standard output, +edited according to a script of commands. +The +.B -f +option causes the script to be taken from file +.IR sfile ; +these options accumulate. +If there is just one +.B -e +option and no +.BR -f 's, +the flag +.B -e +may be omitted. +The +.B -n +option suppresses the default output; +.B -g +causes all substitutions to be global, as if suffixed +.BR g . +.PP +A script consists of editing commands, one per line, +of the following form: +.IP +[\fIaddress\fR [\fL,\fI address\fR] ] \fIfunction\fR [\fIargument\fR ...] +.PP +In normal operation +.I sed +cyclically copies a line of input into a +.I pattern space +(unless there is something left after +a +.L D +command), +applies in sequence +all commands whose +.I addresses +select that pattern space, +and at the end of the script copies the pattern space +to the standard output (except under +.BR -n ) +and deletes the pattern space. +.PP +An +.I address +is either a decimal number that counts +input lines cumulatively across files, a +.L $ +that +addresses the last line of input, or a context address, +.BI / regular-expression / \f1, +in the style of +.IR regexp (7), +with the added convention that +.L \en +matches a +newline embedded in the pattern space. +.PP +A command line with no addresses selects every pattern space. +.PP +A command line with +one address selects each pattern space that matches the address. +.PP +A command line with +two addresses selects the inclusive range from the first +pattern space that matches the first address through +the next pattern space that matches +the second. +(If the second address is a number less than or equal +to the line number first selected, only one +line is selected.) +Thereafter the process is repeated, looking again for the +first address. +.PP +Editing commands can be applied to non-selected pattern +spaces by use of the negation function +.L ! +(below). +.PP +An argument denoted +.I text +consists of one or more lines, +all but the last of which end with +.L \e +to hide the +newline. +Backslashes in text are treated like backslashes +in the replacement string of an +.L s +command, +and may be used to protect initial blanks and tabs +against the stripping that is done on +every script line. +.PP +An argument denoted +.I rfile +or +.I wfile +must terminate the command +line and must be preceded by exactly one blank. +Each +.I wfile +is created before processing begins. +There can be at most 120 distinct +.I wfile +arguments. +.TP \w'\fL!\ \fIfunction\fLXXX'u +.B a\e +.br +.ns +.TP +.I text +Append. +Place +.I text +on the output before +reading the next input line. +.TP +.BI b " label" +Branch to the +.B : +command bearing the +.IR label . +If +.I label +is empty, branch to the end of the script. +.TP +.B c\e +.br +.ns +.TP +.I text +Change. +Delete the pattern space. +With 0 or 1 address or at the end of a 2-address range, place +.I text +on the output. +Start the next cycle. +.TP +.B d +Delete the pattern space. +Start the next cycle. +.TP +.B D +Delete the initial segment of the +pattern space through the first newline. +Start the next cycle. +.TP +.B g +Replace the contents of the pattern space +by the contents of the hold space. +.TP +.B G +Append the contents of the hold space to the pattern space. +.TP +.B h +Replace the contents of the hold space by the contents of the pattern space. +.TP +.B H +Append the contents of the pattern space to the hold space. +.ne 3 +.TP +.B i\e +.br +.ns +.TP +.I text +Insert. +Place +.I text +on the standard output. +.TP +.B n +Copy the pattern space to the standard output. +Replace the pattern space with the next line of input. +.TP +.B N +Append the next line of input to the pattern space +with an embedded newline. +(The current line number changes.) +.TP +.B p +Print. +Copy the pattern space to the standard output. +.TP +.B P +Copy the initial segment of the pattern space through +the first newline to the standard output. +.TP +.B q +Quit. +Branch to the end of the script. +Do not start a new cycle. +.TP +.BI r " rfile" +Read the contents of +.IR rfile . +Place them on the output before reading +the next input line. +.TP +.B s/\fIregular-expression\fP/\fIreplacement\fP/\fIflags +Substitute the +.I replacement +string for instances of the +.I regular-expression +in the pattern space. +Any character may be used instead of +.LR / . +For a fuller description see +.IR regexp (7). +.I Flags +is zero or more of +.RS +.TP +.B g +Global. +Substitute for all non-overlapping instances of the +.I regular expression +rather than just the +first one. +.TP +.B p +Print the pattern space if a replacement was made. +.TP +.BI w " wfile" +Write. +Append the pattern space to +.I wfile +if a replacement +was made. +.RE +.TP +.BI t " label" +Test. +Branch to the +.L : +command bearing the +.I label +if any +substitutions have been made since the most recent +reading of an input line or execution of a +.LR t . +If +.I label +is empty, branch to the end of the script. +.TP +.B w +.I wfile +.br +Write. +Append the pattern space to +.IR wfile . +.TP +.B x +Exchange the contents of the pattern and hold spaces. +.TP +.B y/\fIstring1\fP/\fIstring2\fP/ +Transform. +Replace all occurrences of characters in +.I string1 +with the corresponding character in +.IR string2 . +The lengths of +.I +string1 +and +.I string2 +must be equal. +.TP +.BI ! "function" +Don't. +Apply the +.I function +(or group, if +.I function +is +.LR { ) +only to lines +.I not +selected by the address(es). +.TP +.BI : " label" +This command does nothing; it bears a +.I label +for +.B b +and +.B t +commands to branch to. +.TP +.B = +Place the current line number on the standard output as a line. +.TP +.B { +Execute the following commands through a matching +.L } +only when the pattern space is selected. +.TP +.B " " +An empty command is ignored. +.ne 4 +.SH EXAMPLES +.TP +.B sed 10q file +Print the first 10 lines of the file. +.TP +.B sed '/^$/d' +Delete empty lines from standard input. +.TP +.B sed 's/UNIX/& system/g' +Replace every instance of +.L UNIX +by +.LR "UNIX system" . +.PP +.EX +sed 's/ *$// \fRdrop trailing blanks\fP +/^$/d \fRdrop empty lines\fP +s/ */\e \fRreplace blanks by newlines\fP +/g +/^$/d' chapter* +.EE +.ns +.IP +Print the files +.BR chapter1 , +.BR chapter2 , +etc. one word to a line. +.PP +.EX +nroff -ms manuscript | sed ' +${ + /^$/p \fRif last line of file is empty, print it\fP +} +//N \fRif current line is empty, append next line\fP +/^\en$/D' \fRif two lines are empty, delete the first\fP +.EE +.ns +.IP +Delete all but one of each group of empty lines from a +formatted manuscript. +.SH SOURCE +.B /usr/local/plan9/src/cmd/9sed.c +.SH SEE ALSO +.IR ed (1), +.IR grep (1), +.IR awk (1), +.IR lex (1), +.IR sam (1), +.IR regexp (7) +.br +L. E. McMahon, +`SED \(em A Non-interactive Text Editor', +Unix Research System Programmer's Manual, Volume 2. +.SH BUGS +If input is from a pipe, buffering may consume +characters beyond a line on which a +.L q +command is executed.
diff --git a/man/man1/seq.1 b/man/man1/seq.1 index 73796c2..5fda241 100644 --- a/man/man1/seq.1 +++ b/man/man1/seq.1
@@ -38,7 +38,7 @@ .TP "\w'\fL-f \fIformat\fLXX'u" .BI -f format Use the -.IR print (2)-style +.IR print (3)-style .I format .IR print for printing each (floating point) number.
diff --git a/man/man1/sleep.1 b/man/man1/sleep.1 index 6416bc1..68c94a9 100644 --- a/man/man1/sleep.1 +++ b/man/man1/sleep.1
@@ -28,4 +28,4 @@ .SH SOURCE .B /usr/local/plan9/src/cmd/sleep.c .SH "SEE ALSO" -.IR sleep (2) +.IR sleep (3)
diff --git a/man/man1/split.1 b/man/man1/split.1 index 6e7f7eb..e00e3d0 100644 --- a/man/man1/split.1 +++ b/man/man1/split.1
@@ -41,7 +41,7 @@ that matches a regular .IR expression ; see -.IR regexp (6). +.IR regexp (7). Multiple .B -e options may appear. @@ -79,4 +79,4 @@ .IR sed (1), .IR awk (1), .IR grep (1), -.IR regexp (6) +.IR regexp (7)
diff --git a/man/man1/src.1 b/man/man1/src.1 new file mode 100644 index 0000000..4c03dd7 --- /dev/null +++ b/man/man1/src.1
@@ -0,0 +1,83 @@ +.TH SRC 1 +.SH NAME +src \- find source code for executable +.SH SYNOPSIS +.B src +[ +.B -n +] +[ +.B -s +.I symbol +] +.I file +.B ... +.SH DESCRIPTION +.I Src +examines the named +.I files +to find the corresponding source code, which is then sent to the editor using +.B B +(see +.IR sam (1)). +If +.I file +is an +.IR rc (1) +script, the source is the file itself. +If +.I file +is an executable, the source is defined to be the single file containing the +definition of +.B main +and +.I src +will point the editor at the line that begins the definition. +.I Src +uses +.IR db (1) +to extract the symbol table information that identifies the source. +.PP +.I Src +looks for each +.I file +in the current directory, in +.BR /bin , +and in the subdirectories of +.BR /bin , +in that order. +.PP +The +.B -n +flag causes +.B src +to print the file name but not send it to the editor. +The +.B -s +flag identifies a +.I symbol +other than +.B main +to locate. +.SH EXAMPLES +Find the source to the +.B main +routine in +.BR /bin/ed : +.IP +.EX +src ed +.EE +.PP +Find the source for +.BR strcmp : +.IP +.EX +src -s strcmp rc +.EE +.SH SOURCE +.B /usr/local/plan9/bin/src +.SH "SEE ALSO" +.IR db (1), +.IR plumb (1), +.IR sam (1).
diff --git a/man/man1/tbl.1 b/man/man1/tbl.1 index 921e9e8..0e986e9 100644 --- a/man/man1/tbl.1 +++ b/man/man1/tbl.1
@@ -272,7 +272,7 @@ .if t \{.sp3 .1C\} .SH SOURCE -.B /sys/src/cmd/tbl +.B /usr/local/plan9/src/cmd/tbl .SH SEE ALSO .IR troff (1), .IR eqn (1),
diff --git a/man/man1/tcs.1 b/man/man1/tcs.1 new file mode 100644 index 0000000..e1a410c --- /dev/null +++ b/man/man1/tcs.1
@@ -0,0 +1,167 @@ +.TH TCS 1 +.SH NAME +tcs \- translate character sets +.SH SYNOPSIS +.B tcs +[ +.B -slcv +] +[ +.B -f +.I ics +] +[ +.B -t +.I ocs +] +[ +.I file ... +] +.SH DESCRIPTION +.I Tcs +interprets the named +.I file(s) +(standard input default) as a stream of characters from the +.I ics +character set or format, converts them to runes, +and then converts them into a stream of characters from the +.I ocs +character set or format on the standard output. +The default value for +.I ics +and +.I ocs +is +.BR utf , +the +.SM UTF +encoding described in +.IR utf (7). +The +.B -l +option lists the character sets known to +.IR tcs . +Processing continues in the face of conversion errors (the +.B -s +option prevents reporting of these errors). +The +.B -c +option forces the output to contain only correctly converted characters; +otherwise, +.B 0x80 +characters will be substituted for +.SM UTF +encoding errors and +.B 0xFFFD +characters will substituted for unknown characters. +.PP +The +.B -v +option generates various diagnostic and summary information on standard error, +or makes the +.B -l +output more verbose. +.PP +.I Tcs +recognizes an ever changing list of character sets. +In particular, it supports a variety of Russian and Japanese encodings. +Some of the supported encodings are +.TF jis-kanji +.TP +.B utf +The Plan 9 +.SM UTF +encoding, known by ISO as UTF-8 +.TP +.B utf1 +The deprecated original +.SM UTF +encoding from ISO 10646 +.TP +.B ascii +7-bit ASCII +.TP +.B 8859-1 +Latin-1 (Central European) +.TP +.B 8859-2 +Latin-2 (Czech .. Slovak) +.TP +.B 8859-3 +Latin-3 (Dutch .. Turkish) +.TP +.B 8859-4 +Latin-4 (Scandinavian) +.TP +.B 8859-5 +Part 5 (Cyrillic) +.TP +.B 8859-6 +Part 6 (Arabic) +.TP +.B 8859-7 +Part 7 (Greek) +.TP +.B 8859-8 +Part 8 (Hebrew) +.TP +.B 8859-9 +Latin-5 (Finnish .. Portuguese) +.TP +.B koi8 +KOI-8 (GOST 19769-74) +.TP +.B jis-kanji +ISO 2022-JP +.TP +.B ujis +EUC-JX: JIS 0208 +.TP +.B ms-kanji +Microsoft, or Shift-JIS +.TP +.B jis +(from only) guesses between ISO 2022-JP, EUC or Shift-Jis +.TP +.B gb +Chinese national standard (GB2312-80) +.TP +.B big5 +Big 5 (HKU version) +.TP +.B unicode +Unicode Standard 1.0 +.TP +.B tis +Thai character set plus +.SM ASCII +(TIS 620-1986) +.TP +.B msdos +IBM PC: CP 437 +.TP +.B atari +Atari-ST character set +.SH EXAMPLES +.TP +.B tcs -f 8859-1 +Convert 8859-1 (Latin-1) characters into +.SM UTF +format. +.TP +.B tcs -s -f jis +Convert characters encoded in one of several shift JIS encodings into +.SM UTF +format. +Unknown Kanji will be converted into +.B 0xFFFD +characters. +.TP +.B tcs -lv +Print an up to date list of the supported character sets. +.SH SOURCE +.B /usr/local/plan9/src/cmd/tcs +.SH SEE ALSO +.IR ascii (1), +.IR rune (3), +.IR utf (7).
diff --git a/man/man1/touch.1 b/man/man1/touch.1 index 3b07489..551ea2c 100644 --- a/man/man1/touch.1 +++ b/man/man1/touch.1
@@ -28,7 +28,7 @@ .B /usr/local/plan9/src/cmd/touch.c .SH SEE ALSO .IR ls (1), -.IR stat (2), +.IR stat (3), .IR chmod (1) .SH BUGS .I Touch
diff --git a/man/man1/tr2post.1 b/man/man1/tr2post.1 new file mode 100644 index 0000000..3c4597f --- /dev/null +++ b/man/man1/tr2post.1
@@ -0,0 +1,111 @@ +.TH TR2POST 1 +.SH NAME +tr2post \- convert troff intermediate to PostScript +.SH SYNOPSIS +.B tr2post +[ +.B options +] +[ +.I files ... +] +.SH DESCRIPTION +.I Tr2post +converts +.I files +(or standard input), +which should be the device-independent output of +.IR troff (1), +into the PostScript printer language. +.PP +The options are: +.TP +.BI -a " aspectratio +Set an aspect ratio +.RI ( y / x ) +to stretch the PostScript output (default 1.0). +.TP +.BI -c " copies +Set a comment in the PostScript output +marking the number of copies that should be printed. +The comment is intended for ancient versions of the Unix +\fIlp\fR(1) and is not recognized by any current printer +or print spooler. +.TP +.BI -d +Emit volumes of debugging output on standard error. +.TP +.BI -m " magnification +Magnify the PostScript output (default 1.0). +.TP +.BI -n " formsperpage +Print the PostScript with +.I formsperpage +logical pages per physical page +(default 1). +Using this option emits PostScript with invalid document structuring +comments. +It will print fine but will not view correctly in +.IR gv (1) +or +.IR psv (1). +.TP +.BI -o " pagelist +Print only the pages in the +.IR pagelist , +which is a comma-separated list of ranges. +Each range is of the form +.I p +(just page +.IR p ), +.IB p - q +(pages +.I p +through +.IR q ), +.BI - p +(pages 1 through +.IR p ), +or +.IB p - +(pages +.I p +through the end of the document). +.TP +.BI -p " " l +Print the document in landscape mode. +An argument that does not begin with +.L l +will print the document in portrait mode. +.TP +.BI -x " xoffset +Translate the page output by +.I xoffset +inches to the right. +(Negative offsets translate to the left.) +.TP +.BI -y " yoffset +Translate the page output by +.I yoffset +inches down. +(Negative offsets translate up.) +.TP +.BI -P " pscode +Emit the text +.I pscode +at the end of the usual PostScript header. +.PD +.SH EXAMPLE +Preview this manual page: +.IP +.EX +troff -man /usr/local/plan9/man/man1/tr2post.1 | +tr2post | +psfonts >/tmp/a.ps +psv /tmp/a.ps +.EE +.SH SOURCE +.B /usr/local/plan9/src/cmd/postscript/tr2post +.SH SEE ALSO +.IR troff (1), +.IR psfonts (1)
diff --git a/man/man1/troff.1 b/man/man1/troff.1 index db5b9e6..3f990ab 100644 --- a/man/man1/troff.1 +++ b/man/man1/troff.1
@@ -174,17 +174,18 @@ font width tables for .I troff .SH SOURCE -.B /sys/src/cmd/troff +.B /usr/local/plan9/src/cmd/troff .SH "SEE ALSO" -.IR lp (1), +.IR lpr (1), .IR proof (1), +.IR tr2post (1), .IR eqn (1), .IR tbl (1), .IR pic (1), .IR grap (1), .IR doctype (1), -.IR ms (6), -.IR image (6), +.IR ms (7), +.IR image (7), .IR tex (1), .IR deroff (1) .br
diff --git a/man/man1/tweak.1 b/man/man1/tweak.1 new file mode 100644 index 0000000..511e1ce --- /dev/null +++ b/man/man1/tweak.1
@@ -0,0 +1,167 @@ +.TH TWEAK 1 +.CT 1 graphics +.SH NAME +tweak \- edit image files, subfont files, face files, etc. +.SH SYNOPSIS +.B tweak +[ +.I file ... +] +.SH DESCRIPTION +.I Tweak +edits existing files holding various forms of images. +To create original images, start from an existing image, subfont, etc. +.PP +.I Tweak +reads its argument +.I files +and displays the resulting images in a vertical column. +If the image is too wide to fit across the display, it +is folded much like a long line of text in an +.IR rio +window. +Under each image is displayed one or two lines of text +presenting its parameters. +The first line shows the image's +.BR depth , +the number +of bits per pixel; +.BR r , +the rectangle covered by the image; +and the name of the +.B file +from which it was read. +If the file is a subfont, a second line presents a hexadecimal 16-bit +.B offset +to be applied to character values from the subfont +(typically as stored in a font file; see +.IR font (7)); +and the subfont's +.BR n , +.BR height , +and +.B ascent +as defined in +.IR cachechars (3). +.PP +By means described below, magnified views of portions of the images +may be displayed. +The text associated with such a view includes +.BR mag , +the magnification. +If the view is of a single character from a subfont, the second +line of text shows the character's value (including the subfont's offset) +in hexadecimal and as a character in +.I tweak's +default font; the character's +.BR x , +.BR top , +.BR bottom , +.BR left , +and +.BR width +as defined in +.IR cachechars (3); +and +.BR iwidth , +the physical width of the image in the subfont's image. +.PP +There are two methods to obtain a magnified view of a character from a +subfont. +The first is to click mouse button 1 over the image of the character in +the subfont. The second is to select the +.B char +entry on the button 3 menu, +point the resulting gunsight cursor at the desired subfont and click button 3, +and then type at the text prompt at the bottom of the screen the +character value, either as a multi-digit hexadecimal number or as a single +rune representing the character. +.PP +To magnify a portion of other types of image files, +click button 1 over the unmagnified file. +The cursor will switch to a cross. +Still with button 1, sweep a rectangle, as in +.BR rio , +that encloses the portion of the image to be magnified. +(If the file is 16×16 or smaller, +.I tweak +will just magnify the entire file; no sweeping is necessary.) +.PP +Pressing buttons 1 and 2 within magnified images changes pixel values. +By default, button 1 sets the pixel to all zeros and button 2 sets the pixel +to all ones. +.PP +Across the top of the screen is a textual display of global parameters. +These values, as well as many of the textual values associated with +the images, may be edited by clicking button 1 on the displayed +value and typing a new value. +The values along the top of the screen are: +.TP +.B mag +Default magnification. +.TP +.B val(hex) +The value used to modify pixels within magnified images. +The value must be in hexadecimal, optionally preceded by a +tilde for bitwise negation. +.TP +.B but1 +.TP +.B but2 +The pixel value written when the corresponding button is pressed over a pixel. +.TP +.B invert-on-copy +Whether the pixel values are inverted when a +.B copy +operation is performed. +.PP +Under button 3 is a menu holding a variety of functions. +Many of these functions prompt for the image upon which to act +by switching to a gunsight cursor; click button 3 over the +selection, or click a different button to cancel the action. +.TP +.B open +Read and display a file. The name of the file is typed to the prompt +on the bottom line. +.TP +.B read +Reread a file. +.TP +.B write +Write a file. +.TP +.B copy +Use the copy function, default +.BR S , +to transfer a rectangle of pixels from one image to another. +The program prompts with a cross cursor; sweep out a rectangle in +one image or just click button 3 to select the whole image. +The program will leave that rectangle in place and +attach another one to the cursor. Move that rectangle to the desired +place in any image and click button 3, or another button to cancel the action. +.TP +.B char +As described above, open a magnified view of a character image in a subfont. +.TP +.B pixels +Report the coordinate and value of individual pixels indicated by pressing button 3. +This is a mode of operation canceled by pressing button 1 or 2. +.TP +.B close +Close the specified image. +If the image is the unmagnified file, also close any magnified views of that file. +.TP +.B exit +Quit +.IR tweak . +The program will complain once about modified but unwritten files. +.SH SOURCE +.B /usr/local/plan9/src/cmd/draw/tweak.c +.SH "SEE ALSO" +.IR cachechars (3), +.IR image (7), +.IR font (7) +.SH BUGS +For a program written to adjust width tables in fonts, +.I tweak +has been pushed unreasonably far.
diff --git a/man/man1/units.1 b/man/man1/units.1 new file mode 100644 index 0000000..2386356 --- /dev/null +++ b/man/man1/units.1
@@ -0,0 +1,108 @@ +.TH UNITS 1 +.if n .ds / / +.SH NAME +units \- conversion program +.SH SYNOPSIS +.B units +[ +.B -v +] +[ +.I file +] +.SH DESCRIPTION +.I Units +converts quantities expressed +in various standard scales to +their equivalents in other scales. +It works interactively in this fashion: +.IP +.EX +you have: inch +you want: cm + * 2.54 + / 0.393701 +.EE +.PP +A quantity is specified as a multiplicative combination +of units and floating point numbers. +Operators have the following precedence: +.IP +.EX +.ta \w'\fLXXXXXXXXXXXXXXX'u +\fL+\fP \fL-\fP \f1add and subtract +\fL*\fP \fL/\fP \fL×\fP \fL÷\fP \f1multiply and divide +catenation multiply +\fL²\fP \fL³\fP \fL^\fP \f1exponentiation +\fL|\fP \f1divide +\fL(\fP ... \fL)\fP \f1grouping +.EE +.PP +Most familiar units, +abbreviations, and metric prefixes are recognized, +together with a generous leavening of exotica +and a few constants of nature including: +.IP +.de fq +\fL\\$1\\fP \\$2 \\$3 \\$4 \\$5 \\$6 +.. +.ta \w'\fLwaterXXX'u +.nf +.fq pi,\f1π\fP ratio of circumference to diameter +.fq c speed of light +.fq e charge on an electron +.fq g acceleration of gravity +.fq force same as \fLg\fP +.fq mole Avogadro's number +.fq water "pressure head per unit height of water" +.fq au astronomical unit +.fi +.PP +The +.L pound +is a unit of +mass. +Compound names are run together, e.g. +.LR lightyear . +British units that differ from their US counterparts +are prefixed thus: +.LR brgallon . +Currency is denoted +.LR belgiumfranc , +.LR britainpound , +etc. +.PP +The complete list of units can be found in +.BR /lib/units . +A +.I file +argument to +.I units +specifies a file to be used instead of +.BR /lib/units. +The +.B -v +flag causes +.I units +to print its entire database. +.SH EXAMPLE +.EX +you have: 15 pounds force/in² +you want: atm + * 1.02069 + / .97973 +.EE +.SH FILES +.B /lib/units +.SH SOURCE +.B /usr/local/plan9/src/cmd/units.y +.SH BUGS +Since +.I units +does only multiplicative scale changes, +it can convert Kelvin to Rankine but not Centigrade to +Fahrenheit. +.br +Currency conversions are only as accurate as the last time someone +updated +.BR /lib/units .
diff --git a/man/man1/vac.1 b/man/man1/vac.1 new file mode 100644 index 0000000..4d3208d --- /dev/null +++ b/man/man1/vac.1
@@ -0,0 +1,130 @@ +.TH VAC 1 +.SH NAME +vac \- create a vac archive on Venti +.SH SYNOPSIS +.B vac +[ +.B -mqsv +] [ +.B -b +.I blocksize +] [ +.B -d +.I oldvacfile +] [ +.B -e +.I exclude +] [ +.B -f +.I vacfile +] [ +.B -i +.I name +] [ +.B -h +.I host +] +.I file ... +.SH DESCRIPTION +.I Vac +creates an archival copy of Plan 9 file trees on Venti. It can be used +to build a simple backup system. One of the unusual properties of Venti is +that duplicate blocks are detected and coalesced. When +.I vac +is used on a file tree that shares data with an existing archive, the consumption of +storage will be approximately equal to an incremental backup. +This reduction in storage consumption occurs transparently to the user. +.PP +As an optimization, the +.B -d +and +.B -q +options, described below, can be used to explicitly create an archive relative to an existing archive. +These options do not change the resulting archive generated by +.IR vac , +but simply reduce the number of write operations to Venti. +.PP +The output of +.I vac +is the hexadecimal representation of the Sha1 fingerprint of the root of the archive, in this format: +.IP +.EX +vac:64daefaecc4df4b5cb48a368b361ef56012a4f46 +.EE +.PP +Option to +.I vac +are: +.TP +.BI -b " blocksize +Specifies the block size that data will be broken into. +The units for the size can be specified by appending +.L k +to indicate kilobytes. +The default is 8k. +The size must be in the range +of 512 bytes to 52k. +.TP +.BI -d " oldvacfile +Reduce the number of blocks written to Venti by comparing the files to be stored with +the contents of an existing +.I vac +file tree given by +.IR oldvacfile . +.TP +.BI -e " exclude +Do not include the file or directory specified by +.IR exclude . +This option may be repeated multiple times. +.TP +.BI -f " vacfile +The results of +.I vac +are place in +.IR vacfile , +or the standard output if no file is given. +.TP +.BI -i " name +Include standard input as one of the input files, storing it in the archive +with the specified +.IR name . +.TP +.BI -h " host +The network address of the Venti server. +The default is taken from the environment variable +.BR venti . +.\" If this variable does not exist, then the default is the +.\" metaname +.\" .BR $venti , +.\" which can be configured via +.\" .IR ndb (6). +.TP +.B -m +Expand and merge any +.I vac +archives that are found while reading the input files. This option is +useful for building an archive from a collection of existing archives. Each archive is inserted +into the new archive as if it had been unpacked in the directory in which it was found. Multiple +archives can be unpacked in a single directory and the contents will be merged. To be detected, the +archives must end in +.LR .vac . +Note, an archive is inserted by simply copying the root fingerprint and does not require +the archive to be unpacked. +.TP +.B -q +Increase the performance of the +.B -d +option by detecting unchanged files based on a match of the files name and other meta data, +rather than examining the contents of the files. +.TP +.B -s +Print out various statistics on standard error. +.TP +.B -v +Produce more verbose output on standard error, including the name of the files added to the archive +and the vac archives that are expanded and merged. +.SH SOURCE +.B /usr/local/plan9/src/cmd/vac +.SH "SEE ALSO" +Plan 9's \fIvacfs\fR(4) and \fIventi\fR(8) +
diff --git a/man/man1/web.1 b/man/man1/web.1 new file mode 100644 index 0000000..0bcc9ca --- /dev/null +++ b/man/man1/web.1
@@ -0,0 +1,75 @@ +.TH WEB 1 +.SH NAME +web, wmail \- handle web page, mail message for plumber +.SH SYNOPSIS +.B web +.I url +\&... +.br +.B wmail +.I address +.SH DESCRIPTION +.I Web +opens each of the named +.I urls +in a new web browser window. +Any of the +.I urls +may be relative paths to files in the file system; +they will be translated into +.B file:// +URLs before being passed to the web browser. +.PP +.I Web +uses the +web browser's +.B -remote +option command-line option, +which requires an instance of the web browser +to be already running. +The choice of browser is determined by the +.B $BROWSER +environment variable, which should be the name of +the executable for your choice of web browser. +Since the various browsers all use different syntaxes +in their +.B -remote +options, the executable name is inspected to determine +the type of browser. +The supported browsers are Opera, Mozilla Firefox, Mozilla Firebird, and Mozilla. +When possible, +.I web +opens each URL in a new tab rather than a new window. +.PP +.I Wmail +starts the composition of a new mail message to +.IR address . +.PP +The choice of mailer is determined by the +.B $MAILER +environment variable. +The supported mailers are: +.TP browser +invoke the mailer via a +.B mailto:// +URL passed to +.I web +.PD +.PP +.I Web +and +.I wmail +are invoked as start commands in the +.IR plumber (4)'s +rules for opening web pages and writing mail messages. +.SH FILES +.TP +.B /usr/local/plan9/plumb/basic +plumbing rules using +.I web +and +.I wmail +.SH SOURCE +.B /usr/local/plan9/bin +.SH SEE ALSO +.IR plumber (4)
diff --git a/man/man1/wintext.1 b/man/man1/wintext.1 new file mode 100644 index 0000000..7d3463d --- /dev/null +++ b/man/man1/wintext.1
@@ -0,0 +1,98 @@ +.TH WINTEXT 1 +.SH NAME +wintext, ", "" \- access text in current window +.SH SYNOPSIS +.B wintext +.br +.B \C'"'\ +[ +.I prefix +] +.br +.B \C'"'\C'"'\ +[ +.I prefix +] +.SH DESCRIPTION +.I Wintext +prints the text of the current +.I win +(see +.IR acme (1)) +or +.IR 9term (1) +window to standard output. +.PP +.I \C'"' +searches the window text for commands typed with a particular prefix +and prints them, indented, to standard output. +.I Prefix +is a regular expression that is matched against the beginning of the command-line. +If +.I prefix +is omitted, +.I \C'"' +prints the last command executed. +.I \C'"'\C'"' +prints the last command that +.I \C'"' +would print and then executes it by piping it into +.IR rc (1). +.PP +Both +.I \C'"' +and +.I \C'"'\C'"' +identify commands in the window text by looking for lines +beginning with a shell prompt. +Prompts are assumed to be an unindented sequence of +non-whitespace characters followed by one of the +characters +.BR % , +.BR ; , +.BR $ , +or +.BR # . +.SH EXAMPLES +Print the +.IR ls (1) +and +.I lc +commands executed in this window: +.IP +.EX +.ta +4n +% \C'"' 'l[sc]' + % ls -l /tmp/qq* + # ls -lrt /etc + % lc r* +% +.EE +.PP +Execute the most recent +.I lc +command again: +.IP +.EX +.ta +4n +% \C'"'\C'"' lc + % lc r* +ramfs rc read rio rm +% +.EE +.SH SEE ALSO +.IR 9term (1), +.IR acme (1) +.SH SOURCE +.B /usr/local/plan9/bin +.SH BUGS +.I \C'"' +and +.I \C'"'\C'"' +are hard to type in shells other than +.IR rc (1). +.\" and in troff! +.PP +Don't run +.I \C'"'\C'"' +twice in a row.
diff --git a/man/man1/yacc.1 b/man/man1/yacc.1 index 08d51b7..91bc7d0 100644 --- a/man/man1/yacc.1 +++ b/man/man1/yacc.1
@@ -106,7 +106,7 @@ The parser accepts .SM UTF input text (see -.IR utf (6)), +.IR utf (7)), which has a couple of effects. First, the return value of .B yylex() @@ -145,7 +145,7 @@ .B /usr/local/plan9/lib/yaccpars parser prototype using stdio .SH SOURCE -.B /usr/local/plan9/src/cmd/yacc.c +.B /usr/local/plan9/src/cmd/9yacc.c .SH "SEE ALSO" .IR lex (1) .br
diff --git a/man/man3/9p.3 b/man/man3/9p.3 index 9e75573..9d8967e 100644 --- a/man/man3/9p.3 +++ b/man/man3/9p.3
@@ -10,8 +10,9 @@ readbuf, readstr, respond, +srv, threadpostmountsrv, -srv \- 9P file service +walkandclone \- 9P file service .SH SYNOPSIS .ft L .nf @@ -176,9 +177,7 @@ .BI /srv/ name . .IP Fork a child process via -.I rfork -(see -.IR fork (3)) +.IR rfork (3) or .I procrfork (see @@ -214,9 +213,7 @@ .LP If any error occurs during this process, the entire process is terminated by calling -.I sysfatal -(see -.IR perror (3)). +.IR sysfatal (3). .SS Service functions The functions in a .B Srv @@ -603,12 +600,12 @@ in changing the metadata for .IB r -> fid as described in -.IR stat (5). +.IR stat (9p). When using file trees, .I srv will take care to check that the request satisfies the permissions outlined in -.IR stat (5). +.IR stat (9p). Otherwise .I wstat should take care to enforce permissions @@ -720,19 +717,16 @@ option to increment .BR chatty9p . .SH EXAMPLES -.IR Archfs (4), -.IR cdfs (4), -.IR nntpfs (4), -.IR snap (4), -and -.B /usr/local/plan9/src/lib9p/ramfs.c -are good examples of simple single-threaded file servers. -.IR Webfs (4) +/usr/local/plan9/src/lib9p/ramfs.c +is an example of simple single-threaded file servers. +On Plan 9, see +.IR archfs , +.IR cdfs , +.IR nntpfs , +.IR webfs , and .I sshnet -(see -.IR ssh (1)) -are good examples of multithreaded file servers. +for more examples. .PP In general, the .B File @@ -752,9 +746,4 @@ .SH SEE ALSO .IR 9pfid (3), .IR 9pfile (3), -.IR srv (3), -.IR intro (5) -.SH BUGS -The switch to 9P2000 was taken as an opportunity to tidy -much of the interface; we promise to avoid such gratuitous change -in the future. +.IR intro (9p)
diff --git a/man/man3/9pclient.3 b/man/man3/9pclient.3 new file mode 100644 index 0000000..1c7e76a --- /dev/null +++ b/man/man3/9pclient.3
@@ -0,0 +1,342 @@ +.TH 9PCLIENT 3 +.SH NAME +CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fswrite \- 9P client library +.SH SYNOPSIS +.B #include <u.h> +.PP +.B #include <libc.h> +.PP +.B #include <fcall.h> +.PP +.B #include <9pclient.h> +.PP +.ta +'\fLCFsys* 'u +.B +CFsys* fsmount(int fd, char *aname) +.PP +.B +CFsys* nsmount(char *name, char *aname) +.PP +.B +CFid* fsroot(CFsys *fsys) +.PP +.B +void fsunmount(CFsys *fsys) +.PP +.B +CFsys* fsinit(int fd) +.PP +.B +int fsversion(CFsys *fsys, int msize, char *version, int nversion) +.PP +.B +CFid *fsauth(CFsys *fsys, char *uname, char *aname) +.PP +.B +CFid *fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname) +.PP +.B +void fssetroot(CFsys *fsys, CFid *fid) +.PP +.B +void fsclose(CFid *fid) +.PP +.B +CFid *fscreate(CFsys *fs, char *path, int mode, ulong perm) +.PP +.B +CFid* fsopen(CFsys *fs, char *path, int mode) +.PP +.B +long fspread(CFid *fid, void *buf, long n, vlong offset) +.PP +.B +long fspwrite(CFid *fid, void *buf, long n, vlong offset) +.PP +.B +long fsread(CFid *fid, void *buf, long n) +.PP +.B +long fsreadn(CFid *fid, void *buf, long n) +.PP +.B +long fswrite(CFid *fid, void *buf, long n) +.PP +.B +long fsdirread(CFid *fid, Dir **d) +.PP +.B +long fsdirreadall(CFid *fid, Dir **d) +.PP +.B +Dir* fsdirstat(CFsys *fs, char *path) +.PP +.B +Dir* fsdirfstat(CFid *fid) +.PP +.B +int fsdirwstat(CFsys *fs, char *path, Dir *d) +.PP +.B +int fsdirfwstat(CFid *fid, Dir *d) +.PP +.B +int fsopenfd(CFsys *fs, char *path, int mode) +.SH DESCRIPTION +The +.I 9pclient +library helps client programs interact with 9P servers. +.PP +A +.B CFsys* +represents a connection to a 9P server. +A +.B CFid* +represents an active fid on some connection; +see +.IR intro (9p). +.PP +A new connection to a 9P server is typically established by +.I fsmount +or +.IR nsmount . +.I Fsmount +initializes a new 9P conversation on the open file descriptor +.IR fd ; +.I nsmount +connects to a service named +.I name +in the current name space directory +(see +.IR intro (4)). +Both attach to the root of the file system +using the attach name +.IR aname . +.I Fsroot +returns the +.B CFid* +corresponding to this root. +.PP +.IR Fsinit , +.IR fsversion , +.IR fsauth , +.IR fsattach , +and +.I fssetroot +provide more detailed control over the file system connection +than +.I fsmount +and +.IR nsmount . +.I Fsinit +allocates a new +.B CFsys* +corresponding to a 9P conversation on the file descriptor +.IR fd . +.I Fsversion +executes a +.IR version (9p) +transaction to establish +maximum message size and 9P version. +.I Fsauth +executes an +.IR auth (9p) +transaction, returning the new auth fid. +.RI ( Fsread +and +.I fswrite +can then be used to run the authentication protocol over the fid.) +.I Fsattach +executes an +.IR attach (9p) +transaction to connect to the root of a file tree served by the server. +It presents +.I afid +(which may be nil) +to establish identity. +.I Fssetroot +sets the root fid used by +.IR fsopen , +.IR fsopenfd , +.IR fsdirstat , +and +.IR fsdirwstat , +which evaluate rooted path names. +.PP +When a fid +is no longer needed, it should be clunked by calling +.I fsclose +and then considered freed. +Similarly, when the connection to the server is no longer needed, +it should be closed by calling +.IR fsunmount , +which will take care of calling +.I fsclose +on the current root fid. +Once all fids have been clunked +.I and +the connection has been closed +(the order is not important), +the allocated structures will be freed and the +file descriptor corresponding to the connection +will be closed +(see +.IR close (2)). +Fids are not reference counted: when +.I fsclose +is called, the clunk transaction and freeing of storage +happen immediately. +.PP +.I Fscreate +and +.I fsopen +establish new fids using the +.IR walk , +.I create +and +.I open +transactions +(see +.IR walk (9p) +and +.IR open (9p)). +The +.I path +argument is evaluated relative to the +.B CFsys +root +(see +.I fsroot +and +.I fssetroot +above). +The path is parsed as a slash-separated sequence of path elements, +as on Unix and Plan 9. +Elements that are empty or +dot +.B ( . ) +are ignored. +.PP +Once opened, these fids can be read and written using +.I fspread +and +.IR fspwrite , +which execute +.I read +and +.I write +transactions +(see +.IR read (9p)). +The library maintains an offset for each fid, +analagous to the offset maintained by the kernel for each open file descriptor. +.I Fsread +and +.I fswrite +read and write from this offset, and update it after successful calls. +Calling +.I fspread +or +.I fspwrite +with an +.I offset +of \-1 +is identical to calling +.I fsread +or +.IR fswrite . +.I Fsreadn +calls +.I fsread +repeatedly to obtain exactly +.I n +bytes of data, unless it encounters end-of-file or an error. +.PP +Reading an open a directory returns directory entries encoded as described in +.IR stat (9p). +.I Fsdirread +calls +.I fsread +and then parses the encoded entries into an array of +.B Dir* +data structures, +storing a pointer to the array in +.BI *d +and returning the number of entries. +.I Fsdirreadall +is similar but reads the entire directory. +The returned pointer should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +.I Fsdirfstat +and +.I fsdirfwstat +execute +.I stat +and +.I wstat +(see +.IR stat (9p)) +transactions. +The +.B Dir +structure returned by +.I fsdirfstat +should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +.I Fsdirstat +and +.I fsdirwstat +are similar to +.I fsdirfstat +and +.I fsdirfwstat +but operate on paths relative to the file system root +(see +.I fsopen +and +.I fscreate +above). +.PP +.I Fsopenfd +opens a file on the 9P server +for reading or writing but returns a Unix file descriptor +instead of a fid structure. +The file descriptor is actually one end of a +.IR pipe (2). +A proxy process on the other end is ferrying data +between the pipe and the 9P fid. +Because of the implementation as a pipe, +the only signal of a read or write error is the closing of the pipe. +The file descriptor remains valid even after the +.B CFsys +is unmounted. +.SH SOURCE +.B /usr/local/plan9/src/lib9pclient +.SH SEE ALSO +.IR intro (4), +.IR intro (9p) +.SH BUGS +The implementation +should use a special version string to distinguish between +servers that support +.IR openfd (9p) +and servers that do not. +.PP +The interface does not provide access to the +.IR walk (9p) +transaction, or to +.I open +and +.I create +on already-established fids. +.PP +There is no +.IR fsseek .
diff --git a/man/man3/9pcmdbuf.3 b/man/man3/9pcmdbuf.3 index d6a78b9..e961422 100644 --- a/man/man3/9pcmdbuf.3 +++ b/man/man3/9pcmdbuf.3
@@ -42,7 +42,9 @@ .I p (which need not be NUL-terminated) as a UTF string and splits it using -.IR tokenize (3). +.I tokenize +(see +.IR getfields (3)). It returns a .B Cmdbuf structure holding pointers to each field in the message.
diff --git a/man/man3/9pfile.3 b/man/man3/9pfile.3 index 083b655..1bb3038 100644 --- a/man/man3/9pfile.3 +++ b/man/man3/9pfile.3
@@ -94,7 +94,7 @@ .I dir are used to calculate the permission bits for the file as described in -.IR open (5). +.IR open (9p). It is permissible for .I name to be a slash-separated path rather than a single element. @@ -162,7 +162,7 @@ .PP Directories may be read, yielding a directory entry structure (see -.IR stat (5)) +.IR stat (9p)) for each file in the directory. In order to allow concurrent reading of directories, clients must obtain a
diff --git a/man/man3/INDEX b/man/man3/INDEX new file mode 100644 index 0000000..9c067d0 --- /dev/null +++ b/man/man3/INDEX
@@ -0,0 +1,1163 @@ +9p 9p.3 +Srv 9p.3 +dirread9p 9p.3 +emalloc9p 9p.3 +erealloc9p 9p.3 +estrdup9p 9p.3 +postfd 9p.3 +postmountsrv 9p.3 +readbuf 9p.3 +readstr 9p.3 +respond 9p.3 +srv 9p.3 +threadpostmountsrv 9p.3 +walkandclone 9p.3 +9pclient 9pclient.3 +CFid 9pclient.3 +CFsys 9pclient.3 +fsattach 9pclient.3 +fsauth 9pclient.3 +fsclose 9pclient.3 +fscreate 9pclient.3 +fsdirfstat 9pclient.3 +fsdirfwstat 9pclient.3 +fsdirread 9pclient.3 +fsdirreadall 9pclient.3 +fsdirstat 9pclient.3 +fsdirwstat 9pclient.3 +fsinit 9pclient.3 +fsmount 9pclient.3 +fsopen 9pclient.3 +fsopenfd 9pclient.3 +fspread 9pclient.3 +fspwrite 9pclient.3 +fsread 9pclient.3 +fsreadn 9pclient.3 +fsroot 9pclient.3 +fssetroot 9pclient.3 +fsunmount 9pclient.3 +fsversion 9pclient.3 +fswrite 9pclient.3 +nsmount 9pclient.3 +9pcmdbuf 9pcmdbuf.3 +Cmdbuf 9pcmdbuf.3 +lookupcmd 9pcmdbuf.3 +parsecmd 9pcmdbuf.3 +respondcmderror 9pcmdbuf.3 +9pfid 9pfid.3 +Fid 9pfid.3 +Fidpool 9pfid.3 +Req 9pfid.3 +Reqpool 9pfid.3 +allocfid 9pfid.3 +allocfidpool 9pfid.3 +allocreq 9pfid.3 +allocreqpool 9pfid.3 +closefid 9pfid.3 +closereq 9pfid.3 +freefidpool 9pfid.3 +freereqpool 9pfid.3 +lookupfid 9pfid.3 +lookupreq 9pfid.3 +removefid 9pfid.3 +removereq 9pfid.3 +9pfile 9pfile.3 +File 9pfile.3 +Tree 9pfile.3 +alloctree 9pfile.3 +closedirfile 9pfile.3 +closefile 9pfile.3 +createfile 9pfile.3 +freetree 9pfile.3 +hasperm 9pfile.3 +opendirfile 9pfile.3 +readdirfile 9pfile.3 +removefile 9pfile.3 +walkfile 9pfile.3 +Dx addpt.3 +Dy addpt.3 +Pt addpt.3 +Rect addpt.3 +Rpt addpt.3 +addpt addpt.3 +canonrect addpt.3 +combinerect addpt.3 +divpt addpt.3 +eqpt addpt.3 +eqrect addpt.3 +insetrect addpt.3 +mulpt addpt.3 +ptinrect addpt.3 +rectXrect addpt.3 +rectaddpt addpt.3 +rectclip addpt.3 +rectinrect addpt.3 +rectsubpt addpt.3 +subpt addpt.3 +aes aes.3 +aesCBCdecrypt aes.3 +aesCBCencrypt aes.3 +setupAESstate aes.3 +allocimage allocimage.3 +allocimagemix allocimage.3 +bytesperline allocimage.3 +cloadimage allocimage.3 +freeimage allocimage.3 +loadimage allocimage.3 +namedimage allocimage.3 +nameimage allocimage.3 +readimage allocimage.3 +setalpha allocimage.3 +unloadimage allocimage.3 +wordsperline allocimage.3 +writeimage allocimage.3 +ARGBEGIN arg.3 +ARGC arg.3 +ARGEND arg.3 +ARGF arg.3 +EARGF arg.3 +arg arg.3 +arginit arg.3 +argopt arg.3 +add3 arith3.3 +add4 arith3.3 +arith3 arith3.3 +closept3 arith3.3 +cross3 arith3.3 +dist3 arith3.3 +div3 arith3.3 +dot3 arith3.3 +eqpt3 arith3.3 +fff2p3 arith3.3 +len3 arith3.3 +lerp3 arith3.3 +midpt3 arith3.3 +mul3 arith3.3 +nearseg3 arith3.3 +neg3 arith3.3 +pdiv4 arith3.3 +pldist3 arith3.3 +pn2f3 arith3.3 +ppp2f3 arith3.3 +reflect3 arith3.3 +sub3 arith3.3 +sub4 arith3.3 +unit3 arith3.3 +vdiv3 arith3.3 +vrem3 arith3.3 +atof atof.3 +atoi atof.3 +atol atof.3 +atoll atof.3 +charstod atof.3 +strtod atof.3 +strtol atof.3 +strtoll atof.3 +strtoul atof.3 +strtoull atof.3 +bin bin.3 +binalloc bin.3 +binfree bin.3 +bingrow bin.3 +Bbuffered bio.3 +Bfdopen bio.3 +Bfildes bio.3 +Bflush bio.3 +Bgetc bio.3 +Bgetd bio.3 +Bgetrune bio.3 +Binit bio.3 +Binits bio.3 +Blinelen bio.3 +Boffset bio.3 +Bopen bio.3 +Bprint bio.3 +Bputc bio.3 +Bputrune bio.3 +Brdline bio.3 +Brdstr bio.3 +Bread bio.3 +Bseek bio.3 +Bterm bio.3 +Bungetc bio.3 +Bungetrune bio.3 +Bvprint bio.3 +Bwrite bio.3 +bio bio.3 +bfCBCdecrypt blowfish.3 +bfCBCencrypt blowfish.3 +bfECBdecrypt blowfish.3 +bfECBencrypt blowfish.3 +blowfish blowfish.3 +setupBFstate blowfish.3 +Font cachechars.3 +Fontchar cachechars.3 +Subfont cachechars.3 +agefont cachechars.3 +cachechars cachechars.3 +loadchar cachechars.3 +cleanname cleanname.3 +cmap2rgb color.3 +cmap2rgba color.3 +color color.3 +rgb2cmap color.3 +complete complete.3 +freecompletion complete.3 +cputime cputime.3 +times cputime.3 +asctime ctime.3 +ctime ctime.3 +gmtime ctime.3 +localtime ctime.3 +timezone ctime.3 +tm2sec ctime.3 + +block_cipher des.3 +des des.3 +des3CBCdecrypt des.3 +des3CBCencrypt des.3 +des3ECBdecrypt des.3 +des3ECBencrypt des.3 +des56to64 des.3 +des64to56 des.3 +desCBCdecrypt des.3 +desCBCencrypt des.3 +desECBdecrypt des.3 +desECBencrypt des.3 +des_key_setup des.3 +key_setup des.3 +setupDES3state des.3 +setupDESstate des.3 +triple_block_cipher des.3 +accept dial.3 +announce dial.3 +dial dial.3 +dialparse dial.3 +hangup dial.3 +listen dial.3 +netmkaddr dial.3 +reject dial.3 +dirread dirread.3 +dirreadall dirread.3 +Disk disk.3 +disk disk.3 +opendisk disk.3 +ARROW draw.3 +Image draw.3 +_string draw.3 +arc draw.3 +arcop draw.3 +bezier draw.3 +bezierop draw.3 +bezspline draw.3 +bezsplineop draw.3 +bezsplinepts draw.3 +border draw.3 +draw draw.3 +drawop draw.3 +drawrepl draw.3 +drawreplxy draw.3 +drawsetdebug draw.3 +ellipse draw.3 +ellipseop draw.3 +fillarc draw.3 +fillarcop draw.3 +fillbezier draw.3 +fillbezierop draw.3 +fillbezspline draw.3 +fillbezsplineop draw.3 +fillellipse draw.3 +fillellipseop draw.3 +fillpoly draw.3 +fillpolyop draw.3 +gendraw draw.3 +gendrawop draw.3 +icossin draw.3 +icossin2 draw.3 +line draw.3 +lineop draw.3 +poly draw.3 +polyop draw.3 +replclipr draw.3 +runestring draw.3 +runestringbg draw.3 +runestringbgop draw.3 +runestringn draw.3 +runestringnbg draw.3 +runestringnbgop draw.3 +runestringnop draw.3 +runestringop draw.3 +string draw.3 +stringbg draw.3 +stringbgop draw.3 +stringn draw.3 +stringnbg draw.3 +stringnbgop draw.3 +stringnop draw.3 +stringop draw.3 +dsa dsa.3 +dsagen dsa.3 +dsaprivalloc dsa.3 +dsaprivfree dsa.3 +dsaprivtopub dsa.3 +dsapuballoc dsa.3 +dsapubfree dsa.3 +dsasigalloc dsa.3 +dsasigfree dsa.3 +dsasign dsa.3 +dsaverify dsa.3 +dup dup.3 +egdecrypt elgamal.3 +egencrypt elgamal.3 +eggen elgamal.3 +egprivalloc elgamal.3 +egprivfree elgamal.3 +egprivtopub elgamal.3 +egpuballoc elgamal.3 +egpubfree elgamal.3 +egsigalloc elgamal.3 +egsigfree elgamal.3 +egsign elgamal.3 +egverify elgamal.3 +elgamal elgamal.3 +dec16 encode.3 +dec32 encode.3 +dec64 encode.3 +enc16 encode.3 +enc32 encode.3 +enc64 encode.3 +encode encode.3 +encodefmt encode.3 +errstr errstr.3 +rerrstr errstr.3 +werrstr errstr.3 +Event event.3 +Menu event.3 +Mouse event.3 +eatomouse event.3 +ecankbd event.3 +ecanmouse event.3 +ecanread event.3 +edrawgetrect event.3 +egetrect event.3 +einit event.3 +ekbd event.3 +emenuhit event.3 +emouse event.3 +emoveto event.3 +eread event.3 +ereadmouse event.3 +eresized event.3 +esetcursor event.3 +estart event.3 +estartfn event.3 +etimer event.3 +event event.3 +exec exec.3 +execl exec.3 +_exits exits.3 +atexit exits.3 +atexitdont exits.3 +exits exits.3 +terminate exits.3 +Fcall fcall.3 +convD2M fcall.3 +convM2D fcall.3 +convM2S fcall.3 +convS2M fcall.3 +dirfmt fcall.3 +dirmodefmt fcall.3 +fcall fcall.3 +fcallfmt fcall.3 +read9pmsg fcall.3 +sizeD2M fcall.3 +sizeS2M fcall.3 +statcheck fcall.3 +adler32 flate.3 +blockcrc flate.3 +deflate flate.3 +deflateblock flate.3 +deflateinit flate.3 +deflatezlib flate.3 +deflatezlibblock flate.3 +flate flate.3 +flateerr flate.3 +inflate flate.3 +inflateblock flate.3 +inflateinit flate.3 +inflatezlib flate.3 +inflatezlibblock flate.3 +mkcrctab flate.3 +dofmt fmtinstall.3 +dorfmt fmtinstall.3 +errfmt fmtinstall.3 +fmtfdflush fmtinstall.3 +fmtfdinit fmtinstall.3 +fmtinstall fmtinstall.3 +fmtprint fmtinstall.3 +fmtrune fmtinstall.3 +fmtrunestrcpy fmtinstall.3 +fmtstrcpy fmtinstall.3 +fmtstrflush fmtinstall.3 +fmtstrinit fmtinstall.3 +fmtvprint fmtinstall.3 +runefmtstrflush fmtinstall.3 +runefmtstrinit fmtinstall.3 +frame frame.3 +frcharofpt frame.3 +frclear frame.3 +frdelete frame.3 +frdrawsel frame.3 +frdrawsel0 frame.3 +frgetmouse frame.3 +frinit frame.3 +frinittick frame.3 +frinsert frame.3 +frptofchar frame.3 +frselect frame.3 +frselectpaint frame.3 +frsetrects frame.3 +frtick frame.3 +genrandom genrandom.3 +prng genrandom.3 +get9root get9root.3 +unsharp get9root.3 +getcallerpc getcallerpc.3 +getenv getenv.3 +putenv getenv.3 +getfields getfields.3 +gettokens getfields.3 +tokenize getfields.3 +getns getns.3 +getsnarf getsnarf.3 +putsnarf getsnarf.3 +getuser getuser.3 +sysname getuser.3 +getwd getwd.3 +Cursor graphics.3 +Display graphics.3 +Pfmt graphics.3 +Point graphics.3 +Rectangle graphics.3 +Rfmt graphics.3 +bufimage graphics.3 +buildfont graphics.3 +chantodepth graphics.3 +chantostr graphics.3 +closedisplay graphics.3 +cursorset graphics.3 +cursorswitch graphics.3 +drawerror graphics.3 +flushimage graphics.3 +freefont graphics.3 +gengetwindow graphics.3 +geninitdraw graphics.3 +getdefont graphics.3 +getwindow graphics.3 +graphics graphics.3 +initdisplay graphics.3 +initdraw graphics.3 +lockdisplay graphics.3 +openfont graphics.3 +strtochan graphics.3 +unlockdisplay graphics.3 +dimenkind html.3 +dimenspec html.3 +freedocinfo html.3 +freeitems html.3 +fromStr html.3 +html html.3 +parsehtml html.3 +printitems html.3 +targetid html.3 +targetname html.3 +toStr html.3 +validitems html.3 +Intmap intmap.3 +allocmap intmap.3 +caninsertkey intmap.3 +deletekey intmap.3 +freemap intmap.3 +insertkey intmap.3 +intmap intmap.3 +lookupkey intmap.3 +closeioproc ioproc.3 +iocall ioproc.3 +ioclose ioproc.3 +iodial ioproc.3 +iointerrupt ioproc.3 +ioopen ioproc.3 +ioproc ioproc.3 +ioread ioproc.3 +ioread9pmsg ioproc.3 +ioreadn ioproc.3 +iorecvfd ioproc.3 +iosendfd ioproc.3 +iosleep ioproc.3 +iowrite ioproc.3 +defmask ip.3 +eipfmt ip.3 +equivip ip.3 +hnputl ip.3 +hnputs ip.3 +hnputv ip.3 +ip ip.3 +isv4 ip.3 +maskip ip.3 +myetheraddr ip.3 +myipaddr ip.3 +nhgetl ip.3 +nhgets ip.3 +nhgetv ip.3 +parseether ip.3 +parseip ip.3 +parseipmask ip.3 +ptclbsum ip.3 +readipifc ip.3 +v4parsecidr ip.3 +v4parseip ip.3 +v4tov6 ip.3 +v6tov4 ip.3 +isalpharune isalpharune.3 +islowerrune isalpharune.3 +isspacerune isalpharune.3 +istitlerune isalpharune.3 +isupperrune isalpharune.3 +tolowerrune isalpharune.3 +totitlerune isalpharune.3 +toupperrune isalpharune.3 +closekeyboard keyboard.3 +ctlkeyboard keyboard.3 +initkeyboard keyboard.3 +keyboard keyboard.3 +canlock lock.3 +canqlock lock.3 +canrlock lock.3 +canwlock lock.3 +decref lock.3 +incref lock.3 +lock lock.3 +qlock lock.3 +qunlock lock.3 +rlock lock.3 +rsleep lock.3 +runlock lock.3 +rwakeup lock.3 +rwakeupall lock.3 +unlock lock.3 +wlock lock.3 +wunlock lock.3 +attachargs mach-cmd.3 +attachcore mach-cmd.3 +attachdynamic mach-cmd.3 +attachproc mach-cmd.3 +mach-cmd mach-cmd.3 +proctextfile mach-cmd.3 +crackhdr mach-file.3 +ctlproc mach-file.3 +detachproc mach-file.3 +mach-file mach-file.3 +mapfile mach-file.3 +mapproc mach-file.3 +procnotes mach-file.3 +uncrackhdr mach-file.3 +unmapfile mach-file.3 +unmapproc mach-file.3 +addrtoseg mach-map.3 +addrtosegafter mach-map.3 +addseg mach-map.3 +allocmap mach-map.3 +findseg mach-map.3 +fpformat mach-map.3 +freemap mach-map.3 +get1 mach-map.3 +get2 mach-map.3 +get4 mach-map.3 +get8 mach-map.3 +lget1 mach-map.3 +lget2 mach-map.3 +lget4 mach-map.3 +lget8 mach-map.3 +locaddr mach-map.3 +loccmp mach-map.3 +locconst mach-map.3 +loceval mach-map.3 +locfmt mach-map.3 +locindir mach-map.3 +locnone mach-map.3 +locreg mach-map.3 +locsimplify mach-map.3 +lput1 mach-map.3 +lput2 mach-map.3 +lput4 mach-map.3 +lput8 mach-map.3 +mach-map mach-map.3 +put1 mach-map.3 +put2 mach-map.3 +put4 mach-map.3 +put8 mach-map.3 +removeseg mach-map.3 +rget mach-map.3 +rput mach-map.3 +localaddr mach-stack.3 +mach-stack mach-stack.3 +stacktrace mach-stack.3 +unwindframe mach-stack.3 +windindex mach-stack.3 +windreglocs mach-stack.3 +beieeeftoa32 mach-swap.3 +beieeeftoa64 mach-swap.3 +beieeeftoa80 mach-swap.3 +beload2 mach-swap.3 +beload4 mach-swap.3 +beload8 mach-swap.3 +beswap2 mach-swap.3 +beswap4 mach-swap.3 +beswap8 mach-swap.3 +ieeeftoa32 mach-swap.3 +ieeeftoa64 mach-swap.3 +leieeeftoa32 mach-swap.3 +leieeeftoa64 mach-swap.3 +leieeeftoa80 mach-swap.3 +leload2 mach-swap.3 +leload4 mach-swap.3 +leload8 mach-swap.3 +leswap2 mach-swap.3 +leswap4 mach-swap.3 +leswap8 mach-swap.3 +mach-swap mach-swap.3 +ffindsym mach-symbol.3 +file2pc mach-symbol.3 +fileline mach-symbol.3 +findexsym mach-symbol.3 +findhdr mach-symbol.3 +findlsym mach-symbol.3 +findsym mach-symbol.3 +flookupsym mach-symbol.3 +fnbound mach-symbol.3 +indexlsym mach-symbol.3 +indexsym mach-symbol.3 +line2pc mach-symbol.3 +lookuplsym mach-symbol.3 +lookupsym mach-symbol.3 +mach-symbol mach-symbol.3 +pc2file mach-symbol.3 +pc2line mach-symbol.3 +symclose mach-symbol.3 +symoff mach-symbol.3 +symopen mach-symbol.3 +mach mach.3 +machbyname mach.3 +machbytype mach.3 +calloc malloc.3 +free malloc.3 +getmalloctag malloc.3 +getrealloctag malloc.3 +malloc malloc.3 +mallocz malloc.3 +realloc malloc.3 +setmalloctag malloc.3 +setrealloctag malloc.3 +adjoint matrix.3 +determinant matrix.3 +ident matrix.3 +invertmat matrix.3 +ixform matrix.3 +look matrix.3 +matmul matrix.3 +matmulr matrix.3 +matrix matrix.3 +move matrix.3 +persp matrix.3 +popmat matrix.3 +pushmat matrix.3 +qrot matrix.3 +rot matrix.3 +scale matrix.3 +viewport matrix.3 +xform matrix.3 +xformplane matrix.3 +xformpoint matrix.3 +xformpointd matrix.3 +Memdata memdraw.3 +Memdrawparam memdraw.3 +Memimage memdraw.3 +allocmemimage memdraw.3 +allocmemimaged memdraw.3 +allocmemsubfont memdraw.3 +byteaddr memdraw.3 +cloadmemimage memdraw.3 +creadmemimage memdraw.3 +drawclip memdraw.3 +freememimage memdraw.3 +freememsubfont memdraw.3 +getmemdefont memdraw.3 +hwdraw memdraw.3 +iprint memdraw.3 +loadmemimage memdraw.3 +memarc memdraw.3 +memdraw memdraw.3 +memellipse memdraw.3 +memfillcolor memdraw.3 +memfillpoly memdraw.3 +memimagedraw memdraw.3 +memimageinit memdraw.3 +memimageline memdraw.3 +memimagemove memdraw.3 +memimagestring memdraw.3 +memlinebbox memdraw.3 +memlineendsize memdraw.3 +mempoly memdraw.3 +memsetchan memdraw.3 +memsubfontwidth memdraw.3 +openmemsubfont memdraw.3 +readmemimage memdraw.3 +unloadmemimage memdraw.3 +wordaddr memdraw.3 +writememimage memdraw.3 +memdraw memlayer.3 +memlalloc memlayer.3 +memlayer memlayer.3 +memldelete memlayer.3 +memlexpose memlayer.3 +memlfree memlayer.3 +memlhide memlayer.3 +memline memlayer.3 +memlnorefresh memlayer.3 +memload memlayer.3 +memlorigin memlayer.3 +memlsetrefresh memlayer.3 +memltofront memlayer.3 +memltofrontn memlayer.3 +memltorear memlayer.3 +memltorearn memlayer.3 +memunload memlayer.3 +memccpy memory.3 +memchr memory.3 +memcmp memory.3 +memcpy memory.3 +memmove memory.3 +memory memory.3 +memset memory.3 +closemouse mouse.3 +cursorswitch mouse.3 +drawgetrect mouse.3 +getrect mouse.3 +initmouse mouse.3 +menuhit mouse.3 +mouse mouse.3 +moveto mouse.3 +readmouse mouse.3 +setcursor mouse.3 +mousescrollsize mousescrollsize.3 +betomp mp.3 +crtin mp.3 +crtout mp.3 +crtpre mp.3 +crtprefree mp.3 +crtresfree mp.3 +itomp mp.3 +letomp mp.3 +mp mp.3 +mpadd mp.3 +mpassign mp.3 +mpbits mp.3 +mpcmp mp.3 +mpcopy mp.3 +mpdigdiv mp.3 +mpdiv mp.3 +mpexp mp.3 +mpextendedgcd mp.3 +mpfactorial mp.3 +mpfmt mp.3 +mpfree mp.3 +mpinvert mp.3 +mpleft mp.3 +mplowbits0 mp.3 +mpmagadd mp.3 +mpmagcmp mp.3 +mpmagsub mp.3 +mpmod mp.3 +mpmul mp.3 +mpnew mp.3 +mpnorm mp.3 +mprand mp.3 +mpright mp.3 +mpsetminbits mp.3 +mpsignif mp.3 +mpsub mp.3 +mptoa mp.3 +mptobe mp.3 +mptoi mp.3 +mptole mp.3 +mptoui mp.3 +mptouv mp.3 +mptov mp.3 +mpvecadd mp.3 +mpveccmp mp.3 +mpvecdigmuladd mp.3 +mpvecdigmulsub mp.3 +mpvecmul mp.3 +mpvecsub mp.3 +strtomp mp.3 +uitomp mp.3 +uvtomp mp.3 +vtomp mp.3 +muldiv muldiv.3 +umuldiv muldiv.3 +Mux mux.3 +mux mux.3 +muxinit mux.3 +muxrpc mux.3 +muxthreads mux.3 +Inf nan.3 +NaN nan.3 +isInf nan.3 +isNaN nan.3 +nan nan.3 +needstack needstack.3 +atnotify notify.3 +noted notify.3 +notedisable notify.3 +noteenable notify.3 +notify notify.3 +notifyoff notify.3 +notifyon notify.3 +close open.3 +create open.3 +open open.3 +opentemp opentemp.3 +pipe pipe.3 +Plumbmsg plumb.3 +eplumb plumb.3 +plumb plumb.3 +plumbaddattr plumb.3 +plumbdelattr plumb.3 +plumbfree plumb.3 +plumblookup plumb.3 +plumbopen plumb.3 +plumbopenfid plumb.3 +plumbpack plumb.3 +plumbpackattr plumb.3 +plumbrecv plumb.3 +plumbrecvfid plumb.3 +plumbsend plumb.3 +plumbsendtext plumb.3 +plumbsendtofid plumb.3 +plumbunpack plumb.3 +plumbunpackattr plumb.3 +plumbunpackpartial plumb.3 +post9pservice post9pservice.3 +postnote postnote.3 +DSAprimes prime.3 +genprime prime.3 +gensafeprime prime.3 +genstrongprime prime.3 +prime prime.3 +probably_prime prime.3 +smallprimetest prime.3 +fprint print.3 +print print.3 +runeseprint print.3 +runesmprint print.3 +runesnprint print.3 +runesprint print.3 +runevseprint print.3 +runevsmprint print.3 +runevsnprint print.3 +seprint print.3 +smprint print.3 +snprint print.3 +sprint print.3 +vfprint print.3 +vseprint print.3 +vsmprint print.3 +vsnprint print.3 +proto proto.3 +rdproto proto.3 +freeThumbprints pushtls.3 +initThumbprints pushtls.3 +okThumbprint pushtls.3 +pushtls pushtls.3 +readcert pushtls.3 +readcertchain pushtls.3 +tlsClient pushtls.3 +tlsServer pushtls.3 +qball qball.3 +mtoq quaternion.3 +qadd quaternion.3 +qdiv quaternion.3 +qinv quaternion.3 +qlen quaternion.3 +qmid quaternion.3 +qmul quaternion.3 +qneg quaternion.3 +qsqrt quaternion.3 +qsub quaternion.3 +qtom quaternion.3 +quaternion quaternion.3 +qunit quaternion.3 +slerp quaternion.3 +doquote quote.3 +needsrcquote quote.3 +quote quote.3 +quotefmtinstall quote.3 +quoterunestrdup quote.3 +quoterunestrfmt quote.3 +quotestrdup quote.3 +quotestrfmt quote.3 +unquoterunestrdup quote.3 +unquotestrdup quote.3 +fastrand rand.3 +frand rand.3 +lnrand rand.3 +lrand rand.3 +nfastrand rand.3 +nrand rand.3 +ntruerand rand.3 +rand rand.3 +srand rand.3 +truerand rand.3 +rc4 rc4.3 +rc4back rc4.3 +rc4skip rc4.3 +setupRC4state rc4.3 +pread read.3 +pwrite read.3 +read read.3 +readn read.3 +write read.3 +RGB readcolmap.3 +readcolmap readcolmap.3 +writecolmap readcolmap.3 +regcomp regexp.3 +regcomplit regexp.3 +regcompnl regexp.3 +regerror regexp.3 +regexec regexp.3 +regexp regexp.3 +regsub regexp.3 +rregexec regexp.3 +rregsub regexp.3 +regcomp regexp9.3 +regcomplit regexp9.3 +regcompnl regexp9.3 +regerror regexp9.3 +regexec regexp9.3 +regexp9 regexp9.3 +regsub regexp9.3 +rregexec regexp9.3 +rregsub regexp9.3 +rfork rfork.3 + +X509dump rsa.3 +X509gen rsa.3 +X509req rsa.3 +X509toRSApub rsa.3 +X509verify rsa.3 +asn1dump rsa.3 +asn1toRSApriv rsa.3 +decodepem rsa.3 +decodepemchain rsa.3 +rsa rsa.3 +rsadecrypt rsa.3 +rsaencrypt rsa.3 +rsafill rsa.3 +rsagen rsa.3 +rsaprivalloc rsa.3 +rsaprivfree rsa.3 +rsaprivtopub rsa.3 +rsapuballoc rsa.3 +rsapubfree rsa.3 +chartorune rune.3 +fullrune rune.3 +rune rune.3 +runelen rune.3 +runenlen rune.3 +runetochar rune.3 +utfecpy rune.3 +utflen rune.3 +utfnlen rune.3 +utfrrune rune.3 +utfrune rune.3 +utfutf rune.3 +runestrcat runestrcat.3 +runestrchr runestrcat.3 +runestrcmp runestrcat.3 +runestrcpy runestrcat.3 +runestrdup runestrcat.3 +runestrecpy runestrcat.3 +runestrlen runestrcat.3 +runestrncat runestrcat.3 +runestrncmp runestrcat.3 +runestrncpy runestrcat.3 +runestrrchr runestrcat.3 +runestrstr runestrcat.3 +openscsi scsi.3 +scsi scsi.3 +scsicmd scsi.3 +scsierror scsi.3 +scsiready scsi.3 +hmac_md5 sechash.3 +hmac_sha1 sechash.3 +md4 sechash.3 +md5 sechash.3 +md5pickle sechash.3 +md5unpickle sechash.3 +sechash sechash.3 +sha1 sechash.3 +sha1pickle sechash.3 +sha1unpickle sechash.3 +seek seek.3 +recvfd sendfd.3 +sendfd sendfd.3 +longjmp setjmp.3 +notejmp setjmp.3 +setjmp setjmp.3 +alarm sleep.3 +sleep sleep.3 +dirfstat stat.3 +dirfwstat stat.3 +dirstat stat.3 +dirwstat stat.3 +fstat stat.3 +fwstat stat.3 +nulldir stat.3 +stat stat.3 +wstat stat.3 +cistrcmp strcat.3 +cistrncmp strcat.3 +cistrstr strcat.3 +strcat strcat.3 +strchr strcat.3 +strcmp strcat.3 +strcpy strcat.3 +strcspn strcat.3 +strdup strcat.3 +strecpy strcat.3 +strlen strcat.3 +strncat strcat.3 +strncmp strcat.3 +strncpy strcat.3 +strpbrk strcat.3 +strrchr strcat.3 +strspn strcat.3 +strstr strcat.3 +strtok strcat.3 +s_alloc string.3 +s_allocinstack string.3 +s_append string.3 +s_array string.3 +s_copy string.3 +s_error string.3 +s_free string.3 +s_freeinstack string.3 +s_getline string.3 +s_grow string.3 +s_incref string.3 +s_memappend string.3 +s_nappend string.3 +s_new string.3 +s_newalloc string.3 +s_parse string.3 +s_putc string.3 +s_rdinstack string.3 +s_read string.3 +s_read_line string.3 +s_reset string.3 +s_restart string.3 +s_terminate string.3 +s_tolower string.3 +s_unique string.3 +string string.3 +runestringnwidth stringsize.3 +runestringsize stringsize.3 +runestringwidth stringsize.3 +stringnwidth stringsize.3 +stringsize stringsize.3 +stringwidth stringsize.3 +allocsubfont subfont.3 +freesubfont subfont.3 +installsubfont subfont.3 +lookupsubfont subfont.3 +mkfont subfont.3 +readsubfont subfont.3 +readsubfonti subfont.3 +stringsubfont subfont.3 +strsubfontwidth subfont.3 +subfont subfont.3 +subfontname subfont.3 +uninstallsubfont subfont.3 +writesubfont subfont.3 +sysfatal sysfatal.3 +alt thread.3 +chancreate thread.3 +chanfree thread.3 +chaninit thread.3 +chanprint thread.3 +chansetname thread.3 +mainstacksize thread.3 +nbrecv thread.3 +nbrecvp thread.3 +nbrecvul thread.3 +nbsend thread.3 +nbsendp thread.3 +nbsendul thread.3 +proccreate thread.3 +procdata thread.3 +recv thread.3 +recvp thread.3 +recvul thread.3 +send thread.3 +sendp thread.3 +sendul thread.3 +thread thread.3 +threadcreate thread.3 +threaddata thread.3 +threadexec thread.3 +threadexecl thread.3 +threadexits thread.3 +threadexitsall thread.3 +threadgetgrp thread.3 +threadgetname thread.3 +threadid thread.3 +threadint thread.3 +threadintgrp thread.3 +threadkill thread.3 +threadkillgrp thread.3 +threadlinklibrary thread.3 +threadmain thread.3 +threadnotify thread.3 +threadpid thread.3 +threadsetgrp thread.3 +threadsetname thread.3 +threadsetstate thread.3 +threadspawn thread.3 +threadwaitchan thread.3 +yield thread.3 +nsec time.3 +time time.3 +udpread udpread.3 +udpwrite udpread.3 +await wait.3 +awaitfor wait.3 +awaitnohang wait.3 +wait wait.3 +waitfor wait.3 +waitnohang wait.3 +waitpid wait.3 +drawresizewindow wctl.3 +drawsetlabel wctl.3 +drawtopwindow wctl.3 +wctl wctl.3 +Screen window.3 +allocscreen window.3 +allocwindow window.3 +bottomnwindows window.3 +bottomwindow window.3 +freescreen window.3 +originwindow window.3 +publicscreen window.3 +topnwindows window.3 +topwindow window.3 +window window.3
diff --git a/man/man3/abs.3 b/man/man3/abs.3 deleted file mode 100644 index 46dbd92..0000000 --- a/man/man3/abs.3 +++ /dev/null
@@ -1,33 +0,0 @@ -.TH ABS 3 -.SH NAME -abs, labs \- integer absolute values -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.PP -.B -int abs(int a) -.PP -.B -long labs(long a) -.SH DESCRIPTION -.I Abs -returns -the absolute value of integer -.IR a , -and -.I labs -does the same for a long. -.SH SOURCE -.B /usr/local/plan9/src/libc/port/abs.c -.SH SEE ALSO -.IR floor (3) -for -.I fabs -.SH DIAGNOSTICS -.I Abs -and -.I labs -return -the most negative integer or long when the true result is unrepresentable.
diff --git a/man/man3/allocimage.3 b/man/man3/allocimage.3 index 26365dc..e9da53a 100644 --- a/man/man3/allocimage.3 +++ b/man/man3/allocimage.3
@@ -148,7 +148,7 @@ field will be set to the number of bits per pixel specified by the channel descriptor (see -.IR image (6)). +.IR image (7)). .I Allocimage returns 0 if the server has run out of image memory. .PP @@ -214,7 +214,7 @@ There is a fixed format for the exchange and storage of image data (see -.IR image (6)). +.IR image (7)). .PP .I Unloadimage reads a rectangle of pixels from image @@ -271,7 +271,7 @@ bytes of compressed image .I data (see -.IR image (6)). +.IR image (7)). On each call to .IR cloadimage, the @@ -289,7 +289,7 @@ .PP .I Readimage creates an image from data contained in an external file (see -.IR image (6) +.IR image (7) for the file format); .I fd is a file descriptor obtained by opening such a file for reading. @@ -336,7 +336,7 @@ .IR graphics (3), .IR draw (3), .IR draw (3), -.IR image (6) +.IR image (7) .SH DIAGNOSTICS These functions return pointer 0 or integer \-1 on failure, usually due to insufficient memory.
diff --git a/man/man3/arg.3 b/man/man3/arg.3 index 35e5914..6f7bb92 100644 --- a/man/man3/arg.3 +++ b/man/man3/arg.3
@@ -121,4 +121,4 @@ prog -b -f(file1) badflag('r') -f(file2) 2 args: 'arg1' 'arg2' .PP .SH SOURCE -.B /sys/include/libc.h +.B /usr/local/plan9/include/libc.h
diff --git a/man/man3/arith3.3 b/man/man3/arith3.3 new file mode 100644 index 0000000..faba4aa --- /dev/null +++ b/man/man3/arith3.3
@@ -0,0 +1,269 @@ +.TH ARITH3 3 +.SH NAME +add3, sub3, neg3, div3, mul3, eqpt3, closept3, dot3, cross3, len3, dist3, unit3, midpt3, lerp3, reflect3, nearseg3, pldist3, vdiv3, vrem3, pn2f3, ppp2f3, fff2p3, pdiv4, add4, sub4 \- operations on 3-d points and planes +.SH SYNOPSIS +.PP +.B +#include <draw.h> +.PP +.B +#include <geometry.h> +.PP +.B +Point3 add3(Point3 a, Point3 b) +.PP +.B +Point3 sub3(Point3 a, Point3 b) +.PP +.B +Point3 neg3(Point3 a) +.PP +.B +Point3 div3(Point3 a, double b) +.PP +.B +Point3 mul3(Point3 a, double b) +.PP +.B +int eqpt3(Point3 p, Point3 q) +.PP +.B +int closept3(Point3 p, Point3 q, double eps) +.PP +.B +double dot3(Point3 p, Point3 q) +.PP +.B +Point3 cross3(Point3 p, Point3 q) +.PP +.B +double len3(Point3 p) +.PP +.B +double dist3(Point3 p, Point3 q) +.PP +.B +Point3 unit3(Point3 p) +.PP +.B +Point3 midpt3(Point3 p, Point3 q) +.PP +.B +Point3 lerp3(Point3 p, Point3 q, double alpha) +.PP +.B +Point3 reflect3(Point3 p, Point3 p0, Point3 p1) +.PP +.B +Point3 nearseg3(Point3 p0, Point3 p1, Point3 testp) +.PP +.B +double pldist3(Point3 p, Point3 p0, Point3 p1) +.PP +.B +double vdiv3(Point3 a, Point3 b) +.PP +.B +Point3 vrem3(Point3 a, Point3 b) +.PP +.B +Point3 pn2f3(Point3 p, Point3 n) +.PP +.B +Point3 ppp2f3(Point3 p0, Point3 p1, Point3 p2) +.PP +.B +Point3 fff2p3(Point3 f0, Point3 f1, Point3 f2) +.PP +.B +Point3 pdiv4(Point3 a) +.PP +.B +Point3 add4(Point3 a, Point3 b) +.PP +.B +Point3 sub4(Point3 a, Point3 b) +.SH DESCRIPTION +These routines do arithmetic on points and planes in affine or projective 3-space. +Type +.B Point3 +is +.IP +.EX +.ta 6n +typedef struct Point3 Point3; +struct Point3{ + double x, y, z, w; +}; +.EE +.PP +Routines whose names end in +.B 3 +operate on vectors or ordinary points in affine 3-space, represented by their Euclidean +.B (x,y,z) +coordinates. +(They assume +.B w=1 +in their arguments, and set +.B w=1 +in their results.) +.TF reflect3 +.TP +Name +Description +.TP +.B add3 +Add the coordinates of two points. +.TP +.B sub3 +Subtract coordinates of two points. +.TP +.B neg3 +Negate the coordinates of a point. +.TP +.B mul3 +Multiply coordinates by a scalar. +.TP +.B div3 +Divide coordinates by a scalar. +.TP +.B eqpt3 +Test two points for exact equality. +.TP +.B closept3 +Is the distance between two points smaller than +.IR eps ? +.TP +.B dot3 +Dot product. +.TP +.B cross3 +Cross product. +.TP +.B len3 +Distance to the origin. +.TP +.B dist3 +Distance between two points. +.TP +.B unit3 +A unit vector parallel to +.IR p . +.TP +.B midpt3 +The midpoint of line segment +.IR pq . +.TP +.B lerp3 +Linear interpolation between +.I p +and +.IR q . +.TP +.B reflect3 +The reflection of point +.I p +in the segment joining +.I p0 +and +.IR p1 . +.TP +.B nearseg3 +The closest point to +.I testp +on segment +.IR "p0 p1" . +.TP +.B pldist3 +The distance from +.I p +to segment +.IR "p0 p1" . +.TP +.B vdiv3 +Vector divide \(em the length of the component of +.I a +parallel to +.IR b , +in units of the length of +.IR b . +.TP +.B vrem3 +Vector remainder \(em the component of +.I a +perpendicular to +.IR b . +Ignoring roundoff, we have +.BR "eqpt3(add3(mul3(b, vdiv3(a, b)), vrem3(a, b)), a)" . +.PD +.PP +The following routines convert amongst various representations of points +and planes. Planes are represented identically to points, by duality; +a point +.B p +is on a plane +.B q +whenever +.BR p.x*q.x+p.y*q.y+p.z*q.z+p.w*q.w=0 . +Although when dealing with affine points we assume +.BR p.w=1 , +we can't make the same assumption for planes. +The names of these routines are extra-cryptic. They contain an +.B f +(for `face') to indicate a plane, +.B p +for a point and +.B n +for a normal vector. +The number +.B 2 +abbreviates the word `to.' +The number +.B 3 +reminds us, as before, that we're dealing with affine points. +Thus +.B pn2f3 +takes a point and a normal vector and returns the corresponding plane. +.TF reflect3 +.TP +Name +Description +.TP +.B pn2f3 +Compute the plane passing through +.I p +with normal +.IR n . +.TP +.B ppp2f3 +Compute the plane passing through three points. +.TP +.B fff2p3 +Compute the intersection point of three planes. +.PD +.PP +The names of the following routines end in +.B 4 +because they operate on points in projective 4-space, +represented by their homogeneous coordinates. +.TP +pdiv4 +Perspective division. Divide +.B p.w +into +.IR p 's +coordinates, converting to affine coordinates. +If +.B p.w +is zero, the result is the same as the argument. +.TP +add4 +Add the coordinates of two points. +.PD +.TP +sub4 +Subtract the coordinates of two points. +.SH SOURCE +.B /usr/local/plan9/src/libgeometry +.SH "SEE ALSO +.IR matrix (3)
diff --git a/man/man3/atof.3 b/man/man3/atof.3 index f242036..f8d7c60 100644 --- a/man/man3/atof.3 +++ b/man/man3/atof.3
@@ -127,7 +127,7 @@ after calling .IR charstod . .SH SOURCE -.B /usr/local/plan9/src/libc/port +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR fscanf (3) .SH DIAGNOSTICS
diff --git a/man/man3/auth.3 b/man/man3/auth.3 deleted file mode 100644 index 1fe81f9..0000000 --- a/man/man3/auth.3 +++ /dev/null
@@ -1,395 +0,0 @@ -.TH AUTH 3 -.SH NAME -amount, newns, addns, login, noworld, auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc, auth_rpc, auth_getkey, amount_getkey, auth_freeAI, auth_chuid, auth_challenge, auth_response, auth_freechal, auth_respond, auth_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users -.SH SYNOPSIS -.nf -.PP -.ft L -#include <u.h> -#include <libc.h> -#include <auth.h> -.fi -.ta 11n +4n +4n +4n +4n +4n +4n -.PP -.B -int newns(char *user, char *nsfile); -.PP -.B -int addns(char *user, char *nsfile); -.PP -.B -int amount(int fd, char *old, int flag, char *aname); -.PP -.B -int login(char *user, char *password, char *namespace); -.PP -.B -int noworld(char *user); -.PP -.B -AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...); -.PP -.B -AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey, -.br -.B char *params); -.PP -.B -AuthRpc* auth_allocrpc(int afd); -.PP -.B -void auth_freerpc(AuthRpc *rpc); -.PP -.B -uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n); -.PP -.B -int auth_getkey(char *proto, char *dom); -.PP -.B -int (*amount_getkey)(char*, char*); -.PP -.B -void auth_freeAI(AuthInfo *ai); -.PP -.B -int auth_chuid(AuthInfo *ai, char *ns); -.PP -.B -Chalstate* auth_challenge(char *fmt, ...); -.PP -.B -AuthInfo* auth_response(Chalstate*); -.PP -.B -void auth_freechal(Chalstate*); -.PP -.B -int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...); -.PP -.B -AuthInfo* auth_userpasswd(char*user, char*password); -.PP -.B -UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...); -.PP -.B -AuthInfo* auth_getinfo(int fd); -.SH DESCRIPTION -.PP -This library, in concert with -.IR factotum (4), -is used to authenticate users. -It provides the primary interface to -.IR factotum . -.PP -.I Newns -builds a name space for -.IR user . -It opens the file -.I nsfile -.RB ( /lib/namespace -is used if -.I nsfile -is null), -copies the old environment, erases the current name space, -sets the environment variables -.B user -and -.BR home , -and interprets the commands in -.IR nsfile . -The format of -.I nsfile -is described in -.IR namespace (6). -.PP -.I Addns -also interprets and executes the commands in -.IR nsfile . -Unlike -.I newns -it applies the command to the current name space -rather than starting from scratch. -.PP -.I Amount -is like -.I mount -but performs any authentication required. -It should be used instead of -.I mount -whenever the file server being mounted requires authentication. -See -.IR bind (3) -for a definition of the arguments to -.I mount -and -.IR amount . -.PP -.I Login -changes the user id of the process -.I user -and recreates the namespace using the file -.I namespace -(default -.BR /lib/nnamespace ). -It uses -.I auth_userpassword -and -.IR auth_chuid . -.PP -.I Noworld -returns 1 if the user is in the group -.B noworld -in -.BR /adm/users . -Otherwise, it returns 0. -.I Noworld -is used by telnetd and ftpd to provide sandboxed -access for some users. -.PP -The following routines use the -.B AuthInfo -structure returned after a successful authentication by -.IR factotum (4). -.PP -.ne 8 -.EX -.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n -typedef struct -{ - char *cuid; /* caller id */ - char *suid; /* server id */ - char *cap; /* capability */ - int nsecret; /* length of secret */ - uchar *secret; /* secret */ -} AuthInfo; -.EE -.sp -The fields -.B cuid -and -.B suid -point to the authenticated ids of the client and server. -.B Cap -is a capability returned only to the server. -It can be passed to the -.IR cap (3) -device to change the user id of the process. -.B Secret -is an -.BR nsecret -byte -shared secret that can be used by the client and server to -create encryption and hashing keys for the rest of the -conversation. -.PP -.I Auth_proxy -proxies an authentication conversation between a remote -server reading and writing -.I fd -and a -.I factotum -file. The -.I factotum -file used is -.BR /mnt/factotum/rpc . -An -.B sprint -(see -.IR print (3)) -of -.I fmt -and the variable arg list yields a key template (see -.IR factotum (4)) -specifying the key to use. -The template must specify at least the protocol ( -.BI proto= xxx ) -and the role (either -.B role=client -or -.BR role=server ). -.I Auth_proxy -either returns an allocated -.B AuthInfo -structure, or sets the error string and -returns nil. -.PP -.I Fauth_proxy -can be used instead of -.I auth_proxy -if a single connection to -.I factotum -will be used for multiple authentications. -This is necessary, for example, for -.I newns -which must open the -.I factotum -file before wiping out the namespace. -.I Fauth_proxy -takes as an argument a pointer to an -.B AuthRPC -structure which contains an fd for an open connection to -.I factotum -in addition to storage and state information for -the protocol. -An -.B AuthRPC -structure is obtained by calling -.I auth_allocrpc -with the fd of an open -.I factotum -connection. -It is freed using -.IR auth_freerpc . -Individual commands can be sent to -.IR factotum (4) -by invoking -.IR auth_rpc . -.PP -Both -.I auth_proxy -and -.I fauth_proxy -take a pointer to a routine, -.IR getkey , -to invoke should -.I factotum -not posess a key for the authentication. If -.I getkey -is nil, the authentication fails. -.I Getkey -is called with a key template for the desired -key. -We have provided a generic routine, -.IR auth_getkey , -which queries the user for -the key information and passes it to -.IR factotum . -This is the default for the global variable, -.IR amount_getkey , -which holds a pointer to the key prompting routine used by -.IR amount . -.PP -.I Auth_chuid -uses the -.B cuid -and -.B cap -fields of an -.B AuthInfo -structure to change the user id of the current -process and uses -.IR ns , -default -.BR /lib/namespace , -to build it a new name space. -.PP -.I Auth_challenge -and -.I auth_response -perform challenge/response protocols with -.IR factotum . -State between the challenge and response phase are -kept in the -.B Chalstate -structure: -.sp -.EX -struct Chalstate -{ - char *user; - char chal[MAXCHLEN]; - int nchal; - void *resp; - int nresp; - -/* for implementation only */ - int afd; - AuthRpc *rpc; - char userbuf[MAXNAMELEN]; - int userinchal; -}; -.EE -.sp -.I Auth_challenge -requires a key template generated by an -.B sprint -of -.I fmt -and the variable arguments. It must contain the protocol -(\fBproto=\fIxxx\fR) -and depending on the protocol, the user name ( -.BI user= xxx \fR).\fP -.B P9cr -and -.B vnc -expect the user specified as an attribute in -the key template and -.BR apop , -.BR cram , -and -.BR chap -expect it in the -.B user -field of the arg to -.IR auth_response . -For all protocols, the response is returned -to -.I auth_response -in the -.I resp -field of the -.BR Chalstate . -.I Chalstate.nresp -must be the length of the response. -.PP -Supply to -.I auth_respond -a challenge string and the fmt and args specifying a key, -and it will use -.I factotum -to return the proper user and response. -.PP -.I Auth_userpasswd -verifies a simple user/password pair. -.I Auth_getuserpasswd -retrieves a user/password pair from -.I factotum -if permitted. -.PP -.I Auth_getinfo -reads an -.B AuthInfo -message from -.I fd -and converts it into a structure. It is only -used by the other routines in this library when -communicating with -.IR factotum . -.PP -.ne 8 -.EX -.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n -typedef struct UserPasswd { - char *user; - char *passwd; -} UserPasswd; -.EE -.sp -.PP -.I Auth_freeAI -is used to free an -.B AuthInfo -structure returned by one of these routines. -Similary -.I auth_freechal -frees a challenge/response state. -.SH SOURCE -.B /usr/local/plan9/src/libauth -.SH SEE ALSO -.IR factotum (4), -.IR authsrv (3), -.IR bind (3) -.SH DIAGNOSTICS -These routines set -.IR errstr .
diff --git a/man/man3/authsrv.3 b/man/man3/authsrv.3 deleted file mode 100644 index c8f3330..0000000 --- a/man/man3/authsrv.3 +++ /dev/null
@@ -1,223 +0,0 @@ -.TH AUTHSRV 3 -.SH NAME -authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp \- routines for communicating with authentication servers -.SH SYNOPSIS -.nf -.PP -.ft L -#include <u.h> -#include <libc.h> -#include <authsrv.h> -.fi -.ta 8n +4n +4n +4n +4n +4n +4n -.PP -.B -int authdial(char *netroot, char *ad); -.PP -.B -int passtokey(char key[DESKEYLEN], char *password) -.PP -.B -uchar nvcsum(void *mem, int len) -.PP -.B -int readnvram(Nvrsafe *nv, int flag); -.PPP -.B -int convT2M(Ticket *t, char *msg, char *key) -.PP -.B -void convM2T(char *msg, Ticket *t, char *key) -.PP -.B -int convA2M(Authenticator *a, char *msg, char *key) -.PP -.B -void convM2A(char *msg, Authenticator *a, char *key) -.PP -.B -int convTR2M(Ticketreq *tr, char *msg) -.PP -.B -void convM2TR(char *msg, Ticketreq *tr) -.PP -.B -int convPR2M(Passwordreq *pr, char *msg, char *key) -.PP -.B -void convM2PR(char *msg, Passwordreq *pr, char *key) -.PP -.B -int _asgetticket(int fd, char *trbuf, char *tbuf); -.PP -.B -int _asrdresp(int fd, char *buf, int len); -.SH DESCRIPTION -.PP -.I Authdial -dials an authentication server over the -network rooted at -.IR net , -default -.BR /net . -The authentication domain, -.IR ad , -specifies which server to call. -If -.I ad -is non-nil, -the connection server -.B cs -(see -.IR ndb (8)) -is queried for an entry which contains -.B authdom=\fIad\fP -or -.BR dom=\fIad\fP , -the former having precedence, -and which also contains an -.B auth -attribute. -The string dialed is then -.I netroot\fP!\fIserver\fP!ticket -where -.I server -is the value of the -.B auth -attribute. -If no entry is found, the error string is -set to ``no authentication server found'' -and -1 is returned. -If -.I authdom -is nil, the string -.IB netroot !$auth! ticket -is used to make the call. -.PP -.I Passtokey -converts -.I password -into a DES key and stores the result in -.IR key . -It returns 0 if -.I password -could not be converted, -and 1 otherwise. -.PP -.I Readnvram -reads authentication information into the structure: -.EX -.ta 4n +4n +8n +4n +4n +4n +4n - struct Nvrsafe - { - char machkey[DESKEYLEN]; - uchar machsum; - char authkey[DESKEYLEN]; - uchar authsum; - char config[CONFIGLEN]; - uchar configsum; - char authid[ANAMELEN]; - uchar authidsum; - char authdom[DOMLEN]; - uchar authdomsum; - }; -.EE -.PP -On Sparc, MIPS, and SGI machines this information is -in non-volatile ram, accessible in the file -.BR #r/nvram . -On x86s and Alphas -.I readnvram -successively opens the following areas stopping with the -first to succeed: -.PP -\- the partition named by the -.B $nvram -environment variable -(commonly set via -.IR plan9.ini (8)) -.br -\- the partition -.B #S/sdC0/nvram -.br -\- a file called -.B plan9.nvr -in the partition -.B #S/sdC0/9fat -.br -\- the partition -.B #S/sd00/nvram -.br -\- a file called -.B plan9.nvr -in the partition -.B #S/sd00/9fat -.br -\- a file called -.B plan9.nvr -on a DOS floppy in drive 0 -.br -\- a file called -.B plan9.nvr -on a DOS floppy in drive 1 -.PP -The -.IR nvcsum s -of the fields -.BR machkey , -.BR authid , -and -.B authdom -must match their respective checksum or that field is zeroed. -If -.I flag -is -.B NVwrite -or at least one checksum fails and -.I flag -is -.BR NVwriteonerr , -.I readnvram -will prompt for new values on -.B #c/cons -and then write them back to the storage area. -.PP -.IR ConvT2M , -.IR convA2M , -.IR convTR2M , -and -.I convPR2M -convert tickets, authenticators, ticket requests, and password change request -structures into transmittable messages. -.IR ConvM2T , -.IR convM2A , -.IR convM2TR , -and -.I convM2PR -are used to convert them back. -.I Key -is used for encrypting the message before transmission and decrypting -after reception. -.PP -The routine -.I _asgetresp -receives either a character array or an error string. -On error, it sets errstr and returns -1. If successful, -it returns the number of bytes received. -.PP -The routine -.I _asgetticket -sends a ticket request message and then uses -.I _asgetresp -to recieve an answer. -.SH SOURCE -.B /usr/local/plan9/src/libauthsrv -.SH SEE ALSO -.IR passwd (1), -.IR cons (3), -.IR dial (3), -.IR authsrv (6), -.SH DIAGNOSTICS -These routines set -.IR errstr . -Integer-valued functions return -1 on error.
diff --git a/man/man3/bio.3 b/man/man3/bio.3 index 7f6c05f..8228dad 100644 --- a/man/man3/bio.3 +++ b/man/man3/bio.3
@@ -1,6 +1,6 @@ .TH BIO 3 .SH NAME -Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output +Bopen, Bfdopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output .SH SYNOPSIS .ta \w'Biobuf* 'u .B #include <u.h> @@ -10,7 +10,10 @@ .B #include <bio.h> .PP .B -Biobuf* Bopen(char *file, int mode) +Biobuf* Bopen(char *file, int mode) +.PP +.B +Biobuf* Bfdopen(int fd, int mode) .PP .B int Binit(Biobuf *bp, int fd, int mode) @@ -93,6 +96,17 @@ .IR malloc (3) to allocate a buffer. .PP +.I Bfdopen +allocates a buffer for the already-open file descriptor +.I fd +for mode +.B OREAD +or +.BR OWRITE . +It calls +.IR malloc (3) +to allocate a buffer. +.PP .I Binit initializes a standard size buffer, type .IR Biobuf , @@ -312,7 +326,7 @@ .IR open (3), .IR print (3), .IR exits (3), -.IR utf (6), +.IR utf (7), .SH DIAGNOSTICS .I Bio routines that return integers yield
diff --git a/man/man3/cachechars.3 b/man/man3/cachechars.3 index 46bff61..bb7a475 100644 --- a/man/man3/cachechars.3 +++ b/man/man3/cachechars.3
@@ -4,7 +4,7 @@ .SH SYNOPSIS .B #include <u.h> .br -.B #include <draw.h> +.B #include <libc.h> .br .B #include <draw.h> .PP @@ -127,7 +127,7 @@ .B Font consists of an overall height and ascent and a collection of subfonts together with the ranges of runes (see -.IR utf (6)) +.IR utf (7)) they represent. Fonts are described by the following structures. .IP @@ -306,8 +306,8 @@ .IR allocimage (3), .IR draw (3), .IR subfont (3), -.IR image (6), -.IR font (6) +.IR image (7), +.IR font (7) .SH DIAGNOSTICS All of the functions use the graphics error function (see .IR graphics (3)).
diff --git a/man/man3/cleanname.3 b/man/man3/cleanname.3 index 27818ef..5568880 100644 --- a/man/man3/cleanname.3 +++ b/man/man3/cleanname.3
@@ -29,6 +29,6 @@ .I filename must contain room for at least two bytes. .SH SOURCE -.B /usr/local/plan9/src/libc/port/cleanname.c +.B /usr/local/plan9/src/lib9/cleanname.c .SH SEE ALSO .IR cleanname (1)
diff --git a/man/man3/color.3 b/man/man3/color.3 index 7d772b5..aac61bd 100644 --- a/man/man3/color.3 +++ b/man/man3/color.3
@@ -19,7 +19,7 @@ .SH DESCRIPTION These routines convert between `true color' red/green/blue triples and the Plan 9 color map. See -.IR color (6) +.IR color (7) for a description of RGBV, the standard color map. .PP .I Rgb2cmap @@ -52,5 +52,5 @@ .IR graphics (3), .IR allocimage (3), .IR draw (3), -.IR image (6), -.IR color (6) +.IR image (7), +.IR color (7)
diff --git a/man/man3/complete.3 b/man/man3/complete.3 index b1478dd..dc74050 100644 --- a/man/man3/complete.3 +++ b/man/man3/complete.3
@@ -1,6 +1,6 @@ .TH COMPLETE 3 .SH NAME -complete \- file name completion +complete, freecompletion \- file name completion .SH SYNOPSIS .B #include <u.h> .br
diff --git a/man/man3/cputime.3 b/man/man3/cputime.3 index 5acf671..c88340d 100644 --- a/man/man3/cputime.3 +++ b/man/man3/cputime.3
@@ -24,11 +24,5 @@ returns the sum of those same times, converted to seconds. .I Times returns the elapsed real time, in milliseconds, that the process has been running. -.PP -These functions read -.BR /dev/cputime , -opening that file when they are first called. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys -.SH SEE ALSO -.IR cons (3) +.B /usr/local/plan9/src/lib9/time.c
diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 new file mode 100644 index 0000000..ef3ae11 --- /dev/null +++ b/man/man3/ctime.3
@@ -0,0 +1,98 @@ +.TH CTIME 3 +.SH NAME +ctime, localtime, gmtime, asctime, tm2sec, timezone \- convert date and time +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.ta \w'\fLchar* 'u +.B +char* ctime(long clock) +.PP +.B +Tm* localtime(long clock) +.PP +.B +Tm* gmtime(long clock) +.PP +.B +char* asctime(Tm *tm) +.PP +.B +long tm2sec(Tm *tm) +.SH DESCRIPTION +.I Ctime +converts a time +.I clock +such as returned by +.IR time (3) +into +.SM ASCII +(sic) +and returns a pointer to a +30-byte string +in the following form. +All the fields have constant width. +.PP +.B + Wed Aug 5 01:07:47 EST 1973\en\e0 +.PP +.I Localtime +and +.I gmtime +return pointers to structures containing +the broken-down time. +.I Localtime +corrects for the time zone and possible daylight savings time; +.I gmtime +converts directly to GMT. +.I Asctime +converts a broken-down time to +.SM ASCII +and returns a pointer +to a 30-byte string. +.IP +.EX +.ta 6n +\w'char 'u +\w'zone[4]; 'u +typedef +struct { + int sec; /* seconds (range 0..59) */ + int min; /* minutes (0..59) */ + int hour; /* hours (0..23) */ + int mday; /* day of the month (1..31) */ + int mon; /* month of the year (0..11) */ + int year; /* year A.D. \- 1900 */ + int wday; /* day of week (0..6, Sunday = 0) */ + int yday; /* day of year (0..365) */ + char zone[4]; /* time zone name */ + int tzoff; /* time zone delta from GMT */ +} Tm; +.EE +.PP +.I Tm2sec +converts a broken-down time to +seconds since the start of the epoch. +It ignores +.BR wday , +and assumes the local time zone +if +.B zone +is not +.BR GMT . +.SH SOURCE +.B /usr/local/plan9/src/lib9/date.c +.br +.B /usr/local/plan9/src/lib9/ctime.c +.SH "SEE ALSO" +.IR date (1), +.IR time (3) +.SH BUGS +The return values point to static data +whose content is overwritten by each call. +.br +Daylight Savings Time is ``normal'' in the Southern hemisphere. +.br +These routines are not equipped to handle non-\c +.SM ASCII +text, and are provincial anyway.
diff --git a/man/man3/dial.3 b/man/man3/dial.3 index b26e65c..5110227 100644 --- a/man/man3/dial.3 +++ b/man/man3/dial.3
@@ -1,6 +1,6 @@ .TH DIAL 3 .SH NAME -dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- make and break network connections +dial, hangup, announce, listen, accept, reject, netmkaddr, dialparse \- make and break network connections .SH SYNOPSIS .B #include <u.h> .br @@ -10,9 +10,6 @@ int dial(char *addr, char *local, char *dir, int *cfdp) .PP .B -int hangup(int ctl) -.PP -.B int announce(char *addr, char *dir) .PP .B @@ -26,15 +23,18 @@ .PP .B char* netmkaddr(char *addr, char *defnet, char *defservice) +.\" .PP +.\" .B +.\" void setnetmtpt(char *to, int tolen, char *from) +.\" .PP +.\" .B +.\" NetConnInfo* getnetconninfo(char *conndir, int fd) +.\" .PP +.\" .B +.\" void freenetconninfo(NetConnINfo*) .PP .B -void setnetmtpt(char *to, int tolen, char *from) -.PP -.B -NetConnInfo* getnetconninfo(char *conndir, int fd) -.PP -.B -void freenetconninfo(NetConnINfo*) +int dialparse(char *addr, char **net, char **unix, u32int *host, int *port) .SH DESCRIPTION For these routines, .I addr @@ -44,8 +44,10 @@ or simply .IR netaddr . .I Network -is any directory listed in -.B /net +is +.BR tcp , +.BR udp , +.BR unix , or the special token, .BR net . .B Net @@ -53,45 +55,28 @@ between the source and the host .IR netaddr . .I Netaddr -can be a host name, a domain name, a network address, -or a meta-name of the form -.BI $ attribute\f1, -which -is replaced by -.I value -from the value-attribute pair -.IB attribute = value -most closely associated with the source host in the -network data base (see -.IR ndb (6)). +can be a host name, a domain name, or a network address. +.\" or a meta-name of the form +.\" .BI $ attribute\f1, +.\" which +.\" is replaced by +.\" .I value +.\" from the value-attribute pair +.\" .IB attribute = value +.\" most closely associated with the source host in the +.\" network data base (see +.\" .IR ndb (6)). .PP -If a connection attempt is successful and +On Plan 9, the .I dir -is non-zero, -the path name of a +argument is a path name to a .I line directory -that has files for accessing the connection -is copied into -.IR dir . -The path name is guaranteed to be less than 40 -bytes long. -One line directory exists for each possible connection. -The -.B data -file in the line directory should be used to communicate with the destination. -The -.B ctl -file in the line directory can be used to send commands to the line. -See -.IR ip (3) -for messages that can be written to the -.B ctl -file. -The last close of the -.B data -or -.B ctl -file will close the connection. +that has files for accessing the connection. +To keep the same function signatures, +the Unix port of these routines uses strings of the form +.BI /dev/fd/ n +instead of line directory paths. +These strings should be treated as opaque data and ignored. .PP .I Dial makes a call to destination @@ -111,26 +96,19 @@ 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 +.\" If the network allows the local address to be set, +.\" as is the case with UDP and TCP port numbers, and +.\" .IR local +.\" is non-zero, the local address will be set to +.\" .IR local . +.IR Dial 's +.IR local , +.IR dir , and -.B data -files. -.P +.I cfdp +arguments +are not supported and must be zero. +.PP .I Announce and .I listen @@ -181,73 +159,78 @@ if they are not specified in the address. It returns a pointer to static data holding the actual address to use. .PP -.I Getnetconninfo -returns a structure containing information about a -network connection. The structure is: -.EX - typedef struct NetConnInfo NetConnInfo; - struct NetConnInfo - { - char *dir; /* connection directory */ - char *root; /* network root */ - char *spec; /* binding spec */ - char *lsys; /* local system */ - char *lserv; /* local service */ - char *rsys; /* remote system */ - char *rserv; /* remote service */ - }; -.EE -.PP -The information is obtained from the connection directory, -.IR conndir . -If -.I conndir -is nil, the directory is obtained by performing -.IR fd2path (3) -on -.IR fd . -.I Getnetconninfo -returns either a completely specified structure, or -nil if either the structure can't be allocated or the -network directory can't be determined. -The structure -is freed using -.IR freenetconninfo . -.PP -.I Setnetmtpt -copies the name of the network mount point into -the buffer -.IR to , -whose length is -.IR tolen . -It exists to merge two pre-existing conventions for specifying -the mount point. -Commands that take a network mount point as a parameter -(such as -.BR dns , -.BR cs -(see -.IR ndb (8)), -and -.IR ipconfig (8)) -should now call -.IR setnetmtpt . -If -.I from -is -.BR nil , -the mount point is set to the default, -.BR /net . -If -.I from -points to a string starting with a slash, -the mount point is that path. -Otherwise, the mount point is the string pointed to by -.I from -appended to the string -.BR /net . -The last form is obsolete and is should be avoided. -It exists only to aid in conversion. +.I Dialparse +parses a network address as described above +into a network name, a Unix domain socket address, +an IPv4 host address, and an IPv4 port number. +.\" .PP +.\" .I Getnetconninfo +.\" returns a structure containing information about a +.\" network connection. The structure is: +.\" .EX +.\" typedef struct NetConnInfo NetConnInfo; +.\" struct NetConnInfo +.\" { +.\" char *dir; /* connection directory */ +.\" char *root; /* network root */ +.\" char *spec; /* binding spec */ +.\" char *lsys; /* local system */ +.\" char *lserv; /* local service */ +.\" char *rsys; /* remote system */ +.\" char *rserv; /* remote service */ +.\" }; +.\" .EE +.\" .PP +.\" The information is obtained from the connection directory, +.\" .IR conndir . +.\" If +.\" .I conndir +.\" is nil, the directory is obtained by performing +.\" .IR fd2path (3) +.\" on +.\" .IR fd . +.\" .I Getnetconninfo +.\" returns either a completely specified structure, or +.\" nil if either the structure can't be allocated or the +.\" network directory can't be determined. +.\" The structure +.\" is freed using +.\" .IR freenetconninfo . +.\" .PP +.\" .I Setnetmtpt +.\" copies the name of the network mount point into +.\" the buffer +.\" .IR to , +.\" whose length is +.\" .IR tolen . +.\" It exists to merge two pre-existing conventions for specifying +.\" the mount point. +.\" Commands that take a network mount point as a parameter +.\" (such as +.\" .BR dns , +.\" .BR cs +.\" (see +.\" .IR ndb (8)), +.\" and +.\" .IR ipconfig (8)) +.\" should now call +.\" .IR setnetmtpt . +.\" If +.\" .I from +.\" is +.\" .BR nil , +.\" the mount point is set to the default, +.\" .BR /net . +.\" If +.\" .I from +.\" points to a string starting with a slash, +.\" the mount point is that path. +.\" Otherwise, the mount point is the string pointed to by +.\" .I from +.\" appended to the string +.\" .BR /net . +.\" The last form is obsolete and is should be avoided. +.\" It exists only to aid in conversion. .SH EXAMPLES Make a call and return an open file descriptor to use for communications: @@ -259,12 +242,13 @@ } .EE .PP -Call the local authentication server: +Connect to a Unix socket served by +.IR acme (4): .IP .EX -int dialauth(char *service) +int dialacme(void) { - return dial(netmkaddr("$auth", 0, service), 0, 0, 0); + return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0); } .EE .PP @@ -315,17 +299,14 @@ } .EE .SH SOURCE -.BR /usr/local/plan9/src/libc/9sys , -.B /usr/local/plan9/src/libc/port -.SH "SEE ALSO" -.IR auth (3), -.IR ip (3), -.IR ndb (8) +.B /usr/local/plan9/src/lib9/dial.c +.br +.B /usr/local/plan9/src/lib9/announce.c +.br +.B /usr/local/plan9/src/lib9/_p9dialparse.c .SH DIAGNOSTICS .IR Dial , .IR announce , and .I listen return \-1 if they fail. -.I Hangup -returns nonzero if it fails.
diff --git a/man/man3/dirread.3 b/man/man3/dirread.3 index 4258509..ac83edf 100644 --- a/man/man3/dirread.3 +++ b/man/man3/dirread.3
@@ -62,7 +62,7 @@ .B Dir structures. See -.IR read (5) +.IR read (9p) for more information. .PP The constant @@ -83,7 +83,7 @@ .BR buf . The file offset is advanced by the number of bytes actually read. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/dirread.c +.B /usr/local/plan9/src/lib9/dirread.c .SH SEE ALSO .IR intro (3), .IR open (3),
diff --git a/man/man3/disk.3 b/man/man3/disk.3 new file mode 100644 index 0000000..30e4440 --- /dev/null +++ b/man/man3/disk.3
@@ -0,0 +1,177 @@ +.TH DISK 3 +.SH NAME +opendisk, Disk \- generic disk device interface +.SH SYNOPSIS +.nf +.ft L +#include <u.h> +#include <libc.h> +#include <disk.h> +.ft +.PP +.ft L +typedef struct Disk { + char *prefix; + char part[NAMELEN]; + int fd, wfd, ctlfd, rdonly; + int type; + vlong secs, secsize, size, offset; + int c, h, s; +} Disk; +.ft +.PP +.B +Disk* opendisk(char *file, int rdonly, int noctl) +.SH DESCRIPTION +These routines provide a simple way to gather +and use information about +disks and disk partitions, +as well as plain files. +.PP +.I Opendisk +opens +.I file +for reading and stores the file descriptor in +the +.B fd +field of the +.B Disk +structure. +If +.I rdonly +is not set, +.I opendisk +also opens +.I file +for writing and stores that file descriptor in +.BR wfd . +The two file descriptors are kept separate to +help prevent accidents. +.PP +If +.I noctl +is not set, +.I opendisk +looks for a +.B ctl +file in the same directory as the +disk file; +if it finds one, it declares +the disk to be +an +.I sd +device, +setting the +.B type +field in the +.B Disk +structure +to +.BR Tsd . +If the passed +.I file +is named +.BI fd n disk \fR, +it looks for a file +.BI fd n ctl \fR, +and if it finds that, +declares the disk to be +a floppy disk, of type +.BR Tfloppy . +If either +control +file is found, it is opened for reading +and writing, and the resulting file descriptor +is saved as +.BR ctlfd . +Otherwise the returned disk +has type +.BR Tfile . +.PP +.I Opendisk +then stats the file and stores its length in +.BR size . +If the disk is an +.I sd +partition, +.I opendisk +reads the sector size from the +control +file and stores it in +.BR secsize ; +otherwise the sector size is assumed to be 512, +as is the case for floppy disks. +.I Opendisk +then stores the disk size measured in sectors in +.BR secs . +.PP +If the disk is an +.I sd +partition, +.I opendisk +parses the +control +file to find the partition's offset +within its disk; +otherwise it sets +.B offset +to zero. +If the disk is an ATA disk, +.I opendisk +reads +the disk geometry (number of cylinders, heads, and sectors) +from the +.B geometry +line in the +.I sd +control file; +otherwise it sets these to zero as well. +.B Name +is initialized with the base name of +the disk partition, and is useful for forming messages to the +.I sd +control file. +.B Prefix +is set to the passed filename without +the +.B name +suffix. +.PP +The IBM PC BIOS interface allocates +10 bits for the number of cylinders, 8 for +the number of heads, and 6 for the number of sectors per track. +Disk geometries are not quite so simple +anymore, but to keep the interface useful, +modern disks and BIOSes present geometries +that still fit within these constraints. +These numbers are still used when partitioning +and formatting disks. +.I Opendisk +employs a number of heuristics to discover this +supposed geometry and store it in the +.BR c , +.BR h , +and +.B s +fields. +Disk offsets in partition tables and +in FAT descriptors are stored in a form +dependent upon these numbers, so +.I opendisk +works hard to report numbers that +agree with those used by other operating +systems; the numbers bear little or no resemblance +to reality. +.SH SOURCE +.B /usr/local/plan9/src/libdisk/disk.c +.SH SEE ALSO +Plan 9's +\fIfloppy\fR(3) and \fIsd\fR(3) +.SH BUGS +Disks on Unix systems do not present the interface +that +.I opendisk +expects, so +.I opendisk +will give them type +.BR Tfile .
diff --git a/man/man3/draw.3 b/man/man3/draw.3 index 6ad6d37..be5e6c6 100644 --- a/man/man3/draw.3 +++ b/man/man3/draw.3
@@ -1,10 +1,14 @@ .TH DRAW 3 .SH NAME -Image, draw, gendraw, drawreplxy, drawrepl, -replclipr, line, poly, fillpoly, bezier, bezspline, fillbezier, fillbezspline, ellipse, -fillellipse, arc, fillarc, icossin, icossin2, border, string, stringn, -runestring, runestringn, stringbg, stringnbg, runestringbg, -runestringnbg, _string, ARROW, drawsetdebug \- graphics functions +Image, draw, drawop, gendraw, gendrawop, drawreplxy, drawrepl, +replclipr, line, lineop, poly, polyop, fillpoly, fillpolyop, bezier, bezierop, +bezspline, bezsplineop, bezsplinepts, fillbezier, fillbezierop, +fillbezspline, fillbezsplineop, ellipse, ellipseop, +fillellipse, fillellipseop, arc, arcop, fillarc, fillarcop, +icossin, icossin2, border, string, stringop, stringn, stringnop, +runestring, runestringop, runestringn, runestringnop, stringbg, +stringbgop, stringnbg, stringnbgop, runestringbg, runestringbgop, +runestringnbg, runestringnbgop, _string, ARROW, drawsetdebug \- graphics functions .de PB .PP .ft L @@ -252,7 +256,7 @@ .TP .B chan The pixel channel format descriptor, as described in -.IR image (6). +.IR image (7). The value should not be modified after the image is created. .TP .B depth @@ -805,8 +809,8 @@ .SH SEE ALSO .IR graphics (3), .IR stringsize (3), -.IR color (6), -.IR utf (6), +.IR color (7), +.IR utf (7), .IR addpt (3) .PP T. Porter, T. Duff.
diff --git a/man/man3/dsa.3 b/man/man3/dsa.3 index b1af55e..f95ca77 100644 --- a/man/man3/dsa.3 +++ b/man/man3/dsa.3
@@ -79,7 +79,9 @@ and .B q generated by -.IR DSAprimes (3). +.IR DSAprimes +(see +.IR prime (3)). Otherwise, .B p and
diff --git a/man/man3/dup.3 b/man/man3/dup.3 index e3cee43..3c7312d 100644 --- a/man/man3/dup.3 +++ b/man/man3/dup.3
@@ -25,18 +25,14 @@ for the new file descriptor (closing any old file associated with .IR newfd ). -File descriptors are allocated dynamically, -so to prevent unwarranted growth of the file descriptor table, -.I dup -requires that -.I newfd -be no greater than 20 more than the highest file descriptor ever used by -the program. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.SH SEE ALSO -.IR intro (3), -.IR dup (3) +.B /usr/local/plan9/src/lib9/dup.c .SH DIAGNOSTICS Sets .IR errstr . +.SH BUGS +.I Dup +is a macro for +.I p9dup +to avoid name conflicts with the Unix function; see +.IR intro (3).
diff --git a/man/man3/encode.3 b/man/man3/encode.3 index 1a93e37..44c6afd 100644 --- a/man/man3/encode.3 +++ b/man/man3/encode.3
@@ -80,6 +80,6 @@ .EE .SH SOURCE -.B /usr/local/plan9/src/libc/port/u32.c +.B /usr/local/plan9/src/lib9/u32.c .br -.B /usr/local/plan9/src/libc/port/u64.c +.B /usr/local/plan9/src/lib9/u64.c
diff --git a/man/man3/encrypt.3 b/man/man3/encrypt.3 deleted file mode 100644 index 50d00bf..0000000 --- a/man/man3/encrypt.3 +++ /dev/null
@@ -1,76 +0,0 @@ -.TH ENCRYPT 3 -.SH NAME -encrypt, decrypt, netcrypt \- DES encryption -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.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 <auth.h> ) -bytes containing the encryption key. -.I Data -is an array of -.I len -bytes; -it must be at least 8 bytes long. -The bytes are encrypted or decrypted in place. -.PP -The DES algorithm encrypts an individual 8-byte block of data. -.I Encrypt -uses the following method to encrypt data longer than 8 bytes. -The first 8 bytes are encrypted as usual. -The last byte of the encrypted result -is prefixed to the next 7 unencrypted bytes to make the next 8 -bytes to encrypt. -This is repeated until fewer than 7 bytes remain unencrypted. -Any remaining unencrypted bytes are encrypted with enough of the preceding -encrypted bytes to make a full 8-byte block. -.I Decrypt -uses the inverse algorithm. -.PP -.I Netcrypt -performs the same encryption as a SecureNet Key. -.I Data -points to an -.SM ASCII -string of decimal digits with numeric value between 0 and 10000. -These digits are copied into an 8-byte buffer with trailing binary zero fill -and encrypted as one DES block. -The first four bytes are each formatted as two digit -.SM ASCII -hexadecimal numbers, -and the string is copied into -.IR data . -.SH SOURCE -.B /usr/local/plan9/src/libc/port -.SH DIAGNOSTICS -These routines return 1 if the data was encrypted, -and 0 if the encryption fails. -.I Encrypt -and -.I decrypt -fail if the data passed is less than 8 bytes long. -.I Netcrypt -can fail if it is passed invalid data. -.SH SEE ALSO -.IR securenet (8) -.SH BUGS -The implementation is broken in a way that makes -it unsuitable for anything but authentication.
diff --git a/man/man3/errstr.3 b/man/man3/errstr.3 index 1a88897..a0e6d3f 100644 --- a/man/man3/errstr.3 +++ b/man/man3/errstr.3
@@ -73,13 +73,35 @@ The string returned from .I errstr is discarded. +.PP +The error string is maintained in parallel with the Unix +error number +.IR errno . +Changing +.I errno +will reset the error string, +and changing the error string via +.I errstr +or +.I werrstr +will reset +.IR errno . .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.br -.B /usr/local/plan9/src/libc/9sys/werrstr.c +.B /usr/local/plan9/src/lib9/errstr.c .SH DIAGNOSTICS .I Errstr always returns 0. .SH SEE ALSO .IR intro (3), .IR perror (3) +.SH BUGS +The implementation sets +.I errno +to the (somewhat arbitrary) +constant 0x19283745 when +the error string is valid. +When +.I errno +is set to other values, the error string +is synthesized using +.IR strerror (3).
diff --git a/man/man3/event.3 b/man/man3/event.3 index 7982b70..e029981 100644 --- a/man/man3/event.3 +++ b/man/man3/event.3
@@ -138,9 +138,9 @@ .I Ekbd returns the next rune from the queue, blocking until the queue is non-empty. -The characters are read in raw mode -(see -.IR cons (3)), +The characters are read in raw mode, +.\" (see +.\" .IR cons (3)), so they are available as soon as a complete rune is typed. .PP When the mouse moves or a mouse button is pressed or released, @@ -380,5 +380,5 @@ .IR rio (1), .IR graphics (3), .IR plumb (3), -.IR cons (3), +.\" .IR cons (3), .IR draw (3)
diff --git a/man/man3/exec.3 b/man/man3/exec.3 index 4886861..285af11 100644 --- a/man/man3/exec.3 +++ b/man/man3/exec.3
@@ -1,6 +1,6 @@ .TH EXEC 3 .SH NAME -exec, execl, _clock, _privates, _nprivates \- execute a file +exec, execl \- execute a file .SH SYNOPSIS .B #include <u.h> .br @@ -12,15 +12,6 @@ .PP .B int execl(char *name, ...) -.PP -.B -long *_clock; -.PP -.B -void **_privates; -.PP -.B -int _nprivates; .fi .SH DESCRIPTION .I Exec @@ -35,10 +26,8 @@ must allow the current user to execute it (see .IR stat (3)). -It should also be a valid binary image, as defined in the -.IR a.out (6) -for the current machine architecture, -or a shell script +It should also be a valid binary image, as defined by the local +operating system, or a shell script (see .IR rc (1)). The first line of a @@ -106,45 +95,17 @@ .IR open (3)); and the working directory and environment (see -.IR env (3)) +.IR getenv (3)) remain the same. However, a newly .I exec'ed -process has no notification handler +process has no notification handlers (see .IR notify (3)). -.PP -When the new program begins, the global cell -.B _clock -is set to the address of a cell that keeps approximate time -expended by the process at user level. -The time is measured in milliseconds but is updated at -a system-dependent lower rate. -This clock is typically used by the profiler but is available -to all programs. -.PP -The global cell -.B _privates -points to an array of -.B _nprivates -elements of per-process private data. -This storage is private for each process, even if the processes share data segments. -.PP -The above conventions apply to C programs; the raw system -interface to the new image is as follows: -the word pointed to by the stack pointer is -.BR argc ; -the words beyond that are the zeroth and subsequent elements -of -.BR argv , -followed by a terminating null pointer; and -the return register (e.g. -.B R0 -on the 68020) contains the address of the clock. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/exec.c .br -.B /usr/local/plan9/src/libc/port/execl.c +.B /usr/local/plan9/src/lib9/execl.c .SH SEE ALSO .IR prof (1), .IR intro (3), @@ -157,3 +118,13 @@ or .IR execl ; the calling image is lost. +.SH BUGS +On Unix, unlike on Plan 9, +.I exec +and +.I execl +use the user's current path to locate +.IR prog . +This is a clumsy way to deal with Unix's lack of +a union directory for +.BR /bin .
diff --git a/man/man3/exits.3 b/man/man3/exits.3 index 2591ff1..95e2b93 100644 --- a/man/man3/exits.3 +++ b/man/man3/exits.3
@@ -22,7 +22,10 @@ .I Exits is the conventional way to terminate a process. .I _Exits -is the underlying system call. +also terminates a process but does not call the registered +.I atexit +handlers +.RI ( q.v. ). They can never return. .PP @@ -75,7 +78,18 @@ .I Atexitdont cancels a previous registration of an exit function. .SH SOURCE -.B /usr/local/plan9/src/libc/port/atexit.c +.B /usr/local/plan9/src/lib9/atexit.c +.br +.B /usr/local/plan9/src/lib9/_exits.c .SH "SEE ALSO" -.IR fork (3), +.IR fork (2), .IR wait (3) +.SH BUGS +Because of limitations of Unix, the exit status of a +process can only be an 8-bit integer. +Exit status 0 is used for empty exit messages, and 1 for +non-empty messages. +.PP +Exit codes 97 through 99 are used by the thread library to signal +internal synchronization errors between the main program +and a proxy process that implements backgrounding.
diff --git a/man/man3/fcall.3 b/man/man3/fcall.3 index 2e09dda..1143217 100644 --- a/man/man3/fcall.3 +++ b/man/man3/fcall.3
@@ -303,7 +303,7 @@ .I buf should include the second two-byte (16-bit) length field that precedes the entry when formatted in a 9P message (see -.IR stat (5)); +.IR stat (9p)); in other words, .I nbuf is 2 plus the sum of the sizes of the entry itself. @@ -349,9 +349,9 @@ The return value is 0 for end of file, or -1 for error; it does not return partial messages. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR intro (3), .IR 9p (3), .IR stat (3), -.IR intro (5) +.IR intro (9p)
diff --git a/man/man3/fmtinstall.3 b/man/man3/fmtinstall.3 index cc4884a..8a437f1 100644 --- a/man/man3/fmtinstall.3 +++ b/man/man3/fmtinstall.3
@@ -297,12 +297,12 @@ All these routines return zero for successful execution. Conversion routines that call these functions will work properly regardless of whether the output is bytes or runes. -.PP -.IR 2c (1) -describes the C directive -.B #pragma -.B varargck -that can be used to provide type-checking for custom print verbs and output routines. +.\" .PP +.\" .IR 2c (1) +.\" describes the C directive +.\" .B #pragma +.\" .B varargck +.\" that can be used to provide type-checking for custom print verbs and output routines. .SH EXAMPLES This function prints an error message with a variable number of arguments and then quits. @@ -362,10 +362,10 @@ } .EE .SH SOURCE -.B /usr/local/plan9/src/libc/fmt +.B /usr/local/plan9/src/lib9/fmt .SH SEE ALSO .IR print (3), -.IR utf (6), +.IR utf (7), .IR errstr (3) .SH DIAGNOSTICS These routines return negative numbers or nil for errors and set
diff --git a/man/man3/fork.3 b/man/man3/fork.3 deleted file mode 100644 index e17f0d6..0000000 --- a/man/man3/fork.3 +++ /dev/null
@@ -1,166 +0,0 @@ -.TH FORK 3 -.SH NAME -fork, rfork \- manipulate process resources -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.PP -.nf -.B -int fork(void) -.PP -.B -int rfork(int flags) -.fi -.SH DESCRIPTION -Forking is the only way new processes are created. -The -.I flags -argument to -.I rfork -selects which resources of the -invoking process (parent) are shared -by the new process (child) or initialized to -their default values. -The resources include -the file name space, -the open file descriptor table (which, when shared, permits processes -to open and close files for other processes), -the set of environment variables -(see -.IR env (3)), -the note group -(the set of processes that receive notes written to a member's -.B notepg -file; -see -.IR proc (3)), -the set of rendezvous tags -(see -.IR rendezvous (3)); -and open files. -.I Flags -is the logical OR of some subset of -.TF RFCNAMEG -.TP -.B RFPROC -If set a new process is created; otherwise changes affect the -current process. -.TP -.B RFNOWAIT -If set, the child process will be dissociated from the parent. Upon -exit the child will leave no -.B Waitmsg -(see -.IR wait (3)) -for the parent to collect. -.TP -.B RFNAMEG -If set, the new process inherits a copy of the parent's name space; -otherwise the new process shares the parent's name space. -Is mutually exclusive with -.BR RFCNAMEG . -.TP -.B RFCNAMEG -If set, the new process starts with a clean name space. A new -name space must be built from a mount of an open file descriptor. -Is mutually exclusive with -.BR RFNAMEG . -.TP -.B RFNOMNT -If set, subsequent mounts into the new name space and dereferencing -of pathnames starting with -.B # -are disallowed. -.TP -.B RFENVG -If set, the environment variables are copied; -otherwise the two processes share environment variables. -Is mutually exclusive with -.BR RFCENVG . -.TP -.B RFCENVG -If set, the new process starts with an empty environment. -Is mutually exclusive with -.BR RFENVG . -.TP -.B RFNOTEG -Each process is a member of a group of processes that all -receive notes when a note is written to any of their -.B notepg -files (see -.IR proc (3)). -The group of a new process is by default the same as its parent, but if -.B RFNOTEG -is set (regardless of -.BR RFPROC ), -the process becomes the first in a new group, isolated from -previous processes. -.TP -.B RFFDG -If set, the invoker's file descriptor table (see -.IR intro (3)) -is copied; otherwise the two processes share a -single table. -.TP -.B RFCFDG -If set, the new process starts with a clean file descriptor table. -Is mutually exclusive with -.BR RFFDG . -.TP -.B RFREND -If set, the process will be unable to -.IR rendezvous (3) -with any of its ancestors; its children will, however, be able to -.B rendezvous -with it. In effect, -.B RFREND -makes the process the first in a group of processes that share a space for -.B rendezvous -tags. -.TP -.B RFMEM -If set, the child and the parent will share -.B data -and -.B bss -segments. -Otherwise, the child inherits a copy of those segments. -Other segment types, in particular stack segments, will be unaffected. -May be set only with -.BR RFPROC . -.PD -.PP -File descriptors in a shared file descriptor table are kept -open until either they are explicitly closed -or all processes sharing the table exit. -.PP -If -.B RFPROC -is set, the -value returned in the parent process -is the process id -of the child process; the value returned in the child is zero. -Without -.BR RFPROC , -the return value is zero. -Process ids range from 1 to the maximum integer -.RB ( int ) -value. -.I Rfork -will sleep, if necessary, until required process resources are available. -.PP -.I Fork -is just a call of -.BR rfork(RFFDG|RFREND|RFPROC) . -.SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.br -.B /usr/local/plan9/src/libc/9sys/fork.c -.SH SEE ALSO -.IR intro (3), -.IR proc (3), -.SH DIAGNOSTICS -These functions set -.IR errstr .
diff --git a/man/man3/genrandom.3 b/man/man3/genrandom.3 index f8952e4..761df86 100644 --- a/man/man3/genrandom.3 +++ b/man/man3/genrandom.3
@@ -16,7 +16,6 @@ .B void prng(uchar *buf, int nbytes) .SH DESCRIPTION -.PP Most security software requires a source of random or, at the very least, unguessable numbers. .PP
diff --git a/man/man3/get9root.3 b/man/man3/get9root.3 new file mode 100644 index 0000000..134f305 --- /dev/null +++ b/man/man3/get9root.3
@@ -0,0 +1,75 @@ +.TH GET9ROOT 3 +.SH NAME +get9root, unsharp \- get path to root of Plan 9 tree +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +char* get9root(void) +.PP +.B +char* unsharp(char *path) +.SH DESCRIPTION +This tree of Plan 9 software is conventionally installed in +.B /usr/local/plan9 +but may be installed in other places (for example, users without +the ability to write to +.B /usr/local +may with to install it in their own home directories). +The environment variable +.B $PLAN9 +should contain the path to the root. +.I Get9root +returns a static pointer to the pathname of root, first checking +.B $PLAN9 +and defaulting to +.BR /usr/local/plan9 . +.PP +The lack of a fixed location for the Plan 9 tree +makes it difficult to hard-code paths +to files. +.I Unsharp +replaces a leading +.B #9 +in +.I path +with the root of the tree. +.I Unsharp +also replaces a leading +.B #d +with the path to the underlying system's file descriptor dup device, +typically +.BR /dev/fd . +The string returned from +.IR unsharp , +if different from +.IR path , +should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +As a convention, programs should never +.I unsharp +paths obtained from user input. +.SH EXAMPLE +The +.IR plumber (4) +uses this code to find unrooted file names included by plumb rules. +.IP +.EX +snprint(buf, sizeof buf, "#9/plumb/%s", name); +fd = open(unsharp(buf), OREAD); +.EE +.SH SOURCE +.B /usr/local/plan9/src/lib9/getns.c +.SH SEE ALSO +.IR intro (4) +.SH BUGS +.I Get9root +could be smarter about finding the tree when +.B $PLAN9 +is not set.
diff --git a/man/man3/getcallerpc.3 b/man/man3/getcallerpc.3 index c275fb5..8ad95a3 100644 --- a/man/man3/getcallerpc.3 +++ b/man/man3/getcallerpc.3
@@ -31,7 +31,7 @@ } .EE .SH SOURCE -.B /usr/local/plan9/src/libc/$objtype/getcallerpc.[cs] +.B /usr/local/plan9/src/lib9/ .SH BUGS The .I firstarg
diff --git a/man/man3/getenv.3 b/man/man3/getenv.3 index 315407c..4be92ec 100644 --- a/man/man3/getenv.3 +++ b/man/man3/getenv.3
@@ -15,10 +15,8 @@ .fi .SH DESCRIPTION .I Getenv -reads the contents of -.BI /env/ name -(see -.IR env (3)) +fetches the environment value associated with +.I name into memory allocated with .IR malloc (3), 0-terminates it, @@ -27,18 +25,18 @@ is returned. .PP .I Putenv -creates the file -.BI /env/ name -and writes the string -.I val -to it. The terminating -.B 0 -is not written. -If the file value cannot be written, \-1 is returned. +sets the environment value associated with +.I name +to +.IR val . .SH SOURCE -.B /usr/local/plan9/src/libc/9sys -.SH SEE ALSO -.IR env (3) +.B /usr/local/plan9/src/lib9/getenv.c .SH DIAGNOSTICS Sets .IR errstr . +.SH BUGS +Defined as macros for +.I p9getenv +and +.I p9putenv +to avoid name conflicts with Unix library calls.
diff --git a/man/man3/getfields.3 b/man/man3/getfields.3 index e39c775..7805290 100644 --- a/man/man3/getfields.3 +++ b/man/man3/getfields.3
@@ -87,7 +87,7 @@ .I delims set to \f5"\et\er\en "\fP. .SH SOURCE -.B /usr/local/plan9/src/libc/port/tokenize.c +.B /usr/local/plan9/src/lib9/tokenize.c .SH SEE ALSO .I strtok in
diff --git a/man/man3/getns.3 b/man/man3/getns.3 new file mode 100644 index 0000000..cc76f2b --- /dev/null +++ b/man/man3/getns.3
@@ -0,0 +1,22 @@ +.TH GETNS 3 +.SH NAME +getns \- get path to name space directory +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +char* getns(void) +.SH DESCRIPTION +.I Getns +returns a pointer to a malloced string that contains the +path to the name space directory for the current process. +The name space directory is a clumsy substitute +for Plan 9's per-process name spaces; see +.IR intro (4) +for details. +.SH SOURCE +.B /usr/local/plan9/src/lib9/getns.c +.SH SEE ALSO +.IR intro (4)
diff --git a/man/man3/getpid.3 b/man/man3/getpid.3 deleted file mode 100644 index 44837f6..0000000 --- a/man/man3/getpid.3 +++ /dev/null
@@ -1,41 +0,0 @@ -.TH GETPID 3 -.SH NAME -getpid, getppid \- get process ids -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.PP -.B -int getpid(void) -.PP -.B -int getppid(void) -.SH DESCRIPTION -.I Getpid -reads -.B /dev/pid -(see -.IR cons (3)) -and converts it to get the process id of the current process, -a number guaranteed to be unique among all running processes on the machine -executing -.IR getpid . -.PP -.I Getppid -reads -.B /dev/ppid -(see -.IR cons (3)) -and converts it to get the id of the parent of the current process. -.SH SOURCE -.B /usr/local/plan9/src/libc/9sys -.SH SEE ALSO -.IR intro (3), -.IR cons (3), -.IR proc (3) -.SH DIAGNOSTICS -Returns 0 and -sets -.I errstr -if unsuccessful.
diff --git a/man/man3/getsnarf.3 b/man/man3/getsnarf.3 new file mode 100644 index 0000000..a90d595 --- /dev/null +++ b/man/man3/getsnarf.3
@@ -0,0 +1,37 @@ +.TH GETSNARF 3 +.SH NAME +getsnarf, putsnarf \- window system snarf (cut and paste) buffer +.SH SYNOPSIS +.B #include <draw.h> +.PP +.B +char *getsnarf(void) +.PP +.B +void putsnarf(char *text) +.SH DESCRIPTION +.I Getsnarf +and +.I putsnarf +access the window system's snarf (cut and paste) buffer. +.PP +.I Getsnarf +returns a copy of the current buffer; +the returned pointer should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +.I Putsnarf +sets the buffer to the text string +.IR text . +.PP +Callers should assume that the snarf buffer is UTF. +If the window system does not keep the buffer in UTF, +.I getsnarf +and +.I putsnarf +will convert as necessary. +.SH SOURCE +.B /usr/local/plan9/src/libdraw/x11-itrans.c
diff --git a/man/man3/getuser.3 b/man/man3/getuser.3 index e09c4a4..a7ada46 100644 --- a/man/man3/getuser.3 +++ b/man/man3/getuser.3
@@ -18,20 +18,35 @@ name of the user who owns the current process. .I Getuser -reads -.B /dev/user -to find the name. +calls +.IR getuid (2) +and then reads +.B /etc/passwd +to find the corresponding name. .PP .I Sysname -provides the same service for the file -.BR #c/sysname , -which contains the name of the machine. +returns a pointer to static data which contains the name +of the machine on which the current process is running. +.I Sysname +looks first for an environment variable +.BR $sysname . +If there is no such variable, +.I sysname +calls +.IR gethostname (2) +and truncates the returned name at the first dot. +If +.I gethostname +fails, +.I sysname +returns the default name +.LR gnot . +.PP Unlike .IR getuser , .I sysname -caches the string, reading the file only once. +caches the string, deriving the host name only once. .SH SOURCE -.B /usr/local/plan9/src/libc/port/getuser.c -.SH SEE ALSO -.IR intro (3), -.IR cons (3) +.B /usr/local/plan9/src/lib9/getuser.c +.br +.B /usr/local/plan9/src/lib9/sysname.c
diff --git a/man/man3/getwd.3 b/man/man3/getwd.3 index 6b053fd..d9aa02b 100644 --- a/man/man3/getwd.3 +++ b/man/man3/getwd.3
@@ -21,17 +21,10 @@ .I size bytes in the buffer provided. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/getwd.c +.B /usr/local/plan9/src/lib9/getwd.c .SH "SEE ALSO" .IR pwd (1), -.IR fd2path (3) .SH DIAGNOSTICS On error, zero is returned. .IR Errstr (3) may be consulted for more information. -.SH BUGS -Although the name returned by -.I getwd -is guaranteed to be the path used to reach the directory, -if the name space has changed underfoot, the name may be -incorrect.
diff --git a/man/man3/graphics.3 b/man/man3/graphics.3 index 6824537..971303e 100644 --- a/man/man3/graphics.3 +++ b/man/man3/graphics.3
@@ -189,7 +189,7 @@ A .B Font is a set of character images, indexed by runes (see -.IR utf (6)). +.IR utf (7)). The images are organized into .BR Subfonts , each containing the images for a small, contiguous set of runes. @@ -376,24 +376,24 @@ .IR rio (1) (see .IR window (3)). -.PP -The function -.I newwindow -may be called before -.I initdraw -or -.IR geninitdraw -to cause the program to occupy a newly created window rather than take over the one in -which it is running when it starts. -The -.I str -argument, if non-null, is concatenated to the string \f5\&"new\ "\fP -that is used to create the window (see -.IR rio (4)). -For example, -.B newwindow("-hide -dy 100") -will cause the program to run in a newly created, hidden window -100 pixels high. +.\" .PP +.\" The function +.\" .I newwindow +.\" may be called before +.\" .I initdraw +.\" or +.\" .IR geninitdraw +.\" to cause the program to occupy a newly created window rather than take over the one in +.\" which it is running when it starts. +.\" The +.\" .I str +.\" argument, if non-null, is concatenated to the string \f5\&"new\ "\fP +.\" that is used to create the window (see +.\" .IR rio (4)). +.\" For example, +.\" .B newwindow("-hide -dy 100") +.\" will cause the program to run in a newly created, hidden window +.\" 100 pixels high. .PP .I Initdisplay is part of @@ -484,15 +484,15 @@ sophisticated clients may use .B _screen to make further subwindows. -Programs desiring multiple independent windows -may use the mechanisms of -.IR rio (4) -to create more windows (usually by a fresh mount of the window sytem -in a directory other than -.BR /dev ), -then use -.I gengetwindow -to connect to them. +.\" Programs desiring multiple independent windows +.\" may use the mechanisms of +.\" .IR rio (4) +.\" to create more windows (usually by a fresh mount of the window sytem +.\" in a directory other than +.\" .BR /dev ), +.\" then use +.\" .I gengetwindow +.\" to connect to them. .IR Gengetwindow 's extra arguments are the full path of the window's .B winname @@ -552,7 +552,7 @@ .I chantostr convert between the channel descriptor strings used by -.IR image (6) +.IR image (7) and the internal .B ulong representation @@ -630,9 +630,9 @@ .IR print (3), .IR window (3), .IR draw (3), -.IR rio (4), -.IR image (6), -.IR font (6) +.\" .IR rio (4), +.IR image (7), +.IR font (7) .SH DIAGNOSTICS An error function may call .IR errstr (3)
diff --git a/man/man3/ioproc.3 b/man/man3/ioproc.3 index ae21758..5c3ebda 100644 --- a/man/man3/ioproc.3 +++ b/man/man3/ioproc.3
@@ -8,7 +8,11 @@ ioopen, ioproc, ioread, +ioread9pmsg, ioreadn, +iorecvfd, +iosendfd, +iosleep, iowrite \- slave I/O processes for threaded programs .SH SYNOPSIS .PP @@ -26,12 +30,16 @@ .sp Ioproc* ioproc(void); .XX -int ioopen(Ioproc *io, char *file, int omode); int ioclose(Ioproc *io, int fd); -long ioread(Ioproc *io, int fd, void *a, long n); -long ioreadn(Ioproc *io, int fd, void *a, long n); -long iowrite(Ioproc *io, int fd, void *a, long n); int iodial(Ioproc *io, char *addr, char *local, char *dir, char *cdfp); +int ioopen(Ioproc *io, char *file, int omode); +long ioread(Ioproc *io, int fd, void *a, long n); +int ioread9pmsg(Ioproc *io, int fd, void *a, uint n); +long ioreadn(Ioproc *io, int fd, void *a, long n); +int iorecvfd(int socket); +int iosendfd(int socket, int fd); +int iosleep(int milli); +long iowrite(Ioproc *io, int fd, void *a, long n); .XX void iointerrupt(Ioproc *io); void closeioproc(Ioproc *io); @@ -58,20 +66,28 @@ .I sysfatal rather than return an error. .PP -.IR Ioopen , -.IR ioclose , +.IR Ioclose , +.IR iodial , +.IR ioopen , .IR ioread , +.IR ioread9pmsg , .IR ioreadn , -.IR iowrite , +.IR iorecvfd , +.IR iosendfd , +.IR iosleep , and -.IR iodial -are execute the +.I iowrite +execute the similarly named library or system calls (see +.IR close (2), +.IR dial (3), .IR open (3), .IR read (3), +.IR fcall (3), +.IR sendfd (3), and -.IR dial (3)) +.IR sleep (3)) in the slave process associated with .IR io . It is an error to execute more than one call @@ -144,7 +160,6 @@ common access to .I tot would be unsafe. -.EE .PP Implement .IR ioread : @@ -170,10 +185,12 @@ } .EE .SH SOURCE -.B /usr/local/plan9/src/libthread/io*.c +.B /usr/local/plan9/src/libthread .SH SEE ALSO .IR dial (3), .IR open (3), .IR read (3), .IR thread (3) - +.SH BUGS +.I Iointerrupt +is currently unimplemented.
diff --git a/man/man3/ip.3 b/man/man3/ip.3 index b133adf..c31c294 100644 --- a/man/man3/ip.3 +++ b/man/man3/ip.3
@@ -1,6 +1,6 @@ .TH IP 3 .SH NAME -eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, hnputl, hnputs, ptclbsum, readipifc \- Internet protocol +eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, nhgetv, hnputl, hnputs, hnputv, ptclbsum, readipifc \- Internet protocol .SH SYNOPSIS .B #include <u.h> .br @@ -57,12 +57,18 @@ uint nhgetl(void *p) .PP .B +uvlong nhgetv(void *p) +.PP +.B void hnputs(void *p, ushort v) .PP .B void hnputl(void *p, uint v) .PP .B +void hnputv(void *p, uvlong v) +.PP +.B ushort ptclbsum(uchar *a, int n) .PP .B @@ -211,14 +217,16 @@ to a V4 address and puts the result in .IR v4ip . .PP -.I Hnputs +.IR Hnputs , +.IR hnputl , and -.I hnputl -are used to store 16-bit and 32-bit integers into IP big-endian form. -.I Nhgets +.I hnputv +are used to store 16-, 32-, and 64-bit integers into IP big-endian form. +.IR Nhgets , +.IR nhgetl , and -.I nhgetl -convert big-endian 2 and 4 byte quantities into integers. +.I nhgetv +convert big-endian 2-, 4-, and 8-byte quantities into integers. .PP .I Pctlbsum returns the one's complement checksum used in IP protocols, typically invoked as
diff --git a/man/man3/isalpharune.3 b/man/man3/isalpharune.3 index 07d9955..78bc4e6 100644 --- a/man/man3/isalpharune.3 +++ b/man/man3/isalpharune.3
@@ -35,7 +35,7 @@ Unicode defines some characters as alphabetic and specifies three cases: upper, lower, and title. Analogously to -.IR ctype (3) +.IR isalpha (3) for .SM ASCII\c , @@ -45,7 +45,7 @@ .PP The case-conversion routines return the character unchanged if it has no case. .SH SOURCE -.B /usr/local/plan9/src/libc/port/runetype.c +.B /usr/local/plan9/src/lib9/utf/runetype.c .SH "SEE ALSO -.IR ctype (3) , +.IR isalpha (3) , .IR "The Unicode Standard" .
diff --git a/man/man3/keyboard.3 b/man/man3/keyboard.3 index b90f18b..f341e50 100644 --- a/man/man3/keyboard.3 +++ b/man/man3/keyboard.3
@@ -53,16 +53,8 @@ .PP The argument to .I initkeyboard -is a -.I file -naming the device file from which characters may be read, -typically -.BR /dev/cons . -If -.I file -is nil, -.B /dev/cons -is assumed. +is ignored +(on Plan 9, it is the name of the keyboard device). .PP Once the .B Keyboardctl @@ -75,9 +67,9 @@ to report each character read from the device. .PP .I Ctlkeyboard -is used to set the state of the interface, typically to turn raw mode on and off -(see -.IR cons (3)). +is used to set the state of the interface, typically to turn raw mode on and off. +.\" (see +.\" .IR cons (3)). It writes the string .I msg to the control file associated with the device, which is assumed to be the regular device file name
diff --git a/man/man3/lock.3 b/man/man3/lock.3 index d989d18..9034229 100644 --- a/man/man3/lock.3 +++ b/man/man3/lock.3
@@ -72,22 +72,16 @@ .B QLocks and .B RWLocks -are different types of queueing rendezvous locks, +are different types of queueing locks, and .B Rendezes are rendezvous points. .PP -Locks and rendezvous points work in regular programs as -well as programs that use the thread library +Locks and rendezvous points have trivial implementations in programs +not using the thread library (see -.IR thread (3)). -The thread library replaces the -.IR rendezvous (3) -system call -with its own implementation, -.IR threadrendezvous , -so that threads as well as processes may be synchronized by locking calls -in threaded programs. +.IR thread (3)), +since such programs have no concurrency. .PP Used carelessly, spin locks can be expensive and can easily generate deadlocks. Their use is discouraged, especially in programs that use the @@ -105,7 +99,7 @@ .B QLocks have the same interface but are not spin locks; instead if the lock is taken .I qlock -will suspend execution of the calling task until it is released. +will suspend execution of the calling thread until it is released. .PP Although .B Locks @@ -199,18 +193,39 @@ .B Ref and returns zero if the resulting value is zero, non-zero otherwise. .SH SOURCE -.B /usr/local/plan9/src/libc/port/lock.c +.B /usr/local/plan9/src/lib9/qlock.c .br -.B /usr/local/plan9/src/libc/9sys/qlock.c -.br -.B /usr/local/plan9/src/libthread/ref.c -.SH SEE ALSO -.I rfork -in -.IR fork (3) +.B /usr/local/plan9/src/libthread .SH BUGS .B Locks -are not strictly spin locks. +are not always spin locks. +Instead they are usually implemented using the +.I pthreads +library's +.BR pthread_mutex_t , +whose implementation method is not defined. +.PP +On +.IR pthreads -based +systems, the implementation of +.B Lock +never calls +.I pthread_mutex_destroy +to free the +.BR pthread_mutex_t 's. +This leads to resource leaks on FreeBSD 5 +(though not on Linux 2.6, where +.I pthread_mutex_destroy +is a no-op). +.BR +.PP +On systems that do not have a usable +.I pthreads +implementation, the +.B Lock +implementation provided by +.I libthread +is still not exactly a spin lock. After each unsuccessful attempt, .I lock calls
diff --git a/man/man3/mach-cmd.3 b/man/man3/mach-cmd.3 new file mode 100644 index 0000000..202ca39 --- /dev/null +++ b/man/man3/mach-cmd.3
@@ -0,0 +1,141 @@ +.TH MACH-CMD 3 +.SH NAME +attachargs, attachcore, attachdynamic, attachproc, proctextfile \- debugging processes and core files +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.br +.B #include <mach.h> +.PP +.ta +\w'\fLextern 'u +\w'\fLchar *'u +.B +int attachcore(Fhdr *hdr) +.PP +.B +int attachproc(int pid) +.PP +.B +int attachdynamic(void) +.PP +.B +char* proctextfile(int pid) +.PP +.B +int attachargs(int argc, char **argv, int omode) +.PP +.B +.nf +extern Fhdr* symhdr; +extern char* symfil; +extern Map* symmap; +extern Fhdr* fhdrlist; +.ift .sp .5 +.ifn .sp +extern Fhdr* corhdr; +extern char* corfil; +extern Map* cormap; +.ift .sp .5 +.ifn .sp +extern int corpid; +extern Regs* correg; +.SH DESCRIPTION +These routines provide access to the objects +a typical debugger manipulates: an executable binary, +some number of shared libraries, a memory image +in the form of a core dump or active process, +and a register set. +.PP +The maintained state is: +.TP +.I symhdr +The file header for the main binary. +.TP +.I symfil +The file name of the main binary. +.TP +.I symmap +The memory map of the main binary. +.TP +.I fhdrlist +A linked list (via the +.B Fhdr.next +fields) of all currently open headers +(see +.I symopen +in +.IR mach-symbol (3)). +When dynamically linked objects have been attached, +they are present in this linked list, +and therefore included in searches by +.IR indexsym , +.IR lookupsym , +and +.I findsym +(see +.IR mach-symbol (3)). +.TP +.I corhdr +The file header for the core dump, if any. +.TP +.I corfil +The file name of the core dump, if any. +.TP +.I cormap +The memory map of the core dump or attached process. +.TP +.I corpid +The process id of the attached process, if any. +.TP +.I correg +The register set of the core dump or attached process. +.PD +If these fields are not valid, they are zeroed. +.PP +.I Attachcore +and +.I attachproc +attach to an opened core file or an executing process. +They set +.IR corhdr , +.IR corfil , +.IR cormap , +.IR corpid , +and +.IR correg . +.PP +.I Proctextfile +returns the name of the main binary for the process with id +.IR pid . +.PP +.I Attachdynamic +requires that the memory image already be attached. +It reads the dynamic linker's internal run-time data structures +and then opens all the dynamic objects that are currently +loaded. +.PP +.I Attachargs +uses all of these functions while +parsing an argument vector as would be passed to +a debugger like +.IR db (1) +or +.IR acid (1). +It expects a list of executable files, core dump files, or process ids, +given in any order. +If extra arguments are given (for example, more than one executable, or both +a core dump and a process id), they are ignored and diagnostics are printed to +standard error. +If arguments are missing (for example, the process id is given without an +executable file), +.I attachargs +fills them in as best it can. +.SH SOURCE +.B /usr/local/plan9/src/libmach +.SH "SEE ALSO +.IR mach (3), +.IR mach-file (3), +.IR mach-map (3) +.SH BUGS +The interface needs to be changed to support +multiple threads, each with its own register set.
diff --git a/man/man3/mach-file.3 b/man/man3/mach-file.3 index f235815..17911ec 100644 --- a/man/man3/mach-file.3 +++ b/man/man3/mach-file.3
@@ -1,6 +1,6 @@ .TH MACH-FILE 3 .SH NAME -crackhdr, uncrackhdr, mapfile, mapproc, detachproc, ctlproc, +crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, detachproc, ctlproc, procnotes \- machine-independent access to exectuable files and running processes .SH SYNOPSIS .B #include <u.h> @@ -16,9 +16,13 @@ void uncrackhdr(Fhdr *hdr) .PP .ft B -int mapfile(Map *map, ulong base, Fhdr *hdr) +int mapfile(Fhdr *hdr, ulong base, Map *map, Regs **regs) .br -int mapproc(Map *map, int pid) +void unmapfile(Fhdr *hdr, Map *map) +.br +int mapproc(int pid, Map *map, Regs **regs) +.br +void unmapproc(Map *map) .br int detachproc(int pid) .br @@ -95,6 +99,12 @@ so this arrangement will use the core file for the segments it contains but fall back to the executable for the rest. .PP +.I Unmapfile +removes the mappings in +.I map +corresponding to +.IR hdr . +.PP .I Mapproc attaches to a running program and adds its segments to the given map. It adds one segment for each contiguous section of @@ -103,8 +113,14 @@ a single segment covering the entire address space. Accessing areas of this segment that are actually not mapped in the process address space will cause the get/put routines to return errors. +.PP +.I Unmapproc +removes the mappings in +.I map +corresponding to +.IR pid . .I Detachproc -detaches from a previously-attached program. +detaches from all previously attached processes. .PP .I Ctlproc manipulates the process with id @@ -143,7 +159,9 @@ The memory at .BI * notes should be freed via -.IR free (3) +.I free +(see +.IR malloc (3)) when no longer needed. .SH SOURCE .B /usr/local/plan9/src/libmach
diff --git a/man/man3/mach-map.3 b/man/man3/mach-map.3 index 8175e13..2fc8cc7 100644 --- a/man/man3/mach-map.3 +++ b/man/man3/mach-map.3
@@ -4,10 +4,9 @@ addrtosegafter, removeseg, freemap, get1, get2, get4, get8, put1, put2, put4, put8, -rget1, rget2, rget4, rget8, -rput1, rput2, rput4, rput8, -locaddr, locconst, locreg, locindir, -loccmp, loceval, locfmt, locredir, +rget, rput, fpformat, +locnone, locaddr, locconst, locreg, locindir, +loccmp, loceval, locfmt, locsimplify, lget1, lget2, lget4, lget8, lput1, lput2, lput4, lput8 \- machine-independent access to address spaces and register sets @@ -80,26 +79,16 @@ int put8(Map *map, ulong addr, u64int u) .PP .ft B -int rget1(Map *map, char *reg, u8int *u) -.br -int rget2(Map *map, char *reg, u16int *u) -.br -int rget4(Map *map, char *reg, u32int *u) -.br -int rget8(Map *map, char *reg, u64int *u) +int rget(Regs *regs, char *reg, ulong *u) .br int fpformat(Map *map, char *reg, char *a, uint n, char code); .PP .ft B -int rput1(Map *map, char *reg, u8int u) -.br -int rput2(Map *map, char *reg, u16int u) -.br -int rput4(Map *map, char *reg, u32int u) -.br -int rput8(Map *map, char *reg, u64int u) +int rput(Regs *regs, char *name, ulong u) .PP .ft B +Loc locnone(void) +.br Loc locaddr(ulong addr) .br Loc locconst(ulong con) @@ -115,7 +104,7 @@ .br int locfmt(Fmt *fmt) .br -int locredir(Map *map, Loc *regs, Loc loc, Loc *newloc) +int locsimplify(Map *map, Loc *regs, Loc loc, Loc *newloc) .PP .ft B int lget1(Map *map, Loc loc, uchar *a, uint n) @@ -297,20 +286,15 @@ .PP When representing core files or running programs, maps also provide access to the register set. -.IR Rget1 , -.IR rget2 , -.IR rget4 , -.IR rget8 , -.IR rput1 , -.IR rput2 , -.IR rput4 , -and -.IR rput8 -read or write the 1-, 2-, 4-, or 8-byte register +.IR Rget +and +.IR rput +read or write the register named by .IR reg . -If the register is not the requested size, the -behavior is undefined. +If the register is smaller than a +.BR ulong , +the high bits are ignored. .PP .I Fpformat converts the contents of a floating-point register to a string. @@ -418,3 +402,8 @@ .SH DIAGNOSTICS These routines set .IR errstr . +.SH BUGS +This man page needs to describe +.B Regs +and +.B Regdesc
diff --git a/man/man3/mach-stack.3 b/man/man3/mach-stack.3 index e17c6cb..caae6bf 100644 --- a/man/man3/mach-stack.3 +++ b/man/man3/mach-stack.3
@@ -1,7 +1,6 @@ .TH MACH-STACK 3 .SH NAME -stacktrace, -localaddr, +stacktrace, localaddr, unwindframe, windindex, windreglocs \- stack traces .SH SYNOPSIS .B #include <u.h> .br @@ -14,7 +13,16 @@ int stacktrace(Map *map, Rgetter rget, Tracer trace) .PP .ft B -int localvar(Map *map, char *fn, char *val, Loc *loc) +int localaddr(Map *map, Regs *regs, char *fn, char *val, ulong *val) +.PP +.ft B +int unwindframe(Map *map, Regs *regs, ulong *next, Symbol *sym) +.PP +.ft B +int windindex(char *regname) +.PP +.ft B +Loc* windreglocs(void) .SH DESCRIPTION .I Stacktrace provides machine-independent @@ -80,7 +88,7 @@ .IR lget4 , etc., when evaluating the locations of local variables. .PP -.I Localvar +.I Localaddr uses .I stacktrace to walk up the stack looking for the innermost instance of a function named @@ -88,8 +96,46 @@ once it finds the function, it looks for the parameter or local variable .IR var , -storing the location of the variable in -.IR loc . +storing the address of the variable in +.IR val . +.PP +.I Unwindframe +is the low-level function on which +.I stacktrace +is built. +Given the current memory image in +.I map +and the current register set in +.I regs , +.I unwindframe +fills in +.I next +with the values of the register set +at the time of the call to the function in the current program counter. +.I Sym +should be the symbol corresponding to the current function, +if available. +.PP +The +.I next +array holds only the +.IR "winding registers" , +typically the caller-save registers and the program counter and stack pointer. +The order of registers in the array is called the +.IR "winding order" . +The winding set can be found in the array +.IB mach -> windreg \fR, +which has +.IB mach -> nwindreg +entries. +.I Windindex +returns the index of the named register +in the winding order. +.I Windreglocs +returns an array of +.I Loc +structures corresponding to the winding registers, +in the winding order. .SH EXAMPLE The following code writes a simple stack trace to standard output, stopping after at most 20 stack frames. @@ -135,3 +181,5 @@ .B /usr/local/plan9/src/libmach .SH SEE ALSO .IR mach (3) +.SH BUGS +Need to talk about Regs
diff --git a/man/man3/mach-symbol.3 b/man/man3/mach-symbol.3 index ad208ce..c74ae8e 100644 --- a/man/man3/mach-symbol.3 +++ b/man/man3/mach-symbol.3
@@ -1,6 +1,7 @@ .TH MACH-SYMBOL 3 .SH NAME -symopen, symclose, indexsym, lookupsym, findsym, +symopen, symclose, findhdr, indexsym, lookupsym, findsym, +findexsym, flookupsym, ffindsym, lookuplsym, indexlsym, findlsym, symoff, pc2file, file2pc, line2pc, fnbound, fileline, pc2line \- symbol table access functions @@ -11,11 +12,15 @@ .br .B #include <mach.h> .PP -.ta \w'\fBxxxxxx'u +\w'\fBxxxxxx'u +.ta \w'\fBxxxxxxxx'u +\w'\fBxxxxxx'u .ft B int symopen(Fhdr *hdr) .br void symclose(Fhdr *hdr) +.br +Fhdr *findhdr(char *name) +.br +extern Fhdr* fhdrlist; .PP .ft B int indexsym(uint n, Symbol *s) @@ -25,6 +30,13 @@ int findsym(Loc loc, uint class, Symbol *s) .PP .ft B +int findexsym(Fhdr *hdr, uint n, Symbol *s) +.br +Symbol *flookupsym(Fhdr *hdr, char *name) +.br +Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class) +.PP +.ft B int indexlsym(Symbol *s1, uint n, Symbol *s2) .br int lookuplsym(Symbol *s1, char *name, Symbol *s2) @@ -70,6 +82,25 @@ The rest of the functions described here access a composite symbol table made up of all currently open tables. .PP +The set of all currently open +.BR Fhdr s +is maintained as a linked list starting at +.I fhdrlist +(chained via +.BR Fhdr.next ). +.PP +.I Findhdr +searches the currently open +.BR Fhdr s +for one whose file name ends with the path +.I name +(that is, +.B libc.so +matches +.B /usr/lib/libc.so +but not +.BR mylibc.so ). +.PP The .B Symbol data structure: @@ -190,10 +221,28 @@ .B CANY searches the text table first, then the global table. .PP +.IR Findexsym , +.IR flookupsym , +and +.I ffindsym +are similar to +.IR indexsym , +.IR lookupsym , +and +.IR findsym , +but operate only on the symbols from +.IR hdr . +.I Flookupsym +and +.I ffindsym +return pointers to data stored in the +.IR hdr , +which must not be modified or freed. +.PP .IR Indexlsym , .IR lookuplsym , and -.IR findlsym +.I findlsym are similar to .IR indexsym , .IR lookupsym ,
diff --git a/man/man3/mach.3 b/man/man3/mach.3 index 3891852..1814789 100644 --- a/man/man3/mach.3 +++ b/man/man3/mach.3
@@ -54,24 +54,37 @@ information in the binary files themselves and adjust accordingly. .PP +The supported architectures are +.B 386 +(Intel 32-bit x86) +386 and later) +and +.B power +(IBM PowerPC, typically running +Mac OS X). +.PP Other manual pages describe the library functions in detail. .PP -.I Mach-file (3) +.IR Mach-cmd (3) +describes some convenience routines for attaching to +processes and core files. +.PP +.IR Mach-file (3) describes the manipulation of binary files. .PP -.I Mach-map (3) +.IR Mach-map (3) describes the interface to address spaces and register sets in executable files and executing programs. .PP -.I Mach-stack (3) +.IR Mach-stack (3) describes support for unwinding the stack. .PP -.I Mach-swap (3) +.IR Mach-swap (3) describes helper functions for accessing data in a particular byte order. .PP -.I Mach-symbol (3) +.IR Mach-symbol (3) describes the interface to debugging symbol information. .SH SOURCE .B /usr/local/plan9/src/libmach
diff --git a/man/man3/malloc.3 b/man/man3/malloc.3 index 54e9ecc..01493c7 100644 --- a/man/man3/malloc.3 +++ b/man/man3/malloc.3
@@ -1,6 +1,6 @@ .TH MALLOC 3 .SH NAME -malloc, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock \- memory allocator +malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, getmalloctag, getrealloctag \- memory allocator .SH SYNOPSIS .B #include <u.h> .br @@ -23,23 +23,16 @@ void* calloc(ulong nelem, ulong elsize) .PP .B -ulong msize(void *ptr) -.PP -.B void setmalloctag(void *ptr, ulong tag) .PP .B -ulong getmalloctag(void *ptr, ulong tag) +ulong getmalloctag(void *ptr) .PP .B void setrealloctag(void *ptr, ulong tag) .PP .B -ulong getrealloctag(void *ptr, ulong tag) -.PP -.B -void* malloctopoolblock(void*) -.PP +ulong getrealloctag(void *ptr) .SH DESCRIPTION .I Malloc and @@ -109,12 +102,7 @@ .I Free frees such a block. .PP -When a block is allocated, sometimes there is some extra unused space at the end. -.I Msize -grows the block to encompass this unused space and returns the new number -of bytes that may be used. -.PP -The memory allocator maintains two word-sized fields +The memory allocator on Plan 9 maintains two word-sized fields associated with each block, the ``malloc tag'' and the ``realloc tag''. By convention, the malloc tag is the PC that allocated the block, and the realloc tag the PC that last reallocated the block. @@ -137,24 +125,15 @@ .IR setmalloctag ) to provide more useful information about the source of allocation. -.PP -.I Malloctopoolblock -takes the address of a block returned by -.I malloc -and returns the address of the corresponding -block allocated by the -.IR pool (3) -routines. .SH SOURCE -.B /usr/local/plan9/src/libc/port/malloc.c +.B /usr/local/plan9/src/lib9/malloc.c +.br +.B /usr/local/plan9/src/lib9/malloctag.c .SH SEE ALSO -.IR leak (1), .I trump (in .IR acid (1)), -.IR brk (3), -.IR getcallerpc (3), -.IR pool (3) +.IR getcallerpc (3) .SH DIAGNOSTICS .I Malloc, realloc and @@ -169,22 +148,6 @@ return .BR ~0 . .PP -After including -.BR pool.h , -the call -.B poolcheck(mainmem) -can be used to scan the storage arena for inconsistencies -such as data written beyond the bounds of allocated blocks. -It is often useful to combine this with with setting -.EX - mainmem->flags |= POOL_NOREUSE; -.EE -at the beginning of your program. -This will cause malloc not to reallocate blocks even -once they are freed; -.B poolcheck(mainmem) -will then detect writes to freed blocks. -.PP The .I trump library for @@ -198,7 +161,7 @@ .PP User errors can corrupt the storage arena. The most common gaffes are (1) freeing an already freed block, -(3) storing beyond the bounds of an allocated block, and (3) +(2) storing beyond the bounds of an allocated block, and (3) freeing data that was not obtained from the allocator. When .I malloc
diff --git a/man/man3/matrix.3 b/man/man3/matrix.3 new file mode 100644 index 0000000..87ba34c --- /dev/null +++ b/man/man3/matrix.3
@@ -0,0 +1,350 @@ +.TH MATRIX 3 +.SH NAME +ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, xform, ixform, persp, look, viewport \- Geometric transformations +.SH SYNOPSIS +.PP +.B +#include <draw.h> +.PP +.B +#include <geometry.h> +.PP +.B +void ident(Matrix m) +.PP +.B +void matmul(Matrix a, Matrix b) +.PP +.B +void matmulr(Matrix a, Matrix b) +.PP +.B +double determinant(Matrix m) +.PP +.B +void adjoint(Matrix m, Matrix madj) +.PP +.B +double invertmat(Matrix m, Matrix inv) +.PP +.B +Point3 xformpoint(Point3 p, Space *to, Space *from) +.PP +.B +Point3 xformpointd(Point3 p, Space *to, Space *from) +.PP +.B +Point3 xformplane(Point3 p, Space *to, Space *from) +.PP +.B +Space *pushmat(Space *t) +.PP +.B +Space *popmat(Space *t) +.PP +.B +void rot(Space *t, double theta, int axis) +.PP +.B +void qrot(Space *t, Quaternion q) +.PP +.B +void scale(Space *t, double x, double y, double z) +.PP +.B +void move(Space *t, double x, double y, double z) +.PP +.B +void xform(Space *t, Matrix m) +.PP +.B +void ixform(Space *t, Matrix m, Matrix inv) +.PP +.B +int persp(Space *t, double fov, double n, double f) +.PP +.B +void look(Space *t, Point3 eye, Point3 look, Point3 up) +.PP +.B +void viewport(Space *t, Rectangle r, double aspect) +.SH DESCRIPTION +These routines manipulate 3-space affine and projective transformations, +represented as 4\(mu4 matrices, thus: +.IP +.EX +.ta 6n +typedef double Matrix[4][4]; +.EE +.PP +.I Ident +stores an identity matrix in its argument. +.I Matmul +stores +.I a\(mub +in +.IR a . +.I Matmulr +stores +.I b\(mua +in +.IR b . +.I Determinant +returns the determinant of matrix +.IR m . +.I Adjoint +stores the adjoint (matrix of cofactors) of +.I m +in +.IR madj . +.I Invertmat +stores the inverse of matrix +.I m +in +.IR minv , +returning +.IR m 's +determinant. +Should +.I m +be singular (determinant zero), +.I invertmat +stores its +adjoint in +.IR minv . +.PP +The rest of the routines described here +manipulate +.I Spaces +and transform +.IR Point3s . +A +.I Point3 +is a point in three-space, represented by its +homogeneous coordinates: +.IP +.EX +typedef struct Point3 Point3; +struct Point3{ + double x, y, z, w; +}; +.EE +.PP +The homogeneous coordinates +.RI ( x , +.IR y , +.IR z , +.IR w ) +represent the Euclidean point +.RI ( x / w , +.IR y / w , +.IR z / w ) +if +.IR w ≠0, +and a ``point at infinity'' if +.IR w =0. +.PP +A +.I Space +is just a data structure describing a coordinate system: +.IP +.EX +typedef struct Space Space; +struct Space{ + Matrix t; + Matrix tinv; + Space *next; +}; +.EE +.PP +It contains a pair of transformation matrices and a pointer +to the +.IR Space 's +parent. The matrices transform points to and from the ``root +coordinate system,'' which is represented by a null +.I Space +pointer. +.PP +.I Pushmat +creates a new +.IR Space . +Its argument is a pointer to the parent space. Its result +is a newly allocated copy of the parent, but with its +.B next +pointer pointing at the parent. +.I Popmat +discards the +.B Space +that is its argument, returning a pointer to the stack. +Nominally, these two functions define a stack of transformations, +but +.B pushmat +can be called multiple times +on the same +.B Space +multiple times, creating a transformation tree. +.PP +.I Xformpoint +and +.I Xformpointd +both transform points from the +.B Space +pointed to by +.I from +to the space pointed to by +.IR to . +Either pointer may be null, indicating the root coordinate system. +The difference between the two functions is that +.B xformpointd +divides +.IR x , +.IR y , +.IR z , +and +.I w +by +.IR w , +if +.IR w ≠0, +making +.RI ( x , +.IR y , +.IR z ) +the Euclidean coordinates of the point. +.PP +.I Xformplane +transforms planes or normal vectors. A plane is specified by the +coefficients +.RI ( a , +.IR b , +.IR c , +.IR d ) +of its implicit equation +.IR ax+by+cz+d =0. +Since this representation is dual to the homogeneous representation of points, +.B libgeometry +represents planes by +.B Point3 +structures, with +.RI ( a , +.IR b , +.IR c , +.IR d ) +stored in +.RI ( x , +.IR y , +.IR z , +.IR w ). +.PP +The remaining functions transform the coordinate system represented +by a +.BR Space . +Their +.B Space * +argument must be non-null \(em you can't modify the root +.BR Space . +.I Rot +rotates by angle +.I theta +(in radians) about the given +.IR axis , +which must be one of +.BR XAXIS , +.B YAXIS +or +.BR ZAXIS . +.I Qrot +transforms by a rotation about an arbitrary axis, specified by +.B Quaternion +.IR q . +.PP +.I Scale +scales the coordinate system by the given scale factors in the directions of the three axes. +.IB Move +translates by the given displacement in the three axial directions. +.PP +.I Xform +transforms the coordinate system by the given +.BR Matrix . +If the matrix's inverse is known +.I a +.IR priori , +calling +.I ixform +will save the work of recomputing it. +.PP +.I Persp +does a perspective transformation. +The transformation maps the frustum with apex at the origin, +central axis down the positive +.I y +axis, and apex angle +.I fov +and clipping planes +.IR y = n +and +.IR y = f +into the double-unit cube. +The plane +.IR y = n +maps to +.IR y '=-1, +.IR y = f +maps to +.IR y '=1. +.PP +.I Look +does a view-pointing transformation. The +.B eye +point is moved to the origin. +The line through the +.I eye +and +.I look +points is aligned with the y axis, +and the plane containing the +.BR eye , +.B look +and +.B up +points is rotated into the +.IR x - y +plane. +.PP +.I Viewport +maps the unit-cube window into the given screen viewport. +The viewport rectangle +.I r +has +.IB r .min +at the top left-hand corner, and +.IB r .max +just outside the lower right-hand corner. +Argument +.I aspect +is the aspect ratio +.RI ( dx / dy ) +of the viewport's pixels (not of the whole viewport). +The whole window is transformed to fit centered inside the viewport with equal +slop on either top and bottom or left and right, depending on the viewport's +aspect ratio. +The window is viewed down the +.I y +axis, with +.I x +to the left and +.I z +up. The viewport +has +.I x +increasing to the right and +.I y +increasing down. The window's +.I y +coordinates are mapped, unchanged, into the viewport's +.I z +coordinates. +.SH SOURCE +.B /usr/local/plan9/src/libgeometry/matrix.c +.SH "SEE ALSO +.IR arith3 (3)
diff --git a/man/man3/memdraw.3 b/man/man3/memdraw.3 index 78c4859..4b59428 100644 --- a/man/man3/memdraw.3 +++ b/man/man3/memdraw.3
@@ -231,9 +231,9 @@ .B Memdata points back at the .B Memdata -structure, so that the +structure, so that in the Plan 9 kernel, the memory allocator (see -.IR pool (3)) +Plan 9's \fIpool\fR(3)) can compact image memory using .IR memimagemove . @@ -294,7 +294,7 @@ to file descriptor .IR fd . For more on bitmap formats, see -.IR image (6). +.IR image (7). .I Freememimage frees images returned by any of these routines. The @@ -433,7 +433,7 @@ .I iprint prints to a serial line rather than the screen, for obvious reasons. .SH SOURCE -.B /usr/local/plan9/src/libmemdraw +.B /usr/local/plan9/src/libdraw .SH SEE ALSO .IR addpt (3), .IR color (3), @@ -442,9 +442,14 @@ .IR memlayer (3), .IR stringsize (3), .IR subfont (3), -.IR color (6), -.IR utf (6) +.IR color (7), +.IR utf (7) .SH BUGS .I Memimagestring is unusual in using a subfont rather than a font, and in having no parameter to align the source. +.PP +.I Libmemdraw +is archived into +.IR libdraw . +
diff --git a/man/man3/memlayer.3 b/man/man3/memlayer.3 index 523253a..90e63e5 100644 --- a/man/man3/memlayer.3 +++ b/man/man3/memlayer.3
@@ -294,12 +294,16 @@ .I buf are in compressed image format (see -.IR image (6)). +.IR image (7)). .SH SOURCE -.B /usr/local/plan9/src/libmemlayer +.B /usr/local/plan9/src/libdraw .SH SEE ALSO .IR graphics (3), .IR memdraw (3), .IR stringsize (3), .IR window (3), .IR draw (3) +.SH BUGS +.I Libmemlayer +is archived into +.IR libdraw .
diff --git a/man/man3/memory.3 b/man/man3/memory.3 new file mode 100644 index 0000000..746dc7d --- /dev/null +++ b/man/man3/memory.3
@@ -0,0 +1,126 @@ +.TH MEMORY 3 +.SH NAME +memccpy, memchr, memcmp, memcpy, memmove, memset \- memory operations +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.ta \w'\fLvoid* 'u +.B +void* memccpy(void *s1, void *s2, int c, long n) +.PP +.B +void* memchr(void *s, int c, long n) +.PP +.B +int memcmp(void *s1, void *s2, long n) +.PP +.B +void* memcpy(void *s1, void *s2, long n) +.PP +.B +void* memmove(void *s1, void *s2, long n) +.PP +.B +void* memset(void *s, int c, long n) +.SH DESCRIPTION +These functions operate efficiently on memory areas +(arrays of bytes bounded by a count, not terminated by a zero byte). +They do not check for the overflow of any receiving memory area. +.PP +.I Memccpy +copies bytes from memory area +.I s2 +into +.IR s1 , +stopping after the first occurrence of byte +.I c +has been copied, or after +.I n +bytes have been copied, whichever comes first. +It returns a pointer to the byte after +the copy of +.I c +in +.IR s1 , +or zero if +.I c +was not found in the first +.I n +bytes of +.IR s2 . +.PP +.I Memchr +returns a pointer to the first +occurrence of byte +.I c +in the first +.I n +bytes of memory area +.IR s, +or zero if +.I c +does not occur. +.PP +.I Memcmp +compares its arguments, looking at the first +.I n +bytes only, and returns an integer +less than, equal to, or greater than 0, +according as +.I s1 +is lexicographically less than, equal to, or +greater than +.IR s2 . +The comparison is bytewise unsigned. +.PP +.I Memcpy +copies +.I n +bytes from memory area +.I s2 +to +.IR s1 . +It returns +.IR s1 . +.PP +.I Memmove +works like +.IR memcpy , +except that it is guaranteed to work if +.I s1 +and +.IR s2 +overlap. +.PP +.I Memset +sets the first +.I n +bytes in memory area +.I s +to the value of byte +.IR c . +It returns +.IR s . +.SH SOURCE +All these routines have portable C implementations in +.BR /usr/local/plan9/src/lib9 . +.\" Most also have machine-dependent assembly language implementations in +.\" .BR /usr/local/plan9/lib9/$objtype . +.SH SEE ALSO +.IR strcat (3) +.SH BUGS +ANSI C does not require +.I memcpy +to handle overlapping source and destination; on Plan 9, it does, so +.I memmove +and +.I memcpy +behave identically. +.PP +If +.I memcpy +and +.I memmove +are handed a negative count, they abort.
diff --git a/man/man3/mousescrollsize.3 b/man/man3/mousescrollsize.3 new file mode 100644 index 0000000..915a6bb --- /dev/null +++ b/man/man3/mousescrollsize.3
@@ -0,0 +1,62 @@ +.TH MOUSESCROLLSIZE 3 +.SH NAME +mousescrollsize \- compute mouse scroll increment +.SH SYNOPSIS +.B #include <draw.h> +.PP +int mousescrollsize(int maxlines) +.SH DESCRIPTION +.I Mousescrollsize +computes the number of lines of text that should be scrolled +in response to a mouse scroll wheel click. +.I Maxlines +is the number of lines visible in the text window. +.PP +The default scroll increment is one line. +This default can be overridden by setting the +.B $mousescrollsize +environment variable to an integer, which specifies +a constant number of lines, or to a real number +followed by a percent character, indicating that the +scroll increment should be a percentage of the total +number of lines in the window. +For example, setting +.B $mousescrollsize +to +.B 50% +causes a half-window scroll increment. +.PP +.I Mousescrollsize +is used by +.IR 9term (1) +and +.IR acme (1) +to set their scrolling behavior. +.SH SOURCE +.B /usr/local/plan9/src/libdraw/scroll.c +.SH SEE ALSO +.IR 9term (1), +.IR acme (1) +.SH BUGS +.I Libdraw +expects up and down scroll wheel events to be expressed as clicks of mouse buttons 4 and 5, +but the XFree86 default is to ignore the scroll wheel. +To enable the scroll wheel, change your +.B InputDevice +section of +.B XF86Config-4 +to look like: +.IP +.EX +Section "InputDevice" + Identifier "Mouse0" + Driver "mouse" + Option "Device" "/dev/psaux" + + # next four lines enable scroll wheel as buttons 4 and 5 + Option "Buttons" "5" + Option "Emulate3Buttons" "off" + Option "Protocol" "ImPS/2" + Option "ZAxisMapping" "4 5" +EndSection +.EE
diff --git a/man/man3/mp.3 b/man/man3/mp.3 index 420f0ba..9a4ed84 100644 --- a/man/man3/mp.3 +++ b/man/man3/mp.3
@@ -1,7 +1,6 @@ .TH MP 3 .SH NAME - -mpsetminbits, mpnew, mpfree, mpbits, mpnorm, mpcopy, mpassign, mprand, strtomp, mpfmt,mptoa, betomp, mptobe, letomp, mptole, mptoui, uitomp, mptoi, itomp, uvtomp, mptouv, vtomp, mptov, mpdigdiv, mpadd, mpsub, mpleft, mpright, mpmul, mpexp, mpmod, mpdiv, mpcmp, mpextendedgcd, mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, crtpre, crtin, crtout, crtprefree, crtresfree \- extended precision arithmetic +mpsetminbits, mpnew, mpfree, mpbits, mpnorm, mpcopy, mpassign, mprand, strtomp, mpfmt,mptoa, betomp, mptobe, letomp, mptole, mptoui, uitomp, mptoi, itomp, uvtomp, mptouv, vtomp, mptov, mpdigdiv, mpadd, mpsub, mpleft, mpright, mpmul, mpexp, mpmod, mpdiv, mpcmp, mpextendedgcd, mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, crtpre, crtin, crtout, crtprefree, crtresfree, mpfactorial \- extended precision arithmetic .SH SYNOPSIS .B #include <u.h> .br @@ -163,6 +162,9 @@ void crtresfree(CRTres *res) .PP .B +mpint* mpfactorial(ulong n) +.PP +.B mpint *mpzero, *mpone, *mptwo .SH DESCRIPTION .PP @@ -573,5 +575,9 @@ and .I CRTres structures respectively. +.PP +.I Mpfactorial +returns the factorial of +.IR n . .SH SOURCE .B /usr/local/plan9/src/libmp
diff --git a/man/man3/mux.3 b/man/man3/mux.3 new file mode 100644 index 0000000..cc8de4d --- /dev/null +++ b/man/man3/mux.3
@@ -0,0 +1,154 @@ +.TH MUX 3 +.SH NAME +Mux, muxinit, muxrpc, muxthreads \- protocol multiplexor +.SH SYNOPSIS +.B #include <mux.h> +.PP +.nf +.B +.ta +4n +struct Mux +{ + uint mintag; + uint maxtag; + int (*settag)(Mux *mux, void *msg, uint tag); + int (*gettag)(Mux *mux, void *msg); + int (*send)(Mux *mux, void *msg); + void *(*recv)(Mux *mux); + void *aux; + + \&... /* private fields follow */ +}; +.ta +\w'\fLvoid* 'u +.PP +.B +void muxinit(Mux *mux); +.PP +.B +void* muxrpc(Mux *mux, void *request); +.PP +.B +void muxprocs(Mux *mux); +.SH DESCRIPTION +.I Libmux +is a generic protocol multiplexor. +A client program initializes a +.B Mux +structure with information about the protocol +(mainly in the form of helper functions) +and can then use +.I muxrpc +to execute individual RPCs without worrying +about details of multiplexing requests +and demultiplexing responses. +.PP +.I Libmux +assumes that the protocol messages contain a +.I tag +(or message ID) field that exists for the sole purpose of demultiplexing messages. +.I Libmux +chooses the tags and then calls a helper function +to put them in the outgoing messages. +.I Libmux +calls another helper function to retrieve tags +from incoming messages. +It also calls helper functions to send and receive packets. +.PP +A client should allocate a +.B Mux +structure and then call +.I muxinit +to initialize the library's private elements. +The client must initialize the following elements: +.TP +.I mintag\fR, \fPmaxtag +The range of valid tags; +.I maxtag +is the maximum valid tag plus one, so that +.IR maxtag \- mintag +is equal to the number of valid tags. +If +.I libmux +runs out of tags +(all tags are being used for RPCs currently in progress), +a new call to +.IR muxrpc +will block until an executing call finishes. +.TP +.I settag\fR, \fPgettag +Set or get the tag value in a message. +.TP +.I send\fR, \fPrecv +Send or receive protocol messages on the connection. +.I Recv +should block until a message is available and +should return nil if the connection is closed. +.I Libmux +will arrange that only one call to +.I recv +is active at a time. +.TP +.I aux +An auxiliary pointer for use by the client. +.PD +Once a client has initialized the +.B Mux +structure, it can call +.I muxrpc +to execute RPCs. +The +.I request +is the message passed to +.I settag +and +.IR send . +The return value is the response packet, +as provided by +.IR recv , +or +nil if an error occurred. +.I Muxprocs +allocates new procs +(see +.IR thread (3)) +in which to run +.I send +and +.IR recv . +After a call to +.IR muxprocs , +.I muxrpc +will run +.I send +and +.I recv +in these procs instead of in the calling proc. +This is useful if the implementation of +either (particularly +.IR recv ) +blocks an entire proc +and there are other threads in the calling proc +that need to remain active. +.SH EXAMPLE +See +.B /usr/local/plan9/src/lib9pclient/fs.c +for an example of using +.I libmux +with +9P +(see +.IR intro (9p)). +.SH SOURCE +.B /usr/local/plan9/src/libmux +.SH SEE ALSO +.IR thread (3), +.IR intro (9p) +.SH BUGS +.I Libmux +does not know how to free protocol messages, +so message arriving with unexpected or invalid +tags are leaked. +.PP +Using +.I mintag +other than zero is not well tested and probably buggy.
diff --git a/man/man3/nan.3 b/man/man3/nan.3 index 2c77af0..69777e5 100644 --- a/man/man3/nan.3 +++ b/man/man3/nan.3
@@ -41,4 +41,4 @@ returns true if its first argument is infinity with the same sign as the second argument. .SH SOURCE -.B /usr/local/plan9/src/libc/port/nan.c +.B /usr/local/plan9/src/lib9/nan.c
diff --git a/man/man3/needstack.3 b/man/man3/needstack.3 new file mode 100644 index 0000000..31588f6 --- /dev/null +++ b/man/man3/needstack.3
@@ -0,0 +1,69 @@ +.TH NEEDSTACK 3 +.SH NAME +needstack \- check for execution stack overflow +.SH SYNOPSIS +.B +#include <u.h> +.PP +.B +#include <libc.h> +.PP +.B +int needstack(int n) +.SH DESCRIPTION +Stack overflow in the thread library leads to bugs that are +difficult to diagnose. +The Plan 9 libraries are careful about not allocating +large structures on the stack, so typically four or eight kilobytes is plenty of stack +for a thread. +Other libraries are not always as careful. +Calling +.I needstack +indicates to the thread library that an external routine is about +to be called that will require +.I n +bytes of stack space. +If there is not enough space left on the stack, +the thread library prints an error and terminates +the program. +The call +.B needstack(0) +can be used to check whether the stack is +currently overflowed. +.PP +.I Needstack +is defined in +.B libc.h +so that library functions used in threaded and non-threaded contexts +can call it. +The implementation of +.I needstack +in +.B lib9 +is a no-op. +.PP +.I Needstack +should be thought of as a comment checked at run time, +like +.IR assert (3). +.SH EXAMPLE +The X Window library implementation of +.I XLookupString +allocates some very large buffers on the stack, so +.B /usr/local/plan9/src/libdraw/x11-itrans.c +calls +.B needstack(20*1024) +before making calls to +.IR XLookupString . +If a thread (in this case, the keyboard-reading thread used +inside the +.IR draw (3) +library) +does not allocate a large enough stack, the problem is diagnosed +immediately rather than left to corrupt memory. +.SH SOURCE +.B /usr/local/plan9/src/lib9/needstack.c +.br +.B /usr/local/plan9/src/libthread +.SH SEE ALSO +.IR thread (3)
diff --git a/man/man3/notify.3 b/man/man3/notify.3 index 0286ea8..41b8452 100644 --- a/man/man3/notify.3 +++ b/man/man3/notify.3
@@ -1,6 +1,6 @@ .TH NOTIFY 3 .SH NAME -notify, noted, atnotify \- handle asynchronous process notification +notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff \- handle asynchronous process notification .SH SYNOPSIS .B #include <u.h> .br @@ -14,36 +14,34 @@ .PP .B int atnotify(int (*f)(void*, char*), int in) +.PP +.B +int noteenable(char *msg) +.br +.B +int notedisable(char *msg) +.PP +.B +int notifyon(char *msg) +.br +.B +int notifyoff(char *msg) .SH DESCRIPTION When a process raises an exceptional condition such as dividing by zero or writing on a closed pipe, a .I note is posted to communicate the exception. -A note may also be posted by a -.I write -(see -.IR read (3)) -to the process's -.BI /proc/ n /note -file or to the -.BI /proc/ m /notepg -file of a process in the same process group (see -.IR proc (3)). -When the note is received -the behavior of the process depends on the origin of the note. -If the note was posted by an external process, -the process receiving the note exits; -if generated by the system the note string, -preceded by the name -and id of the process and the string -\fL"suicide: "\fP, -is printed on the process's standard error file -and the -process is suspended in the -.B Broken -state for debugging. +A note may also be posted by another process +via +.IR postnote (3). +On Unix, notes are implemented as signals. .PP -These default actions may be overridden. +When a note is received, the action taken depends on the note. +See +.IR signal (7) +for the full description of the defaults. +.PP +The default actions may be overridden. The .I notify function registers a @@ -55,7 +53,7 @@ An argument of zero cancels a previous handler, restoring the default action. A -.IR fork (3) +.IR fork (2) system call leaves the handler registered in both the parent and the child; .IR exec (3) @@ -64,20 +62,19 @@ .PP After a note is posted, the handler is called with two arguments: -the first is a pointer to a +the first is unimplemented and should not be used +(on Plan 9 +it is a .B Ureg -structure (defined in -.BR /$objtype/include/ureg.h ) -giving the current values of registers; +structure +giving the current values of registers); the second is a pointer to the note itself, -a null-terminated string with no more than -.L ERRLEN -characters in it including the terminal NUL. -The -.B Ureg -argument is usually not needed; it is provided to help recover from traps such -as floating point exceptions. -Its use and layout are machine- and system-specific. +a null-terminated string. +.\" The +.\" .B Ureg +.\" argument is usually not needed; it is provided to help recover from traps such +.\" as floating point exceptions. +.\" Its use and layout are machine- and system-specific. .PP A notification handler must finish either by exiting the program or by calling .IR noted ; @@ -115,14 +112,32 @@ using the .I notejmp function (see -.IR setjmp (3)), -which is implemented by modifying the saved state and calling -.BR noted(NCONT) . +.IR setjmp (3)). +.PP +Unix provides a fixed set of notes (typically there are 32) called +.IR signals . +It also allows a process to block certain notes from being delivered +(see +.IR sigprocmask (2)) +and to ignore certain notes by setting the signal hander to the special value +.B SIG_IGN +(see +.IR signal (2)). +.I Noteenable +and +.I notedisable +enable or disable receipt of a particular note by changing the current process's blocked signal mask. +Receipt of a disabled note will be postponed until it is reenabled. +.I Notifyon +and +.I notifyoff +enable or disable whether the notification handler +is called upon receipt of the note; if the handler is not called, the note is discarded. .PP Regardless of the origin of the note or the presence of a handler, if the process is being debugged (see -.IR proc (3)) +.IR ptrace (2)) the arrival of a note puts the process in the .B Stopped state and awakens the debugger. @@ -158,87 +173,67 @@ .I noted with argument .BR NDFLT . -.PP -.I Noted -has two other possible values for its argument. -.B NSAVE -returns from the handler and clears the note, enabling the receipt of another, -but does not return to the program. -Instead it starts a new handler with the same stack, stack pointer, -and arguments as the -original, at the address recorded in the program counter of the -.B Ureg -structure. Typically, the program counter will be overridden by the -first note handler to be the address of a separate function; -.B NSAVE -is then a `trampoline' to that handler. -That handler may executed -.B noted(NRSTR) -to return to the original program, usually after restoring the original program -counter. -.B NRSTR -is identical to -.BR NCONT -except that it can only be executed after an -.BR NSAVE . -.B NSAVE -and -.B NRSTR -are designed to improve the emulation of signals by the ANSI C/POSIX -environment; their use elsewhere is discouraged. +.\" .PP +.\" .I Noted +.\" has two other possible values for its argument. +.\" .B NSAVE +.\" returns from the handler and clears the note, enabling the receipt of another, +.\" but does not return to the program. +.\" Instead it starts a new handler with the same stack, stack pointer, +.\" and arguments as the +.\" original, at the address recorded in the program counter of the +.\" .B Ureg +.\" structure. Typically, the program counter will be overridden by the +.\" first note handler to be the address of a separate function; +.\" .B NSAVE +.\" is then a `trampoline' to that handler. +.\" That handler may executed +.\" .B noted(NRSTR) +.\" to return to the original program, usually after restoring the original program +.\" counter. +.\" .B NRSTR +.\" is identical to +.\" .BR NCONT +.\" except that it can only be executed after an +.\" .BR NSAVE . +.\" .B NSAVE +.\" and +.\" .B NRSTR +.\" are designed to improve the emulation of signals by the ANSI C/POSIX +.\" environment; their use elsewhere is discouraged. .PP The set of notes a process may receive is system-dependent, but there is a common set that includes: .PP .RS 3n .nf -.ta \w'\fLsys: write on closed pipe \fP'u -\fINote\fP \fIMeaning\fP -\fLinterrupt\fP user interrupt (DEL key) -\fLhangup\fP I/O connection closed -\fLalarm\fP alarm expired -\fLsys: breakpoint\fP breakpoint instruction -\fLsys: bad address\fP system call address argument out of range -\fLsys: odd address\fP system call address argument unaligned -\fLsys: bad sys call\fP system call number out of range -\fLsys: odd stack\fP system call user stack unaligned -\fLsys: write on closed pipe\fP write on closed pipe -\fLsys: fp: \fIfptrap\f1 floating point exception -\fLsys: trap: \fItrap\f1 other exception (see below) +.ta \w'\fLsys: write on closed pipe \fP'u \w'system call address argument out of range 'u +\fINote\fP \fIMeaning\fP \fIUnix signal\fP +\fLinterrupt\fP user interrupt (DEL key) SIGINTR +\fLhangup\fP I/O connection closed SIGHUP +\fLalarm\fP alarm expired SIGLARM +\fLquit\fP quit from keyboard SIGQUIT +\fLkill\fP process requested to exit SIGTERM +\fLsys: kill\fP process forced to exit SIGKILL +\fLsys: bus error\fP bus error SIGBUS +\fLsys: segmentation violation\fP segmentation violation SIGSEGV .fi .RE .PP +See +.B /usr/local/plan9/src/lib9/await.c +(sic) +for the full list. +.PP The notes prefixed .B sys: -are generated by the operating system. -They are suffixed by the user program counter in format -.BR pc=0x1234 . -If the note is due to a floating point exception, just before the -.BR pc -is the address of the offending instruction in format -.BR fppc=0x1234 . -Notes are limited to -.B ERRLEN -bytes; if they would be longer they are truncated but the -.B pc -is always reported correctly. -.PP -The types and syntax of the -.I trap -and -.I fptrap -portions of the notes are machine-dependent. +are usually generated by the operating system. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/notify.c .br -.B /usr/local/plan9/src/libc/port/atnotify.c +.B /usr/local/plan9/src/lib9/atnotify.c .SH SEE ALSO .IR intro (3), .I notejmp in .IR setjmp (3) -.SH BUGS -Since -.IR exec (3) -discards the notification handler, there is a window -of vulnerability to notes in a new process.
diff --git a/man/man3/open.3 b/man/man3/open.3 index 46b4fe5..b964cc9 100644 --- a/man/man3/open.3 +++ b/man/man3/open.3
@@ -94,7 +94,7 @@ Exclusive-use files may be open for I/O by only one client at a time, but the file descriptor may become invalid if no I/O is done for an extended period; see -.IR open (5). +.IR open (9p). .PP .I Create fails if the path up to the last element of @@ -106,12 +106,12 @@ of if there there are no free file descriptors. In the last case, the file may be created even when an error is returned. -If the file is new and the directory in which it is created is -a union directory (see -.IR intro (3)) -then the constituent directory where the file is created -depends on the structure of the union: see -.IR bind (3). +.\" If the file is new and the directory in which it is created is +.\" a union directory (see +.\" .IR intro (3)) +.\" then the constituent directory where the file is created +.\" depends on the structure of the union: see +.\" .IR bind (3). .PP Since .I create @@ -126,7 +126,7 @@ .IR create, the call succeeds only if the file does not already exist; see -.IR open (5) +.IR open (9p) for details. .PP .I Close @@ -138,10 +138,9 @@ .I close allows the file descriptor to be reused. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR intro (3), -.IR bind (3), .IR stat (3) .SH DIAGNOSTICS These functions set
diff --git a/man/man3/opentemp.3 b/man/man3/opentemp.3 new file mode 100644 index 0000000..23e77d3 --- /dev/null +++ b/man/man3/opentemp.3
@@ -0,0 +1,48 @@ +.TH OPENTEMP 3 +.SH NAME +opentemp \- create a uniquely-named file +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +int opentemp(char *template) +.SH DESCRIPTION +.I Opentemp +replaces +.I template +by a unique file name, and returns the +address of the template. +The template should look like a file name with eleven trailing +.LR X s. +The +.LR X s +are replaced by a letter followed by the current process id. +Letters from +.L a +to +.L z +are tried until the name of a file that does not yet exist +(see +.IR access (2)) +is generated. +.I Opentemp +then creates the file for reading and writing +and returns the file descriptor. +.PP +If no such name can be generated, +.I opentemp +returns \-1. +.PP +.I Opentemp +avoids races. +Two simultaneous calls to +.I opentemp +will never return the same name. +.SH SOURCE +.B /usr/local/plan9/src/lib9/opentemp.c +.SH "SEE ALSO +.I create +in +.IR open (3)
diff --git a/man/man3/pipe.3 b/man/man3/pipe.3 index 06d3769..993e33a 100644 --- a/man/man3/pipe.3 +++ b/man/man3/pipe.3
@@ -25,50 +25,76 @@ After the pipe has been established, cooperating processes created by subsequent -.IR fork (3) +.IR fork (2) calls may pass data through the pipe with .I read and .I write calls. -The bytes placed on a pipe -by one -.I write -are contiguous even if many processes are writing. -Write boundaries are preserved: each read terminates -when the read buffer is full or after reading the last byte -of a write, whichever comes first. -.PP -The number of bytes available to a -.IR read (3) -is reported -in the -.B Length -field returned by -.I fstat -or -.I dirfstat -on a pipe (see -.IR stat (3)). +.\" The bytes placed on a pipe +.\" by one +.\" .I write +.\" are contiguous even if many processes are writing. +.\" Write boundaries are preserved: each read terminates +.\" when the read buffer is full or after reading the last byte +.\" of a write, whichever comes first. +.\" .PP +.\" The number of bytes available to a +.\" .IR read (3) +.\" is reported +.\" in the +.\" .B Length +.\" field returned by +.\" .I fstat +.\" or +.\" .I dirfstat +.\" on a pipe (see +.\" .IR stat (3)). .PP When all the data has been read from a pipe and the writer has closed the pipe or exited, .IR read (3) will return 0 bytes. Writes to a pipe with no reader will generate a note .BR "sys: write on closed pipe" . .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/pipe.c .SH SEE ALSO .IR intro (3), -.IR read (3), -.IR pipe (3) +.IR read (3) .SH DIAGNOSTICS Sets .IR errstr . .SH BUGS If a read or a write of a pipe is interrupted, some unknown number of bytes may have been transferred. -.br -When a read from a pipe returns 0 bytes, it usually means end of file -but is indistinguishable from reading the result of an explicit -write of zero bytes. +.PP +.I Pipe +is a macro defined as +.I p9pipe +to avoid name conflicts with Unix's +.I pipe +system call. +.PP +Unix pipes are not guaranteed to be bidirectional. +In order to ensure a bidirectional channel, +.I p9pipe +creates Unix domain sockets via the +.IR socketpair (2) +instead of Unix pipes. +.PP +The implementation of pipes as Unix domain sockets +causes problems with some Unix implementations of +.BR /dev/fd , +Unix's dup device. If a Unix domain socket is open as file +descriptor 0, some implementations disallow the opening of +.BR /dev/fd/0 ; +instead one must +.IR connect (2) +to it. +If this functionality is important +(as it is for +.IR rc (1)), +one must +.B #undef +.B pipe +and fall back on the (possibly unidirectional) Unix pipes.
diff --git a/man/man3/plumb.3 b/man/man3/plumb.3 index f75acb3..c988bba 100644 --- a/man/man3/plumb.3 +++ b/man/man3/plumb.3
@@ -1,6 +1,6 @@ .TH PLUMB 3 .SH NAME -eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages +eplumb, plumbfree, plumbopen, plumbopenfid, plumbsend, plumbsendtofid, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages .SH SYNOPSIS .B #include <u.h> .br @@ -51,9 +51,21 @@ .PP .B int eplumb(int key, char *port) +.PP +.B +#include <9pclient.h> +.PP +.B +CFid *plumbopenfid(char *port, int omode) +.PP +.B +Plumbmsg* plumbrecvfid(CFid *fid) +.PP +.B +int plumbsendtofid(CFid *fid, Plumbmsg *m) .SH DESCRIPTION These routines manipulate -.IR plumb (6) +.IR plumb (7) messages, transmitting them, receiving them, and converting them between text and these data structures: .IP @@ -141,7 +153,7 @@ encodes message .I m as a character string in the format of -.IR plumb (6) , +.IR plumb (7) , setting .BI * np to the length in bytes of the string. @@ -226,15 +238,49 @@ and deletes it from the list, returning the resulting list. .I Plumbdelattr is a no-op if no such attribute exists. +.PP +The file descriptor returned by +.I plumbopen +is created with +.I fsopenfd +(see +.IR 9pclient (3)), +which masks information about read and write errors. +This is acceptable for use in +.I plumbrecv +but not for +.IR plumbsend , +which depends on seeing details of write errors. +.IR Plumbopenfid , +.IR plumbrecvfid , +and +.IR plumbsendtofid +provide an explicit interface to +.I lib9pclient +that preserves the exact error details. .SH SOURCE .B /usr/local/plan9/src/libplumb .SH SEE ALSO .IR plumb (1), .IR event (3), .IR plumber (4), -.IR plumb (6) +.IR plumb (7) .SH DIAGNOSTICS When appropriate, including when a .I plumbsend fails, these routine set .IR errstr . +.SH BUGS +To avoid rewriting clients that use +.IR plumbsend , +the call +.B plumbopen("send", +.B OWRITE) +returns a useless file descriptor +(it is opened to +.BR /dev/null ). +.I Plumbsend +looks for this particular file descriptor +and uses a static copy of the +.B CFid +instead.
diff --git a/man/man3/post9pservice.3 b/man/man3/post9pservice.3 new file mode 100644 index 0000000..74404c1 --- /dev/null +++ b/man/man3/post9pservice.3
@@ -0,0 +1,29 @@ +.TH POST9PSERVICE 3 +.SH NAME +post9pservice \- post 9P service for use by clients +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +int post9pservice(int fd, char *name) +.SH DESCRIPTION +.I Post9pservice +invokes +.IR 9pserve (4) +to post a new 9P service in the current +``name space'' +(see +.IR intro (4)) +named +.IR name . +Clients connecting to the posted service +are multiplexed onto a single 9P conversation with the server +on file descriptor +.IR fd . +.SH "SEE ALSO +.IR intro (4), +.IR 9pserve (4) +.SH SOURCE +.B /usr/local/plan9/src/lib9/post9p.c
diff --git a/man/man3/postnote.3 b/man/man3/postnote.3 index fed339b..535c7e6 100644 --- a/man/man3/postnote.3 +++ b/man/man3/postnote.3
@@ -19,17 +19,16 @@ .BR PNPROC , then .I note -is written to -.BI /proc/ pid /note\f1. +is sent to the process with id +.IR pid . If .I who is .BI PNGROUP , the note is delivered to the -process group by writing -.I note -to -.BI /proc/ pid /notepg\f1. +process group which has the process with id +.I pid +as a member. For .B PNGROUP only, if the calling process is in the target group, the note is @@ -39,11 +38,10 @@ If the write is successful, zero is returned. Otherwise \-1 is returned. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/postnote.c +.B /usr/local/plan9/src/lib9/postnote.c .SH "SEE ALSO" .IR notify (3), -.IR intro (3), -.IR proc (3) +.IR intro (3) .SH DIAGNOSTICS Sets .IR errstr .
diff --git a/man/man3/print.3 b/man/man3/print.3 index 1fab0ad..b1c8545 100644 --- a/man/man3/print.3 +++ b/man/man3/print.3
@@ -8,7 +8,7 @@ .ft R .. .SH NAME -print, fprint, sprint, snprint, seprint, smprint, vfprint, vsnprint, vseprint, vsmprint \- print formatted output +print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output .SH SYNOPSIS .B #include <utf.h> .PP
diff --git a/man/man3/proto.3 b/man/man3/proto.3 new file mode 100644 index 0000000..ab8d304 --- /dev/null +++ b/man/man3/proto.3
@@ -0,0 +1,131 @@ +.TH PROTO 3 +.SH NAME +rdproto \- parse and process a proto file listing +.SH SYNOPSIS +.nf +.ft L +#include <u.h> +#include <libc.h> +#include <disk.h> +.ft +.PP +.B +typedef void Protoenum(char *new, char *old, Dir *d, void *a) +.PP +.B +typedef void Protowarn(char *msg, void *a) +.PP +.B +int rdproto(char *proto, char *root, Protoenum *enm, +.br +.B + Protowarn *warn, void *a) +.SH DESCRIPTION +.I Rdproto +reads and interprets the named +.I proto +file relative to the +root directory +.IR root . +.PP +Each line of the +.I proto +file specifies a file to copy. +Blank lines and lines beginning with +.B # +are ignored. +Indentation (usually tabs) is significant, +with each level of indentation corresponding to a level in the file tree. +Fields within a line are separated by white space. +The first field is the last path element in the destination file tree. +The second field specifies the permissions. +The third field is the owner of the file, +and the fourth is the group owning the file. +The fifth field is the name of the file from which to copy; +this file is read from the current name space, +not the source file tree. +All fields except the first are optional. +Specifying +.B - +for permissions, owner, or group +causes +.I rdproto +to fetch the corresponding information +from the file rather than override it. +(This is the default behavior when the fields +are not present; explicitly specifying +.B - +is useful when one wishes to set, say, +the file owner without setting the permissions.) +.PP +Names beginning with a +.L $ +are expanded as environment variables. +If the first file specified in a directory is +.LR * , +all of the files in that directory are considered listed. +If the first file is +.LR + , +all of the files are copied, and all subdirectories +are recursively considered listed. +All files are considered relative to +.IR root . +.PP +For each file named by the +.IR proto , +.I enm +is called with +.I new +pointing at the name of the file (without the root prefix), +.I old +pointing at the name of the source file (with the root prefix, +when applicable), +and +.I Dir +at the desired directory information for the new file. +Only the +.BR name , +.BR uid , +.BR gid , +.BR mode , +.BR mtime , +and +.B length +fields are guaranteed to be valid. +The argument +.I a +is the same argument passed to +.IR rdproto ; +typically it points at some extra state +used by the enumeration function. +.PP +When files or directories do not exist or +cannot be read by +.IR rdproto , +it formats a warning message, calls +.IR warn , +and continues processing; +if +.I warn +is nil, +.I rdproto +prints the warning message to standard error. +.PP +.I Rdproto +returns zero +if +.I proto +was processed, \-1 if it could not be opened. +.SH FILES +.TF /sys/lib/sysconfig/proto/portproto +.TP +.B /sys/lib/sysconfig/proto/ +directory of prototype files. +.TP +.B /sys/lib/sysconfig/proto/portproto +generic prototype file. +.SH SOURCE +.B /usr/local/plan9/src/libdisk/proto.c +.SH SEE ALSO +.IR mk9660 (8), +Plan 9's \fImkfs\fR(8)
diff --git a/man/man3/pushtls.3 b/man/man3/pushtls.3 new file mode 100644 index 0000000..b92dcb6 --- /dev/null +++ b/man/man3/pushtls.3
@@ -0,0 +1,196 @@ +.TH PUSHTLS 3 +.SH NAME +pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +int pushtls(int fd, char *hashalg, char *encalg, +.br +.B + int isclient, char *secret, char *dir) +.PP +.B #include <mp.h> +.br +.B #include <libsec.h> +.PP +.B +int tlsClient(int fd, TLSconn *conn) +.PP +.B +int tlsServer(int fd, TLSconn *conn) +.PP +.B +uchar *readcert(char *filename, int *pcertlen) +.PP +.B +PEMchain *readcertchain(char *filename) +.PP +.B +Thumbprint* initThumbprints(char *ok, char *crl) +.PP +.B +void freeThumbprints(Thumbprint *table) +.PP +.B +int okThumbprint(uchar *hash, Thumbprint *table) +.SH DESCRIPTION +Transport Layer Security (TLS) comprises a record layer protocol, +doing message digesting and encrypting in the kernel, +and a handshake protocol, +doing initial authentication and secret creation at +user level and then starting a data channel in the record protocol. +TLS is nearly the same as SSL 3.0, and the software should interoperate +with implementations of either standard. +.PP +To use just the record layer, as described in Plan 9's +\fItls\fR(3), +call +.I pushtls +to open the record layer device, connect to the communications channel +.IR fd , +and start up encryption and message authentication as specified +in +.IR hashalg , +.IR encalg , +and +.IR secret . +These parameters must have been arranged at the two ends of the +conversation by other means. +For example, +.I hashalg +could be +.BR sha1 , +.I encalg +could be +.BR rc4_128 , +and +.I secret +could be the base-64 encoding of two (client-to-server and server-to-client) +20-byte digest keys and two corresponding 16-byte encryption keys. +.I Pushtls +returns a file descriptor for the TLS data channel. Anything written to this +descriptor will get encrypted and authenticated and then written to the +file descriptor, +.IR fd . +If +.I dir +is non-zero, the path name of the connection directory is copied into +.IR dir . +This path name is guaranteed to be less than 40 bytes long. +.PP +Alternatively, call +.I tlsClient +to speak the full handshake protocol, +negotiate the algorithms and secrets, +and return a new data file descriptor for the data channel. +.I Conn +points to a (caller-allocated) struct +.EX + typedef struct TLSconn{ + char dir[40]; // OUT connection directory + uchar *cert; // IN/OUT certificate + uchar *sessionID; // IN/OUT sessionID + int certlen, sessionIDlen; + void (*trace)(char*fmt, ...); + PEMChain *chain; + } TLSconn; +.EE +defined in +.IR tls.h . +On input, the caller can provide options such as +.IR cert , +the local certificate, and +.IR sessionID , +used by a client to resume a previously negotiated security association. +On output, the connection directory is set, as with +.B listen +(see +.IR dial (3)). +The input +.I cert +is freed and a freshly allocated copy of the remote's certificate +is returned in +.IR conn , +to be checked by the caller +according to its needs. One mechanism is supplied by +.I initThumbprints +and +.I freeThumbprints +which allocate and free, respectively, a table of hashes +from files of known trusted and revoked certificates. +.I okThumbprint +confirms that a particular hash is in the table, as computed by +.PP +.EX + uchar hash[SHA1dlen]; + conn = (TLSconn*)mallocz(sizeof *conn, 1); + fd = tlsClient(fd, conn); + sha1(conn->cert, conn->certlen, hash, nil); + if(!okThumbprint(hash,table)) + exits("suspect server"); + ...application begins... +.EE +.PP +Call +.I tlsServer +to perform the corresponding function on the server side: +.PP +.EX + fd = accept(lcfd, ldir); + conn = (TLSconn*)mallocz(sizeof *conn, 1); + conn->cert = readcert("cert.pem", &conn->certlen); + fd = tlsServer(fd, conn); + ...application begins... +.EE +The private key corresponding to +.I cert.pem +should have been previously loaded into factotum. +(See +.IR rsa (3) +.\" XXX should be rsa(8) +for more about key generation.) +By setting +.EX + conn->chain = readcertchain("intermediate-certs.pem"); +.EE +the server can present extra certificate evidence +to establish the chain of trust to a root authority +known to the client. +.PP +.I Conn +is not required for the ongoing conversation and may +be freed by the application whenever convenient. +.SH FILES +.TP +.B /sys/lib/tls +thumbprints of trusted services +.TP +.B /sys/lib/ssl +PEM certificate files +.SH SOURCE +.\" .B /sys/src/libc/9sys/pushtls.c +.\" .br +.B /usr/local/plan9/src/libsec/port +.SH "SEE ALSO" +.IR dial (3), +.IR thumbprint (7); +Plan 9's +\fIfactotum\fR(4) +and +\fItls\fR(3) +.SH DIAGNOSTICS +return \-1 on failure. +.SH BUGS +.I Pushtls +is not implemented. +.PP +Client certificates and client sessionIDs are not yet +implemented. +.PP +Note that in the TLS protocol +.I sessionID +itself is public; it is used as a pointer to +secrets stored in factotum.
diff --git a/man/man3/qball.3 b/man/man3/qball.3 new file mode 100644 index 0000000..8d27f21 --- /dev/null +++ b/man/man3/qball.3
@@ -0,0 +1,76 @@ +.TH QBALL 3 +.SH NAME +qball \- 3-d rotation controller +.SH SYNOPSIS +.PP +.B +#include <draw.h> +.PP +.B +#include <geometry.h> +.PP +.B +void qball(Rectangle r, Mouse *mousep, +.br +.B + Quaternion *orientation, +.br +.B + void (*redraw)(void), Quaternion *ap) +.SH DESCRIPTION +.I Qball +is an interactive controller that allows arbitrary 3-space rotations to be specified with +the mouse. Imagine a sphere with its center at the midpoint of rectangle +.IR r , +and diameter the smaller of +.IR r 's +dimensions. Dragging from one point on the sphere to another specifies the endpoints of a +great-circle arc. (Mouse points outside the sphere are projected to the nearest point +on the sphere.) The axis of rotation is normal to the plane of the arc, and the +angle of rotation is twice the angle of the arc. +.PP +Argument +.I mousep +is a pointer to the mouse event that triggered the interaction. It should +have some button set. +.I Qball +will read more events into +.IR mousep , +and return when no buttons are down. +.PP +While +.I qball +is reading mouse events, it calls out to the caller-supplied routine +.IR redraw , +which is expected to update the screen to reflect the changing orientation. +Argument +.I orientation +is the orientation that +.I redraw +should examine, represented as a unit Quaternion (see +.IR quaternion(9.2)). +The caller may set it to any orientation. +It will be updated before each call to +.I redraw +(and on return) by multiplying by the rotation specified with the mouse. +.PP +It is possible to restrict +.I qball's +attention to rotations about a particular axis. +If +.I ap +is null, the rotation is unconstrained. +Otherwise, the rotation will be about the same axis as +.IR *ap . +This is accomplished by projecting points on the sphere to +the nearest point also on the plane through the sphere's center +and normal to the axis. +.SH SOURCE +.B /usr/local/plan9/src/libgeometry/qball.c +.SH SEE ALSO +.IR quaternion (3) +.br +Ken Shoemake, +``Animating Rotation with Quaternion Curves'', +.I +SIGGRAPH '85 Conference Proceedings.
diff --git a/man/man3/quaternion.3 b/man/man3/quaternion.3 new file mode 100644 index 0000000..31f4ab5 --- /dev/null +++ b/man/man3/quaternion.3
@@ -0,0 +1,152 @@ +.TH QUATERNION 3 +.SH NAME +qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, qmid, qsqrt \- Quaternion arithmetic +.SH SYNOPSIS +.PP +.B +#include <draw.h> +.PP +.B +#include <geometry.h> +.PP +.B +Quaternion qadd(Quaternion q, Quaternion r) +.PP +.B +Quaternion qsub(Quaternion q, Quaternion r) +.PP +.B +Quaternion qneg(Quaternion q) +.PP +.B +Quaternion qmul(Quaternion q, Quaternion r) +.PP +.B +Quaternion qdiv(Quaternion q, Quaternion r) +.PP +.B +Quaternion qinv(Quaternion q) +.PP +.B +double qlen(Quaternion p) +.PP +.B +Quaternion qunit(Quaternion q) +.PP +.B +void qtom(Matrix m, Quaternion q) +.PP +.B +Quaternion mtoq(Matrix mat) +.PP +.B +Quaternion slerp(Quaternion q, Quaternion r, double a) +.PP +.B +Quaternion qmid(Quaternion q, Quaternion r) +.PP +.B +Quaternion qsqrt(Quaternion q) +.SH DESCRIPTION +The Quaternions are a non-commutative extension field of the Real numbers, designed +to do for rotations in 3-space what the complex numbers do for rotations in 2-space. +Quaternions have a real component +.I r +and an imaginary vector component \fIv\fP=(\fIi\fP,\fIj\fP,\fIk\fP). +Quaternions add componentwise and multiply according to the rule +(\fIr\fP,\fIv\fP)(\fIs\fP,\fIw\fP)=(\fIrs\fP-\fIv\fP\v'-.3m'.\v'.3m'\fIw\fP, \fIrw\fP+\fIvs\fP+\fIv\fP×\fIw\fP), +where \v'-.3m'.\v'.3m' and × are the ordinary vector dot and cross products. +The multiplicative inverse of a non-zero quaternion (\fIr\fP,\fIv\fP) +is (\fIr\fP,\fI-v\fP)/(\fIr\^\fP\u\s-22\s+2\d-\fIv\fP\v'-.3m'.\v'.3m'\fIv\fP). +.PP +The following routines do arithmetic on quaternions, represented as +.IP +.EX +.ta 6n +typedef struct Quaternion Quaternion; +struct Quaternion{ + double r, i, j, k; +}; +.EE +.TF qunit +.TP +Name +Description +.TP +.B qadd +Add two quaternions. +.TP +.B qsub +Subtract two quaternions. +.TP +.B qneg +Negate a quaternion. +.TP +.B qmul +Multiply two quaternions. +.TP +.B qdiv +Divide two quaternions. +.TP +.B qinv +Return the multiplicative inverse of a quaternion. +.TP +.B qlen +Return +.BR sqrt(q.r*q.r+q.i*q.i+q.j*q.j+q.k*q.k) , +the length of a quaternion. +.TP +.B qunit +Return a unit quaternion +.RI ( length=1 ) +with components proportional to +.IR q 's. +.PD +.PP +A rotation by angle \fIθ\fP about axis +.I A +(where +.I A +is a unit vector) can be represented by +the unit quaternion \fIq\fP=(cos \fIθ\fP/2, \fIA\fPsin \fIθ\fP/2). +The same rotation is represented by \(mi\fIq\fP; a rotation by \(mi\fIθ\fP about \(mi\fIA\fP is the same as a rotation by \fIθ\fP about \fIA\fP. +The quaternion \fIq\fP transforms points by +(0,\fIx',y',z'\fP) = \%\fIq\fP\u\s-2-1\s+2\d(0,\fIx,y,z\fP)\fIq\fP. +Quaternion multiplication composes rotations. +The orientation of an object in 3-space can be represented by a quaternion +giving its rotation relative to some `standard' orientation. +.PP +The following routines operate on rotations or orientations represented as unit quaternions: +.TF slerp +.TP +.B mtoq +Convert a rotation matrix (see +.IR matrix (3)) +to a unit quaternion. +.TP +.B qtom +Convert a unit quaternion to a rotation matrix. +.TP +.B slerp +Spherical lerp. Interpolate between two orientations. +The rotation that carries +.I q +to +.I r +is \%\fIq\fP\u\s-2-1\s+2\d\fIr\fP, so +.B slerp(q, r, t) +is \fIq\fP(\fIq\fP\u\s-2-1\s+2\d\fIr\fP)\u\s-2\fIt\fP\s+2\d. +.TP +.B qmid +.B slerp(q, r, .5) +.TP +.B qsqrt +The square root of +.IR q . +This is just a rotation about the same axis by half the angle. +.PD +.SH SOURCE +.B /usr/local/plan9/src/libgeometry/quaternion.c +.SH SEE ALSO +.IR matrix (3), +.IR qball (3)
diff --git a/man/man3/quote.3 b/man/man3/quote.3 index 286cdd9..5a4c8d1 100644 --- a/man/man3/quote.3 +++ b/man/man3/quote.3
@@ -157,9 +157,9 @@ .IR print (3) format strings. .SH SOURCE -.B /usr/local/plan9/src/libc/port/quote.c +.B /usr/local/plan9/src/lib9/quote.c .br -.B /usr/local/plan9/src/libc/fmt/fmtquote.c +.B /usr/local/plan9/src/lib9/fmt/fmtquote.c .SH "SEE ALSO .IR rc (1), .IR malloc (3),
diff --git a/man/man3/rand.3 b/man/man3/rand.3 index 3f3e006..25ea8a4 100644 --- a/man/man3/rand.3 +++ b/man/man3/rand.3
@@ -156,18 +156,12 @@ .IR x , .RI 0≤ x < val ≤ 2\u\s732\s10\d-1. .SH SOURCE -.B /usr/local/plan9/src/libc/port/*rand.c +.B /usr/local/plan9/src/lib9/ .br -.B /usr/local/plan9/src/libc/9sys/truerand.c -.br -.B /usr/local/plan9/src/libsec/port/genrandom.c -.br -.B /usr/local/plan9/src/libsec/port/prng.c -.br -.B /usr/local/plan9/src/libsec/port/*fastrand.c +.B /usr/local/plan9/src/libsec/port/ .SH "SEE ALSO -.IR cons (3), -.IR mp (3), +.\" .IR cons (3), +.IR mp (3) .SH BUGS .I Truerand and
diff --git a/man/man3/read.3 b/man/man3/read.3 index aa35c65..34e65c6 100644 --- a/man/man3/read.3 +++ b/man/man3/read.3
@@ -75,21 +75,18 @@ By combining the operations in a single atomic call, they more closely match the 9P protocol (see -.IR intro (5)) +.IR intro (9p)) and, more important, permit multiprocess programs to execute multiple concurrent read and write operations on the same file descriptor without interference. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.br -.B /usr/local/plan9/src/libc/port/readn.c +.B /usr/local/plan9/src/lib9/readn.c .SH SEE ALSO .IR intro (3), .IR open (3), .IR dup (3), -.IR pipe (3), -.IR readv (3) +.IR pipe (3) .SH DIAGNOSTICS These functions set .IR errstr .
diff --git a/man/man3/readcolmap.3 b/man/man3/readcolmap.3 new file mode 100644 index 0000000..51753c5 --- /dev/null +++ b/man/man3/readcolmap.3
@@ -0,0 +1,76 @@ +.TH READCOLMAP 3 +.SH NAME +RGB, readcolmap, writecolmap \- access display color map +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.br +.B #include <draw.h> +.PP +.PP +.ta \w'\fLvoid 'u +.PP +.B +int readcolmap(Display *d, RGB *map) +.PP +.B +int writecolmap(Display *d, RGB *map) +.fi +.SH DESCRIPTION +Colors are described by their red, green, and blue +light intensities, in an +.B RGB +datum: +.IP +.EX +.ta 6n +typedef +struct RGB { + ulong red; + ulong green; + ulong blue; +} RGB; +.EE +.PP +Black is represented by zero in all three positions and +white has the maximum +.B unsigned +.B long +value in all three positions. +.PP +A color map is an array of +.BR RGB s, +of length +.if t \x'-.8n'2\u\s-1\fIdepth\fP\s+1\d, +.if n 2^\fIdepth\fP, +giving the colors for pixels 0, 1, 2, etc. +On displays with color mapped pixels +(typically 8-bit displays), +one retrieves RGB color information +by treating the pixel data as an offset +into the color map. +.PP +.I Readcolmap +reads the color map for the given display into the provided +.IR map , +which must have enough space to hold it. +.I Writecolmap +associates the given color map with the given display, if possible. +(The hardware might not allow this.) +Both return 0 on success, or \-1 on error, setting +.IR errstr . +.PP +Changing the hardware color map does not change +the color map used by the +.IR draw (3) +operator to convert between +mapped and true color or greyscale images, +which is described in +.IR color (7). +.SH SOURCE +.B /usr/local/plan9/src/libdraw +.SH "SEE ALSO" +.IR graphics (3), +.IR draw (3), +.IR color (7)
diff --git a/man/man3/regexp.3 b/man/man3/regexp.3 index 92f0701..2d3c1a2 100644 --- a/man/man3/regexp.3 +++ b/man/man3/regexp.3
@@ -46,7 +46,7 @@ and may be released by .IR free . Regular expressions are exactly as in -.IR regexp (6). +.IR regexp (7). .PP .I Regcomplit is like
diff --git a/man/man3/regexp9.3 b/man/man3/regexp9.3 new file mode 100644 index 0000000..dc5e434 --- /dev/null +++ b/man/man3/regexp9.3
@@ -0,0 +1,212 @@ +.TH REGEXP9 3 +.SH NAME +regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, regerror \- regular expression +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.br +.B #include <regexp.h> +.PP +.ta \w'\fLRegprog 'u +.B +Reprog *regcomp(char *exp) +.PP +.B +Reprog *regcomplit(char *exp) +.PP +.B +Reprog *regcompnl(char *exp) +.PP +.nf +.B +int regexec(Reprog *prog, char *string, Resub *match, int msize) +.PP +.nf +.B +void regsub(char *source, char *dest, int dlen, Resub *match, int msize) +.PP +.nf +.B +int rregexec(Reprog *prog, Rune *string, Resub *match, int msize) +.PP +.nf +.B +void rregsub(Rune *source, Rune *dest, int dlen, Resub *match, int msize) +.PP +.B +void regerror(char *msg) +.SH DESCRIPTION +.I Regcomp +compiles a +regular expression and returns +a pointer to the generated description. +The space is allocated by +.IR malloc (3) +and may be released by +.IR free . +Regular expressions are exactly as in +.IR regexp9 (7). +.PP +.I Regcomplit +is like +.I regcomp +except that all characters are treated literally. +.I Regcompnl +is like +.I regcomp +except that the +.B . +metacharacter matches all characters, including newlines. +.PP +.I Regexec +matches a null-terminated +.I string +against the compiled regular expression in +.IR prog . +If it matches, +.I regexec +returns +.B 1 +and fills in the array +.I match +with character pointers to the substrings of +.I string +that correspond to the +parenthesized subexpressions of +.IR exp : +.BI match[ i ].sp +points to the beginning and +.BI match[ i ].ep +points just beyond +the end of the +.IR i th +substring. +(Subexpression +.I i +begins at the +.IR i th +left parenthesis, counting from 1.) +Pointers in +.B match[0] +pick out the substring that corresponds to +the whole regular expression. +Unused elements of +.I match +are filled with zeros. +Matches involving +.LR * , +.LR + , +and +.L ? +are extended as far as possible. +The number of array elements in +.I match +is given by +.IR msize . +The structure of elements of +.I match +is: +.IP +.EX +typedef struct { + union { + char *sp; + Rune *rsp; + }; + union { + char *ep; + Rune *rep; + }; +} Resub; +.EE +.LP +If +.B match[0].sp +is nonzero on entry, +.I regexec +starts matching at that point within +.IR string . +If +.B match[0].ep +is nonzero on entry, +the last character matched is the one +preceding that point. +.PP +.I Regsub +places in +.I dest +a substitution instance of +.I source +in the context of the last +.I regexec +performed using +.IR match . +Each instance of +.BI \e n\f1, +where +.I n +is a digit, is replaced by the +string delimited by +.BI match[ n ].sp +and +.BI match[ n ].ep\f1. +Each instance of +.L & +is replaced by the string delimited by +.B match[0].sp +and +.BR match[0].ep . +The substitution will always be null terminated and +trimmed to fit into dlen bytes. +.PP +.IR Regerror , +called whenever an error is detected in +.IR regcomp , +writes the string +.I msg +on the standard error file and exits. +.I Regerror +can be replaced to perform +special error processing. +If the user supplied +.I regerror +returns rather than exits, +.I regcomp +will return 0. +.PP +.I Rregexec +and +.I rregsub +are variants of +.I regexec +and +.I regsub +that use strings of +.B Runes +instead of strings of +.BR chars . +With these routines, the +.I rsp +and +.I rep +fields of the +.I match +array elements should be used. +.SH SOURCE +.B /usr/local/plan9/src/libregexp +.SH "SEE ALSO" +.IR grep (1) +.SH DIAGNOSTICS +.I Regcomp +returns +.B 0 +for an illegal expression +or other failure. +.I Regexec +returns 0 +if +.I string +is not matched. +.SH BUGS +There is no way to specify or match a NUL character; NULs terminate patterns and strings.
diff --git a/man/man3/rendezvous.3 b/man/man3/rendezvous.3 deleted file mode 100644 index 97128ce..0000000 --- a/man/man3/rendezvous.3 +++ /dev/null
@@ -1,57 +0,0 @@ -.TH RENDEZVOUS 3 -.SH NAME -rendezvous \- user level process synchronization -.SH SYNOPSIS -.B #include <u.h> -.br -.B #include <libc.h> -.PP -.B -ulong rendezvous(ulong tag, ulong value) -.SH DESCRIPTION -The rendezvous system call allows two processes to synchronize and -exchange a value. -In conjunction with the shared memory system calls -(see -.IR segattach (3) -and -.IR fork (3)), -it enables parallel programs to control their scheduling. -.PP -Two processes wishing to synchronize call -.I rendezvous -with a common -.IR tag , -typically an address in -memory they share. -One process will arrive at the rendezvous first; -it suspends execution until a second arrives. -When a second process meets the rendezvous -the -.I value -arguments are exchanged between the processes and returned -as the result of the respective -.I rendezvous -system calls. -Both processes are awakened when -the rendezvous succeeds. -.PP -The set of tag values which two processes may use to rendezvous\(emtheir tag space\(emis -inherited when a process forks, unless -.B RFREND -is set in the argument to -.BR rfork ; -see -.IR fork (3). -.PP -If a rendezvous is interrupted the return value is -.BR ~0 , -so that value should not be used in normal communication. -.SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.SH SEE ALSO -.IR segattach (3), -.IR fork (3) -.SH DIAGNOSTICS -Sets -.IR errstr .
diff --git a/man/man3/rfork.3 b/man/man3/rfork.3 new file mode 100644 index 0000000..12cedda --- /dev/null +++ b/man/man3/rfork.3
@@ -0,0 +1,163 @@ +.TH RFORK 3 +.SH NAME +rfork \- manipulate process state +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.nf +.B +int rfork(int flags) +.fi +.SH DESCRIPTION +.I Rfork +is a partial implementation of the Plan 9 system call. +It can be used to manipulate some process state and to create +new processes a la +.IR fork (2). +It cannot be used to create shared-memory processes +(Plan 9's +.B RFMEM +flag); for that functionality use +.I proccreate +(see +.IR thread (3)). +.PP +The +.I flags +argument to +.I rfork +selects which resources of the +invoking process (parent) are shared +by the new process (child) or initialized to +their default values. +.I Flags +is the logical OR of some subset of +.TF RFCNAMEG +.TP +.B RFPROC +If set a new process is created; otherwise changes affect the +current process. +.TP +.B RFNOWAIT +If set, the child process will be dissociated from the parent. Upon +exit the child will leave no +.B Waitmsg +(see +.IR wait (3)) +for the parent to collect. +.\" .TP +.\" .B RFNAMEG +.\" If set, the new process inherits a copy of the parent's name space; +.\" otherwise the new process shares the parent's name space. +.\" Is mutually exclusive with +.\" .BR RFCNAMEG . +.\" .TP +.\" .B RFCNAMEG +.\" If set, the new process starts with a clean name space. A new +.\" name space must be built from a mount of an open file descriptor. +.\" Is mutually exclusive with +.\" .BR RFNAMEG . +.\" .TP +.\" .B RFNOMNT +.\" If set, subsequent mounts into the new name space and dereferencing +.\" of pathnames starting with +.\" .B # +.\" are disallowed. +.\" .TP +.\" .B RFENVG +.\" If set, the environment variables are copied; +.\" otherwise the two processes share environment variables. +.\" Is mutually exclusive with +.\" .BR RFCENVG . +.\" .TP +.\" .B RFCENVG +.\" If set, the new process starts with an empty environment. +.\" Is mutually exclusive with +.\" .BR RFENVG . +.TP +.B RFNOTEG +Each process is a member of a group of processes that all +receive notes when a note is sent to the group +(see +.IR postnote (3) +and +.IR signal (2)). +The group of a new process is by default the same as its parent, but if +.B RFNOTEG +is set (regardless of +.BR RFPROC ), +the process becomes the first in a new group, isolated from +previous processes. +In Plan 9, a process can call +.B rfork(RFNOTEG) +and then be sure that it will no longer receive console interrupts +or other notes. +Unix job-control shells put each command in its own process group +and then relay notes to the current foreground command, making +the idiom less useful. +.TP +.B RFFDG +If set, the invoker's file descriptor table (see +.IR intro ( )) +is copied; otherwise the two processes share a +single table. +.\" .TP +.\" .B RFCFDG +.\" If set, the new process starts with a clean file descriptor table. +.\" Is mutually exclusive with +.\" .BR RFFDG . +.\" .TP +.\" .B RFREND +.\" If set, the process will be unable to +.\" .IR rendezvous (3) +.\" with any of its ancestors; its children will, however, be able to +.\" .B rendezvous +.\" with it. In effect, +.\" .B RFREND +.\" makes the process the first in a group of processes that share a space for +.\" .B rendezvous +.\" tags. +.\" .TP +.\" .B RFMEM +.\" If set, the child and the parent will share +.\" .B data +.\" and +.\" .B bss +.\" segments. +.\" Otherwise, the child inherits a copy of those segments. +.\" Other segment types, in particular stack segments, will be unaffected. +.\" May be set only with +.\" .BR RFPROC . +.PD +.PP +File descriptors in a shared file descriptor table are kept +open until either they are explicitly closed +or all processes sharing the table exit. +.PP +If +.B RFPROC +is set, the +value returned in the parent process +is the process id +of the child process; the value returned in the child is zero. +Without +.BR RFPROC , +the return value is zero. +Process ids range from 1 to the maximum integer +.RB ( int ) +value. +.I Rfork +will sleep, if necessary, until required process resources are available. +.PP +Calling +.B rfork(RFFDG|RFPROC) +is equivalent to calling +.IR fork (2). +.SH SOURCE +.B /usr/local/plan9/src/lib9/rfork.c +.SH DIAGNOSTICS +.I Rfork +sets +.IR errstr .
diff --git a/man/man3/rsa.3 b/man/man3/rsa.3 index 56ad4c7..c0b0fe9 100644 --- a/man/man3/rsa.3 +++ b/man/man3/rsa.3
@@ -3,8 +3,10 @@ asn1dump, asn1toRSApriv, decodepem, +decodepemchain, rsadecrypt, rsaencrypt, +rsafill,, rsagen, rsaprivalloc, rsaprivfree, @@ -12,7 +14,9 @@ rsapuballoc, rsapubfree, X509toRSApub, +X509dump, X509gen, +X509req, X509verify \- RSA encryption algorithm .SH SYNOPSIS .B #include <u.h> @@ -24,9 +28,13 @@ .B #include <libsec.h> .PP .B +.ta +\w'\fLPEMChain* 'u RSApriv* rsagen(int nlen, int elen, int nrep) .PP .B +RSApriv* rsafill(mpint *n, mpint *ek, mpint *dk, mpint *p, mpint *q) +.PP +.B mpint* rsaencrypt(RSApub *k, mpint *in, mpint *out) .PP .B @@ -60,6 +68,12 @@ uchar* decodepem(char *s, char *type, int *len) .PP .B +PEMChain* decodepemchain(char *s, char *type) +.PP +.B +void X509dump(uchar *cert, int ncert) +.PP +.B uchar* X509gen(RSApriv *priv, char *subj, ulong valid[2], int *certlen); .PP .B @@ -113,6 +127,22 @@ returns a newly allocated copy of the public key corresponding to the private key. .PP +.I Rsafill +takes as input the bare minimum pieces of an RSA private key +and computes the rest +.RB ( kp , +.BR kq , +and +.BR c2 ). +It returns a new private key. +All the +.BR mpint s +in the key, +even the ones that correspond directly to +.IR rsafill 's +input parameters, +are freshly allocated, +.PP The routines .IR rsaalloc , .IR rsafree , @@ -148,6 +178,9 @@ .IR cert . It returns nil if successful, else an error string. .PP +.I X509dump +prints an X.509 certificate to standard ouptut. +.PP .I X509gen creates a self-signed X.509 certificate, given an RSA keypair .IR priv , @@ -162,7 +195,12 @@ "C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric" .EE using the quoting conventions of -.IR tokenize (3). +.I tokenize +(see +.IR getfields (3)). +.PP +.I X509req +creates an X.509 certification request. .PP .I Asn1toRSApriv converts an ASN1 formatted RSA private key into the corresponding @@ -186,6 +224,20 @@ and .BI * len is undefined. +.PP +.I Decodepemchain +is similar but expects a sequence of PEM-formatted sections +and returns a linked list of the decodings: +.IP +.EX +typedef struct PEMChain PEMChain +struct PEMChain +{ + PEMChain *next; + uchar *pem; + int pemlen; +}; +.EE .SH SOURCE .B /usr/local/plan9/src/libsec .SH SEE ALSO @@ -198,5 +250,5 @@ .IR rc4 (3), .IR sechash (3), .IR prime (3), -.IR rand (3), -.IR x509 (8) +.IR rand (3) +.\" .IR pem (8)
diff --git a/man/man3/rune.3 b/man/man3/rune.3 index 4689530..bc3dbe8 100644 --- a/man/man3/rune.3 +++ b/man/man3/rune.3
@@ -182,9 +182,9 @@ returns .IR s1 . .SH SOURCE -.B /usr/local/plan9/src/libc/port/rune.c +.B /usr/local/plan9/src/lib9/utf/rune.c .br -.B /usr/local/plan9/src/libc/port/utfrune.c +.B /usr/local/plan9/src/lib9/utf/utfrune.c .SH SEE ALSO -.IR utf (6), +.IR utf (7), .IR tcs (1)
diff --git a/man/man3/runestrcat.3 b/man/man3/runestrcat.3 index f5210c2..dadcbcd 100644 --- a/man/man3/runestrcat.3 +++ b/man/man3/runestrcat.3
@@ -58,7 +58,7 @@ the corresponding functions in .IR strcat (3). .SH SOURCE -.B /usr/local/plan9/src/libc/port +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR memory (3), .IR rune (3),
diff --git a/man/man3/scsi.3 b/man/man3/scsi.3 new file mode 100644 index 0000000..5b6f24c --- /dev/null +++ b/man/man3/scsi.3
@@ -0,0 +1,188 @@ +.TH SCSI 3 +.SH NAME +openscsi, scsiready, scsi, scsicmd, scsierror \- SCSI device operations +.SH SYNOPSIS +.nf +.ft L +#include <u.h> +#include <libc.h> +#include <disk.h> +.ft +.PP +.ft L +typedef struct Scsi { + char *inquire; + int rawfd; + int nchange; + ulong changetime; +}; +.ft +.PP +.B +Scsi* openscsi(char *devdir) +.PP +.B +void closescsi(Scsi *s) +.PP +.B +int scsiready(Scsi *s) +.PP +.B +int scsi(Scsi *s, uchar *cmd, int ncmd, +.br + void *data, int ndata, int dir) +.PP +.B +int scsicmd(Scsi *s, uchar *cmd, int ncmd, +.br + void *data, int ndata, int dir) +.PP +.B +char* scsierror(int asc, int ascq) +.PP +.B +int scsiverbose; +.SH DESCRIPTION +These routines provide an interface +to a SCSI or ATAPI device via Plan 9's +\fIsd\fR(3). +.PP +.I Openscsi +attempts to open the file +.IB devdir /raw +and use it to send raw SCSI commands. +On success, it reads the device's inquiry +string and stores it in in returned +.B Scsi +structure. +.I Closescsi +closes the connection and frees the +.B Scsi +structure. +.PP +.I Scsiready +sends the ``unit ready'' command up to three times, +returning zero if the unit responds that it is ready, +or \-1 on error. +.PP +.I Scsierror +returns a textual description of the SCSI status +denoted by the ASC and ASCQ sense codes. +The description is found by consulting +.BR /sys/lib/scsicodes . +The returned string will be overwritten by +the next call to +.IR scsierror . +.PP +.I Scsi +and +.I scsicmd +execute a single SCSI command on the named device. +There should be +.I ncmd +bytes of +command data in +.IR cmd ; +if +.I dir +is +.BR Sread , +a successful operation +will store up to +.I ndata +bytes into +.IR data , +returning the number of bytes stored. +If +.I dir +is +.BR Swrite , +the +.I ndata +bytes beginning at +.I data +are transmitted as the data argument to +the command, and the +number of bytes written is returned. +If +.I dir +is +.BR Snone , +.I data +and +.I ndata +are ignored. +On error, +.I scsi +and +.I scsicmd +return \-1. +.I Scsicmd +simply issues the command and +returns the result; +.I scsi +works a bit harder and +is the more commonly used routine. +.I Scsi +attempts to send the command; +if it is successful, +.I scsi +returns what +.I scsicmd +returned. +Otherwise, +.I scsi +sends a request sense command to +obtain the reason for the failure, +sends a unit ready command in +an attempt to bring the unit out of any +inconsistent states, and tries again. +If the second try fails, +.I scsi +sends the request +sense and unit ready commands +again +and then uses +.I scsierror +to set +.I errstr +with a reason for failure. +.PP +The +.B nchange +and +.B changetime +fields +in the +.B Scsi +structure +record the number of times a media +change has been detected, and the +time when the current media was +inserted into the drive (really the +first time a SCSI command was issued +after it was inserted). +They are maintained by +.IR scsi . +.PP +If +.I scsiverbose +is set, +these commands will produce a fair +amount of debugging output on file descriptor 2 +when SCSI commands fail. +.SH FILES +.TP +.B /sys/lib/scsicodes +List of textual messages corresponding to SCSI error codes; +consulted by +.BR scsierror . +.SH SOURCE +.B /usr/local/plan9/src/libdisk/scsi.c +.SH SEE ALSO +Plan 9's +\fIsd\fR(3) and +\fIscuzz\fR(8) +.SH BUGS +SCSI devices on Unix do not present the interface expected by +these routines.
diff --git a/man/man3/seek.3 b/man/man3/seek.3 index 3396638..2ce4cff 100644 --- a/man/man3/seek.3 +++ b/man/man3/seek.3
@@ -37,7 +37,7 @@ Seeking in a directory is not allowed. Seeking in a pipe is a no-op. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/seek.c .SH SEE ALSO .IR intro (3), .IR open (3)
diff --git a/man/man3/sendfd.3 b/man/man3/sendfd.3 new file mode 100644 index 0000000..8090dfc --- /dev/null +++ b/man/man3/sendfd.3
@@ -0,0 +1,57 @@ +.TH SENDFD 3 +.SH NAME +sendfd, recvfd \- pass file descriptors along Unix domain sockets +.SH SYNOPSIS +.B +#include <u.h> +.PP +.B +#include <libc.h> +.PP +.B +int sendfd(int socket, int fd) +.PP +.B +int recvfd(int socket) +.SH DESCRIPTION +.I Recvfd +and +.I sendfd +can be used to pass an open file descriptor over +a Unix domain socket from one process to another. +Since +.IR pipe (3) +is implemented with +.IR socketpair (2) +instead of +.IR pipe (2), +.I socket +can be a file descriptor obtained from +.IR pipe (3). +.PP +.I Sendfd +sends the file descriptor +.I fd +along the socket to a process calling +.I recvfd +on the other end. +.PP +It is assumed that the two sides have coordinated +and agreed to transfer a file descriptor already, so +that the +.I sendfd +is met with a +.I recvfd +instead of an ordinary +.IR read . +.PP +The file descriptor number may change on its way +between processes, but the kernel structure it represents +will not. +.SH SOURCE +.B /usr/local/plan9/src/lib9/sendfd.c +.SH SEE ALSO +.IR socketpair (2), +.I sendmsg +in +.IR send (2)
diff --git a/man/man3/setjmp.3 b/man/man3/setjmp.3 index b451c29..0ed7845 100644 --- a/man/man3/setjmp.3 +++ b/man/man3/setjmp.3
@@ -86,9 +86,7 @@ } .EE .SH SOURCE -.B /usr/local/plan9/src/libc/$objtype/setjmp.s -.br -.B /usr/local/plan9/src/libc/$objtype/notejmp.c +.B /usr/local/plan9/src/lib9/jmp.c .SH SEE ALSO .IR notify (3) .SH BUGS
diff --git a/man/man3/sleep.3 b/man/man3/sleep.3 index 1872ab5..da2e695 100644 --- a/man/man3/sleep.3 +++ b/man/man3/sleep.3
@@ -37,7 +37,7 @@ The return value is the amount of time previously remaining in the alarm clock. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/sleep.c .SH SEE ALSO .IR intro (3) .SH DIAGNOSTICS
diff --git a/man/man3/stat.3 b/man/man3/stat.3 index a815550..03f3abe 100644 --- a/man/man3/stat.3 +++ b/man/man3/stat.3
@@ -46,7 +46,7 @@ are the system calls; they deal with machine-independent .IR "directory entries" . Their format is defined by -.IR stat (5). +.IR stat (9p). .I Stat and .I fstat @@ -67,7 +67,7 @@ .IR edir . The data returned from the kernel includes its leading 16-bit length field as described in -.IR intro (5). +.IR intro (9p). For symmetry, this field must also be present when passing data to the kernel in a call to .I wstat and @@ -242,19 +242,15 @@ by the group leader of the file's current group if also leader of the new group (see -.IR intro (5) -for more information about permissions and -.IR users (6) -for users and groups). +.IR intro (9p) +for more information about permissions, users, and groups). The .B length can be changed by anyone with write permission, provided the operation is implemented by the server. (See -.IR intro (5) -for permission information, and -.IR users (6) -for user and group information). +.IR intro (9p) +for permission, user, and group information). .PP Special values in the fields of the .B Dir @@ -281,21 +277,12 @@ .I stat to retrieve the initial values first. .SH SOURCE -.TF /usr/local/plan9/src/libc/9syscall -.TP -.B /usr/local/plan9/src/libc/9syscall -for the -.RB non- dir -routines -.TP -.B /usr/local/plan9/src/libc/9sys -for the routines prefixed -.B dir +.B /usr/local/plan9/src/lib9/dirstat.c .SH SEE ALSO .IR intro (3), .IR fcall (3), .IR dirread (3), -.IR stat (5) +.IR stat (9p) .SH DIAGNOSTICS The .I dir
diff --git a/man/man3/strcat.3 b/man/man3/strcat.3 index 6e16158..8fcf2ca 100644 --- a/man/man3/strcat.3 +++ b/man/man3/strcat.3
@@ -242,11 +242,7 @@ .I Cistrstr operates analogously, but ignores ASCII case differences when comparing strings. .SH SOURCE -All these routines have portable C implementations in -.BR /usr/local/plan9/src/libc/port . -Many also have machine-dependent assembly language -implementations in -.BR /usr/local/plan9/src/libc/$objtype . +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR memory (3), .IR rune (3),
diff --git a/man/man3/string.3 b/man/man3/string.3 index 0782b26..0b39d5c 100644 --- a/man/man3/string.3 +++ b/man/man3/string.3
@@ -1,6 +1,6 @@ .TH STRING 3 .SH NAME -s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, s_getline \- extensible strings +s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, s_getline, s_allocinstack, s_freeinstack, s_rdinstack \- extensible strings .SH SYNOPSIS .B #include <u.h> .br @@ -8,6 +8,7 @@ .br .B #include <String.h> .PP +.ta +\w'\fLSinstack* 'u .B String* s_new(void) .br @@ -61,6 +62,15 @@ String* s_unique(String *s) .PP .B +Sinstack* s_allocinstack(char *file) +.br +.B +void s_freeinstack(Sinstack *stack) +.br +.B +char* s_rdinstack(Sinstack *stack, String *s) +.PP +.B #include <bio.h> .PP .B @@ -222,14 +232,39 @@ The string is null terminated. .PP .I S_getline -reads up to the next newline and returns +reads up to the next newline, appends the input to +.IR s , +and returns a pointer to the beginning of the bytes read. Leading spaces and tabs and the trailing newline are all discarded. .I S_getline -will recursively read through files included with +discards blank lines and lines beginning with +.LR # . +.I S_getline +ignores +newlines escaped by immediately-preceding backslashes. +.PP +.I S_allocinstack +allocates an input stack with the single file +.I file +open for reading. +.I S_freeinstack +frees an input stack. +.I S_rdinstack +reads a line from an input stack. +It follows the same rules as +.I s_getline +except that when it encounters a line of the form .B #include -and discard all other lines beginning with -.BR # . +.IR newfile , +.I s_getline +pushes +.I newfile +onto the input stack, postponing further reading of the current +file until +.I newfile +has been read. +The input stack has a maximum depth of 32 nested include files. .SH SOURCE .B /usr/local/plan9/src/libString .SH SEE ALSO
diff --git a/man/man3/stringsize.3 b/man/man3/stringsize.3 index ac57f4a..448df99 100644 --- a/man/man3/stringsize.3 +++ b/man/man3/stringsize.3
@@ -62,8 +62,8 @@ .IR subfont (3), .IR draw (3), .IR draw (3), -.IR image (6), -.IR font (6) +.IR image (7), +.IR font (7) .SH DIAGNOSTICS Because strings are loaded dynamically, these routines may generate I/O to the server and produce calls to the graphics error function.
diff --git a/man/man3/subfont.3 b/man/man3/subfont.3 index 980b93b..4933c0d 100644 --- a/man/man3/subfont.3 +++ b/man/man3/subfont.3
@@ -150,7 +150,7 @@ may be substituted by the application to provide a less file-oriented subfont naming scheme. .PP The format of a subfont file is described in -.IR font (6). +.IR font (7). Briefly, it contains a image with all the characters in it, followed by a subfont header, followed by character information. .I Readsubfont @@ -228,8 +228,8 @@ .IR allocimage (3), .IR draw (3), .IR cachechars (3), -.IR image (6), -.IR font (6) +.IR image (7), +.IR font (7) .SH DIAGNOSTICS All of the functions use the graphics error function (see .IR graphics (3)).
diff --git a/man/man3/sysfatal.3 b/man/man3/sysfatal.3 new file mode 100644 index 0000000..ea1a3df --- /dev/null +++ b/man/man3/sysfatal.3
@@ -0,0 +1,39 @@ +.TH SYSFATAL 3 +.SH NAME +sysfatal \- system error messages +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.B +void sysfatal(char *fmt, ...) +.SH DESCRIPTION +.I Sysfatal +prints to standard error the name of the running program, +a colon and a space, +the message described by the +.IR print (3) +format string +.I fmt +and subsequent arguments, and a newline. +It then calls +.IR exits (3) +with the formatted message as argument. +The program's name is the value of +.BR argv0 , +which will be set if the program uses the +.IR arg (3) +interface to process its arguments. +If +.B argv0 +is null, it is ignored and the following colon and space are suppressed. +.SH SOURCE +.B /usr/local/plan9/src/lib9/sysfatal.c +.SH "SEE ALSO" +.IR intro (3), +.IR errstr (3), +the +.B %r +format in +.IR print (3)
diff --git a/man/man3/thread.3 b/man/man3/thread.3 index 84ca69f..05c1902 100644 --- a/man/man3/thread.3 +++ b/man/man3/thread.3
@@ -5,12 +5,10 @@ chanfree, chaninit, chanprint, +chansetname, mainstacksize, proccreate, procdata, -procexec, -procexecl, -procrfork, recv, recvp, recvul, @@ -25,6 +23,8 @@ nbsendul, threadcreate, threaddata, +threadexec, +threadexecl, threadexits, threadexitsall, threadgetgrp, @@ -33,12 +33,15 @@ threadintgrp, threadkill, threadkillgrp, +threadlinklibrary, threadmain, threadnotify, threadid, threadpid, threadsetgrp, threadsetname, +threadsetstate, +threadspawn, threadwaitchan, yield \- thread and proc management .SH SYNOPSIS @@ -71,6 +74,7 @@ int op; Channel **tag; int entryno; + char *name; }; .fi .de XX @@ -126,8 +130,9 @@ int nbsendul(Channel *c, ulong v) int chanprint(Channel *c, char *fmt, ...) .XX -int procexecl(Channel *cpid, char *file, ...) -int procexec(Channel *cpid, char *file, char *args[]) +int threadspawn(int fd[3], char *file, char *args[]) +int threadexecl(Channel *cpid, int fd[3], char *file, ...) +int threadexec(Channel *cpid, int fd[3], char *file, char *args[]) Channel* threadwaitchan(void) .XX int threadnotify(int (*f)(void*, char*), int in) @@ -179,31 +184,31 @@ .IR stacksize . Thread stacks are allocated in shared memory, making it valid to pass pointers to stack variables between threads and procs. -.I Procrfork +.I Proccreate creates a new proc, and inside that proc creates a single thread as .I threadcreate would, returning the id of the created thread. -.I Procrfork -creates the new proc by calling -.B rfork -(see -.IR fork (3)) -with flags -.BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR. -(The thread library depends on all its procs -running in the same rendezvous group. -Do not include -.B RFREND -in -.IR rforkflag .) -.I Proccreate -is identical to -.I procrfork -with -.I rforkflag -set to zero. +.\" .I Procrfork +.\" creates the new proc by calling +.\" .B rfork +.\" (see +.\" .IR fork (3)) +.\" with flags +.\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR. +.\" (The thread library depends on all its procs +.\" running in the same rendezvous group. +.\" Do not include +.\" .B RFREND +.\" in +.\" .IR rforkflag .) +.\" .I Proccreate +.\" is identical to +.\" .I procrfork +.\" with +.\" .I rforkflag +.\" set to zero. Be aware that the calling thread may continue execution before the newly created proc and thread @@ -226,6 +231,11 @@ .I status as the exit status. .PP +When the last thread in +.IR threadmain 's +proc exits, the program will appear to its parent to have exited. +The remaining procs will still run together, but as a background program. +.PP The threads in a proc are coroutines, scheduled nonpreemptively in a round-robin fashion. A thread must explicitly relinquish control of the processor @@ -233,9 +243,10 @@ Calls that do this are .IR yield , .IR proccreate , -.IR procexec , -.IR procexecl , +.IR threadexec , +.IR threadexecl , .IR threadexits , +.IR threadspawn , .IR alt , .IR send , and @@ -307,6 +318,17 @@ is only valid until the next call to .IR threadsetname . .PP +Also for debugging, +threads have a string state associated with them. +.I Threadsetstate +sets the state string. +There is no +.IR threadgetstate ; +since the thread scheduler resets the state to +.B Running +every time it runs the thread, +it is only useful for debuggers to inspect the state. +.PP .I Threaddata returns a pointer to a per-thread pointer that may be modified by threaded programs for @@ -315,9 +337,9 @@ .I procdata returns a pointer to a per-proc pointer. .PP -.I Procexecl +.I Threadexecl and -.I procexec +.I threadexec are threaded analogues of .I exec and @@ -325,30 +347,67 @@ (see .IR exec (3)); on success, -they replace the calling thread (which must be the only thread in its proc) +they replace the calling thread and invoke the external program, never returning. +(Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other +threads will continue executing.) On error, they return \-1. If .I cpid is not null, the pid of the invoked program will be sent along .I cpid +(using +.IR sendul ) once the program has been started, or \-1 will be sent if an error occurs. -.I Procexec +.I Threadexec and -.I procexecl +.I threadexecl will not access their arguments after sending a result along .IR cpid . Thus, programs that malloc the .I argv passed to -.I procexec +.I threadexec can safely free it once they have received the .I cpid response. +.PP +.I Threadexecl +and +.I threadexec +will duplicate +(see +.IR dup (3)) +the three file descriptors in +.I fd +onto standard input, output, and error for the external program +and then close them in the calling thread. +Beware of code that sets +.IP +.EX +fd[0] = 0; +fd[1] = 1; +fd[2] = 2; +.EE +to use the current standard files. The correct code is +.IP +.EX +fd[0] = dup(0, -1); +fd[1] = dup(1, -1); +fd[2] = dup(2, -1); +.EE +.PP +.I Threadspawn +is like +.I threadexec +but does not replace the current thread. +It returns the pid of the invoked program on success, or +\-1 on error. +.PP .I Threadwaitchan returns a channel of pointers to .B Waitmsg @@ -398,6 +457,14 @@ .I chanfree returns immediately). .PP +The +.B name +element in the +.B Channel +structure is a description intended for use in debugging. +.I Chansetname +sets the name. +.PP .I Send sends the element pointed at by .I v @@ -536,49 +603,97 @@ .IR notify (3)). .PP It is safe to use -.B sysfatal -(see -.IR perror (3)) +.IR sysfatal (3) in threaded programs. .I Sysfatal will print the error string and call .IR threadexitsall . .PP -It is safe to use +It is not safe to call .IR rfork -(see -.IR fork (3)) -to manage the namespace, file descriptors, note group, and environment of a -single process. -That is, it is safe to call -.I rfork -with the flags -.BR RFNAMEG , -.BR RFFDG , -.BR RFCFDG , -.BR RFNOTEG , -.BR RFENVG , -and -.BR RFCENVG. -(To create new processes, use -.I proccreate -and -.IR procrfork .) -As mentioned above, -the thread library depends on all procs being in the -same rendezvous group; do not change the rendezvous -group with -.IR rfork . +in a threaded program, except to call +.B rfork(RFNOTEG) +from the main proc before any other procs have been created. +To create new processes, use +.IR proccreate . +.\" .PP +.\" It is safe to use +.\" .IR rfork +.\" (see +.\" .IR fork (3)) +.\" to manage the namespace, file descriptors, note group, and environment of a +.\" single process. +.\" That is, it is safe to call +.\" .I rfork +.\" with the flags +.\" .BR RFNAMEG , +.\" .BR RFFDG , +.\" .BR RFCFDG , +.\" .BR RFNOTEG , +.\" .BR RFENVG , +.\" and +.\" .BR RFCENVG. +.\" (To create new processes, use +.\" .I proccreate +.\" and +.\" .IR procrfork .) +.\" As mentioned above, +.\" the thread library depends on all procs being in the +.\" same rendezvous group; do not change the rendezvous +.\" group with +.\" .IR rfork . .SH FILES .B /usr/local/plan9/acid/thread contains useful .IR acid (1) functions for debugging threaded programs. .PP -.B /usr/local/plan9/src/libthread/example.c -contains a full example program. +.B /usr/local/plan9/src/libthread/test +contains some example programs. .SH SOURCE .B /usr/local/plan9/src/libthread .SH SEE ALSO .IR intro (3), .IR ioproc (3) +.SH BUGS +A program that intends to use the thread library +but does not call any of its functions will not cause Unix linkers +to link the thread library, resulting in the unintelligible error: +.IP +.EX +/usr/local/plan9/lib/lib9.a(main.o)(.text+0x17): In function `main': +/usr/local/plan9/src/lib9/main.c:10: undefined reference to `p9main' +.EE +.LP +or similar. To force the thread library to be linked properly in such cases, +insert a call to the no-op function +.I threadlinklibrary +somewhere in your program. +.PP +To avoid name conflicts, +.IR alt , +.IR nbrecv , +.IR nbrecvp , +.IR nbrecvul , +.IR nbsend , +.IR nbsendp , +.IR nbsendul , +.IR recv , +.IR recvp , +.IR recvul , +.IR send , +.IR sendp , +and +.IR sendul +are defined as macros that expand to +.IR chanalt , +.IR channbrecv , +and so on. +Similarly, +.I yield +is defined as a macro that expands to +.IR threadyield . +.PP +The implementation of +.I threadnotify +may not be correct.
diff --git a/man/man3/time.3 b/man/man3/time.3 index 90ec731..6f3cbcd 100644 --- a/man/man3/time.3 +++ b/man/man3/time.3
@@ -26,20 +26,8 @@ is not zero then .BI * tp is also set to the answer. -.PP -These functions work by reading -.BR /dev/bintime , -opening that file when -.I they -are first called. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/time.c -.br -.B /usr/local/plan9/src/libc/9sys/nsec.c -.SH SEE ALSO -.IR cons (3) +.B /usr/local/plan9/src/lib9/time.c .SH DIAGNOSTICS -Sets +These functions set .IR errstr . -.SH BUGS -These routines maintain a static file descriptor.
diff --git a/man/man3/udpread.3 b/man/man3/udpread.3 new file mode 100644 index 0000000..3a0a7ea --- /dev/null +++ b/man/man3/udpread.3
@@ -0,0 +1,68 @@ +.TH UDPREAD 3 +.SH NAME +udpread, udpwrite \- read and write UDP packets +.SH SYNOPSIS +.B #include <u.h> +.PP +.B #include <libc.h> +.PP +.B #include <ip.h> +.PP +.B +.nf +.ta +4n +8n +typedef struct Udphdr Udphdr; +struct Udphdr +{ + uchar raddr[IPaddrlen]; /* remote address and port */ + uchar laddr[IPaddrlen]; /* local address and port */ + uchar rport[2]; + uchar lport[2]; +}; +.PP +.B +long udpread(int fd, Udphdr *hdr, void *data, long n) +.PP +.B +long udpwrite(int fd, Udphdr *hdr, void *data, long n) +.SH DESCRIPTION +.I Udpread +and +.I udpwrite +read and write UDP packets from the UDP network connection +established on file descriptor +.IR fd . +.PP +.I Udpread +reads at most +.I n +bytes of packet body into +.I data , +stores the header in +.IR hdr , +and returns the number of bytes stored in +.IR data . +.PP +.I Udpwrite +writes the +.I n +bytes stored in +.I data +in a UDP packet with header +.IR hdr . +.PP +Note that the +.B Udphdr +frames the addresses as local and remote +instead of source and destination. +Thus the +.I hdr +filled in for a packet read by +.I udpread +can be used unchanged in +.I udpwrite +to send a response back to the sender of the original packet. +.SH SOURCE +.B /usr/local/plan9/src/lib9/udp.c +.SH SEE ALSO +.IR ip (3)
diff --git a/man/man3/wait.3 b/man/man3/wait.3 index b8b5c7f..03b55bf 100644 --- a/man/man3/wait.3 +++ b/man/man3/wait.3
@@ -1,6 +1,6 @@ .TH WAIT 3 .SH NAME -await, wait, waitpid \- wait for a process to exit +await, awaitnohang, awaitfor, wait, waitnohang, waitfor, waitpid \- wait for a process to exit .SH SYNOPSIS .B #include <u.h> .br @@ -10,14 +10,28 @@ Waitmsg* wait(void) .PP .B +Waitmsg* waitnohang(void) +.PP +.B +Waitmsg* waitfor(int pid) +.PP +.B int waitpid(void) .PP .B int await(char *s, int n) +.PP +.B +int awaitnohang(char *s, int n) +.PP +.B +int awaitfor(int pid, char *s, int n) .SH DESCRIPTION .I Wait causes a process to wait for any child process (see -.IR fork (3)) +.IR fork (2) +and +.IR rfork (3)) to exit. It returns a .B Waitmsg @@ -70,16 +84,33 @@ .I waitpid returns just the pid and discards the rest of the information. .PP -The underlying system call is +.I Waitnohang +is like +.I wait +but does not block if there are no more children to wait for. +Instead it returns immediately and sets +.IR errstr . +.PP +.I Waitfor +is like +.I wait +but waits for a particular +.IR pid . +.PP +The underlying calls are .IR await , -which fills in the n-byte buffer +.IR awaitnohang , +and +.IR awaitfor , +which fill in the +.IR n -byte +buffer .I s with a textual representation of the pid, times, and exit string. There is no terminal NUL. The return value is the length, in bytes, of the data. .PP -The buffer filled in by -.I await +The filled-in buffer may be parsed (after appending a NUL) using .IR tokenize (see @@ -104,14 +135,12 @@ returns .BR -1 . .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/wait.c +.PP +.B /usr/local/plan9/src/lib9/await.c .SH "SEE ALSO" -.IR fork (3), +.IR rfork (3), .IR exits (3), -the -.B wait -file in -.IR proc (3) .SH DIAGNOSTICS These routines set .IR errstr .
diff --git a/man/man3/wctl.3 b/man/man3/wctl.3 new file mode 100644 index 0000000..dfed6fc --- /dev/null +++ b/man/man3/wctl.3
@@ -0,0 +1,39 @@ +.TH WCTL 3 +.SH NAME +drawresizewindow, drawsetlabel, drawtopwindow \- window management +.SH SYNOPSIS +.B #include <draw.h> +.PP +.B +void drawresizewindow(Rectangle r) +.PP +.B +int drawsetlabel(Display *d, char *name) +.PP +.B +void drawtopwindow(void) +.SH DESCRIPTION +These routines interact with a window manager +to set the properties of the window running the current program. +They substitute for interacting directly with the Plan 9 +.IR rio 's +.BR /dev/wctl . +.PP +.I Drawresizewindow +requests that the program's window be resized to have the +width and height of the rectangle +.IR r . +Only the width and height +are important; the offset is ignored. +.PP +.I Drawsetlabel +requests that the program's window title be set to +.IR name . +.PP +.I Drawtopwindow +requests that the program's window be moved +above all other windows and given the input focus. +.SH SOURCE +.B /usr/local/plan9/src/libdraw/x11-init.c +.br +.B /usr/local/plan9/src/libdraw/x11-wsys.c
diff --git a/man/man3/window.3 b/man/man3/window.3 new file mode 100644 index 0000000..6f14060 --- /dev/null +++ b/man/man3/window.3
@@ -0,0 +1,244 @@ +.TH WINDOW 3 +.SH NAME +Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, bottomnwindows, topwindow, topnwindows, originwindow \- window management +.SH SYNOPSIS +.nf +.B +#include <u.h> +.B +#include <libc.h> +.B +#include <draw.h> +.PP +.ft L +.nf +typedef +struct Screen +{ + Display *display; /* display holding data */ + int id; /* id of system-held Screen */ + Image *image; /* unused; for reference only */ + Image *fill; /* color to paint behind windows */ +} Screen; +.fi +.ta \w'\fLScreen* 'u +.PP +.B +Screen* allocscreen(Image *image, Image *fill, int public) +.PP +.B +Screen* publicscreen(Display *d, int id, ulong chan) +.PP +.B +int freescreen(Screen *s) +.PP +.B +Image* allocwindow(Screen *s, Rectangle r, int ref, int val) +.PP +.B +void bottomwindow(Image *w) +.PP +.B +void bottomnwindows(Image **wp, int nw) +.PP +.B +void topwindow(Image *w) +.PP +.B +void topnwindows(Image **wp, int nw) +.PP +.B +int originwindow(Image *w, Point log, Point scr) +.PP +.ft L +.nf +enum +{ + /* refresh methods */ + Refbackup = 0, + Refnone = 1, + Refmesg = 2 +}; +.fi +.ft P +.SH DESCRIPTION +Windows are represented as +.B Images +and may be treated as regular images for all drawing operations. +The routines discussed here permit the creation, deletion, and shuffling +of windows, facilities that do not apply to regular images. +.PP +To create windows, it is first necessary to allocate a +.B Screen +data structure to gather them together. +A +.B Screen +turns an arbitrary image into something that may have windows upon it. +It is created by +.BR allocscreen , +which takes an +.I image +upon which to place the windows (typically +.BR display->image ), +a +.I fill +image to paint the background behind all the windows on the image, +and a flag specifying whether the result should be publicly visible. +If it is public, an arbitrary other program connected to the same +display may acquire a pointer to the same screen by calling +.B publicscreen +with the +.B Display +pointer and the +.I id +of the published +.BR Screen , +as well as the expected channel descriptor, as a safety check. +It will usually require some out-of-band coordination for programs to share a screen profitably. +.B Freescreen +releases a +.BR Screen , +although it may not actually disappear from view until all the windows upon it have also been deallocated. +.PP +Unlike +.BR allocwindow , +.B allocscreen +does +.I not +initialize the appearance of the +.BR Screen . +.PP +Windows are created by +.BR allocwindow , +which takes a pointer to the +.B Screen +upon which to create the window, a rectangle +.I r +defining its geometry, an integer pixel value +.I val +to color the window initially, and a refresh method +.BR ref . +The refresh methods are +.BR Refbackup , +which provides backing store and is the method used by +.IR rio (1) +for its clients; +.BR Refnone , +which provides no refresh and is designed for temporary uses +such as sweeping a display rectangle, for windows that are +completely covered by other windows, and for windows that +are already protected by backing store; and +.BR Refmesg , +which causes messages to be delivered to the owner of the window +when it needs to be repainted. +.B Refmesg +is not fully implemented. +.PP +The result of +.B allocwindow +is an +.B Image +pointer that may be treated like any other image. +In particular, it is freed by calling +.B freeimage +(see +.IR allocimage (3)). +The following functions, however, apply only to windows, not regular images. +.PP +.B Bottomwindow +pushes window +.I w +to the bottom of the stack of windows on its +.BR Screen , +perhaps obscuring it. +.B Topwindow +pulls window +.I w +to the top, making it fully visible on its +.BR Screen . +(This +.B Screen +may itself be within a window that is not fully visible; +.B topwindow +will not affect the stacking of this parent window.) +.B Bottomnwindows +and +.B Topnwindows +are analogous, but push or pull a group of +.I nw +windows listed in the array +.IR wp . +The order within +.IR wp +is unaffected. +.PP +Each window is created as an +.B Image +whose +.B Rectangle +.B r +corresponds to the rectangle given to +.B allocwindow +when it was created. Thus, a newly created window +.I w +resides on its +.B Screen->image +at +.IB w ->r +and has internal coordinates +.IB w ->r . +Both these may be changed by a call to +.BR originwindow . +The two +.B Point +arguments to +.B originwindow +define the upper left corner of the logical coordinate system +.RI ( log ) +and screen position +.RI ( scr ). +Their usage is shown in the Examples section. +.PP +.IR Rio (1) +creates its client windows with backing store, +.BR Refbackup . +The graphics initialization routine, +.B initdraw +(see +.IR graphics (3)), +builds a +.B Screen +upon this, and then allocates upon that another window indented +to protect the border. That window is created +.BR Refnone , +since the backing store created by +.B rio +protects its contents. That window is the one known in the +library by the global name +.B screen +(a historic but confusing choice). +.SH EXAMPLES +To move a window to the upper left corner of the display, +.EX + originwindow(w, w->r.min, Pt(0, 0)); +.EE +To leave a window where it is on the screen but change its internal +coordinate system so (0,\ 0) is the upper left corner of the window, +.EX + originwindow(w, Pt(0, 0), w->r.min); +.EE +After this is done, +.B w->r +is translated to the origin and there will be no way to discover the +actual screen position of the window unless it is recorded separately. +.SH SOURCE +.B /usr/local/plan9/src/libdraw +.SH SEE ALSO +.IR graphics (3), +.IR draw (3), +.IR cachechars (3), +.IR draw (3) +.SH BUGS +The refresh method +.B Refmesg +should be finished.
diff --git a/man/man4/0intro.4 b/man/man4/0intro.4 new file mode 100644 index 0000000..1e4c81d --- /dev/null +++ b/man/man4/0intro.4
@@ -0,0 +1,82 @@ +.TH INTRO 4 +.SH NAME +intro \- introduction to file servers +.SH DESCRIPTION +A Plan 9 +.I "file server" +provides a file tree to processes. +This section of the manual describes servers that can be +mounted in a name space to give a file-like interface to interesting services. +A file server may be a provider of a conventional file system, +with files maintained on permanent storage, +or it may also be a process that synthesizes files in some manner. +.PP +In Plan 9, the kernel mount device +\fImnt\fR(3) +acts as a client to the 9P servers mounted in the current name space, +translating system calls such as +.IR open (2) +into 9P transactions such as +.IR open (9p). +The kernel also multiplexes the potentially many processes onto a single 9P conversation +with each server. +Finally, the kernel provides each process with its own private +.I name space +which it can customize at will. +Modern Unix systems do not provide these niceties, so +the Unix port of these Plan 9 file servers provides them via other means. +.PP +On Unix, 9P clients do not access servers via the traditional +file system call interface. Only the Unix name space can be accessed +that way. +Instead, 9P clients use the +.IR 9pclient (3) +library to connect and interact directly with particular 9P servers. +The +.IR 9p (1) +command-line client is useful for interactive use and in shell scripts. +.PP +To preserve the façade of a single 9P conversation with each server, +9P servers invoke +.IR 9pserve (4), +typically via +.IR post9pservice (3). +.I 9pserve +announces a 9P service at a particular +network address and multiplexes the clients that connect to +that address onto a single 9P conversation with the server. +.PP +Each ported program operates in a pseudo-name space +that determines which 9P servers it is using. +The name space of a ported program is represented by a +directory containing Unix domain sockets, one for each 9P server. +The directory defaults to +.BR /tmp/ns.$USER.$DISPLAY , +meaning that all programs in an X Windows login session +share a single name space. +Setting the +.B $NAMESPACE +environment variable overrides this default. +The +.IR namespace (1) +command prints the current name space directory. +.PP +Occasionally it is useful to be able to connect the input or output +of a standard Unix program to a file served by a 9P server. +The new +.IR openfd (9p) +9P transaction, which depends on file descriptor passing, +provides a sufficient workaround in many cases. +.IR 9pserve 's +implementation of +.I openfd +(see also +.I fsopenfd +in +.IR 9pclient (3)) +returns the read or write end of a pipe; +a helper process transfers data between the other end of the pipe +and the 9P server. +Note that since the data is being transferred via a pipe, +9P read and write errors cannot be passed on to the Unix program. +The Unix program sees only end-of-file or a closed pipe.
diff --git a/man/man4/9pserve.4 b/man/man4/9pserve.4 new file mode 100644 index 0000000..81cfc26 --- /dev/null +++ b/man/man4/9pserve.4
@@ -0,0 +1,46 @@ +.TH 9PSERVE 4 +.SH NAME +9pserve \- announce and multiplex 9P service +.SH SYNOPSIS +.B 9pserve +[ +.B -v +] +.I addr +.SH DESCRIPTION +On Plan 9, when a user-level file server mounts itself into a name space +or posts itself in +.BR /srv , +the Plan 9 kernel multiplexes the potentially many processes +accessing the server into a single 9P conversation. +The user-level server need not concern itself with how many +processes are accessing it or with cleaning up after a process when it +exits unexpectedly. +On Unix, +.I 9pserve +takes the place of the Plan 9 kernel, multiplexing clients onto +a single server conversation and cleaning up after clients when +they hang up unexpectedly. +.PP +.I 9pserve +announces a 9P service on +.I addr +and multiplexes any 9P clients connecting to +.I addr +into a single conversation with a 9P server on +.IR 9pserve 's +standard input and output. +When a client hangs up, +.I 9pserve +flushes any outstanding 9P transactions +and clunks any outstanding fids belonging to the client. +.PP +.I 9pserve +is typically not invoked directly; use +.IR post9pservice (3) +instead. +.SH "SEE ALSO +.IR intro (4), +.IR intro (9p) +.SH SOURCE +.B /usr/local/plan9/src/cmd/9pserve.c
diff --git a/man/man4/INDEX b/man/man4/INDEX new file mode 100644 index 0000000..bd0f7bc --- /dev/null +++ b/man/man4/INDEX
@@ -0,0 +1,6 @@ +0intro 0intro.4 +intro 0intro.4 +9pserve 9pserve.4 +acme acme.4 +plumber plumber.4 +ramfs ramfs.4
diff --git a/man/man4/acme.4 b/man/man4/acme.4 new file mode 100644 index 0000000..f6a4853 --- /dev/null +++ b/man/man4/acme.4
@@ -0,0 +1,406 @@ +.TH ACME 4 +.SH NAME +acme \- control files for text windows +.SH SYNOPSIS +.B acme +[ +.B -f +.I varfont +] [ +.B -F +.I fixfont +] +[ +.I file +\&... ] +.SH DESCRIPTION +The text window system +.IR acme (1) +serves a variety of files for reading, writing, and controlling +windows. +Some of them are virtual versions of system files for dealing +with the virtual console; others control operations +of +.I acme +itself. +When a command is run under +.IR acme , +a directory holding these files is mounted on +.B /mnt/acme +(also bound to +.BR /mnt/wsys ) +and also +.BR /dev ; +the files mentioned here +appear in both those directories. +.PP +Some of these files supply virtual versions of services available from the underlying +environment, in particular the character terminal files in Plan 9's +\fIcons\fR(3). +(Unlike in Plan 9's \fIrio\fR(1), +each command under +.I acme +sees the same set of files; there is not a distinct +.B /dev/cons +for each window.) +Other files are unique to +.IR acme . +.TP +.B acme +is a subdirectory used by +.B win +(see +.IR acme (1)) +as a mount point for the +.I acme +files associated with the window in which +.B win +is running. +It has no specific function under +.I acme +itself. +.TP +.B cons +is the standard and diagnostic output file for all commands +run under +.IR acme . +(Input for commands is redirected to +.BR /dev/null .) +Text written to +.B cons +appears in a window labeled +.IB dir /+Errors\f1, +where +.I dir +is the directory in which the command +was run. +The window is created if necessary, but not until text is actually written. +.TP +.B consctl +Is an empty unwritable file present only for compatibility; there is no way +to turn off `echo', for example, under +.IR acme . +.TP +.B index +holds a sequence of lines of text, one per window. Each line has 5 decimal numbers, +each formatted in 11 characters plus a blank\(emthe window ID; +number of characters (runes) in the tag; +number of characters in the body; +a 1 if the window is a directory, 0 otherwise; +and a 1 if the window is modified, 0 +otherwise\(emfollowed by the tag up to a newline if present. +Thus at character position 5×12 starts the name of the window. +If a file has multiple zeroxed windows open, +only the most recently used will appear in the +.B index +file. +.TP +.B label +is an empty file, writable without effect, present only for compatibility with +.BR rio . +.TP +.B new +A directory analogous to the numbered directories +.RI ( q.v. ). +Accessing any +file in +.B new +creates a new window. Thus to cause text to appear in a new window, +write it to +.BR /dev/new/body . +For more control, open +.BR /dev/new/ctl +and use the interface described below. +.LP +.PP +Each +.I acme +window has associated a directory numbered by its ID. +Window IDs are chosen sequentially and may be discovered by the +.B ID +command, by +reading the +.B ctl +file, or +indirectly through the +.B index +file. The files in the numbered directories are as follows. +.TP +.B addr +may be written with any textual address (line number, regular expression, etc.), +in the format understood by button 3 but without the initial colon, including compound addresses, +to set the address for text accessed through the +.B data +file. +When read, it returns the value of the address that would next be read +or written through the +.B data +file, in the format +.BI # m ,# n +where +.I m +and +.I n +are character (not byte) offsets. If +.I m +and +.I n +are identical, the format is just +.BI # m\f1. +Thus a regular expression may be evaluated by writing it to +.B addr +and reading it back. +The +.B addr +address has no effect on the user's selection of text. +.TP +.B body +holds contents of the window body. It may be read at any byte offset. +Text written to +.B body +is always appended; the file offset is ignored. +.TP +.B ctl +may be read to recover the five numbers as held in the +.B index +file, described above, plus two more fields: the width of the +window in pixels and the name of the font used in the window. +Text messages may be written to +.B ctl +to affect the window. +Each message is terminated by a newline and multiple +messages may be sent in a single write. +.RS .5i +.TF limit=addr +.TP +.B addr=dot +Set the +.B addr +address to that of the user's selected text in the window. +.TP +.B clean +Mark the window clean as though it has just been written. +.TP +.B dirty +Mark the window dirty, the opposite of clean. +.TP +.B cleartag +Remove all text in the tag after the vertical bar. +.TP +.B del +Equivalent to the +.B Del +interactive command. +.TP +.B delete +Equivalent to the +.B Delete +interactive command. +.TP +.B dot=addr +Set the user's selected text in the window to the text addressed by the +.B addr +address. +.TP +.BI dump " command +Set the command string to recreate the window from a dump file. +.TP +.BI dumpdir " directory +Set the directory in which to run the command to recreate the window from a dump file. +.TP +.B get +Equivalent to the +.B Get +interactive command with no arguments; accepts no arguments. +.TP +.B limit=addr +When the +.B ctl +file is first opened, regular expression context searches in +.B addr +addresses examine the whole file; this message restricts subsequent +searches to the current +.B addr +address. +.TP +.B mark +Cancel +.BR nomark , +returning the window to the usual state wherein each modification to the +body must be undone individually. +.TP +.BI name " name +Set the name of the window to +.IR name . +.TP +.B nomark +Turn off automatic `marking' of changes, so a set of related changes +may be undone in a single +.B Undo +interactive command. +.TP +.B noscroll +Turn off automatic `scrolling' of the window to show text written to the body. +.TP +.B put +Equivalent to the +.B Put +interactive command with no arguments; accepts no arguments. +.TP +.B scroll +Cancel a +.B noscroll +message, returning the window to the default state wherein each write +to the +.B body +file causes the window to `scroll' to display the new text. +.TP +.B show +Guarantee at least some of the selected text is visible on the display. +.RE +.PD +.TP +.B data +is used in conjunction with +.B addr +for random access to the contents of the body. +The file offset is ignored when writing the +.B data +file; instead the location of the data to be read or written is determined by the state of the +.B addr +file. +Text, which must contain only whole characters (no `partial runes'), +written to +.B data +replaces the characters addressed by the +.B addr +file and sets the address to the null string at the end of the written text. +A read from +.B data +returns as many whole characters as the read count will permit starting +at the beginning of the +.B addr +address (the end of the address has no effect) +and sets the address to the null string at the end of the returned +characters. +.TP +.B event +When a window's +.B event +file is open, changes to the window occur as always but the +actions are also reported as +messages to the reader of the file. Also, user actions with buttons 2 and 3 +(other than chorded +.B Cut +and +.BR Paste , +which behave normally) have no immediate effect on the window; +it is expected that the program reading the +.B event +file will interpret them. +The messages have a fixed format: +a character indicating the origin or cause of the action, +a character indicating the type of the action, +four free-format blank-terminated decimal numbers, +optional text, and a newline. +The first and second numbers are the character addresses of the action, +the third is a flag, +and the final is a count of the characters in the optional text, which +may itself contain newlines. +The origin characters are +.B E +for writes to the +.B body +or +.B tag +file, +.B F +for actions through the window's other files, +.B K +for the keyboard, and +.B M +for the mouse. +The type characters are +.B D +for text deleted from the body, +.B d +for text deleted from the tag, +.B I +for text inserted to the body, +.B i +for text inserted to the tag, +.B L +for a button 3 action in the body, +.B l +for a button 3 action in the tag, +.B X +for a button 2 action in the body, and +.B x +for a button 2 action in the tag. +.IP +If the relevant text has less than 256 characters, it is included in the message; +otherwise it is elided, the fourth number is 0, and the program must read +it from the +.B data +file if needed. No text is sent on a +.B D +or +.B d +message. +.IP +For +.BR D , +.BR d , +.BR I , +and +.BR i +the flag is always zero. +For +.BR X +and +.BR x , +the flag is a bitwise OR (reported decimally) of the following: +1 if the text indicated is recognized as an +.I acme +built-in command; +2 if the text indicated is a null string that has a non-null expansion; +if so, another complete message will follow describing the expansion +exactly as if it had been indicated explicitly (its flag will always be 0); +8 if the command has an extra (chorded) argument; if so, +two more complete messages will follow reporting the argument (with +all numbers 0 except the character count) and where it originated, in the form of +a fully-qualified button 3 style address. +.IP +For +.B L +and +.BR l , +the flag is the bitwise OR of the following: +1 if +.I acme +can interpret the action without loading a new file; +2 if a second (post-expansion) message follows, analogous to that with +.B X +messages; +4 if the text is a file or window name (perhaps with address) rather than +plain literal text. +.IP +For messages with the 1 bit on in the flag, +writing the message back to the +.B event +file, but with the flag, count, and text omitted, +will cause the action to be applied to the file exactly as it would +have been if the +.B event +file had not been open. +.TP +.B tag +holds contents of the window tag. It may be read at any byte offset. +Text written to +.B tag +is always appended; the file offset is ignored. +.SH SOURCE +.B /usr/local/plan9/src/cmd/acme +.SH SEE ALSO +.IR rio (1), +.IR acme (1)
diff --git a/man/man4/plumber.4 b/man/man4/plumber.4 new file mode 100644 index 0000000..681bd5e --- /dev/null +++ b/man/man4/plumber.4
@@ -0,0 +1,121 @@ +.TH PLUMBER 4 +.SH NAME +plumber \- file system for interprocess messaging +.SH SYNOPSIS +.B plumber +[ +.B -p +.I plumbing +] +.SH DESCRIPTION +The +.I plumber +is a user-level file server that receives, examines, rewrites, and dispatches +.IR plumb (7) +messages between programs. +Its behavior is programmed by a +.I plumbing +file (default +.BR /usr/$user/lib/plumbing ) +in the format of +.IR plumb (7). +.PP +Its services are posted via +.IR 9pserve (4) +as +.BR plumb . +and consist of two +pre-defined files, +.B plumb/send +and +.BR plumb/rules , +and a set of output +.I ports +for dispatching messages to applications. +.PP +Programs use +.B fswrite +(see +.IR 9pclient (3)) +to deliver messages to the +.B send +file, and +.I fsread +to receive them from the corresponding port. +For example, +.IR sam (1)'s +.B plumb +menu item or the +.B B +command cause a message to be sent to +.BR plumb/send ; +.B sam +in turn reads from, by convention, +.B plumb/edit +to receive messages about files to open. +.PP +A copy of each message is sent to each client that has the corresponding port open. +If none has it open, and the rule has a +.B plumb +.B client +or +.B plumb +.B start +rule, that rule is applied. +A +.B plumb +.B client +rule causes the specified command to be run +and the message to be held for delivery when the port is opened. +A +.B plumb +.B start +rule runs the command but discards the message. +If neither +.B start +or +.B client +is specified and the port is not open, +the message is discarded and a write error is returned to the sender. +.PP +The set of output ports is determined dynamically by the +specification in the plumbing rules file: a port is created for each unique +destination of a +.B plumb +.B to +rule. +.PP +The set of rules currently active may be examined by reading the file +.BR plumb/rules ; +appending to this file adds new rules to the set, while +creating it (opening it with +.BR OTRUNC ) +clears the rule set. +Thus the rule set may be edited dynamically with a traditional text editor. +However, ports are never deleted dynamically; if a new set of rules does not +include a port that was defined in earlier rules, that port will still exist (although +no new messages will be delivered there). +.SH FILES +.TF /usr/$user/lib/plumbing +.TP +.B /usr/$user/lib/plumbing +default rules file +.TP +.B /usr/local/plan9/plumb +directory to search for files in +.B include +statements +.TP +.B plumb +mount name for +.IR plumber (4). +.SH SOURCE +.B /usr/local/plan9/src/cmd/plumb +.SH "SEE ALSO" +.IR plumb (1), +.IR plumb (3), +.IR plumb (7) +.\" .SH BUGS +.\" .IR Plumber 's +.\" file name space is fixed, so it is difficult to plumb +.\" messages that involve files in newly mounted services.
diff --git a/man/man4/ramfs.4 b/man/man4/ramfs.4 new file mode 100644 index 0000000..32405de --- /dev/null +++ b/man/man4/ramfs.4
@@ -0,0 +1,50 @@ +.TH RAMFS 4 +.SH NAME +ramfs \- memory file system +.SH SYNOPSIS +.B ramfs +[ +.B -i +] +[ +.B -S +.I service +] +.SH DESCRIPTION +.I Ramfs +starts a 9P file server +keeping all files in memory. +Initially the file tree is empty. +.PP +By default +.I ramfs +posts its service as +.B ramfs +using +.IR 9pserve (4). +.PP +The +.B -S +flag specifies an alternate service name for ramfs to use. +.PP +The +.B -i +flag tells +.I ramfs +to use file descriptors 0 and 1 for its communication channel +rather than create a pipe. +This makes it possible to use +.I ramfs +as a file server on a remote machine: the file descriptors 0 +and 1 will be the network channel from +.I ramfs +to the client machine. +.PP +This program is useful mainly as an example of how +to write a user-level file server. +It can also be used to provide high-performance temporary files. +.SH SOURCE +.B /usr/local/plan9/src/cmd/ramfs.c +.SH "SEE ALSO" +.IR 9p (3), +.IR 9pserve (4)
diff --git a/man/man5/INDEX b/man/man5/INDEX new file mode 100644 index 0000000..6f51523 --- /dev/null +++ b/man/man5/INDEX
@@ -0,0 +1 @@ +[a-z0-9:]* [a-z0-9:]*
diff --git a/man/man7/INDEX b/man/man7/INDEX new file mode 100644 index 0000000..7930266 --- /dev/null +++ b/man/man7/INDEX
@@ -0,0 +1,18 @@ +color color.7 +face face.7 +font font.7 +subfont font.7 +image image.7 +man man.7 +map map.7 +ms ms.7 +plot plot.7 +plumb plumb.7 +regexp regexp.7 +regexp9 regexp9.7 +thumbprint thumbprint.7 +ASCII utf.7 +UTF utf.7 +Unicode utf.7 +rune utf.7 +utf utf.7
diff --git a/man/man7/color.7 b/man/man7/color.7 new file mode 100644 index 0000000..c8b536a --- /dev/null +++ b/man/man7/color.7
@@ -0,0 +1,150 @@ +.TH COLOR 7 +.SH NAME +color \- representation of pixels and colors +.SH DESCRIPTION +To address problems of consistency and portability among applications, +Plan 9 uses a fixed color map, called +.BR rgbv , +on 8-bit-per-pixel displays. +Although this avoids problems caused by multiplexing color maps between +applications, it requires that the color map chosen be suitable for most purposes +and usable for all. +Other systems that use fixed color maps tend to sample the color cube +uniformly, which has advantages\(emmapping from a (red, green, blue) triple +to the color map and back again is easy\(embut ignores an important property +of the human visual system: eyes are +much more sensitive to small changes in intensity than +to changes in hue. +Sampling the color cube uniformly gives a color map with many different +hues, but only a few shades of each. +Continuous tone images converted into such maps demonstrate conspicuous +artifacts. +.PP +Rather than dice the color cube into subregions of +size 6\(mu6\(mu6 (as in Netscape Navigator) or 8\(mu8\(mu4 +(as in previous releases of Plan 9), picking 1 color in each, +the +.B rgbv +color map uses a 4\(mu4\(mu4 subdivision, with +4 shades in each subcube. +The idea is to reduce the color resolution by dicing +the color cube into fewer cells, and to use the extra space to increase the intensity +resolution. +This results in 16 grey shades (4 grey subcubes with +4 samples in each), 13 shades of each primary and secondary color (3 subcubes +with 4 samples plus black) and a reasonable selection of colors covering the +rest of the color cube. +The advantage is better representation of +continuous tones. +.PP +The following function computes the 256 3-byte entries in the color map: +.IP +.EX +.ta 6n +6n +6n +6n +void +setmaprgbv(uchar cmap[256][3]) +{ + uchar *c; + int r, g, b, v; + int num, den; + int i, j; + + for(r=0,i=0; r!=4; r++) + for(v=0; v!=4; v++,i+=16) + for(g=0,j=v-r; g!=4; g++) + for(b=0; b!=4; b++,j++){ + c = cmap[i+(j&15)]; + den = r; + if(g > den) + den = g; + if(b > den) + den = b; + if(den == 0) /* would divide check; pick grey shades */ + c[0] = c[1] = c[2] = 17*v; + else{ + num = 17*(4*den+v); + c[0] = r*num/den; + c[1] = g*num/den; + c[2] = b*num/den; + } + } +} +.EE +.PP +There are 4 nested loops to pick the (red,green,blue) coordinates of the subcube, +and the value (intensity) within the subcube, indexed by +.BR r , +.BR g , +.BR b , +and +.BR v , +whence +the name +.IR rgbv . +The peculiar order in which the color map is indexed is designed to distribute the +grey shades uniformly through the map\(emthe +.IR i 'th +grey shade, +.RI 0<= i <=15 +has index +.IR i ×17, +with black going to 0 and white to 255. +Therefore, when a call to +.B draw +converts a 1, 2 or 4 bit-per-pixel picture to 8 bits per pixel (which it does +by replicating the pixels' bits), the converted pixel values are the appropriate +grey shades. +.PP +The +.B rgbv +map is not gamma-corrected, for two reasons. First, photographic +film and television are both normally under-corrected, the former by an +accident of physics and the latter by NTSC's design. +Second, we require extra color resolution at low intensities because of the +non-linear response and adaptation of the human visual system. +Properly +gamma-corrected displays with adequate low-intensity resolution pack the +high-intensity parts of the color cube with colors whose differences are +almost imperceptible. +Either reason suggests concentrating +the available intensities at the low end of the range. +.PP +On `true-color' displays with separate values for the red, green, and blue +components of a pixel, the values are chosen so 0 represents no intensity (black) and the +maximum value (255 for an 8-bit-per-color display) represents full intensity (e.g., full red). +Common display depths are 24 bits per pixel, with 8 bits per color in order +red, green, blue, and 16 bits per pixel, with 5 bits of red, 6 bits of green, and 5 bits of blue. +.PP +Colors may also be created with an opacity factor called +.BR alpha , +which is scaled so 0 represents fully transparent and 255 represents opaque color. +The alpha is +.I premultiplied +into the other channels, as described in the paper by Porter and Duff cited in +.IR draw (3). +The function +.B setalpha +(see +.IR allocimage (3)) +aids the initialization of color values with non-trivial alpha. +.PP +The packing of pixels into bytes and words is odd. +For compatibility with VGA frame buffers, the bits within a +pixel byte are in big-endian order (leftmost pixel is most +significant bits in byte), while bytes within a pixel are packed in little-endian +order. Pixels are stored in contiguous bytes. This results +in unintuitive pixel formats. For example, for the RGB24 format, +the byte ordering is blue, green, red. +.PP +To maintain a constant external representation, +the +.IR draw (3) +interface +as well as the +various graphics libraries represent colors +by 32-bit numbers, as described in +.IR color (3). +.SH "SEE ALSO" +.IR color (3), +.IR graphics (3), +.IR draw (3)
diff --git a/man/man7/face.7 b/man/man7/face.7 new file mode 100644 index 0000000..08b04a4 --- /dev/null +++ b/man/man7/face.7
@@ -0,0 +1,115 @@ +.TH FACE 7 +.SH NAME +face \- face files +.SH DESCRIPTION +The directories +.B /usr/$user/lib/face +and +.B /lib/face +contain a hierarchy of images of people. +In those directories are subdirectories named by the sizes of +the corresponding image files: +.B 48x48x1 +(48 by 48 pixels, one bit per pixel); +.B 48x48x2 +(48 by 48 pixels, two (grey) bits per pixel); +.B 48x48x4 +(48 by 48 pixels, four (grey) bits per pixel); +.B 48x48x8 +(48 by 48 pixels, eight (color-mapped) bits per pixel); +.B 512x512x8 +(512 by 512 pixels, eight (color-mapped) bits per pixel); +.B 512x512x24 +(512 by 512 pixels, twenty-four bits per pixel (3 times 8 bits +per color)). +The large files serve no special purpose; they are stored +as images +(see +.IR image (7)). +The small files are the `icons' displayed by +.B faces +and +.B seemail +(see Plan 9's +\fIfaces\fR(1)); +for depths less than 4, their format is special. +.PP +One- and two-bit deep icons are stored as text, one line of the file to one scan line +of display. +Each line is divided into 8-bit, 16-bit, or 32-bit big-endian words, +stored as a list of comma-separated hexadecimal C constants, +such as: +.IP +.EX +0x9200, 0x1bb0, 0x003e, +.EE +.PP +This odd format is historical and the programs that read it +are somewhat forgiving about blanks and the need for commas. +.PP +The files +.BR lib/face/*/.dict +hold a correspondence between users at machines +and face files. +The format is +.IP +.EX +.I machine\fB/\fPuser directory\fB/\fPfile\fB.\fPver +.EE +.PP +The +.I machine +is the domain name of the machine sending the message, +and +.I user +the name of the user sending it. +The +.I directory +is a further subdirectory of (say) +.BR /lib/face/48x48x1 , +named by a single letter corresponding to the first character +of the user names. The +.I file +is the name of the file, typically but not always the user name, +and +.I ver +is a number to distinguish different images, for example to +distinguish the image for Bill Gates from the image for Bill Joy, +both of which might otherwise be called +.BR b/bill . +For example, Bill Gates might be represented by the line +.IP +.EX +microsoft.com/bill b/bill.1 +.EE +.PP +If multiple entries exist for a user in the various +.B .dict +files, +.I faces +chooses the highest pixel size less than or equal to that of the +display on which it is running. +.PP +Finally, or rather firstly, the file +.B /lib/face/.machinelist +contains a list of machine/domain pairs, one per line, +to map any of a set of machines to a single domain name to +be looked up in the +.B .dict +files. The machine name may be a regular expression, +so for example the entry +.IP +.EX +\&.*research\e.bell-labs\e.com astro +.EE +.PP +maps any of the machines in Bell Labs Research into the +shorthand name +.BR astro , +which then appears as a domain name in the +.B .dict +files. +.SH "SEE ALSO" +.IR mail (1), +.IR tweak (1), +.IR image (7)
diff --git a/man/man7/font.7 b/man/man7/font.7 new file mode 100644 index 0000000..f651a58 --- /dev/null +++ b/man/man7/font.7
@@ -0,0 +1,87 @@ +.TH FONT 7 +.SH NAME +font, subfont \- external format for fonts and subfonts +.SH SYNOPSIS +.B #include <draw.h> +.SH DESCRIPTION +Fonts and subfonts are described in +.IR cachechars (3). +.PP +External fonts are described by a plain text file that can be read using +.IR openfont . +The format of the file is a header followed by any number of +subfont range specifications. +The header contains two numbers: the height and the ascent, both in pixels. +The height is the inter-line spacing and the ascent is the distance +from the top of the line to the baseline. These numbers are chosen +to display consistently all the subfonts of the font. +A subfont range specification contains two or three numbers and a file name. +The numbers are the inclusive range of characters covered by the subfont, +with an optional starting position within the subfont, +and the file name names an external file suitable for +.I readsubfont +(see +.IR graphics (3)). +The minimum number of a covered range is mapped to the specified starting position +(default zero) of the +corresponding subfont. +If the subfont file name does not begin with a slash, it is taken relative to the +directory containing the font file. +Each field must be followed by some white space. +Each numeric field may be C-format decimal, octal, or hexadecimal. +.PP +External subfonts are represented in a more rigid format +that can be read and written using +.I readsubfont +and +.I writesubfont +(see +.IR subfont (3)). +The format for subfont files is: an image containing character glyphs, +followed by a subfont header, followed by character information. +The image has the format for external image files described in +.IR image (7). +The subfont header has 3 +decimal strings: +.BR n , +.BR height , +and +.BR ascent . +Each number is right-justified and blank padded in 11 characters, followed by a blank. +The character +.B info +consists of +.BR n +1 +6-byte entries, each giving the +.B Fontchar +.B x +(2 bytes, low order byte first), +.BR top , +.BR bottom , +.BR left , +and +.BR width . +The +.B x +field of the last +.B Fontchar +is used to calculate the image width +of the previous character; the other fields in the last +.B Fontchar +are irrelevant. +.PP +Note that the convention of using the character with value zero (NUL) to represent +characters of zero width (see +.IR draw (3)) +means that fonts should have, as their zeroth character, +one with non-zero width. +.SH FILES +.TF /lib/font/bit/* +.TP +.B /lib/font/bit/* +font directories +.SH "SEE ALSO" +.IR graphics (3), +.IR draw (3), +.IR cachechars (3), +.IR subfont (3)
diff --git a/man/man7/image.7 b/man/man7/image.7 new file mode 100644 index 0000000..6e613f9 --- /dev/null +++ b/man/man7/image.7
@@ -0,0 +1,205 @@ +.TH IMAGE 7 +.SH NAME +image \- external format for images +.SH SYNOPSIS +.B #include <draw.h> +.SH DESCRIPTION +Images are described in +.IR graphics (3), +and the definition of pixel values is in +.IR color (7). +Fonts and images are stored in external files +in machine-independent formats. +.PP +Image files are read and written using +.B readimage +and +.B writeimage +(see +.IR allocimage (3)), or +.B readmemimage +and +.B writememimage +(see +.IR memdraw (3)). +An uncompressed image file starts with 5 +strings: +.BR chan , +.BR r.min.x , +.BR r.min.y , +.BR r.max.x , +and +.BR r.max.y . +Each is right-justified and blank padded in 11 characters, followed by a blank. +The +.B chan +value is a textual string describing the pixel format +(see +.B strtochan +in +.IR graphics (3) +and the discussion of channel descriptors below), +and the rectangle coordinates are decimal strings. +The rest of the file contains the +.B r.max.y-r.min.y +rows of pixel data. +A +.I row +consists of the byte containing pixel +.B r.min.x +and all the bytes up to and including the byte containing pixel +.BR r.max.x -1. +For images with depth +.I d +less than eight, a pixel with x-coordinate = +.I x +will appear as +.I d +contiguous bits in a byte, with the pixel's high order bit +starting at the byte's bit number +.if t \fIw\fP\(mu(\fIx\fP mod (8/\fIw\fP)), +.if n w*(x mod (8/w)), +where bits within a byte are numbered 0 to 7 from the +high order to the low order bit. +Rows contain integral number of bytes, so there may be some unused +pixels at either end of a row. +If +.I d +is greater than 8, the definition of images requires that it will a multiple of 8, so +pixel values take up an integral number of bytes. +.PP +The +.B loadimage +and +.B unloadimage +functions described in +.IR allocimage (3) +also deal with rows in this format, stored in user memory. +.PP +The channel format string is a sequence of two-character channel descriptions, +each comprising a letter +.RB ( r +for red, +.B g +for green, +.B b +for blue, +.B a +for alpha, +.B m +for color-mapped, +.B k +for greyscale, +and +.B x +for ``don't care'') +followed by a number of bits per pixel. +The sum of the channel bits per pixel is the +depth of the image, which must be either +a divisor or a multiple of eight. +It is an error to have more than +one of any channel but +.BR x . +An image must have either a greyscale channel; a color mapped channel; +or red, green, and blue channels. +If the alpha channel is present, it must be at least as deep as any other channel. +.PP +The channel string defines the format of the pixels in the file, +and should not be confused with ordering of bytes in the file. +In particular +.B 'r8g8b8' +pixels have byte ordering blue, green, and red within the file. +See +.IR color (7) +for more details of the pixel format. +.PP +A venerable yet deprecated format replaces the channel string +with a decimal +.IR ldepth , +which is the base two logarithm of the number +of bits per pixel in the image. +In this case, +.IR ldepth s +0, 1, 2, and 3 +correspond to channel descriptors +.BR k1 , +.BR k2 , +.BR k4 , +and +.BR m8 , +respectively. +.PP +Compressed image files start with a line of text containing the word +.BR compressed , +followed by a header as described above, followed by the image data. +The data, when uncompressed, is laid out in the usual form. +.PP +The data is represented by a string of compression blocks, each encoding +a number of rows of the image's pixel data. Compression blocks +are at most 6024 bytes long, so that they fit comfortably in a +single 9P message. Since a compression block must encode a +whole number of rows, there is a limit (about 5825 bytes) to the width of images +that may be encoded. Most wide images are in subfonts, +which, at 1 bit per pixel (the usual case for fonts), can be 46600 pixels wide. +.PP +A compression block begins with two decimal strings of twelve bytes each. +The first number is one more than the +.B y +coordinate of the last row in the block. The second is the number +of bytes of compressed data in the block, not including the two decimal strings. +This number must not be larger than 6000. +.PP +Pixels are encoded using a version of Lempel & Ziv's sliding window scheme LZ77, +best described in J A Storer & T G Szymanski +`Data Compression via Textual Substitution', +JACM 29#4, pp. 928-951. +.PP +The compression block is a string of variable-length +code words encoding substrings of the pixel data. A code word either gives the +substring directly or indicates that it is a copy of data occurring +previously in the pixel stream. +.PP +In a code word whose first byte has the high-order bit set, the rest of the +byte indicates the length of a substring encoded directly. +Values from 0 to 127 encode lengths from 1 to 128 bytes. +Subsequent bytes are the literal pixel data. +.PP +If the high-order bit is zero, the next 5 bits encode +the length of a substring copied from previous pixels. Values from 0 to 31 +encode lengths from 3 to 34 bytes. The bottom two bits of the first byte and +the 8 bits of the next byte encode an offset backward from the current +position in the pixel data at which the copy is to be found. Values from +0 to 1023 encode offsets from 1 to 1024. The encoding may be `prescient', +with the length larger than the offset, which works just fine: the new data +is identical to the data at the given offset, even though the two strings overlap. +.PP +Some small images, in particular 48\(mu48 face files +as used by +.I seemail +(see Plan 9's +\fIfaces\fR(1) +and +.IR face (7)) +and 16\(mu16 +cursors, can be stored textually, suitable for inclusion in C source. +Each line of text represents one scan line as a +comma-separated sequence of hexadecimal +bytes, shorts, or words in C format. +For cursors, each line defines a pair of bytes. +(It takes two images to define a cursor; each must be stored separately +to be processed by programs such as +.IR tweak (1).) +Face files of one bit per pixel are stored as a sequence of shorts, +those of larger pixel sizes as a sequence of longs. +Software that reads these files must deduce the image size from +the input; there is no header. +These formats reflect history rather than design. +.SH "SEE ALSO" +.IR jpg (1), +.IR tweak (1), +.IR graphics (3), +.IR draw (3), +.IR allocimage (3), +.IR color (7), +.IR face (7), +.IR font (7)
diff --git a/man/man7/man.7 b/man/man7/man.7 new file mode 100644 index 0000000..fbfa9f2 --- /dev/null +++ b/man/man7/man.7
@@ -0,0 +1,249 @@ +.TH MAN 7 +.SH NAME +man \- macros to typeset manual +.SH SYNOPSIS +.B nroff -man +.I file ... +.PP +.B troff -man +.I file ... +.SH DESCRIPTION +These macros are used to format pages of this manual. +.PP +Except in +.L .LR +and +.L .RL +requests, any text argument denoted +.I t +in the request summary may be zero to six words. +Quotes +\fL"\fP ... \fL"\fP +may be used to include blanks in a `word'. +If +.I t +is empty, +the special treatment is applied to +the next text input line (the next line that doesn't begin with dot). +In this way, for example, +.B .I +may be used to italicize a line of more than 6 words, or +.B .SM +followed by +.B .B +to make small letters in `bold' font. +.PP +A prevailing indent distance is remembered between +successive indented paragraphs, +and is reset to default value upon reaching a non-indented paragraph. +Default units for indents +.I i +are ens. +.PP +The fonts are +.TP +.B R +roman, the main font, preferred for diagnostics +.PD 0 +.TP +.B I +italic, preferred for parameters, short names of commands, +names of manual pages, +and naked function names +.TP +.L B +`bold', actually the constant width font, +preferred for examples, file names, declarations, keywords, names of +.B struct +members, and literals +(numbers are rarely literals) +.TP +.B L +also the constant width font. +In +.I troff +.BR L = B ; +in +.I nroff +arguments of the macros +.BR .L , +.BR .LR , +and +.B .RL +are printed in quotes; +preferred only where quotes really help (e.g. lower-case literals and +punctuation). +.PD +.LP +Type font and size are reset to default values +before each paragraph, and after processing +font- or size-setting macros. +.PP +The +.B -man +macros admit equations and tables in the style of +.IR eqn (1) +and +.IR tbl (1), +but do not support arguments on +.B .EQ +and +.B .TS +macros. +.PP +These strings are predefined by +.BR -man : +.TP +.B \e*R +.if t `\*R', `(Reg)' in +.if t .IR nroff . +.if n `(Reg)', trademark symbol in +.if n .IR troff . +.br +.ns +.TP +.B \e*S +Change to default type size. +.SH FILES +.B /sys/lib/tmac/tmac.an +.SH SEE ALSO +.IR troff (1), +.IR man (1) +.SH REQUESTS +.ta \w'.TH n c x 'u +\w'Cause 'u +\w'Argument\ 'u +.di xx + \ka +.br +.di +.in \nau +.ti0 +Request Cause If no Explanation +.ti0 + Break Argument +.ti0 +\&\fL.B\fR \fIt\fR no \fIt\fR=n.t.l.* Text +.I t +is `bold'. +.ti0 +\&\fL.BI\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating bold and italic. +.ti0 +\&\fL.BR\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating bold and Roman. +.ti0 +\&\fL.DT\fR no Restore default tabs. +.ti0 +\&\fL.EE\fR yes End displayed example +.ti0 +\&\fL.EX\fR yes Begin displayed example +.ti0 +\&\fL.HP\fR \fIi\fR yes \fIi\fR=p.i.* Set prevailing indent to +.IR i . +Begin paragraph with hanging indent. +.ti0 +\&\fL.I\fR \fIt\fR no \fIt\fR=n.t.l. Text +.I t +is italic. +.ti0 +\&\fL.IB\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating italic and bold. +.ti0 +\&\fL.IP\fR \fIx i\fR yes \fIx\fR="" Same as \fL.TP\fP with tag +.IR x . +.ti0 +\&\fL.IR\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating italic and Roman. +.ti0 +\&\fL.L\fR \fIt\fR no \fIt\fR=n.t.l. Text +.I t +is literal. +.ti0 +\&\fL.LP\fR yes Same as \fL.PP\fP. +.ti0 +\&\fL.LR\fR \fIt\fR no Join 2 +words of +.I t +alternating literal and Roman. +.ti0 +\&\fL.PD\fR \fId\fR no \fId\fR=\fL.4v\fP Interparagraph distance is +.IR d . +.ti0 +\&\fL.PP\fR yes Begin paragraph. +Set prevailing indent to default. +.ti0 +\&\fL.RE\fR yes End of relative indent. +Set prevailing indent to amount of starting \fL.RS\fP. +.ti0 +\&\fL.RI\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating Roman and italic. +.ti0 +\&\fL.RL\fR \fIt\fR no Join 2 or 3 +words of +.I t +alternating Roman and literal. +.ti0 +\&\fL.RS\fR \fIi\fR yes \fIi\fR=p.i. Start relative indent, +move left margin in distance +.IR i . +Set prevailing indent to default for nested indents. +.ti0 +\&\fL.SH\fR \fIt\fR yes \fIt\fR="" Subhead; reset paragraph distance. +.ti0 +\&\fL.SM\fR \fIt\fR no \fIt\fR=n.t.l. Text +.I t +is small. +.ti0 +\&\fL.SS\fR \fIt\fR no \fIt\fR="" Secondary subhead. +.ti0 +\&\fL.TF\fR \fIs\fR yes Prevailing indent is wide as +string +.I s +in font +.BR L ; +paragraph distance is 0. +.ti0 +\&\fL.TH\fR \fIn c x\fR yes Begin page named +.I n +of chapter +.IR c; +.I x +is extra commentary, e.g. `local', for page head. +Set prevailing indent and tabs to default. +.ti0 +\&\fL.TP\fR \fIi\fR yes \fIi\fR=p.i. Set prevailing indent to +.IR i . +Restore default indent if +.IR i =0. +Begin indented paragraph +with hanging tag given by next text line. +If tag doesn't fit, place it on separate line. +.ti0 +\&\fL.1C\fR yes Equalize columns and return to 1-column output +.ti0 +\&\fL.2C\fR yes Start 2-column nofill output +.PP +.ti0 +* n.t.l. = next text line; p.i. = prevailing indent +.SH BUGS +There's no way to fool +.I troff +into handling literal double quote marks +.B \&" +in font-alternation macros, such as +.LR .BI . +.br +There is no direct way to suppress column widows in 2-column +output; the column lengths may be adjusted by inserting +.L .sp +requests before the closing +.LR .1C .
diff --git a/man/man7/map.7 b/man/man7/map.7 new file mode 100644 index 0000000..80e1eeb --- /dev/null +++ b/man/man7/map.7
@@ -0,0 +1,87 @@ +.TH MAP 7 +.SH NAME +map \- digitized map formats +.SH DESCRIPTION +Files used by +.IR map (7) +are a sequence of structures of the form: +.PP +.EX +struct { + signed char patchlatitude; + signed char patchlongitude; + short n; + union { + struct { + short latitude; + short longitude; + } point[n]; + struct { + short latitude; + short longitude; + struct { + signed char latdiff; + signed char londiff; + } point[\-n]; + } highres; + } segment; +}; +.EE +where +.B short +stands for 16-bit integers and there is no padding within or between +.BR structs . +Shorts are stored in little-endian order, low byte first. +To assure portability, +.I map +accesses them bytewise. +.PP +Fields +.L patchlatitude +and +.L patchlongitude +tell to what +10-degree by 10-degree +patch of the earth's surface a segment belongs. +Their values range from \-9 to 8 and from \-18 to 17, +respectively, and indicate the coordinates of the +southeast corner of the patch in units of 10 degrees. +.PP +Each segment of +.RB | n | +points is connected; consecutive segments +are not necessarily related. +Latitude and longitude +are measured in units of 0.0001 radian. +If +.B n +is negative, then +differences to the first and succeeding points +are measured in units of 0.00001 radian. +Latitude is counted positive to the north and +longitude positive to the west. +.PP +The patches are ordered lexicographically by +.L patchlatitude +then +.LR patchlongitude . +A printable +index to the first segment of each patch +in a file named +.I data +is kept in an associated file named +.IB data .x\f1. +Each line of an index file contains +.L patchlatitude, +.L patchlongitude +and the byte position +of the patch +in the map file. +Both the map file and the index file are ordered by +patch latitude and longitude. +.SH "SEE ALSO" +.IR map (7) +.br +The data comes from the World Data Bank I and II and +U.S. Government sources: the Census Bureau, Geological +Survey, and CIA.
diff --git a/man/man7/ms.7 b/man/man7/ms.7 new file mode 100644 index 0000000..b6c6788 --- /dev/null +++ b/man/man7/ms.7
@@ -0,0 +1,308 @@ +.TH MS 7 +.hc % +.SH NAME +ms \- macros for formatting manuscripts +.SH SYNOPSIS +.B "nroff -ms" +[ +.I options +] +.I file ... +.br +.B "troff -ms" +[ +.I options +] +.I file ... +.SH DESCRIPTION +This package of +.I nroff +and +.IR troff (1) +macro definitions provides a canned formatting +facility for tech%nical papers in various formats. +.PP +The macro requests are defined below. +Many +.I nroff +and +.I troff +requests are unsafe in conjunction with +this package, but the following requests may be used with +impunity after the first +.BR .PP : +.LR .bp , +.LR .br , +.LR .sp , +.LR .ls , +.LR .na . +.PP +Output of the +.IR eqn (1), +.IR tbl (1), +.IR pic (1) +and +.IR grap (1) +preprocessors +for equations, tables, pictures, and graphs is acceptable as input. +.SH FILES +.B /sys/lib/tmac/tmac.s +.SH "SEE ALSO" +.br +M. E. Lesk, +``Typing Documents on the UNIX System: Using the \-ms Macros with Troff and Nroff'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.br +.IR eqn (1), +.IR troff (1), +.IR tbl (1), +.IR pic (1) +.SH REQUESTS +.ta \w'..ND \fIdate\fR 'u +\w'Initial 'u +\w'Cause 'u +.br +.di x + \ka +.br +.di +.in \nau +.ti0 +Request Initial Cause Explanation +.ti0 + Value Break +.br +.in \nau +.ti0 +\fL\&.1C\fP yes yes One column format on a new page. +.ti0 +\fL\&.2C\fP no yes Two column format. +.ti0 +\fL\&.AB\fP no yes Begin abstract. +.ti0 +\fL\&.AE\fP - yes End abstract. +.ti0 +\fL\&.AI\fP no yes Author's institution follows. +Suppressed in +.BR .TM . +.ti0 +\fL\&.AT\fP no yes Print `Attached' and turn off line filling. +.ti0 +\fL\&.AU\fP\fP\fP \fIx y\fR no yes Author's name follows. +.IR x " is location and " y " is" +extension, ignored except in +.BR TM . +.ti0 +\fL\&.B\fP \fIx y\fR no no Print +.I x +in boldface, append +.IR y ; +if no argument switch to boldface. +.ti0 +\fL\&.B1\fP no yes Begin text to be enclosed in a box. +.ti0 +\fL\&.B2\fP no yes End boxed text. +.ti0 +\fL\&.BI\fP \fIx y\fR no no Print +.I x +in bold italic and append +.IR y ; +if no argument switch to bold italic. +.ti0 +\fL\&.BT\fP date no Bottom title, automatically invoked at +foot of page. +May be redefined. +.ti0 +\fL\&.BX\fP \fIx\fR no no Print +.I x +in a box. +.ti0 +\fL\&.CW\fP \fIx y\fR no no Constant width font for +.IR x , +append +.IR y ; +if no argument switch to constant width. +.ti0 +\fL\&.CT\fP no yes Print `Copies to' and turn off line filling. +.ti0 +\fL\&.DA\fP \fIx\fR nroff no `Date line' at bottom of page +is +.IR x . +Default is today. +.ti0 +\fL\&.DE\fP - yes End displayed text. +Implies +.BR .KE . +.ti0 +\fL\&.DS\fP \fIx\fR no yes Start of displayed text, +to appear verbatim line-by-line: +.L I +indented (default), +.L L +left-justified, +.L C +centered, +.L B +(block) centered with straight left margin. +Implies +.BR .KS . +.ti0 +\fL\&.EG\fP no - Print document in BTL format for `Engineer's Notes.' Must be first. +.ti0 +\fL\&.EN\fP - yes Space after equation +produced by +.I neqn +or +.IR eqn (1). +.ti0 +\fL\&.EQ\fP \fIx y\fR - yes Display equation. +Equation number is +.IR y . +Optional +.I x +is +.BR I ", " L ", " C +as in +.BR .DS . +.ti0 +\fL\&.FE\fP - yes End footnote. +.ti0 +\fL\&.FP\fP \fIx\fR - no Set font positions for a family, e.g., +.L .FP lucidasans +.ti0 +\fL\&.FS\fP no no Start footnote. +The note will be moved to the bottom of the page. +.ti0 +\fL\&.HO\fP - no `Bell Laboratories, Holmdel, +New Jersey 07733'. +.ti0 +\fL\&.I\fP \fIx y\fR no no Italicize +.IR x , +append +.IR y ; +if no argument switch to italic. +.ti0 +\fL\&.IH\fP no no `Bell Laboratories, Naperville, Illinois 60540' +.ti0 +\fL\&.IM\fP no no Print document in BTL format for an internal memorandum. Must be first. +.ti0 +\fL\&.IP\fP \fIx y\fR no yes Start indented paragraph, +with hanging tag +.IR x . +Indentation is +.I y +ens (default 5). +.ti0 +\fL\&.KE\fP - yes End keep. +Put kept text on next page if not enough room. +.ti0 +\fL\&.KF\fP no yes Start floating keep. +If the kept text must be moved to the next page, +float later text back to this page. +.ti0 +\fL\&.KS\fP no yes Start keeping following text. +.ti0 +\fL\&.LG\fP no no Make letters larger. +.ti0 +\fL\&.LP\fP yes yes Start left-blocked paragraph. +.ti0 +\fL\&.LT\fP no yes Start a letter; a non-empty first argument +produces a full Lucent letterhead, a second argument is a room number, +a third argument is a telephone number. +.ti0 +\fL\&.MF\fP - - Print document in BTL format for `Memorandum for File.' Must be first. +.ti0 +\fL\&.MH\fP - no `Bell Laboratories, Murray Hill, +New Jersey 07974'. +.ti0 +\fL\&.MR\fP - - Print document in BTL format for `Memorandum for Record.' Must be first. +.ti0 +\fL\&.ND\fP \fIdate\fR troff no Use date supplied (if any) only in +special BTL format positions; omit from page footer. +.ti0 +\fL\&.NH\fP \fIn\fR - yes Same as +.BR .SH , +with automatic section +numbers like `1.2.3'; +.I n +is subsection level (default 1). +.ti0 +\fL\&.NL\fP yes no Make letters normal size. +.ti0 +\fL\&.P1\fP - yes Begin program display in constant width font. +.ti0 +\fL\&.P2\fP - yes End program display. +.ti0 +\fL\&.PE\fP - yes End picture; see +.IR pic (1). +.ti0 +\fL\&.PF\fP - yes End picture; restore vertical +position. +.ti0 +\fL\&.PP\fP no yes Begin paragraph. +First line indented. +.ti0 +\fL\&.PS\fP \fIh w\fR - yes Start picture; height +and width in inches. +.ti0 +\fL\&.PY\fP - no `Bell Laboratories, Piscataway, New Jersey 08854' +.ti0 +\fL\&.QE\fP - yes End quoted material. +.ti0 +\fL\&.QP\fP - yes Begin quoted paragraph (indent both margins). +.ti0 +\fL\&.QS\fP - yes Begin quoted material (indent both margins). +.ti0 +\fL\&.R\fP yes no Roman text follows. +.ti0 +\fL\&.RE\fP - yes End relative indent level. +.ti0 +\fL\&.RP\fP no - Cover sheet and first page for released +paper. +Must precede other requests. +.ti0 +\fL\&.RS\fP - yes Start level of relative indentation +from which subsequent indentation is measured. +.ti0 +\fL\&.SG\fP \fIx\fR no yes Insert signature(s) of author(s), +ignored except in +.B .TM +and +.BR .LT . +.IR x " is the reference line (initials of author and typist)." +.ti0 +\fL\&.SH\fP - yes Section head follows, +font automatically bold. +.ti0 +\fL\&.SM\fP no no Make letters smaller. +.ti0 +\fL\&.TA\fP\ \fIx\fR... 5... no Set tabs in ens. +Default is 5 10 15 ... +.ti0 +\fL\&.TE\fP - yes End table; see +.IR tbl (1). +.ti0 +\fL\&.TH\fP - yes End heading section of table. +.ti0 +\fL\&.TL\fP no yes Title follows. +.ti0 +\fL\&.TM\fP\ \fIx\fR... no - Print document in BTL technical memorandum format. +Arguments are TM number, (quoted list of) case number(s), and file number. +Must precede other requests. +.ti0 +\fL\&.TR\fP \fIx\fR - - Print in BTL technical report format; report number is \fIx\fR. Must be first. +.ti0 +\fL\&.TS\fP \fIx\fR - yes Begin table; if +.I x +is +.B H +table heading is repeated on new pages. +.ti0 +\fL\&.UL\fP \fIx\fR - no Underline argument (even in troff). +.ti0 +\fL\&.UX\fP\ \fIy z\fP - no `\fIz\fRUNIX\fIy\fP'; +first use gives registered trademark notice. +.ti0 +\fL\&.WH\fP - no `Bell Laboratories, Whippany, +New Jersey 07981'. +.hc
diff --git a/man/man7/plot.7 b/man/man7/plot.7 new file mode 100644 index 0000000..452ab19 --- /dev/null +++ b/man/man7/plot.7
@@ -0,0 +1,336 @@ +.TH PLOT 7 +.SH NAME +plot \- graphics interface +.SH DESCRIPTION +Files of this format are interpreted by +.IR plot (1) +to draw graphics on the screen. +A +.I plot +file is a +.SM UTF +stream of +instruction lines. +Arguments are delimited by spaces, tabs, or commas. +Numbers may be floating point. +Punctuation marks (except +.LR : ) +, +spaces, and tabs at the beginning of lines are ignored. +Comments run from +.L : +to newline. +Extra letters appended to a valid instruction are ignored. +Thus +.LR ...line , +.LR line , and +.L li +all mean the same thing. +Arguments are interpreted as follows: +.TP +1. +If an instruction requires no arguments, the rest of the line is ignored. +.TP +2. +If it requires a string argument, then all the line +after the first field separator is passed as argument. +Quote marks may be used to preserve leading blanks. +Strings may include newlines represented as +.LR \en . +.TP +3. +Between numeric arguments alphabetic characters and +punctuation marks are ignored. +Thus +.L +line from 5 6 to 7 8 +draws a line from (5, 6) to (7, 8). +.TP +4. +Instructions with numeric arguments remain in effect until +a new instruction is read. +Such commands may spill over many lines. Thus +the following sequence will draw a polygon +with vertices +(4.5, 6.77), (5.8, 5.6), (7.8, 4.55), and (10.0, 3.6). +.IP +.EX +move 4.5 6.77 +vec 5.8, 5.6 7.8 +4.55 10.0, 3.6 4.5, 6.77 +.EE +.PP +The instructions are executed in order. +The last designated point in a +.BR line ", " move ", " rmove , +.BR vec ", " rvec ", " arc , +or +.B point +command becomes the `current point' +.RI ( X,Y ) +for the next command. +.SS "Open & Close" +.PD0 +.TP 10 +.BI o " string" +Open plotting device. +For +.IR troff , +.I string +specifies the size of the plot +(default is +.LR 6i ). +.TP 10 +.B cl +Close plotting device. +.PD +.SS "Basic Plotting Commands" +.PD0 +.TP 10 +.B e +Start another frame of output. +.TP 10 +.BI m " x y" +(move) Current point becomes +.I "x y." +.TP 10 +.BI rm " dx dy" +Current point becomes +.I "X+dx Y+dy." +.TP 10 +.BI poi " x y" +Plot the point +.I "x y" +and make it the current point. +.TP 10 +.BI v " x y" +Draw a vector from the current point to +.I "x y." +.TP 10 +.BI rv " dx dy" +Draw vector from current point to +.RI X + dx +.RI Y + dy +.TP 10 +.BI li " x1 y1 x2 y2" +Draw a line from +.I "x1 y1" +to +.I "x2 y2." +Make the current point +.I "x2 y2." +.TP 10 +.BI t " string" +Place the +.I string +so that its +first character is centered on the current point (default). +If +.I string +begins with +.L \eC +.RL ( \eR ), +it is centered (right-adjusted) on the current point. +A backslash at the beginning of the string may +be escaped with another backslash. +.TP 10 +.BI a " x1 y1 x2 y2 xc yc r" +Draw a circular arc from +.I "x1 y1" +to +.I "x2 y2" +with center +.I "xc yc" +and radius +.IR r . +If the radius is positive, the arc is drawn counterclockwise; +negative, clockwise. +The starting point is exact but the ending point is approximate. +.TP 10 +.BI ci " xc yc r" +Draw a circle centered at +.I "xc yc" +with radius +.IR r . +If the range and frame parameters do not specify a square, +the `circle' will be elliptical. +.TP 10 +.BI di " xc yc r" +Draw a disc centered at +.I "xc yc" +with radius +.I r +using the filling color (see +.B cfill +below). +.TP 10 +.BI bo " x1 y1 x2 y2" +Draw a box with lower left corner at +.I "x1 y1" +and upper right corner at +.I "x2 y2." +.TP 10 +.BI sb " x1 y1 x2 y2" +Draw a solid box with lower left corner at +.I "x1 y1" +and upper right corner at +.I "x2 y2" +using the filling color (see +.B cfill +below). +.TP 10 +.BI par " x1 y1 x2 y2 xg yg" +Draw a parabola from +.I "x1 y1" +to +.I "x2 y2" +`guided' by +.I "xg yg." +The parabola passes through the midpoint of the line joining +.I "xg yg" +with the midpoint of the line +joining +.I "x1 y1" +and +.I "x2 y2" +and is tangent to the lines from +.I "xg yg" +to the endpoints. +.TP 10 +.BI "pol { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fP} }\fI" +Draw polygons with vertices +.I "x1 y1 ... xn yn" +and +.I "X1 Y1 ... Xm Ym." +If only one polygon is specified, the inner brackets are +not needed. +.TP 10 +.BI "fi { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fP} }\fI" +Fill a polygon. +The arguments are the same as those for +.B pol +except that the first vertex is automatically repeated to +close each polygon. +The polygons do not have to be connected. +Enclosed polygons appear as holes. +.TP 10 +.BI "sp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with simple endpoints. +.TP 10 +.BI "fsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with double first endpoint. +.TP 10 +.BI "lsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with double last endpoint. +.TP 10 +.BI "dsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with double endpoints. +.TP 10 +.BI "csp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +.TP 10 +.BI in " filename" +(include) Take commands from +.IR filename . +.TP 10 +.BI de " string " { " commands " } +Define +.I string +as +.IR commands . +.TP 10 +.BI ca " string scale" +Invoke commands defined as +.I string +applying +.I scale +to all coordinates. +.PD +.SS "Commands Controlling the Environment" +.PD0 +.TP 10 +.BI co " string" +Use color given by first character of +.IR string , +one of +.BR red , +.BR yellow , +.BR green , +.BR blue , +.BR cyan , +.BR magenta , +.BR white , +and +.BR kblack . +.TP 10 +.BI pe " string" +Use +.I string +as the style for drawing lines. +The available pen styles are: +.BR solid , +.BR dott [ed], +.BR short , +.BR long , +.BR dotd [ashed] , +.BR cdash , +.BR ddash +.TP 10 +.BI cf " string" +Color for filling (see +.BR co , +above). +.TP 10 +.BI ra " x1 y1 x2 y2" +The data will fall between +.I "x1 y1" +and +.I "x2 y2." +The plot will be magnified or reduced to fit +the device as closely as possible. +.IP +Range settings that exactly fill the plotting area +with unity scaling appear below for +devices supported by the filters of +.IR plot (1). +The upper limit is just outside the plotting area. +In every case the plotting area is taken to be square; +points outside may be displayable on +devices with nonsquare faces. +.TP 10 +.BI fr " px1 py1 px2 py2" +Plot the data in the fraction of the display +specified by +.I "px1 py1" +for lower left corner +and +.I "px2 py2" +for upper right corner. +Thus +.L frame .5 0 1. .5 +plots in the lower right +quadrant of the display; +.L frame 0. 1. 1. 0. +uses the whole display but +inverts the +.I y +coordinates. +.TP 10 +.B sa +Save the current environment, and move to a new one. +The new environment inherits the old one. +There are 7 levels. +.TP 10 +.B re +Restore previous environment. +.PD +.SH "SEE ALSO" +.IR plot (1), +.IR graph (1)
diff --git a/man/man7/plumb.7 b/man/man7/plumb.7 new file mode 100644 index 0000000..a3c10e1 --- /dev/null +++ b/man/man7/plumb.7
@@ -0,0 +1,417 @@ +.TH PLUMB 7 +.SH NAME +plumb \- format of plumb messages and rules +.SH SYNOPSIS +.B #include <plumb.h> +.SH DESCRIPTION +.SS "Message format +The messages formed by the +.IR plumb (3) +library are formatted for transmission between +processes into textual form, using newlines to separate +the fields. +Only the data field may contain embedded newlines. +The fields occur in a specified order, +and each has a name, corresponding to the elements +of the +.B Plumbmsg +structure, that is used in the plumbing rules. +The fields, in order, are: +.RS +.TF ndata +.TP +.B src +application/service generating message +.TP +.B dst +destination `port' for message +.TP +.B wdir +working directory (used if data is a file name) +.TP +.B type +form of the data, e.g. +.B text +.TP +.B attr +attributes of the message, in +.IB name = value +pairs separated by white space +(the value must follow the usual quoting convention if it contains +white space or quote characters or equal signs; it cannot contain a newline) +.TP +.B ndata +number of bytes of data +.TP +.B data +the data itself +.RE +At the moment, only textual data +.RB ( type=text ) +is supported. +.PD +.PP +All fields are optional, but +.B type +should usually be set since it describes the form of the data, and +.B ndata +must be an accurate count (possibly zero) of the number of bytes of data. +A missing field is represented by an empty line. +.SS "Plumbing rules +The +.B plumber +(see +.IR plumb (1)) +receives messages on its +.B send +port (applications +.I send +messages there), interprets and reformats them, and (typically) emits them from a destination port. +Its behavior is determined by a plumbing rules file, default +.BR /usr/$user/lib/plumbing , +which defines a set of pattern/action rules with which to analyze, rewrite, and dispatch +received messages. +.PP +The file is a sequence of rule sets, each of which is a set of one-line rules +called patterns and actions. +There must be at least one pattern and one action in each rule set. +(The only exception is that a rule set may contain nothing but +.B plumb +.B to +rules; such a rule set declares the named ports but has no other effect.) +A blank line terminates a rule set. +Lines beginning with a +.B # +character are commentary and are regarded as blank lines. +.PP +A line of the form +.EX + include \f2file\fP +.EE +substitutes the contents of +.I file +for the line, much as in a C +.B #include +statement. Unlike in C, the file name is not quoted. +If +.I file +is not an absolute path name, or one beginning +.B ./ +or +.BR ../ , +.I file +is looked for first in the directory in which the plumber is executing, +and then in +.BR /sys/lib/plumb . +.PP +When a message is received by the +.BR plumber , +the rule sets are examined in order. +For each rule set, if the message matches all the patterns in the rule set, +the actions associated with the rule set are triggered to dispose of the message. +If a rule set is triggered, the rest are ignored for this message. +If none is triggered, the message is discarded (giving a write error to the sender) +unless it has a +.B dst +field that specifies an existing port, in which case the message is emitted, unchanged, from there. +.PP +Patterns and actions all consist of three components: an +.IR object , +a +.IR verb , +and arguments. +These are separated by white space on the line. +The arguments may contain quoted strings and variable substitutions, +described below, and in some cases contain multiple words. +The object and verb are single words from a pre-defined set. +.PP +The object in a pattern is the name of an element of the message, such as +.B src +or +.BR data , +or the special case +.BR arg , +which refers to the argument component of the current rule. +The object in an action is always the word +.BR plumb . +.PP +The verbs in the pattern rules +describe how the objects and arguments are to be interpreted. +Within a rule set, the patterns are evaluated in sequence; if one fails, +the rule set fails. +Some verbs are predicates that check properties of the message; others rewrite +components of the message and implicitly always succeed. +Such rewritings are permanent, so rules that specify them should be placed after +all pattern-matching rules in the rule set. +.RS +.TF delete +.TP +.B add +The object must be +.BR attr . +Append the argument, which must be a sequence of +.IB name = value +pairs, to the list of attributes of the message. +.TP +.B delete +The object must be +.BR attr . +If the message has an attribute whose name is the argument, +delete it from the list of attributes of the message. +(Even if the message does not, the rule matches the message.) +.TP +.B is +If the text of the object is identical to the text of the argument, +the rule matches. +.TP +.B isdir +If the text of the object +is the name of an existing directory, the rule matches and +sets the variable +.B $dir +to that directory name. +.TP +.B isfile +If the text of the object is the name of an existing file (not a directory), +the rule matches and sets the variable +.B $file +to that file name. +.TP +.B matches +If the entire text of the object matches the regular expression +specified in the argument, the rule matches. +This verb is described in more detail below. +.TP +.B set +The value of the object is set to the value of the argument. +.RE +.PP +The +.B matches +verb has special properties that enable the rules to select which portion of the +data is to be sent to the destination. +By default, a +.B data +.B matches +rule requires that the entire text matches the regular expression. +If, however, the message has an attribute named +.BR click , +that reports that the message was produced by a mouse click within the +text and that the regular expressions in the rule set should be used to +identify what portion of the data the user intended. +Typically, a program such as an editor will send a white-space delimited +block of text containing the mouse click, using the value of the +.B click +attribute (a number starting from 0) to indicate where in the textual data the user pointed. +.PP +When the message has a +.B click +attribute, the +.B data +.B matches +rules extract the longest leftmost match to the regular expression that contains or +abuts the textual location identified by the +.BR click . +For a sequence of such rules within a given rule set, each regular expression, evaluated +by this specification, must match the same subset of the data for the rule set to match +the message. +For example, here is a pair of patterns that identify a message whose data contains +the name of an existing file with a conventional ending for an encoded picture file: +.EX + data matches '[a-zA-Z0-9_\-./]+' + data matches '([a-zA-Z0-9_\-./]+)\.(jpe?g|gif|bit|ps|pdf)' +.EE +The first expression extracts the largest subset of the data around the click that contains +file name characters; the second sees if it ends with, for example, +.BR \&.jpeg . +If only the second pattern were present, a piece of text +.B horse.gift +could be misinterpreted as an image file named +.BR horse.gif . +.PP +If a +.B click +attribute is specified in a message, it will be deleted by the +.B plumber +before sending the message if the +.B data +.B matches +rules expand the selection. +.PP +The action rules all have the object +.BR plumb . +There are only three verbs for action rules: +.RS +.TF client +.TP +.B to +The argument is the name of the port to which the message will be sent. +If the message has a destination specified, it must match the +.B to +port of the rule set or the entire rule set will be skipped. +(This is the only rule that is evaluated out of order.) +.TP +.B client +If no application has the port open, the arguments to a +.B plumb +.B start +rule specify a shell program to run in response to the message. +The message will be held, with the supposition that the program +will eventually open the port to retrieve it. +.TP +.B start +Like +.BR client , +but the message is discarded. +Only one +.B start +or +.B client +rule should be specified in a rule set. +.RE +.PP +The arguments to all rules may contain quoted strings, exactly as in +.IR rc (1). +They may also contain simple string variables, identified by a leading dollar sign +.BR $ . +Variables may be set, between rule sets, by assignment statements in the style of +.BR rc . +Only one variable assignment may appear on a line. +The +.B plumber +also maintains some built-in variables: +.RS +.TF $wdir +.TP +.B $0 +The text that matched the entire regular expression in a previous +.B data +.B matches +rule. +.BR $1 , +.BR $2 , +etc. refer to text matching the first, second, etc. parenthesized subexpression. +.TP +.B $attr +The textual representation of the attributes of the message. +.TP +.B $data +The contents of the data field of the message. +.TP +.B $dir +The directory name resulting from a successful +.B isdir +rule. +If no such rule has been applied, it is the string constructed +syntactically by interpreting +.B data +as a file name in +.BR wdir . +.TP +.B $dst +The contents of the +.B dst +field of the message. +.TP +.B $file +The file name resulting from a successful +.B isfile +rule. +If no such rule has been applied, it is the string constructed +syntactically by interpreting +.B data +as a file name in +.BR wdir . +.TP +.B $type +The contents of the +.B type +field of the message. +.TP +.B $src +The contents of the +.B src +field of the message. +.TP +.B $wdir +The contents of the +.B wdir +field of the message. +.RE +.SH EXAMPLE +The following is a modest, representative file of plumbing rules. +.EX +# these are generally in order from most specific to least, +# since first rule that fires wins. + +addr=':(#?[0-9]+)' +protocol='(https?|ftp|file|gopher|mailto|news|nntp|telnet|wais)' +domain='[a-zA-Z0-9_@]+([.:][a-zA-Z0-9_@]+)*/?[a-zA-Z0-9_?,%#~&/\e-]+' +file='([:.][a-zA-Z0-9_?,%#~&/\e-]+)*' + +# image files go to page +type is text +data matches '[a-zA-Z0-9_\e-./]+' +data matches '([a-zA-Z0-9_\e-./]+)\.(jpe?g|gif|bit)' +arg isfile $0 +plumb to image +plumb start page -w $file + +# URLs go to web browser +type is text +data matches $protocol://$domain$file +plumb to web +plumb start window webbrowser $0 + +# existing files, possibly tagged by line number, go to edit/sam +type is text +data matches '([.a-zA-Z0-9_/\-]+[a-zA-Z0-9_/\e-])('$addr')?' +arg isfile $1 +data set $file +attr add addr=$3 +plumb to edit +plumb start window sam $file + +# .h files are looked up in /sys/include and passed to edit/sam +type is text +data matches '([a-zA-Z0-9]+\e.h)('$addr')?' +arg isfile /sys/include/$1 +data set $file +attr add addr=$3 +plumb to edit +plumb start window sam $file +.EE +.PP +The following simple plumbing rules file is a good beginning set of rules. +.EX +# to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules + +editor = acme +# or editor = sam +include basic +.EE +.SH FILES +.TF /usr/$user/lib/plumbing +.TP +.B /usr/$user/lib/plumbing +default rules file. +.TP +.B /mnt/plumb +mount point for +.IR plumber (4). +.TP +.B /sys/lib/plumb +directory for +.B include +files. +.TP +.B /sys/lib/plumb/fileaddr +public macro definitions. +.TP +.B /sys/lib/plumb/basic +basic rule set. +.SH "SEE ALSO" +.IR plumb (1), +.IR plumb (3), +.IR plumber (4), +.IR regexp (7)
diff --git a/man/man7/regexp.7 b/man/man7/regexp.7 index 14a90d0..75640b9 100644 --- a/man/man7/regexp.7 +++ b/man/man7/regexp.7
@@ -1,4 +1,4 @@ -.TH REGEXP9 7 +.TH REGEXP 7 .de EX .nf .ft B @@ -17,11 +17,11 @@ .if n .RB ` \\$1 ' .. .SH NAME -regexp9 \- Plan 9 regular expression notation +regexp \- Plan 9 regular expression notation .SH DESCRIPTION This manual page describes the regular expression syntax used by the Plan 9 regular expression library -.IR regexp9 (3). +.IR regexp (3). It is the form used by .IR egrep (1) before @@ -147,4 +147,4 @@ extends as far as possible without preventing a match to the remainder of the regular expression. .SH "SEE ALSO" -.IR regexp9 (3) +.IR regexp (3)
diff --git a/man/man7/regexp9.7 b/man/man7/regexp9.7 new file mode 100644 index 0000000..14a90d0 --- /dev/null +++ b/man/man7/regexp9.7
@@ -0,0 +1,150 @@ +.TH REGEXP9 7 +.de EX +.nf +.ft B +.. +.de EE +.fi +.ft R +.. +.de LR +.if t .BR \\$1 \\$2 +.if n .RB ` \\$1 '\\$2 +.. +.de L +.nh +.if t .B \\$1 +.if n .RB ` \\$1 ' +.. +.SH NAME +regexp9 \- Plan 9 regular expression notation +.SH DESCRIPTION +This manual page describes the regular expression +syntax used by the Plan 9 regular expression library +.IR regexp9 (3). +It is the form used by +.IR egrep (1) +before +.I egrep +got complicated. +.PP +A +.I "regular expression" +specifies +a set of strings of characters. +A member of this set of strings is said to be +.I matched +by the regular expression. In many applications +a delimiter character, commonly +.LR / , +bounds a regular expression. +In the following specification for regular expressions +the word `character' means any character (rune) but newline. +.PP +The syntax for a regular expression +.B e0 +is +.IP +.EX +e3: literal | charclass | '.' | '^' | '$' | '(' e0 ')' + +e2: e3 + | e2 REP + +REP: '*' | '+' | '?' + +e1: e2 + | e1 e2 + +e0: e1 + | e0 '|' e1 +.EE +.PP +A +.B literal +is any non-metacharacter, or a metacharacter +(one of +.BR .*+?[]()|\e^$ ), +or the delimiter +preceded by +.LR \e . +.PP +A +.B charclass +is a nonempty string +.I s +bracketed +.BI [ \|s\| ] +(or +.BI [^ s\| ]\fR); +it matches any character in (or not in) +.IR s . +A negated character class never +matches newline. +A substring +.IB a - b\f1, +with +.I a +and +.I b +in ascending +order, stands for the inclusive +range of +characters between +.I a +and +.IR b . +In +.IR s , +the metacharacters +.LR - , +.LR ] , +an initial +.LR ^ , +and the regular expression delimiter +must be preceded by a +.LR \e ; +other metacharacters +have no special meaning and +may appear unescaped. +.PP +A +.L . +matches any character. +.PP +A +.L ^ +matches the beginning of a line; +.L $ +matches the end of the line. +.PP +The +.B REP +operators match zero or more +.RB ( * ), +one or more +.RB ( + ), +zero or one +.RB ( ? ), +instances respectively of the preceding regular expression +.BR e2 . +.PP +A concatenated regular expression, +.BR "e1\|e2" , +matches a match to +.B e1 +followed by a match to +.BR e2 . +.PP +An alternative regular expression, +.BR "e0\||\|e1" , +matches either a match to +.B e0 +or a match to +.BR e1 . +.PP +A match to any part of a regular expression +extends as far as possible without preventing +a match to the remainder of the regular expression. +.SH "SEE ALSO" +.IR regexp9 (3)
diff --git a/man/man7/thumbprint.7 b/man/man7/thumbprint.7 new file mode 100644 index 0000000..743172d --- /dev/null +++ b/man/man7/thumbprint.7
@@ -0,0 +1,41 @@ +.TH THUMBPRINT 7 +.SH NAME +thumbprint \- public key thumbprints +.SH DESCRIPTION +.PP +Applications in Plan 9 that use public keys for authentication, +for example by calling +.B tlsClient +and +.B okThumbprint +(see +.IR pushtls (3)), +check the remote side's public key by comparing against +thumbprints from a trusted list. +The list is maintained by people who set local policies +about which servers can be trusted for which applications, +thereby playing the role taken by certificate authorities +in PKI-based systems. +By convention, these lists are stored as files in +.B /sys/lib/tls/ +and protected by normal file system permissions. +.PP +Such a thumbprint file comprises lines made up of +attribute/value pairs of the form +.IB attr = value +or +.IR attr . +The first attribute must be +.B x509 +and the second must be +.BI sha1= {hex checksum of binary certificate}. +All other attributes are treated as comments. +The file may also contain lines of the form +.BI #include file +.PP +For example, a web server might have thumbprint +.EX +x509 sha1=8fe472d31b360a8303cd29f92bd734813cbd923c cn=*.cs.bell-labs.com +.EE +.SH "SEE ALSO" +.IR pushtls (3)
diff --git a/man/man7/utf.7 b/man/man7/utf.7 index 97b7b1e..a240945 100644 --- a/man/man7/utf.7 +++ b/man/man7/utf.7
@@ -57,7 +57,7 @@ .SM ASCII input. See -.IR rune (2). +.IR rune (3). .PP Letting numbers be binary, a rune x is converted to a multibyte
diff --git a/man/man8/INDEX b/man/man8/INDEX new file mode 100644 index 0000000..9ca1d02 --- /dev/null +++ b/man/man8/INDEX
@@ -0,0 +1,2 @@ +dump9660 mk9660.8 +mk9660 mk9660.8
diff --git a/man/man8/mk9660.8 b/man/man8/mk9660.8 new file mode 100644 index 0000000..85edf2d --- /dev/null +++ b/man/man8/mk9660.8
@@ -0,0 +1,233 @@ +.TH MK9660 8 +.SH NAME +dump9660, mk9660 \- create an ISO-9660 CD image +.SH SYNOPSIS +.B disk/mk9660 +[ +.B -:D +] +[ +.B -9cjr +] +[ +.B -b +.I bootfile +] +[ +.B -p +.I proto +] +[ +.B -s +src +] +[ +.B -v +volume +] +.I image +.PP +.B disk/dump9660 +[ +.B -:D +] +[ +.B -9cjr +] +[ +.B -p +.I proto +] +[ +.B -s +src +] +[ +.B -v +volume +] +[ +.B -m +.I maxsize +] +[ +.B -n +.I now +] +.I image +.SH DESCRIPTION +.I Mk9660 +writes to the random access file +.I image +an ISO-9660 CD image containing the +files named in +.I proto +(by default, +.BR /sys/lib/sysconfig/proto/allproto ) +from the file tree +.I src +(by default, +the current directory). +The +.I proto +file is formatted as described in +.IR proto (3). +.PP +The created CD image will be in ISO-9660 +format, but by default the file names will +be stored in UTF-8 with no imposed length +or character restrictions. +The +.B -c +flag causes +.I mk9660 +to use only file names in ``8.3'' form +that use digits, letters, and underscore. +File names that do not conform are changed +to +.BI D nnnnnn +(for directories) +or +.BI F nnnnnn +(for files); +a key file +.B _CONFORM.MAP +is created in the root +directory to ease the reverse process. +.PP +If the +.B -9 +flag is given, the system use fields at the end of +each directory entry will be populated with +Plan directory information (owner, group, mode, +full name); this is interpreted by +.IR 9660srv . +.PP +If the +.B -j +flag is given, the usual directory tree is written, +but an additional tree in Microsoft Joliet format is +also added. +This second tree can contain long Unicode file names, +and can be read by +.I 9660srv +as well as most versions of Windows +and many Unix clones. +The characters +.BR * , +.BR : , +.BR ; , +.BR ? , +and +.B \e +are allowed in Plan 9 file names but not in Joliet file names; +non-conforming file names are translated +and a +.B _CONFORM.MAP +file written +as in the case of the +.B -c +option. +.PP +If the +.B -r +flag is given, Rock Ridge extensions are written in the +format of the system use sharing protocol; +this format provides Posix-style file metadata and is +common on Unix platforms. +.PP +The options +.BR -c , +.BR -9 , +.BR -j , +and +.B -r +may be mixed freely with the exception that +.B -9 +and +.B -r +are mutually exclusive. +.PP +The +.B -v +flag sets the volume title; +if unspecified, the base name of +.I proto +is used. +.PP +The +.B -: +flag causes +.B mk9660 +to replace colons in scanned file names with spaces; +this is the inverse of the map applied by Plan 9's +\fIdossrv\fR(4) +and is useful for writing Joliet CDs containing data +from FAT file systems. +.PP +The +.B -b +option creates a bootable CD. +Bootable CDs contain pointers to floppy images which are +loaded and booted by the BIOS. +.I Bootfile +should be the name of the floppy image to use; +it is a path relative to the root of the created CD. +That is, the boot floppy image must be listed in the +.I proto +file already: +the +.B -b +flag just creates a pointer to it. +.PP +The +.B -D +flag creates immense amounts of debugging output +on standard error. +.PP +.I Dump9660 +is similar in specification to +.I mk9660 +but creates and updates backup CD images in the style of +the +.I dump +file system +(see Plan 9's \fIfs\fR(4)). +The dump is file-based rather than block-based: +if a file's contents have not changed since the last +backup, only its directory entry will be rewritten. +.PP +The +.B -n +option specifies a time (in seconds since January 1, 1970) +to be used for naming the dump directory. +.PP +The +.B -m +option specifies a maximum size for the image; +if a backup would cause the image to grow larger than +.IR maxsize , +it will not be written, and +.I dump9660 +will exit with a non-empty status. +.SH EXAMPLE +.PP +Create an image of the Plan 9 source tree, +including a conformant ISO-9660 directory tree, +Plan 9 extensions in the system use fields, and +a Joliet directory tree. +.IP +.EX +disk/mk9660 -9cj -s /n/bootes \e + -p /sys/lib/sysconfig/srcproto cdimage +.EE +.SH SOURCE +/usr/local/plan9/src/cmd/9660 +.SH "SEE ALSO +.IR proto (3) +.\" .SH "SEE ALSO" +.\" .I 9660srv +.\" (in +.\" .IR dossrv (4)), +.\" .IR cdfs (4), +.\" .IR proto (3)
diff --git a/man/man9/0intro.9p b/man/man9/0intro.9p new file mode 100644 index 0000000..397486f --- /dev/null +++ b/man/man9/0intro.9p
@@ -0,0 +1,630 @@ +.TH INTRO 9P +.SH NAME +intro \- introduction to the Plan 9 File Protocol, 9P +.SH SYNOPSIS +.B #include <fcall.h> +.SH DESCRIPTION +A Plan 9 +.I server +is an agent that provides one or more hierarchical file systems +\(em file trees \(em +that may be accessed by Plan 9 processes. +A server responds to requests by +.I clients +to navigate the hierarchy, +and to create, remove, read, and write files. +The prototypical server is a separate machine that stores +large numbers of user files on permanent media; +such a machine is called, somewhat confusingly, a +.I file +.IR server . +Another possibility for a server is to synthesize +files on demand, perhaps based on information on data structures +maintained in memory; the +.IR plumber (4) +server is an example of such a server. +.PP +A +.I connection +to a server is a bidirectional communication path from the client to the server. +There may be a single client or +multiple clients sharing the same connection. +.PP +The +.IR "Plan 9 File Protocol" , +9P, is used for messages between +.I clients +and +.IR servers . +A client transmits +.I requests +.RI ( T-messages ) +to a server, which +subsequently returns +.I replies +.RI ( R-messages ) +to the client. +The combined acts of transmitting (receiving) a request of a particular type, +and receiving (transmitting) +its reply is called a +.I transaction +of that type. +.PP +Each message consists of a sequence of bytes. +Two-, four-, and eight-byte fields hold unsigned +integers represented in little-endian order +(least significant byte first). +Data items of larger or variable lengths are represented +by a two-byte field specifying a count, +.IR n , +followed by +.I n +bytes of data. +Text strings are represented this way, +with the text itself stored as a UTF-8 +encoded sequence of Unicode characters (see +.IR utf (7)). +Text strings in 9P messages are not +.SM NUL\c +-terminated: +.I n +counts the bytes of UTF-8 data, which include no final zero byte. +The +.SM NUL +character is illegal in all text strings in 9P, and is therefore +excluded from file names, user names, and so on. +.PP +Each 9P message begins with a four-byte size field +specifying the length in bytes of the complete message including +the four bytes of the size field itself. +The next byte is the message type, one of the constants +in the enumeration in the include file +.BR <fcall.h> . +The next two bytes are an identifying +.IR tag , +described below. +The remaining bytes are parameters of different sizes. +In the message descriptions, the number of bytes in a field +is given in brackets after the field name. +The notation +.IR parameter [ n ] +where +.I n +is not a constant represents a variable-length parameter: +.IR n [2] +followed by +.I n +bytes of data forming the +.IR parameter . +The notation +.IR string [ s ] +(using a literal +.I s +character) +is shorthand for +.IR s [2] +followed by +.I s +bytes of UTF-8 text. +(Systems may choose to reduce the set of legal characters +to reduce syntactic problems, +for example to remove slashes from name components, +but the protocol has no such restriction. +Plan 9 names may contain any printable character (that is, any character +outside hexadecimal 00-1F and 80-9F) +except slash.) +Messages are transported in byte form to allow for machine independence; +.IR fcall (3) +describes routines that convert to and from this form into a machine-dependent +C structure. +.SH MESSAGES +.ta \w'\fLTsession 'u +.IP +.ne 2v +.IR size [4] +.B Tversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.br +.IR size [4] +.B Rversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.IP +.ne 2v +.IR size [4] +.B Tauth +.IR tag [2] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.br +.IR size [4] +.B Rauth +.IR tag [2] +.IR aqid [13] +.IP +.ne 2v +.IR size [4] +.B Rerror +.IR tag [2] +.IR ename [ s ] +.IP +.ne 2v +.IR size [4] +.B Tflush +.IR tag [2] +.IR oldtag [2] +.br +.IR size [4] +.B Rflush +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tattach +.IR tag [2] +.IR fid [4] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.IR size [4] +.B Rattach +.IR tag [2] +.IR qid [13] +.IP +.ne 2v +.IR size [4] +.B Twalk +.IR tag [2] +.IR fid [4] +.IR newfid [4] +.IR nwname [2] +.IR nwname *( wname [ s ]) +.br +.IR size [4] +.B Rwalk +.IR tag [2] +.IR nwqid [2] +.IR nwqid *( wqid [13]) +.IP +.ne 2v +.IR size [4] +.B Topen +.IR tag [2] +.IR fid [4] +.IR mode [1] +.br +.IR size [4] +.B Ropen +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IP +.ne 2v +.IR size [4] +.B Topenfd +.IR tag [2] +.IR fid [4] +.IR mode [1] +.br +.IR size [4] +.B Ropenfd +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IR unixfd [4] +.IP +.ne 2v +.IR size [4] +.B Tcreate +.IR tag [2] +.IR fid [4] +.IR name [ s ] +.IR perm [4] +.IR mode [1] +.br +.IR size [4] +.B Rcreate +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IP +.ne 2v +.IR size [4] +.B Tread +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.br +.IR size [4] +.B Rread +.IR tag [2] +.IR count [4] +.IR data [ count ] +.IP +.ne 2v +.IR size [4] +.B Twrite +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.IR data [ count ] +.br +.IR size [4] +.B Rwrite +.IR tag [2] +.IR count [4] +.IP +.ne 2v +.IR size [4] +.B Tclunk +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rclunk +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tremove +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rremove +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tstat +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rstat +.IR tag [2] +.IR stat [ n ] +.IP +.ne 2v +.IR size [4] +.B Twstat +.IR tag [2] +.IR fid [4] +.IR stat [ n ] +.br +.IR size [4] +.B Rwstat +.IR tag [2] +.PP +Each T-message has a +.I tag +field, chosen and used by the client to identify the message. +The reply to the message will have the same tag. +Clients must arrange that no two outstanding messages +on the same connection have the same tag. +An exception is the tag +.BR NOTAG , +defined as +.B (ushort)~0 +in +.BR <fcall.h> : +the client can use it, when establishing a connection, +to +override tag matching in +.B version +messages. +.PP +The type of an R-message will either be one greater than the type +of the corresponding T-message or +.BR Rerror , +indicating that the request failed. +In the latter case, the +.I ename +field contains a string describing the reason for failure. +.PP +The +.B version +message identifies the version of the protocol and indicates +the maximum message size the system is prepared to handle. +It also initializes the connection and +aborts all outstanding I/O on the connection. +The set of messages between +.B version +requests is called a +.IR session . +.PP +Most T-messages contain a +.IR fid , +a 32-bit unsigned integer that the client uses to identify +a ``current file'' on the server. +Fids are somewhat like file descriptors in a user process, +but they are not restricted to files open for I/O: +directories being examined, files being accessed by +.IR stat (3) +calls, and so on \(em all files being manipulated by the operating +system \(em are identified by fids. +Fids are chosen by the client. +All requests on a connection share the same fid space; +when several clients share a connection, +the agent managing the sharing must arrange +that no two clients choose the same fid. +.PP +The fid supplied in an +.B attach +message +will be taken by the server to refer to the root of the served file tree. +The +.B attach +identifies the user +to the server and may specify a particular file tree served +by the server (for those that supply more than one). +.PP +Permission to attach to the service is proven by providing a special fid, called +.BR afid , +in the +.B attach +message. This +.B afid +is established by exchanging +.B auth +messages and subsequently manipulated using +.B read +and +.B write +messages to exchange authentication information not defined explicitly by 9P. +Once the authentication protocol is complete, the +.B afid +is presented in the +.B attach +to permit the user to access the service. +.PP +A +.B walk +message causes the server to change the current file associated +with a fid to be a file in the directory that is the old current file, or one of +its subdirectories. +.B Walk +returns a new fid that refers to the resulting file. +Usually, a client maintains a fid for the root, +and navigates by +.B walks +from the root fid. +.PP +A client can send multiple T-messages without waiting for the corresponding +R-messages, but all outstanding T-messages must specify different tags. +The server may delay the response to a request +and respond to later ones; +this is sometimes necessary, for example when the client reads +from a file that the server synthesizes from external events +such as keyboard characters. +.PP +Replies (R-messages) to +.BR auth , +.BR attach , +.BR walk , +.BR open , +and +.B create +requests convey a +.I qid +field back to the client. +The qid represents the server's unique identification for the +file being accessed: +two files on the same server hierarchy are the same if and only if their qids +are the same. +(The client may have multiple fids pointing to a single file on a server +and hence having a single qid.) +The thirteen-byte qid fields hold a one-byte type, +specifying whether the file is a directory, append-only file, etc., +and two unsigned integers: +first the four-byte qid +.IR version , +then the eight-byte qid +.IR path . +The path is an integer unique among all files in the hierarchy. +If a file is deleted and recreated with the +same name in the same directory, the old and new path components of the qids +should be different. +The version is a version number for a file; +typically, it is incremented every time the file is modified. +.PP +An existing file can be +.BR opened , +or a new file may be +.B created +in the current (directory) file. +I/O of a given number of bytes +at a given offset +on an open file is done by +.B read +and +.BR write . +.PP +A client should +.B clunk +any fid that is no longer needed. +The +.B remove +transaction deletes files. +.PP +.B Openfd +is an extension used by Unix utilities to allow traditional Unix programs +to have their input or output attached to fids on 9P servers. +See +.IR openfd (9p) +and +.IR 9pclient (3) +for details. +.PP +The +.B stat +transaction retrieves information about the file. +The +.I stat +field in the reply includes the file's +name, +access permissions (read, write and execute for owner, group and public), +access and modification times, and +owner and group identifications +(see +.IR stat (3)). +The owner and group identifications are textual names. +The +.B wstat +transaction allows some of a file's properties +to be changed. +.PP +A request can be aborted with a +flush +request. +When a server receives a +.BR Tflush , +it should not reply to the message with tag +.I oldtag +(unless it has already replied), +and it should immediately send an +.BR Rflush . +The client must wait +until it gets the +.B Rflush +(even if the reply to the original message arrives in the interim), +at which point +.I oldtag +may be reused. +.PP +Because the message size is negotiable and some elements of the +protocol are variable length, it is possible (although unlikely) to have +a situation where a valid message is too large to fit within the negotiated size. +For example, a very long file name may cause a +.B Rstat +of the file or +.B Rread +of its directory entry to be too large to send. +In most such cases, the server should generate an error rather than +modify the data to fit, such as by truncating the file name. +The exception is that a long error string in an +.B Rerror +message should be truncated if necessary, since the string is only +advisory and in some sense arbitrary. +.PP +Most programs do not see the 9P protocol directly; +on Plan 9, calls to library +routines that access files are +translated by the kernel's mount driver +into 9P messages. +.SS Unix +On Unix, 9P services are posted as Unix domain sockets in a +well-known directory (see +.IR getns (3) +and +.IR 9pserve (4)). +Clients connect to these servers using a 9P client library +(see +.IR 9pclient (3)). +.SH DIRECTORIES +Directories are created by +.B create +with +.B DMDIR +set in the permissions argument (see +.IR stat (9P)). +The members of a directory can be found with +.IR read (9P). +All directories must support +.B walks +to the directory +.B .. +(dot-dot) +meaning parent directory, although by convention directories +contain no explicit entry for +.B .. +or +.B . +(dot). +The parent of the root directory of a server's tree is itself. +.SH "ACCESS PERMISSIONS" +This section describes the access permission conventions +implemented by most Plan 9 file servers. These conventions +are not enforced by the protocol and may differ between servers, +especially servers built on top of foreign operating systems. +.PP +Each file server maintains a set of user and group names. +Each user can be a member of any number of groups. +Each group has a +.I group leader +who has special privileges (see +.IR stat (9P) +and +Plan 9's \fIusers\fR(6)). +Every file request has an implicit user id (copied from the original +.BR attach ) +and an implicit set of groups (every group of which the user is a member). +.PP +Each file has an associated +.I owner +and +.I group +id and +three sets of permissions: +those of the owner, those of the group, and those of ``other'' users. +When the owner attempts to do something to a file, the owner, group, +and other permissions are consulted, and if any of them grant +the requested permission, the operation is allowed. +For someone who is not the owner, but is a member of the file's group, +the group and other permissions are consulted. +For everyone else, the other permissions are used. +Each set of permissions says whether reading is allowed, +whether writing is allowed, and whether executing is allowed. +A +.B walk +in a directory is regarded as executing the directory, +not reading it. +Permissions are kept in the low-order bits of the file +.IR mode : +owner read/write/execute permission represented as 1 in bits 8, 7, and 6 +respectively (using 0 to number the low order). +The group permissions are in bits 5, 4, and 3, +and the other permissions are in bits 2, 1, and 0. +.PP +The file +.I mode +contains some additional attributes besides the permissions. +If bit 31 +.RB ( DMDIR ) +is set, the file is a directory; +if bit 30 +.RB ( DMAPPEND ) +is set, the file is append-only (offset is ignored in writes); +if bit 29 +.RB ( DMEXCL ) +is set, the file is exclusive-use (only one client may have it +open at a time); +if bit 27 +.RB ( DMAUTH ) +is set, the file is an authentication file established by +.B auth +messages; +if bit 26 +.RB ( DMTMP ) +is set, the contents of the file (or directory) are not included in nightly archives. +(Bit 28 is skipped for historical reasons.) +These bits are reproduced, from the top bit down, in the type byte of the Qid: +.BR QTDIR , +.BR QTAPPEND , +.BR QTEXCL , +(skipping one bit) +.BR QTAUTH , +and +.BR QTTMP . +The name +.BR QTFILE , +defined to be zero, +identifies the value of the type for a plain file.
diff --git a/man/man9/INDEX b/man/man9/INDEX new file mode 100644 index 0000000..2e331bf --- /dev/null +++ b/man/man9/INDEX
@@ -0,0 +1,16 @@ +0intro 0intro.9p +intro 0intro.9p +attach attach.9p +auth attach.9p +clunk clunk.9p +error error.9p +flush flush.9p +create open.9p +open open.9p +read read.9p +write read.9p +remove remove.9p +stat stat.9p +wstat stat.9p +version version.9p +walk walk.9p
diff --git a/man/man9/attach.9p b/man/man9/attach.9p new file mode 100644 index 0000000..ddcf747 --- /dev/null +++ b/man/man9/attach.9p
@@ -0,0 +1,168 @@ +.TH ATTACH 9P +.SH NAME +attach, auth \- messages to establish a connection +.SH SYNOPSIS +.ta \w'\fLTauth 'u +.IR size [4] +.B Tauth +.IR tag [2] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.IR size [4] +.B Rauth +.IR tag [2] +.IR aqid [13] +.PP +.IR size [4] +.B Tattach +.IR tag [2] +.IR fid [4] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.IR size [4] +.B Rattach +.IR tag [2] +.IR qid [13] +.SH DESCRIPTION +.PP +The +.B attach +message serves as a fresh introduction from a user on +the client machine to the server. +The message identifies the user +.RI ( uname ) +and may select +the file tree to access +.RI ( aname ). +The +.I afid +argument specifies a fid previously established by an +.B auth +message, as described below. +.PP +As a result of the +.B attach +transaction, the client will have a connection to the root +directory of the desired file tree, +represented by +.IR fid . +An error is returned if +.I fid +is already in use. +The server's idea of the root of the file tree is represented by the returned +.IR qid . +.PP +If the client does not wish to authenticate the connection, or knows that +authentication is not required, the +.I afid +field in the +.B attach +message should be set to +.BR NOFID , +defined as +.B (u32int)~0 +in +.BR <fcall.h> . +If the client does wish to authenticate, it must acquire and validate an +.I afid +using an +.B auth +message before doing the +.BR attach . +.PP +The +.B auth +message contains +.IR afid , +a new fid to be established for authentication, and the +.I uname +and +.I aname +that will be those of the following +.B attach +message. +If the server does not require authentication, it returns +.B Rerror +to the +.B Tauth +message. +.PP +If the server does require authentication, it returns +.I aqid +defining a file of type +.B QTAUTH +(see +.IR intro (9P)) +that may be read and written (using +.B read +and +.B write +messages in the usual way) to execute an authentication protocol. +That protocol's definition is not part of 9P itself. +.PP +Once the protocol is complete, the same +.I afid +is presented in the +.B attach +message for the user, granting entry. +The same validated +.I afid +may be used for multiple +.B attach +messages with the same +.I uname +and +.IR aname . +.SH ENTRY POINTS +.I Fsmount +and +.I fsauth +(see +.IR 9pclient (3)) +generate +.B attach +and +.B auth +transactions. +.\" An +.\" .B attach +.\" transaction will be generated for kernel devices +.\" (see +.\" .IR intro (3)) +.\" when a system call evaluates a file name +.\" beginning with +.\" .LR # . +.\" .IR Pipe (2) +.\" generates an attach on the kernel device +.\" .IR pipe (3). +.\" The +.\" .I mount +.\" system call +.\" (see +.\" .IR bind (2)) +.\" generates an +.\" .B attach +.\" message to the remote file server. +.\" When the kernel boots, an +.\" .I attach +.\" is made to the root device, +.\" .IR root (3), +.\" and then an +.\" .B attach +.\" is made to the requested file server machine. +.\" .PP +.\" An +.\" .B auth +.\" transaction is generated by the +.\" .IR fauth (2) +.\" system call or by the first +.\" .B mount +.\" system call on an uninitialized connection. +.SH SEE ALSO +.IR 9pclient (3), +.IR version (9P), +Plan 9's \fIauthsrv\fR(6)
diff --git a/man/man9/clunk.9p b/man/man9/clunk.9p new file mode 100644 index 0000000..ef3ecdc --- /dev/null +++ b/man/man9/clunk.9p
@@ -0,0 +1,55 @@ +.TH CLUNK 9P +.SH NAME +clunk \- forget about a fid +.SH SYNOPSIS +.ta \w'\fLTclunk 'u +.IR size [4] +.B Tclunk +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rclunk +.IR tag [2] +.SH DESCRIPTION +The +.B clunk +request informs the file server +that the current file represented by +.I fid +is no longer needed by the client. +The actual file is not removed on the server unless the fid had been opened with +.BR ORCLOSE . +.PP +Once a fid has been clunked, +the same fid can be reused in a new +.B walk +or +.B attach +request. +.PP +Even if the +.B clunk +returns an error, the +.I fid +is no longer valid. +.SH ENTRY POINTS +.B Clunk +transactions are +generated by +.I fsclose +and +.I fsunmount +(see +.IR 9pclient (3)) +and indirectly by other actions such as failed +.I fsopen +calls. +.\" +.\" A +.\" .B clunk +.\" message is generated by +.\" .I close +.\" and indirectly by other actions such as failed +.\" .I open +.\" calls.
diff --git a/man/man9/error.9p b/man/man9/error.9p new file mode 100644 index 0000000..6380f64 --- /dev/null +++ b/man/man9/error.9p
@@ -0,0 +1,28 @@ +.TH ERROR 9P +.SH NAME +error \- return an error +.SH SYNOPSIS +.ta \w'\fLRerror 'u +.IR size [4] +.B Rerror +.IR tag [2] +.IR ename [ s ] +.SH DESCRIPTION +The +.B Rerror +message +(there is no +.BR Terror ) +is used to return an error string +describing the +failure of a transaction. +It replaces the corresponding reply message +that would accompany a successful call; its tag is that +of the failing request. +.PP +By convention, clients may truncate error messages after +.B ERRMAX-1 +bytes; +.B ERRMAX +is defined in +.BR <libc.h> .
diff --git a/man/man9/flush.9p b/man/man9/flush.9p new file mode 100644 index 0000000..9d3ea26 --- /dev/null +++ b/man/man9/flush.9p
@@ -0,0 +1,109 @@ +.TH FLUSH 9P +.SH NAME +flush \- abort a message +.SH SYNOPSIS +.ta \w'\fLTflush 'u +.IR size [4] +.B Tflush +.IR tag [2] +.IR oldtag [2] +.br +.IR size [4] +.B Rflush +.IR tag [2] +.SH DESCRIPTION +When the response to a request is no longer needed, such as when +a user interrupts a process doing a +.IR read (9p), +a +.B Tflush +request is sent to the server to purge the pending response. +The message being flushed is identified by +.IR oldtag . +The semantics of +.B flush +depends on messages arriving in order. +.PP +The server should answer the +.B flush +message immediately. +If it recognizes +.I oldtag +as the tag of a pending transaction, it should abort any pending response +and discard that tag. +In either case, it should respond with an +.B Rflush +echoing the +.I tag +(not +.IR oldtag ) +of the +.B Tflush +message. +A +.B Tflush +can never be responded to by an +.B Rerror +message. +.PP +The server may respond to the pending request before +responding to the +.BR Tflush . +It is possible for a client to send multiple +.B Tflush +messages for a particular pending request. Each +subsequent +.B Tflush +must contain as +.I oldtag +the tag of the pending request (not a previous +.BR Tflush ). +Should multiple +.BR Tflush es +be received for a pending request, they must be answered in +order. A +.B Rflush +for any of the multiple +.BR Tflush es +implies an answer for all previous ones. Therefore, should +a server receive a request and then multiple flushes for that +request, it need respond only to the last flush. +.PP +When the client sends a +.BR Tflush , +it must wait to receive the corresponding +.B Rflush +before reusing +.I oldtag +for subsequent messages. +If a response to the flushed request is received before the +.BR Rflush , +the client must honor the response +as if it had not been flushed, +since the completed request may signify a state change in the server. +For instance, +.B Tcreate +may have created a file and +.B Twalk +may have allocated a fid. +If no response is received before the +.BR Rflush , +the flushed transaction is considered to have been canceled, +and should be treated as though it had never been sent. +.PP +Several exceptional conditions are handled correctly by the above specification: +sending multiple flushes for a single tag, +flushing after a transaction is completed, +flushing a +.BR Tflush , +and flushing an invalid tag. +.SH ENTRY POINTS +The +.IR 9pclient (3) +library does not generate +.B flush +transactions.. +.IR 9pserve (4) +generates +.B flush +transactions to cancel transactions pending when a client hangs up.
diff --git a/man/man9/open.9p b/man/man9/open.9p new file mode 100644 index 0000000..b8ed973 --- /dev/null +++ b/man/man9/open.9p
@@ -0,0 +1,249 @@ +.TH OPEN 9P +.SH NAME +open, create \- prepare a fid for I/O on an existing or new file +.SH SYNOPSIS +.ta \w'\fLTcreate 'u +.IR size [4] +.B Topen +.IR tag [2] +.IR fid [4] +.IR mode [1] +.br +.IR size [4] +.B Ropen +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.PP +.IR size [4] +.B Tcreate +.IR tag [2] +.IR fid [4] +.IR name [ s ] +.IR perm [4] +.IR mode [1] +.br +.IR size [4] +.B Rcreate +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.SH DESCRIPTION +The +.B open +request asks the file server to check permissions and +prepare a fid for I/O with subsequent +.B read +and +.B write +messages. +The +.I mode +field determines the type of I/O: +0 +(called +.BR OREAD +in +.BR <libc.h> ), +1 +.RB ( OWRITE ), +2 +.RB ( ORDWR ), +and 3 +.RB ( OEXEC ) +mean +.I +read access, write access, read and write access, +and +.I +execute access, +to be checked against the permissions for the file. +In addition, if +.I mode +has the +.B OTRUNC +.RB ( 0x10 ) +bit set, +the file is to be truncated, which requires write permission +(if +the file is append-only, and permission is granted, the +.B open +succeeds but the file will not be truncated); +if the +.I mode +has the +.B ORCLOSE +.RB ( 0x40 ) +bit set, the file is to be removed when the fid +is clunked, which requires permission to remove the file from its directory. +All other bits in +.I mode +should be zero. +It is illegal to write a directory, truncate it, or attempt to remove it on close. +If the file is marked for exclusive use (see +.IR stat (9P)), +only one client can have the file open at any time. +That is, after such a file has been opened, +further opens will fail until +.I fid +has been clunked. +All these permissions are checked at the time of the +.B open +request; subsequent changes to the permissions of files do not affect +the ability to read, write, or remove an open file. +.PP +The +.B create +request asks the file server to create a new file +with the +.I name +supplied, in the directory +.RI ( dir ) +represented by +.IR fid , +and requires write permission in the directory. +The owner of the file is the implied user id of the request, +the group of the file is the same as +.IR dir , +and the permissions are the value of +.ce +.B "perm & (~0666 | (dir.perm & 0666))" +if a regular file is being created and +.ce +.B "perm & (~0777 | (dir.perm & 0777))" +if a directory is being created. +This means, for example, that if the +.B create +allows read permission to others, but the containing directory +does not, then the created file will not allow others to read the file. +.PP +Finally, the newly created file is opened according to +.IR mode , +and +.I fid +will represent the newly opened file. +.I Mode +is not checked against the permissions in +.IR perm . +The +.I qid +for the new file is returned with the +.B create +reply message. +.PP +Directories are created by setting the +.B DMDIR +bit +.RB ( 0x80000000 ) +in the +.IR perm . +.PP +The names +.B . +and +.B .. +are special; it is illegal to create files with these names. +.PP +It is an error for either of these messages if the fid +is already the product of a successful +.B open +or +.B create +message. +.PP +An attempt to +.B create +a file in a directory where the given +.I name +already exists will be rejected; +in this case, the +.I fscreate +call +(see +.IR 9pclient (3)) +uses +.B open +with truncation. +The algorithm used by the +.IR create +system call +is: +first walk to the directory to contain the file. +If that fails, return an error. +Next +.B walk +to the specified file. +If the +.B walk +succeeds, send a request to +.B open +and truncate the file and return the result, successful or not. +If the +.B walk +fails, send a create message. +If that fails, it may be because the file was created by another +process after the previous walk failed, so (once) try the +.B walk +and +.B open +again. +.\" .PP +.\" For the behavior of +.\" .I create +.\" on a union directory, see +.\" .IR bind (2). +.\" .PP +.\" The +.\" .B iounit +.\" field returned by +.\" .B open +.\" and +.\" .B create +.\" may be zero. +.\" If it is not, it is the maximum number of bytes that are guaranteed to +.\" be read from or written to the file without breaking the I/O transfer +.\" into multiple 9P messages; see +.\" .IR read (9P). +.SH ENTRY POINTS +.I Fsopen +and +.I fscreate +(see +.IR 9pclient (3)) +both generate +.B open +messages; only +.I fscreate +generates a +.B create +message. +The +.B iounit +associated with an open file may be discovered by calling +.IR fsiounit . +.PP +For programs that need atomic file creation, without the race +that exists in the +.B open-create +sequence described above, +.IR fscreate +does the following. +If the +.B OEXCL +.RB ( 0x1000 ) +bit is set in the +.I mode +for a +.I fscreate +call, +the +.B open +message is not sent; the kernel issues only the +.BR create . +Thus, if the file exists, +.I fscreate +will draw an error, but if it doesn't and the +.I fscreate +call succeeds, the process issuing the +.I fscreate +is guaranteed to be the one that created the file.
diff --git a/man/man9/read.9p b/man/man9/read.9p new file mode 100644 index 0000000..a68f153 --- /dev/null +++ b/man/man9/read.9p
@@ -0,0 +1,126 @@ +.TH READ 9P +.SH NAME +read, write \- transfer data from and to a file +.SH SYNOPSIS +.ta \w'\fLTwrite 'u +.IR size [4] +.B Tread +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.br +.IR size [4] +.B Rread +.IR tag [2] +.IR count [4] +.IR data [ count ] +.PP +.IR size [4] +.B Twrite +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.IR data [ count ] +.br +.IR size [4] +.B Rwrite +.IR tag [2] +.IR count [4] +.SH DESCRIPTION +The +.B read +request +asks for +.I count +bytes of data +from the file identified by +.IR fid , +which must be opened for reading, +starting +.I offset +bytes after the beginning of the file. +The bytes are returned with the +.B read +reply message. +.PP +The +.I count +field in the reply indicates the number of bytes returned. +This may be less than the requested amount. +If the +.I offset +field is greater than or equal to the number of bytes in the file, +a count of zero will be returned. +.PP +For directories, +.B read +returns an integral number of +directory entries exactly as in +.B stat +(see +.IR stat (9P)), +one for each member of the directory. +The +.B read +request message must have +.B offset +equal to zero or the value of +.B offset +in the previous +.B read +on the directory, plus the number of bytes +returned in the previous +.BR read . +In other words, seeking other than to the beginning +is illegal in a directory. +.PP +The +.B write +request asks that +.I count +bytes of data be recorded in the file identified by +.IR fid , +which must be opened for writing, starting +.I offset +bytes after the beginning of the file. +If the file is append-only, +the data will be placed at the end of the file regardless of +.IR offset . +Directories may not be written. +.PP +The +.B write +reply records the number of bytes actually written. +It is usually an error +if this is not the same as requested. +.PP +Because 9P implementations may limit the size of individual +messages, +more than one message may be produced by a single +.I read +or +.I write +call. +The +.I iounit +field returned by +.IR open (9P), +if non-zero, reports the maximum size that is guaranteed +to be transferred atomically. +.SH ENTRY POINTS +.I Fsread +and +.I fswrite +(see +.IR 9pclient (3)) +generate the corresponding messages. +Because they take an offset parameter, the +.I fspread +and +.I fspwrite +calls correspond more directly to the 9P messages. +Although +.I fsseek +affects the offset, it does not generate a message.
diff --git a/man/man9/remove.9p b/man/man9/remove.9p new file mode 100644 index 0000000..a9a844a --- /dev/null +++ b/man/man9/remove.9p
@@ -0,0 +1,51 @@ +.TH REMOVE 9P +.SH NAME +remove \- remove a file from a server +.SH SYNOPSIS +.ta \w'\fLTremove 'u +.IR size [4] +.B Tremove +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rremove +.IR tag [2] +.SH DESCRIPTION +The +.B remove +request asks the file server both to remove the file represented by +.I fid +and to +.B clunk +the +.IR fid , +even if the remove fails. +This request will fail if the client does not have write permission +in the parent directory. +.PP +It is correct to consider +.B remove +to be a +.B clunk +with the side effect of removing the file if permissions allow. +.PP +If a file has been opened as multiple fids, +possibly on different connections, +and one fid is used to remove the file, +whether the other fids continue to provide access to the file +is implementation-defined. +The Plan 9 file servers +remove the file immediately: attempts to use the other fids +will yield a +``phase error.'' +.IR U9fs +follows the semantics of the underlying Unix file system, +so other fids typically remain usable. +.SH ENTRY POINTS +.I Fsremove +(see +.IR 9pclient (3)) +generates +.B remove +messages.
diff --git a/man/man9/stat.9p b/man/man9/stat.9p new file mode 100644 index 0000000..ab68133 --- /dev/null +++ b/man/man9/stat.9p
@@ -0,0 +1,297 @@ +.TH STAT 9P +.SH NAME +stat, wstat \- inquire or change file attributes +.SH SYNOPSIS +.ta \w'\fLTwstat 'u +.IR size [4] +.B Tstat +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rstat +.IR tag [2] +.IR stat [ n ] +.PP +.IR size [4] +.B Twstat +.IR tag [2] +.IR fid [4] +.IR stat [ n ] +.br +.IR size [4] +.B Rwstat +.IR tag [2] +.SH DESCRIPTION +The +.B stat +transaction inquires about the file +identified by +.IR fid . +The reply will contain a +machine-independent +.I directory +.IR entry , +.IR stat , +laid out as follows: +.TP +.I size\f1[2]\fP +total byte count of the following data +.TP +.I type\f1[2]\fP +for kernel use +.TP +.I dev\f1[4]\fP +for kernel use +.TP +.I qid.type\f1[1]\fP +the type of the file (directory, etc.), represented as a bit vector +corresponding to the high 8 bits of the file's mode word. +.TP +.I qid.vers\f1[4]\fP +version number for given path +.TP +.I qid.path\f1[8]\fP +the file server's unique identification for the file +.TP +.I mode\f1[4]\fP +permissions and flags +.TP +.I atime\f1[4]\fP +last access time +.TP +.I mtime\f1[4]\fP +last modification time +.TP +.I length\f1[8]\fP +length of file in bytes +.TP +.I name\f1[ s ]\fP +file name; must be +.B / +if the file is the root directory of the server +.TP +.I uid\f1[ s ]\fP +owner name +.TP +.I gid\f1[ s ]\fP +group name +.TP +.I muid\f1[ s ]\fP +name of the user who last modified the file +.PD +.PP +Integers in this encoding are in little-endian order (least +significant byte first). +The +.I convM2D +and +.I convD2M +routines (see +.IR fcall (3)) +convert between directory entries and a C structure called a +.BR Dir . +.PP +The +.I mode +contains permission bits as described in +.IR intro (9P) +and the following: +.B 0x80000000 +.RB ( DMDIR , +this file is a directory), +.B 0x40000000 +.RB ( DMAPPEND , +append only), +.B 0x20000000 +.RB ( DMEXCL , +exclusive use), +.B 0x04000000 +.RB ( DMTMP , +temporary); +these are echoed in +.BR Qid.type . +Writes to append-only files always place their data at the +end of the file; the +.I offset +in the +.B write +message is ignored, as is the +.B OTRUNC +bit in an open. +Exclusive use files may be open for I/O by only one fid at a time +across all clients of the server. If a second open is attempted, +it draws an error. Servers may implement a timeout on the lock +on an exclusive use file: if the fid holding the file open has +been unused for an extended period (of order at least minutes), +it is reasonable to break the lock and deny the initial fid +further I/O. +Temporary files are not included in nightly archives +(see Plan 9's \fIfossil\fR(4)). +.PP +The two time fields are measured in seconds since the epoch +(Jan 1 00:00 1970 GMT). +The +.I mtime +field reflects the time of the last change of content (except when later changed by +.BR wstat ). +For a plain file, +.I mtime +is the time of the most recent +.BR create , +.B open +with truncation, +or +.BR write ; +for a directory it is the time of the most recent +.BR remove , +.BR create , +or +.B wstat +of a file in the directory. +Similarly, the +.I atime +field records the last +.B read +of the contents; +also it is set whenever +.I mtime +is set. +In addition, for a directory, it is set by +an +.BR attach , +.BR walk , +or +.BR create , +all whether successful or not. +.PP +The +.I muid +field names the user whose actions most recently changed the +.I mtime +of the file. +.PP +The +.I length +records the number of bytes in the file. +Directories and most files representing devices have a conventional +length of 0. +.PP +The +.B stat +request requires no special permissions. +.PP +The +.B wstat +request can change some of the file status information. +The +.I name +can be changed by anyone with write permission in the parent directory; +it is an error to change the name to that of an existing file. +The +.I length +can be changed (affecting the actual length of the file) by anyone with +write permission on the file. +It is an error to attempt to set the length of a directory to a non-zero value, +and servers may decide to reject length changes for other reasons. +The +.I mode +and +.I mtime +can be changed by the owner of the file or the group leader of the file's current +group. +The directory bit cannot be changed by a +.BR wstat ; +the other defined permission and mode bits can. +The +.I gid +can be changed: by the owner if also a member of the new group; or +by the group leader of the file's current group +if also leader of the new group +(see +.IR intro (9P) +for more information about permissions, users, and groups). +None of the other data can be altered by a +.B wstat +and attempts to change them will trigger an error. +In particular, +it is illegal to attempt to change the owner of a file. +(These conditions may be +relaxed when establishing the initial state of a file server; see +Plan 9's \fIfsconfig\fR(8).) +.PP +Either all the changes in +.B wstat +request happen, or none of them does: if the request succeeds, +all changes were made; if it fails, none were. +.PP +A +.B wstat +request can avoid modifying some properties of the file +by providing explicit ``don't touch'' values in the +.B stat +data that is sent: zero-length strings for text values and +the maximum unsigned value of appropriate size +for integral values. +As a special case, if +.I all +the elements of the directory entry in a +.B Twstat +message are ``don't touch'' values, the server may interpret it +as a request to guarantee that the contents of the associated +file are committed to stable storage before the +.B Rwstat +message is returned. +(Consider the message to mean, ``make the state of the file +exactly what it claims to be.'') +.PP +A +.I read +of a directory yields an integral number of directory entries in +the machine independent encoding given above +(see +.IR read (9P)). +.PP +Note that since the +.B stat +information is sent as a 9P variable-length datum, it is limited to a maximum of +65535 bytes. +.SH ENTRY POINTS +.B Stat +messages are generated by +.I fsdirfstat +and +.IR fsdirstat +(see +.IR 9pclient (3)). +.PP +.B Wstat +messages are generated by +.I fsdirfwstat +and +.IR fsdirwstat . +.SH BUGS +To make the contents of a directory, such as returned by +.IR read (9P), +easy to parse, each +directory entry begins with a size field. +For consistency, the entries in +.B Twstat +and +.B Rstat +messages also contain +their size, which means the size appears twice. +For example, the +.B Rstat +message is formatted as +.RI ``(4+1+2+2+ n )[4] +.B Rstat +.IR tag [2] +.IR n [2] +.RI ( n -2)[2] +.IR type [2] +.IR dev [4]...,'' +where +.I n +is the value returned by +.BR convD2M .
diff --git a/man/man9/version.9p b/man/man9/version.9p new file mode 100644 index 0000000..c496121 --- /dev/null +++ b/man/man9/version.9p
@@ -0,0 +1,99 @@ +.TH VERSION 9P +.SH NAME +version \- negotiate protocol version +.SH SYNOPSIS +.ta \w'\fLTversion 'u +.IR size [4] +.B Tversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.br +.IR size [4] +.B Rversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.SH DESCRIPTION +The +.B version +request negotiates the protocol version and message size +to be used on the connection and initializes the connection for I/O. +.B Tversion +must be the first message sent on the 9P connection, +and the client cannot issue any further requests until it has received the +.B Rversion +reply. +The +.I tag +should be +.B NOTAG +(value +.BR (ushort)~0 ) +for a +.B version +message. +.PP +The client suggests a maximum message size, +.BR msize , +that is the maximum length, in bytes, +it will ever generate or expect to receive in a single 9P message. +This count includes all 9P protocol data, starting from the +.B size +field and extending through the message, +but excludes enveloping transport protocols. +The server responds with its own maximum, +.BR msize , +which must be less than or equal to the client's value. +Thenceforth, both sides of the connection must honor this limit. +.PP +The +.B version +string identifies the level of the protocol. +The string must always begin with the two characters +.RB `` 9P ''. +If the server does not understand the client's version string, +it should respond with an +.B Rversion +message (not +.BR Rerror ) +with the +.B version +string the 7 characters +.RB `` unknown ''. +.PP +The server may respond with the client's version string, +or a version string identifying +an earlier defined protocol version. +Currently, the only defined version is the 6 characters +.RB `` 9P2000 ''. +Version strings are defined such that, if the client string contains +one or more period characters, the initial substring up to but not including +any single period in the version string defines a version of the protocol. +After stripping any such period-separated suffix, the server is allowed to respond +with a string of the form +.BI 9P nnnn\f1, +where +.I nnnn +is less than or equal to the digits sent by the client. +.PP +The client and server will use the protocol version defined by the +server's response for all subsequent communication on the connection. +.PP +A successful +.B version +request initializes the connection. +All outstanding I/O on the connection is aborted; all active fids are freed (`clunked') automatically. +The set of messages between +.B version +requests is called a +.IR session . +.SH ENTRY POINTS +.I Fsversion +(see +.IR 9pclient (3)) +generates +.B version +messages; +it is called automatically by +.IR fsmount .
diff --git a/man/man9/walk.9p b/man/man9/walk.9p new file mode 100644 index 0000000..49777f2 --- /dev/null +++ b/man/man9/walk.9p
@@ -0,0 +1,189 @@ +.TH WALK 9P +.SH NAME +walk \- descend a directory hierarchy +.SH SYNOPSIS +.ta \w'\fLTwalk 'u +.IR size [4] +.B Twalk +.IR tag [2] +.IR fid [4] +.IR newfid [4] +.IR nwname [2] +.IR nwname *( wname [ s ]) +.br +.IR size [4] +.B Rwalk +.IR tag [2] +.IR nwqid [2] +.IR nwqid *( qid [13]) +.SH DESCRIPTION +The +.B walk +request carries as arguments an existing +.IR fid +and a proposed +.I newfid +(which must not be in use unless it is the same as +.IR fid ) +that the client wishes to associate with +the result of traversing the directory hierarchy +by `walking' the hierarchy using the successive path name +elements +.BR wname . +The +.I fid +must represent a directory unless zero path name elements are specified. +.PP +The +.I fid +must be valid in the current session and must not have been opened for I/O +by an +.B open +or +.B create +message. +If the full sequence of +.B nwname +elements is walked successfully, +.I newfid +will represent the file that results. +If not, +.I newfid +(and +.BR fid ) +will be unaffected. +However, if +.I newfid +is in use or otherwise illegal, an +.B Rerror +is returned. +.PP +The name +.RB `` .. '' +(dot-dot) represents the parent directory. +The name +.RB `` . '' +(dot), meaning the current directory, is not used in the protocol. +.PP +It is legal for +.B nwname +to be zero, in which case +.I newfid +will represent the same file as +.I fid +and the +.B walk +will usually succeed; this is equivalent to walking to dot. +The rest of this discussion assumes +.B nwname +is greater than zero. +.PP +The +.B nwname +path name elements +.B wname +are walked in order, ``elementwise''. +For the first elementwise walk +to succeed, the file identified by +.I fid +must be a directory, +and the implied user of the request must have permission +to search the directory (see +.IR intro (9P)). +Subsequent elementwise walks have equivalent restrictions +applied to the implicit fid that results from the preceding elementwise walk. +.PP +If the first element cannot be walked for any reason, +.B Rerror +is returned. +Otherwise, the walk will return an +.B Rwalk +message containing +.I nwqid +qids corresponding, in order, to the files that are visited by the +.I nwqid +successful elementwise walks; +.I nwqid +is therefore either +.B nwname +or the index of the first elementwise walk that failed. +The value of +.I nwqid +cannot be zero unless +.B nwname +is zero. +Also, +.I nwqid +will always be less than or equal to +.BR nwname . +Only if it is equal, however, will +.I newfid +be affected, in which case +.I newfid +will represent the file +reached by the final elementwise walk requested in the message. +.PP +A +.B walk +of the name +.RB `` .. '' +in the root directory of a server is equivalent to a walk with no name elements. +.PP +If +.I newfid +is the same as +.IR fid , +the above discussion applies, with the obvious difference +that if the walk changes the state of +.IR newfid , +it also changes the state of +.IR fid ; +and if +.I newfid +is unaffected, then +.I fid +is also unaffected. +.PP +To simplify the implementation of the servers, a maximum of sixteen name elements or qids +may be packed in a single message. +This constant is called +.B MAXWELEM +in +.IR fcall (3). +Despite this restriction, the system imposes no limit on the number of elements in a file name, +only the number that may be transmitted in a single message. +.SH ENTRY POINTS +.I Fswalk +(see +.IR 9pclient (3)) +generates walk messages. +One or more walk messages may be generated by +any call that evaluates file names: +.IR fsopen , +.IR fsopenfd , +.IR fsdirstat , +.IR fsdirwstat . +.\" +.\" A call to +.\" .IR chdir (2) +.\" causes a +.\" .BR walk . +.\" One or more +.\" .B walk +.\" messages may be generated by +.\" any of the following calls, which evaluate file names: +.\" .IR bind , +.\" .IR create , +.\" .IR exec , +.\" .IR mount , +.\" .IR open , +.\" .IR remove , +.\" .IR stat , +.\" .IR unmount , +.\" .IR wstat . +.\" The file name element +.\" .B . +.\" (dot) is interpreted locally and +.\" is not transmitted in +.\" .B walk +.\" messages.