diff options
| author | Taru Karttunen <taruti@taruti.net> | 2011-03-30 16:49:47 +0300 |
|---|---|---|
| committer | Taru Karttunen <taruti@taruti.net> | 2011-03-30 16:49:47 +0300 |
| commit | b41b9034225ab3e49980d9de55c141011b6383b0 (patch) | |
| tree | 891014b4c2e803e01ac7a1fd2b60819fbc5a6e73 /sys/man/6 | |
| parent | c558a99e0be506a9abdf677f0ca4490644e05fc1 (diff) | |
Import sources from 2011-03-30 iso image - sys/man
Diffstat (limited to 'sys/man/6')
| -rwxr-xr-x | sys/man/6/0intro | 8 | ||||
| -rwxr-xr-x | sys/man/6/INDEX | 41 | ||||
| -rwxr-xr-x | sys/man/6/INDEX.html | 137 | ||||
| -rwxr-xr-x | sys/man/6/a.out | 252 | ||||
| -rwxr-xr-x | sys/man/6/ar | 99 | ||||
| -rwxr-xr-x | sys/man/6/authsrv | 726 | ||||
| -rwxr-xr-x | sys/man/6/color | 150 | ||||
| -rwxr-xr-x | sys/man/6/face | 116 | ||||
| -rwxr-xr-x | sys/man/6/font | 87 | ||||
| -rwxr-xr-x | sys/man/6/htmlroff | 358 | ||||
| -rwxr-xr-x | sys/man/6/image | 205 | ||||
| -rwxr-xr-x | sys/man/6/keyboard | 195 | ||||
| -rwxr-xr-x | sys/man/6/keys.who | 45 | ||||
| -rwxr-xr-x | sys/man/6/man | 249 | ||||
| -rwxr-xr-x | sys/man/6/map | 87 | ||||
| -rwxr-xr-x | sys/man/6/mhtml | 105 | ||||
| -rwxr-xr-x | sys/man/6/mnihongo | 30 | ||||
| -rwxr-xr-x | sys/man/6/mpictures | 151 | ||||
| -rwxr-xr-x | sys/man/6/ms | 319 | ||||
| -rwxr-xr-x | sys/man/6/namespace | 95 | ||||
| -rwxr-xr-x | sys/man/6/ndb | 351 | ||||
| -rwxr-xr-x | sys/man/6/plot | 336 | ||||
| -rwxr-xr-x | sys/man/6/plumb | 417 | ||||
| -rwxr-xr-x | sys/man/6/regexp | 129 | ||||
| -rwxr-xr-x | sys/man/6/rewrite | 154 | ||||
| -rwxr-xr-x | sys/man/6/smtpd | 309 | ||||
| -rwxr-xr-x | sys/man/6/snap | 98 | ||||
| -rwxr-xr-x | sys/man/6/style | 109 | ||||
| -rwxr-xr-x | sys/man/6/thumbprint | 41 | ||||
| -rwxr-xr-x | sys/man/6/users | 75 | ||||
| -rwxr-xr-x | sys/man/6/utf | 98 | ||||
| -rwxr-xr-x | sys/man/6/venti | 451 | ||||
| -rwxr-xr-x | sys/man/6/venti.conf | 88 | ||||
| -rwxr-xr-x | sys/man/6/vgadb | 486 |
34 files changed, 6597 insertions, 0 deletions
diff --git a/sys/man/6/0intro b/sys/man/6/0intro new file mode 100755 index 000000000..281f10b6e --- /dev/null +++ b/sys/man/6/0intro @@ -0,0 +1,8 @@ +.TH INTRO 6 +.SH NAME +intro \- introduction to file formats +.SH DESCRIPTION +This section of the manual describes file formats +and other miscellany such as +.I troff +macro packages. diff --git a/sys/man/6/INDEX b/sys/man/6/INDEX new file mode 100755 index 000000000..9d8e496d7 --- /dev/null +++ b/sys/man/6/INDEX @@ -0,0 +1,41 @@ +0intro 0intro +intro 0intro +a.out a.out +ar ar +authsrv authsrv +p9any authsrv +p9sk1 authsrv +p9sk2 authsrv +color color +face face +font font +subfont font +htmlroff htmlroff +image image +keyboard keyboard +keys.who keys.who +man man +map map +mhtml mhtml +mnihongo mnihongo +mpictures mpictures +ms ms +namespace namespace +ndb ndb +plot plot +plumb plumb +regexp regexp +rewrite rewrite +smtpd smtpd +snap snap +style style +thumbprint thumbprint +users users +ASCII utf +UTF utf +Unicode utf +rune utf +utf utf +venti venti +venti.conf venti.conf +vgadb vgadb diff --git a/sys/man/6/INDEX.html b/sys/man/6/INDEX.html new file mode 100755 index 000000000..816e636eb --- /dev/null +++ b/sys/man/6/INDEX.html @@ -0,0 +1,137 @@ +<HEAD> +<TITLE>plan 9 man section 6</TITLE> +</HEAD> +<BODY> +<B>[<A HREF="/sys/man/index.html">manual index</A>]</B> +<H2>Plan 9 from Bell Labs - Section 6 - File Formats, Misc</H2> +<HR> +<DL> +<DT><A HREF="/magic/man2html/6/0intro">0intro</A> +- introduction to file formats +<DD><TT> intro</TT> +</DT> +<DT><A HREF="/magic/man2html/6/a.out">a.out</A> +- object file format +<DD><TT> a.out</TT> +</DT> +<DT><A HREF="/magic/man2html/6/ar">ar</A> +- archive (library) file format +<DD><TT> ar</TT> +</DT> +<DT><A HREF="/magic/man2html/6/authsrv">authsrv</A> +- authentication protocols +<DD><TT> authsrv, p9any, p9sk1, p9sk2</TT> +</DT> +<DT><A HREF="/magic/man2html/6/color">color</A> +- representation of pixels and colors +<DD><TT> color</TT> +</DT> +<DT><A HREF="/magic/man2html/6/face">face</A> +- face files +<DD><TT> face</TT> +</DT> +<DT><A HREF="/magic/man2html/6/font">font</A> +- external format for fonts and subfonts +<DD><TT> font, subfont</TT> +</DT> +<DT><A HREF="/magic/man2html/6/htmlroff">htmlroff</A> +- HTML formatting and typesetting +<DD><TT> htmlroff</TT> +</DT> +<DT><A HREF="/magic/man2html/6/image">image</A> +- external format for images +<DD><TT> image</TT> +</DT> +<DT><A HREF="/magic/man2html/6/keyboard">keyboard</A> +- how to type characters +<DD><TT> keyboard</TT> +</DT> +<DT><A HREF="/magic/man2html/6/keys.who">keys.who</A> +- biographic information for key holders +<DD><TT> keys.who</TT> +</DT> +<DT><A HREF="/magic/man2html/6/man">man</A> +- macros to typeset manual +<DD><TT> man</TT> +</DT> +<DT><A HREF="/magic/man2html/6/map">map</A> +- digitized map formats +<DD><TT> map</TT> +</DT> +<DT><A HREF="/magic/man2html/6/mhtml">mhtml</A> +- macros for formatting HTML +<DD><TT> mhtml</TT> +</DT> +<DT><A HREF="/magic/man2html/6/mnihongo">mnihongo</A> +- macros for typesetting Japanese +<DD><TT> mnihongo</TT> +</DT> +<DT><A HREF="/magic/man2html/6/mpictures">mpictures</A> +- picture inclusion macros +<DD><TT> mpictures</TT> +</DT> +<DT><A HREF="/magic/man2html/6/ms">ms</A> +- macros for formatting manuscripts +<DD><TT> ms</TT> +</DT> +<DT><A HREF="/magic/man2html/6/namespace">namespace</A> +- name space description file +<DD><TT> namespace</TT> +</DT> +<DT><A HREF="/magic/man2html/6/ndb">ndb</A> +- Network database +<DD><TT> ndb</TT> +</DT> +<DT><A HREF="/magic/man2html/6/plot">plot</A> +- graphics interface +<DD><TT> plot</TT> +</DT> +<DT><A HREF="/magic/man2html/6/plumb">plumb</A> +- format of plumb messages and rules +<DD><TT> plumb</TT> +</DT> +<DT><A HREF="/magic/man2html/6/regexp">regexp</A> +- regular expression notation +<DD><TT> regexp</TT> +</DT> +<DT><A HREF="/magic/man2html/6/rewrite">rewrite</A> +- mail rewrite rules +<DD><TT> rewrite</TT> +</DT> +<DT><A HREF="/magic/man2html/6/smtpd">smtpd</A> +- SMTP listener configuration +<DD><TT> smtpd</TT> +</DT> +<DT><A HREF="/magic/man2html/6/snap">snap</A> +- process snapshots +<DD><TT> snap</TT> +</DT> +<DT><A HREF="/magic/man2html/6/style">style</A> +- Plan 9 coding conventions for C +<DD><TT> style</TT> +</DT> +<DT><A HREF="/magic/man2html/6/thumbprint">thumbprint</A> +- public key thumbprints +<DD><TT> thumbprint</TT> +</DT> +<DT><A HREF="/magic/man2html/6/users">users</A> +- file server user list format +<DD><TT> users</TT> +</DT> +<DT><A HREF="/magic/man2html/6/utf">utf</A> +- character set and format +<DD><TT> UTF, Unicode, ASCII, rune</TT> +</DT> +<DT><A HREF="/magic/man2html/6/venti">venti</A> +- archival storage server +<DD><TT> venti</TT> +</DT> +<DT><A HREF="/magic/man2html/6/venti.conf">venti.conf</A> +- a venti configuration file +<DD><TT> venti.conf</TT> +</DT> +<DT><A HREF="/magic/man2html/6/vgadb">vgadb</A> +- VGA controller and monitor database +<DD><TT> vgadb</TT> +</DT> +</DL> diff --git a/sys/man/6/a.out b/sys/man/6/a.out new file mode 100755 index 000000000..a4fa5db21 --- /dev/null +++ b/sys/man/6/a.out @@ -0,0 +1,252 @@ +.TH A.OUT 6 +.SH NAME +a.out \- object file format +.SH SYNOPSIS +.B #include <a.out.h> +.SH DESCRIPTION +An executable Plan 9 binary file has up to six sections: +a header, the program text, the data, +a symbol table, a PC/SP offset table (MC68020 only), +and finally a PC/line number table. +The header, given by a structure in +.BR <a.out.h> , +contains 4-byte integers in big-endian order: +.PP +.EX +.ta \w'#define 'u +\w'_MAGIC(b) 'u +\w'_MAGIC(10) 'u +4n +4n +4n +4n +typedef struct Exec { + long magic; /* magic number */ + long text; /* size of text segment */ + long data; /* size of initialized data */ + long bss; /* size of uninitialized data */ + long syms; /* size of symbol table */ + long entry; /* entry point */ + long spsz; /* size of pc/sp offset table */ + long pcsz; /* size of pc/line number table */ +} Exec; +#define _MAGIC(b) ((((4*b)+0)*b)+7) +#define A_MAGIC _MAGIC(8) /* 68020 */ +#define I_MAGIC _MAGIC(11) /* intel 386 */ +#define J_MAGIC _MAGIC(12) /* intel 960 */ +#define K_MAGIC _MAGIC(13) /* sparc */ +#define V_MAGIC _MAGIC(16) /* mips 3000 */ +#define X_MAGIC _MAGIC(17) /* att dsp 3210 */ +#define M_MAGIC _MAGIC(18) /* mips 4000 */ +#define D_MAGIC _MAGIC(19) /* amd 29000 */ +#define E_MAGIC _MAGIC(20) /* arm 7-something */ +#define Q_MAGIC _MAGIC(21) /* powerpc */ +#define N_MAGIC _MAGIC(22) /* mips 4000 LE */ +#define L_MAGIC _MAGIC(23) /* dec alpha */ +.EE +.DT +.PP +Sizes are expressed in bytes. +The size of the header is not included in any of the other sizes. +.PP +When a Plan 9 binary file is executed, +a memory image of three segments is +set up: the text segment, the data segment, and the stack. +The text segment begins at a virtual address which is +a multiple of the machine-dependent page size. +The text segment consists of the header and the first +.B text +bytes of the binary file. +The +.B entry +field gives the virtual address of the entry point of the program. +The data segment starts at the first page-rounded virtual address +after the text segment. +It consists of the next +.B data +bytes of the binary file, followed by +.B bss +bytes initialized to zero. +The stack occupies the highest possible locations +in the core image, automatically growing downwards. +The bss segment may be extended by +.IR brk (2). +.PP +The next +.B syms +(possibly zero) +bytes of the file contain symbol table +entries, each laid out as: +.IP +.EX +uchar value[4]; +char type; +char name[\f2n\fP]; /* NUL-terminated */ +.EE +.PP +The +.B value +is in big-endian order and +the size of the +.B name +field is not pre-defined: it is a zero-terminated array of +variable length. +.PP +The +.B type +field is one of the following characters with the high bit set: +.RS +.TP +.B T +text segment symbol +.PD0 +.TP +.B t +static text segment symbol +.TP +.B L +leaf function text segment symbol +.TP +.B l +static leaf function text segment symbol +.TP +.B D +data segment symbol +.TP +.B d +static data segment symbol +.TP +.B B +bss segment symbol +.TP +.B b +static bss segment symbol +.TP +.B a +automatic (local) variable symbol +.TP +.B p +function parameter symbol +.RE +.PD +.PP +A few others are described below. +The symbols in the symbol table appear in the same order +as the program components they describe. +.PP +The Plan 9 compilers implement a virtual stack frame pointer rather +than dedicating a register; +moreover, on the MC680X0 architectures +there is a variable offset between the stack pointer and the +frame pointer. +Following the symbol table, +MC680X0 executable files contain a +.BR spsz -byte +table encoding the offset +of the stack frame pointer as a function of program location; +this section is not present for other architectures. +The PC/SP table is encoded as a byte stream. +By setting the PC to the base of the text segment +and the offset to zero and interpreting the stream, +the offset can be computed for any PC. +A byte value of 0 is followed by four bytes that hold, in big-endian order, +a constant to be added to the offset. +A byte value of 1 to 64 is multiplied by four and added, without sign +extension, to the offset. +A byte value of 65 to 128 is reduced by 64, multiplied by four, and +subtracted from the offset. +A byte value of 129 to 255 is reduced by 129, multiplied by the quantum +of instruction size +(e.g. two on the MC680X0), +and added to the current PC without changing the offset. +After any of these operations, the instruction quantum is added to the PC. +.PP +A similar table, occupying +.BR pcsz -bytes, +is the next section in an executable; it is present for all architectures. +The same algorithm may be run using this table to +recover the absolute source line number from a given program location. +The absolute line number (starting from zero) counts the newlines +in the C-preprocessed source seen by the compiler. +Three symbol types in the main symbol table facilitate conversion of the absolute +number to source file and line number: +.RS +.TP +.B f +source file name components +.TP +.B z +source file name +.TP +.B Z +source file line offset +.RE +.PP +The +.B f +symbol associates an integer (the +.B value +field of the `symbol') with +a unique file path name component (the +.B name +of the `symbol'). +These path components are used by the +.B z +symbol to represent a file name: the +first byte of the name field is always 0; the remaining +bytes hold a zero-terminated array of 16-bit values (in big-endian order) +that represent file name components from +.B f +symbols. +These components, when separated by slashes, form a file name. +The initial slash of a file name is recorded in the symbol table by an +.B f +symbol; when forming file names from +.B z +symbols an initial slash is not to be assumed. +The +.B z +symbols are clustered, one set for each object file in the program, +before any text symbols from that object file. +The set of +.B z +symbols for an object file form a +.I history stack +of the included source files from which the object file was compiled. +The value associated with each +.B z +symbol is the absolute line number at which that file was included in the source; +if the name associated with the +.B z +symbol is null, the symbol represents the end of an included file, that is, +a pop of the history stack. +If the value of the +.B z +symbol is 1 (one), +it represents the start of a new history stack. +To recover the source file and line number for a program location, +find the text symbol containing the location +and then the first history stack preceding the text symbol in the symbol table. +Next, interpret the PC/line offset table to discover the absolute line number +for the program location. +Using the line number, scan the history stack to find the set of source +files open at that location. +The line number within the file can be found using the line numbers +in the history stack. +The +.B Z +symbols correspond to +.B #line +directives in the source; they specify an adjustment to the line number +to be printed by the above algorithm. The offset is associated with the +first previous +.B z +symbol in the symbol table. +.SH "SEE ALSO" +.IR db (1), +.IR acid (1), +.IR 2a (1), +.IR 2l (1), +.IR nm (1), +.IR strip (1), +.IR mach (2), +.IR symbol (2) +.SH BUGS +There is no type information in the symbol table; however, the +.B -a +flags on the compilers will produce symbols for +.IR acid (1). diff --git a/sys/man/6/ar b/sys/man/6/ar new file mode 100755 index 000000000..669be0739 --- /dev/null +++ b/sys/man/6/ar @@ -0,0 +1,99 @@ +.TH AR 6 +.SH NAME +ar \- archive (library) file format +.SH SYNOPSIS +.B #include <ar.h> +.SH DESCRIPTION +The archive command +.IR ar (1) +is used to combine several files into +one. +Archives are used mainly as libraries to be searched +by the loaders +.IR 2l (1) +.I et al. +.PP +A file produced by +.I ar +has a magic string at the start, +followed by the constituent files, each preceded by a file header. +The magic number and header layout as described in the +include file are: +.IP +.EX +.ta \w'#define 'u +\w'SAR_HDR 'u +.ec % +#define ARMAG "!<arch>\n" +#define SARMAG 8 + +#define ARFMAG "`\n" + +struct ar_hdr { + char name[16]; + char date[12]; + char uid[6]; + char gid[6]; + char mode[8]; + char size[10]; + char fmag[2]; +}; +#define SAR_HDR 60 +.ec \ +.EE +.LP +The +.B name +is a blank-padded string. +The +.L fmag +field contains +.L ARFMAG +to help verify the presence of a header. +The other fields are left-adjusted, blank-padded numbers. +They are decimal except for +.LR mode , +which is octal. +The date is the modification date of the file (see +.IR stat (2)) +at the time of its insertion into the archive. +The mode is the low 9 bits of the file permission mode. +The length of the header is +.LR SAR_HDR . +Because the +.L ar_hdr +structure is padded in an architecture-dependent manner, +the structure should never be read or written as a unit; +instead, each field should be read or written independently. +.PP +Each file begins on an even (0 mod 2) boundary; +a newline is inserted between files if necessary. +Nevertheless +.B size +reflects the +actual size of the file exclusive of padding. +.PP +When all members of an archive are object files of +the same architecture, +.B ar +automatically adds an extra file, named +.BR __.SYMDEF , +as the first member of the archive. This file +contains an index used by the loaders to locate all +externally defined text and data symbols in the archive. +.PP +There is no provision for empty areas in an archive +file. +.SH "SEE ALSO" +.IR ar (1), +.IR 2l (1), +.IR nm (1), +.IR stat (2) +.SH BUGS +The +.B uid +and +.B gid +fields are unused in Plan 9. +They provide compatibility with Unix +.I ar +format. diff --git a/sys/man/6/authsrv b/sys/man/6/authsrv new file mode 100755 index 000000000..911b1f4b1 --- /dev/null +++ b/sys/man/6/authsrv @@ -0,0 +1,726 @@ +.TH AUTHSRV 6 +.SH NAME +authsrv, p9any, p9sk1, p9sk2 \- authentication protocols +.SH DESCRIPTION +This manual page describes +the protocols used to authorize connections, confirm the identities +of users and machines, and maintain the associated databases. +The machine that provides these services is called the +.I authentication server +(AS). +The AS may be a stand-alone machine or a general-use machine such as a CPU server. +The network database +.IR ndb (6) +holds for each public machine, such as a CPU server or +file server, the name of the authentication server that machine uses. +.PP +Each machine contains three values important to authentication; a 56-bit DES +key, a 28-byte authentication ID, and a 48-byte authentication domain name. +The ID is a user name and identifies who is currently responsible for the +kernel running on that machine. +The domain name identifies the machines across which the ID is valid. +Together, the ID and domain name identify the owner of a key. +.PP +When a terminal boots, +.IR factotum (4) +prompts for user name and password. +The user name becomes the terminal's authentication ID. +The password is converted using +.I passtokey +(see +.IR authsrv (2)) +into a 56-bit DES key and saved in memory. +The authentication domain is set to the null string. +If possible, +.I factotum +validates the key with the AS +before saving it. +For Internet machines the correct AS to ask is found using +.IR dhcpd (8). +.PP +When a CPU or file server boots, +.I factotum +reads the key, ID, and domain name from +non-volatile RAM. +This allows servers to reboot without operator intervention. +.PP +The details of any authentication are mixed with the semantics +of the particular service they are authenticating so we describe +them one case at a time. The following definitions will be used +in the descriptions: +.TF nullx +.TP +.I Ks +server's host ID's key +.TP +.I Kc +client's host ID's key +.TP +.I Kn +a nonce key created for a ticket +.RB ( key ) +.TP +.IR K { m } +message +.I m +encrypted with key +.I K +.TP +.I CHc +an 8-byte random challenge from a client +.RB ( chal ) +.TP +.I CHs +an 8-byte random challenge from a server +.RB ( chal ) +.TP +.I IDs +server's ID +.RB ( authid ) +.TP +.I DN +server's authentication domain name +.RB ( authdom ) +.TP +.I IDc +client's ID +.RB ( hostid , +.BR cuid ) +.TP +.I IDr +client's desired ID on server +.RB ( uid , +.BR suid ) +.PD +.PP +The parenthesized names are the ones used in the +.B Ticketreq +and +.B Ticket +structures in +.BR <authsrv.h> . +.PP +The message type constants +.IR AuthTreq , +.IR AuthChal , +.IR AuthPass , +.IR AuthOK , +.IR AuthErr , +.IR AuthMod , +.IR AuthApop , +.IR AuthOKvar , +.IR AuthChap , +.IR AuthMSchap , +.IR AuthCram , +and +.IR AuthVNC +.RB ( type ) +are defined in +.BR <authsrv.h> , +as are the encrypted message types +.IR AuthTs , +.IR AuthAs , +.IR AuthAc , +.IR AuthTp , +and +.IR AuthHr +.RB ( num ). +.SS "Ticket Service +When a client and server wish to authenticate to each other, +they do so using +.I tickets +issued by the AS. +Obtaining tickets from the AS +is the client's responsibility. +.PP +The protocol to obtain a ticket pair is: +.TP +.IR C \(-> A +.IR AuthTreq , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDc , +.IR IDr +.sp -\n(PDu +.TP +.IR A \(-> C +.IR AuthOK , +.IR Kc { AuthTc , +.IR CHs , +.IR IDc , +.IR IDr , +.IR Kn }, +.IR Ks { AuthTs , +.IR CHs , +.IR IDc , +.IR IDr , +.IR Kn } +.PP +The two tickets are identical except for their type fields +and the keys with which they are encrypted. +The client and server can each decrypt one of the tickets, +establishing a shared secret +.IR Kn . +.PP +The +tickets can be viewed as a statement by the +AS that +``a client possessing the +.I Kn +key is allowed to authenticate as +.IR IDr .'' +.PP +The presence of the server challenge +.I CHs +in the ticket allows the server to verify the freshness +of the ticket pair. +.PP +The AS sets the +.I IDr +in the tickets to the requested +.I IDr +only if +.I IDc +is allowed to +.I "speak for +.RI ( q.v. ) +.IR IDr . +If not, +the AS sets +.I IDr +to the empty string. +.PP +If the users +.I IDc +or +.I IDs +do not exist, +the AS silently generates one-time +random keys to use in place of +.I Kc +or +.IR Ks , +so that clients cannot probe the AS +to learn whether a user name is valid. +.SS "P9sk1 +The Plan 9 shared key protocol +.I p9sk1 +allows a client and server to authenticate each other. +The protocol is: +.TP +.IR C \(-> S +.I CHc +.br +The client starts by sending a random challenge to the server. +.TP +.IR S \(-> C +.IR AuthTreq , +.IR IDs , +.IR DN , +.IR CHs , +.IR \- , +.IR \- +.br +The server replies with a ticket request giving its +id and authentication domain along with its own +random challenge. +.TP +.IR C \(-> S +.IR Ks { AuthTs , +.IR CHs , +.IR IDc , +.IR IDr , +.IR Kn }, +.IR Kn { AuthAc , +.IR CHs } +.br +The client adds +.I IDc +and +.I IDr +to the ticket request and obtains a ticket pair +from the AS as described above. +The client relays the server's ticket along with +an +.IR authenticator , +the +.I AuthAc +message. +The authenticator proves to the server that the +client knows +.I Kn +and is therefore allowed to authenticate as +.IR IDr . +(The inclusion of +.IR CHs +in the authenticator avoids replay attacks.) +.TP +.IR S \(-> C +.IR Kn { AuthAs , +.IR CHc } +.br +The server replies with its own authenticator, +proving to the client that it also knows +.I Kn +and therefore +.I Ks . +.PD +.PP +.I P9sk2 +is an older variant of +.I p9sk1 +used only when connecting to pre-9P2000 remote +execution services. +It omits the first message and last +messages and therefore does not +authenticate the server to the client. +.SS "P9any +.I P9any +is the standard Plan 9 authentication protocol. +It consists of a negotiation to determine a common +protocol, followed by the agreed-upon protocol. +.PP +The negotiation protocol is: +.TP +.IR S \(-> C +.B v.2 +.IB proto@authdom +.IB proto@authdom +.I ... +.sp -\n(PDu +.TP +.IR C \(-> S +.I proto +.I dom +.sp -\n(PDu +.TP +.IR S \(-> C +.B OK +.PP +Each message is a NUL-terminated UTF string. +The server begins by sending a list of +.IR proto , +.I authdom +pairs it is willing to use. +The client +responds with its choice. +Requiring the client to wait for the final +.B OK +ensures that the client will not start +the chosen protocol until the server is ready. +.PP +The above is version 2 of the protocol. +Version 1, +no longer used, +omitted the first message's +.B v.2 +prefix +and the +.B OK +message. +.PP +The +.I p9any +protocol is the protocol used by all +Plan 9 services. +The file server runs it over special +authentication files +(see +.IR fauth (2) +and +.IR attach (5)). +Other services, such as +.IR cpu (1) +and +.IR exportfs (4), +run +.I p9any +over the network and then +use +.I Kn +to derive an +.IR ssl (3) +key to encrypt the rest of their communications. +.SS "Password Change +Users connect directly to the AS +to change their passwords. +The protocol is: +.TP +.IR C \(-> A +.IR AuthPass , +.IR IDc , +.IR DN , +.IR CHc , +.IR IDc , +.IR IDc +.br +The client sends a password change ticket request. +.TP +.IR A \(-> C +.IR Kc { AuthTp , +.IR CHc , +.IR IDc , +.IR IDc , +.IR Kn } +.br +The server responds with a ticket containing the key +.I Kn +encrypted with the client's key +.IR Kc +.TP +.IR C \(-> A +.IR Kn { AuthPass , +.IR old , +.IR new , +.IR changesecret , +.IR secret } +.br +The client decrypts the ticket using the old password +and then sends back an encrypted password request +.RB ( Passwordreq +structure) +containing the old password and the new password. +If +.I changesecret +is set, the AS also changes +the user's +.IR secret , +the password used for non-Plan 9 authentications. +.TP +.IR A \(-> C +.I AuthOK +or +.IR AuthErr , +64-byte error message +.br +The AS responds with simply +.I AuthOK +or with +.I AuthErr +followed by a 64-byte error message. +.SS "Authentication Database +An +.IR ndb (2) +database file +.B /lib/ndb/auth +exists for the AS. +This database maintains ``speaks for'' relationships, i.e., +it lists which users may speak for other users when +authtenticating. +The attribute types used by the AS are +.B hostid +and +.BR uid . +The value in the +.B hostid +is a client host's ID. +The values in the +.B uid +pairs in the same entry list which users that host ID +make speak for. +A uid value of +.B * +means the host ID may speak for all users. +A uid value of +.BI ! user +means the host ID may not speak for +.IR user . +For example: +.PP +.EX +hostid=bootes + uid=!sys uid=!adm uid=* +.EE +.PP +is interpreted as +.B bootes +may speak for any user except +.B sys +and +.BR adm . +This property is used heavily on CPU servers. +.SS "Foreign Protocols +The AS accepts ticket request +messages of types other than +.I AuthTreq +to allow users to +authenticate using non-Plan 9 protocols. +In these situations, the server communicates +directly with the AS. +Some protocols must begin without knowing the +client's name. They ignore the client name in the +ticket request. +All the protocols end +with the AS sending +an +.I AuthOK +message containing a server ticket and authenticator. +.PP +.I AuthOK +messages +always have a fixed but context-dependent size. +The occasional variable-length OK message starts with a +.I AuthOKvar +byte and a five-byte space-padded decimal length of the +data that follows. +.PP +Anywhere an +.I AuthOK +message is expected, a +.I AuthErr +message may be substituted. +.de Ok +.sp -\n(PDu +.TP +.IR A \(-> S +.IR AuthOK , +.IR Ks { \\$1 , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDs , +.IR IDc , +.IR Kn }, +.IR Kn { AuthTs , +.IR CHs } +.. +.PP +.TP +.IR S \(-> A +.IR AuthChal , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDs , +.IR IDc +.sp -\n(PDu +.TP +.IR A \(-> S +.IR AuthOK , +.IR challenge +.sp -\n(PDu +.TP +.IR S \(-> A +.IR response +.Ok AuthChal +.IP +This protocol allows the use of +handheld authenticators such as SecureNet +keys and SecureID tokens +in programs such as +.IR ssh (1) +and +.I ftpd +(see +.IR ipserv (8)). +.IP +.I Challenge +and +.I response +are text strings, +.SM NUL -padded +to 16 bytes +.RB ( NETCHLEN ). +The +.I challenge +is a random five-digit decimal number. +When using a SecureNet key or +.I netkey +(see +.IR passwd (1)), +the +.I response +is an eight-digit decimal or hexadecimal number +that is an encryption of the challenge +using the user's DES key. +.IP +When using a SecureID token, +the challenge is ignored. +The response is the user's PIN followed by +the six-digit number currently displayed +on the token. +In this case, the AS +queries an external RADIUS server +to check the response. +Use of a RADIUS server requires an entry in +the authentication database. For example: +.IP +.EX + radius=server-name secret=xyzzy + uid=howard rid=trickey + uid=sape rid=smullender +.EE +.IP +In this example, the secret +.B xyzzy +is the hash key used in talking to the RADIUS server. +The +.BR uid / rid +lines map from Plan 9 user ids to RADIUS ids. +Users not listed are assumed to have the +same id in both places. +.TP +.IR S \(-> A +AuthApop , +.IR IDs , +.IR DN , +.IR CHs , +.IR \- , +.IR \- +.sp -\n(PDu +.TP +.IR A \(-> S +.IR AuthOKvar , +.IR challenge +.sp -\n(PDu +.TP +.IR S \(-> A +AuthApop , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDc , +.IR IDc ; +hexadecimal MD5 checksum +.Ok AuthApop +.IP +This protocol implements APOP authentication +(see +.IR pop3 (8)). +After receiving a ticket request of type +.IR AuthApop , +the AS generates a random challenge +of the form +.BI < random @ domain >\fR. +The client then replies with a new ticket request +giving the user name +followed by the MD5 checksum of +the challenge concatenated with the user's secret. +If the response is correct, the authentication +server sends back a ticket +and authenticator. +If the response is incorrect, the client may repeat the +ticket request/MD5 checksum message to try again. +.IP +The +.I AuthCram +protocol runs identically to the +.I AuthApop +protocol, except that the expected MD5 checksum +is the keyed MD5 hash using the user's secret as the key +(see +.I hmac_md5 +in +.IR sechash (2)). +.TP +.IR S \(-> A +.IR AuthChap , +.IR IDs , +.IR DN , +.IR CHs , +.IR \- , +.IR \- +.sp -\n(PDu +.TP +.IR A \(-> S +.I challenge +.sp -\n(PDu +.TP +.IR S \(-> A +.IR pktid , +.IR IDc , +.IR response +.Ok AuthChap +.IP +This protocol implements CHAP authentication +(see +.IR ppp (8)). +The +.I challenge +is eight random bytes. +The response is a 16-byte MD5 checksum +over the packet id, user's secret, and challenge. +The reply packet is defined as +.B OChapreply +in +.BR <authsrv.h> . +.TP +.IR S \(-> A +.IR AuthMSchap , +.IR IDs , +.IR DN , +.IR CHs , +.IR \- , +.IR \- +.sp -\n(PDu +.TP +.IR A \(-> S +.I challenge +.sp -\n(PDu +.TP +.IR S \(-> A +.IR IDc , +.IR lm-response , +.IR nt-response +.Ok AuthMschap +.IP +This protocol implements Microsoft's MS-CHAP +authentication +(see +.IR ppp (8)). +The +.I challenge +is eight random bytes. +The two responses are Microsofts LM and NT hashes. +Only the NT hash may be used to authenticate, +as the LM hash is considered too weak. +The reply packet is defined as +.B OMSchapreply +in +.BR <authsrv.h> . +.TP +.IR S \(-> A +.IR AuthVNC , +.IR IDs , +.IR DN , +.IR CHs , +.IR IDs , +.IR IDc +.sp -\n(PDu +.TP +.IR A \(-> S +.IR AuthOKvar , +.I challenge +.sp -\n(PDu +.TP +.IR S \(-> A +.I response +.Ok +.IP +This protocol implements VNC authentication +(see +.I vncs +in +.IR vnc (1)). +The challenge is 16 random bytes, and the response +is a DES ECB encryption of the challenge. +The method by which VNC converts the user's +secret into a DES key is weak, +considering only the first eight bytes of the secret. +.PD +.SH FILES +.TF /lib/ndb/auth.*xxx +.TP +.B /lib/ndb/auth +database file +.TP +.B /lib/ndb/auth.* +hash files for +.B /lib/ndb/auth +.SH SEE ALSO +.IR auth (2), +.IR fauth (2), +.IR cons (3), +.IR attach (5), +.IR auth (8) diff --git a/sys/man/6/color b/sys/man/6/color new file mode 100755 index 000000000..aedaee58d --- /dev/null +++ b/sys/man/6/color @@ -0,0 +1,150 @@ +.TH COLOR 6 +.SH NAME +color \- representation of pixels and colors +.SH DESCRIPTION +To address problems of consistency and portability among applications, +Plan 9 uses a fixed color map, called +.BR rgbv , +on 8-bit-per-pixel displays. +Although this avoids problems caused by multiplexing color maps between +applications, it requires that the color map chosen be suitable for most purposes +and usable for all. +Other systems that use fixed color maps tend to sample the color cube +uniformly, which has advantages\(emmapping from a (red, green, blue) triple +to the color map and back again is easy\(embut ignores an important property +of the human visual system: eyes are +much more sensitive to small changes in intensity than +to changes in hue. +Sampling the color cube uniformly gives a color map with many different +hues, but only a few shades of each. +Continuous tone images converted into such maps demonstrate conspicuous +artifacts. +.PP +Rather than dice the color cube into subregions of +size 6\(mu6\(mu6 (as in Netscape Navigator) or 8\(mu8\(mu4 +(as in previous releases of Plan 9), picking 1 color in each, +the +.B rgbv +color map uses a 4\(mu4\(mu4 subdivision, with +4 shades in each subcube. +The idea is to reduce the color resolution by dicing +the color cube into fewer cells, and to use the extra space to increase the intensity +resolution. +This results in 16 grey shades (4 grey subcubes with +4 samples in each), 13 shades of each primary and secondary color (3 subcubes +with 4 samples plus black) and a reasonable selection of colors covering the +rest of the color cube. +The advantage is better representation of +continuous tones. +.PP +The following function computes the 256 3-byte entries in the color map: +.IP +.EX +.ta 6n +6n +6n +6n +void +setmaprgbv(uchar cmap[256][3]) +{ + uchar *c; + int r, g, b, v; + int num, den; + int i, j; + + for(r=0,i=0; r!=4; r++) + for(v=0; v!=4; v++,i+=16) + for(g=0,j=v-r; g!=4; g++) + for(b=0; b!=4; b++,j++){ + c = cmap[i+(j&15)]; + den = r; + if(g > den) + den = g; + if(b > den) + den = b; + if(den == 0) /* would divide check; pick grey shades */ + c[0] = c[1] = c[2] = 17*v; + else{ + num = 17*(4*den+v); + c[0] = r*num/den; + c[1] = g*num/den; + c[2] = b*num/den; + } + } +} +.EE +.PP +There are 4 nested loops to pick the (red,green,blue) coordinates of the subcube, +and the value (intensity) within the subcube, indexed by +.BR r , +.BR g , +.BR b , +and +.BR v , +whence +the name +.IR rgbv . +The peculiar order in which the color map is indexed is designed to distribute the +grey shades uniformly through the map\(emthe +.IR i 'th +grey shade, +.RI 0<= i <=15 +has index +.IR i ×17, +with black going to 0 and white to 255. +Therefore, when a call to +.B draw +converts a 1, 2 or 4 bit-per-pixel picture to 8 bits per pixel (which it does +by replicating the pixels' bits), the converted pixel values are the appropriate +grey shades. +.PP +The +.B rgbv +map is not gamma-corrected, for two reasons. First, photographic +film and television are both normally under-corrected, the former by an +accident of physics and the latter by NTSC's design. +Second, we require extra color resolution at low intensities because of the +non-linear response and adaptation of the human visual system. +Properly +gamma-corrected displays with adequate low-intensity resolution pack the +high-intensity parts of the color cube with colors whose differences are +almost imperceptible. +Either reason suggests concentrating +the available intensities at the low end of the range. +.PP +On `true-color' displays with separate values for the red, green, and blue +components of a pixel, the values are chosen so 0 represents no intensity (black) and the +maximum value (255 for an 8-bit-per-color display) represents full intensity (e.g., full red). +Common display depths are 24 bits per pixel, with 8 bits per color in order +red, green, blue, and 16 bits per pixel, with 5 bits of red, 6 bits of green, and 5 bits of blue. +.PP +Colors may also be created with an opacity factor called +.BR alpha , +which is scaled so 0 represents fully transparent and 255 represents opaque color. +The alpha is +.I premultiplied +into the other channels, as described in the paper by Porter and Duff cited in +.IR draw (2). +The function +.B setalpha +(see +.IR allocimage (2)) +aids the initialization of color values with non-trivial alpha. +.PP +The packing of pixels into bytes and words is odd. +For compatibility with VGA frame buffers, the bits within a +pixel byte are in big-endian order (leftmost pixel is most +significant bits in byte), while bytes within a pixel are packed in little-endian +order. Pixels are stored in contiguous bytes. This results +in unintuitive pixel formats. For example, for the RGB24 format, +the byte ordering is blue, green, red. +.PP +To maintain a constant external representation, +the +.IR draw (3) +interface +as well as the +various graphics libraries represent colors +by 32-bit numbers, as described in +.IR color (2). +.SH "SEE ALSO" +.IR color (2), +.IR graphics (2), +.IR draw (2) diff --git a/sys/man/6/face b/sys/man/6/face new file mode 100755 index 000000000..8820cec81 --- /dev/null +++ b/sys/man/6/face @@ -0,0 +1,116 @@ +.TH FACE 6 +.SH NAME +face \- face files +.SH DESCRIPTION +The directories +.B /usr/$user/lib/face +and +.B /lib/face +contain a hierarchy of images of people. +In those directories are subdirectories named by the sizes of +the corresponding image files: +.B 48x48x1 +(48 by 48 pixels, one bit per pixel); +.B 48x48x2 +(48 by 48 pixels, two (grey) bits per pixel); +.B 48x48x4 +(48 by 48 pixels, four (grey) bits per pixel); +.B 48x48x8 +(48 by 48 pixels, eight (color-mapped) bits per pixel); +.B 512x512x8 +(512 by 512 pixels, eight (color-mapped) bits per pixel); +.B 512x512x24 +(512 by 512 pixels, twenty-four bits per pixel (3 times 8 bits +per color)). +The large files serve no special purpose; they are stored +as images +(see +.IR image (6)). +The small files are the `icons' displayed by +.B faces +and +.B seemail +(see +.IR faces (1)); +for depths less than 4, their format is special. +.PP +One- and two-bit deep icons are stored as text, one line of the file to one scan line +of display. +Each line is divided into 8-bit, 16-bit, or 32-bit big-endian words, +stored as a list of comma-separated hexadecimal C constants, +such as: +.IP +.EX +0x9200, 0x1bb0, 0x003e, +.EE +.PP +This odd format is historical and the programs that read it +are somewhat forgiving about blanks and the need for commas. +.PP +The files +.BR lib/face/*/.dict +hold a correspondence between users at machines +and face files. +The format is +.IP +.EX +.I machine\fB/\fPuser directory\fB/\fPfile\fB.\fPver +.EE +.PP +The +.I machine +is the domain name of the machine sending the message, +and +.I user +the name of the user sending it, as recorded in +.BR /sys/log/mail . +The +.I directory +is a further subdirectory of (say) +.BR /lib/face/48x48x1 , +named by a single letter corresponding to the first character +of the user names. The +.I file +is the name of the file, typically but not always the user name, +and +.I ver +is a number to distinguish different images, for example to +distinguish the image for Bill Gates from the image for Bill Joy, +both of which might otherwise be called +.BR b/bill . +For example, Bill Gates might be represented by the line +.IP +.EX +microsoft.com/bill b/bill.1 +.EE +.PP +If multiple entries exist for a user in the various +.B .dict +files, +.I faces +chooses the highest pixel size less than or equal to that of the +display on which it is running. +.PP +Finally, or rather firstly, the file +.B /lib/face/.machinelist +contains a list of machine/domain pairs, one per line, +to map any of a set of machines to a single domain name to +be looked up in the +.B .dict +files. The machine name may be a regular expression, +so for example the entry +.IP +.EX +\&.*research\e.bell-labs\e.com astro +.EE +.PP +maps any of the machines in Bell Labs Research into the +shorthand name +.BR astro , +which then appears as a domain name in the +.B .dict +files. +.SH "SEE ALSO" +.IR mail (1), +.IR tweak (1), +.IR image (6) diff --git a/sys/man/6/font b/sys/man/6/font new file mode 100755 index 000000000..c6263f66a --- /dev/null +++ b/sys/man/6/font @@ -0,0 +1,87 @@ +.TH FONT 6 +.SH NAME +font, subfont \- external format for fonts and subfonts +.SH SYNOPSIS +.B #include <draw.h> +.SH DESCRIPTION +Fonts and subfonts are described in +.IR cachechars (2). +.PP +External fonts are described by a plain text file that can be read using +.IR openfont . +The format of the file is a header followed by any number of +subfont range specifications. +The header contains two numbers: the height and the ascent, both in pixels. +The height is the inter-line spacing and the ascent is the distance +from the top of the line to the baseline. These numbers are chosen +to display consistently all the subfonts of the font. +A subfont range specification contains two or three numbers and a file name. +The numbers are the inclusive range of characters covered by the subfont, +with an optional starting position within the subfont, +and the file name names an external file suitable for +.I readsubfont +(see +.IR graphics (2)). +The minimum number of a covered range is mapped to the specified starting position +(default zero) of the +corresponding subfont. +If the subfont file name does not begin with a slash, it is taken relative to the +directory containing the font file. +Each field must be followed by some white space. +Each numeric field may be C-format decimal, octal, or hexadecimal. +.PP +External subfonts are represented in a more rigid format +that can be read and written using +.I readsubfont +and +.I writesubfont +(see +.IR subfont (2)). +The format for subfont files is: an image containing character glyphs, +followed by a subfont header, followed by character information. +The image has the format for external image files described in +.IR image (6). +The subfont header has 3 +decimal strings: +.BR n , +.BR height , +and +.BR ascent . +Each number is right-justified and blank padded in 11 characters, followed by a blank. +The character +.B info +consists of +.BR n +1 +6-byte entries, each giving the +.B Fontchar +.B x +(2 bytes, low order byte first), +.BR top , +.BR bottom , +.BR left , +and +.BR width . +The +.B x +field of the last +.B Fontchar +is used to calculate the image width +of the previous character; the other fields in the last +.B Fontchar +are irrelevant. +.PP +Note that the convention of using the character with value zero (NUL) to represent +characters of zero width (see +.IR draw (2)) +means that fonts should have, as their zeroth character, +one with non-zero width. +.SH FILES +.TF /lib/font/bit/* +.TP +.B /lib/font/bit/* +font directories +.SH "SEE ALSO" +.IR graphics (2), +.IR draw (2), +.IR cachechars (2), +.IR subfont (2) diff --git a/sys/man/6/htmlroff b/sys/man/6/htmlroff new file mode 100755 index 000000000..96d974b88 --- /dev/null +++ b/sys/man/6/htmlroff @@ -0,0 +1,358 @@ +.TH HTMLROFF 6 +.SH NAME +htmlroff \- HTML formatting and typesetting +.SH DESCRIPTION +.IR Htmlroff (1) +accepts +.I troff +input with a few extensions and changes. +This manual describes the changes to the input language, +assuming a working knowledge of +.I troff +itself. +.SS Name lengths +.PP +Request, macro, string, and number names can be longer +than two letters, as in: +.IP +.EX +\&.html c <center> +\&.de footnote +Footnote here. +\&.. +\&.footnote +\&.ds string "hello +\&\e*[string] +\&.nr number 1 +\&\en[number] +.EE +.SS HTML output +.PP +Two new requests: +.IP +.EX +\&.html \fIid\fP \fR[ \fI<html>\fP ]\fL +\&.ihtml \fIid\fP \fR[ \fI<ihtml>\fP ]\fL +.EE +.LP +.B .html +and +.B .ihtml +insert HTML into the output. +The requests are only for opening new HTML tags. +To close previously-opened tags, repeat the request +with the same +.IR id . +For example, the input: +.IP +.EX +\&.html t <table><tr> +\&.html td <td>Cell 1 +\&.html td <td>Cell 2 +\&.html td +\&.html t +.EE +.LP +produces this output: +.IP +.EX +<table><tr><td>Cell 1</td><td>Cell 2</td></tr></table> +.EE +.LP +The +.B .html +request is intended for block-level HTML constructs (those that can contain +.BR <p> ) +and maintains the HTML tag stack automatically. +Intermediate tags need not be explicitly closed: +removing the final +.B \&.html t +line in the example above would produce the same output. +The special +.I id +.L - +closes the HTML tags immediately after printing them. +.PP +The +.B .ihtml +request is similar to +.B .html +but is intended for inline HTML constructs such as +.B <b> +or +.B <i> +(those that can be contained +within +.BR <p> ). +Unlike +.BR .html , +.B .ihtml +treats the open HTML tags as a set rather than a stack: +each must be explicitly closed. +Although it treats the tags as a set, +.B .ihtml +treats nesting properly in the output, +closing and reopening tags as necessary. +For example, the input: +.IP +.EX +\&.ihtml style <b> +\&.ihtml link <a href="link.html"> +Bold +\&.ihtml style <i> +and italic, still linked. +\&.ihtml link <a> +Unlinked. +\&.ihtml style +.EE +.LP +produces this output: +.IP +.EX +<b><a href="link.html">Bold</a></b> +<i><a href="link.html">and italic, still linked.</i></a> +<i>Unlinked.</i> +.EE +.PP +Outside of +.B .html +and +.B .ihtml +requests, the characters +.LR < , +.LR > , +and +.L & +are treated as normal characters, not HTML markers, +and are translated to +.LR < , +.LR > , +and +.L & +on output. +To embed the raw HTML markers, use +.LR \e< , +.LR \e> , +and +.L \e@ +.RI [ sic ]. +.SS Font changes +.PP +.I Htmlroff +interprets the usual +.BR \ef , +.BR .ft , +.BR \es , +and +.B .ps +requests to change the font and point size. +After applying each such change to its internal registers, +.I htmlroff +invokes the +.B .font +macro to emit corresponding HTML. +The default definition of +.B .font +is: +.IP +.EX +\&.de font +\&.ihtml f1 +\&.ihtml f +\&.ihtml f <span style=\"font-size=\\n(.spt\"> +\&.if \\n(.f==2 .ihtml f1 <i> +\&.if \\n(.f==3 .ihtml f1 <b> +\&.if \\n(.f==4 .ihtml f1 <b><i> +\&.if \\n(.f==5 .ihtml f1 <tt> +\&.if \\n(.f==6 .ihtml f1 <tt><i> +\&.. +.EE +.LP +Input files can redefine +.B .font +like any other request or macro. +.SS Paragraphs +.I Htmlroff +implements line height, text adjustment, and margins by +wrapping all output text in +.B <p style="..."> +tags. +This behavior can be disabled by setting the +.B .paragraph +number register to zero. +Setting the +.B .margin +register to zero +eliminates only the margin annotations. +.SS Subscripts and superscripts +.PP +.I Htmlroff +interprets the +.BR \eu , +.BR \ed , +and +.BR \ev +requests to move vertically during output. +It emits output vertically offset up the page inside +.B <sup> +tags and output vertically offset down the page +inside +.B <sub> +tags. +This heuristic handles simple equations formatted by +.IR eqn (1). +.SS Conditional input +.PP +To make it easier to write input files that can be formatted by both +.I troff +and +.IR htmlroff , +.I htmlroff +adds a new condition +.B h +which evaluates true in +.B .if +and +.B .ie +requests. +The +.B t +condition continues to evaluate true, to accomodate +input files trying to distinguish between +.I troff +and +.IR nroff . +To write a conditional matching +.I troff +alone, use +.RB ` ".if !h .if t" '. +.PP +.I Htmlroff 's +handling of conditional input does not match +.IR troff 's +exactly. +For example, +.IP +.EX +\&.if 0 \e{\e +\&.de xx +\&.. +\&.\e} +.EE +.LP +redefines the +.B xx +macro in +.I troff +but not in +.IR htmlroff . +Do not write files depending on this behavior, as this bug may be fixed +in the future. +.I Htmlroff +also mishandles +.B \e} +in some cases. To work around them, use +.B .\e} +on a line by itself, as in the last example. +.SS Diversions +.PP +Diversions in +.I htmlroff +use the alignment in effect at the time of the +diversion +when output. +In particular, +.IP +.EX +\&.di xx +Line here. +\&.di +\&.nf +\&.ce +\&.xx +.EE +.LP +produces a centered line in +.I troff +but not in +.IR htmlroff . +The solution is to center inside the diversion, as in +.IP +.EX +\&.di xx +\&.if h .ce 999 +Line here +\&.di +.EE +.SS Traps +.I Htmlroff +implements traps at vertical position 0, +which run when the first character is about +to be printed. +Other position traps are ignored. +Input traps are implemented. +.SS Input pipes +.PP +.I Htmlroff +adds a new request +.B .inputpipe +.I stop +.I cmd +that redirects +.IR htmlroff 's +input into a pipe to +.IR cmd . +The redirection stops on encountering the line +.IR stop , +optionally followed by white space and extra text. +This is a dangerous and clumsy request, as +.I htmlroff +stops interpreting its input during the redirection, so +.I stop +must be found in the input itself, not in a macro that +the input might appear to call. +Although clumsy, +.B .inputpipe +allows input files to invoke +.I troff +to handle complicated input. +For example, +.B tmac.html +redefines the +.B PS +macro that marks the beginning of a +.IR pic (1) +picture: +.IP +.EX +\&.nr png -1 1 +\&.de PS +\&.ds pngbase "\e\e*[basename] +\&.if '\e\e*[pngbase]'' .ds pngbase \e\en(.B +\&.ds pngfile \e\e*[pngbase]\e\en+[png].png +\&.html - <center><img src="\e\e*[pngfile]"></center> +\&.inputpipe .PE troff2png >\e\e*[pngfile] +\&.. +.EE +.LP +This macro invokes the shell script +.I troff2png +to run troff and convert the Postscript +output to a PNG image file. +Before starting the program, the macro creates +a new file name for the image and prints +HTML referring to it. +The +.B .B +register holds the final path element +(the base name) of the current input file. +.SS Unimplemented +Tabs are set every eight spaces and cannot be changed. +.PP +Some requests, such as +.BR .tl , +are unimplemented for lack of a good implementation. +Workarounds can be defined as necessary in input files. +.SH SEE ALSO +.IR htmlroff (1), +.IR mhtml (6) diff --git a/sys/man/6/image b/sys/man/6/image new file mode 100755 index 000000000..315608919 --- /dev/null +++ b/sys/man/6/image @@ -0,0 +1,205 @@ +.TH IMAGE 6 +.SH NAME +image \- external format for images +.SH SYNOPSIS +.B #include <draw.h> +.SH DESCRIPTION +Images are described in +.IR graphics (2), +and the definition of pixel values is in +.IR color (6). +Fonts and images are stored in external files +in machine-independent formats. +.PP +Image files are read and written using +.B readimage +and +.B writeimage +(see +.IR allocimage (2)), or +.B readmemimage +and +.B writememimage +(see +.IR memdraw (2)). +An uncompressed image file starts with 5 +strings: +.BR chan , +.BR r.min.x , +.BR r.min.y , +.BR r.max.x , +and +.BR r.max.y . +Each is right-justified and blank padded in 11 characters, followed by a blank. +The +.B chan +value is a textual string describing the pixel format +(see +.B strtochan +in +.IR graphics (2) +and the discussion of channel descriptors below), +and the rectangle coordinates are decimal strings. +The rest of the file contains the +.B r.max.y-r.min.y +rows of pixel data. +A +.I row +consists of the byte containing pixel +.B r.min.x +and all the bytes up to and including the byte containing pixel +.BR r.max.x -1. +For images with depth +.I d +less than eight, a pixel with x-coordinate = +.I x +will appear as +.I d +contiguous bits in a byte, with the pixel's high order bit +starting at the byte's bit number +.if t \fIw\fP\(mu(\fIx\fP mod (8/\fIw\fP)), +.if n w*(x mod (8/w)), +where bits within a byte are numbered 0 to 7 from the +high order to the low order bit. +Rows contain integral number of bytes, so there may be some unused +pixels at either end of a row. +If +.I d +is greater than 8, the definition of images requires that it will a multiple of 8, so +pixel values take up an integral number of bytes. +.PP +The +.B loadimage +and +.B unloadimage +functions described in +.IR allocimage (2) +also deal with rows in this format, stored in user memory. +.PP +The channel format string is a sequence of two-character channel descriptions, +each comprising a letter +.RB ( r +for red, +.B g +for green, +.B b +for blue, +.B a +for alpha, +.B m +for color-mapped, +.B k +for greyscale, +and +.B x +for ``don't care'') +followed by a number of bits per pixel. +The sum of the channel bits per pixel is the +depth of the image, which must be either +a divisor or a multiple of eight. +It is an error to have more than +one of any channel but +.BR x . +An image must have either a greyscale channel; a color mapped channel; +or red, green, and blue channels. +If the alpha channel is present, it must be at least as deep as any other channel. +.PP +The channel string defines the format of the pixels in the file, +and should not be confused with ordering of bytes in the file. +In particular +.B 'r8g8b8' +pixels have byte ordering blue, green, and red within the file. +See +.IR color (6) +for more details of the pixel format. +.PP +A venerable yet deprecated format replaces the channel string +with a decimal +.IR ldepth , +which is the base two logarithm of the number +of bits per pixel in the image. +In this case, +.IR ldepth s +0, 1, 2, and 3 +correspond to channel descriptors +.BR k1 , +.BR k2 , +.BR k4 , +and +.BR m8 , +respectively. +.PP +Compressed image files start with a line of text containing the word +.BR compressed , +followed by a header as described above, followed by the image data. +The data, when uncompressed, is laid out in the usual form. +.PP +The data is represented by a string of compression blocks, each encoding +a number of rows of the image's pixel data. Compression blocks +are at most 6024 bytes long, so that they fit comfortably in a +single 9P message. Since a compression block must encode a +whole number of rows, there is a limit (about 5825 bytes) to the width of images +that may be encoded. Most wide images are in subfonts, +which, at 1 bit per pixel (the usual case for fonts), can be 46600 pixels wide. +.PP +A compression block begins with two decimal strings of twelve bytes each. +The first number is one more than the +.B y +coordinate of the last row in the block. The second is the number +of bytes of compressed data in the block, not including the two decimal strings. +This number must not be larger than 6000. +.PP +Pixels are encoded using a version of Lempel & Ziv's sliding window scheme LZ77, +best described in J A Storer & T G Szymanski +`Data Compression via Textual Substitution', +JACM 29#4, pp. 928-951. +.PP +The compression block is a string of variable-length +code words encoding substrings of the pixel data. A code word either gives the +substring directly or indicates that it is a copy of data occurring +previously in the pixel stream. +.PP +In a code word whose first byte has the high-order bit set, the rest of the +byte indicates the length of a substring encoded directly. +Values from 0 to 127 encode lengths from 1 to 128 bytes. +Subsequent bytes are the literal pixel data. +.PP +If the high-order bit is zero, the next 5 bits encode +the length of a substring copied from previous pixels. Values from 0 to 31 +encode lengths from 3 to 34 bytes. The bottom two bits of the first byte and +the 8 bits of the next byte encode an offset backward from the current +position in the pixel data at which the copy is to be found. Values from +0 to 1023 encode offsets from 1 to 1024. The encoding may be `prescient', +with the length larger than the offset, which works just fine: the new data +is identical to the data at the given offset, even though the two strings overlap. +.PP +Some small images, in particular 48\(mu48 face files +as used by +.I seemail +(see +.IR faces (1) +and +.IR face (6)) +and 16\(mu16 +cursors, can be stored textually, suitable for inclusion in C source. +Each line of text represents one scan line as a +comma-separated sequence of hexadecimal +bytes, shorts, or words in C format. +For cursors, each line defines a pair of bytes. +(It takes two images to define a cursor; each must be stored separately +to be processed by programs such as +.IR tweak (1).) +Face files of one bit per pixel are stored as a sequence of shorts, +those of larger pixel sizes as a sequence of longs. +Software that reads these files must deduce the image size from +the input; there is no header. +These formats reflect history rather than design. +.SH "SEE ALSO" +.IR jpg (1), +.IR tweak (1), +.IR graphics (2), +.IR draw (2), +.IR allocimage (2), +.IR color (6), +.IR face (6), +.IR font (6) diff --git a/sys/man/6/keyboard b/sys/man/6/keyboard new file mode 100755 index 000000000..8c01eb0b3 --- /dev/null +++ b/sys/man/6/keyboard @@ -0,0 +1,195 @@ +.TH KEYBOARD 6 +.SH NAME +keyboard \- how to type characters +.SH DESCRIPTION +Keyboards are idiosyncratic. +It should be obvious how to type ordinary +.SM ASCII +characters, +backspace, tab, escape, and newline. +In Plan 9, the key labeled +.B Return +or +.B Enter +generates a newline +.RB ( 0x0A ); +if there is a key labeled +.B Line +.BR Feed , +it generates a carriage return +.RB ( 0x0D ); +Plan 9 eschews CRLFs. +All control characters are typed in the usual way; +in particular, control-J is a line feed and control-M a carriage return. +On the PC and some other machines, the key labeled +.B Caps +.B Lock +acts as an additional control key. +.PP +The delete character +.RB ( 0x7F ) +may be generated by a different key, +one near the extreme upper right of the keyboard. +On the Next it is the key labeled +.L * +(not the asterisk above the 8). +On the SLC and Sparcstation 2, delete is labeled +.B Num +.B Lock +(the key above +.B Backspace +labeled +.B Delete +functions as an additional backspace key). +On the other keyboards, the key labeled +.B Del +or +.B Delete +generates the delete character. +.PP +The view character +.RB ( 0x80 ), +used by +.IR rio (1), +.IR acme (1), +and +.IR sam (1), +causes windows to scroll forward. +It is generally somewhere near the lower right of the main key area. +The scroll character is generated by the +.B VIEW +key on the Gnot, the +.B Alt +.B Graph +key on the SLC, and the arrow key ↓ +on the other terminals. +As a convenience for sloppy typists, some programs interpret → and ← keys, +which lie on either side of ↓, as view keys as well. +The arrow key ↑ scrolls backward. +.PP +Characters in Plan 9 are runes (see +.IR utf (6)). +Any 16-bit rune can be typed using a compose key followed by several +other keys. +The compose key is also generally near the lower right of the main key area: +the +.B NUM PAD +key on the Gnot, the +.B Alternate +key on the Next, the +.B Compose +key on the SLC, the +.B Option +key on the Magnum, and either +.B Alt +key on the PC. +After typing the compose key, type a capital +.L X +and exactly four hexadecimal characters (digits and +.L a +to +.LR f ) +to type a single rune with the value represented by +the typed number. +There are shorthands for many characters, comprising +the compose key followed by a two- or three-character sequence. +There are several rules guiding the design of the sequences, as +illustrated by the following examples. +The full list is too long to repeat here, but is contained in the file +.L /lib/keyboard +in a format suitable for +.IR grep (1) +or +.IR look (1). +.IP +A repeated symbol gives a variant of that symbol, e.g., +.B ?? +yields ¿\|. +.IP +.SM ASCII +digraphs for mathematical operators give the corresponding operator, e.g., +.B <= +yields ≤. +.IP +Two letters give the corresponding ligature, e.g., +.B AE +yields Æ. +.IP +Mathematical and other symbols are given by abbreviations for their names, e.g., +.B pg +yields ¶. +.IP +Chess pieces are given by a +.B w +or +.B b +followed by a letter for the piece +.RB ( k +for king, +.B q +for queen, +.B r +for rook, +.B n +for knight, +.B b +for bishop, or +.B p +for pawn), +e.g., +.B wk +for a white king. +.IP +Greek letters are given by an asterisk followed by a corresponding latin letter, +e.g., +.B *d +yields δ. +.IP +Cyrillic letters are given by an at sign followed by a corresponding latin letter or letters, +e.g., +.B @ya +yields я. +.IP +Script letters are given by a dollar sign followed by the corresponding regular letter, +e.g., +.B $F +yields ℱ. +.IP +A digraph of a symbol followed by a letter gives the letter with an accent that looks like the symbol, e.g., +.B ,c +yields ç. +.IP +Two digits give the fraction with that numerator and denominator, e.g., +.B 12 +yields ½. +.IP +The letter s followed by a character gives that character as a superscript, e.g., +.B s1 +yields ⁱ. +These characters are taken from the Unicode block 0x2070; the 1, 2, and 3 +superscripts in the Latin-1 block are available by using a capital S instead of s. +.IP +Sometimes a pair of characters give a symbol related to the superimposition of the characters, e.g., +.B cO +yields ©. +.IP +A mnemonic letter followed by $ gives a currency symbol, e.g., +.B l$ +yields £. +.PP +Note the difference between ß (ss) and µ (micron) and +the Greek β and μ. +.SH FILES +.TF "/lib/keyboard " +.TP +.B /lib/keyboard +sorted table of characters and keyboard sequences +.SH "SEE ALSO" +.IR intro (1), +.IR ascii (1), +.IR tcs (1), +.IR acme (1), +.IR rio (1), +.IR sam (1), +.IR cons (3), +.IR utf (6) diff --git a/sys/man/6/keys.who b/sys/man/6/keys.who new file mode 100755 index 000000000..c7a768f23 --- /dev/null +++ b/sys/man/6/keys.who @@ -0,0 +1,45 @@ +.TH KEYS.WHO 6 +.SH NAME +keys.who \- biographic information for key holders +.SH DESCRIPTION +When +.I auth/changeuser +(see +.IR auth (8)) +creates or modifies an account, it writes a line of +biographical information to +.BR /adm/keys.who . +The line contains the following fields, separated by +.L | +characters: +.TP +.I name +login name +.TP +.I postid +company-wide user name +.TP +.I "full name +full name of the user +.TP +.I dept +department of the user +.TP +.I email... +one or more fields containing email addresses +to be notified when the key is about to expire +.PD +.PP +The program +.IR auth/warning , +which has fallen into disrepair, +once read +.I keys.who +and mailed expiry warnings. +.SH EXAMPLE +.EX +rsc|rscox|Russell S Cox|11276|rsc|dmr|rob +.EE +.SH "SEE ALSO +.IR keyfs (4), +.IR auth (8) diff --git a/sys/man/6/man b/sys/man/6/man new file mode 100755 index 000000000..09d5455f2 --- /dev/null +++ b/sys/man/6/man @@ -0,0 +1,249 @@ +.TH MAN 6 +.SH NAME +man \- macros to typeset manual +.SH SYNOPSIS +.B nroff -man +.I file ... +.PP +.B troff -man +.I file ... +.SH DESCRIPTION +These macros are used to format pages of this manual. +.PP +Except in +.L .LR +and +.L .RL +requests, any text argument denoted +.I t +in the request summary may be zero to six words. +Quotes +\fL"\fP ... \fL"\fP +may be used to include blanks in a `word'. +If +.I t +is empty, +the special treatment is applied to +the next text input line (the next line that doesn't begin with dot). +In this way, for example, +.B .I +may be used to italicize a line of more than 6 words, or +.B .SM +followed by +.B .B +to make small letters in `bold' font. +.PP +A prevailing indent distance is remembered between +successive indented paragraphs, +and is reset to default value upon reaching a non-indented paragraph. +Default units for indents +.I i +are ens. +.PP +The fonts are +.TP +.B R +roman, the main font, preferred for diagnostics +.PD 0 +.TP +.B I +italic, preferred for parameters, short names of commands, +names of manual pages, +and naked function names +.TP +.L B +`bold', actually the constant width font, +preferred for examples, file names, declarations, keywords, names of +.B struct +members, and literals +(numbers are rarely literals) +.TP +.B L +also the constant width font. +In +.I troff +.BR L = B ; +in +.I nroff +arguments of the macros +.BR .L , +.BR .LR , +and +.B .RL +are printed in quotes; +preferred only where quotes really help (e.g. lower-case literals and +punctuation). +.PD +.LP +Type font and size are reset to default values +before each paragraph, and after processing +font- or size-setting macros. +.PP +The +.B -man +macros admit equations and tables in the style of +.IR eqn (1) +and +.IR tbl (1), +but do not support arguments on +.B .EQ +and +.B .TS +macros. +.PP +These strings are predefined by +.BR -man : +.TP +.B \e*R +.if t `\*R', `(Reg)' in +.if t .IR nroff . +.if n `(Reg)', trademark symbol in +.if n .IR troff . +.br +.ns +.TP +.B \e*S +Change to default type size. +.SH FILES +.B /sys/lib/tmac/tmac.an +.SH SEE ALSO +.IR troff (1), +.IR man (1) +.SH REQUESTS +.ta \w'.TH n c x 'u +\w'Cause 'u +\w'Argument\ 'u +.di xx + \ka +.br +.di +.in \nau +.ti0 +Request Cause If no Explanation +.ti0 + Break Argument +.ti0 +\&\fL.B\fR \fIt\fR no \fIt\fR=n.t.l.* Text +.I t +is `bold'. +.ti0 +\&\fL.BI\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating bold and italic. +.ti0 +\&\fL.BR\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating bold and Roman. +.ti0 +\&\fL.DT\fR no Restore default tabs. +.ti0 +\&\fL.EE\fR yes End displayed example +.ti0 +\&\fL.EX\fR yes Begin displayed example +.ti0 +\&\fL.HP\fR \fIi\fR yes \fIi\fR=p.i.* Set prevailing indent to +.IR i . +Begin paragraph with hanging indent. +.ti0 +\&\fL.I\fR \fIt\fR no \fIt\fR=n.t.l. Text +.I t +is italic. +.ti0 +\&\fL.IB\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating italic and bold. +.ti0 +\&\fL.IP\fR \fIx i\fR yes \fIx\fR="" Same as \fL.TP\fP with tag +.IR x . +.ti0 +\&\fL.IR\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating italic and Roman. +.ti0 +\&\fL.L\fR \fIt\fR no \fIt\fR=n.t.l. Text +.I t +is literal. +.ti0 +\&\fL.LP\fR yes Same as \fL.PP\fP. +.ti0 +\&\fL.LR\fR \fIt\fR no Join 2 +words of +.I t +alternating literal and Roman. +.ti0 +\&\fL.PD\fR \fId\fR no \fId\fR=\fL.4v\fP Interparagraph distance is +.IR d . +.ti0 +\&\fL.PP\fR yes Begin paragraph. +Set prevailing indent to default. +.ti0 +\&\fL.RE\fR yes End of relative indent. +Set prevailing indent to amount of starting \fL.RS\fP. +.ti0 +\&\fL.RI\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating Roman and italic. +.ti0 +\&\fL.RL\fR \fIt\fR no Join 2 or 3 +words of +.I t +alternating Roman and literal. +.ti0 +\&\fL.RS\fR \fIi\fR yes \fIi\fR=p.i. Start relative indent, +move left margin in distance +.IR i . +Set prevailing indent to default for nested indents. +.ti0 +\&\fL.SH\fR \fIt\fR yes \fIt\fR="" Subhead; reset paragraph distance. +.ti0 +\&\fL.SM\fR \fIt\fR no \fIt\fR=n.t.l. Text +.I t +is small. +.ti0 +\&\fL.SS\fR \fIt\fR no \fIt\fR="" Secondary subhead. +.ti0 +\&\fL.TF\fR \fIs\fR yes Prevailing indent is wide as +string +.I s +in font +.BR L ; +paragraph distance is 0. +.ti0 +\&\fL.TH\fR \fIn c x\fR yes Begin page named +.I n +of chapter +.IR c; +.I x +is extra commentary, e.g. `local', for page head. +Set prevailing indent and tabs to default. +.ti0 +\&\fL.TP\fR \fIi\fR yes \fIi\fR=p.i. Set prevailing indent to +.IR i . +Restore default indent if +.IR i =0. +Begin indented paragraph +with hanging tag given by next text line. +If tag doesn't fit, place it on separate line. +.ti0 +\&\fL.1C\fR yes Equalize columns and return to 1-column output +.ti0 +\&\fL.2C\fR yes Start 2-column nofill output +.PP +.ti0 +* n.t.l. = next text line; p.i. = prevailing indent +.SH BUGS +There's no way to fool +.I troff +into handling literal double quote marks +.B \&" +in font-alternation macros, such as +.LR .BI . +.br +There is no direct way to suppress column widows in 2-column +output; the column lengths may be adjusted by inserting +.L .sp +requests before the closing +.LR .1C . diff --git a/sys/man/6/map b/sys/man/6/map new file mode 100755 index 000000000..d767065a6 --- /dev/null +++ b/sys/man/6/map @@ -0,0 +1,87 @@ +.TH MAP 6 +.SH NAME +map \- digitized map formats +.SH DESCRIPTION +Files used by +.IR map (7) +are a sequence of structures of the form: +.PP +.EX +struct { + signed char patchlatitude; + signed char patchlongitude; + short n; + union { + struct { + short latitude; + short longitude; + } point[n]; + struct { + short latitude; + short longitude; + struct { + signed char latdiff; + signed char londiff; + } point[\-n]; + } highres; + } segment; +}; +.EE +where +.B short +stands for 16-bit integers and there is no padding within or between +.BR structs . +Shorts are stored in little-endian order, low byte first. +To assure portability, +.I map +accesses them bytewise. +.PP +Fields +.L patchlatitude +and +.L patchlongitude +tell to what +10-degree by 10-degree +patch of the earth's surface a segment belongs. +Their values range from \-9 to 8 and from \-18 to 17, +respectively, and indicate the coordinates of the +southeast corner of the patch in units of 10 degrees. +.PP +Each segment of +.RB | n | +points is connected; consecutive segments +are not necessarily related. +Latitude and longitude +are measured in units of 0.0001 radian. +If +.B n +is negative, then +differences to the first and succeeding points +are measured in units of 0.00001 radian. +Latitude is counted positive to the north and +longitude positive to the west. +.PP +The patches are ordered lexicographically by +.L patchlatitude +then +.LR patchlongitude . +A printable +index to the first segment of each patch +in a file named +.I data +is kept in an associated file named +.IB data .x\f1. +Each line of an index file contains +.L patchlatitude, +.L patchlongitude +and the byte position +of the patch +in the map file. +Both the map file and the index file are ordered by +patch latitude and longitude. +.SH "SEE ALSO" +.IR map (7) +.br +The data comes from the World Data Bank I and II and +U.S. Government sources: the Census Bureau, Geological +Survey, and CIA. diff --git a/sys/man/6/mhtml b/sys/man/6/mhtml new file mode 100755 index 000000000..0aaf7608f --- /dev/null +++ b/sys/man/6/mhtml @@ -0,0 +1,105 @@ +.TH MHTML 6 +.SH NAME +mhtml \- macros for formatting HTML +.SH SYNOPSIS +.B pic +.B | +.B tbl +.B | +.B eqn +.B | +.B htmlroff +[ +.B -man +| +.B -ms +] +.B -mhtml +.I file +\&... +.SH DESCRIPTION +This package of +.IR htmlroff (1) +macro definitions provides convenient macros for formatting HTML. +It is usually used along with +.IR troff (1) +macro packages such as +.IR man (6) +and +.IR ms (6). +.I Mhtml +replaces some macros defined in the other packages, +so it should be listed after them on the +.I htmlroff +command line. +.PP +The following macros are defined: +.TP +.B .HTML \fItitle +Print an HTML header marking the output as +HTML 4.01 loose transitional encoded in UTF. +If given, the +.I title +is printed inside +.B <title> +tags. +This macro opens the +.B <html> +tag, opens and closes the +.B <head> +section, and opens +.BR <body> . +It invokes the +.B .HEAD +macro inside the +.B <head> +section. +To add arbitrary lines to the header, +append to +.B .HEAD +before invoking +.BR .HTML . +.TP +.B .FS\fR, \fP.FE +Accumulate footnotes and print them at the end of the +document under a \fBNotes\fP heading. +These replace the macros in +.IR ms (6). +To emit the notes accumulated so far, invoke +.BR .NOTES . +.TP +.B .PS\fR, \fP.PE +Replace input bracketed +.B .PS +and +.B .PE +with a PNG image corresponding to the output of +running +.IR troff (1) +on the input. +.TP +.B .TS\fR, \fP.TE +Identical to +.B .PS +and +.BR .PE . +.TP +.B .B1 \fImargin\fP \fIwidth\fR, \fL.B2 +Format the input between +.B .B1 +and +.B .B2 +inside a box, with +.I margin +(default 10) +pixels between the box and the text. +The box is set to be +.I width +(default 60) +percent of the current output width. +.SH FILES +.B /sys/lib/tmac/tmac.html +.SH SEE ALSO +.IR htmlroff (1), +.IR htmlroff (6), +.IR ms (6) diff --git a/sys/man/6/mnihongo b/sys/man/6/mnihongo new file mode 100755 index 000000000..6ae8a1219 --- /dev/null +++ b/sys/man/6/mnihongo @@ -0,0 +1,30 @@ +.TH MNIHONGO 6 +.SH NAME +mnihongo \- macros for typesetting Japanese +.SH SYNOPSIS +.B troff -mnihongo +.I ... +.SH DESCRIPTION +.I Mnihongo +provides a simple +.IR troff (1) +post-processor that formats Unicode characters that +might be Japanese text. +It looks up the characters in the bitmap font +.B /lib/font/bit/pelm/unicode.9x24.font +and generates bitmap images embedded in the output. +.PP +During troff processing, widths of the Japanese characters +are taken from the troff font +.BR Jp , +which is at best a simple approximation to the truth. +.SH FILES +.B /bin/aux/mnihongo +.br +.B /sys/lib/tmac/tmac.nihongo +.br +.B /lib/font/bit/pelm/unicode.9x24.font +.SH SOURCE +.B /sys/src/cmd/aux/mnihongo +.SH SEE ALSO +.IR troff (1) diff --git a/sys/man/6/mpictures b/sys/man/6/mpictures new file mode 100755 index 000000000..7100118f3 --- /dev/null +++ b/sys/man/6/mpictures @@ -0,0 +1,151 @@ +.TH MPICTURES 6 +.SH NAME +mpictures \- picture inclusion macros +.SH SYNOPSIS +.B troff -mpictures +[ +.I options +] +.I file ... +.SH DESCRIPTION +.I Mpictures +macros insert PostScript pictures into +.IR troff (1) +documents. +The macros are: +.TP +.BI .BP " source height width position offset flags label +Define a frame and place a picture in it. +Null arguments, represented by \f5""\fR, +are interpreted as defaults. +The arguments are: +.RS +.TP +.I source +Name of a PostScript picture file, optionally +suffixed with +.RI ( n ) +to select page number +.I n +from the file (first page by default). +.PD0 +.TP +.I height +Vertical size of the frame, default +.BR 3.0i . +.TP +.I width +Horizontal size of the frame, current line length by default. +.TP +.I position +.L l +(default), +.LR c , +or +.L r +to left-justify, center, or right-justify the frame. +.TP +.I offset +Move the frame horizontally from the original +.I position +by this amount, default +.BR 0i . +.TP +.I flags +One or more of: +.RS +.PD 0v +.TP +.BI a d +Rotate the picture clockwise +.I d +degrees, default +.IR d =90. +.TP +.B o +Outline the picture with a box. +.TP +.B s +Freely scale both picture dimensions. +.TP +.B w +White out the area to be occupied by the picture. +.TP +.BR l , r , t ,\fPb +Attach the picture to the left right, top, or bottom of the frame. +.RE +.TP +.I label +Place +.I label +at distance +.B 1.5v +below the frame. +.PD +.PP +If there's room, +.B .BP +fills text around the frame. +Everything destined for either side of the frame +goes into a diversion to be retrieved when the accumulated +text sweeps past the trap set by +.B .BP +or when the diversion is explicitly closed +by +.BR .EP . +.RE +.TP +.BI .PI " source height" , width , "yoffset\fB,\fPxoffset flags. +This low-level macro, used by +.BR .BP , +can help do more complex things. +The two arguments not already described are: +.RS +.TP +.I xoffset +Offset the frame from the left margin by this amount, default +.BR 0i . +.PD0 +.TP +.I yoffset +Offset the frame from the current baseline, +measuring positive downward, default +.BR 0i . +.PD +.RE +.TP +.B .EP +End a picture started by +.BR .BP ; +.B .EP +is usually called implicitly by a trap +at frame bottom. +.PP +If a PostScript file lacks page-delimiting comments, +the entire file is included. +If no +.B %%BoundingBox +comment is present, the picture is +assumed to fill an 8.5\(mu11-inch page. +Nothing prevents the picture from being placed off the page. +.SH SEE ALSO +.IR troff (1) +.SH DIAGNOSTICS +A picture file that can't be read by the PostScript +postprocessor is replaced by white space. +.SH BUGS +A picture and associated text silently disappear if +a diversion trap set by +.B .BP +isn't reached. +Call +.B .EP +at the end of the document to retrieve it. +.br +Macros in other packages may break the adjustments +made to the line length and indent when text is being placed +around a picture. +.br +A missing or improper +.B %%BoundingBox +comment may cause the frame to be filled incorrectly. diff --git a/sys/man/6/ms b/sys/man/6/ms new file mode 100755 index 000000000..2a8047102 --- /dev/null +++ b/sys/man/6/ms @@ -0,0 +1,319 @@ +.TH MS 6 +.hc % +.SH NAME +ms \- macros for formatting manuscripts +.SH SYNOPSIS +.B "nroff -ms" +[ +.I options +] +.I file ... +.br +.B "troff -ms" +[ +.I options +] +.I file ... +.SH DESCRIPTION +This package of +.I nroff +and +.IR troff (1) +macro definitions provides a canned formatting +facility for tech%nical papers in various formats. +.PP +The macro requests are defined below. +Many +.I nroff +and +.I troff +requests are unsafe in conjunction with +this package, but the following requests may be used with +impunity after the first +.BR .PP : +.LR .bp , +.LR .br , +.LR .sp , +.LR .ls , +.LR .na . +.PP +Output of the +.IR eqn (1), +.IR tbl (1), +.IR pic (1) +and +.IR grap (1) +preprocessors +for equations, tables, pictures, and graphs is acceptable as input. +.SH FILES +.B /sys/lib/tmac/tmac.s +.SH "SEE ALSO" +.br +M. E. Lesk, +``Typing Documents on the UNIX System: Using the \-ms Macros with Troff and Nroff'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.br +.IR eqn (1), +.IR troff (1), +.IR tbl (1), +.IR pic (1) +.SH REQUESTS +.ta \w'.\fL.CW \fIx y z\fR 'u +\w'Initial 'u +\w'Cause 'u +.br +.di x + \ka +.br +.di +.in \nau +.ti0 +Request Initial Cause Explanation +.ti0 + Value Break +.br +.in \nau +.ti0 +\fL\&.1C\fP yes yes One column format on a new page. +.ti0 +\fL\&.2C\fP no yes Two column format. +.ti0 +\fL\&.AB\fP no yes Begin abstract. +.ti0 +\fL\&.AE\fP - yes End abstract. +.ti0 +\fL\&.AI\fP no yes Author's institution follows. +Suppressed in +.BR .TM . +.ti0 +\fL\&.AT\fP no yes Print `Attached' and turn off line filling. +.ti0 +\fL\&.AU\fP\fP\fP \fIx y\fR no yes Author's name follows. +.IR x " is location and " y " is" +extension, ignored except in +.BR TM . +.ti0 +\fL\&.B\fP \fIx y z\fR no no Print +.I x +in boldface, append roman +.I y +and preface with +.IR z ; +if no argument switch to boldface. +.ti0 +\fL\&.B1\fP no yes Begin text to be enclosed in a box. +.ti0 +\fL\&.B2\fP no yes End boxed text. +.ti0 +\fL\&.BI\fP \fIx y z\fR no no Print +.I x +in bold italic, append roman +.I y +and preface with +.IR z ; +if no argument switch to bold italic. +.ti0 +\fL\&.BT\fP date no Bottom title, automatically invoked at +foot of page. +May be redefined. +.ti0 +\fL\&.BX\fP \fIx\fR no no Print +.I x +in a box. +.ti0 +\fL\&.CW\fP \fIx y z\fR no no Constant width font for +.IR x , +append roman +.I y +and preface with +.IR z ; +if no argument switch to constant width. +.ti0 +\fL\&.CT\fP no yes Print `Copies to' and turn off line filling. +.ti0 +\fL\&.DA\fP \fIx\fR nroff no `Date line' at bottom of page +is +.IR x . +Default is today. +.ti0 +\fL\&.DE\fP - yes End displayed text. +Implies +.BR .KE . +.ti0 +\fL\&.DS\fP \fIx\fR no yes Start of displayed text, +to appear verbatim line-by-line: +.L I +indented (default), +.L L +left-justified, +.L C +centered, +.L B +(block) centered with straight left margin. +Implies +.BR .KS . +.ti0 +\fL\&.EG\fP no - Print document in BTL format for `Engineer's Notes.' Must be first. +.ti0 +\fL\&.EN\fP - yes Space after equation +produced by +.I neqn +or +.IR eqn (1). +.ti0 +\fL\&.EQ\fP \fIx y\fR - yes Display equation. +Equation number is +.IR y . +Optional +.I x +is +.BR I ", " L ", " C +as in +.BR .DS . +.ti0 +\fL\&.FE\fP - yes End footnote. +.ti0 +\fL\&.FP\fP \fIx\fR - no Set font positions for a family, e.g., +.L .FP lucidasans +.ti0 +\fL\&.FS\fP no no Start footnote. +The note will be moved to the bottom of the page. +.ti0 +\fL\&.HO\fP - no `Bell Laboratories, Holmdel, +New Jersey 07733'. +.ti0 +\fL\&.I\fP \fIx y z\fR no no Italicize +.IR x , +append roman +.I y +and preface with +.IR z ; +if no argument switch to italic. +.ti0 +\fL\&.IH\fP no no `Bell Laboratories, Naperville, Illinois 60540' +.ti0 +\fL\&.IM\fP no no Print document in BTL format for an internal memorandum. Must be first. +.ti0 +\fL\&.IP\fP \fIx y\fR no yes Start indented paragraph, +with hanging tag +.IR x . +Indentation is +.I y +ens (default 5). +.ti0 +\fL\&.KE\fP - yes End keep. +Put kept text on next page if not enough room. +.ti0 +\fL\&.KF\fP no yes Start floating keep. +If the kept text must be moved to the next page, +float later text back to this page. +.ti0 +\fL\&.KS\fP no yes Start keeping following text. +.ti0 +\fL\&.LG\fP no no Make letters larger. +.ti0 +\fL\&.LP\fP yes yes Start left-blocked paragraph. +.ti0 +\fL\&.LT\fP no yes Start a letter; a non-empty first argument +produces a full Lucent letterhead, a second argument is a room number, +a third argument is a telephone number. +.ti0 +\fL\&.MF\fP - - Print document in BTL format for `Memorandum for File.' Must be first. +.ti0 +\fL\&.MH\fP - no `Bell Laboratories, Murray Hill, +New Jersey 07974'. +.ti0 +\fL\&.MR\fP - - Print document in BTL format for `Memorandum for Record.' Must be first. +.ti0 +\fL\&.ND\fP \fIdate\fR troff no Use date supplied (if any) only in +special BTL format positions; omit from page footer. +.ti0 +\fL\&.NH\fP \fIn\fR - yes Same as +.BR .SH , +with automatic section +numbers like `1.2.3'; +.I n +is subsection level (default 1). +If +.I n +is 0, reset the numbering. +.ti0 +\fL\&.NL\fP yes no Make letters normal size. +.ti0 +\fL\&.P1\fP - yes Begin program display in constant width font. +.ti0 +\fL\&.P2\fP - yes End program display. +.ti0 +\fL\&.PE\fP - yes End picture; see +.IR pic (1). +.ti0 +\fL\&.PF\fP - yes End picture; restore vertical +position. +.ti0 +\fL\&.PP\fP no yes Begin paragraph. +First line indented. +.ti0 +\fL\&.PS\fP \fIh w\fR - yes Start picture; height +and width in inches. +.ti0 +\fL\&.PY\fP - no `Bell Laboratories, Piscataway, New Jersey 08854' +.ti0 +\fL\&.QE\fP - yes End quoted material. +.ti0 +\fL\&.QP\fP - yes Begin quoted paragraph (indent both margins). +.ti0 +\fL\&.QS\fP - yes Begin quoted material (indent both margins). +.ti0 +\fL\&.R\fP yes no Roman text follows. +.ti0 +\fL\&.RE\fP - yes End relative indent level. +.ti0 +\fL\&.RP\fP no - Cover sheet and first page for released +paper. +Must precede other requests. +.ti0 +\fL\&.RS\fP - yes Start level of relative indentation +from which subsequent indentation is measured. +.ti0 +\fL\&.SG\fP \fIx\fR no yes Insert signature(s) of author(s), +ignored except in +.B .TM +and +.BR .LT . +.IR x " is the reference line (initials of author and typist)." +.ti0 +\fL\&.SH\fP - yes Section head follows, +font automatically bold. +.ti0 +\fL\&.SM\fP no no Make letters smaller. +.ti0 +\fL\&.TA\fP\ \fIx\fR... 5... no Set tabs in ens. +Default is 5 10 15 ... +.ti0 +\fL\&.TE\fP - yes End table; see +.IR tbl (1). +.ti0 +\fL\&.TH\fP - yes End heading section of table. +.ti0 +\fL\&.TL\fP no yes Title follows. +.ti0 +\fL\&.TM\fP\ \fIx\fR... no - Print document in BTL technical memorandum format. +Arguments are TM number, (quoted list of) case number(s), and file number. +Must precede other requests. +.ti0 +\fL\&.TR\fP \fIx\fR - - Print in BTL technical report format; report number is \fIx\fR. Must be first. +.ti0 +\fL\&.TS\fP \fIx\fR - yes Begin table; if +.I x +is +.B H +table heading is repeated on new pages. +.ti0 +\fL\&.UL\fP \fIx\fR - no Underline argument (even in troff). +.ti0 +\fL\&.UX\fP\ \fIy z\fP - no `\fIz\fRUNIX\fIy\fP'; +first use gives registered trademark notice. +.ti0 +\fL\&.WH\fP - no `Bell Laboratories, Whippany, +New Jersey 07981'. +.hc diff --git a/sys/man/6/namespace b/sys/man/6/namespace new file mode 100755 index 000000000..caf58b3dc --- /dev/null +++ b/sys/man/6/namespace @@ -0,0 +1,95 @@ +.TH NAMESPACE 6 +.SH NAME +namespace \- name space description file +.SH DESCRIPTION +Namespace files describe how to construct a name space from scratch, +an operation normally performed by the +.I newns +or +.I addns +subroutines +(see +.IR auth (2)) +which is typically called by +.IR init (8). +Each line specifies one name space operation. +Spaces and tabs separate arguments to operations; +no quotes or escapes are recognized. +Blank lines and lines with +.B # +as the first non-space character are ignored. +Environment variables of the form +.BI $ name +are expanded within arguments, +where +.I name +is a +.SM UTF +string terminated by white space, a +.BR / , +or a +.BR $ . +.PP +The known operations and their arguments are: +.TF 0 +.TP +.BR mount \ [ -abcC ]\ \fIservename\ old " \fR[\fIspec\fR\^\^] +Mount +.I servename +on +.IR old . +.TP +.BR bind \ [ -abcC "] \fInew old +Bind +.I new +on +.IR old . +.TP +.BR import \ [ -abc ]\ \fIhost\fR\ "[\fIremotepath\fR\^\^] \fImountpoint\fR +Import +.I remotepath +from machine +.I server +and attach it to +.IR mountpoint . +.TP +.BI cd \ dir +Change the working directory to +.IR dir . +.TP +.BR unmount \ [ \fInew\fR ]\ \fIold +Unmount +.I new +from +.IR old , +or everything mounted on +.I old +if +.I new +is missing. +.TP +.BR clear +Clear the name space with +.BR rfork(RFCNAMEG) . +.TP +.BI . \ path +Execute the namespace file +.IR path . +Note that +.I path +must be present in the name space being built. +.PD +.PP +The options for +.IR bind , +.IR mount , +and +.I import +are interpreted as in +.IR bind (1) +and +.IR import (4). +.SH "SEE ALSO" +.IR bind (1), +.IR namespace (4), +.IR init (8) diff --git a/sys/man/6/ndb b/sys/man/6/ndb new file mode 100755 index 000000000..f7b481f85 --- /dev/null +++ b/sys/man/6/ndb @@ -0,0 +1,351 @@ +.TH NDB 6 +.SH NAME +ndb \- Network database +.SH DESCRIPTION +.PP +The network database consists of files +describing machines known to the local +installation and machines known publicly. +The files comprise multi-line tuples made up of +attribute/value pairs of the form +.IB attr = value +or sometimes just +.IR attr . +Each line starting without white space starts a new tuple. +Lines starting with +.B # +are comments. +.PP +The file +.B /lib/ndb/local +is the root of the database. +Other files are included in the +database if a tuple with an +attribute-value pair of attribute +.B database +and no value exists in +.BR /lib/ndb/local
. +Within the +.B database +tuple, +each pair with attribute +.B file +identifies a file to be included in the database. The files are searched +in the order they appear. +For example: +.IP +.EX +database= + file=/lib/ndb/common + file=/lib/ndb/local + file=/lib/ndb/global +.EE +.PP +declares the database to be composed of the three files +.BR /lib/ndb/common , +.BR /lib/ndb/local , +and +.BR /lib/ndb/global . +By default, +.B /lib/ndb/local +is searched before the others. +However, +.B /lib/ndb/local +may be included in the +.B database +to redefine its ordering. +.PP +Within tuples, pairs on the same line bind tighter than +pairs on different lines. +.PP +Programs search the database directly using the routines in +.IR ndb (2) +or indirectly using +.B ndb/cs +and +.B ndb/dns +(see +.IR ndb (8)). +Both +.B ndb/cs +and the routine +.I ndbipinfo +impose structure on the otherwise flat database by using +knowledge specific to the network. +The internet is made up of networks which can be subnetted +multiple times. A network must have an +.B ipnet +attribute and is uniquely identified by the values of its +.B ip +and +.B ipmask +attributes. If the +.B ipmask +is missing, the relevant Class A, B or C one is used. +.LP +A search for an attribute associated with a network or host starts +at the lowest level, the entry for the host or network itself, +and works its way up, bit by bit, looking at entries for nets/subnets +that include the network or host. The search ends when the attribute +is found. +For example, consider the following entries: +.IP +.EX +ipnet=murray-hill ip=135.104.0.0 ipmask=255.255.0.0 + dns=135.104.10.1 + ntp=ntp.cs.bell-labs.com +ipnet=plan9 ip=135.104.9.0 ipmask=255.255.255.0 + ntp=oncore.cs.bell-labs.com + smtp=smtp1.cs.bell-labs.com +ip=135.104.9.6 sys=anna dom=anna.cs.bell-labs.com + smtp=smtp2.cs.bell-labs.com +.EE +.LP +Here +.B anna +is on the subnet +.B plan9 +which is in turn on the class B net +.BR murray-hill . +Assume that we're searching for +.BR anna 's +.B NTP +and +.B SMTP +servers. +The search starts by looking for an entry with +.BR sys=anna . +We find the anna entry. Since it has an +.B smtp=smtp2.cs.bell-labs.com +pair, +we're done looking for that attribute. +To fulfill the NTP request, we continue by looking for networks +that include anna's IP address. +We lop off the right most one bit from anna's address and +look for an +.B ipnet= +entry with +.BR ip=135.104.9.4 . +Not finding one, we drop another bit and look for an +.B ipnet= +entry with +.BR ip=135.104.9.0 . +There is +such an entry and it has the pair, +.BR ntp=oncore.cs.bell-labs.com , +ending our search. +.PP +.I Ndb/cs +can be made to perform such network aware +searches by using metanames in the dialstring. +A metaname is a +.I $ +followed by an attribute name. +.I Ndb/cs +looks up the attribute relative to the system it is running +on. Thus, with the above example, if a program called +.IP +.EX + dial("tcp!$smtp!smtp", 0, 0, 0); +.EE +.LP +the dial would connect to the SMTP port of +.BR smtp2.cs.bell-labs.com . +.PP +A number of attributes are meaningful to programs and thus +reserved. +They are: +.TF dnsdomain +.TP +.B sys +system name (a short name) +.TP +.B dom +Internet fully-qualified domain name +.TP +.B ip +Internet address, +v4 or v6. +.TP +.B ipv6 +IPv6 Internet address. +For DNS, an +.L AAAA +record. +.TP +.B ether +Ethernet address +(must be lower-case hexadecimal). +Beware that for machines with multiple +.B ether +attributes, +.I dhcpd +may expect requests to come from the address in the first +.B ether +attribute. +.TP +.B bootf +file to download for initial bootstrap; +.B /386/9pxeload +to boot a PC via PXE. +.TP +.B ipnet +Internet network name +.TP +.B ipmask +Internet network mask +.TP +.B ipgw +Internet gateway +.TP +.B auth +authentication server to be used +.TP +.B authdom +authentication domain. Plan 9 supports multiple authentication +domains. To specify an authentication server for a particular domain, +add a tuple containing both +.B auth +and +.B authdom +attributes and values. +.TP +.B fs +file server to be used +.TP +.B tcp +a TCP service name +.TP +.B udp +a UDP service name +.TP +.B port +a TCP or UDP port number +.TP +.B restricted +a TCP service that can be called only by ports numbered +less that 1024 +.TP +.B proto +a protocol supported by a host. +The pair +.B proto=il +was needed by +.I cs +(see +.IR ndb (8)) +in tuples for hosts that supported the IL protocol +.TP +.B dnsdomain +a domain name that +.I ndb/dns +adds onto any unrooted names when doing a search. +There may be multiple +.B dnsdomain +pairs. +.TP +.B dns +a DNS server to use (for DNS and DHCP) +.TP +.B ntp +an NTP server to use (for DHCP) +.TP +.B smtp +an SMTP server to use (for DHCP) +.TP +.B time +a time server to use (for DHCP) +.TP +.B wins +a Windows name server (for DHCP) +.TP +.B mx +mail exchanger (for DNS and DHCP); +also +.BR pref . +.TP +.B srv +service location (for DNS); +also +.BR pri , +.B weight +and +.BR port . +.TP +.B soa +start of area (for DNS) +.PD +.PP +.I Cs +defers to +.I dns +to translate dotted names to IP addresses, +only consulting the database files if +.I dns +cannot translate the name. +.PP +.I Cs +allows network entries with +.B sys +and +.B dom +attributes but no +.B ip +attribute. +Searches for the system name are resolved +by looking up the domain name with +.IR dns . +.PP +The file +.B /lib/ndb/auth +is used during authentication to decide who has the power to `speak for' other +users; see +.IR authsrv (6). +.SH EXAMPLES +.LP +A tuple for the CPU server, spindle. +.LP +.EX +sys=spindle + dom=spindle.research.bell-labs.com + bootf=/mips/9powerboot + ip=135.104.117.32 ether=080069020677 +.EE +.LP +Entries for the network +.B mh-astro-net +and its subnets. +.LP +.EX +ipnet=mh-astro-net ip=135.104.0.0 ipmask=255.255.255.0 + fs=bootes.research.bell-labs.com + ipgw=r70.research.bell-labs.com + auth=p9auth.research.bell-labs.com +ipnet=unix-room ip=135.104.117.0 + ipgw=135.104.117.1 +ipnet=third-floor ip=135.104.51.0 + ipgw=135.104.51.1 +.EE +.LP +Mappings between TCP service names and port numbers. +.LP +.EX +.ta \w'\fLtcp=sysmonxxxxx'u \w'\fLtcp=sysmonxxxxxport=512xxx'u +tcp=sysmon port=401 +tcp=rexec port=512 restricted +tcp=9fs port=564 +.EE +.SH FILES +.TF /lib/ndb/local +.TP +.B /lib/ndb/local +first database file searched +.SH "SEE ALSO" +.IR con (1), +.IR dial (2), +.IR ndb (2), +.IR 9load (8), +.IR booting (8), +.IR dhcpd (8), +.IR ipconfig (8), +.IR ndb (8) diff --git a/sys/man/6/plot b/sys/man/6/plot new file mode 100755 index 000000000..73edcf0ed --- /dev/null +++ b/sys/man/6/plot @@ -0,0 +1,336 @@ +.TH PLOT 6 +.SH NAME +plot \- graphics interface +.SH DESCRIPTION +Files of this format are interpreted by +.IR plot (1) +to draw graphics on the screen. +A +.I plot +file is a +.SM UTF +stream of +instruction lines. +Arguments are delimited by spaces, tabs, or commas. +Numbers may be floating point. +Punctuation marks (except +.LR : ) +, +spaces, and tabs at the beginning of lines are ignored. +Comments run from +.L : +to newline. +Extra letters appended to a valid instruction are ignored. +Thus +.LR ...line , +.LR line , and +.L li +all mean the same thing. +Arguments are interpreted as follows: +.TP +1. +If an instruction requires no arguments, the rest of the line is ignored. +.TP +2. +If it requires a string argument, then all the line +after the first field separator is passed as argument. +Quote marks may be used to preserve leading blanks. +Strings may include newlines represented as +.LR \en . +.TP +3. +Between numeric arguments alphabetic characters and +punctuation marks are ignored. +Thus +.L +line from 5 6 to 7 8 +draws a line from (5, 6) to (7, 8). +.TP +4. +Instructions with numeric arguments remain in effect until +a new instruction is read. +Such commands may spill over many lines. Thus +the following sequence will draw a polygon +with vertices +(4.5, 6.77), (5.8, 5.6), (7.8, 4.55), and (10.0, 3.6). +.IP +.EX +move 4.5 6.77 +vec 5.8, 5.6 7.8 +4.55 10.0, 3.6 4.5, 6.77 +.EE +.PP +The instructions are executed in order. +The last designated point in a +.BR line ", " move ", " rmove , +.BR vec ", " rvec ", " arc , +or +.B point +command becomes the `current point' +.RI ( X,Y ) +for the next command. +.SS "Open & Close" +.PD0 +.TP 10 +.BI o " string" +Open plotting device. +For +.IR troff , +.I string +specifies the size of the plot +(default is +.LR 6i ). +.TP 10 +.B cl +Close plotting device. +.PD +.SS "Basic Plotting Commands" +.PD0 +.TP 10 +.B e +Start another frame of output. +.TP 10 +.BI m " x y" +(move) Current point becomes +.I "x y." +.TP 10 +.BI rm " dx dy" +Current point becomes +.I "X+dx Y+dy." +.TP 10 +.BI poi " x y" +Plot the point +.I "x y" +and make it the current point. +.TP 10 +.BI v " x y" +Draw a vector from the current point to +.I "x y." +.TP 10 +.BI rv " dx dy" +Draw vector from current point to +.RI X + dx +.RI Y + dy +.TP 10 +.BI li " x1 y1 x2 y2" +Draw a line from +.I "x1 y1" +to +.I "x2 y2." +Make the current point +.I "x2 y2." +.TP 10 +.BI t " string" +Place the +.I string +so that its +first character is centered on the current point (default). +If +.I string +begins with +.L \eC +.RL ( \eR ), +it is centered (right-adjusted) on the current point. +A backslash at the beginning of the string may +be escaped with another backslash. +.TP 10 +.BI a " x1 y1 x2 y2 xc yc r" +Draw a circular arc from +.I "x1 y1" +to +.I "x2 y2" +with center +.I "xc yc" +and radius +.IR r . +If the radius is positive, the arc is drawn counterclockwise; +negative, clockwise. +The starting point is exact but the ending point is approximate. +.TP 10 +.BI ci " xc yc r" +Draw a circle centered at +.I "xc yc" +with radius +.IR r . +If the range and frame parameters do not specify a square, +the `circle' will be elliptical. +.TP 10 +.BI di " xc yc r" +Draw a disc centered at +.I "xc yc" +with radius +.I r +using the filling color (see +.B cfill +below). +.TP 10 +.BI bo " x1 y1 x2 y2" +Draw a box with lower left corner at +.I "x1 y1" +and upper right corner at +.I "x2 y2." +.TP 10 +.BI sb " x1 y1 x2 y2" +Draw a solid box with lower left corner at +.I "x1 y1" +and upper right corner at +.I "x2 y2" +using the filling color (see +.B cfill +below). +.TP 10 +.BI par " x1 y1 x2 y2 xg yg" +Draw a parabola from +.I "x1 y1" +to +.I "x2 y2" +`guided' by +.I "xg yg." +The parabola passes through the midpoint of the line joining +.I "xg yg" +with the midpoint of the line +joining +.I "x1 y1" +and +.I "x2 y2" +and is tangent to the lines from +.I "xg yg" +to the endpoints. +.TP 10 +.BI "pol { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fP} }\fI" +Draw polygons with vertices +.I "x1 y1 ... xn yn" +and +.I "X1 Y1 ... Xm Ym." +If only one polygon is specified, the inner brackets are +not needed. +.TP 10 +.BI "fi { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fP} }\fI" +Fill a polygon. +The arguments are the same as those for +.B pol +except that the first vertex is automatically repeated to +close each polygon. +The polygons do not have to be connected. +Enclosed polygons appear as holes. +.TP 10 +.BI "sp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with simple endpoints. +.TP 10 +.BI "fsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with double first endpoint. +.TP 10 +.BI "lsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with double last endpoint. +.TP 10 +.BI "dsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with double endpoints. +.TP 10 +.BI "csp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +.TP 10 +.BI in " filename" +(include) Take commands from +.IR filename . +.TP 10 +.BI de " string " { " commands " } +Define +.I string +as +.IR commands . +.TP 10 +.BI ca " string scale" +Invoke commands defined as +.I string +applying +.I scale +to all coordinates. +.PD +.SS "Commands Controlling the Environment" +.PD0 +.TP 10 +.BI co " string" +Use color given by first character of +.IR string , +one of +.BR red , +.BR yellow , +.BR green , +.BR blue , +.BR cyan , +.BR magenta , +.BR white , +and +.BR kblack . +.TP 10 +.BI pe " string" +Use +.I string +as the style for drawing lines. +The available pen styles are: +.BR solid , +.BR dott [ed], +.BR short , +.BR long , +.BR dotd [ashed] , +.BR cdash , +.BR ddash +.TP 10 +.BI cf " string" +Color for filling (see +.BR co , +above). +.TP 10 +.BI ra " x1 y1 x2 y2" +The data will fall between +.I "x1 y1" +and +.I "x2 y2." +The plot will be magnified or reduced to fit +the device as closely as possible. +.IP +Range settings that exactly fill the plotting area +with unity scaling appear below for +devices supported by the filters of +.IR plot (1). +The upper limit is just outside the plotting area. +In every case the plotting area is taken to be square; +points outside may be displayable on +devices with nonsquare faces. +.TP 10 +.BI fr " px1 py1 px2 py2" +Plot the data in the fraction of the display +specified by +.I "px1 py1" +for lower left corner +and +.I "px2 py2" +for upper right corner. +Thus +.L frame .5 0 1. .5 +plots in the lower right +quadrant of the display; +.L frame 0. 1. 1. 0. +uses the whole display but +inverts the +.I y +coordinates. +.TP 10 +.B sa +Save the current environment, and move to a new one. +The new environment inherits the old one. +There are 7 levels. +.TP 10 +.B re +Restore previous environment. +.PD +.SH "SEE ALSO" +.IR plot (1), +.IR graph (1) diff --git a/sys/man/6/plumb b/sys/man/6/plumb new file mode 100755 index 000000000..bc58a5064 --- /dev/null +++ b/sys/man/6/plumb @@ -0,0 +1,417 @@ +.TH PLUMB 6 +.SH NAME +plumb \- format of plumb messages and rules +.SH SYNOPSIS +.B #include <plumb.h> +.SH DESCRIPTION +.SS "Message format +The messages formed by the +.IR plumb (2) +library are formatted for transmission between +processes into textual form, using newlines to separate +the fields. +Only the data field may contain embedded newlines. +The fields occur in a specified order, +and each has a name, corresponding to the elements +of the +.B Plumbmsg +structure, that is used in the plumbing rules. +The fields, in order, are: +.RS +.TF ndata +.TP +.B src +application/service generating message +.TP +.B dst +destination `port' for message +.TP +.B wdir +working directory (used if data is a file name) +.TP +.B type +form of the data, e.g. +.B text +.TP +.B attr +attributes of the message, in +.IB name = value +pairs separated by white space +(the value must follow the usual quoting convention if it contains +white space or quote characters or equal signs; it cannot contain a newline) +.TP +.B ndata +number of bytes of data +.TP +.B data +the data itself +.RE +At the moment, only textual data +.RB ( type=text ) +is supported. +.PD +.PP +All fields are optional, but +.B type +should usually be set since it describes the form of the data, and +.B ndata +must be an accurate count (possibly zero) of the number of bytes of data. +A missing field is represented by an empty line. +.SS "Plumbing rules +The +.B plumber +(see +.IR plumb (2)) +receives messages on its +.B send +port (applications +.I send +messages there), interprets and reformats them, and (typically) emits them from a destination port. +Its behavior is determined by a plumbing rules file, default +.BR /usr/$user/lib/plumbing , +which defines a set of pattern/action rules with which to analyze, rewrite, and dispatch +received messages. +.PP +The file is a sequence of rule sets, each of which is a set of one-line rules +called patterns and actions. +There must be at least one pattern and one action in each rule set. +(The only exception is that a rule set may contain nothing but +.B plumb +.B to +rules; such a rule set declares the named ports but has no other effect.) +A blank line terminates a rule set. +Lines beginning with a +.B # +character are commentary and are regarded as blank lines. +.PP +A line of the form +.EX + include \f2file\fP +.EE +substitutes the contents of +.I file +for the line, much as in a C +.B #include +statement. Unlike in C, the file name is not quoted. +If +.I file +is not an absolute path name, or one beginning +.B ./ +or +.BR ../ , +.I file +is looked for first in the directory in which the plumber is executing, +and then in +.BR /sys/lib/plumb . +.PP +When a message is received by the +.BR plumber , +the rule sets are examined in order. +For each rule set, if the message matches all the patterns in the rule set, +the actions associated with the rule set are triggered to dispose of the message. +If a rule set is triggered, the rest are ignored for this message. +If none is triggered, the message is discarded (giving a write error to the sender) +unless it has a +.B dst +field that specifies an existing port, in which case the message is emitted, unchanged, from there. +.PP +Patterns and actions all consist of three components: an +.IR object , +a +.IR verb , +and arguments. +These are separated by white space on the line. +The arguments may contain quoted strings and variable substitutions, +described below, and in some cases contain multiple words. +The object and verb are single words from a pre-defined set. +.PP +The object in a pattern is the name of an element of the message, such as +.B src +or +.BR data , +or the special case +.BR arg , +which refers to the argument component of the current rule. +The object in an action is always the word +.BR plumb . +.PP +The verbs in the pattern rules +describe how the objects and arguments are to be interpreted. +Within a rule set, the patterns are evaluated in sequence; if one fails, +the rule set fails. +Some verbs are predicates that check properties of the message; others rewrite +components of the message and implicitly always succeed. +Such rewritings are permanent, so rules that specify them should be placed after +all pattern-matching rules in the rule set. +.RS +.TF delete +.TP +.B add +The object must be +.BR attr . +Append the argument, which must be a sequence of +.IB name = value +pairs, to the list of attributes of the message. +.TP +.B delete +The object must be +.BR attr . +If the message has an attribute whose name is the argument, +delete it from the list of attributes of the message. +(Even if the message does not, the rule matches the message.) +.TP +.B is +If the text of the object is identical to the text of the argument, +the rule matches. +.TP +.B isdir +If the text of the object +is the name of an existing directory, the rule matches and +sets the variable +.B $dir +to that directory name. +.TP +.B isfile +If the text of the object is the name of an existing file (not a directory), +the rule matches and sets the variable +.B $file +to that file name. +.TP +.B matches +If the entire text of the object matches the regular expression +specified in the argument, the rule matches. +This verb is described in more detail below. +.TP +.B set +The value of the object is set to the value of the argument. +.RE +.PP +The +.B matches +verb has special properties that enable the rules to select which portion of the +data is to be sent to the destination. +By default, a +.B data +.B matches +rule requires that the entire text matches the regular expression. +If, however, the message has an attribute named +.BR click , +that reports that the message was produced by a mouse click within the +text and that the regular expressions in the rule set should be used to +identify what portion of the data the user intended. +Typically, a program such as an editor will send a white-space delimited +block of text containing the mouse click, using the value of the +.B click +attribute (a number starting from 0) to indicate where in the textual data the user pointed. +.PP +When the message has a +.B click +attribute, the +.B data +.B matches +rules extract the longest leftmost match to the regular expression that contains or +abuts the textual location identified by the +.BR click . +For a sequence of such rules within a given rule set, each regular expression, evaluated +by this specification, must match the same subset of the data for the rule set to match +the message. +For example, here is a pair of patterns that identify a message whose data contains +the name of an existing file with a conventional ending for an encoded picture file: +.EX + data matches '[a-zA-Z0-9_\-./]+' + data matches '([a-zA-Z0-9_\-./]+)\.(jpe?g|gif|bit|ps|pdf)' +.EE +The first expression extracts the largest subset of the data around the click that contains +file name characters; the second sees if it ends with, for example, +.BR \&.jpeg . +If only the second pattern were present, a piece of text +.B horse.gift +could be misinterpreted as an image file named +.BR horse.gif . +.PP +If a +.B click +attribute is specified in a message, it will be deleted by the +.B plumber +before sending the message if the +.B data +.B matches +rules expand the selection. +.PP +The action rules all have the object +.BR plumb . +There are only three verbs for action rules: +.RS +.TF client +.TP +.B to +The argument is the name of the port to which the message will be sent. +If the message has a destination specified, it must match the +.B to +port of the rule set or the entire rule set will be skipped. +(This is the only rule that is evaluated out of order.) +.TP +.B client +If no application has the port open, the arguments to a +.B plumb +.B start +rule specify a shell program to run in response to the message. +The message will be held, with the supposition that the program +will eventually open the port to retrieve it. +.TP +.B start +Like +.BR client , +but the message is discarded. +Only one +.B start +or +.B client +rule should be specified in a rule set. +.RE +.PP +The arguments to all rules may contain quoted strings, exactly as in +.IR rc (1). +They may also contain simple string variables, identified by a leading dollar sign +.BR $ . +Variables may be set, between rule sets, by assignment statements in the style of +.BR rc . +Only one variable assignment may appear on a line. +The +.B plumber +also maintains some built-in variables: +.RS +.TF $wdir +.TP +.B $0 +The text that matched the entire regular expression in a previous +.B data +.B matches +rule. +.BR $1 , +.BR $2 , +etc. refer to text matching the first, second, etc. parenthesized subexpression. +.TP +.B $attr +The textual representation of the attributes of the message. +.TP +.B $data +The contents of the data field of the message. +.TP +.B $dir +The directory name resulting from a successful +.B isdir +rule. +If no such rule has been applied, it is the string constructed +syntactically by interpreting +.B data +as a file name in +.BR wdir . +.TP +.B $dst +The contents of the +.B dst +field of the message. +.TP +.B $file +The file name resulting from a successful +.B isfile +rule. +If no such rule has been applied, it is the string constructed +syntactically by interpreting +.B data +as a file name in +.BR wdir . +.TP +.B $type +The contents of the +.B type +field of the message. +.TP +.B $src +The contents of the +.B src +field of the message. +.TP +.B $wdir +The contents of the +.B wdir +field of the message. +.RE +.SH EXAMPLE +The following is a modest, representative file of plumbing rules. +.EX +# these are generally in order from most specific to least, +# since first rule that fires wins. + +addr=':(#?[0-9]+)' +protocol='(https?|ftp|file|gopher|mailto|news|nntp|telnet|wais)' +domain='[a-zA-Z0-9_@]+([.:][a-zA-Z0-9_@]+)*/?[a-zA-Z0-9_?,%#~&/\e-]+' +file='([:.][a-zA-Z0-9_?,%#~&/\e-]+)*' + +# image files go to page +type is text +data matches '[a-zA-Z0-9_\e-./]+' +data matches '([a-zA-Z0-9_\e-./]+)\.(jpe?g|gif|bit)' +arg isfile $0 +plumb to image +plumb start page -w $file + +# URLs go to web browser +type is text +data matches $protocol://$domain$file +plumb to web +plumb start window webbrowser $0 + +# existing files, possibly tagged by line number, go to edit/sam +type is text +data matches '([.a-zA-Z0-9_/\-]+[a-zA-Z0-9_/\e-])('$addr')?' +arg isfile $1 +data set $file +attr add addr=$3 +plumb to edit +plumb start window sam $file + +# .h files are looked up in /sys/include and passed to edit/sam +type is text +data matches '([a-zA-Z0-9]+\e.h)('$addr')?' +arg isfile /sys/include/$1 +data set $file +attr add addr=$3 +plumb to edit +plumb start window sam $file +.EE +.PP +The following simple plumbing rules file is a good beginning set of rules. +.EX +# to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules + +editor = acme +# or editor = sam +include basic +.EE +.SH FILES +.TF /usr/$user/lib/plumbing +.TP +.B /usr/$user/lib/plumbing +default rules file. +.TP +.B /mnt/plumb +mount point for +.IR plumber (4). +.TP +.B /sys/lib/plumb +directory for +.B include +files. +.TP +.B /sys/lib/plumb/fileaddr +public macro definitions. +.TP +.B /sys/lib/plumb/basic +basic rule set. +.SH "SEE ALSO" +.IR plumb (1), +.IR plumb (2), +.IR plumber (4), +.IR regexp (6) diff --git a/sys/man/6/regexp b/sys/man/6/regexp new file mode 100755 index 000000000..58cc2ee1a --- /dev/null +++ b/sys/man/6/regexp @@ -0,0 +1,129 @@ +.TH REGEXP 6 +.SH NAME +regexp \- regular expression notation +.SH DESCRIPTION +A +.I "regular expression" +specifies +a set of strings of characters. +A member of this set of strings is said to be +.I matched +by the regular expression. In many applications +a delimiter character, commonly +.LR / , +bounds a regular expression. +In the following specification for regular expressions +the word `character' means any character (rune) but newline. +.PP +The syntax for a regular expression +.B e0 +is +.IP +.EX +e3: literal | charclass | '.' | '^' | '$' | '(' e0 ')' + +e2: e3 + | e2 REP + +REP: '*' | '+' | '?' + +e1: e2 + | e1 e2 + +e0: e1 + | e0 '|' e1 +.EE +.PP +A +.B literal +is any non-metacharacter, or a metacharacter +(one of +.BR .*+?[]()|\e^$ ), +or the delimiter +preceded by +.LR \e . +.PP +A +.B charclass +is a nonempty string +.I s +bracketed +.BI [ \|s\| ] +(or +.BI [^ s\| ]\fR); +it matches any character in (or not in) +.IR s . +A negated character class never +matches newline. +A substring +.IB a - b\f1, +with +.I a +and +.I b +in ascending +order, stands for the inclusive +range of +characters between +.I a +and +.IR b . +In +.IR s , +the metacharacters +.LR - , +.LR ] , +an initial +.LR ^ , +and the regular expression delimiter +must be preceded by a +.LR \e ; +other metacharacters +have no special meaning and +may appear unescaped. +.PP +A +.L . +matches any character. +.PP +A +.L ^ +matches the beginning of a line; +.L $ +matches the end of the line. +.PP +The +.B REP +operators match zero or more +.RB ( * ), +one or more +.RB ( + ), +zero or one +.RB ( ? ), +instances respectively of the preceding regular expression +.BR e2 . +.PP +A concatenated regular expression, +.BR "e1\|e2" , +matches a match to +.B e1 +followed by a match to +.BR e2 . +.PP +An alternative regular expression, +.BR "e0\||\|e1" , +matches either a match to +.B e0 +or a match to +.BR e1 . +.PP +A match to any part of a regular expression +extends as far as possible without preventing +a match to the remainder of the regular expression. +.SH "SEE ALSO" +.IR awk (1), +.IR ed (1), +.IR grep (1), +.IR sam (1), +.IR sed (1), +.IR regexp (2) diff --git a/sys/man/6/rewrite b/sys/man/6/rewrite new file mode 100755 index 000000000..c54032c32 --- /dev/null +++ b/sys/man/6/rewrite @@ -0,0 +1,154 @@ +.TH REWRITE 6 +.SH NAME +rewrite \- mail rewrite rules +.SH SYNOPSIS +.B /mail/lib/rewrite +.SH DESCRIPTION +.IR Mail (1) +uses rewrite rules to convert mail destinations into +commands used to dispose of the mail. +Each line of the file +.F /mail/lib/rewrite +is a rule. +Blank lines and lines beginning with +.B # +are ignored. +.PP +Each rewriting rule consists of (up to) 4 strings: +.TF pattern +.TP +.I pattern +A regular expression in the style of +.IR regexp (6). +The +.I pattern +is applied to mail destination addresses. +The pattern match is case-insensitive +and must match the entire address. +.TP +.I type +The type of rule; see below. +.TP +.I arg1 +An +.IR ed (1) +style replacement string, with +.BI \e n +standing for the text matched by the +.IR n th +parenthesized subpattern. +.TP +.I arg2 +Another +.IR ed (1) +style replacement string. +.PD +.PP +In each of these fields the substring +.B \es +is replaced by the login id of the +sender and the substring +.B \el +is replaced by the name of the local machine. +.PP +When delivering a message, +.I mail +starts with the first rule and continues down the list until a pattern +matches the destination address. +It then performs one of the following actions depending on the +.I type +of the rule: +.TF alias +.TP +.B >> +Append the mail to the file indicated by expanding +.IR arg1 , +provided that file appears to be a valid mailbox. +.TP +.B | +Pipe the mail through the command formed from concatenating the +expanded +.I arg1 +and +.IR arg2 . +.TP +.B alias +Replace the address by the address(es) specified +by expanding +.I arg1 +and recur. +.TP +.B translate +Replace the address by the address(es) output by the +command formed by expanding +.I arg1 +and recur. +.PD +.PP +.I Mail +expands the addresses recursively until each address has matched a +.B >> +or +.B | +rule or until the recursion depth indicates a rewriting loop +(currently 32). +.PD +.PP +If +.IR mail (1) +is called with more than one address and +several addresses match +.B | +rules and result in the same +expanded +.IR arg1 , +the message is delivered to all those addresses +by a single command, +composed by concatenating the common expanded +.I arg1 +and each expanded +.IR arg2 . +This mail bundling is performed to reduce the number +of times the same message is transmitted across a +network. For example, with the following +rewrite rule +.PP +.EX + ([^!]*\.bell-labs\.com)!(.*) | "/mail/lib/qmail '\es' 'net!\e1'" "'\e2'" +.EE +.PP +if user +.B presotto +runs the command +.PP +.EX + % mail plan9.bell-labs.com!ken plan9.bell-labs.com!rob +.EE +.PP +there will follow only one execution of the command +.PP +.EX + /mail/lib/qmail presotto net!plan9.bell-labs.com ken rob +.EE +.PP +Here +.B /mail/lib/qmail +is an +.IR rc (1) +script used for locally queuing remote mail. +.PP +In the event of an error, the disposition of the mail depends on the name of the +command executing the rewrite. If the command is called +.B mail +and is run by +.BR $user , +the command will print an error and deposit the message in +.BR /mail/box/$user/dead.letter . +If the command is called +.BR rmail , +usually because it was invoked to deliver mail arriving over the network, +the message will be returned to the sender. The returned message will +appear to have been sent by user +.BR postmaster . +.SH "SEE ALSO" +.IR mail (1) diff --git a/sys/man/6/smtpd b/sys/man/6/smtpd new file mode 100755 index 000000000..dcf16fbcc --- /dev/null +++ b/sys/man/6/smtpd @@ -0,0 +1,309 @@ +.TH SMTPD 6 +.SH NAME +smtpd \- SMTP listener configuration +.SH DESCRIPTION +The +SMTP +daemon +of +.IR mail (1) +implements the slave side of the SMTP protocol +to accept incoming mail on TCP port 25. +In general, +.IR smtpd 's +default parameters +are sufficient for internal systems +on protected networks, but external or +gateway systems require additional +security mechanisms. +The files +.BR /mail/lib/smtpd.conf , +containing configuration parameters, +and +.BR /mail/lib/blocked , +containing +banished addresses, provide the means to +exercise these facilities. +.SS Input Format +In both files input lines +consist of a verb followed by one or more +parameters. These tokens are separated by white space or +commas and all characters following a +.B # +are comments. A +.B # +cannot be escaped. Continuation lines are +not supported, but verbs that take multiple parameters +can be restated on many lines and the associated +parameters accumulate into a single set. +All token processing is case-insensitive. +.PP +Many parameters are +.IR addresses , +either numeric IP addresses in CIDR notation +or a +.I "sender address" +in UUCP-style format. +.PP +An IP address in CIDR notation has the form +.PP +.EX + aaa.bbb.ccc.ddd/mask +.EE +.PP +consisting of a four octet IP address, a slash, +and a +.I mask length +specifying the number of significant high-order bits. +The lower the mask length, the larger the +range of addresses covered by the CIDR address; +see RFC 1878 for a discussion of mask lengths. +Missing low-order octets are assumed to be zero. +If a mask length is not given, a mask length of +16, 24, or 32 is assumed for addresses containing +two, three, or four octets, respectively. These +mask lengths select a class B, class C or Class D +address block. Notice that this convention differs +from the standard treatment, where the default mask length +depends on the allocation class of the network +block containing the address. +.PP +.I "Sender addresses" +are specified in UUCP notation as +follows: +.PP +.EX + [domain!]...domain!user +.EE +.PP +It is seldom necessary to specify more than one domain. +When +.I domain +is missing or +.BR * , +the address selects the specified user in all domains. +A +.I domain +of the form +.BI *. domain +selects the domain and all of its sub-domains. +For example, +.B example.com!user +only matches the account +.I user +in domain +.BR example.com , +while +.B *.example.com!user +selects that account in +.B example.com +and all of its sub-domains. +When +.I user +is omitted or +.BR * , +the address selects all users in the specified domain. +Finally, when +.B * +is the last character of the user name it is a wild-card +matching all user names beginning with +.IR user . +This limited pattern matching capability should be used with care. +For safety, the sender addresses +.BR * , +.BR ! , +.BR *! , +.B !* +and +.B *!* +are ignored. +.SS /mail/lib/smtpd.conf +This file contains configuration options +and parameters describing the local domain. +Many of the options can also be specified on the command +line; command line options always override the values in +this file. +Configuration options are: +.PD0 +.TP 10 +.BI defaultdomain " domain" +The name of the local domain; it is appended to addresses +lacking a domain qualification. +This is identical to the +.B -h +command line option. +.TP 10 +.BR norelay \ [ on\f1|\fPoff ] +If +.I on +is specified, relaying is prohibited +from unauthorized networks to external domains. +Authorized networks and domains must be specified +by the +.B ournets +and +.B ourdomains +verbs described below. Setting this option on is equivalent to specifying the +.B -f +command line flag, but the list of +networks and domains can only be specified in +this file. +.TP 10 +.BR verifysenderdom \ [ on\f1|\fPoff ] +When +.IR on , +.I smtpd +verifies that the first domain of the sender's address +exists. The test is cursory; it checks only that +there is a DNS delegation for the domain. +Setting the option on is equivalent to specifying the +.B -r +command line option and +is useful for detecting some unreturnable +messages as well as messages with randomly +generated domain names. +.TP 10 +.BR saveblockedmsg \ [ on\f1|\fPoff ] +When +.IR on , +causes copies of blocked messages to be saved +in subdirectories of +.BR /mail/queue.dump . +Directories are named with the date and file names +are random numbers. +If this option is +.I off +blocked messages are discarded. +Setting this option on is equivalent to specifying the +.B -s +command line option. +.TP 10 +.BR ournets " \fIIP address\fP [, \fIIP address\fP, ..., \fIIP address\fP]" +This option specifies trusted +source networks that are allowed to relay mail to external domains. +These are usually the internal networks of the local domain, but they +can also include friendly +external networks. Addresses +are in CIDR notation. +.TP 10 +.BR ourdomains " \fIdomain\fP [, \fIdomain\fP, ..., \fIdomain\fP]" +This option specifies destination domains that are allowed +to receive relayed mail. These are usually the domains +served by a gateway system. +Domain specifications conform to the format +for sender addresses given above. +.PD +.PP +When the +.B norelay +option is enabled or the +.B -f +command line option given, +relaying is allowed only if the source IP address is in +.B ournets +or the destination domain is specified in +.BR ourdomains . +.SS Blocked Addresses +.I Smtpd +consults +.B /mail/ratify +(see +.IR ratfs (4)) +for a list of banned addresses. +Messages received from these addresses are +rejected with a 5\fIxx\fP-series SMTP error code. +There is no option +to turn blocking on or off; if +.B /mail/ratify +is mounted, +.I smtpd +will use it, even for connections from trusted networks. +.PP +The command line format and address specifications +conform to the notation described above. If the parameters +of the verb is sender addresses in UUCP format, the line +must begin with an +.B * +character; if the parameters are one or more IP addresses, +the +.B * +must precede the verb. Most +verbs cause messages to be rejected; verbs +of this class generally select different error +messages. The remaining verbs specify addresses that +are always accepted, in effect overriding blocked addresses. +The file is processed in order, so an override must +precede its associated blocked address. +Supported verbs are: +.PD0 +.TP 10 +.BR dial " \fIIP address\fP [,..., \fIIP address\fP]" +The parameters are IP addresses associated with +dial-up ports. The rejection message states +that connections from dial-up ports are not accepted. Copies +of messages are never saved. +.TP 10 +.BR block " \fIaddress\fP [, ... \fIaddress\fP]" +Messages from addresses +matching the parameters +are rejected with an error message saying +that spam is not accepted. The message is saved if +the option is enabled. +.TP 10 +.BR relay " \fIaddress\fP [, ... \fIaddress\fP]" +This verb is identical to +.BR block , +but the error message states that +the message is rejected because the sending +system is being used as a spam relay. +.TP +.BR deny " \fIaddress\fP [, ... \fIaddress\fP]" +The +.B deny +command rejects a message when the +sender address matches one of its parameters. +The rejection message asks the sender to +contact +.BR postmaster @ +.I hostdomain +for further information. +This verb is usually used to block +inadvertently abusive traffic, for example, +mail loops and stuck senders. Messages are +never saved. +.TP +.BR allow " \fIaddress\fP [, ... \fIaddress\fP]" +The +.B allow +verb negates the effect of subsequent blocking commands. +It is useful when a large range of addresses contains +a few legitimate addresses, for example, when +a mail server is in a Class C network block +of modem ports. Rather than enumerate the dial ports, it is +easier to block the entire Class C with a +.B dial +command, and precede it with an override for +the address of the mail server. Similarly, +it is possible to block mail from an entire +domain while accepting mail from a few friendly +senders in the domain. +The verb +.B accept +is a synonym for +.BR allow . +.PD +.PP +.IR Scanmail (8) +describes spam detection +software that works well with +the capabilities described here +and +.IR mail (1) +defines additional +.I smtpd +command line arguments applicable +to exposed systems. +.SH "SEE ALSO" +.IR mail (1), +.IR ratfs (4), +.IR scanmail (8) diff --git a/sys/man/6/snap b/sys/man/6/snap new file mode 100755 index 000000000..a7b1432d7 --- /dev/null +++ b/sys/man/6/snap @@ -0,0 +1,98 @@ +.TH SNAP 6 +.SH NAME +snap \- process snapshots +.SH DESCRIPTION +Process snapshots are used to +save a process image for debugging on +another machine or at another time. +They are like old Unix core dumps but +can hold multiple process images and +are smaller. +.PP +The first line of a snapshot begins with the prefix +``process snapshot'' and often contains +other information as well, such as creation time, +user name, system name, cpu type, and kernel type. +This information is intended for humans, not programs. +Programs reading snapshots should only +check that this line begins with the specified prefix. +.PP +Throughout the rest of the snapshot, decimal strings are +always right-justified, blank-padded to at least 11 characters, +and followed by a single space character. +.PP +The rest of the snapshot is one or more records, +each of which begins with a one-line header. +This header is a decimal process id followed by +an identification string, which denotes the type of +data in the record. +.PP +Records of type +.BR fd , +.BR fpregs , +.BR kregs , +.BR noteid , +.BR ns , +.BR proc , +.BR regs , +.BR segment , +and +.BR status +are all formatted as a decimal number +.I n +followed by +.I n +bytes of data. +This data is the contents of the file +of the same name found in +.BR /proc . +.PP +The format of the +.B mem +and +.B text +sections is not as simple. +These sections contain one or more page descriptions. +Each describes a one kilobyte page of data. +If the section is not a multiple of a kilobyte in size, +the last page will be shorter. +Each description begins with a one-byte +flag. +If the flag is +.BR r , +then it is followed by +a page of binary data. +If the flag is +.BR z , +then the data is understood to be zeros, +and is omitted. +If the flag is +.B m +or +.BR t , +then it is followed by two decimal strings +.I p +and +.IR o , +indicating that this page is the same +as the page at offset +.I o +of the memory or text +segment for process +.IR p . +This data must have been previously +described in the snapshot, and the offset +must be a multiple of a kilobyte. +.PP +It is not guaranteed that any of the sections +described above be in a process snapshot, +although the snapshot quickly becomes useless when +too much is missing. +.PP +Memory and text images may be incomplete. +The memory or text file for a given process +may be split across multiple disjoint sections +in the snapshot. +.SH SEE ALSO +.IR proc (3), +.IR snap (4). diff --git a/sys/man/6/style b/sys/man/6/style new file mode 100755 index 000000000..b0ae34d4a --- /dev/null +++ b/sys/man/6/style @@ -0,0 +1,109 @@ +.TH STYLE 6 +.SH NAME +style \- Plan 9 coding conventions for C +.SH DESCRIPTION +Plan 9 C code has its own conventions. +You would do well to follow them. +Here are a few: +.IP • 3 +don't use +.L // +comments; some old Plan 9 code does, but we're converting it as we touch it. +We do sometimes use +.L // +to comment-out a few lines of code. +.IP • +avoid +.BR goto s. +.IP • +no tabs expanded to spaces. +.IP • +surround a binary operator (particular a low precedence one) with spaces; +don't try to write the most compact code possible +but rather the most readable. +.IP • +parenthesize expressions involving arithmetic and bit-wise operators; +otherwise don't parenthesize heavily (e.g., as in Pascal). +.IP • +no white space before opening braces. +.IP • +no white space after the keywords +.LR if , +.LR for , +.LR while , +etc. +.IP • +no braces around single-line blocks (e.g., +.LR if , +.LR for , +and +.L while +bodies). +.IP • +integer-valued functions return -1 on error, 0 or positive on success. +.IP • +functions that return errors should set +.IR errstr (2). +.IP • +variable and function names are all lowercase, with no underscores. +.IP • +.B enum +or +.BR #define d +constants should be Uppercase (or UPPERCASE). +.IP • +.B struct +tags are Uppercase, with matching +.BR typedef s. +.IP • +automatic variables (local variables inside a function) are +never initialized at declaration. +.IP • +follow the standard idioms: use +.L "x < 0" +not +.LR "0 > x" , +etc. +.IP • +don't write +.L !strcmp +(nor +.LR !memcmp , +etc.) +nor +.LR "if(memcmp(a, b, c))" ; +always explicitly compare the result of string or memory +comparison with zero using a relational operator. +.PP +Ultimately, the goal is to write code that fits in with the other code +around it and the system as a whole. If the file you are editing +already deviates from these guidelines, do what it does. After you +edit a file, a reader should not be able to tell just from coding +style which parts you worked on. +.SS COMMENTS +If your code is readable, you shouldn't need many comments. A line or +two comment above a function explaining what it does is always welcome. +.PP +Comment any code you find yourself wondering about for more than 2 +seconds, even if it's to say that you don't understand what's going +on. Explain why. +.PP +Don't use commenting as an excuse for writing confusing code. Rewrite +the code to make it clear. +.SS EFFICIENCY +Do the simple thing. Don't optimize unless you've measured the code +and it is too slow. Fix the data structures and the algorithms +instead of going for little 5% tunings. +.SH SEE ALSO +``Notes on Programming in C'', Rob Pike, +.br +.B http://www.literateprogramming.com/pikestyle.pdf +.SH BUGS +Some programs use very different styles, for example, +.IR rc . +.PP +Some programs and programmers diverge from the above rules due to +habits formed long before these rules. +Notably, some programs have a single space after a keyword and +before an opening brace, +and some initialize automatic variables at declaration. diff --git a/sys/man/6/thumbprint b/sys/man/6/thumbprint new file mode 100755 index 000000000..63be911af --- /dev/null +++ b/sys/man/6/thumbprint @@ -0,0 +1,41 @@ +.TH THUMBPRINT 6 +.SH NAME +thumbprint \- public key thumbprints +.SH DESCRIPTION +.PP +Applications in Plan 9 that use public keys for authentication, +for example by calling +.B tlsClient +and +.B okThumbprint +(see +.IR pushtls (2)), +check the remote side's public key by comparing against +thumbprints from a trusted list. +The list is maintained by people who set local policies +about which servers can be trusted for which applications, +thereby playing the role taken by certificate authorities +in PKI-based systems. +By convention, these lists are stored as files in +.B /sys/lib/tls/ +and protected by normal file system permissions. +.PP +Such a thumbprint file comprises lines made up of +attribute/value pairs of the form +.IB attr = value +or +.IR attr . +The first attribute must be +.B x509 +and the second must be +.BI sha1= {hex checksum of binary certificate}. +All other attributes are treated as comments. +The file may also contain lines of the form +.BI #include file +.PP +For example, a web server might have thumbprint +.EX +x509 sha1=8fe472d31b360a8303cd29f92bd734813cbd923c cn=*.cs.bell-labs.com +.EE +.SH "SEE ALSO" +.IR pushtls (2) diff --git a/sys/man/6/users b/sys/man/6/users new file mode 100755 index 000000000..6db15c98a --- /dev/null +++ b/sys/man/6/users @@ -0,0 +1,75 @@ +.TH USERS 6 +.SH NAME +users \- file server user list format +.SH DESCRIPTION +The permanent file servers each maintain a private list of users +and groups, in +.B /adm/users +by convention. +Each line in the file has the format +.IP +.IB id : name : leader :\fImembers\fP +.PP +where +.I name +and +.I leader +are printable strings excluding the characters +.LR ? , +.LR = , +.LR + , +.LR - , +.LR / , +and +.LR : , +and +.I members +is a comma-separated list of such strings. +Such a line defines a user and a group with the given +.IR name ; +the group has a group leader given by +.I leader +and group members given by the user names in +.IR members . +The +.I leader +field may be empty, +in which case any group member is a group leader. +The +.I members +field may be empty. +.PP +Lines beginning with +.L # +are ignored. +.PP +The +.I id +in a line is an identifier used in the on-disk structures maintained +by a file server; there should be no duplicate +.IR id s +in the file. +In +.IR fossil (4), +.IR id s +are arbitrary text strings, typically the same as +.IR name . +In older Plan 9 file servers, +.IR id s +are small decimal numbers. +In those, +a negative +.I id +is special: a user with a negative +.I id +cannot attach to the file server. +The file +.B /adm/users +itself is owned by user +.I adm +and write protected to others, +so it can only be changed via console commands. +.SH "SEE ALSO" +.IR intro (5), +.IR stat (5), +.IR fossilcons (8) diff --git a/sys/man/6/utf b/sys/man/6/utf new file mode 100755 index 000000000..92f7c9534 --- /dev/null +++ b/sys/man/6/utf @@ -0,0 +1,98 @@ +.TH UTF 6 +.SH NAME +UTF, Unicode, ASCII, rune \- character set and format +.SH DESCRIPTION +The Plan 9 character set and representation are +based on the Unicode Standard and on the ISO multibyte +.SM UTF-8 +encoding (Universal Character +Set Transformation Format, 8 bits wide). +The Unicode Standard represents its characters in 16 +bits; +.SM UTF-8 +represents such +values in an 8-bit byte stream. +Throughout this manual, +.SM UTF-8 +is shortened to +.SM UTF. +.PP +In Plan 9, a +.I rune +is a 16-bit quantity representing a Unicode character. +Internally, programs may store characters as runes. +However, any external manifestation of textual information, +in files or at the interface between programs, uses a +machine-independent, byte-stream encoding called +.SM UTF. +.PP +.SM UTF +is designed so the 7-bit +.SM ASCII +set (values hexadecimal 00 to 7F), +appear only as themselves +in the encoding. +Runes with values above 7F appear as sequences of two or more +bytes with values only from 80 to FF. +.PP +The +.SM UTF +encoding of the Unicode Standard is backward compatible with +.SM ASCII\c +: +programs presented only with +.SM ASCII +work on Plan 9 +even if not written to deal with +.SM UTF, +as do +programs that deal with uninterpreted byte streams. +However, programs that perform semantic processing on +.SM ASCII +graphic +characters must convert from +.SM UTF +to runes +in order to work properly with non-\c +.SM ASCII +input. +See +.IR rune (2). +.PP +Letting numbers be binary, +a rune x is converted to a multibyte +.SM UTF +sequence +as follows: +.PP +01. x in [00000000.0bbbbbbb] → 0bbbbbbb +.br +10. x in [00000bbb.bbbbbbbb] → 110bbbbb, 10bbbbbb +.br +11. x in [bbbbbbbb.bbbbbbbb] → 1110bbbb, 10bbbbbb, 10bbbbbb +.br +.PP +Conversion 01 provides a one-byte sequence that spans the +.SM ASCII +character set in a compatible way. +Conversions 10 and 11 represent higher-valued characters +as sequences of two or three bytes with the high bit set. +Plan 9 does not support the 4, 5, and 6 byte sequences proposed by X-Open. +When there are multiple ways to encode a value, for example rune 0, +the shortest encoding is used. +.PP +In the inverse mapping, +any sequence except those described above +is incorrect and is converted to rune hexadecimal FFFD. +.SH FILES +.TF "/lib/unicode " +.TP +.B /lib/unicode +table of characters and descriptions, suitable for +.IR look (1). +.SH "SEE ALSO" +.IR ascii (1), +.IR tcs (1), +.IR rune (2), +.IR keyboard (6), +.IR "The Unicode Standard" . diff --git a/sys/man/6/venti b/sys/man/6/venti new file mode 100755 index 000000000..92296d506 --- /dev/null +++ b/sys/man/6/venti @@ -0,0 +1,451 @@ +.TH VENTI 6 +.SH NAME +venti \- archival storage server +.SH DESCRIPTION +Venti is a block storage server intended for archival data. +In a Venti server, the SHA1 hash of a block's contents acts +as the block identifier for read and write operations. +This approach enforces a write-once policy, preventing +accidental or malicious destruction of data. In addition, +duplicate copies of a block are coalesced, reducing the +consumption of storage and simplifying the implementation +of clients. +.PP +This manual page documents the basic concepts of +block storage using Venti as well as the Venti network protocol. +.PP +.IR Venti (1) +documents some simple clients. +.IR Vac (1) +and +.IR vacfs (4) +are more complex clients. +.PP +.IR Venti (2) +describes a C library interface for accessing +Venti servers and manipulating Venti data structures. +.PP +.IR Venti (8) +describes the programs used to run a Venti server. +.PP +.SS "Scores +The SHA1 hash that identifies a block is called its +.IR score . +The score of the zero-length block is called the +.IR "zero score" . +.PP +Scores may have an optional +.IB label : +prefix, typically used to +describe the format of the data. +For example, +.IR vac (1) +uses a +.B vac: +prefix, while +.IR vbackup (8) +uses prefixes corresponding to the file system +types: +.BR ext2: , +.BR ffs: , +and so on. +.SS "Files and Directories +Venti accepts blocks up to 56 kilobytes in size. +By convention, Venti clients use hash trees of blocks to +represent arbitrary-size data +.IR files . +The data to be stored is split into fixed-size +blocks and written to the server, producing a list +of scores. +The resulting list of scores is split into fixed-size pointer +blocks (using only an integral number of scores per block) +and written to the server, producing a smaller list +of scores. +The process continues, eventually ending with the +score for the hash tree's top-most block. +Each file stored this way is summarized by +a +.B VtEntry +structure recording the top-most score, the depth +of the tree, the data block size, and the pointer block size. +One or more +.B VtEntry +structures can be concatenated +and stored as a special file called a +.IR directory . +In this +manner, arbitrary trees of files can be constructed +and stored. +.PP +Scores passed between programs conventionally refer +to +.B VtRoot +blocks, which contain descriptive information +as well as the score of a directory block containing a small number +of directory entries. +.PP +Conventionally, programs do not mix data and directory entries +in the same file. Instead, they keep two separate files, one with +directory entries and one with metadata referencing those +entries by position. +Keeping this parallel representation is a minor annoyance +but makes it possible for general programs like +.I venti/copy +(see +.IR venti (1)) +to traverse the block tree without knowing the specific details +of any particular program's data. +.SS "Block Types +To allow programs to traverse these structures without +needing to understand their higher-level meanings, +Venti tags each block with a type. The types are: +.PP +.nf +.ft L + VtDataType 000 \f1data\fL + VtDataType+1 001 \fRscores of \fPVtDataType\fR blocks\fL + VtDataType+2 002 \fRscores of \fPVtDataType+1\fR blocks\fL + \fR\&...\fL + VtDirType 010 VtEntry\fR structures\fL + VtDirType+1 011 \fRscores of \fLVtDirType\fR blocks\fL + VtDirType+2 012 \fRscores of \fLVtDirType+1\fR blocks\fL + \fR\&...\fL + VtRootType 020 VtRoot\fR structure\fL +.fi +.PP +The octal numbers listed are the type numbers used +by the commands below. +(For historical reasons, the type numbers used on +disk and on the wire are different from the above. +They do not distinguish +.BI VtDataType+ n +blocks from +.BI VtDirType+ n +blocks.) +.SS "Zero Truncation +To avoid storing the same short data blocks padded with +differing numbers of zeros, Venti clients working with fixed-size +blocks conventionally +`zero truncate' the blocks before writing them to the server. +For example, if a 1024-byte data block contains the +11-byte string +.RB ` hello " " world ' +followed by 1013 zero bytes, +a client would store only the 11-byte block. +When the client later read the block from the server, +it would append zero bytes to the end as necessary to +reach the expected size. +.PP +When truncating pointer blocks +.RB ( VtDataType+ \fIn +and +.BI VtDirType+ n +blocks), +trailing zero scores are removed +instead of trailing zero bytes. +.PP +Because of the truncation convention, +any file consisting entirely of zero bytes, +no matter what its length, will be represented by the zero score: +the data blocks contain all zeros and are thus truncated +to the empty block, and the pointer blocks contain all zero scores +and are thus also truncated to the empty block, +and so on up the hash tree. +.SS Network Protocol +A Venti session begins when a +.I client +connects to the network address served by a Venti +.IR server ; +the conventional address is +.BI tcp! server !venti +(the +.B venti +port is 17034). +Both client and server begin by sending a version +string of the form +.BI venti- versions - comment \en \fR. +The +.I versions +field is a list of acceptable versions separated by +colons. +The protocol described here is version +.BR 02 . +The client is responsible for choosing a common +version and sending it in the +.B VtThello +message, described below. +.PP +After the initial version exchange, the client transmits +.I requests +.RI ( T-messages ) +to the server, which subsequently returns +.I replies +.RI ( R-messages ) +to the client. +The combined act of transmitting (receiving) a request +of a particular type, and receiving (transmitting) its reply +is called a +.I transaction +of that type. +.PP +Each message consists of a sequence of bytes. +Two-byte fields hold unsigned integers represented +in big-endian order (most significant byte first). +Data items of variable lengths are represented by +a one-byte field specifying a count, +.IR n , +followed by +.I n +bytes of data. +Text strings are represented similarly, +using a two-byte count with +the text itself stored as a UTF-encoded sequence +of Unicode characters (see +.IR utf (6)). +Text strings are not +.SM NUL\c +-terminated: +.I n +counts the bytes of UTF data, which include no final +zero byte. +The +.SM NUL +character is illegal in text strings in the Venti protocol. +The maximum string length in Venti is 1024 bytes. +.PP +Each Venti message begins with a two-byte size field +specifying the length in bytes of the message, +not including the length field itself. +The next byte is the message type, one of the constants +in the enumeration in the include file +.BR <venti.h> . +The next byte is an identifying +.IR tag , +used to match responses to requests. +The remaining bytes are parameters of different sizes. +In the message descriptions, the number of bytes in a field +is given in brackets after the field name. +The notation +.IR parameter [ n ] +where +.I n +is not a constant represents a variable-length parameter: +.IR n [1] +followed by +.I n +bytes of data forming the +.IR parameter . +The notation +.IR string [ s ] +(using a literal +.I s +character) +is shorthand for +.IR s [2] +followed by +.I s +bytes of UTF-8 text. +The notation +.IR parameter [] +where +.I parameter +is the last field in the message represents a +variable-length field that comprises all remaining +bytes in the message. +.PP +All Venti RPC messages are prefixed with a field +.IR size [2] +giving the length of the message that follows +(not including the +.I size +field itself). +The message bodies are: +.ta \w'\fLVtTgoodbye 'u +.IP +.ne 2v +.B VtThello +.IR tag [1] +.IR version [ s ] +.IR uid [ s ] +.IR strength [1] +.IR crypto [ n ] +.IR codec [ n ] +.br +.B VtRhello +.IR tag [1] +.IR sid [ s ] +.IR rcrypto [1] +.IR rcodec [1] +.IP +.ne 2v +.B VtTping +.IR tag [1] +.br +.B VtRping +.IR tag [1] +.IP +.ne 2v +.B VtTread +.IR tag [1] +.IR score [20] +.IR type [1] +.IR pad [1] +.IR count [2] +.br +.B VtRead +.IR tag [1] +.IR data [] +.IP +.ne 2v +.B VtTwrite +.IR tag [1] +.IR type [1] +.IR pad [3] +.IR data [] +.br +.B VtRwrite +.IR tag [1] +.IR score [20] +.IP +.ne 2v +.B VtTsync +.IR tag [1] +.br +.B VtRsync +.IR tag [1] +.IP +.ne 2v +.B VtRerror +.IR tag [1] +.IR error [ s ] +.IP +.ne 2v +.B VtTgoodbye +.IR tag [1] +.PP +Each T-message has a one-byte +.I tag +field, chosen and used by the client to identify the message. +The server will echo the request's +.I tag +field in the reply. +Clients should arrange that no two outstanding +messages have the same tag field so that responses +can be distinguished. +.PP +The type of an R-message will either be one greater than +the type of the corresponding T-message or +.BR Rerror , +indicating that the request failed. +In the latter case, the +.I error +field contains a string describing the reason for failure. +.PP +Venti connections must begin with a +.B hello +transaction. +The +.B VtThello +message contains the protocol +.I version +that the client has chosen to use. +The fields +.IR strength , +.IR crypto , +and +.IR codec +could be used to add authentication, encryption, +and compression to the Venti session +but are currently ignored. +The +.IR rcrypto , +and +.I rcodec +fields in the +.B VtRhello +response are similarly ignored. +The +.IR uid +and +.IR sid +fields are intended to be the identity +of the client and server but, given the lack of +authentication, should be treated only as advisory. +The initial +.B hello +should be the only +.B hello +transaction during the session. +.PP +The +.B ping +message has no effect and +is used mainly for debugging. +Servers should respond immediately to pings. +.PP +The +.B read +message requests a block with the given +.I score +and +.IR type . +Use +.I vttodisktype +and +.I vtfromdisktype +(see +.IR venti (2)) +to convert a block type enumeration value +.RB ( VtDataType , +etc.) +to the +.I type +used on disk and in the protocol. +The +.I count +field specifies the maximum expected size +of the block. +The +.I data +in the reply is the block's contents. +.PP +The +.B write +message writes a new block of the given +.I type +with contents +.I data +to the server. +The response includes the +.I score +to use to read the block, +which should be the SHA1 hash of +.IR data . +.PP +The Venti server may buffer written blocks in memory, +waiting until after responding to the +.B write +message before writing them to +permanent storage. +The server will delay the response to a +.B sync +message until after all blocks in earlier +.B write +messages have been written to permanent storage. +.PP +The +.B goodbye +message ends a session. There is no +.BR VtRgoodbye : +upon receiving the +.BR VtTgoodbye +message, the server terminates up the connection. +.SH SEE ALSO +.IR venti (1), +.IR venti (2), +.IR venti (8) +.br +Sean Quinlan and Sean Dorward, +``Venti: a new approach to archival storage'', +.I "Usenix Conference on File and Storage Technologies" , +2002. diff --git a/sys/man/6/venti.conf b/sys/man/6/venti.conf new file mode 100755 index 000000000..7d5cdd3f9 --- /dev/null +++ b/sys/man/6/venti.conf @@ -0,0 +1,88 @@ +.TH VENTI.CONF 6 +.SH NAME +venti.conf \- a venti configuration file +.SH DESCRIPTION +A venti configuration file enumerates the various index sections and +arenas that constitute a venti system. +The components are indicated by the name of the file, typically +a disk partition, in which they reside. The configuration +file is the only location that file names are used. Internally, +venti uses the names assigned when the components were formatted +with +.I fmtarenas +or +.I fmtisect +(see +.IR venti-fmt (8)). +In particular, by changing the configuration a +component can be copied to a different file. +.PP +The configuration file consists of lines in the form described below. +Lines starting with +.B # +are comments. +.TP +.BI index " name +Names the index for the system. +.TP +.BI arenas " file +.I File +contains a collection of arenas, formatted using +.IR fmtarenas . +.TP +.BI isect " file +.I File +contains an index section, formatted using +.IR fmtisect . +.PP +After formatting a venti system using +.IR fmtindex , +the order of arenas and index sections should not be changed. +Additional arenas can be appended to the configuration. +.PP +The configuration file optionally holds configuration parameters +for the venti server itself. +These are: +.TP +.BI mem " cachesize +.TP +.BI bcmem " blockcachesize +.TP +.BI icmem " indexcachesize +.TP +.BI addr " ventiaddress +.TP +.BI httpaddr " httpaddress +.TP +.B queuewrites +.PD +See +.IR venti (8) +for descriptions of these variables. +.SH EXAMPLE +.EX +# a sample venti configuration file +# +# formatted with +# venti/fmtarenas arena. /tmp/disks/arenas +# venti/fmtisect isect0 /tmp/disks/isect0 +# venti/fmtisect isect1 /tmp/disks/isect1 +# venti/fmtindex venti.conf +# +# server is started with +# venti/venti + +# the name of the index +index main + +# the index sections +isect /tmp/disks/isect0 +isect /tmp/disks/isect1 + +# the arenas +arenas /tmp/disks/arenas +.EE +.SH "SEE ALSO" +.IR fs (3), +.IR venti (8), +.IR venti-fmt (8) diff --git a/sys/man/6/vgadb b/sys/man/6/vgadb new file mode 100755 index 000000000..a63357680 --- /dev/null +++ b/sys/man/6/vgadb @@ -0,0 +1,486 @@ +.TH VGADB 6 +.SH NAME +vgadb \- VGA controller and monitor database +.SH DESCRIPTION +.PP +The VGA database, +.BR /lib/vgadb , +consists of two parts, +the first describing how to identify and program a VGA controller +and the second describing the timing parameters for known +monitors to be loaded into a VGA controller to give a particular +resolution and refresh rate. +Conventionally, at system boot, the program +.B aux/vga +(see +.IR vga (8)) +uses the monitor type in +.BR /env/monitor , +the display resolution in +.BR /env/vgasize , +and the VGA controller information in the database to +find a matching monitor entry and initialize the VGA controller accordingly. +.PP +The file comprises multi-line entries made up of +attribute/value pairs of the form +.IB attr = value +or sometimes just +.IR attr . +Each line starting without white space starts a new entry. +Lines starting with +.B # +are comments. +.PP +The first part of the database, the VGA controller identification and +programming information, +consists of a number of entries with attribute +.B ctlr +and no value. +Within one of these entries the following attributes are +meaningful: +.TF 0xC0000 +.TP +.I nnnnn +an offset into the VGA BIOS area. +The value is a string expected to be found there that will +identify the controller. +For example, +.B 0xC0068="#9GXE64 Pro" +would identify a #9GXEpro VGA controller if the string +.B "#9GXE64 Pro" +was found in the BIOS at address 0xC0068. +There may be more than one identifier attribute per controller. +If a match cannot be found, the first few bytes of the BIOS +are printed to help identify the card and create a controller +entry. +.TP +.IB nnnnn - mmmmm +A range of the VGA BIOS area. +The value is a string as above, but the entire range +is searched for that string. +The string must begin at or after +.I nnnnn +and not contain any characters at or after +.IR mmmmm . +For example, +.B 0xC0000-0xC0200="MACH64LP" +identifies a Mach 64 controller with the +string +.B MACH64LP +occurring anywhere in the first 512 bytes of BIOS memory. +.TP +.B ctlr +VGA controller chip type. +This must match one of the VGA controller types +known to +.B /dev/vgactl +(see +.IR vga (3)) +and internally to +.BR aux/vga . +Currently, +.BR ark2000pv , +.BR clgd542x , +.BR ct65540 , +.BR ct65545 , +.BR cyber938x , +.BR et4000 , +.BR hiqvideo , +.BR ibm8514 , +.BR mach32 , +.BR mach64 , +.BR mach64xx , +.BR mga2164w , +.BR neomagic , +.BR s3801 , +.BR s3805 , +.BR s3928 , +.BR t2r4 , +.BR trio64 , +.BR virge , +.BR vision864 , +.BR vision964 , +.BR vision968 , +and +.B w30c516 +are recognized. +.TP +.B ramdac +RAMDAC controller type. +This must match one of the types +known internally to +.BR aux/vga . +Currently +.BR att20c490 , +.BR att20c491 , +.BR att20c492 , +.BR att21c498 , +.BR bt485 , +.BR rgb524mn , +.BR sc15025 , +.BR stg1702 , +.BR tvp3020 , +.BR tvp3025 , +and +.B tvp3026 +are recognized. +.TP +.B clock +clock generator type. +This must match one of the types +known internally to +.BR aux/vga . +Currently +.BR ch9294 , +.BR icd2061a , +.BR ics2494 , +.BR ics2494a , +.BR s3clock , +.BR tvp3025clock , +and +.B tvp3026clock +are recognized. +.TP +.B hwgc +hardware graphics cursor type. +This must match one of the types +known to +.B /dev/vgactl +and internally to +.BR aux/vga . +Currently +.BR ark200pvhwgc , +.BR bt485hwgc , +.BR clgd542xhwgc , +.BR clgd546xhwgc , +.BR ct65545hwgc , +.BR cyber938xhwgc , +.BR hiqvideohwgc , +.BR mach64xxhwgc , +.BR mga2164whwgc , +.BR neomagichwgc , +.BR rgb524hwgc , +.BR s3hwgc , +.BR t2r4hwgc , +.BR tvp3020hwgc , +and +.B tvp3026hwgc +are recognized. +.TP +.B membw +Memory bandwidth in megabytes per second. +.I Vga +chooses the highest refresh rate possible within the constraints +of the monitor (explained below) and the +card's memory bandwidth. +.TP +.B linear +Whether the card supports a large (>64kb) linear memory +window. The value is either +.B 1 +or +.B 0 +(equivalent to unspecified). +The current kernel graphics subsystem +requires a linear window; entries without +.B linear=1 +are of historic value only. +.TP +.B link +This must match one of the types +known internally to +.BR aux/vga . +Currently +.B vga +and +.B ibm8514 +are recognized. +The type +.B vga +handles generic VGA functions and should almost always be included. +The type +.B Ibm8514 +handles basic graphics accelerator initialization on controllers +such as the early S3 family of GUI chips. +.PD +.PP +The +.BR clock , +.BR ctlr , +.BR link , +and +.B ramdac +values can all take an extension following a +.B '-' +that can be used as a speed-grade +or subtype; matching is done without the extension. +For example, +.B ramdac=stg1702-135 +indicates the STG1702 RAMDAC has a maximum clock frequency of 135MHz, +and +.B clock=ics2494a-324 +indicates that the frequency table numbered +324 +should be used for the ICS2494A clock generator. +.PP +The functions internal to +.B aux/vga +corresponding to the +.BR clock , +.BR ctlr , +.BR link , +and +.B ramdac +values will be called in the order given for initialization. +Sometimes the clock should be set before the RAMDAC is initialized, +for example, depending on the components used. +In general, +.BR link=vga +will always be first and, +if appropriate, +.BR link=ibm8514 +will be last. +.PP +The entries in the second part of +.B /lib/vgadb +have as attribute the name of a monitor type +and the value is conventionally a resolution in the form +.IB X x Y\f1, +where +.I X +and +.I Y +are numbers representing width and height in pixels. +The monitor type (i.e. entry) +.B include +has special properties, described below and shown in the examples. +The remainder of the entry contains timing information for +the desired resolution. +Within one of these entries the following attributes are +meaningful: +.TF interlace +.TP +.B clock +the video dot-clock frequency in MHz required for this resolution. +The value 25.175 is known internally to +.IR vga (8) +as the baseline VGA clock rate. +.B defaultclock +the default video dot-clock frequency in MHz used +for this resolution when no +memory bandwidth is specified for the card +or when +.I vga +cannot determine the maximum clock frequency of the card. +.TP +.B shb +start horizontal blanking, in character clocks. +.TP +.B ehb +end horizontal blanking, in character clocks. +.TP +.B ht +horizontal total, in character clocks. +.TP +.B vrs +vertical refresh start, in character clocks. +.TP +.B vre +vertical refresh end, in character clocks. +.TP +.B vt +vertical total, in character clocks. +.TP +.B hsync +horizontal sync polarity. +Value must be +.B + +or +.BR - . +.TP +.B vsync +vertical sync polarity. +Value must be +.B + +or +.BR - . +.TP +.B interlace +interlaced mode. +Only value +.B v +is recognized. +.TP +.B alias +continue, replacing the +.B alias +line by the contents of the entry whose attribute is given as +.IR value . +.TP +.B include +continue, replacing this +.B include +line by the contents of the previously defined +.B include +monitor type with matching +.IR value . +(See the examples.) +Any non-zero attributes already set will not be overwritten. +This is used to save duplication of timing information. +Note that +.I value +is not parsed, it is only used as a string +to identify the previous +.BI include= value +monitor type entry. +.PD +.PP +The values given for +.BR shb , +.BR ehb , +.BR ht , +.BR vrs , +.BR vre , +.BR vt , +.BR hsync , +and +.B vsync +are beyond the +scope of this manual page. +See the book by +Ferraro +for details. +.SH EXAMPLES +Basic +.B ctlr +entry for a laptop with a Chips and Technology 65550 +controller: +.EX +ctlr # NEC Versa 6030X/6200MX + 0xC0090="CHIPS 65550 PCI & VL Accelerated VGA BIOS" + link=vga + ctlr=hiqvideo linear=1 + hwgc=hiqvideohwgc +.EE +A more complex entry. Note the extensions on the +.BR clock , +.BR ctlr , +and +.B ramdac +attributes. The order here is important: the RAMDAC clock input must be +initialized before the RAMDAC itself. The clock frequency is selected by +the +.B ET4000 +chip. +.EX +ctlr # Hercules Dynamite Power + 0xC0076="Tseng Laboratories, Inc. 03/04/94 V8.00N" + link=vga + clock=ics2494a-324 + ctlr=et4000-w32p + ramdac=stg1702-135 +.EE +Monitor entry for type +.B vga +(the default monitor type used by +.IR vga (8)) +and resolution 640x480x[18]. +.EX +include = 640x480@60Hz # 60Hz, 31.5KHz + clock=25.175 + shb=664 ehb=760 ht=800 + vrs=491 vre=493 vt=525 + +vga = 640x480 # 60Hz, 31.5KHz + include=640x480@60Hz +.EE +Entries for multisync monitors with video bandwidth up to 65MHz. +.EX +# +# Multisync monitors with video bandwidth up to 65MHz. +# +multisync65 = 1024x768 # 60Hz, 48.4KHz + include=1024x768@60Hz +multisync65 = 1024x768i # 87Hz, 35.5KHz (interlaced) + include=1024x768i@87Hz +multisync65 + alias=vga +.EE +Note how this builds on the existing +.B vga +entries. +.SH FILES +.TP +.B /lib/vgadb +.SH "SEE ALSO" +.IR ndb (2), +.IR vga (3), +.IR ndb (6), +.IR 9load (8), +.IR vga (8) +.br +Richard E. Ferraro, +.I +Programming Guide to the EGA, VGA and Super VGA Cards, +Third Edition +.SH BUGS +The database should provide a way +to use the PCI bus +as well as BIOS memory to identify cards. +.SH "ADDING A NEW MONITOR" +Adding a new monitor is usually fairly straightforward, as most modern monitors +are multisync and the only interesting parameter is the +maximum video bandwidth. +Once the timing parameters are worked out for a particular maximum +video bandwidth as in the example above, an entry for a new monitor +with that limit is simply +.EX +# +# Sony CPD-1304 +# Horizontal timing: +# Allowable frequency range: 28-50KHz +# Vertical timing: +# Allowable frequency range: 50-87Hz +# +cpd-1304 + alias=multisync65 +.EE +Even this is not necessary, as the monitor type could simply be +given as +.BR multisync65 . +.SH "ADDING A NEW VGA CONTROLLER" +While the use of this database formalizes the steps needed to +program a VGA controller, +unless you are lucky and all the important components on +a new VGA controller card are interconnected in the same way as an +existing entry, adding a new entry requires adding new internal +types to +.IR vga (8). +Fortunately, the unit of variety +has, for the most part, shifted from +individual components to entire +video chipsets. +Thus in lucky cases all that is necessary +is the addition of another +.B 0xNNNNN= +line to the entry for the controller. +This is particularly true in the case +of the ATI Mach 64 and the S3 Virge. +.PP +If you need to actually add support +for a controller with a different chipset, +you will need the data sheets for the VGA controller +as well as any RAMDAC or clock generator +(these are commonly integrated into the controller). +You will also need to know how these components interact. +For example, a common combination is an S3 86C928 VGA chip with +an ICD2061A clock generator. The ICD2061A is usually loaded by clocking +a serial bit-stream out of one of the 86C928 registers. +Similarly, the RAMDAC may have an internal clock-doubler and/or +pixel-multiplexing modes, in which case both the clock generator and +VGA chip must be programmed accordingly. +Hardware acceleration for rectangle fills +and block copies is provided in the kernel; +writing code to handle this is necessary +to achieve reasonable performance at high +pixel depths. |