diff options
Diffstat (limited to 'man/6')
| -rw-r--r-- | man/6/0intro | 7 | ||||
| -rw-r--r-- | man/6/INDEX | 29 | ||||
| -rw-r--r-- | man/6/attrdb | 101 | ||||
| -rw-r--r-- | man/6/audio | 79 | ||||
| -rw-r--r-- | man/6/auth | 74 | ||||
| -rw-r--r-- | man/6/colour | 187 | ||||
| -rw-r--r-- | man/6/dis | 487 | ||||
| -rw-r--r-- | man/6/font | 102 | ||||
| -rw-r--r-- | man/6/image | 178 | ||||
| -rw-r--r-- | man/6/keyboard | 170 | ||||
| -rw-r--r-- | man/6/keys | 52 | ||||
| -rw-r--r-- | man/6/keytext | 124 | ||||
| -rw-r--r-- | man/6/login | 109 | ||||
| -rw-r--r-- | man/6/man | 248 | ||||
| -rw-r--r-- | man/6/namespace | 162 | ||||
| -rw-r--r-- | man/6/ndb | 219 | ||||
| -rw-r--r-- | man/6/plumbing | 163 | ||||
| -rw-r--r-- | man/6/proto | 153 | ||||
| -rw-r--r-- | man/6/regexp | 126 | ||||
| -rw-r--r-- | man/6/sbl | 385 | ||||
| -rw-r--r-- | man/6/scancode | 37 | ||||
| -rw-r--r-- | man/6/sexprs | 236 | ||||
| -rw-r--r-- | man/6/translate | 55 | ||||
| -rw-r--r-- | man/6/ubfa | 129 | ||||
| -rw-r--r-- | man/6/users | 73 | ||||
| -rw-r--r-- | man/6/utf | 84 |
26 files changed, 3769 insertions, 0 deletions
diff --git a/man/6/0intro b/man/6/0intro new file mode 100644 index 00000000..28d23789 --- /dev/null +++ b/man/6/0intro @@ -0,0 +1,7 @@ +.TH INTRO 6 +.SH NAME +intro \- introduction to file formats +.SH DESCRIPTION +This section describes Inferno file formats that are meant to be public +(as opposed to formats that are for a program's internal use). +It also describes a few system conventions. diff --git a/man/6/INDEX b/man/6/INDEX new file mode 100644 index 00000000..8627fab0 --- /dev/null +++ b/man/6/INDEX @@ -0,0 +1,29 @@ +intro 0intro +attrdb attrdb +audio audio +auth auth +colour colour +dis dis +font font +subfont font +image image +keyboard keyboard +keys keys +keytext keytext +login login +man man +namespace namespace +ndb ndb +plumbing plumbing +proto proto +regex regexp +regexp regexp +sbl sbl +scancode scancode +sexprs sexprs +translate translate +ubfa ubfa +users users +ascii utf +unicode utf +utf utf diff --git a/man/6/attrdb b/man/6/attrdb new file mode 100644 index 00000000..d4333de2 --- /dev/null +++ b/man/6/attrdb @@ -0,0 +1,101 @@ +.TH ATTRDB 6 +.SH NAME +attrdb \- data base of attribute-value pairs +.SH DESCRIPTION +An attribute data base is formed from one or more text files, +each containing groups of related attribute-value pairs. +A given data base typically stores data relating to a single logical domain. +For instance, +Inferno uses an attribute data base +.IR ndb (6) +to organise network configuration data. +.I Attrdb (2) +is typically used by applications to search the data. +.PP +Each entry in the data base consists of one or more lines containing +attribute/value pairs, separated by white space. +The first line of an entry starts a line; subsequent lines in the entry +are preceded by white space (spaces or tabs). +Pairs on the same line bind tighter together than others in the same entry. +(This is important when one known pair is used to find another by attribute name.) +The character +.RB ` # ' +causes the rest of the line to be ignored (eg, as commentary). +Empty lines are also ignored. +.PP +Attribute/value pairs are written as +.IB attribute = value, +which can be abbreviated to +.lB attribute = +or simply +.I attribute +if the attribute has no value. +A +.I value +that contains white space, or any of the characters \f5#'"=\fP +must be quoted, using either the single or double quote character. +Within a quoted string, two adjacent quotes can be written to enter a quote in the string. +For example: +.IP +.EX +name='Paul Wilson' business company='Fruitbat Villas Ltd' + title='Key Grip' + address='39 Willis Street, York' tel='+44 1904 20927' + address='On the road' tel='+44 7904 169 704' +name='James Mason' personal= + address='10 St James''s, East Grinstead' tel='01342 7674' +.EE +.PP +Note that the binding rule associates each +.B address +in the first entry most closely with the +.B tel +on the same line. +The attributes +.B business +(first entry) +and +.B personal +(second entry) +are both attributes without value. +.PP +A single logical data base can be formed by concatenating several physical files, +each having the format above. +One of the files must contain an entry (typically first in the file) containing a +.B database +attribute and a sequence of attributes of the form +.BI file= filename. +For example: +.IP +.EX +database= + file=file1 + file=file2 + file=file3 +.EE +.PP +The logical database is formed by (logically) concatenating the contents +of each +.I filename +in the order listed +(ie, +.BR file1 , +.BR file2 , +and +.BR file3 +above). +Typically the file containing the +.B database +attribute +appears in the list as well, at the point where its contents should go; +if it does not appear at all, it is assumed to be first. +The name of that file is also used as the name of the logical database, +for instance when opened by +.IR attrdb (2). +.SH SEE ALSO +.IR cfg (2), +.IR attrdb (2), +.IR ipattr (2), +.IR ndb (6), +.IR cs (8), +.IR dns (8) diff --git a/man/6/audio b/man/6/audio new file mode 100644 index 00000000..3d8e9699 --- /dev/null +++ b/man/6/audio @@ -0,0 +1,79 @@ +.TH AUDIO 6 +.SH NAME +audio \- Inferno audio file format +.SH DESCRIPTION +Inferno audio files accepted by commands such as +.IR auplay (1) +have a simple format. +The file contains a header consisting of +non-empty lines of text specifying the data format and characteristics, +followed by an empty line, +followed by the audio data in binary form. +The data can be copied +directly to a suitable audio device (see +.IR audio (3)) +correctly configured, +using +.BR read , +.B write +or +.B stream +(see +.IR sys-read (2)). +.PP +Each header line corresponds to a command that can be written to +the control file +.B audioctl +of the +.IR audio (3) +device. +The first line of the header must be a +.BR rate +command; +other commands can appear in any order. +The commands available are: +.TP +.BI rate " n" +The data was recorded at +.I n +Hz, typically one of +.BR 44100 , +.BR 22050 , +.BR 11025 +or +.BR 8000 +but other values are legal. +.TP +.BI chans " n" +There are +.I n +channels of audio data (eg, 1 for mono and 2 for stereo). +.TP +.BI bits " n" +Each sample is +.I n +bits (typically 8 or 16). +.TP +.BI enc " e" +.br +The string +.I e +gives the recording format, and +will usually be one of the following: +.BR ulaw , +.BR alaw , +.BR pcm +or +.BR adpcm . +.PP +The audio data is stored with a sample from each channel in turn +(`left' sample first if stereo, regardless of encoding or data size). +Data encoded as +.B pcm +is little-endian, 2's complement if 16-bit, but unsigned if 8 bit. +The +.B adpcm +encoding uses 4-bit samples (two mono samples or one stereo sample per byte, again little-endian). +.SH SEE ALSO +.IR auplay (1), +.IR audio (3) diff --git a/man/6/auth b/man/6/auth new file mode 100644 index 00000000..f0b6b025 --- /dev/null +++ b/man/6/auth @@ -0,0 +1,74 @@ +.TH AUTH 6 +.SH NAME +auth \- authentication using station-to-station protocol +.SH DESCRIPTION +The following protocol, +based on the Station-to-Station +protocol, is used for mutual authentication of two parties, +each possessing a certificate from the same certifying authority (CA). +.PP +In the description below: +.TF CERTx +.PD +.TP +.I alpha +is a Diffie-Hellman base used system wide +.TP +.I p +is a Diffie-Hellman modulus used system wide +.TP +.I Rx +is a random number of the same order as +.IR p . +.TP +.BI PK x +the public key of +.I x +.TP +.BI SK x +the private key of +.I x +.TP +.BI CERT x +the public key +of +.I x +signed by the certifying authority +.TP +.BI sig n ( x ) +represents +.I x +signed with +.IR n 's +private key +.PP +In the following, the parties are labelled 0 and 1. +.PP +Each sends its public key and certificate to the other together with +a computation +.IR "alpha**r0 mod p" +.RI ( "alpha**r1 mod p" ) +based on the Diffie-Hellman parameters contained in the certificate: +.IP +.EX +0 → 1 alpha**r0 mod p, CERTu0, PKu0 +1 → 0 alpha**r1 mod p, CERTu1, PKu1 +.EE +.PP +Each can now use the CA's public key and the certificate received to check +that each has the other's public key. +.PP +Finally, each user signs values known to both that each can then verify: +.IP +.EX +0 → 1 sig0(alpha**r0 mod p, alpha**r1 mod p) +1 → 0 sig1(alpha**r0 mod p, alpha**r1 mod p) +.EE +.PP +At this point 0 and 1 can calculate the shared secret +.BR "alpha**(r0*r1)" , +and can use it to encrypt later communications. +.SH SEE ALSO +.IR keyring-auth (2), +.IR keytext (6), +.IR login (6) diff --git a/man/6/colour b/man/6/colour new file mode 100644 index 00000000..145e5b4b --- /dev/null +++ b/man/6/colour @@ -0,0 +1,187 @@ +.TH COLOUR 6 +.SH NAME +colour \- representation of pixels and colours +.SH DESCRIPTION +An image manipulated by +.IR draw (2) +(via the device +.IR draw (3)), +including the image corresponding to a physical display, +contains a set of pixels. +Each pixel has one or more components: +colour components (red, green, blue); greyscale value; colour-map index; alpha value; and +``don't care'' (for padding). +Each component takes a given number of bits; the sum of the sizes of all components +determines the size of the pixel. +The implementation supports only pixel sizes that are either divisors or multiples of 8 bits. +All pixels in an image have the same structure, corresponding to the +.I channels +of that image (see +.IR image (6)). +.PP +The values of the red, green and blue components are chosen so 0 represents +no intensity (black) and the maximum value (all ones, 255 for an 8-bit component) +represents full intensity (eg, full red). +Common colour physical display depths are 24 bits per pixel, with 8 bits per colour 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 +.IR alpha , +which is scaled so 0 represents fully transparent and the maximum value (eg, 255 for +an 8-bit alpha component) represents opaque colour. +The alpha is +.I premultiplied +into the other channels, as described in the paper by Porter and Duff cited in +.IR draw-image (2). +The function +.B Draw->setalpha +(see +.IR draw-intro (2)) +aids the initialisation of colour values with non-trivial alpha. +.PP +Because images are stored in memory managed by +.IR draw (3) +and operated through +.IR draw-image (2), +the details of pixel representation internally can be ignored by many applications. +The representation is visible, however, when using the operations +.B Image.readpixels +and +.B Image.writepixels +(see +.IR draw-image (2)). +The bits representing a pixel's channel components are packed contiguously, and +pixels are stored in contiguous bytes. +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. +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 colours +by 32-bit integers, containing red, blue, green and alpha components +as 8-bit values, in that order from most to least significant byte. +The color component values range from 0 (no colour) to 255 (saturated); +alpha ranges from 0 (fully transparent) to 255 (fully opaque). +.PP +On displays with 8 bits per pixel or less, +to address problems of consistency and portability amongst Inferno applications, +Inferno uses a fixed colour map, called +.BR rgbv . +Although this avoids problems caused by multiplexing colour maps between +applications, it requires that the colour map chosen be suitable for most purposes +and usable for all. +Other systems that use fixed colour maps tend to sample the colour cube +uniformly, which has advantages\(emmapping from a (red, green, blue) triple +to the colour 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 colour cube uniformly gives a colour 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 colour cube into subregions of +size 6\(mu6\(mu6 (as in Netscape Navigator) or 8\(mu8\(mu4 +picking 1 colour in each, +the +.B rgbv +colour map uses a 4\(mu4\(mu4 subdivision, with +4 shades in each subcube. +The idea is to reduce the colour resolution by dicing +the colour 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 colour (3 subcubes +with 4 samples plus black) and a reasonable selection of colours covering the +rest of the colour cube. +The advantage is better representation of +continuous tones. +.PP +The following function computes the 256 3-byte entries in the colour 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 colour 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 Image.draw +(see +.IR draw-image (2)) +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 many 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 colour 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 colour cube with colours whose differences are +almost imperceptible. +Either of these reasons suggests concentrating +the available intensities at the low end of the range. +Third, the compositing computations underlying the graphics operations in +.IR draw-image (2) +assume a linear colour space. +Finally, the right value for gamma correction is determined in part by the +characteristics of the physical display device, and correction should be done on output. +.SH "SEE ALSO" +.IR draw-intro (2), +.IR draw-image (2) diff --git a/man/6/dis b/man/6/dis new file mode 100644 index 00000000..26a43997 --- /dev/null +++ b/man/6/dis @@ -0,0 +1,487 @@ +.TH DIS 6 +.SH NAME +dis \- Dis object file +.SH DESCRIPTION +.ds Os "\v'0.2m'\s-3\|opt\s+3\^\v'-0.2m' +A Dis object file contains the executable form of a single module, +and conventionally uses the file suffix +.BR .dis . +.PP +The following names are used in the description of the file encoding. +.PP +.TP 10n +.I byte +An unsigned 8-bit byte. +.TP +.I word +A 32-bit integer value represented in exactly 4 bytes. +.TP +.I long +A 64-bit integer value represented in exactly 8 bytes. +.TP +.I operand +An integer stored in a compact variable-length +encoding selected by the two most significant bits as follows: +.IP +.nf +0x signed 7 bits, 1 byte +.br +10 signed 14 bits, 2 bytes +.br +11 signed 30 bits, 4 bytes +.fi +.TP +.I string +A variable length sequence of bytes terminated by a zero byte. +Names thus represented are in +.IR utf (6) +format. +.PP +All integers are encoded in two's complement format, most significant byte first. +.PP +Every object file has a header followed by five sections containing code, data, and several sorts of descriptors: +.IP +.I "header code-section type-section data-section module-name link-section" +.PP +Each section is described in turn below. +.SS Header +The header contains a magic number, +a digital signature, a flag word, +sizes of the other sections, and a description of the entry point. +It has the following format: +.IP +.EX +.ft I +header: + magic signature\*(Os runflag stack-extent + code-size data-size type-size link-size entry-pc entry-type +magic, runflag: + operand +stack-extent, code-size, data-size, type-size, link-size: + operand +entry-pc, entry-type: + operand +.EE +.PP +The magic number is defined as 819248 +(symbolically +.BR XMAGIC ), +for modules that have not been signed cryptographically, and 923426 +(symbolically +.BR "SMAGIC" ), +for modules that contain a signature. +The symbolic names +.B "XMAGIC" +and +.B SMAGIC +are defined by the C include file +.B "/include/isa.h" +and by the Limbo module +.IR dis (2). +.PP +The +.I signature +is present only if the magic number is +.BR "SMAGIC" . +It has the form: +.IP +.EX +.ft I +signature: + length signature-data +length: + operand +signature-data: + byte ... +.EE +.PP +A digital signature is defined by a length, followed by an array of bytes of that +length that contain the signature in some unspecified format. +Data within the signature should identify the signing authority, algorithm, and data to be signed. +.PP +.I Runflag +is a bit mask that +selects various execution options for a Dis module. The flags currently defined are: +.IP +.RS +.TP +.BR MUSTCOMPILE " (1<<0)" +The module must be compiled into native instructions for execution (using a just-in-time compiler); +if the implementation cannot do that, +the +.B load +instruction should given an error. +.TP +.BR DONTCOMPILE " (1<<1)" +The module should not be compiled into native instructions, when that is the default for the runtime environment, but +should be interpreted. +This flag may be set to allow debugging or to save memory. +.TP +.BR SHAREMP " (1<<2)" +Each instance of the module should use the same module data for all instances of the module. There is no implicit synchronisation between threads using the shared data. +.TP +.BR HASLDT " (1<<4)" +The dis file contains a separate import section. On older versions of the system, +this section was within the data section. +.TP +.BR HASEXCEPT " (1<<5)" +The dis file contains an exception handler section. +.RE +.PP +.IR Stack-extent , +if non-zero, gives the number of bytes by which the thread stack of this module should be extended in the event that procedure calls exhaust the allocated stack. +While stack extension is transparent to programs, increasing this value may improve the efficiency of execution at the expense of using more memory. +.PP +.IR Code-size , +.I type-size +and +.I link-size +give the number of entries (instructions, type descriptors, linkage directives) +in the corresponding sections. +.PP +.I Data-size +is the size in bytes of the module's global data area +(not the number of items in +.IR data-section ). +.PP +.I Entry-pc +is an integer index into the instruction stream that is the default entry point for this module. +It should point to the first instruction of a function. +Instructions are numbered from a program counter value of zero. +.PP +.I Entry-type +is the index of the type descriptor in the type section that corresponds to the function entry point set by +.IR entry-pc . +.SS Code Section +.PP +The code section describes a sequence of instructions for the virtual machine. +There are +.I code-size +instructions. +An instruction is encoded as follows: +.IP +.EX +.ft I +instruction: + opcode address-mode middle-data\*(Os source-data\*(Os dest-data\*(Os +opcode, address-mode: + byte +middle-data: + operand +source-data, dest-data: + operand operand\*(Os +.ft R +.EE +.PP +The one byte +.I opcode +specifies the instruction to execute; opcodes are +defined by the virtual machine specification. +.PP +The +.I address-mode +byte specifies the addressing mode of each of the three operands: middle, source and destination. The source and destination operands are encoded by three bits and the middle operand by two bits. The bits are packed as follows: +.IP +.EX +bit 7 6 5 4 3 2 1 0 + m1 m0 s2 s1 s0 d2 d1 d0 +.EE +.PP +The following definitions are used in the description of addressing modes: +.IP +.RS +.TP +.B OP +30 bit integer operand +.PD0 +.TP +.B SO +16 bit unsigned small offset from register +.TP +.B SI +16 bit signed immediate value +.TP +.B LO +30 bit signed large offset from register +.PD +.RE +.PP +The middle operand is encoded as follows: +.IP +.RS +.TF "00 SO(MP)" +.TP +.BI "00 " "none" +no middle operand +.TP +.B "01 $SI" +small immediate +.TP +.B "10 SO(FP)" +small offset indirect from FP +.TP +.B "11 SO(MP)" +small offset indirect from MP +.RE +.PD +.PP +The +.I middle-data +field is present only if the middle operand specifier of the +.I address-mode +is not `none'. +If the field is present it is encoded as an +.IR operand . +.PP +The source and destination operands are encoded as follows: +.IP +.RS +.TF "000 SO(SO(MP))" +.TP +.B "000 LO(MP)" +offset indirect from MP +.TP +.B "001 LO(FP)" +offset indirect from FP +.TP +.B "010 $OP" +30 bit immediate +.TP +.BI "011 " "\fInone\fP" +no operand +.TP +.B "100 SO(SO(MP))" +double indirect from MP +.TP +.B "101 SO(SO(FP))" +double indirect from FP +.TP +.B 110 +\fIreserved\fP +.TP +.B 111 +\fIreserved\fP +.RE +.PD +.PP +The +.I source-data +and +.I dest-data +fields are present only when the corresponding +.I address-mode +field is not `none'. +For offset indirect and immediate modes the field contains a single +.I operand +value. +For double indirect modes the values are encoded as two +.IR operands : +the first is the register indirect offset, and the second is the final indirect offset. +The offsets for double indirect addressing cannot be larger than 16 bits. +.SS Type Section +The type section contains +.I type-size +type descriptors describing the layout of pointers within data types. The format of each descriptor is: +.IP +.EX +.ft I +type-descriptor: + desc-number memsize mapsize map +desc-number, memsize, mapsize: + operand +map: + byte ... +.ft R +.EE +.PP +The +.I desc-number +is a small integer index used to identify the descriptor to instructions such as +.BR "new" . +.I Memsize +is the size in bytes of the memory described by this type. +.PP +The +.I mapsize +field gives the size in bytes of the following +.I "map" +array. +.I Map +is an array of bytes representing +a bit map where each bit corresponds to a word in memory. +The most significant bit corresponds to the lowest address. +For each bit in the map, +the word at the corresponding offset in the type is a pointer iff the bit is set to 1. +.SS Data Section +.PP +The data section encodes the contents of the +data segment for the module, addressed by +.B MP +at run-time. +The section contains a sequence of items of the following form: +.IP +.EX +.ft I +data-item: + code count\*(Os offset data-value ... +code: + byte +count, offset: + operand +.EE +.PP +Each item contains an +.I offset +into the section, followed by one or more data values in +a machine-independent encoding. +As each value is placed in the data segment, the offset is incremented by the size of the datum. +.PP +The +.I code +byte has two 4-bit fields. +The bottom 4 bits of +.I code +gives the number of +.I data-values +if there are between 1 and 15; +if there are more than 15, +the low-order field is zero, and a following +.I operand +gives the count. +.PP +The top 4 bits of +.I code +encode the type of each +.I data-value +in the item, which determines its encoding. +The defined values are: +.IP +.RS +.TF 0000 +.TP +.B 0001 +8 bit bytes +.TP +.B 0010 +32 bit integers, one +.I word +each +.TP +.B 0011 +string value encoded by +.IR utf (6) +in +.I count +bytes +.TP +.B 0100 +real values in IEEE754 canonical representation, 8 bytes each +.TP +.B 0101 +Array, represented by two +.I words +giving type and length +.TP +.B 0110 +Set base for data items: one +.I word +giving an array index +.TP +.B 0111 +Restore base for data items: +no operands +.TP +.B 1000 +64 bit big, 8 bytes each +.RE +.PD +.PP +The loader maintains a current base address and a stack of addresses. +Each item's value is stored at the address formed by adding the current offset +to the current base address. +That address initially is the base of the module's data segment. +The `set base' operation immediately follows +an `array' +.IR data-item . +It stacks the current base address and sets the current base address to the +address of the array element selected by its operand. +The `restore base' operation sets the current base address to the +address on the top of the stack, and pops the stack. +.SS Module name +The module name immediately follows the data section. +It contains the name of the module implemented by the object file, +as a sequence of bytes in +UTF encoding, terminated by a zero byte. +.SS Link Section +The link section contains an array of +.I link-size +external linkage items, +listing the functions exported by this module. +Each variable-length item contains the following: +.IP +.EX +.ft I +link-item: + pc desc sig fn-name +pc, desc: + operand +sig: + word +fn-name: + string +.ft R +.EE +.PP +.I Fn-name +is the name of an exported function. +Adt member functions appear with their +full names: the member name qualified by the adt name, in the form +.IB adt-name . member-name, +for instance +.BR Iobuf.gets . +.PP +.I Pc +is the instruction number of its entry point. +.I Desc +is an index value that selects a type descriptor in the type section, +which gives the type of the function's stack frame. +.I Sig +is an integer hash of the type signature of the function, used in type checking. +.SS Import Section +The optional import section lists all those functions imported from other +modules. This allows type checking at load time. The size of the section in +bytes is given at the start in operand form. For each module imported there +is a list of functions imported from that module. For each function, its type signature (a word) is followed by +a 0 terminated list of bytes representing its name. +.SS Handler Section +The final optional section lists all exception handlers declared in the module. The number +of such handlers is given at the start of the section in operand form. For each one, its format +is: +.IP +.EX +.ft 1 +handler: + offset pc1 pc2 desc nlab exc-tab +offset, pc1, pc2, desc, nlab: + operand +exc-tab: + exc-name pc ... exc-name pc pc +exc-name: + string +pc: + operand +.ft R +.EE +.PP +Each handler specifies the frame offset of its exception structure, the range of pc values it covers (from pc1 up to but not including pc2), the type descriptor of any +memory that needs destroying by the handler (or -1 if none), the number of +exceptions in the handler and then the exception table itself. The latter consists +of a list of exception names and the corresponding pc to jump to when this +exception is raised. This is then followed by the pc to jump to in any wildcard (*) case +or -1 if this is not applicable. +.SH SEE ALSO +.IR asm (1), +.IR dis (2), +.IR sbl (6) +.br +``The Dis Virtual Machine Specification'', Volume 2 diff --git a/man/6/font b/man/6/font new file mode 100644 index 00000000..b118ad6d --- /dev/null +++ b/man/6/font @@ -0,0 +1,102 @@ +.TH FONT 6 +.SH NAME +font, subfont \- external format for character fonts and subfonts +.SH DESCRIPTION +Fonts are constructed as a list defining a range of Unicode characters +and a subfont containing the character images for that range. +Subfonts are not directly accessible from Limbo. +.PP +External fonts are described by a plain text file that can be read using +.BR Font.open ; +.B Font.build +reads the same format from a string rather than a file. +(see +.IR draw-font (2)). +.PP +The format 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 should be 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 holding the subfont data. +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: +an image containing character images, +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 values called +.B x +(2 bytes, low order byte first), +.BR top , +.BR bottom , +.BR left , +and +.BR width +for the successive characters from left to right (in increasing Unicode order) in the +subfont. +The rectangle holding the character is +.B (x, +.B top, +.B xn, +.BR bottom) , +where +.B xn +is the +.B x +field of the next character. +When the character is to be drawn in an image at point +.BR p , +the rectangle is placed at +.B (p.x+left , +.B p.y) +and the next character to be drawn is placed at +.B (p.x+width , +.B p.y) +The +.B x +field of the last +entry +is used to calculate the image width +of the previous character; the other fields in the last +entry +are irrelevant. +.PP +Note that the convention of using the character with value zero (NUL) to represent +characters of zero width (see the description of +.B Image.text +in +.IR draw-image (2)) +means that fonts should have, as their zeroth character, +one with non-zero width. +.SH FILES +.TF /fonts/* +.TP +.B /fonts/* +font directories +.SH "SEE ALSO" +.IR draw-intro (2), +.IR draw-font (2), +.IR draw (3) diff --git a/man/6/image b/man/6/image new file mode 100644 index 00000000..93e668fa --- /dev/null +++ b/man/6/image @@ -0,0 +1,178 @@ +.TH IMAGE 6 +.SH NAME +image \- external format for images +.SH DESCRIPTION +Images are described in +.IR draw-image (2), +and the definition of pixel values is in +.IR colour (6). +Fonts and images are stored in external files +in machine-independent formats. +.PP +Image files are read and written using +.B Display.readimage +and +.B Display.writeimage +(see +.IR draw-display (2)). +An image is a rectangular array of pixels, +where each pixel is organised as one or more channels, +as determined by the image. +.PP +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 below for a discussion of channel descriptors), +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 be a multiple of 8, so +pixel values take up an integral number of bytes. +.PP +The +.B Image.readpixels +and +.B Image.writepixel +operations described in +.IR draw-image (2) +also deal with rows in this format, stored in Limbo arrays of bytes. +.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 colour-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 colour-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, +which is little-endian. +In particular +.B 'r8g8b8' +pixels have byte ordering blue, green, and red within the file. +See +.IR colour (6) +for more details of the pixel format. +.PP +A previous Inferno image 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. +Furthermore, the pixel values are inverted compared to the current colour maps; +in particular, an all-zero pixel is white and all-ones is black. +That format is still readable but cannot be written; older files should be converted to the +newer one. +The image file reading operations automatically invert the pixel values to produce correct results. +.PP +A compressed image file begins with the 11 bytes "compressed\en", +immediately followed by a header as described above, followed by the +image data. +(The pixel data once uncompressed has the format described above.) +The rest of the file is 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 Styx 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. +.SH "SEE ALSO" +.IR draw-intro (2), +.IR draw-image (2), +.IR draw (3), +.IR colour (6), +.IR font (6) diff --git a/man/6/keyboard b/man/6/keyboard new file mode 100644 index 00000000..7662200c --- /dev/null +++ b/man/6/keyboard @@ -0,0 +1,170 @@ +.TH KEYBOARD 6 +.SH NAME +keyboard \- how to type characters +.SH DESCRIPTION +Keyboards are idiosyncratic. +The differing conventions of host operating systems +make them more so for Inferno. +In all implementations, +it should be obvious how to type ordinary +.SM ASCII +characters, +backspace, tab, escape, and newline. +When typing into the Inferno environment, the key labelled +.B Return +or +.B Enter +generates a newline +.RB ( 0x0A ); +if there is a key labelled +.B Line +.BR Feed , +it generates a carriage return +.RB ( 0x0D ); +Inferno 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. +.PP +In native mode, +on the PC and some other machines, the following +extra conventions might also be used. +The key labelled +.B Caps +.B Lock +acts as an additional control key. +The character erase key generates backspace. +The key labelled +.B Del +or +.B Delete +generates the delete character +.RB ( 0x7F ). +The plethora of function keys generate values in the Unicode +user-defined space, as defined by +.B /include/keyboard.h +and +.BR /module/keyboard.m . +They are fitfully supported by applications, but +.B "Page\ Up" +and +.B "Page\ Down" +are often understood by Tk applications. +.PP +Characters in Inferno 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 implementation-dependent, and +is also generally near the lower right of the main key area: +either +.B Alt +key on the PC, +and in X11 implementations, whatever X11 regards +as +.B Alt +or +.BR Meta . +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). +.IP +A repeated symbol gives a variant of that symbol, e.g., +.B ?? +yields ¿\|. +.IP +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 ¹. +.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 acme (1), +.IR wm-brutus (1), +.IR intro (1), +.IR unicode (1), +.IR cons (3), +.IR utf (6), +.IR kbdputc (10.2) diff --git a/man/6/keys b/man/6/keys new file mode 100644 index 00000000..02e7cfee --- /dev/null +++ b/man/6/keys @@ -0,0 +1,52 @@ +.TH KEYS 6 +.SH NAME +keys \- secrets shared with signer +.SH DESCRIPTION +The file +.B /keydb/keys +exists only on a host acting as a `signer' (authentication server, Certifying Authority). +It +holds a password entry +for each user registered with an Inferno server. +Each entry contains a user name, a password, the time at which the entry +expires, and the entry's status. +The password is the secret shared between the user +and signer (authentication server), +allowing the signer to sign a certificate to authenticate a +user's public key to others, using the secret to check the user's identity. +The actual secret is not stored, but rather its SHA-1 hash. +.PP +The file is encrypted with a secret provided by the signer's administrator; +normally that secret is entered once when +authentication services are started by +.B svc/auth +on the host acting as signer +(see +.IR svc (8)). +The file should also be readable and writable only by the user identity +that runs the signing service +(ie, +mode +.BR 600 , +see +.IR chmod (1)). +Entries are usually accessed only through +the name space provided by +.IR keyfs (4), +which decrypts the file into internal data structures given the administrative key, +and makes each entry visible as a separate directory. +Using that name space, +entries are added and updated by an administrator using +.IR changelogin (8), +a user can change a secret using +.IR passwd (1) +via +.IR keysrv (4), +and it is accessed for signing by +.IR logind (8) +to obtain the secret used to verify the identity +of a client requesting a certificate +(typically via +.IR security-login (2)). +.SH FILES +.B /keydb/keys diff --git a/man/6/keytext b/man/6/keytext new file mode 100644 index 00000000..0e9876eb --- /dev/null +++ b/man/6/keytext @@ -0,0 +1,124 @@ +.TH KEYTEXT 6 +.SH NAME +keytext \- textual form of Inferno public/private keys +.SH DESCRIPTION +.IR Keyring-certtostr (2) +defines a set of functions that convert between textual forms of the elements of the +Inferno public-key authentication system and their internal data types. +The textual form is used for key storage and as the transport format for the authentication protocol +.IR auth (6). +In storage and transport each encoded value is encapsulated by the record-oriented +encoding defined in +.IR keyring-getmsg (2). +The format represents public and private keys, and signer's certificates. +In this context a +.I certificate +is a time-limited cryptographically signed hash of some other value +(usually a public key) and contains neither that value nor the signer's key, which is assumed to be +available elsewhere. +.PP +All values are represented by a sequence of newline-separated text fields. +The type of any given value is determined by its context. +Each type of value has a common prefix that includes an algorithm identifier, followed by a sequence of algorithm-dependent fields: +.IP +.EX +.ft R +.ta \w'\f2elgamal-public-keyxx\f1'u +\w'\ ::=\ 'u +.fi +.IR "authinfo" " ::= " "signer-public-key certificate !private-key big-alpha big-p" +.br +.IR certificate " ::= " "sigalg hashalg signer-name exp-time *-sig" +.br +.IR sigalg " ::= " +.BR "rsa" " | " +.BR "dsa" " | " +.BR "elgamal" +.br +.IR hashalg " ::= " +.BR sha1 " | " +.B md5 +.br +.IR "*-key" " ::= " "sigalg owner-name ..." +.sp +.IR "rsa-public-key" " ::= " +.B rsa +.I owner-name +.I "big-n big-ek" +.br +.IR "rsa-private-key" " ::= " +.B rsa +.I owner-name +.I "big-n big-ek" +.br +.I " !big-dk !big-p !big-q !big-kp !big-kq !big-c2" +.br +.IR "dsa-public-key" " ::= " +.B dsa +.I owner-name +.I "big-p big-q big-alpha big-key" +.br +.IR "dsa-private-key" " ::= " +.B dsa +.I owner-name +.I "big-p big-q big-alpha big-key !big-secret" +.sp +.IR rsa-sig " ::= " "big-val" +.br +.IR dsa-sig " ::= " "big-r big-s" +.br +.IR elgamal-sig " ::= " "big-r big-s" +.EE +.PP +Each value labelled as +.RI ` big- ' +is an unsigned multiple-precision integer +from +.IR keyring-ipint (2), +represented as a sequence of bytes with +in big-endian order, +as produced by +.BR IPint->iptobytes +with an extra leading zero byte added if the top bit of the first byte is set, +and then encoded in base-64 (as by +.IR encoding (2)). +Each value labelled +.RI ` -name ' +is +.I utf (6) +text not containing a newline; +it is interpreted by an application and need not be a name. +The expiry time +.I exp-time +is represented in decimal as seconds from the Epoch (1 January 1970 00:00 GMT); +if it is zero, no expiry time is set. +A label prefixed by +.RB ` ! ' +marks a value that should be considered secret. +.PP +The hash of a key is computed over its textual encoding according to the syntax above. +A certificate's signature value is produced by digitally signing using +.I sigalg +the hash (using +.IR hashalg ) +of the concatenation of the value to be authenticated, the +.I signer-name +in +.IR utf (6), +a single space, and the +.I exp-time +in decimal (with no leading zeroes). +When checking a signature, comparisons are done with values in internal multiple-precision form +(ie, as +.BR IPint s), +not in base-64 form. +.SH SEE ALSO +.IR keyring-certtostr (2), +.IR keyring-getmsg (2), +.IR factotum (4), +.IR keys (6), +.IR getauthinfo (8) +.SH BUGS +The byte-array encoding of +.B IPint +should not require the leading zero; +it does so for compatibility with old keys. diff --git a/man/6/login b/man/6/login new file mode 100644 index 00000000..e43d085b --- /dev/null +++ b/man/6/login @@ -0,0 +1,109 @@ +.TH LOGIN 6 +.SH NAME +login \- key exchange protocol +.SH DESCRIPTION +The following encrypted key exchange protocol is used between a client such as +.B login +in +.IR security-login (2), +and a certificate signing process such as +.IR logind (8), +to justify the latter's issuing a certificate that can +later be presented to an Inferno service +to establish credentials. +.PP +A shared secret must previously be agreed between +user and certifying authority (CA). +It is used by the protocol to establish a secure channel between user and CA. +.PP +In the description below: +.TF key(m) +.PD +.TP +.I ivec +is an 8 byte random number (`initialisation vector') chosen for +this conversation. +.TP +.I sha +is the 20 byte secure hash (SHA-1) of the password +.TP +.I key +is an 8 byte secret formed as follows: +.EX +.br +key[0] = ivec[0]^sha[0]^sha[8]^sha[16] +key[1] = ivec[1]^sha[1]^sha[9]^sha[17] +.EE +\&... +.EX +key[5] = ivec[5]^sha[5]^sha[13]; +key[6] = ivec[6]^sha[6]^sha[14]; +key[7] = ivec[7]^sha[7]^sha[15]; +.EE +.TP +.I alpha +is a Diffie-Hellman base used system wide +.TP +.I p +is a Diffie-Hellman modulus used system wide +.TP +.I "key(m)" +is +.I m +encrypted using the RC4 algorithm with +.IR key . +.TP +.I Rx +is a random number of the same order as +.IR p . +.TP +.I "secret" +is the Diffie-Hellman secret +.IR "alpha**(r0*r1) mod p" . +.PP +The protocol follows. ``user→CA xxx'' means that the user +sends the message ``xxx'' to the certifying authority. +Any party can send an error instead of a message at any +point to terminate the protocol. +.IP +.EX +user→CA name +CA→user ACK +.sp 1v +user→CA ivec +CA→user key(alpha**r0 mod p), alpha, p +.sp 1v +user→CA alpha**r1 mod p +CA→user CA's public key, SHA(CA's public key + secret) +.sp 1v +user→CA user's public key, SHA(user's public key + secret) +CA→user user's public key certificate +.EE +.PP +The complexity of this protocol is intended to shield the password. +To start a clear text attack against the password, one +needs to first attack the Diffie-Hellman exponential +to determine +.IR "alpha**r0 mod p" . +A possible weakness is that the encrypted quantity +is base64 encoded, constraining +the possible values of each byte. +This could aid a brute force attack. +.PP +.I Alpha +and +.I p +are sent unprotected, though the user code does a few sanity checks +on the values it receives. +This is another likely point of attack. +We should like to know about any. +.PP +The role of +.I ivec +is to foil any replay attacks by someone spoofing the CA +though this is probably overkill. +.SH SEE ALSO +.IR security-intro (2), +.IR security-login (2), +.IR logind (8), +.IR signer (8) diff --git a/man/6/man b/man/6/man new file mode 100644 index 00000000..142bfe84 --- /dev/null +++ b/man/6/man @@ -0,0 +1,248 @@ +.TH MAN 6 +.SH NAME +man \- manual page format +.SH DESCRIPTION +The Inferno manual pages are stored as text files in a format originally defined for use with the Unix and Plan 9 +.I troff +command, when used with the +.I man +macro package. +Within Inferno, the format is interpreted by the programs of +.IR man (1). +.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 +.B 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. +For graphical display and printing, +.BR L = B ; +when converted to plain text, the +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 +.I man +format +admits equations and tables in the style of Unix +.I eqn +(equation setting) +and +.I tbl +(table layout) +preprocessors, +but do not support arguments on +.B .EQ +and +.B .TS +macros. +.PP +These strings are predefined by +.IR man : +.TP +.B \e*R +Trademark symbol +.br +.ns +.TP +.B \e*S +Change to default type size. +.SH FILES +.TF /man/1/INDEX +.TP +.B /man/*/* +Source files of manual pages. +.SH SEE ALSO +.IR man (1) +.SH REQUESTS +.ta \w'.TH n c x 'u +\w'Cause 'u +\w'Argument\ 'u +.if 1 .di xx +.if 1 \ka +.if 1 .br +.if 1 .di +.if 1 .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 include literal double quote marks +.B \&" +in font-alternation macros, such as +.LR .BI . +.br +There is no direct way to suppress column widows in 2-column +output; the column lengths may be adjusted by inserting +.L .sp +requests before the closing +.LR .1C . diff --git a/man/6/namespace b/man/6/namespace new file mode 100644 index 00000000..8eee9376 --- /dev/null +++ b/man/6/namespace @@ -0,0 +1,162 @@ +.TH NAMESPACE 6 +.SH NAME +namespace \- name space description file +.SH DESCRIPTION +Namespace files describe how to construct a name space from scratch, +or add to an existing name space. +The files are interpreted by +.IR newns (2), +invoked by commands such as +.IR logon (1) +and by other system services. +.PP +The name space description file contains one or more +lines each of which specifies one name space operation. +Empty 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 string terminated by white space, or one of the characters +.LR / , +.LR . , +or +.LR $ . +.PP +The known operations and their arguments are: +.TP +.B "bind [-abci] \f2old\fP \f2new\fP" +Use +.I new +as an alias for file or directory +.IR old . +Options +.BR a , +.BR b +and +.BR c +translate to flag values +.BR Sys\->MAFTER , +.B Sys\->MBEFORE +and +.B Sys\->MCREATE +of +.IR sys-bind (2). +If neither +.B a +nor +.B b +are given, the default is +.BR Sys\->MREPL . +Option +.B i +means to ignore errors. +.TP +.B cd \f2directory\fP +Change working directory to +.IR directory . +.TP +.B fork +Split the name space before modification. +This is equivalent to passing a value of +.B Sys->FORKNS +to +.IR sys-pctl (2). +.TP +.B "mount [-abc9i] [-k \f2keyfile\fP] [-C \f2alg\fP] [\f2net\fP!]\f2machine\fP[!\f2svc\fP] \f2dir\fP [\f2spec\fP]" +Mount the file tree of +.I machine +upon directory +.IR dir . +The default service is +.BR styx . +Options +.BR a , +.BR b , +.B c +and +. B i +are the same as for +.BR bind . +The tokens +.I dir +and +.I spec +translate to +.I old +and +.I aname +of +.B mount +as described under +.IR sys-bind (2). +The +.BR -k , +.B -C +and +.B -9 +options are the same as those for the +.I mount +command (see +.IR bind (1)). +.TP +.B "import [-abc9i] [\f2net\fP!]\f2machine\fP[!\f2svc\fP] [\f2remotedir\fP] \f2dir\fP" +Import a directory from a remote Plan 9 +.I machine +and make it appear on directory +.IR dir . +Options +.BR a , +.BR b , +.BR c +and +.B i +are the same as for +.BR mount . +By default, +.I remotedir +is assumed to be the same name as +.IR dir . +The default service is +.BR exportfs . +(Currently this operation works only under native Inferno and Plan 9.) +.TP +.B new +Create a new name space in which the current directory +becomes the root directory; +typically used after +.BR cd . +This is equivalent to passing a value of +.B Sys->NEWNS +to +.IR sys-pctl (2). +.TP +.B nodev +Disallow device attaches. +This is equivalent to passing a value of +.B Sys->NODEVS +to +.IR sys-pctl (2). +.TP +.B unmount [-i] [\f2name\fP] \f2from\fP +If two arguments are given, undo a +.B bind +or +.B mount +with the same arguments. +If only one argument is given, everything bound to or mounted on +.I from +is unmounted. +The +.B -i +option means ignore errors. +.TP +.BI "\&." " path" +Include the name space description file +.IR path . +.SH SEE ALSO +.IR nsbuild (1), +.IR wm (1), +.IR newns (2) diff --git a/man/6/ndb b/man/6/ndb new file mode 100644 index 00000000..c84c33eb --- /dev/null +++ b/man/6/ndb @@ -0,0 +1,219 @@ +.TH NDB 6 +.SH NAME +ndb \- network data base +.SH SYNOPSIS +.B /lib/ndb/local +.br +.B /lib/ndb/inferno +.br +.B /lib/ndb/dns +.br +.B /lib/ndb/common +.SH DESCRIPTION +Network configuration data is stored in one or more files in the directory +.BR /lib/ndb , +in the attribute data base format defined by +.IR attrdb (6). +Most applications that use it start with +.B /lib/ndb/local +by default. +That can refer (using a +.B database +entry) to other files that form part of the same logical database. +They are stored in distinct files to allow different configurations +to avoid duplicating data by sharing some common content. +For example, +.B /lib/ndb/common +associates service names with port numbers for Internet protocols, +and +.B /lib/ndb/inferno +provides the Inferno-specific port mapping. +A database is automatically reread if any component file has +changed since it was last read (based on its modification time). +.PP +A network database gives particular meaning to the following attributes: +.TF dnsdomainxx +.TP +.B auth +name or address of authentication server +.TP +.B bootf +name of the file to send to a device on request when booting +.TP +.B dns +name or address of DNS resolver (see also the +.B ns +attribute below) +.TP +.B dnsdomain +domain in which the local host lives (used to qualify unqualified names) +.TP +.B dom +Internet domain name (host or DNS zone) +.TP +.B ether +Ethernet address in the form accepted by +.IR ether (2) +.TP +.B fs +name or address of file server +.TP +.B il +IL service name +.TP +.B infernosite +empty-valued attribute that labels default site parameters +.TP +.B ip +Internet address +.TP +.B ipgw +name or address of Internet gateway +.TP +.B ipmask +Internet network mask +.TP +.B ipnet +network or subnetwork name +.TP +.B ipv4proto +IPv4 protocol number (see also +.BR protocol ) +.TP +.B mx +mail exchanger +.TP +.B ns +name of a DNS name server for an associated +.B dom +.TP +.B port +port number for a service +.TP +.B protocol +protocol name +.TP +.B soa +start of area (value is empty if locally authoritative, or +.RB ` delegated ' +if another server is authoritative) +.TP +.B sys +system name (short local name for a host) +.TP +.B tcp +TCP service name +.TP +.B udp +UDP service name +.PD +.PP +Internet addresses and masks can be written in any form +accepted by +.IR Ip (2). +Network applications might use other attributes of their own, +which they document on their own pages. +.PP +.I Cs (8) +interprets a host name of the form +.BI $ server +as referring to the set of names and addresses that are values +of the attribute +.I server +in the network data base. +Attributes in general use include some of those above, and the following: +.TF FILESERVER +.TP +.B FILESERVER +older name for file server +.B fs +file server +.TP +.B pop3 +mail reading service using the POP3 protocol +.TP +.B PROXY +firewall proxy for +.IR ftpfs (4) +.TP +.B SIGNER +Inferno authentication server running +.IR logind (8) +and/or +.IR signer (8) +.TP +.B smtp +mail delivery gateway using the SMTP protocol +.PD +.PP +Other such symbolic server names are mentioned in the manual pages for associated applications. +.PP +.IR Dns (8) +interprets +.BR dns +and +.BR dnsdomain +values in any +.B infernosite +entry, and +.BR dom , +.BR ip , +and +.BR ns +values more generally. +When resolving a domain name, +.I dns +looks first in this data base to see if there is a +.B dom +entry for the name, and if so, whether there is either an associated +.B ns +attribute giving a name server to ask, or an +.B ip +attribute giving the name's IP address. +Failing that, it works up the name hierarchy looking for name servers to ask. +Failing that, it looks for a +.B dnsdomain +entry with +.B dns +attributes listing other resolvers to ask. +Bootstrap data is commonly stored in +.BR /lib/ndb/dns ; +by default it defines the root name servers: +.IP +.EX +dom= # root + ns=a.root-servers.net + ns=b.root-servers.net + \f1...\fP +dom=a.root-servers.net ip=198.41.0.4 +dom=b.root-servers.net ip=128.9.0.107 + \f1...\fP +.EE +.SH EXAMPLE +Specify the site's default DNS domain name and resolvers for +.IR dns (8), +and a collection of symbolic service names for +.IR cs (8): +.IP +.EX +infernosite= + dnsdomain=vitanuova.com + dns=200.1.1.11 + dns=158.152.1.58 + dns=158.152.1.43 + SIGNER=doppio + FILESERVER=doppio + smtp=doppio + pop3=doppio + PROXY=doppio + GAMES=vivido + IRMSERVER=vivido +.EE +.SH FILES +.B /lib/ndb/* +.SH SEE ALSO +.IR attrdb (2), +.IR attrdb (6), +.IR bootpd (8), +.IR cs (8), +.IR dns (8) diff --git a/man/6/plumbing b/man/6/plumbing new file mode 100644 index 00000000..d28e26b8 --- /dev/null +++ b/man/6/plumbing @@ -0,0 +1,163 @@ +.TH PLUMBING 6 +.SH NAME +plumbing \- plumbing rules +.SH DESCRIPTION +Plumbing rules tell +.IR plumber (8) +how to route plumbing messages +generated by applications using +.IR plumbmsg (2). +.PP +The file is a set of rules separated by blank lines. +Each +rule +is a set of patterns followed by a set of actions. +The rules are interpreted in order. +The first rule whose patterns all match is applied, and no further +rules are examined. +Comments start with +.B # +and continue to end of line. +Single quotes protect special characters (use +.B '' +to get a single quote). +.PP +A +pattern +has the general form: +.IP +.I "field verb arg" +.PP +Each +.I field +corresponds to a field in the incoming plumbing message: +.RS +.TP +.B src +Source application +.TP +.B dst +Destination port +.TP +.B dir +Working directory +.TP +.B kind +Format of the data (eg, +.B text +or +.BR image ) +.TP +.B attr +A line of +.IB name = value +pairs +.TP +.B data +The message data (an array of bytes) +.RE +.PP +The verbs are: +.RS +.TF matches +.PD +.TP +.B is +Exact string comparison with +.I arg +.TP +.B matches +Regular expression comparison with +.I arg +.TP +.B isdir +.I Arg +must name an existing directory +.TP +.B isfile +.I Arg +must name an existing file +.TP +.B set +Set the value of the +.I field +to +.IR arg . +This verb operates in place, so put it after all other patterns in the rule. +.RE +.PP +The +.I arg +can refer to one of the following variables: +.RS +.TF "$0 to $9 " +.PD +.TP +.BR $0 " to " $9 +Substrings resulting from the most recent regular expression match: +.B $0 +is the entire substring; +.B $1 +the first parenthesised substring, etc. +.TP +.B $file +The file name examined by the last +.B isfile +verb. +.TP +.B $dir +The directory name examined by the last +.B isdir +verb. +.RE +.PP +The following actions are provided: +.RS +.TP +.BI "plumb to" " port" +Route the message to the given plumbing +.IR port . +.TP +.BI "plumb start" " command arg ..." +If no program is currently listening on the current rule's +.IR port , +start the +.I command +with the given arguments. +The +.RB ` $ ' +variables listed above can be used, to include part +of the message in the command line arguments to the program. +They are replaced in the command string by their actual values. +.RE +.PP +For example, the following rule sends the names of module files\- +file names ending with suffix +.RB ` .m '\- +to +.IR wm-brutus (1), +starting it if it is not already running: +.IP +.EX +kind is text +data matches '([a-zA-Z0-9]+\.m)(:[0-9]+)?' +data isfile /module/$1 +data set /module/$0 +plumb to edit +plumb start /dis/wm/brutus.dis $file$2 +.EE +.PP +Note the use of +.B $2 +in the +.B start +action to pass +.B brutus +the line number selected by the second parenthesised +expression in the pattern. +.SH FILES +.BI /usr/ user /lib/plumbing +.SH SEE ALSO +.IR plumb (1), +.IR plumbmsg (2), +.IR plumber (8) diff --git a/man/6/proto b/man/6/proto new file mode 100644 index 00000000..1a324373 --- /dev/null +++ b/man/6/proto @@ -0,0 +1,153 @@ +.TH PROTO 6 +.SH NAME +proto \- file system prototype +.SH DESCRIPTION +A +.I proto +file defines a file system hierarchy, for +programs that create, copy or operate on them, +such as +.IR fs (1) +or +.IR mkfs (8). +The +.I proto +file defines the hierarchy as a set of names relative to an +existing hierarchy, for instance in an existing file system or a list of path names +in an archive. +Files in the existing hierarchy that are not specified in the +.I proto +file +are ignored. +.IR Fsproto (2) +provides functions to read a prototype file and enumerate the names it selects in an +existing hierarchy. +.PP +Each line of the +.I proto +file specifies a file (where the term `file' includes directories). +Indentation is significant, +with each level of indentation corresponding to a level in the file tree. +Each line contains up to five fields separated by white space: +.IP +.EX +.I "name perm uid gid source" +.EE +.PP +.I Name +is the last path element in the resulting file tree. +.I Perm +specifies the permissions, as described below. +.I Uid +is the owner of the file, +and +.I gid +is the group owning the file. +.I Source +is the name of a file in the current name space +(not the source file tree) from which to copy +.IR name 's +content. +All fields except +.I name +are optional. +If a field such as +.I perm +or +.I uid +is not given, or is given as +.LR - , +its value is taken from the existing file. +.PP +A +.I name +starting with +.L $ +is taken as a reference to an environment variable (see +.IR sh (1) +and +.IR env (3)) +and replaced by the value of that variable. +If the first +.I name +in a directory is +.LR + , +all of the files are represented, and all subdirectories recursively. +If the first +.I name +is +.LR * , +all of the names in the corresponding existing directory are represented, +but only the names of subdirectories, not their content. +If the first +.I name +is +.LR % , +only non-directory names are represented excluding both the names and content +of subdirectories. +.PP +.I Perm +has the form: +.IP +.RB [ d ] +.RB [ a ] +.RB [ l ] +.I oct +.PP +where the optional letters set file attributes +.RL ( d +directory, +.L a +append-only, and +.L l +exclusive-use), +and +.I oct +is an octal number giving the permissions for user, group and others +(see +.IR chmod (1)). +.SH EXAMPLES +.PP +Denote all files in a given file system: +.IP +.EX ++ +.EE +.PP +Denote all files in the current user's home directory: +.IP +.EX +usr + $user +.EE +.PP +Specify a subset of files in +.BR /dis : +.IP +.EX +dis + * + install + * + lib + arg.dis + names.dis +.EE +.SH FILES +.TF /lib/proto/portproto +.TP +.B /lib/proto +directory of prototype files +.TP +.B /lib/proto/all +prototype for whole hierarchy (ie, line containing +.LR + ) +.TP +.B /lib/proto/portproto +generic prototype file +.SH "SEE ALSO" +.IR fs (1), +.IR fsproto (2), +.IR kfs (4), +.IR mkfs (8) + diff --git a/man/6/regexp b/man/6/regexp new file mode 100644 index 00000000..09dea814 --- /dev/null +++ b/man/6/regexp @@ -0,0 +1,126 @@ +.TH REGEXP 6 +.SH NAME +regexp, regex \- 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 acme (1), +.IR sh-regex (1), +.IR regex (2) diff --git a/man/6/sbl b/man/6/sbl new file mode 100644 index 00000000..4b3dad88 --- /dev/null +++ b/man/6/sbl @@ -0,0 +1,385 @@ +.TH SBL 6 +.SH NAME +sbl \- symbol table file +.SH DESCRIPTION +A Limbo symbol table file provides type information for the module +in an associated Dis executable file, +for use by debuggers and similar applications. +They are written by the Limbo compiler +when given the +.B -g +option. +The files conventionally have a +.B .sbl +suffix; they need not be stored in the same directory as +the corresponding Dis file. +.PP +The file consists of a header followed by five tables: +.IP +.I "header file-table pc-table type-table fn-table data-table" +.PP +Each table starts with a line containing a decimal +count of the items in that table. +The count can be zero. The following +sections describe the format of table items in each table. +In the description, the following terminals are used. +.PP +A +.I "string" +is a sequence of letters, digits, and the characters _, ., -, and >. Letters are the Unicode characters a through z and A through Z, and all Unicode characters with encoded values greater than A0 hexadecimal. +.PP +An +.I int +is an optional minus sign followed by a sequence of digits, 0 to 9. +.PP +In the following description, +the presence of a space is represented by +.B • +and a newline by +.BR \en . +There are no other spaces between syntactic elements in the file format. +Other special characters represent themselves. +.SS Header +.PP +The header consists of two items. +.ds Os "\v'0.2m'\s-3\|opt\s+3\^\v'-0.2m' +.IP +.EX +.ft I +.nf +header: + magic\f5\en\fP + module\f5\en\fP +magic: + \f5limbo .sbl 2.0\fP +module: + string +.ft R +.EE +.PP +There have been two previous versions of symbol table format, distinguished +by the number in +.IR magic . +Version +.B 1. +was the original; version +.B 1.1 +added more references back to the source; and version +.B 2.0 +replaced the original +adt table by a type table and added support for Limbo's +.B pick +construction. +Only version 2.0 is described here; the others are obsolete. +.PP +.I Module +is the name of the module implemented in the Dis file. +Symbol file references to identifiers declared by the implementation module are unqualified. +A name referenced that is imported from any other module is preceded by +.IB m -> +where +.I m +is that module's identifier. +.SS File table +The file table is a list of file names referenced by the rest of the tables. Each file name is terminated by a newline character; within the name, any character other than a newline is valid. +.SS PC table +The PC table relates every instruction in the Dis file to the source from which it was compiled. +The table is indexed by Dis PC to obtain a reference to the corresponding source. +Each item consists of a source description +and a statement reference: +.IP +.EX +.ft I +pc-item: + src stmt \f5\en\fP +src: + pos\f5,\fPpos• +pos: + file\f5:\fP\*(Os line\f5.\fP\*(Os char +file, line, char, stmt: + int +.ft R +.EE +.PP +A source description +.I src +selects source text as a range of characters within lines of a source file. +.I File +is an index into the file table (origin 0); +.I "line" +and +.I "char" +are positions within that source file, with line numbers starting at 1 and character positions at 0. If +.I "file" +or +.I "line" +is omitted, it is assumed to have the previous value, or 0 if there is no previous value. +.PP +.I Stmt +is the `statement number' of the instruction. +Despite its name, the scope of a statement number is smaller than a Limbo statement: +it identifies a region marked by the compiler for treatment as a unit when debugging. +For instance, +in a +.B for +statement, the initial expression, increment, test, and body all have unique +statement numbers. +All instructions compiled from the same region in a Limbo program have the same statement number. +The number is that of the innermost region that contains the instruction. +.SS Type table +The type table describes the Limbo adts used in the Dis file, +both locally declared and imported. +Each entry describes a +.IR type : +.IP +.EX +.I "type:" +.ft 5 + @ \fItype-index\fP \en + a \fIadt-item\fP + p \fIadt-item\fP \fItag-table\fP + t \fIsize\fP . \fIid-table\fP + m \fImodule\fP \en \fIsrc\fP + A \fItype\fP + C \fItype\fP + L \fItype\fP + R \fItype\fP + n + N + B + b + i + f + s +.ft I +type-index: + int +.EE +.PP +Each leading character specifies a different Limbo type: +.IP +.RS +.TF N +.TP 5n +.B @ +existing type referenced by type table index (not self-referential) +.TP +.B A +.B array of +.I type +.TP +.B a +.B adt +without +.B pick +.TP +.B B +.B big +.TP +.B b +.B byte +.TP +.B +C +.B chan of +.I type +.TP +.B f +.B real +.TP +.B i +.B int +.TP +.B L +.B list of +.I type +.TP +.B m +.B module +.TP +.B N +.BR nil 's +type +.TP +.B n +no type (eg, function with no return type) +.TP +.B p +.B adt +with +.B pick +.TP +.B R +.B ref +.I type +.TP +.B s +.B string +.TP +.B t +tuple +.PD +.RE +.PP +A +.I type-index +is an offset in the type table, representing the corresponding type. +.I Size +is the size in bytes of a value of the given type. +The size of basic types is known and does not appear explicitly: +.B big +and +.B real +are 64 bits; all others including strings and reference types are 4 bytes. +(Strings are represented internally by a pointer.) +.PP +Each +.I "id-table" +is preceded by a count of the number of entries, followed by +an +.I id-item +for each entry in the table: +.IP +.EX +.ft I +id-table: + count \f5\en\fP id-items +id-item: + id-offset \f5:\fP id-name \f5:\fP src type \f5\en\fP +id-offset: + int +id-name: + string +count: + int +.ft R +.EE +.PP +.I Id-offset +is the number of bytes from the start of the enclosing object to the value of the +object identified by +.IR "id-name" . +.PP +An adt without a +.B pick +clause is described using an +.IR adt-item : +.IP +.EX +.ft I +adt-item: + adt-name • src size \f5\en\fP id-table +adt-name: + string +size: + int +.ft R +.EE +.PP +The +.I id-table +has an entry for every data element of +.IR "adt-name" . +.PP +If an adt has a +.B pick +clause, the adt's type table entry uses the +.B p +type character. +The invariant part of the adt is described by an +.I adt-item +(with zero +.IR size ) +and the variant clause is described by a +.I tag-table +of the following form: +.IP +.EX +.ft I +tag-table: + count \f5\en\fP tag-items +tag-item: + name \f5:\fP src size \f5\en\fP id-table + \f1|\fP name \f5:\fP src \f5\en\fP +.ft R +.EE +.PP +The +.I tag-table +describes the variants of a Limbo adt +that includes a +.B pick +clause. +The +.I name +is the +.B pick +tag for the associated alternative. +If the +.I size +and +.I id-table +are missing, the given variant has the same description +as the previous one. +.PP +A tuple's +.I id-table +contains +.I id-names +of the form +.BI t n, +where +.I n +is the 0-origin index of the item in the tuple. +.PP +.I Src +is as previously defined above in the PC table section. +.SS Fn table +The function table describes each function implemented by the Dis file. +.IP +.EX +.ft I +fn-item: + fn-pc \f5:\fP fn-name \f5\en\fP args locals return +fn-pc: + int +fn-name: + string +args, locals: + id-table +return: + type +.ft R +.EE +.PP +.I Fn-pc +is the starting pc for the Dis instructions for +.IR "fn-name" . +If the function is a member of an adt, +the member name is qualified by the adt name, so that +.I fn-name +has the form +.IB `adt-name . member-name'. +Within the +.I id-tables +for +.I args +and +.IR locals , +the +.I "id-offset" +fields give offsets relative to the function's activation frame. +Furthermore, no table entries are made for +.I args +that are declared +.B nil +(unused). +.SS Data table +The data table describes the global variables in the Dis file. It is an +.IR "id-table" , +with one entry for each global variable. +.SH SEE ALSO +.IR limbo (1), +.IR wm-deb (1), +.IR debug (2), +.IR dis (6) diff --git a/man/6/scancode b/man/6/scancode new file mode 100644 index 00000000..11c6c495 --- /dev/null +++ b/man/6/scancode @@ -0,0 +1,37 @@ +.TH SCANCODE 6 +.SH NAME +scancode \- known formats of scan codes +.SH DESCRIPTION +The +.B scancode +interface of +.IR cons (3) +provides access to scan codes of the primary keyboard. There +are as many scan code formats as keyboards. Here are some +common ones. +.SH Microsoft Windows™ Virtual Key +.PP +The identifier is +.BR emu_win32vk , +and each scan code is encoded in the two byte format specified in +.IR cons(3) . +This format is used by the Microsoft Windows™ implementation of +.IR emu (1E), +and each scan code is a +.IR "Virtual Key" . +See the appropriate Microsoft documentation for the meaning of the +codes. +.SH X11 +.PP +The identifier is +.BR emu_x11 , +and each scan code is encoded in the single byte format specified in +.IR cons(3) . +This format is used by the various Unix/X11 implementations of +.IR emu (1E), +and each scan code is an X11 +.IR keycode . +See the appropriate X11 documentation for the meaning of the +codes. +.SH "SEE ALSO" +.IR cons (3) diff --git a/man/6/sexprs b/man/6/sexprs new file mode 100644 index 00000000..d2a5a7cc --- /dev/null +++ b/man/6/sexprs @@ -0,0 +1,236 @@ +.TH SEXPRS 6 +.SH NAME +sexprs \- symbolic expressions +.SH DESCRIPTION +S-expressions (`symbolic expressions') provide a way for programs to store and +exchange tree-structured text and binary data. +The Limbo module +.IR sexprs (2) +provides the variant defined by +Rivest in Internet Draft +.L draft-rivest-sexp-00.txt +(4 May 1997), +as used for instance by the Simple Public Key Infrastructure (SPKI). +It provides a `canonical' form of S-expression, +and an `advanced' form for display. +They can convey binary data directly and efficiently, unlike some +other schemes such as XML. +The two forms are closely related and all can be read or written by +.IR sexprs (2), +including a variant sometimes used for transport on links that are not 8-bit safe. +.PP +An S-expression is either a sequence of bytes (a byte +.IR string ), +or a parenthesised list of smaller S-expressions. +All forms start with the fundamental rules below, in extended BNF: +.IP +.EX +.ft R +.ta \w'\f2simple-stringxxxxx\f1'u +\w'\ ::=\ 'u +\f2sexpr\fP ::= \f2string\fP | \f2list\fP +\f2list\fP ::= '(' \f2sexpr\fP* ')' +.EE +.DT +.PD +.PP +They give the recursive structure. +The various representations ultimately differ only in how the byte string is represented +and whether white space such as blanks or newlines can appear. +.PP +Furthermore, the definition of +.I string +is also common to all forms: +.IP +.EX +.ft R +.ta \w'\f2simple-stringxxxxx\f1'u +\w'\ ::=\ 'u +\f2string\fP ::= \f2display\fP? \f2simple-string\fP +\f2display\fP ::= '[' \f2simple-string\fP ']' +.EE +.DT +.PD +.PP +The optional bracketed +.I display +string provides information on how to present the associated byte string to a user. +(``It has no other function. Many of the MIME types work here.'') +Although supported by +.IR sexprs (2), +it is largely unused by Inferno applications and is usually left out. +The canonical and advanced forms differ in their definitions of +.IR simple-string . +They always denote sequences of 8-bit bytes, but with different syntax (encodings). +Two +.I strings +are equal iff their +.I simple-strings +encode the same byte strings (for both data and +.IR display ). +.PP +.I Canonical +form must be used when exchanging S-expressions between computers, +and when digitally signing an expression. +It is defined by the complete set of rules below: +.IP +.EX +.ft R +.ta \w'\f2simple-stringxxxxx\f1'u +\w'\ ::=\ 'u +\f2sexpr\fP ::= \f2string\fP | \f2list\fP +\f2list\fP ::= '(' \f2sexpr\fP* ')' +\f2string\fP ::= \f2display\fP? \f2simple-string\fP +\f2display\fP ::= '[' \f2simple-string\fP ']' +\f2simple-string\fP ::= \f2raw\fP +\f2raw\fP ::= \f2nbytes\fP ':' \f2byte*\fP +\f2nbytes\fP ::= \f5[1-9][0-9]\fP+ | \f50\fP +.EE +.DT +.PD +.PP +Its +.I simple-string +is a raw byte string. +The primitive +.I byte +represents an 8-bit byte. +The length of every byte string is given explicitly by a preceding decimal value +.I nbytes +(with no leading zeroes). +There is no white space. +It is `canonical' because it is uniquely defined for each S-expression. +It is efficient to parse even on small computers. +.PP +.I Advanced +form is more elaborate, and has two main differences: +not all byte strings need an explicit length, and binary +data can be represented in printable form, either using hexadecimal or base 64 encodings, +or using quoted strings (with escape sequences similar to those of Limbo or C). +Unquoted text is called a +.IR token , +and is restricted by the standard to a specific alphabet: +it must contain only letters, digits, or characters from the set +.LR "-./_:*+=" , +and must not start with a digit. +The latter restriction is imposed to allow byte counts to be distinguished from tokens without +lookahead, but has the consequence that decimal numbers must be quoted, +as must non-ASCII characters in +.IR utf (6) +encoding. +Upper- and lower-case letters are distinct. +The advanced transport syntax is defined by the complete set of rules below: +.IP +.EX +.ft R +.ta \w'\f2simple-stringxxxxx\f1'u +\w'\ ::=\ 'u +\f2sexpr\fP ::= \f2string\fP | \f2list\fP +\f2list\fP ::= '(' ( \f2sexpr\fP | \f2whitespace\fP )* ')' +\f2string\fP ::= \f2display\fP? \f2simple-string\fP +\f2display\fP ::= '[' \f2simple-string\fP ']' +\f2simple-string\fP ::= \f2raw\fP | \f2token\fP | \f2base-64\fP | \f2hexadecimal\fP | \f2quoted-string\fP +\f2raw\fP ::= \f2nbytes\fP ':' \f2byte*\fP +\f2nbytes\fP ::= \f5[1-9][0-9]\fP+ | \f50\fP +\f2token\fP ::= \f2token-start\fP \f2token-char*\fP +\f2base-64\fP ::= \f2decimal\fP? '|' ( \f2base-64-char\fP | \f2whitespace\fP )* '|' +\f2hexadecimal\fP ::= '#' ( \f2hex-digit\fP | \f2whitespace\fP )* '#' +\f2quoted-string\fP ::= \f2nbytes\fP? \f2quoted-string-body\fP +\f2quoted-string-body\fP ::= '"' \f2byte*\fP '"' +\f2token-start\fP ::= \f5[-./_:*+=a-zA-Z]\fP +\f2token-char\fP ::= \f2token-start\fP | \f5[0-9]\fP +\f2hex-digit\fP ::= \f5[0-9a-fA-F]\fP +\f2base-64-char\fP ::= \f5[a-zA-Z0-9+/=]\fP +.EE +.PD +.DT +.PP +.I Whitespace +is any sequence of blank, tab, newline or carriage-return characters; +note that it can appear only at the places shown. +The +.I bytes +in a +.I quoted-string-body +are interpreted according to the quoting rules for Limbo (or C). +That is, the bytes are enclosed in quotes, and may contain the +escape sequences for the following characters: +backspace +.RB ( \eb ), +form-feed +.RB ( \ef ), +newline +.RB ( \en ), +carriage-return +.RB ( \er ), +tab +.RB ( \et ), +and vertical tab +.RB ( \ev ), +octal escape +.BI \e ooo +(all three digits must be given), +hexadecimal escape +.BI \ex hh +(both digits must be given), +.B \e\e +for backslash, +.B \e' +for single quote, and +and \f5\e"\fP to include a quote in a string. +Note that a quoted string can have an optional +.IR nbytes , +but it gives the length of the byte string resulting +.I after +interpreting character escapes. +.PP +Both canonical and advanced forms can contain binary data verbatim. +Sometimes that is troublesome for storage or transport. +At the lexical level any +.I sexpr +can therefore be replaced by the following: +.IP +.EX +.ft R +\&'{' ( \f2base-64-char\fP | \f2whitespace\fP )* '}' +.EE +.PP +where the text between the braces is the base-64 encoding of the +.I sexpr +expressed in canonical or advanced form. +The S-expression parser will replace the sequence by its decoded, and resume +parsing at the start of that byte string. +Note the difference in syntax and interpretation from rule +.IR base-64 +above, which encodes a +.IR simple-string , +not an +.IR sexpr . +.SH EXAMPLES +The following S-expression is in canonical form: +.IP +.EX +(12:hello world!(5:inner0:)) +.EE +.PP +It is a list of two elements: the string +.BR "hello world!" , +and another list also with two elements, +the string +.BR inner +and an empty string. +All the bytes in the example are printable characters, but they could have been arbitrary binary values. +.PP +The following is an S-expression in advanced form: +.IP +.EX +(hello-world + (* "3" "5.6") + (best-of-3 (5:inner0:))) +.EE +.PP +Note that advanced form contains canonical form as a subset; +here it is used for the innermost list. +.SH SEE ALSO +.IR sexprs (2) +.PP +R. Rivest, ``S-expressions'', Network Working Group Internet Draft +(4 May 1997), +reproduced in +.BR /lib/sexp . diff --git a/man/6/translate b/man/6/translate new file mode 100644 index 00000000..f0f8895c --- /dev/null +++ b/man/6/translate @@ -0,0 +1,55 @@ +.TH TRANSLATE 6 +.SH NAME +translate \- translation dictionary +.SH SYNOPSIS +.BI /locale/dict/ app +.br +.BI /locale/ locale /dict/ app +.SH DESCRIPTION +A dictionary file provides translation text that applications can access using +.IR translate (2). +Each is a Unicode file containing a set of translations, one per line, +each line having the following syntax: +.IP +.EX +"\fIsource-text\fP"\fR [\fP (\fInote-text\fP)\fR ] [ \fP="\fItarget-text\fP" \fR ] \fP +.EE +.PP +which defines +.I target-text +as the translation for +.I source-text . +A missing translation clause defines the identity translation. +The optional +.I note-text +qualifies the context of the +.IR source-text , +when the same phrase in the source language might +translate to different phrases in the target language, +or to distinguish a particular context in the program (eg, particular menus): +For example: +.IP +.EX +"Times"(newspaper) = "La Republicca" +"Times"(timetable) = "L'orario" +"ABC"(keypad) = "abc" +.EE +.PP +Empty lines and lines beginning with +.B # +are ignored. +The quoted strings can contain the Limbo escape sequences +.B "\en" +(newline), +.B "\et" +(tab), +.B "\er" +(carriage return), +and +.B "\e\e" +(backslash). +.PP +The default locale is set by binding one or more specific locales onto +.BR /locale/dict . +.SH FILES +.B /locale/*/dict/* diff --git a/man/6/ubfa b/man/6/ubfa new file mode 100644 index 00000000..61b5705d --- /dev/null +++ b/man/6/ubfa @@ -0,0 +1,129 @@ +.TH UBFA 6 +.SH NAME +ubfa \- universal binary format for data transport +.SH DESCRIPTION +.I UBF(A) +is the data transport encoding for Armstrong's +Universal Binary Format. +It provides four primitive types: atoms (symbolic constants), integers, strings, and binary data. +There are two compound types: fixed-length tuples and variable-length lists. +.IR Ubfa (2) +provides basic support in Limbo for reading and writing streams of UBF(A)-encoded data. +.PP +The +.I input +syntax is defined by the following rules: +.IP +.EX +.ft R +.ta \w'\f2simple-xxx\f1'u +\w'\ ::=\ 'u +\f2input\fP ::= \f2item\fP* '$' +\f2item\fP ::= \f2integer\fP | \f2atom\fP | \f2string\fP | \f2binary\fP | \f2tuple\fP | \f2list\fP | \f2store\fP | \f2push\fP | \f2comment\fP | \f2tag\fP + +\f2integer\fP ::= \f5'-'\fP?\f5[0-9]\fP+ +\f2atom\fP ::= "'" (\f5[^\e']\fP | '\e\e' | "\e'")* "'" +\f2string\fP ::= '"' (\f5[^\e"]\fP | '\e\e' | '\e"')* '"' +\f2binary\fP ::= '~' \f2byte\fP* '~' # preceded by \f2integer\fP byte count + +\f2tuple\fP ::= '{' \f2item\fP* '}' +\f2list\fP ::= '#' (\f2item\fP '&')* + +\f2store\fP ::= '>' \f2reg\fP +\f2push\fP ::= \f2reg\fP +\f2reg\fP ::= \f5[^-%"~'`{}#& \en\er\et,0-9]\fP +\f2comment\fP ::= '%' (\f5[^\e%]\fP | '\e\e' | '\e%')* '%' +\f2tag\fP ::= '`' (\f5[^\e`]\fP | '\e\e' | '\e`')* '`' +.EE +.PD +.DT +.PP +White space is any sequence of blank, tab, newline or carriage-return characters, and can appear +before or after any instance of +.I item +in the grammar. +.PP +The +.I input +data is interpreted by a simple virtual machine. +The machine contains a stack of values of primitive and compound types, and a set of registers also containing +values of those types. +White space and comments are ignored. +Primitive +.IR integer , +.I atom +and +.IR string +values are pushed onto the stack as they are recognised. +Certain input bytes outside any value act as operators: +.TP +.B { +Note the current stack depth. +.TP +.B } +Pop stack values to restore the most recently noted stack depth. +Push a single value +representing a tuple of those items; the left-most value in the tuple is the last one popped +(the first in the original input stream). +.TP +.B ~ +Pop an integer value +.I n +from the stack. +Read +.I n +bytes from the input stream and push a value onto the stack that represents them. +The next byte must be the character +.BR ~ , +which is discarded. +.TP +.B # +Push a value representing an empty list onto the stack. +.TP +.B & +Pop a value +.IR v . +Pop another value +.IR l , +which must represent a list. +Push a value that represents +the list +.IB v :: l . +(Note that the items in a +.I list +therefore appear in reverse order in the input stream.) +.TP +.BI > reg +Pop the top value from the stack and store it in a register labelled by the byte +.IR reg . +.TP +.I reg +Push the value of register +.I reg +(which must be non-null) onto the stack. +.TP +.I tag +Associate the tag string with the value on top of the stack. +The +.IR ubfa (2) +implementation does so by replacing it by a special +.B Tag +tuple. +.TP +.B $ +End-of-input: there must be exactly one value on the stack, +which is the result. +.PP +Applications using UBF(A) typically take turns to exchange +.I input +values on a communication channel. +.SH SEE ALSO +.IR sexprs (2), +.IR ubfa (2), +.IR sexprs (6) +.br +J L Armstrong, ``Getting Erlang to talk to the outside world'', +.I "ACM SIGPLAN Erlang workshop 2002" , +Pittsburg, PA USA +.br +UBF web page, +.B "http://www.sics.se/~joe/ubf/" diff --git a/man/6/users b/man/6/users new file mode 100644 index 00000000..585cf188 --- /dev/null +++ b/man/6/users @@ -0,0 +1,73 @@ +.TH USERS 6 +.SH NAME +users \- kfs file server user list format +.SH DESCRIPTION +The permanent file server +.IR kfs (4) +maintains a private list of users +and groups, in +.B /adm/users +by convention. +Each line in the file has the format +.IP +.IB num : name : leader :\fImembers\fP +.PP +where +.I num +is a decimal integer, +.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 num +in a line is a number used internally by a file server; +there should be no duplicate +.IR num s +in the file. +A negative +.I num +is special: a user with a negative +.I num +cannot attach to the file server. +The file +.B /adm/users +itself is owned by user +.IR adm , +having a negative +.IR num , +and write protected to others, +so it can only be changed via console commands. +.SH "SEE ALSO" +.IR kfs (4), +.IR intro (5), +.IR stat (5), +.IR kfscmd (8) diff --git a/man/6/utf b/man/6/utf new file mode 100644 index 00000000..0e7f04d3 --- /dev/null +++ b/man/6/utf @@ -0,0 +1,84 @@ +.TH UTF 6 +.SH NAME +UTF, Unicode, ASCII \- character set and format +.SH DESCRIPTION +The Inferno 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 +Internally, programs store individual Unicode characters as 16-bit values. +However, any external manifestation of textual information, +in files or at the interface between programs, uses the +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. +Characters 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 +: Inferno programs handle +.SM ASCII +text, as well as uninterpreted byte streams, without special arrangement. +However, programs that perform semantic processing on +characters must convert from +.SM UTF +to Unicode +in order to work properly with non-\c +.SM ASCII +input. +Normally, all necessary conversions are done by the Limbo compiler +and execution environment, but sometimes more is necessary, such +as when a program receives +.SM UTF +input one byte at a time; +see +.IR sys-byte2char (2) +for routines to handle such processing. +.PP +Letting numbers be binary, +a Unicode character x +is converted to a multibyte +.SM UTF +sequence +as follows: +.EX +01. x in [00000000.0bbbbbbb] \(-> 0bbbbbbb +10. x in [00000bbb.bbbbbbbb] \(-> 110bbbbb, 10bbbbbb +11. x in [bbbbbbbb.bbbbbbbb] \(-> 1110bbbb, 10bbbbbb, 10bbbbbb +.EE +.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. +Inferno 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 the Unicode value of hexadecimal 0080. +.SH "SEE ALSO" +.IR sys-byte2char (2), +.IR "The Unicode Standard" . |