mysticmode/plan9port
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Lots of man pages.

Browse Source
This commit is contained in:
rsc
2004-04-10 18:53:55 +00:00
parent 08df2a433e
commit cfa37a7b11
152 changed files with 25407 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
man/man1/9nm.1 Normal file
View File

@@ -0,0 +1,104 @@
.TH NM 1
.SH NAME
nm \- name list (symbol table)
.SH SYNOPSIS
.B nm
[
.B -aghnsu
]
.I file ...
.SH DESCRIPTION
.I Nm
prints the name list of each executable or object
.I file
in the argument list.
If the
.I file
is an archive
(see
.IR ar (1)),
the name list of each file in the archive is printed.
If more than one file is given in the argument list,
the name of each file is printed at the beginning of each line.
.PP
Each symbol name is preceded by its hexadecimal
value (blanks if undefined)
and one of the letters
.TP
.B T
text segment symbol
.PD0
.TP
.B t
static text segment symbol
.TP
.B L
leaf function text segment symbol
.TP
.B l
static leaf function text segment symbol
.TP
.B D
data segment symbol
.TP
.B d
static data segment symbol
.TP
.B B
bss segment symbol
.TP
.B b
static bss segment symbol
.TP
.B a
automatic (local) variable symbol
.TP
.B p
function parameter symbol
.TP
.B z
source file name
.TP
.B Z
source file line offset
.TP
.B f
source file name components
.PD
.PP
The output is sorted alphabetically.
.PP
Options are:
.TP
.B -a
Print all symbols; normally only user-defined text, data,
and bss segment symbols are printed.
.TP
.B -g
Print only global
.RB ( T ,
.BR L ,
.BR D ,
.BR B )
symbols.
.TP
.B -h
Do not print file name headers with output lines.
.TP
.B -n
Sort according to the address of the symbols.
.TP
.B -s
Don't sort; print in symbol-table order.
.TP
.B -u
Print only undefined symbols.
.SH SOURCE
.B /sys/src/cmd/nm.c
.SH SEE ALSO
.IR ar (1),
.IR 2l (1),
.IR db (1),
.IR acid (1),
.IR a.out (6)

385
man/man1/9sed.1 Normal file
View File

@@ -0,0 +1,385 @@
.TH SED 1
.SH NAME
sed \- stream editor
.SH SYNOPSIS
.B sed
[
.B -n
]
[
.B -g
]
[
.B -e
.I script
]
[
.B -f
.I sfile
]
[
.I file ...
]
.SH DESCRIPTION
.I Sed
copies the named
.I files
(standard input default) to the standard output,
edited according to a script of commands.
The
.B -f
option causes the script to be taken from file
.IR sfile ;
these options accumulate.
If there is just one
.B -e
option and no
.BR -f 's,
the flag
.B -e
may be omitted.
The
.B -n
option suppresses the default output;
.B -g
causes all substitutions to be global, as if suffixed
.BR g .
.PP
A script consists of editing commands, one per line,
of the following form:
.IP
[\fIaddress\fR [\fL,\fI address\fR] ] \fIfunction\fR [\fIargument\fR ...]
.PP
In normal operation
.I sed
cyclically copies a line of input into a
.I pattern space
(unless there is something left after
a
.L D
command),
applies in sequence
all commands whose
.I addresses
select that pattern space,
and at the end of the script copies the pattern space
to the standard output (except under
.BR -n )
and deletes the pattern space.
.PP
An
.I address
is either a decimal number that counts
input lines cumulatively across files, a
.L $
that
addresses the last line of input, or a context address,
.BI / regular-expression / \f1,
in the style of
.IR regexp (6),
with the added convention that
.L \en
matches a
newline embedded in the pattern space.
.PP
A command line with no addresses selects every pattern space.
.PP
A command line with
one address selects each pattern space that matches the address.
.PP
A command line with
two addresses selects the inclusive range from the first
pattern space that matches the first address through
the next pattern space that matches
the second.
(If the second address is a number less than or equal
to the line number first selected, only one
line is selected.)
Thereafter the process is repeated, looking again for the
first address.
.PP
Editing commands can be applied to non-selected pattern
spaces by use of the negation function
.L !
(below).
.PP
An argument denoted
.I text
consists of one or more lines,
all but the last of which end with
.L \e
to hide the
newline.
Backslashes in text are treated like backslashes
in the replacement string of an
.L s
command,
and may be used to protect initial blanks and tabs
against the stripping that is done on
every script line.
.PP
An argument denoted
.I rfile
or
.I wfile
must terminate the command
line and must be preceded by exactly one blank.
Each
.I wfile
is created before processing begins.
There can be at most 120 distinct
.I wfile
arguments.
.TP \w'\fL!\ \fIfunction\fLXXX'u
.B a\e
.br
.ns
.TP
.I text
Append.
Place
.I text
on the output before
reading the next input line.
.TP
.BI b " label"
Branch to the
.B :
command bearing the
.IR label .
If
.I label
is empty, branch to the end of the script.
.TP
.B c\e
.br
.ns
.TP
.I text
Change.
Delete the pattern space.
With 0 or 1 address or at the end of a 2-address range, place
.I text
on the output.
Start the next cycle.
.TP
.B d
Delete the pattern space.
Start the next cycle.
.TP
.B D
Delete the initial segment of the
pattern space through the first newline.
Start the next cycle.
.TP
.B g
Replace the contents of the pattern space
by the contents of the hold space.
.TP
.B G
Append the contents of the hold space to the pattern space.
.TP
.B h
Replace the contents of the hold space by the contents of the pattern space.
.TP
.B H
Append the contents of the pattern space to the hold space.
.ne 3
.TP
.B i\e
.br
.ns
.TP
.I text
Insert.
Place
.I text
on the standard output.
.TP
.B n
Copy the pattern space to the standard output.
Replace the pattern space with the next line of input.
.TP
.B N
Append the next line of input to the pattern space
with an embedded newline.
(The current line number changes.)
.TP
.B p
Print.
Copy the pattern space to the standard output.
.TP
.B P
Copy the initial segment of the pattern space through
the first newline to the standard output.
.TP
.B q
Quit.
Branch to the end of the script.
Do not start a new cycle.
.TP
.BI r " rfile"
Read the contents of
.IR rfile .
Place them on the output before reading
the next input line.
.TP
.B s/\fIregular-expression\fP/\fIreplacement\fP/\fIflags
Substitute the
.I replacement
string for instances of the
.I regular-expression
in the pattern space.
Any character may be used instead of
.LR / .
For a fuller description see
.IR regexp (6).
.I Flags
is zero or more of
.RS
.TP
.B g
Global.
Substitute for all non-overlapping instances of the
.I regular expression
rather than just the
first one.
.TP
.B p
Print the pattern space if a replacement was made.
.TP
.BI w " wfile"
Write.
Append the pattern space to
.I wfile
if a replacement
was made.
.RE
.TP
.BI t " label"
Test.
Branch to the
.L :
command bearing the
.I label
if any
substitutions have been made since the most recent
reading of an input line or execution of a
.LR t .
If
.I label
is empty, branch to the end of the script.
.TP
.B w
.I wfile
.br
Write.
Append the pattern space to
.IR wfile .
.TP
.B x
Exchange the contents of the pattern and hold spaces.
.TP
.B y/\fIstring1\fP/\fIstring2\fP/
Transform.
Replace all occurrences of characters in
.I string1
with the corresponding character in
.IR string2 .
The lengths of
.I
string1
and
.I string2
must be equal.
.TP
.BI ! "function"
Don't.
Apply the
.I function
(or group, if
.I function
is
.LR { )
only to lines
.I not
selected by the address(es).
.TP
.BI : " label"
This command does nothing; it bears a
.I label
for
.B b
and
.B t
commands to branch to.
.TP
.B =
Place the current line number on the standard output as a line.
.TP
.B {
Execute the following commands through a matching
.L }
only when the pattern space is selected.
.TP
.B " "
An empty command is ignored.
.ne 4
.SH EXAMPLES
.TP
.B sed 10q file
Print the first 10 lines of the file.
.TP
.B sed '/^$/d'
Delete empty lines from standard input.
.TP
.B sed 's/UNIX/& system/g'
Replace every instance of
.L UNIX
by
.LR "UNIX system" .
.PP
.EX
sed 's/ *$// \fRdrop trailing blanks\fP
/^$/d \fRdrop empty lines\fP
s/ */\e \fRreplace blanks by newlines\fP
/g
/^$/d' chapter*
.EE
.ns
.IP
Print the files
.BR chapter1 ,
.BR chapter2 ,
etc. one word to a line.
.PP
.EX
nroff -ms manuscript | sed '
${
/^$/p \fRif last line of file is empty, print it\fP
}
//N \fRif current line is empty, append next line\fP
/^\en$/D' \fRif two lines are empty, delete the first\fP
.EE
.ns
.IP
Delete all but one of each group of empty lines from a
formatted manuscript.
.SH SOURCE
.B /sys/src/cmd/sed.c
.SH SEE ALSO
.IR ed (1),
.IR grep (1),
.IR awk (1),
.IR lex (1),
.IR sam (1),
.IR regexp (6)
.br
L. E. McMahon,
`SED \(em A Non-interactive Text Editor',
Unix Research System Programmer's Manual, Volume 2.
.SH BUGS
If input is from a pipe, buffering may consume
characters beyond a line on which a
.L q
command is executed.

683
man/man1/acme.1 Normal file
View File

@@ -0,0 +1,683 @@
.TH ACME 1
.SH NAME
acme, win, awd \- interactive text windows
.SH SYNOPSIS
.B acme
[
.B -f
.I varfont
]
[
.B -F
.I fixfont
]
[
.B -c
.I ncol
]
[
.B -b
]
[
.B -l
.I file
|
.I file
\&... ]
.LP
.B win
[
.I command
]
.LP
.B awd
[
.I label
]
.SH DESCRIPTION
.I Acme
manages windows of text that may be edited interactively or by external programs.
The interactive interface uses the keyboard and mouse; external programs
use a set of files served by
.IR acme ;
these are discussed in
.IR acme (4).
.PP
Any named
.I files
are read into
.I acme
windows before
.I acme
accepts input.
With the
.B -l
option, the state of the entire system is loaded
from
.IR file ,
which should have been created by a
.B Dump
command (q.v.),
and subsequent
.I file
names are ignored.
Plain files display as text; directories display as columnated lists of the
names of their components, as in
.B "ls -p directory|mc
except that the names of subdirectories have a slash appended.
.PP
The
.B -f
.RB ( -F )
option sets the main font, usually variable-pitch (alternate, usually fixed-pitch);
the default is
.B /lib/font/bit/lucidasans/euro.8.font
.RB ( \&.../lucm/unicode.9.font ).
Tab intervals are set to the width of 4 (or the value of
.BR $tabstop )
numeral zeros in the appropriate font.
.PP
.SS Windows
.I Acme
windows are in two parts: a one-line
.I tag
above a multi-line
.IR body .
The body typically contains an image of a file, as in
.IR sam (1),
or the output of a
program, as in an
.IR rio (1)
window.
The tag contains a number of
blank-separated words, followed by a vertical bar character, followed by anything.
The first word is the name of the window, typically the name of the associated
file or directory, and the other words are commands available in that window.
Any text may be added after the bar; examples are strings to search for or
commands to execute in that window.
Changes to the text left of the bar will be ignored,
unless the result is to change the name of the
window.
.PP
If a window holds a directory, the name (first word of the tag) will end with
a slash.
.SS Scrolling
Each window has a scroll bar to the left of the body.
The scroll bar behaves much as in
.IR sam (1)
or
.IR rio (1)
except that scrolling occurs when the button is pressed, rather than released,
and continues
as long as the mouse button is held down in the scroll bar.
For example, to scroll slowly through a file,
hold button 3 down near the top of the scroll bar. Moving the mouse
down the scroll bar speeds up the rate of scrolling.
.SS Layout
.I Acme
windows are arranged in columns. By default, it creates two columns when starting;
this can be overridden with the
.B -c
option.
Placement is automatic but may be adjusted
using the
.I layout box
in the upper left corner of each window and column.
Pressing and holding any mouse button in the box drags
the associated window or column.
For windows, just
clicking in the layout box grows the window in place: button 1
grows it a little, button 2 grows it as much as it can, still leaving all other
tags in that column visible, and button 3 takes over the column completely,
temporarily hiding other windows in the column.
(They will return
.I en masse
if any of them needs attention.)
The layout box in a window is normally white; when it is black in the center,
it records that the file is `dirty':
.I Acme
believes it is modified from its original
contents.
.PP
Tags exist at the top of each column and across the whole display.
.I Acme
pre-loads them with useful commands.
Also, the tag across the top maintains a list of executing long-running commands.
.SS Typing
The behavior of typed text is similar to that in
.IR rio (1)
except that the characters are delivered to the tag or body under the mouse; there is no
`click to type'.
(The experimental option
.B -b
causes typing to go to the most recently clicked-at or made window.)
The usual backspacing conventions apply.
As in
.IR sam (1)
but not
.IR rio ,
the ESC key selects the text typed since the last mouse action,
a feature particularly useful when executing commands.
A side effect is that typing ESC with text already selected is identical
to a
.B Cut
command
.RI ( q.v. ).
.PP
Most text, including the names of windows, may be edited uniformly.
The only exception is that the command names to the
left of the bar in a tag are maintained automatically; changes to them are repaired
by
.IR acme .
.SS "Directory context
Each window's tag names a directory: explicitly if the window
holds a directory; implicitly if it holds a regular file
(e.g. the directory
.B /adm
if the window holds
.BR /adm/users ).
This directory provides a
.I context
for interpreting file names in that window.
For example, the string
.B users
in a window labeled
.B /adm/
or
.B /adm/keys
will be interpreted as the file name
.BR /adm/users .
The directory is defined purely textually, so it can be a non-existent
directory or a real directory associated with a non-existent file
(e.g.
.BR /adm/not-a-file ).
File names beginning with a slash
are assumed to be absolute file names.
.SS Errors
Windows whose names begin with
.B -
or
.B +
conventionally hold diagnostics and other data
not directly associated with files.
A window labeled
.B +Errors
receives all diagnostics produced by
.I acme
itself.
Diagnostics from commands run by
.I acme
appear in a window named
.IB directory /+Errors
where
.I directory
is identified by the context of the command.
These error windows are created when needed.
.SS "Mouse button 1
Mouse button 1 selects text just as in
.IR sam (1)
or
.IR rio (1) ,
including the usual double-clicking conventions.
.SS "Mouse button 2
By an
action similar to selecting text with button 1,
button 2 indicates text to execute as a command.
If the indicated text has multiple white-space-separated words,
the first is the command name and the second and subsequent
are its arguments.
If button 2 is `clicked'\(emindicates a null string\(em\c
.I acme
.I expands
the indicated text to find a command to run:
if the click is within button-1-selected text,
.I acme
takes that selection as the command;
otherwise it takes the largest string of valid file name characters containing the click.
Valid file name characters are alphanumerics and
.B _
.B .
.B -
.B +
.BR / .
This behavior is similar to double-clicking with button 1 but,
because a null command is meaningless, only a single click is required.
.PP
Some commands, all by convention starting with a capital letter, are
.I built-ins
that are executed directly by
.IR acme :
.TP
.B Cut
Delete most recently selected text and place in snarf buffer.
.TP
.B Del
Delete window. If window is dirty, instead print a warning; a second
.B Del
will succeed.
.TP
.B Delcol
Delete column and all its windows, after checking that windows are not dirty.
.TP
.B Delete
Delete window without checking for dirtiness.
.TP
.B Dump
Write the state of
.I acme
to the file name, if specified, or
.B $home/acme.dump
by default.
.TP
.B Edit
Treat the argument as a text editing command in the style of
.IR sam (1).
The full
.B Sam
language is implemented except for the commands
.BR k ,
.BR n ,
.BR q ,
and
.BR ! .
The
.B =
command is slightly different: it includes the file name and
gives only the line address unless the command is explicitly
.BR =# .
The `current window' for the command is the body of the window in which the
.B Edit
command is executed.
Usually the
.B Edit
command would be typed in a tag; longer commands may be prepared in a
scratch window and executed, with
.B Edit
itself in the current window, using the 2-1 chord described below.
.TP
.B Exit
Exit
.I acme
after checking that windows are not dirty.
.TP
.B Font
With no arguments, change the font of the associated window from fixed-spaced to
proportional-spaced or
.I vice
.IR versa .
Given a file name argument, change the font of the window to that stored in the named file.
If the file name argument is prefixed by
.B var
.RB ( fix ),
also set the default proportional-spaced (fixed-spaced) font for future use to that font.
Other existing windows are unaffected.
.TP
.B Get
Load file into window, replacing previous contents (after checking for dirtiness as in
.BR Del ).
With no argument, use the existing file name of the window.
Given an argument, use that file but do not change the window's file name.
.TP
.B ID
Print window ID number
.RI ( q.v. ).
.TP
.B Incl
When opening `include' files
(those enclosed in
.BR <> )
with button 3,
.I acme
searches in directories
.B /$objtype/include
and
.BR /sys/include .
.B Incl
adds its arguments to a supplementary list of include directories, analogous to
the
.B -I
option to the compilers.
This list is per-window and is inherited when windows are created by actions in that window, so
.I Incl
is most usefully applied to a directory containing relevant source.
With no arguments,
.I Incl
prints the supplementary list.
This command is largely superseded by plumbing
(see
.IR plumb (6)).
.TP
.B Kill
Send a
.B kill
note to
.IR acme -initiated
commands named as arguments.
.TP
.B Local
When prefixed to a command
run the
command in the same file name space and environment variable group as
.IR acme .
The environment of the command
is restricted but is sufficient to run
.IR bind (1),
.IR 9fs
(see
.IR srv (4)),
.IR import (4),
etc.,
and to set environment variables such as
.BR $objtype .
.TP
.B Load
Restore the state of
.I acme
from a file (default
.BR $home/acme.dump )
created by the
.B Dump
command.
.TP
.B Look
Search in body for occurrence of literal text indicated by the argument or,
if none is given, by the selected text in the body.
.TP
.B New
Make new window. With arguments, load the named files into windows.
.TP
.B Newcol
Make new column.
.TP
.B Paste
Replace most recently selected text with contents of snarf buffer.
.TP
.B Put
Write window to the named file.
With no argument, write to the file named in the tag of the window.
.TP
.B Putall
Write all dirty windows whose names indicate existing regular files.
.TP
.B Redo
Complement of
.BR Undo .
.TP
.B Send
Append selected text or snarf buffer to end of body; used mainly with
.IR win .
.TP
.B Snarf
Place selected text in snarf buffer.
.TP
.B Sort
Arrange the windows in the column from top to bottom in lexicographical
order based on their names.
.TP
.B Tab
Set the width of tab stops for this window to the value of the argument, in units of widths of the zero
character.
With no arguments, it prints the current value.
.TP
.B Undo
Undo last textual change or set of changes.
.TP
.B Zerox
Create a copy of the window containing most recently selected text.
.PP
A common place to store text for commands is in the tag; in fact
.I acme
maintains a set of commands appropriate to the state of the window
to the left of the bar in the tag.
.PP
If the text indicated with button 2 is not a recognized built-in, it is executed as
a shell command. For example, indicating
.B date
with button 2 runs
.IR date (1).
The standard
and error outputs of commands are sent to the error window associated with
the directory from which the command was run, which will be created if
necessary.
For example, in a window
.B /adm/users
executing
.B pwd
will produce the output
.B /adm
in a (possibly newly-created) window labeled
.BR /adm/+Errors ;
in a window containing
.B /sys/src/cmd/sam/sam.c
executing
.B mk
will run
.IR mk (1)
in
.BR /sys/src/cmd/sam ,
producing output in a window labeled
.BR /sys/src/cmd/sam/+Errors .
The environment of such commands contains the variable
.B $%
with value set to the filename of the window in which the command is run.
.SS "Mouse button 3
Pointing at text with button 3 instructs
.I acme
to locate or acquire the file, string, etc. described by the indicated text and
its context.
This description follows the actions taken when
button 3 is released after sweeping out some text.
In the description,
.I text
refers to the text of the original sweep or, if it was null, the result of
applying the same expansion rules that apply to button 2 actions.
.PP
If the text names an existing window,
.I acme
moves the mouse cursor to the selected text in the body of that window.
If the text names an existing file with no associated window,
.I acme
loads the file into a new window and moves the mouse there.
If the text is a file name contained in angle brackets,
.I acme
loads the indicated include file from the directory appropriate to the
suffix of the file name of the window holding the text.
(The
.B Incl
command adds directories to the standard list.)
.PP
If the text begins with a colon, it is taken to be an address, in
the style of
.IR sam (1),
within the body of the window containing the text.
The address is evaluated, the resulting text highlighted, and the mouse moved to it.
Thus, in
.IR acme ,
one must type
.B :/regexp
or
.B :127
not just
.B /regexp
or
.BR 127 .
(There is an easier way to locate literal text; see below.)
.PP
If the text is a file name followed by a colon and an address,
.I acme
loads the file and evaluates the address. For example, clicking button 3 anywhere
in the text
.B file.c:27
will open
.BR file.c ,
select line
27, and put the mouse at the beginning of the line. The rules about Error
files, directories, and so on all combine to make this an efficient way to
investigate errors from compilers, etc.
.PP
If the text is not an address or file, it is taken to
be literal text, which is then searched for in the body of the window
in which button 3 was clicked. If a match is found, it is selected and the mouse is
moved there. Thus, to search for occurrences of a word in a file,
just click button 3 on the word. Because of the rule of using the
selection as the button 3 action, subsequent clicks will find subsequent
occurrences without moving the mouse.
.PP
In all these actions, the mouse motion is not done if the text is a null string
within a non-null selected string in the tag, so that (for example) complex regular expressions
may be selected and applied repeatedly to the
body by just clicking button 3 over them.
.SS "Chords of mouse buttons
Several operations are bound to multiple-button actions.
After selecting text, with button 1 still down, pressing button 2
executes
.B Cut
and button 3 executes
.BR Paste .
After clicking one button, the other undoes
the first; thus (while holding down button 1) 2 followed by 3 is a
.B Snarf
that leaves the file undirtied;
3 followed by 2 is a no-op.
These actions also apply to text selected by double-clicking because
the double-click expansion is made when the second
click starts, not when it ends.
.PP
Commands may be given extra arguments by a mouse chord with buttons 2 and 1.
While holding down button 2 on text to be executed as a command, clicking button 1
appends the text last pointed to by button 1 as a distinct final argument.
For example, to search for literal
.B text
one may execute
.B Look text
with button 2 or instead point at
.B text
with button 1 in any window, release button 1,
then execute
.BR Look ,
clicking button 1 while 2 is held down.
.PP
When an external command (e.g.
.IR echo (1))
is executed this way, the extra argument is passed as expected and an
environment variable
.B $acmeaddr
is created that holds, in the form interpreted by button 3,
the fully-qualified address of the extra argument.
.SS "Support programs
.I Win
creates a new
.I acme
window and runs a
.I command
(default
.BR /bin/rc )
in it, turning the window into something analogous to an
.IR rio (1)
window.
Executing text in a
.I win
window with button
2 is similar to using
.BR Send .
.PP
.I Awd
loads the tag line of its window with the directory in which it's running, suffixed
.BI - label
(default
.BR rc );
it is
intended to be executed by a
.B cd
function for use in
.I win
windows. An example definition is
.EX
fn cd { builtin cd $1 && awd $sysname }
.EE
.SS "Applications and guide files
In the directory
.B /acme
live several subdirectories, each corresponding to a program or
set of related programs that employ
.I acme's
user interface.
Each subdirectory includes source, binaries, and a
.B readme
file for further information.
It also includes a
.BR guide ,
a text file holding sample commands to invoke the programs.
The idea is to find an example in the guide that best matches
the job at hand, edit it to suit, and execute it.
.PP
Whenever a command is executed by
.IR acme ,
the default search path includes the directory of the window containing
the command and its subdirectory
.BR $cputype .
The program directories in
.B /acme
contain appropriately labeled subdirectories of binaries,
so commands named
in the guide files will be found automatically when run.
Also,
.I acme
binds the directories
.B /acme/bin
and
.B /acme/bin/$cputype
to the end of
.B /bin
when it starts; this is where
.IR acme -specific
programs such as
.I win
and
.I awd
reside.
.SH FILES
.TF $home/acme.dump
.TP
.B $home/acme.dump
default file for
.B Dump
and
.BR Load ;
also where state is written if
.I acme
dies or is killed unexpectedly, e.g. by deleting its window.
.TP
.B /acme/*/guide
template files for applications
.TP
.B /acme/*/readme
informal documentation for applications
.TP
.B /acme/*/src
source for applications
.TP
.B /acme/*/mips
MIPS-specific binaries for applications
.SH SOURCE
.B /sys/src/cmd/acme
.br
.B /acme/bin/source/win
.br
.B /sys/src/cmd/awd.c
.SH SEE ALSO
.IR acme (4)
.br
Rob Pike,
.I
Acme: A User Interface for Programmers.
.SH BUGS
With the
.B -l
option or
.B Load
command,
the recreation of windows under control of external programs
such as
.I win
is just to rerun the command; information may be lost.

161
man/man1/ascii.1 Normal file
View File

@@ -0,0 +1,161 @@
.TH ASCII 1
.SH NAME
ascii, unicode \- interpret ASCII, Unicode characters
.SH SYNOPSIS
.B ascii
[
.B -8
]
[
.BI -oxdb n
]
[
.B -nct
]
[
.I text
]
.PP
.B unicode
[
.B -nt
]
.IB hexmin - hexmax
.PP
.B unicode
[
.B -t
]
.I hex
[
\&...
]
.PP
.B unicode
[
.B -n
]
.I characters
.PP
.B look
.I hex
.B /lib/unicode
.SH DESCRIPTION
.I Ascii
prints the
.SM ASCII
values corresponding to characters and
.I vice
.IR versa ;
under the
.B -8
option, the
.SM ISO
Latin-1 extensions (codes 0200-0377) are included.
The values are interpreted in a settable numeric base;
.B -o
specifies octal,
.B -d
decimal,
.B -x
hexadecimal (the default), and
.BI -b n
base
.IR n .
.PP
With no arguments,
.I ascii
prints a table of the character set in the specified base.
Characters of
.I text
are converted to their
.SM ASCII
values, one per line. If, however, the first
.I text
argument is a valid number in the specified base, conversion
goes the opposite way.
Control characters are printed as two- or three-character mnemonics.
Other options are:
.TP
.B -n
Force numeric output.
.TP
.B -c
Force character output.
.TP
.B -t
Convert from numbers to running text; do not interpret
control characters or insert newlines.
.PP
.I Unicode
is similar; it converts between
.SM UTF
and character values from the Unicode Standard (see
.IR utf (6)).
If given a range of hexadecimal numbers,
.I unicode
prints a table of the specified Unicode characters \(em their values and
.SM UTF
representations.
Otherwise it translates from
.SM UTF
to numeric value or vice versa,
depending on the appearance of the supplied text;
the
.B -n
option forces numeric output to avoid ambiguity with numeric characters.
If converting to
.SM UTF ,
the characters are printed one per line unless the
.B -t
flag is set, in which case the output is a single string
containing only the specified characters.
Unlike
.IR ascii ,
.I unicode
treats no characters specially.
.PP
The output of
.I ascii
and
.I unicode
may be unhelpful if the characters printed are not available in the current font.
.PP
The file
.B /lib/unicode
contains a
table of characters and descriptions, sorted in hexadecimal order,
suitable for
.IR look (1)
on the lower case
.I hex
values of characters.
.SH EXAMPLES
.TP
.B "ascii -d"
Print the
.SM ASCII
table base 10.
.TP
.B "unicode p"
Print the hex value of `p'.
.TP
.B "unicode 2200-22f1"
Print a table of miscellaneous mathematical symbols.
.TP
.B "look 039 /lib/unicode"
See the start of the Greek alphabet's encoding in the Unicode Standard.
.SH FILES
.TF /lib/unicode
.TP
.B /lib/unicode
table of characters and descriptions.
.SH SOURCE
.B /sys/src/cmd/ascii.c
.br
.B /sys/src/cmd/unicode.c
.SH "SEE ALSO"
.IR look (1)
.IR tcs (1),
.IR utf (6),
.IR font (6)

35
man/man1/basename.1 Normal file
View File

@@ -0,0 +1,35 @@
.TH BASENAME 1
.SH NAME
basename \- strip file name affixes
.SH SYNOPSIS
.B basename
[
.B -d
]
.I string
[
.I suffix
]
.SH DESCRIPTION
.PP
.I Basename
deletes any prefix ending in slash
.RB ( / )
and the
.IR suffix ,
if present in
.IR string ,
from
.IR string ,
and prints the result on the standard output.
.PP
The
.B -d
option instead prints the directory component,
that is,
.I string
up to but not including the final slash.
If the string contains no slash,
a period and newline are printed.
.SH SOURCE
.B /sys/src/cmd/basename.c

46
man/man1/cal.1 Normal file
View File

@@ -0,0 +1,46 @@
.TH CAL 1
.SH NAME
cal \- print calendar
.SH SYNOPSIS
.B cal
[
.I month
]
[
.I year
]
.SH DESCRIPTION
.I Cal
prints a calendar.
.I Month
is either a number from 1 to 12,
a lower case month name,
or a lower case three-letter prefix of a month name.
.I Year
can be between 1
and 9999.
If either
.I month
or
.I year
is omitted, the current month or year is used.
If only one argument is given, and it is a number larger than 12,
a calendar for all twelve months of the given year is produced;
otherwise a calendar for just one month is printed.
The calendar
produced is that for England and her colonies.
.PP
Try
.EX
cal sep 1752
.EE
.SH SOURCE
.B /sys/src/cmd/cal.c
.SH BUGS
The year is always considered to start in January even though this
is historically naive.
.br
Beware that
.L "cal 90"
refers to the early Christian era,
not the 20th century.

53
man/man1/calendar.1 Normal file
View File

@@ -0,0 +1,53 @@
.TH CALENDAR 1
.SH NAME
calendar \- print upcoming events
.SH SYNOPSIS
.B calendar
[
.B \-y
]
[
.B \-p days
]
[
.I file ...
]
.SH DESCRIPTION
.I Calendar
reads the named files, default
.BR /usr/$user/lib/calendar ,
and writes to standard output any lines
containing today's or tomorrow's date.
Examples of recognized date formats are
"4/11",
"April 11",
"Apr 11",
"11 April",
and
"11 Apr".
All comparisons are case insensitive.
.PP
If the
.B \-y
flag is given, an attempt is made to match on year too. In this case,
dates of the forms listed above will be accepted if they are followed
by the current year (or last two digits thereof) or not a year —
digits not followed by white space or non-digits.
.PP
If the
.B \-p
flag is given, its argument is the number of days ahead to match
dates. This flag is not repeatable, and it performs no special
processing at the end of the week.
.PP
On Friday and Saturday, events through Monday are printed.
.PP
To have your calendar mailed to you every day, use
.IR cron (8).
.SH FILES
.TF /usr/$user/lib/calendar
.TP
.B /usr/$user/lib/calendar
personal calendar
.SH SOURCE
.B /sys/src/cmd/calendar.c

86
man/man1/cat.1 Normal file
View File

@@ -0,0 +1,86 @@
.TH CAT 1
.SH NAME
cat, read \- catenate files
.SH SYNOPSIS
.B cat
[
.I file ...
]
.br
.B read
[
.B -m
] [
.B -n
.I nline
] [
.I file ...
]
.SH DESCRIPTION
.I Cat
reads each
.I file
in sequence and writes it on the standard output.
Thus
.IP
.L
cat file
.LP
prints a file and
.IP
.L
cat file1 file2 >file3
.LP
concatenates the first two files and places the result
on the third.
.PP
If no
.I file
is given,
.I cat
reads from the standard input.
Output is buffered in blocks matching the input.
.PP
.I Read
copies to standard output exactly one line from the named
.IR file ,
default standard input.
It is useful in interactive
.IR rc (1)
scripts.
.PP
The
.B -m
flag causes it to continue reading and writing multiple lines until end of file;
.B -n
causes it to read no more than
.I nline
lines.
.PP
Read always executes a single
.B write
for each line of input, which can be helpful when
preparing input to programs that expect line-at-a-time data.
It never reads any more data from the input than it prints to the output.
.SH SOURCE
.B /sys/src/cmd/cat.c
.br
.B /sys/src/cmd/read.c
.SH SEE ALSO
.IR cp (1)
.SH DIAGNOSTICS
.I Read
exits with status
.B eof
on end of file or, in the
.B -n
case, if it doesn't read
.I nlines
lines.
.SH BUGS
Beware of
.L "cat a b >a"
and
.LR "cat a b >b" ,
which
destroy input files before reading them.

32
man/man1/cleanname.1 Normal file
View File

@@ -0,0 +1,32 @@
.TH CLEANNAME 1
.SH NAME
cleanname \- clean a path name
.SH SYNOPSIS
.B cleanname
[
.B -d
.I pwd
]
.I names ...
.SH DESCRIPTION
For each file name argument,
.IR cleanname ,
by lexical processing only,
prints the shortest equivalent string that names the same
(possibly hypothetical) file.
It eliminates multiple and trailing slashes, and it lexically
interprets
.B .
and
.B ..
directory components in the name.
If the
.B -d
option is present,
unrooted names are prefixed with
.IB pwd /
before processing.
.SH SOURCE
.B /sys/src/cmd/cleanname.c
.SH SEE ALSO
.IR cleanname (2).

57
man/man1/cmp.1 Normal file
View File

@@ -0,0 +1,57 @@
.TH CMP 1
.SH NAME
cmp \- compare two files
.SH SYNOPSIS
.B cmp
[
.B -lsL
]
.I file1 file2
[
.I offset1
[
.I offset2
]
]
.SH DESCRIPTION
The two files are
compared.
A diagnostic results if the contents differ, otherwise
there is no output.
.PP
The options are:
.TP
.B l
Print the byte number (decimal) and the
differing bytes (hexadecimal) for each difference.
.TP
.B s
Print nothing for differing files,
but set the exit status.
.TP
.B L
Print the line number of the first differing byte.
.PP
If offsets are given,
comparison starts at the designated byte position
of the corresponding file.
Offsets that begin with
.B 0x
are hexadecimal;
with
.BR 0 ,
octal; with anything else, decimal.
.SH SOURCE
.B /sys/src/cmd/cmp.c
.SH "SEE ALSO"
.IR diff (1)
.SH DIAGNOSTICS
If a file is inaccessible or missing, the exit status is
.LR open .
If the files are the same, the exit status is empty (true).
If they are the same except that one is longer than the other, the exit status is
.LR EOF .
Otherwise
.I cmp
reports the position of the first disagreeing byte and the exit status is
.LR differ .

47
man/man1/comm.1 Normal file
View File

@@ -0,0 +1,47 @@
.TH COMM 1
.CT 1 files
.SH NAME
comm \- select or reject lines common to two sorted files
.SH SYNOPSIS
.B comm
[
.B -123
]
.I file1 file2
.SH DESCRIPTION
.I Comm
reads
.I file1
and
.IR file2 ,
which are in lexicographical order,
and produces a three column output: lines only in
.IR file1 ;
lines only in
.IR file2 ;
and lines in both files.
The file name
.L -
means the standard input.
.PP
Flag
.LR 1 ,
.LR 2 ,
or
.LR 3
suppresses printing of the corresponding
column.
.SH EXAMPLE
.TP
.EX
comm -12 file1 file2
.EE
.IP
Print lines common to two sorted files.
.SH SOURCE
.B /sys/src/cmd/comm.c
.SH "SEE ALSO"
.IR sort (1),
.IR cmp (1),
.IR diff (1),
.IR uniq (1)

58
man/man1/date.1 Normal file
View File

@@ -0,0 +1,58 @@
.TH DATE 1
.SH NAME
date, clock \- date and time
.SH SYNOPSIS
.B date
[
.I option
] [
.I seconds
]
.br
.B clock
.SH DESCRIPTION
Print the date, in the format
.PP
.B
Tue Aug 16 17:03:52 CDT 1977
.PP
The options are
.TP
.B -u
Report Greenwich Mean Time (GMT) rather than local time.
.TP
.B -n
Report the date as the number of seconds since the
epoch, 00:00:00 GMT, January 1, 1970.
.PP
The conversion from Greenwich Mean Time to local time depends on the
.B $timezone
environment variable; see
.IR ctime (2).
.PP
If the optional argument
.I seconds
is present, it is used as the time to convert rather than
the real time.
.SH FILES
.TF /adm/timezone/local
.TP
.B /env/timezone
Current timezone name and adjustments.
.TP
.B /adm/timezone
A directory containing timezone tables.
.TP
.B /adm/timezone/local
Default timezone file, copied by
.IR init (8)
into
.BR /env/timezone .
.PD
.PP
.I Clock
draws a simple analog clock in its window.
.SH SOURCE
.B /sys/src/cmd/date.c
.br
.B /sys/src/cmd/clock.c

257
man/man1/dc.1 Normal file
View File

@@ -0,0 +1,257 @@
.TH DC 1
.SH NAME
dc \- desk calculator
.SH SYNOPSIS
.B dc
[
.I file
]
.SH DESCRIPTION
.I Dc
is an arbitrary precision desk calculator.
Ordinarily it operates on decimal integers,
but one may specify an input base, output base,
and a number of fractional digits to be maintained.
The overall structure of
.I dc
is
a stacking (reverse Polish) calculator.
If an argument is given,
input is taken from that file until its end,
then from the standard input.
The following constructions are recognized:
.TP
number
The value of the number is pushed on the stack.
A number is an unbroken string of the digits
.B 0-9A-F
or
.BR 0-9a-f .
A hexadecimal number beginning with a lower case
letter must be preceded by a zero to distinguish it
from the command associated with the letter.
It may be preceded by an underscore
.B _
to input a
negative number.
Numbers may contain decimal points.
.TP
.L
+ - / * % ^
Add
.LR + ,
subtract
.LR - ,
multiply
.LR * ,
divide
.LR / ,
remainder
.LR % ,
or exponentiate
.L ^
the top two values on the stack.
The two entries are popped off the stack;
the result is pushed on the stack in their place.
Any fractional part of an exponent is ignored.
.TP
.BI s x
.br
.ns
.TP
.BI S x
Pop the top of the stack and store into
a register named
.IR x ,
where
.I x
may be any character.
Under operation
.B S
register
.I x
is treated as a stack and the value is pushed on it.
.TP
.BI l x
.br
.ns
.TP
.BI L x
Push the value in register
.I x
onto the stack.
The register
.I x
is not altered.
All registers start with zero value.
Under operation
.B L
register
.I x
is treated as a stack and its top value is popped onto the main stack.
.TP
.B d
Duplicate the
top value on the stack.
.TP
.B p
Print the top value on the stack.
The top value remains unchanged.
.B P
interprets the top of the stack as an
text
string,
removes it, and prints it.
.TP
.B f
Print the values on the stack.
.TP
.B q
.br
.ns
.TP
.B Q
Exit the program.
If executing a string, the recursion level is
popped by two.
Under operation
.B Q
the top value on the stack is popped and the string execution level is popped
by that value.
.TP
.B x
Treat the top element of the stack as a character string
and execute it as a string of
.I dc
commands.
.TP
.B X
Replace the number on the top of the stack with its scale factor.
.TP
.B "[ ... ]"
Put the bracketed
text
string on the top of the stack.
.TP
.PD0
.BI < x
.TP
.BI > x
.TP
.BI = x
.PD
Pop and compare the
top two elements of the stack.
Register
.I x
is executed if they obey the stated
relation.
.TP
.B v
Replace the top element on the stack by its square root.
Any existing fractional part of the argument is taken
into account, but otherwise the scale factor is ignored.
.TP
.B !
Interpret the rest of the line as a shell command.
.TP
.B c
Clear the stack.
.TP
.B i
The top value on the stack is popped and used as the
number base for further input.
.TP
.B I
Push the input base on the top of the stack.
.TP
.B o
The top value on the stack is popped and used as the
number base for further output.
In bases larger than 10, each `digit' prints as a group of decimal digits.
.TP
.B O
Push the output base on the top of the stack.
.TP
.B k
Pop the top of the stack, and use that value as
a non-negative scale factor:
the appropriate number of places
are printed on output,
and maintained during multiplication, division, and exponentiation.
The interaction of scale factor,
input base, and output base will be reasonable if all are changed
together.
.TP
.B z
Push the stack level onto the stack.
.TP
.B Z
Replace the number on the top of the stack with its length.
.TP
.B ?
A line of input is taken from the input source (usually the terminal)
and executed.
.TP
.B "; :"
Used by
.I bc
for array operations.
.PP
The scale factor set by
.B k
determines how many digits are kept to the right of
the decimal point.
If
.I s
is the current scale factor,
.I sa
is the scale of the first operand,
.I sb
is the scale of the second,
and
.I b
is the (integer) second operand,
results are truncated to the following scales.
.IP
.nf
\fL+\fR,\fL-\fR max(\fIsa,sb\fR)
\fL*\fR min(\fIsa\fR+\fIsb \fR, max\fR(\fIs,sa,sb\fR))
\fL/\fI s
\fL%\fR so that dividend = divisor*quotient + remainder; remainder has sign of dividend
\fL^\fR min(\fIsa\fR\(mu|\fIb\fR|, max(\fIs,sa\fR))
\fLv\fR max(\fIs,sa\fR)
.fi
.SH EXAMPLES
.EX
[la1+dsa*pla10>y]sy
0sa1
lyx
.EE
.ns
.IP
Print the first ten values of
.IR n !
.SH SOURCE
.B /sys/src/cmd/dc.c
.SH "SEE ALSO"
.IR bc (1),
.IR hoc (1)
.SH DIAGNOSTICS
.I x
.LR "is unimplemented" ,
where
.I x
is an octal number: an internal error.
.br
`Out of headers'
for too many numbers being kept around.
.br
`Nesting depth'
for too many levels of nested execution.
.SH BUGS
When the input base exceeds 16,
there is no notation for digits greater than
.BR F .
.PP
Past its time.

117
man/man1/deroff.1 Normal file
View File

@@ -0,0 +1,117 @@
.TH DEROFF 1
.SH NAME
deroff, delatex \- remove formatting requests
.SH SYNOPSIS
.B deroff
[
.I option ...
]
.I file ...
.PP
.B delatex
.I file
.SH DESCRIPTION
.I Deroff
reads each file in sequence
and removes all
.I nroff
and
.IR troff (1)
requests and non-text arguments, backslash constructions,
and constructs of preprocessors such as
.IR eqn (1),
.IR pic (1),
and
.IR tbl (1).
Remaining text is written on the standard output.
.I Deroff
follows files included by
.L .so
and
.L .nx
commands;
if a file has already been included, a
.L .so
for that file is ignored and a
.L .nx
terminates execution.
If no input file is given,
.I deroff
reads from standard input.
.PP
The options are
.TP
.B -w
Output a word list, one `word' (string of letters, digits, and
properly embedded ampersands and apostrophes,
beginning with a letter) per line.
Other characters are skipped.
Otherwise, the output follows the original, with the deletions mentioned above.
.TP
.B -_
Like
.BR -w ,
but consider underscores to be alphanumeric rather than punctuation.
.TP
.B -i
Ignore
.L .so
and
.L .nx
requests.
.TP
.BR -ms
.PD0
.TP
.B -mm
Remove titles, attachments, etc., as well as ordinary
.IR troff
constructs, from
.IR ms (6)
or
.I mm
documents.
.PD
.TP
.B -ml
Same as
.BR -mm ,
but remove lists as well.
.PP
.I Delatex
does for
.I tex
and
.I latex
(see
.IR tex (1))
files what
.B deroff -wi
does for
.I troff
files.
.SH SOURCE
.B /sys/src/cmd/deroff.c
.br
.B /sys/src/cmd/tex/local/delatex.c
.SH "SEE ALSO"
.IR troff (1),
.IR tex (1),
.IR spell (1)
.SH BUGS
These filters are not complete interpreters of
.I troff
or
.IR tex .
For example, macro definitions containing
.L \e$
cause chaos in
.IR deroff
when the popular
.L $$
delimiters for
.I eqn
are in effect.
.br
Text inside macros is emitted at place of
definition, not place of call.

163
man/man1/dict.1 Normal file
View File

@@ -0,0 +1,163 @@
.TH DICT 7
.SH NAME
dict \- dictionary browser
.SH SYNOPSIS
.B dict
[
.B -k
]
[
.B -d
.I dictname
]
[
.B -c
.I command
]
[
.I pattern
]
.SH DESCRIPTION
.I Dict
is a dictionary browser.
If a
.I pattern
is given on the command line,
.I dict
prints all matching entries;
otherwise it repeatedly accepts and executes commands.
The options are
.TF -d\ \fIdictname\fP
.TP
.BI -d " dictname"
Use the given dictionary.
The default is
.BR oed ,
the second edition of the Oxford English Dictionary.
A list of available dictionaries is printed by option
.BR -d? .
.TP
.BI -c " command"
Execute one command and quit.
The command syntax is described below.
.TP
.B -k
Print a pronunciation key.
.PD
.PP
Patterns are regular expressions (see
.IR regexp (6)),
with an implicit leading
.L ^
and trailing
.LR $ .
Patterns are matched against an index of headwords and variants,
to form a `match set'.
By default, both patterns and the index are folded:
upper case characters are mapped into their lower case equivalents,
and Latin accented characters are mapped into their non-accented
equivalents.
In interactive mode, there is always a `current match set'
and a `current entry' within the match set.
Commands can change either or both, as well as print the entries
or information about them.
.PP
Commands have an address followed by a command letter.
Addresses have the form:
.TF /\fIre\fP/.\fIn\fP
.TP
.BI / re /
Set the match set to all entries matching the regular expression
.IR re ,
sorted in dictionary order.
Set the current entry to the first of the match set.
.TP
.BI ! re !
Like
.BI / re /
but use exact matching, i.e., without case and accent folding.
.TP
.I n
An integer
.I n
means change the current entry to the
.IR n th
of the current match set.
.TP
.BI # n
The integer
.I n
is an absolute byte offset into the raw dictionary.
(See the
.B A
command, below.)
.TP
.IB addr +
After setting the match set and current entry according to
.IR addr ,
change the match set and current entry to be the next entry
in the dictionary (not necessarily in the match set) after
the current entry.
.TP
.IB addr -
Like
.IB addr +
but go to previous dictionary entry.
.PD
.PP
The command letters come in pairs: a lower case and the
corresponding upper case letter.
The lower case version prints something about the current
entry only, and advances the current entry to the next
in the match set (wrapping around to the beginning after
the last).
The upper case version prints something about all of the
match set and resets the current entry to the beginning of
the set.
.TF \fLa,A\fP
.TP
.BR p , P
Print the whole entry.
.TP
.BR h , H
Print only the headword(s) of the entry.
.TP
.BR a , A
Print the dictionary byte offset of the entry.
.TP
.BR r , R
Print the whole entry in raw format (without translating
special characters, etc.).
.PD
.PP
If no command letter is given for the first command,
.B H
is assumed.
After an
.BR H ,
the default command is
.BR p .
Otherwise, the default command is the previous command.
.SH FILES
.B /lib/dict/oed2
.br
.B /lib/dict/oed2index
.br
Other files in
.BR /lib .
.SH "SEE ALSO"
.IR regexp (6)
.SH SOURCE
.B /sys/src/cmd/dict
.SH BUGS
A font with wide coverage of the Unicode Standard
should be used for best results.
(Try
.BR /lib/font/bit/pelm/unicode.9.font .)
.br
If the
.I pattern
doesn't begin with
a few literal characters, matching takes a long time.
.br
The dictionaries are not distributed outside Bell Labs.

155
man/man1/diff.1 Normal file
View File

@@ -0,0 +1,155 @@
.TH DIFF 1
.SH NAME
diff \- differential file comparator
.SH SYNOPSIS
.B diff
[
.B -efmnbwr
] file1 ... file2
.SH DESCRIPTION
.I Diff
tells what lines must be changed in two files to bring them
into agreement.
If one file
is a directory,
then a file in that directory with basename the same as that of
the other file is used.
If both files are directories, similarly named files in the
two directories are compared by the method of
.I diff
for text
files and
.IR cmp (1)
otherwise.
If more than two file names are given, then each argument is compared
to the last argument as above.
The
.B -r
option causes
.I diff
to process similarly named subdirectories recursively.
When processing more than one file,
.I diff
prefixes file differences with a single line
listing the two differing files, in the form of
a
.I diff
command line.
The
.B -m
flag causes this behavior even when processing single files.
.PP
The normal output contains lines of these forms:
.IP "" 5
.I n1
.B a
.I n3,n4
.br
.I n1,n2
.B d
.I n3
.br
.I n1,n2
.B c
.I n3,n4
.PP
These lines resemble
.I ed
commands to convert
.I file1
into
.IR file2 .
The numbers after the letters pertain to
.IR file2 .
In fact, by exchanging `a' for `d' and reading backward
one may ascertain equally how to convert
.I file2
into
.IR file1 .
As in
.IR ed ,
identical pairs where
.I n1
=
.I n2
or
.I n3
=
.I n4
are abbreviated as a single number.
.PP
Following each of these lines come all the lines that are
affected in the first file flagged by `<',
then all the lines that are affected in the second file
flagged by `>'.
.PP
The
.B -b
option causes
trailing blanks (spaces and tabs) to be ignored
and other strings of blanks to compare equal.
The
.B -w
option causes all white-space to be removed from input lines
before applying the difference algorithm.
.PP
The
.B -n
option prefixes each range with
.IB file : \fR
and inserts a space around the
.BR a ,
.BR c ,
and
.B d
verbs.
The
.B -e
option produces a script of
.I "a, c"
and
.I d
commands for the editor
.IR ed ,
which will recreate
.I file2
from
.IR file1 .
The
.B -f
option produces a similar script,
not useful with
.IR ed ,
in the opposite order. It may, however, be
useful as input to a stream-oriented post-processor.
.PP
Except in rare circumstances,
.I diff
finds a smallest sufficient set of file
differences.
.SH FILES
.B /tmp/diff[12]
.SH SOURCE
.B /sys/src/cmd/diff
.SH "SEE ALSO"
.IR cmp (1),
.IR comm (1),
.IR ed (1)
.SH DIAGNOSTICS
Exit status is the empty string
for no differences,
.L some
for some,
and
.L error
for trouble.
.SH BUGS
Editing scripts produced under the
.BR -e " or"
.BR -f " option are naive about"
creating lines consisting of a single `\fB.\fR'.
.br
When running
.I diff
on directories, the notion of what is a text
file is open to debate.

26
man/man1/echo.1 Normal file
View File

@@ -0,0 +1,26 @@
.TH ECHO 1
.SH NAME
echo \- print arguments
.SH SYNOPSIS
.B echo
[
.B -n
]
[
.I arg ...
]
.SH DESCRIPTION
.I Echo
writes its arguments separated by blanks and terminated by
a newline on the standard output.
Option
.B -n
suppresses the newline.
.SH SOURCE
.B /sys/src/cmd/echo.c
.SH DIAGNOSTICS
If
.I echo
draws an error while writing to standard output, the exit status is
.LR "write error" .
Otherwise the exit status is empty.

683
man/man1/ed.1 Normal file
View File

@@ -0,0 +1,683 @@
.TH ED 1
.SH NAME
ed \- text editor
.SH SYNOPSIS
.B ed
[
.B -
]
[
.B -o
]
[
.I file
]
.SH DESCRIPTION
.I Ed
is a venerable text editor.
.PP
If a
.I file
argument is given,
.I ed
simulates an
.L e
command (see below) on that file:
it is read into
.I ed's
buffer so that it can be edited.
The options are
.TP
.B -
Suppress the printing
of character counts by
.LR e ,
.LR r ,
and
.L w
commands and of the confirming
.L !
by
.L !
commands.
.TP
.B -o
(for output piping)
Write all output to the standard error file except writing by
.L w
commands.
If no
.I file
is given, make
.B /fd/1
the remembered file; see the
.L e
command below.
.PP
.I Ed
operates on a `buffer', a copy of the file it is editing;
changes made
in the buffer have no effect on the file until a
.L w
(write)
command is given.
The copy of the text being edited resides
in a temporary file called the
.IR buffer .
.PP
Commands to
.I ed
have a simple and regular structure: zero, one, or
two
.I addresses
followed by a single character
.IR command ,
possibly
followed by parameters to the command.
These addresses specify one or more lines in the buffer.
Missing addresses are supplied by default.
.PP
In general, only one command may appear on a line.
Certain commands allow the
addition of text to the buffer.
While
.I ed
is accepting text, it is said
to be in
.I "input mode."
In this mode, no commands are recognized;
all input is merely collected.
Input mode is left by typing a period
.L .
alone at the
beginning of a line.
.PP
.I Ed
supports the
.I "regular expression"
notation described in
.IR regexp (6).
Regular expressions are used in addresses to specify
lines and in one command
(see
.I s
below)
to specify a portion of a line which is to be replaced.
If it is desired to use one of
the regular expression metacharacters as an ordinary
character, that character may be preceded by
.RB ` \e '.
This also applies to the character bounding the regular
expression (often
.LR / )
and to
.L \e
itself.
.PP
To understand addressing in
.I ed
it is necessary to know that at any time there is a
.I "current line."
Generally, the current line is
the last line affected by a command; however,
the exact effect on the current line
is discussed under the description of
each command.
Addresses are constructed as follows.
.TP
1.
The character
.LR . ,
customarily called `dot',
addresses the current line.
.TP
2.
The character
.L $
addresses the last line of the buffer.
.TP
3.
A decimal number
.I n
addresses the
.IR n -th
line of the buffer.
.TP
4.
.BI \'x
addresses the line marked with the name
.IR x ,
which must be a lower-case letter.
Lines are marked with the
.L k
command.
.TP
5.
A regular expression enclosed in slashes (
.LR / )
addresses
the line found by searching forward from the current line
and stopping at the first line containing a
string that matches the regular expression.
If necessary the search wraps around to the beginning of the
buffer.
.TP
6.
A regular expression enclosed in queries
.L ?
addresses
the line found by searching backward from the current line
and stopping at the first line containing
a string that matches the regular expression.
If necessary
the search wraps around to the end of the buffer.
.TP
7.
An address followed by a plus sign
.L +
or a minus sign
.L -
followed by a decimal number specifies that address plus
(resp. minus) the indicated number of lines.
The plus sign may be omitted.
.TP
8.
An address followed by
.L +
(or
.LR - )
followed by a
regular expression enclosed in slashes specifies the first
matching line following (or preceding) that address.
The search wraps around if necessary.
The
.L +
may be omitted, so
.L 0/x/
addresses the
.I first
line in the buffer with an
.LR x .
Enclosing the regular expression in
.L ?
reverses the search direction.
.TP
9.
If an address begins with
.L +
or
.L -
the addition or subtraction is taken with respect to the current line;
e.g.\&
.L -5
is understood to mean
.LR .-5 .
.TP
10.
If an address ends with
.L +
or
.LR - ,
then 1 is added (resp. subtracted).
As a consequence of this rule and rule 9,
the address
.L -
refers to the line before the current line.
Moreover,
trailing
.L +
and
.L -
characters
have cumulative effect, so
.L --
refers to the current
line less 2.
.TP
11.
To maintain compatibility with earlier versions of the editor,
the character
.L ^
in addresses is
equivalent to
.LR - .
.PP
Commands may require zero, one, or two addresses.
Commands which require no addresses regard the presence
of an address as an error.
Commands which accept one or two addresses
assume default addresses when insufficient are given.
If more addresses are given than a command requires,
the last one or two (depending on what is accepted) are used.
.PP
Addresses are separated from each other typically by a comma
.LR , .
They may also be separated by a semicolon
.LR ; .
In this case the current line
is set to
the previous address before the next address is interpreted.
If no address precedes a comma or semicolon, line 1 is assumed;
if no address follows, the last line of the buffer is assumed.
The second address of any two-address sequence
must correspond to a line following the line corresponding to the first address.
.PP
In the following list of
.I ed
commands, the default addresses
are shown in parentheses.
The parentheses are not part of
the address, but are used to show that the given addresses are
the default.
`Dot' means the current line.
.TP
.RB (\|\fL.\fP\|) \|a
.br
.ns
.TP
<text>
.br
.ns
.TP
.B .
Read the given text
and append it after the addressed line.
Dot is left
on the last line input, if there
were any, otherwise at the addressed line.
Address
.L 0
is legal for this command; text is placed
at the beginning of the buffer.
.TP
.RB (\|\fL.,.\fP\|) \|b [ +- ][\fIpagesize\fP][ pln\fR]
Browse.
Print a `page', normally 20 lines.
The optional
.L +
(default) or
.L -
specifies whether the next or previous
page is to be printed.
The optional
.I pagesize
is the number of lines in a page.
The optional
.LR p ,
.LR n ,
or
.L l
causes printing in the specified format, initially
.LR p .
Pagesize and format are remembered between
.L b
commands.
Dot is left at the last line displayed.
.TP
.RB (\|\fL.,.\fP\|) \|c
.br
.ns
.TP
<text>
.br
.ns
.TP
.B .
Change.
Delete the addressed lines, then accept input
text to replace these lines.
Dot is left at the last line input; if there were none,
it is left at the line preceding the deleted lines.
.TP
.RB (\|\fL.,.\fP\|) \|d
Delete the addressed lines from the buffer.
Dot is set to the line following the last line deleted, or to
the last line of the buffer if the deleted lines had no successor.
.TP
.BI e " filename"
Edit.
Delete the entire contents of the buffer;
then read the named file into the buffer.
Dot is set to the last line of the buffer.
The number of characters read is typed.
The file name is remembered for possible use in later
.LR e ,
.LR r ,
or
.L w
commands.
If
.I filename
is missing, the remembered name is used.
.TP
.BI E " filename"
Unconditional
.LR e ;
see
.RL ` q '
below.
.TP
.BI f " filename"
Print the currently remembered file name.
If
.I filename
is given,
the currently remembered file name is first changed to
.IR filename .
.TP
.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/\fIcommand\ list\fP
.PD 0
.TP
.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/
.TP
.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP
.PD
Global.
First mark every line which matches
the given
.IR regular expression .
Then for every such line, execute the
.I command list
with dot initially set to that line.
A single command or the first of multiple commands
appears on the same line with the global command.
All lines of a multi-line list except the last line must end with
.LR \e .
The
.RB \&` \&. \&'
terminating input mode for an
.LR a ,
.LR i ,
.L c
command may be omitted if it would be on the
last line of the command list.
The commands
.L g
and
.L v
are not permitted in the command list.
Any character other than space or newline may
be used instead of
.L /
to delimit the regular expression.
The second and third forms mean
.BI g/ regular\ expression /p \f1.
.TP
.RB (\| .\| ) \|i
.PD 0
.TP
<text>
.TP
.B .
Insert the given text before the addressed line.
Dot is left at the last line input, or, if there were none,
at the line before the addressed line.
This command differs from the
.I a
command only in the placement of the
text.
.PD
.TP
.RB (\| .,.+1 \|) \|j
Join the addressed lines into a single line;
intermediate newlines are deleted.
Dot is left at the resulting line.
.TP
.RB (\|\fL.\fP\|) \|k\fIx\fP
Mark the addressed line with name
.IR x ,
which must be a lower-case letter.
The address form
.BI \' x
then addresses this line.
.ne 2.5
.TP
.RB (\|\fL.,.\fP\|) \|l
List.
Print the addressed lines in an unambiguous way:
a tab is printed as
.LR \et ,
a backspace as
.LR \eb ,
backslashes as
.LR \e\e ,
and non-printing characters as
a backslash, an
.LR x ,
and four hexadecimal digits.
Long lines are folded,
with the second and subsequent sub-lines indented one tab stop.
If the last character in the line is a blank,
it is followed by
.LR \en .
An
.L l
may be appended, like
.LR p ,
to any non-I/O command.
.TP
.RB (\|\fL.,.\fP\|) \|m\fIa
Move.
Reposition the addressed lines after the line
addressed by
.IR a .
Dot is left at the last moved line.
.TP
.RB (\|\fL.,.\fP\|) \|n
Number.
Perform
.LR p ,
prefixing each line with its line number and a tab.
An
.L n
may be appended, like
.LR p ,
to any non-I/O command.
.TP
.RB (\|\fL.,.\fP\|) \|p
Print the addressed lines.
Dot is left at the last line printed.
A
.L p
appended to any non-I/O command causes the then current line
to be printed after the command is executed.
.TP
.RB (\|\fL.,.\fP\|) \|P
This command is a synonym for
.LR p .
.TP
.B q
Quit the editor.
No automatic write
of a file is done.
A
.L q
or
.L e
command is considered to be in error if the buffer has
been modified since the last
.LR w ,
.LR q ,
or
.L e
command.
.TP
.B Q
Quit unconditionally.
.TP
.RB ( $ )\|r\ \fIfilename\fP
Read in the given file after the addressed line.
If no
.I filename
is given, the remembered file name is used.
The file name is remembered if there were no
remembered file name already.
If the read is successful, the number of characters
read is printed.
Dot is left at the last line read from the file.
.TP
.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/
.PD 0
.TP
.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/g
.TP
.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP
.PD
Substitute.
Search each addressed
line for an occurrence of the specified regular expression.
On each line in which
.I n
matches are found
.RI ( n
defaults to 1 if missing),
the
.IR n th
matched string is replaced by the replacement specified.
If the global replacement indicator
.L g
appears after the command,
all subsequent matches on the line are also replaced.
It is an error for the substitution to fail on all addressed lines.
Any character other than space or newline
may be used instead of
.L /
to delimit the regular expression
and the replacement.
Dot is left at the last line substituted.
The third form means
.BI s n / regular\ expression / replacement\fP/p\f1.
The second
.L /
may be omitted if the replacement is
empty.
.IP
An ampersand
.L &
appearing in the replacement
is replaced by the string matching the regular expression.
The characters
.BI \e n\f1,
where
.I n
is a digit,
are replaced by the text matched by the
.IR n -th
regular subexpression
enclosed between
.L (
and
.LR ) .
When
nested parenthesized subexpressions
are present,
.I n
is determined by counting occurrences of
.L (
starting from the left.
.IP
A literal
.LR & ,
.LR / ,
.L \e
or newline may be included in a replacement
by prefixing it with
.LR \e .
.TP
.RB (\|\fL.,.\fP\|) \|t\|\fIa
Transfer.
Copy the addressed lines
after the line addressed by
.IR a .
Dot is left at the last line of the copy.
.TP
.RB (\|\fL.,.\fP\|) \|u
Undo.
Restore the preceding contents
of the first addressed line (sic), which must be the last line
in which a substitution was made (double sic).
.TP
.RB (\|\fL1,$\fP\|) \|v/\fIregular\ expression\fP/\fIcommand\ list\fP
This command is the same as the global command
.L g
except that the command list is executed with
dot initially set to every line
.I except
those
matching the regular expression.
.TP
.RB (\|\fL1,$\fP\|) \|w " \fIfilename\fP"
Write the addressed lines to
the given file.
If the file does not exist,
it is created with mode 666 (readable and writable by everyone).
If no
.I filename
is given, the remembered file name, if any, is used.
The file name is remembered if there were no
remembered file name already.
Dot is unchanged.
If the write is successful, the number of characters written is
printed.
.TP
.RB (\|\fL1,$\fP\|) \|W " \fIfilename\fP"
Perform
.LR w ,
but append to, instead of overwriting, any existing file contents.
.TP
.RB ( $ ) \|=
Print the line number of the addressed line.
Dot is unchanged.
.TP
.BI ! shell\ command
Send the remainder of the line after the
.L !
to
.IR rc (1)
to be interpreted as a command.
Dot is unchanged.
.TP
.RB (\| .+1 )\|<newline>
An address without a command is taken as a
.L p
command.
A terminal
.L /
may be omitted from the address.
A blank line alone is equivalent to
.LR .+1p ;
it is useful
for stepping through text.
.PP
If an interrupt signal
.SM (DEL)
is sent,
.I ed
prints a
.L ?
and returns to its command level.
.PP
When reading a file,
.I ed
discards
.SM NUL
characters
and all characters after the last newline.
.SH FILES
.B /tmp/e*
.br
.B ed.hup
\ \ work is saved here if terminal hangs up
.SH SOURCE
.B /sys/src/cmd/ed.c
.SH "SEE ALSO"
.IR sam (1),
.IR sed (1),
.IR regexp (6)
.SH DIAGNOSTICS
.BI ? name
for inaccessible file;
.L ?TMP
for temporary file overflow;
.L ?
for errors in commands or other overflows.

66
man/man1/factor.1 Normal file
View File

@@ -0,0 +1,66 @@
.TH FACTOR 1
.CT 1 numbers
.SH NAME
factor, primes \- factor a number, generate large primes
.SH SYNOPSIS
.B factor
[
.I number
]
.PP
.B primes
[
.I start
[
.I finish
]
]
.SH DESCRIPTION
.I Factor
prints
.I number
and its prime factors,
each repeated the proper number of times.
The number must be positive and less than
.if n 2**54
.if t 2\u\s754\s0\d
(about
.if n 1.8e16)
.if t 1.8\(mu10\u\s716\s0\d\|).
.PP
If no
.I number
is given,
.I factor
reads a stream of numbers from the standard input and factors them.
It exits on any input not a positive integer.
Maximum running time is proportional to
.if n sqrt(n).
.if t .I \(sr\o'n\(rn'\f1.
.PP
.PP
.I Primes
prints the prime numbers ranging from
.I start
to
.IR finish ,
where
.I start
and
.I finish
are positive numbers less than
.if n 2**56.
.if t 2\u\s756\s0\d.
If
.I finish
is missing,
.I primes
prints without end;
if
.I start
is missing, it reads the starting number from the
standard input.
.SH SOURCE
.B /sys/src/cmd/factor.c
.br
.B /sys/src/cmd/primes.c

90
man/man1/fmt.1 Normal file
View File

@@ -0,0 +1,90 @@
.TH FMT 1
.SH NAME
fmt, htmlfmt \- simple text formatters
.SH SYNOPSIS
.B fmt
[
.I option ...
]
[
.I file ...
]
.PP
.B htmlfmt
[
.B -a
] [
.B -c
.I charset
] [
.B -u
.I url
] [
.I file ...
]
.SH DESCRIPTION
.I Fmt
copies the given
.I files
(standard input by default)
to its standard output, filling and indenting lines.
The options are
.TP
.BI -l " n
Output line length is
.IR n ,
including indent (default 70).
.TP
.BI -w " n
A synonym for
.BR -l .
.TP
.BI -i " n
Indent
.I n
spaces (default 0).
.TP
.BI -j
Do not join short lines: only fold long lines.
.PP
Empty lines and initial white space in input lines are preserved.
Empty lines are inserted between input files.
.PP
.I Fmt
is idempotent: it leaves already formatted text unchanged.
.PP
.I Htmlfmt
performs a similar service, but accepts as input text formatted with
HTML tags.
It accepts
.IR fmt 's
.B -l
and
.B -w
flags and also:
.TP
.BI -a
Normally
.I htmlfmt
suppresses the contents of form fields and anchors (URLs and image files); this flag
causes it to print them, in square brackets.
.TP
.BI -c " charset
change the default character set from iso-8859-1 to
.IR charset .
This is the character set assumed if there isn't one
specified by the html itself in a <meta> directive.
.TP
.BI -u " url
Use
.I url
as the base URL for the document when displaying anchors; sets
.BI -a .
.SH SOURCE
.B /sys/src/cmd/fmt.c
.PP
.B /sys/src/cmd/htmlfmt
.SH BUGS
.I Htmlfmt
makes no attempt to render the two-dimensional geometry of tables;
it just treats the table entries as plain, to-be-formatted text.

23
man/man1/fortune.1 Normal file
View File

@@ -0,0 +1,23 @@
.TH FORTUNE 1
.SH NAME
fortune \- sample lines from a file
.SH SYNOPSIS
.B fortune
[
.I file
]
.SH DESCRIPTION
.I Fortune
prints a one-line aphorism chosen at random.
If a
.I file
is specified, the saying is taken from that file;
otherwise it is selected from
.BR /sys/games/lib/fortunes .
.SH FILES
.B /sys/games/lib/fortunes
.br
.B /sys/games/lib/fortunes.index
\ \ fast lookup table, maintained automatically
.SH SOURCE
.B /sys/src/cmd/fortune.c

40
man/man1/freq.1 Normal file
View File

@@ -0,0 +1,40 @@
.TH FREQ 1
.SH NAME
freq \- print histogram of character frequencies
.SH SYNOPSIS
.B freq
[
.B -dxocr
]
[
.I file ...
]
.SH DESCRIPTION
.I Freq
reads the given files (default standard input)
and prints histograms of the character frequencies.
By default,
.I freq
counts each byte as a character;
under the
.B -r
option it instead counts
.SM UTF
sequences, that is, runes.
.PP
Each non-zero entry of the table is printed preceded by the byte value,
in decimal, octal, hex, and
Unicode
character (if printable).
If any options are given, the
.BR -d ,
.BR -x ,
.BR -o ,
.B -c
flags specify a subset of value formats: decimal, hex, octal, and
character, respectively.
.SH SOURCE
.B /sys/src/cmd/freq.c
.SH SEE ALSO
.IR utf (6),
.IR wc (1)

103
man/man1/grep.1 Normal file
View File

@@ -0,0 +1,103 @@
.TH GREP 1
.SH NAME
grep \- search a file for a pattern
.SH SYNOPSIS
.B grep
[
.I option ...
]
.I pattern
[
.I file ...
]
.SH DESCRIPTION
.I Grep\^
searches the input
.I files\^
(standard input default)
for lines that match the
.IR pattern ,
a regular expression as defined in
.IR regexp (6)
with the addition of a newline character as an alternative
(substitute for
.BR | )
with lowest precedence.
Normally, each line matching the pattern is `selected',
and each selected line is copied to the standard output.
The options are
.TP
.B -c
Print only a count of matching lines.
.PD 0
.TP
.B -h
Do not print file name tags (headers) with output lines.
.TP
.B -e
The following argument is taken as a
.IR pattern .
This option makes it easy to specify patterns that
might confuse argument parsing, such as
.BR -n .
.TP
.B -i
Ignore alphabetic case distinctions. The implementation
folds into lower case all letters in the pattern and input before
interpretation. Matched lines are printed in their original form.
.TP
.B -l
(ell) Print the names of files with selected lines; don't print the lines.
.TP
.B -L
Print the names of files with no selected lines;
the converse of
.BR -l .
.TP
.B -n
Mark each printed line with its line number counted in its file.
.TP
.B -s
Produce no output, but return status.
.TP
.B -v
Reverse: print lines that do not match the pattern.
.TP
.B -f
The pattern argument is the name of a file containing regular
expressions one per line.
.TP
.B -b
Don't buffer the output: write each output line as soon as it is discovered.
.PD
.PP
Output lines are tagged by file name when there is more than one
input file.
(To force this tagging, include
.B /dev/null
as a file name argument.)
.PP
Care should be taken when
using the shell metacharacters
.B $*[^|()=\e
and newline
in
.IR pattern ;
it is safest to enclose the
entire expression
in single quotes
.BR \&\|' \|.\|.\|.\| ' .
An expression starting with '*'
will treat the rest of the expression
as literal characters.
.SH SOURCE
.B /sys/src/cmd/grep
.SH SEE ALSO
.IR ed (1),
.IR awk (1),
.IR sed (1),
.IR sam (1),
.IR regexp (6)
.SH DIAGNOSTICS
Exit status is null if any lines are selected,
or non-null when no lines are selected or an error occurs.

144
man/man1/hoc.1 Normal file
View File

@@ -0,0 +1,144 @@
.TH HOC 1
.SH NAME
hoc \- interactive floating point language
.SH SYNOPSIS
.B hoc
[
.I file ...
]
[
.B -e
.I expression
]
.SH DESCRIPTION
.I Hoc
interprets a simple language for floating point arithmetic,
at about the level of BASIC, with C-like syntax and
functions.
.PP
The named
.I files
are read and interpreted in order.
If no
.I file
is given or if
.I file
is
.L -
.I hoc
interprets the standard input.
The
.B -e
option allows input to
.I hoc
to be specified on the command line, to be treated as if it appeared in a file.
.PP
.I Hoc
input consists of
.I expressions
and
.IR statements .
Expressions are evaluated and their results printed.
Statements, typically assignments and function or procedure
definitions, produce no output unless they explicitly call
.IR print .
.PP
Variable names have the usual syntax, including
.LR _ ;
the name
.L _
by itself contains the value of the last expression evaluated.
The variables
.BR E ,
.BR PI ,
.BR PHI ,
.BR GAMMA
and
.B DEG
are predefined; the last is 59.25..., degrees per radian.
.PP
Expressions are formed with these C-like operators, listed by
decreasing precedence.
.TP
.B ^
exponentiation
.TP
.B ! - ++ --
.TP
.B * / %
.TP
.B + -
.TP
.B > >= < <= == !=
.TP
.B &&
.TP
.B ||
.TP
.B = += -= *= /= %=
.PP
Built in functions are
.BR abs ,
.BR acos ,
.BR asin ,
.B atan
(one argument),
.BR cos ,
.BR cosh ,
.BR exp ,
.BR int ,
.BR log ,
.BR log10 ,
.BR sin ,
.BR sinh ,
.BR sqrt ,
.BR tan ,
and
.BR tanh .
The function
.B read(x)
reads a value into the variable
.B x
and returns 0 at EOF;
the statement
.B print
prints a list of expressions that may include
string constants such as
\fL"hello\en"\f1.\fP
.PP
Control flow statements are
.BR if - else ,
.BR while ,
and
.BR for ,
with braces for grouping.
Newline ends a statement.
Backslash-newline is equivalent to a space.
.PP
Functions and procedures are introduced by the words
.B func
and
.BR proc ;
.B return
is used to return with a value from a function.
.SH EXAMPLES
.EX
func gcd(a, b) {
temp = abs(a) % abs(b)
if(temp == 0) return abs(b)
return gcd(b, temp)
}
for(i=1; i<12; i++) print gcd(i,12)
.EE
.SH SOURCE
.B /sys/src/cmd/hoc
.SH "SEE ALSO"
.IR bc (1),
.IR dc (1)
.br
B. W. Kernighan and R. Pike,
.I
The Unix Programming Environment,
Prentice-Hall, 1984
.SH BUGS
Error recovery is imperfect within function and procedure definitions.

72
man/man1/idiff.1 Normal file
View File

@@ -0,0 +1,72 @@
.TH IDIFF 1
.SH NAME
idiff \- interactive diff
.SH SYNOPSIS
.B idiff
[
.B -bw
]
.I file1
.I file2
.SH DESCRIPTION
.I Idiff
interactively
merges
.I file1
and
.IR file2 .
Wherever
.I file1
and
.I file2
differ,
.I idiff
displays the differences in the style of
.RB `` diff
.RB -n ''
and prompts the user to select a chunk.
Valid responses are:
.TP
.B <
Use the chunk from
.IR file1 .
.TP
.B >
Use the chunk from
.IR file2 .
.TP
.B =
Use the diff output itself.
.TP
.BR q< ", " q> ", " q=
Use the given response for all future questions.
.TP
.BI ! cmd
Execute
.I cmd
and prompt again.
.PP
.I Idiff
invokes
.IR diff (1)
to compare the files.
The
.B -b
and
.B -w
flags
are simply
passed through to
.IR diff .
.SH FILES
.B /tmp/idiff.*
.SH SOURCE
.B /sys/src/cmd/idiff.c
.SH "SEE ALSO
.IR diff (1)
.br
Kernighan and Pike,
.IR "The Unix Programming Environment" ,
Prentice-Hall, 1984.
.SH BUGS
This is a poorly-written manual page.

148
man/man1/join.1 Normal file
View File

@@ -0,0 +1,148 @@
.TH JOIN 1
.CT 1 files
.SH NAME
join \- relational database operator
.SH SYNOPSIS
.B join
[
.I options
]
.I file1 file2
.SH DESCRIPTION
.I Join
forms, on the standard output,
a join
of the two relations specified by the lines of
.I file1
and
.IR file2 .
If one of the file names is
.LR - ,
the standard input is used.
.PP
.I File1
and
.I file2
must be sorted in increasing
.SM ASCII
collating
sequence on the fields
on which they are to be joined,
normally the first in each line.
.PP
There is one line in the output
for each pair of lines in
.I file1
and
.I file2
that have identical join fields.
The output line normally consists of the common field,
then the rest of the line from
.IR file1 ,
then the rest of the line from
.IR file2 .
.PP
Input fields are normally separated spaces or tabs;
output fields by space.
In this case, multiple separators count as one, and
leading separators are discarded.
.PP
The following options are recognized, with POSIX syntax.
.TP
.BI -a " n
In addition to the normal output,
produce a line for each unpairable line in file
.IR n ,
where
.I n
is 1 or 2.
.TP
.BI -v " n
Like
.BR -a ,
omitting output for paired lines.
.TP
.BI -e " s
Replace empty output fields by string
.IR s .
.TP
.BI -1 " m
.br
.ns
.TP
.BI -2 " m
Join on the
.IR m th
field of
.I file1
or
.IR file2 .
.TP
.BI -j "n m"
Archaic equivalent for
.BI - n " m"\f1.
.TP
.BI -o fields
Each output line comprises the designated fields.
The comma-separated field designators are either
.BR 0 ,
meaning the join field, or have the form
.IR n . m ,
where
.I n
is a file number and
.I m
is a field number.
Archaic usage allows separate arguments for field designators.
.PP
.TP
.BI -t c
Use character
.I c
as the only separator (tab character) on input and output.
Every appearance of
.I c
in a line is significant.
.SH EXAMPLES
.TP
.L
sort -t: +1 /adm/users | join -t: -1 2 -a 1 -e "" - bdays
Add birthdays to the
.B /adm/users
file, leaving unknown
birthdays empty.
The layout of
.B /adm/users
is given in
.IR users (6);
.B bdays
contains sorted lines like
.LR "ken:Feb\ 4,\ 1953" .
.TP
.L
tr : ' ' </adm/users | sort -k 3 3 >temp
.br
.ns
.TP
.L
join -1 3 -2 3 -o 1.1,2.1 temp temp | awk '$1 < $2'
Print all pairs of users with identical userids.
.SH SOURCE
.B /sys/src/cmd/join.c
.SH "SEE ALSO"
.IR sort (1),
.IR comm (1),
.IR awk (1)
.SH BUGS
With default field separation,
the collating sequence is that of
.BI "sort -b"
.BI -k y , y\f1;
with
.BR -t ,
the sequence is that of
.BI "sort -t" x
.BI -k y , y\f1.
.br
One of the files must be randomly accessible.

162
man/man1/ls.1 Normal file
View File

@@ -0,0 +1,162 @@
.TH LS 1
.SH NAME
ls, lc \- list contents of directory
.SH SYNOPSIS
.B ls
[
.B -dlmnpqrstuFQ
]
.I name ...
.PP
.B lc
[
.B -dlmnqrstuFQ
]
.I name ...
.SH DESCRIPTION
For each directory argument,
.I ls
lists the contents of the directory;
for each file argument,
.I ls
repeats its name and any other information requested.
When no argument is given, the current directory is listed.
By default, the output is sorted alphabetically by name.
.PP
.I Lc
is the same as
.IR ls ,
but sets the
.B -p
option and pipes the output through
.IR mc (1).
.PP
There are a number of options:
.TP
.B -d
If argument is a directory, list it, not
its contents.
.TP
.B -l
List in long format, giving mode (see below), file system type
(e.g., for devices, the
.B #
code letter that names it; see
.IR intro (3)),
the instance or subdevice number, owner, group,
size in bytes, and time of last modification
for each file.
.TP
.B -m
List the name of the user who most recently modified the file.
.TP
.B -n
Don't sort the listing.
.TP
.B -p
Print only the final path element of each file name.
.TP
.B -q
List the
.I qid
(see
.IR stat (2))
of each file; the printed fields are in the order
path, version, and type.
.TP
.B -r
Reverse the order of sort.
.TP
.B -s
Give size in Kbytes for each entry.
.TP
.B -t
Sort by time modified (latest first) instead of
by name.
.TP
.B -u
Under
.B -t
sort by time of last access;
under
.B -l
print time of last access.
.TP
.B -F
Add the character
.B /
after all directory names
and the character
.B *
after all executable files.
.TP
.B -L
Print the character
.B t
before each file if it has the temporary flag set, and
.B -
otherwise.
.TP
.B -Q
By default, printed file names are quoted if they contain characters special to
.IR rc (1).
The
.B -Q
flag disables this behavior.
.PP
The mode printed under the
.B -l
option contains 11 characters,
interpreted
as follows:
the first character is
.TP
.B d
if the entry is a directory;
.PD 0
.TP
.B a
if the entry is an append-only file;
.TP
.B -
if the entry is a plain file.
.PD
.PP
The next letter is
.B l
if the file is exclusive access (one writer or reader at a time).
.PP
The last 9 characters are interpreted
as three sets of three bits each.
The first set refers to owner permissions;
the next to permissions to others in the same user-group;
and the last to all others.
Within each set the three characters indicate
permission respectively to read, to write, or to
execute the file as a program.
For a directory, `execute' permission is interpreted
to mean permission to search the directory
for a specified file.
The permissions are indicated as follows:
.TP 3
.B r
if the file is readable;
.PD 0
.TP 3
.B w
if the file is writable;
.TP 3
.B x
if the file is executable;
.TP 3
.B -
if none of the above permissions is granted.
.PD
.SH SOURCE
.B /sys/src/cmd/ls.c
.br
.B /rc/bin/lc
.SH SEE ALSO
.IR stat (2)
.IR mc (1)

40
man/man1/mc.1 Normal file
View File

@@ -0,0 +1,40 @@
.TH MC 1
.SH NAME
mc \- multicolumn print
.SH SYNOPSIS
.B mc
[
.B -
]
[
.BI - N
]
[
.I file ...
]
.SH DESCRIPTION
.I Mc
splits the input into as many columns as will fit in
.I N
print positions.
If run in a
.IR rio (1)
window, the default
.I N
is the number of blanks that will fit across the window;
otherwise the default
.I N
is 80.
Under option
.B -
each input line ending in a colon
.L :
is printed separately.
.SH SOURCE
.B /sys/src/cmd/mc.c
.SH "SEE ALSO"
.IR rio (1),
.IR pr (1),
.I lc
in
.IR ls (1)

35
man/man1/mkdir.1 Normal file
View File

@@ -0,0 +1,35 @@
.TH MKDIR 1
.SH NAME
mkdir \- make a directory
.SH SYNOPSIS
.B mkdir
[
.B -p
]
.I dirname ...
.SH DESCRIPTION
.I Mkdir
creates the specified directories.
It
requires write permission in the parent directory.
.PP
If the
.B -p
flag is given,
.I mkdir
creates any necessary parent directories
and does not complain if the target directory already exists.
.SH "SEE ALSO"
.IR rm (1)
.br
.IR cd
in
.IR rc (1)
.SH SOURCE
.B /sys/src/cmd/mkdir.c
.SH DIAGNOSTICS
.I Mkdir
returns null exit status if all directories were successfully made.
Otherwise it prints a diagnostic and returns
.B \&"error"
status.

92
man/man1/plumb.1 Normal file
View File

@@ -0,0 +1,92 @@
.TH PLUMB 1
.SH NAME
plumb \- send message to plumber
.SH SYNOPSIS
.B plumb
[
.B -p
.I plumbfile
] [
.B -a
.I attributes
] [
.B -s
.I source
] [
.B -d
.I destination
] [
.B -t
.I type
] [
.B -w
.I directory
]
.B -i
|
.I data...
.SH DESCRIPTION
The
.I plumb
command formats and sends a plumbing message whose data
is, by default, the concatenation of the argument strings separated by blanks.
The options are:
.TP
.B -p
write the message to
.I plumbfile
(default
.BR /mnt/plumb/send ).
.TP
.B -a
set the
.B attr
field of the message (default is empty).
.TP
.B -s
set the
.B src
field of the message (default is
.BR plumb ).
.TP
.B -d
set the
.B dst
field of the message (default is empty).
.TP
.B -t
set the
.B type
field of the message (default is
.BR text ).
.TP
.B -w
set the
.B wdir
field of the message (default is the current working directory of
.IR plumb ).
.TP
.B -i
take the data from standard input rather than the argument strings.
If an
.B action=
attribute is not otherwise specified,
.I plumb
will add an
.B action=showdata
attribute to the message.
.SH FILES
.TF /usr/$user/lib/plumbing
.TP
.B /usr/$user/lib/plumbing
default rules file
.TP
.B /mnt/plumb
mount point for
.IR plumber (4).
.SH SOURCE
.B /sys/src/cmd/plumb
.SH "SEE ALSO"
.IR plumb (2),
.IR plumber (4),
.IR plumb (6)

959
man/man1/rc.1 Normal file
View File

@@ -0,0 +1,959 @@
.TH RC 1
.SH NAME
rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ \- command language
.SH SYNOPSIS
.B rc
[
.B -srdiIlxepvV
]
[
.B -c command
]
[
.I file
[
.I arg ...
]]
.SH DESCRIPTION
.I Rc
is the Plan 9 shell.
It executes command lines read from a terminal or a file or, with the
.B -c
flag, from
.I rc's
argument list.
.SS Command Lines
A command line is a sequence of commands, separated by ampersands or semicolons
.RB ( &
or
.BR ; ),
terminated by a newline.
The commands are executed in sequence
from left to right.
.I Rc
does not wait for a command followed by
.B &
to finish executing before starting
the following command.
Whenever a command followed by
.B &
is executed, its process id is assigned to the
.I rc
variable
.BR $apid .
Whenever a command
.I not
followed by
.B &
exits or is terminated, the
.I rc
variable
.B $status
gets the process's wait message (see
.IR wait (2));
it will be the null string if the command was successful.
.PP
A long command line may be continued on subsequent lines by typing
a backslash
.RB ( \e )
followed by a newline.
This sequence is treated as though it were a blank.
Backslash is not otherwise a special character.
.PP
A number-sign
.RB ( # )
and any following characters up to (but not including) the next newline
are ignored, except in quotation marks.
.SS Simple Commands
A simple command is a sequence of arguments interspersed with I/O redirections.
If the first argument is the name of an
.I rc
function or of one of
.I rc's
built-in commands, it is executed by
.IR rc .
Otherwise if the name starts with a slash
.RB ( / ),
it must be the path name of the program to be executed.
Names containing no initial slash are searched for in
a list of directory names stored in
.BR $path .
The first executable file of the given name found
in a directory in
.B $path
is the program to be executed.
To be executable, the user must have execute permission (see
.IR stat (2))
and the file must be either an executable binary
for the current machine's CPU type, or a shell script.
Shell scripts begin with a line containing the full path name of a shell
(usually
.BR /bin/rc ),
prefixed by
.LR #! .
.PP
The first word of a simple command cannot be a keyword unless it is
quoted or otherwise disguised.
The keywords are
.EX
for in while if not switch fn ~ ! @
.EE
.SS Arguments and Variables
A number of constructions may be used where
.I rc's
syntax requires an argument to appear.
In many cases a construction's
value will be a list of arguments rather than a single string.
.PP
The simplest kind of argument is the unquoted word:
a sequence of one or more characters none of which is a blank, tab,
newline, or any of the following:
.EX
# ; & | ^ $ = ` ' { } ( ) < >
.EE
An unquoted word that contains any of the characters
.B *
.B ?
.B [
is a pattern for matching against file names.
The character
.B *
matches any sequence of characters,
.B ?
matches any single character, and
.BI [ class ]
matches any character in the
.IR class .
If the first character of
.I class
is
.BR ~ ,
the class is complemented.
The
.I class
may also contain pairs of characters separated by
.BR - ,
standing for all characters lexically between the two.
The character
.B /
must appear explicitly in a pattern, as must the
first character of the path name components
.B .
and
.BR .. .
A pattern is replaced by a list of arguments, one for each path name matched,
except that a pattern matching no names is not replaced by the empty list,
but rather stands for itself.
Pattern matching is done after all other
operations.
Thus,
.EX
x=/tmp echo $x^/*.c
.EE
matches
.BR /tmp/*.c ,
rather than matching
.B "/*.c
and then prefixing
.BR /tmp .
.PP
A quoted word is a sequence of characters surrounded by single quotes
.RB ( ' ).
A single quote is represented in a quoted word by a pair of quotes
.RB ( '' ).
.PP
Each of the following is an argument.
.PD 0
.HP
.BI ( arguments )
.br
The value of a sequence of arguments enclosed in parentheses is
a list comprising the members of each element of the sequence.
Argument lists have no recursive structure, although their syntax may
suggest it.
The following are entirely equivalent:
.EX
echo hi there everybody
((echo) (hi there) everybody)
.EE
.HP
.BI $ argument
.HP
.BI $ argument ( subscript )
.br
The
.I argument
after the
.B $
is the name of a variable whose value is substituted.
Multiple levels
of indirection are possible, but of questionable utility.
Variable values
are lists of strings.
If
.I argument
is a number
.IR n ,
the value is the
.IR n th
element of
.BR $* ,
unless
.B $*
doesn't have
.I n
elements, in which case the value is empty.
If
.I argument
is followed by a parenthesized list of subscripts, the
value substituted is a list composed of the requested elements (origin 1).
The parenthesis must follow the variable name with no spaces.
Assignments to variables are described below.
.HP
.BI $# argument
.br
The value is the number of elements in the named variable.
A variable
never assigned a value has zero elements.
.HP
$"\c
.I argument
.br
The value is a single string containing the components of the named variable
separated by spaces. A variable with zero elements yields the empty string.
.HP
.BI `{ command }
.br
.I rc
executes the
.I command
and reads its standard output, splitting it into a list of arguments,
using characters in
.B $ifs
as separators.
If
.B $ifs
is not otherwise set, its value is
.BR "'\ \et\en'" .
.HP
.BI <{ command }
.HP
.BI >{ command }
.br
The
.I command
is executed asynchronously with its standard output or standard input
connected to a pipe.
The value of the argument is the name of a file
referring to the other end of the pipe.
This allows the construction of
non-linear pipelines.
For example, the following runs two commands
.B old
and
.B new
and uses
.B cmp
to compare their outputs
.EX
cmp <{old} <{new}
.EE
.HP
.IB argument ^ argument
.br
The
.B ^
operator concatenates its two operands.
If the two operands
have the same number of components, they are concatenated pairwise.
If not,
then one operand must have one component, and the other must be non-empty,
and concatenation is distributive.
.PD
.SS Free Carets
In most circumstances,
.I rc
will insert the
.B ^
operator automatically between words that are not separated by white space.
Whenever one of
.B $
.B '
.B `
follows a quoted or unquoted word or an unquoted word follows a quoted word
with no intervening blanks or tabs,
a
.B ^
is inserted between the two.
If an unquoted word immediately follows a
.BR $
and contains a character other than an alphanumeric, underscore,
or
.BR * ,
a
.B ^
is inserted before the first such character.
Thus
.IP
.B cc -$flags $stem.c
.LP
is equivalent to
.IP
.B cc -^$flags $stem^.c
.SS I/O Redirections
The sequence
.BI > file
redirects the standard output file (file descriptor 1, normally the
terminal) to the named
.IR file ;
.BI >> file
appends standard output to the file.
The standard input file (file descriptor 0, also normally the terminal)
may be redirected from a file by the sequence
.BI < file \f1,
or from an inline `here document'
by the sequence
.BI << eof-marker\f1.
The contents of a here document are lines of text taken from the command
input stream up to a line containing nothing but the
.IR eof-marker ,
which may be either a quoted or unquoted word.
If
.I eof-marker
is unquoted, variable names of the form
.BI $ word
have their values substituted from
.I rc's
environment.
If
.BI $ word
is followed by a caret
.RB ( ^ ),
the caret is deleted.
If
.I eof-marker
is quoted, no substitution occurs.
.PP
Redirections may be applied to a file-descriptor other than standard input
or output by qualifying the redirection operator
with a number in square brackets.
For example, the diagnostic output (file descriptor 2)
may be redirected by writing
.BR "cc junk.c >[2]junk" .
.PP
A file descriptor may be redirected to an already open descriptor by writing
.BI >[ fd0 = fd1 ]
or
.BI <[ fd0 = fd1 ]\f1.
.I Fd1
is a previously opened file descriptor and
.I fd0
becomes a new copy (in the sense of
.IR dup (2))
of it.
A file descriptor may be closed by writing
.BI >[ fd0 =]
or
.BI <[ fd0 =]\f1.
.PP
Redirections are executed from left to right.
Therefore,
.B cc junk.c >/dev/null >[2=1]
and
.B cc junk.c >[2=1] >/dev/null
have different effects: the first puts standard output in
.BR /dev/null
and then puts diagnostic output in the same place, where the second
directs diagnostic output to the terminal and sends standard output to
.BR /dev/null .
.SS Compound Commands
A pair of commands separated by a pipe operator
.RB ( | )
is a command.
The standard output of the left command is sent through a pipe
to the standard input of the right command.
The pipe operator may be decorated
to use different file descriptors.
.BI |[ fd ]
connects the output end of the pipe to file descriptor
.I fd
rather than 1.
.BI |[ fd0 = fd1 ]
connects output to
.I fd1
of the left command and input to
.I fd0
of the right command.
.PP
A pair of commands separated by
.B &&
or
.B ||
is a command.
In either case, the left command is executed and its exit status examined.
If the operator is
.B &&
the right command is executed if the left command's status is null.
.B ||
causes the right command to be executed if the left command's status is non-null.
.PP
The exit status of a command may be inverted (non-null is changed to null, null
is changed to non-null) by preceding it with a
.BR ! .
.PP
The
.B |
operator has highest precedence, and is left-associative (i.e. binds tighter
to the left than the right).
.B !
has intermediate precedence, and
.B &&
and
.B ||
have the lowest precedence.
.PP
The unary
.B @
operator, with precedence equal to
.BR ! ,
causes its operand to be executed in a subshell.
.PP
Each of the following is a command.
.PD 0
.HP
.B if (
.I list
.B )
.I command
.br
A
.I list
is a sequence of commands, separated by
.BR & ,
.BR ; ,
or newline.
It is executed and
if its exit status is null, the
.I command
is executed.
.HP
.B if not
.I command
.br
The immediately preceding command must have been
.BI if( list )
.IR command .
If its condition was non-zero, the
.I command
is executed.
.HP
.BI for( name
.B in
.IB arguments )
.I command
.HP
.BI for( name )
.I command
.br
The
.I command
is executed once for each
.IR argument
with that argument assigned to
.IR name .
If the argument list is omitted,
.B $*
is used.
.HP
.BI while( list )
.I command
.br
The
.I list
is executed repeatedly until its exit status is non-null.
Each time it returns null status, the
.I command
is executed.
An empty
.I list
is taken to give null status.
.HP
.BI "switch(" argument "){" list }
.br
The
.IR list
is searched for simple commands beginning with the word
.BR case .
(The search is only at the `top level' of the
.IR list .
That is,
.B cases
in nested constructs are not found.)
.I Argument
is matched against each word following
.B case
using the pattern-matching algorithm described above, except that
.B /
and the first characters of
.B .
and
.B ..
need not be matched explicitly.
When a match is found, commands in the list are executed up to the next
following
.B case
command (at the top level) or the closing brace.
.HP
.BI { list }
.br
Braces serve to alter the grouping of commands implied by operator
priorities.
The
.I body
is a sequence of commands separated by
.BR & ,
.BR ; ,
or newline.
.HP
.BI "fn " name { list }
.HP
.BI "fn " name
.br
The first form defines a function with the given
.IR name .
Subsequently, whenever a command whose first argument is
.I name
is encountered, the current value of
the remainder of the command's argument list will be assigned to
.BR $* ,
after saving its current value, and
.I rc
will execute the
.IR list .
The second form removes
.IR name 's
function definition.
.HP
.BI "fn " note { list }
.br
.HP
.BI "fn " note
.br
A function with a special name will be called when
.I rc
receives a corresponding note; see
.IR notify (2).
The valid note names (and corresponding notes) are
.B sighup
.RB ( hangup ),
.B sigint
.RB ( interrupt ),
.BR sigalrm
.RB ( alarm ),
and
.B sigfpe
(floating point trap).
By default
.I rc
exits on receiving any signal, except when run interactively,
in which case interrupts and quits normally cause
.I rc
to stop whatever it's doing and start reading a new command.
The second form causes
.I rc
to handle a signal in the default manner.
.I Rc
recognizes an artificial note,
.BR sigexit ,
which occurs when
.I rc
is about to finish executing.
.HP
.IB name = "argument command"
.br
Any command may be preceded by a sequence of assignments
interspersed with redirections.
The assignments remain in effect until the end of the command, unless
the command is empty (i.e. the assignments stand alone), in which case
they are effective until rescinded by later assignments.
.PD
.SS Built-in Commands
These commands are executed internally by
.IR rc ,
usually because their execution changes or depends on
.IR rc 's
internal state.
.PD 0
.HP
.BI . " file ..."
.br
Execute commands from
.IR file .
.B $*
is set for the duration to the remainder of the argument list following
.IR file .
.I File
is searched for using
.BR $path .
.HP
.BI builtin " command ..."
.br
Execute
.I command
as usual except that any function named
.I command
is ignored in favor of the built-in meaning.
.HP
.BI "cd [" dir "]"
.br
Change the current directory to
.IR dir .
The default argument is
.BR $home .
.I dir
is searched for in each of the directories mentioned in
.BR $cdpath .
.HP
.BI "eval [" "arg ..." "]"
.br
The arguments are concatenated separated by spaces into a single string,
read as input to
.IR rc ,
and executed.
.HP
.BI "exec [" "command ..." "]"
.br
This instance of
.I rc
replaces itself with the given (non-built-in)
.IR command .
.HP
.BI "flag " f " [+-]"
.br
Either set
.RB ( + ),
clear
.RB ( - ),
or test (neither
.B +
nor
.BR - )
the flag
.IR f ,
where
.I f
is a single character, one of the command line flags (see Invocation, below).
.HP
.BI "exit [" status "]"
.br
Exit with the given exit status.
If none is given, the current value of
.B $status
is used.
.HP
.BR "rfork " [ nNeEsfFm ]
.br
Become a new process group using
.BI rfork( flags )
where
.I flags
is composed of the bitwise OR of the
.B rfork
flags specified by the option letters
(see
.IR fork (2)).
If no
.I flags
are given, they default to
.BR ens .
The
.I flags
and their meanings are:
.B n
is
.BR RFNAMEG ;
.B N
is
.BR RFCNAMEG ;
.B e
is
.BR RFENVG ;
.B E
is
.BR RFCENVG ;
.B s
is
.BR RFNOTEG ;
.B f
is
.BR RFFDG ;
.B F
is
.BR RFCFDG ;
and
.B m
is
.BR RFNOMNT .
.HP
.BI "shift [" n "]"
.br
Delete the first
.IR n
(default 1)
elements of
.BR $* .
.HP
.BI "wait [" pid "]"
.br
Wait for the process with the given
.I pid
to exit.
If no
.I pid
is given, all outstanding processes are waited for.
.HP
.BI whatis " name ..."
.br
Print the value of each
.I name
in a form suitable for input to
.IR rc .
The output is
an assignment to any variable,
the definition of any function,
a call to
.B builtin
for any built-in command, or
the completed pathname of any executable file.
.HP
.BI ~ " subject pattern ..."
.br
The
.I subject
is matched against each
.I pattern
in sequence.
If it matches any pattern,
.B $status
is set to zero.
Otherwise,
.B $status
is set to one.
Patterns are the same as for file name matching, except that
.B /
and the first character of
.B .
and
.B ..
need not be matched explicitly.
The
.I patterns
are not subjected to
file name matching before the
.B ~
command is executed, so they need not be enclosed in quotation marks.
.PD
.SS Environment
The
.I environment
is a list of strings made available to executing binaries by the
.B env
device
(see
.IR env (3)).
.I Rc
creates an environment entry for each variable whose value is non-empty,
and for each function.
The string for a variable entry has the variable's name followed by
.B =
and its value.
If the value has more than one component, these
are separated by ctrl-a
.RB ( '\e001' )
characters.
The string for a function is just the
.I rc
input that defines the function.
The name of a function in the environment is the function name
preceded by
.LR fn# .
.PP
When
.I rc
starts executing it reads variable and function definitions from its
environment.
.SS Special Variables
The following variables are set or used by
.IR rc .
.PD 0
.TP \w'\fL$promptXX'u
.B $*
Set to
.IR rc 's
argument list during initialization.
Whenever a
.B .
command or a function is executed, the current value is saved and
.B $*
receives the new argument list.
The saved value is restored on completion of the
.B .
or function.
.TP
.B $apid
Whenever a process is started asynchronously with
.BR & ,
.B $apid
is set to its process id.
.TP
.B $home
The default directory for
.BR cd .
.TP
.B $ifs
The input field separators used in backquote substitutions.
If
.B $ifs
is not set in
.IR rc 's
environment, it is initialized to blank, tab and newline.
.TP
.B $path
The search path used to find commands and input files
for the
.B .
command.
If not set in the environment, it is initialized by
.BR "path=(.\ /bin)" .
Its use is discouraged; instead use
.IR bind (1)
to build a
.B /bin
containing what's needed.
.TP
.B $pid
Set during initialization to
.IR rc 's
process id.
.TP
.B $prompt
When
.I rc
is run interactively, the first component of
.B $prompt
is printed before reading each command.
The second component is printed whenever a newline is typed and more lines
are required to complete the command.
If not set in the environment, it is initialized by
.BR "prompt=('%\ '\ '\ ')" .
.TP
.B $status
Set to the wait message of the last-executed program.
(unless started with
.BR &).
.B !
and
.B ~
also change
.BR $status .
Its value is used to control execution in
.BR && ,
.BR || ,
.B if
and
.B while
commands.
When
.I rc
exits at end-of-file of its input or on executing an
.B exit
command with no argument,
.B $status
is its exit status.
.PD
.SS Invocation
If
.I rc
is started with no arguments it reads commands from standard input.
Otherwise its first non-flag argument is the name of a file from which
to read commands (but see
.B -c
below).
Subsequent arguments become the initial value of
.BR $* .
.I Rc
accepts the following command-line flags.
.PD 0
.TP \w'\fL-c\ \fIstring\fLXX'u
.BI -c " string"
Commands are read from
.IR string .
.TP
.B -s
Print out exit status after any command where the status is non-null.
.TP
.B -e
Exit if
.B $status
is non-null after executing a simple command.
.TP
.B -i
If
.B -i
is present, or
.I rc
is given no arguments and its standard input is a terminal,
it runs interactively.
Commands are prompted for using
.BR $prompt .
.TP
.B -I
Makes sure
.I rc
is not run interactively.
.TP
.B -l
If
.B -l
is given or the first character of argument zero is
.BR - ,
.I rc
reads commands from
.BR $home/lib/profile ,
if it exists, before reading its normal input.
.TP
.B -p
A no-op.
.TP
.B -d
A no-op.
.TP
.B -v
Echo input on file descriptor 2 as it is read.
.TP
.B -x
Print each simple command before executing it.
.TP
.B -r
Print debugging information (internal form of commands
as they are executed).
.PD
.SH SOURCE
.B /sys/src/cmd/rc
.SH "SEE ALSO"
Tom Duff,
``Rc \- The Plan 9 Shell''.
.SH BUGS
There should be a way to match patterns against whole lists rather than
just single strings.
.br
Using
.B ~
to check the value of
.B $status
changes
.BR $status .
.br
Functions that use here documents don't work.
.br
Free carets don't get inserted next to keywords.

28
man/man1/rm.1 Normal file
View File

@@ -0,0 +1,28 @@
.TH RM 1
.SH NAME
rm \- remove files
.SH SYNOPSIS
.B rm
[
.B -fr
]
.I file ...
.SH DESCRIPTION
.I Rm
removes files or directories.
A directory is removed only if it is empty.
Removal of a file requires write permission in its directory,
but neither read nor write permission on the file itself.
The options are
.TP
.B -f
Don't report files that can't be removed.
.TP
.B -r
Recursively delete the
entire contents of a directory
and the directory itself.
.SH SOURCE
.B /sys/src/cmd/rm.c
.SH "SEE ALSO"
.IR remove (2)

885
man/man1/sam.1 Normal file
View File

@@ -0,0 +1,885 @@
.TH SAM 1
.ds a \fR*\ \fP
.SH NAME
sam, B, sam.save \- screen editor with structural regular expressions
.SH SYNOPSIS
.B sam
[
.I option ...
] [
.I files
]
.PP
.B sam
.B -r
.I machine
.PP
.B sam.save
.PP
.B B
[
.BI -nnnn
]
.I file ...
.SH DESCRIPTION
.I Sam
is a multi-file editor.
It modifies a local copy of an external file.
The copy is here called a
.IR file .
The files are listed in a menu available through mouse button 3
or the
.B n
command.
Each file has an associated name, usually the name of the
external file from which it was read, and a `modified' bit that indicates whether
the editor's file agrees with the external file.
The external file is not read into
the editor's file until it first becomes the current file\(emthat to
which editing commands apply\(emwhereupon its menu entry is printed.
The options are
.TF -rmachine
.TP
.B -d
Do not `download' the terminal part of
.IR sam .
Editing will be done with the command language only, as in
.IR ed (1).
.TP
.BI -r " machine
Run the host part remotely
on the specified machine, the terminal part locally.
.TP
.BI -s " path
Start the host part from the specified file on the remote host.
Only meaningful with the
.BI -r
option.
.TP
.BI -t " path
Start the terminal part from the specified file. Useful
for debugging.
.PD
.SS Regular expressions
Regular expressions are as in
.IR regexp (6)
with the addition of
.BR \en
to represent newlines.
A regular expression may never contain a literal newline character.
The empty
regular expression stands for the last complete expression encountered.
A regular expression in
.I sam
matches the longest leftmost substring formally
matched by the expression.
Searching in the reverse direction is equivalent
to searching backwards with the catenation operations reversed in
the expression.
.SS Addresses
An address identifies a substring in a file.
In the following, `character
.IR n '
means the null string
after the
.IR n -th
character in the file, with 1 the
first character in the file.
`Line
.IR n '
means the
.IR n -th
match,
starting at the beginning of the file, of the regular expression
.LR .*\en? .
All files always have a current substring, called dot,
that is the default address.
.SS Simple Addresses
.PD 0
.TP
.BI # n
The empty string after character
.IR n ;
.B #0
is the beginning of the file.
.TP
.I n
Line
.IR n ;
.B 0
is the beginning of the file.
.TP
.BI / regexp /
.PD 0
.TP
.BI ? regexp ?
The substring that matches the regular expression,
found by looking toward the end
.RB ( / )
or beginning
.RB ( ? )
of the file,
and if necessary continuing the search from the other end to the
starting point of the search.
The matched substring may straddle
the starting point.
When entering a pattern containing a literal question mark
for a backward search, the question mark should be
specified as a member of a class.
.PD
.TP
.B 0
The string before the first full line.
This is not necessarily
the null string; see
.B +
and
.B -
below.
.TP
.B $
The null string at the end of the file.
.TP
.B .
Dot.
.TP
.B \&'
The mark in the file (see the
.B k
command below).
.TP
\fB"\f2regexp\fB"\f1\f1
Preceding a simple address (default
.BR . ),
refers to the address evaluated in the unique file whose menu line
matches the regular expression.
.PD
.SS Compound Addresses
In the following,
.I a1
and
.I a2
are addresses.
.TF a1+a2
.TP
.IB a1 + a2
The address
.I a2
evaluated starting at the end of
.IR a1 .
.TP
.IB a1 - a2
The address
.I a2
evaluated looking in the reverse direction
starting at the beginning of
.IR a1 .
.TP
.IB a1 , a2
The substring from the beginning of
.I a1
to the end of
.IR a2 .
If
.I a1
is missing,
.B 0
is substituted.
If
.I a2
is missing,
.B $
is substituted.
.TP
.IB a1 ; a2
Like
.IB a1 , a2\f1,
but with
.I a2
evaluated at the end of, and dot set to,
.IR a1 .
.PD
.PP
The operators
.B +
and
.B -
are high precedence, while
.B ,
and
.B ;
are low precedence.
.PP
In both
.B +
and
.B -
forms, if
.I a2
is a line or character address with a missing
number, the number defaults to 1.
If
.I a1
is missing,
.L .
is substituted.
If both
.I a1
and
.I a2
are present and distinguishable,
.B +
may be elided.
.I a2
may be a regular
expression; if it is delimited by
.LR ? 's,
the effect of the
.B +
or
.B -
is reversed.
.PP
It is an error for a compound address to represent a malformed substring.
Some useful idioms:
.IB a1 +-
\%(\f2a1\fB-+\f1)
selects the line containing
the end (beginning) of a1.
.BI 0/ regexp /
locates the first match of the expression in the file.
(The form
.B 0;//
sets dot unnecessarily.)
.BI ./ regexp ///
finds the second following occurrence of the expression,
and
.BI .,/ regexp /
extends dot.
.SS Commands
In the following, text demarcated by slashes represents text delimited
by any printable
character except alphanumerics.
Any number of
trailing delimiters may be elided, with multiple elisions then representing
null strings, but the first delimiter must always
be present.
In any delimited text,
newline may not appear literally;
.B \en
may be typed for newline; and
.B \e/
quotes the delimiter, here
.LR / .
Backslash is otherwise interpreted literally, except in
.B s
commands.
.PP
Most commands may be prefixed by an address to indicate their range
of operation.
Those that may not are marked with a
.L *
below.
If a command takes
an address and none is supplied, dot is used.
The sole exception is
the
.B w
command, which defaults to
.BR 0,$ .
In the description, `range' is used
to represent whatever address is supplied.
Many commands set the
value of dot as a side effect.
If so, it is always set to the `result'
of the change: the empty string for a deletion, the new text for an
insertion, etc. (but see the
.B s
and
.B e
commands).
.br
.ne 1.2i
.SS Text commands
.PD 0
.TP
.BI a/ text /
.TP
or
.TP
.B a
.TP
.I lines of text
.TP
.B .
Insert the text into the file after the range.
Set dot.
.PD
.TP
.B c\fP
.br
.ns
.TP
.B i\fP
Same as
.BR a ,
but
.B c
replaces the text, while
.B i
inserts
.I before
the range.
.TP
.B d
Delete the text in the range.
Set dot.
.TP
.BI s/ regexp / text /
Substitute
.I text
for the first match to the regular expression in the range.
Set dot to the modified range.
In
.I text
the character
.B &
stands for the string
that matched the expression.
Backslash behaves as usual unless followed by
a digit:
.BI \e d
stands for the string that matched the
subexpression begun by the
.IR d -th
left parenthesis.
If
.I s
is followed immediately by a
number
.IR n ,
as in
.BR s2/x/y/ ,
the
.IR n -th
match in the range is substituted.
If the
command is followed by a
.BR g ,
as in
.BR s/x/y/g ,
all matches in the range
are substituted.
.TP
.BI m " a1
.br
.ns
.TP
.BI t " a1
Move
.RB ( m )
or copy
.RB ( t )
the range to after
.IR a1 .
Set dot.
.SS Display commands
.PD 0
.TP
.B p
Print the text in the range.
Set dot.
.TP
.B =
Print the line address and character address of the range.
.TP
.B =#
Print just the character address of the range.
.PD
.SS File commands
.PD 0
.TP
.BI \*ab " file-list
Set the current file to the first file named in the list
that
.I sam
also has in its menu.
The list may be expressed
.BI < "Plan 9 command"
in which case the file names are taken as words (in the shell sense)
generated by the Plan 9 command.
.TP
.BI \*aB " file-list
Same as
.BR b ,
except that file names not in the menu are entered there,
and all file names in the list are examined.
.TP
.B \*an
Print a menu of files.
The format is:
.RS
.TP 11
.BR ' " or blank
indicating the file is modified or clean,
.TP 11
.BR - " or \&" +
indicating the file is unread or has been read
(in the terminal,
.B *
means more than one window is open),
.TP 11
.BR . " or blank
indicating the current file,
.TP 11
a blank,
.TP 11
and the file name.
.RE
.TP 0
.BI \*aD " file-list
Delete the named files from the menu.
If no files are named, the current file is deleted.
It is an error to
.B D
a modified file, but a subsequent
.B D
will delete such a file.
.PD
.SS I/O Commands
.PD 0
.TP
.BI \*ae " filename
Replace the file by the contents of the named external file.
Set dot to the beginning of the file.
.TP
.BI r " filename
Replace the text in the range by the contents of the named external file.
Set dot.
.TP
.BI w " filename
Write the range (default
.BR 0,$ )
to the named external file.
.TP
.BI \*af " filename
Set the file name and print the resulting menu entry.
.PP
If the file name is absent from any of these, the current file name is used.
.B e
always sets the file name;
.B r
and
.B w
do so if the file has no name.
.TP
.BI < " Plan 9-command
Replace the range by the standard output of the
Plan 9 command.
.TP
.BI > " Plan 9-command
Send the range to the standard input of the
Plan 9 command.
.TP
.BI | " Plan 9-command
Send the range to the standard input, and replace it by
the standard output, of the
Plan 9 command.
.TP
.BI \*a! " Plan 9-command
Run the
Plan 9 command.
.TP
.BI \*acd " directory
Change working directory.
If no directory is specified,
.B $home
is used.
.PD
.PP
In any of
.BR < ,
.BR > ,
.B |
or
.BR ! ,
if the
.I Plan 9 command
is omitted the last
.I Plan 9 command
(of any type) is substituted.
If
.I sam
is
.I downloaded
(using the mouse and raster display, i.e. not using option
.BR -d ),
.B !
sets standard input to
.BR /dev/null ,
and otherwise
unassigned output
.RB ( stdout
for
.B !
and
.BR > ,
.B stderr
for all) is placed in
.B /tmp/sam.err
and the first few lines are printed.
.SS Loops and Conditionals
.PD 0
.TP
.BI x/ regexp / " command
For each match of the regular expression in the range, run the command
with dot set to the match.
Set dot to the last match.
If the regular
expression and its slashes are omitted,
.L /.*\en/
is assumed.
Null string matches potentially occur before every character
of the range and at the end of the range.
.TP
.BI y/ regexp / " command
Like
.BR x ,
but run the command for each substring that lies before, between,
or after
the matches that would be generated by
.BR x .
There is no default regular expression.
Null substrings potentially occur before every character
in the range.
.TP
.BI \*aX/ regexp / " command
For each file whose menu entry matches the regular expression,
make that the current file and
run the command.
If the expression is omitted, the command is run
in every file.
.TP
.BI \*aY/ regexp / " command
Same as
.BR X ,
but for files that do not match the regular expression,
and the expression is required.
.TP
.BI g/ regexp / " command
.br
.ns
.TP
.BI v/ regexp / " command
If the range contains
.RB ( g )
or does not contain
.RB ( v )
a match for the expression,
set dot to the range and run the command.
.PP
These may be nested arbitrarily deeply, but only one instance of either
.B X
or
.B Y
may appear in a \%single command.
An empty command in an
.B x
or
.B y
defaults to
.BR p ;
an empty command in
.B X
or
.B Y
defaults to
.BR f .
.B g
and
.B v
do not have defaults.
.PD
.SS Miscellany
.TF (empty)
.TP
.B k
Set the current file's mark to the range. Does not set dot.
.TP
.B \*aq
Quit.
It is an error to quit with modified files, but a second
.B q
will succeed.
.TP
.BI \*au " n
Undo the last
.I n
(default 1)
top-level commands that changed the contents or name of the
current file, and any other file whose most recent change was simultaneous
with the current file's change.
Successive
.BR u 's
move further back in time.
The only commands for which u is ineffective are
.BR cd ,
.BR u ,
.BR q ,
.B w
and
.BR D .
If
.I n
is negative,
.B u
`redoes,' undoing the undo, going forwards in time again.
.TP
(empty)
If the range is explicit, set dot to the range.
If
.I sam
is downloaded, the resulting dot is selected on the screen;
otherwise it is printed.
If no address is specified (the
command is a newline) dot is extended in either direction to
line boundaries and printed.
If dot is thereby unchanged, it is set to
.B .+1
and printed.
.PD
.SS Grouping and multiple changes
Commands may be grouped by enclosing them in braces
.BR {} .
Commands within the braces must appear on separate lines (no backslashes are
required between commands).
Semantically, an opening brace is like a command:
it takes an (optional) address and sets dot for each sub-command.
Commands within the braces are executed sequentially, but changes made
by one command are not visible to other commands (see the next
paragraph).
Braces may be nested arbitrarily.
.PP
When a command makes a number of changes to a file, as in
.BR x/re/c/text/ ,
the addresses of all changes to the file are computed in the original file.
If the changes are in sequence,
they are applied to the file.
Successive insertions at the same address are catenated into a single
insertion composed of the several insertions in the order applied.
.SS The terminal
What follows refers to behavior of
.I sam
when downloaded, that is, when
operating as a display editor on a raster display.
This is the default
behavior; invoking
.I sam
with the
.B -d
(no download) option provides access
to the command language only.
.PP
Each file may have zero or more windows open.
Each window is equivalent
and is updated simultaneously with changes in other windows on the same file.
Each window has an independent value of dot, indicated by a highlighted
substring on the display.
Dot may be in a region not within
the window.
There is usually a `current window',
marked with a dark border, to which typed text and editing
commands apply.
Text may be typed and edited as in
.IR rio (1);
also the escape key (ESC) selects (sets dot to) text typed
since the last mouse button hit.
.PP
The button 3 menu controls window operations.
The top of the menu
provides the following operators, each of which uses one or
more
.IR rio -like
cursors to prompt for selection of a window or sweeping
of a rectangle.
`Sweeping' a null rectangle gets a large window, disjoint
from the command window or the whole screen, depending on
where the null rectangle is.
.TF resize
.TP
.B new
Create a new, empty file.
.TP
.B zerox
Create a copy of an existing window.
.TP
.B resize
As in
.IR rio .
.TP
.B close
Delete the window.
In the last window of a file,
.B close
is equivalent to a
.B D
for the file.
.TP
.B write
Equivalent to a
.B w
for the file.
.PD
.PP
Below these operators is a list of available files, starting with
.BR ~~sam~~ ,
the command window.
Selecting a file from the list makes the most recently
used window on that file current, unless it is already current, in which
case selections cycle through the open windows.
If no windows are open
on the file, the user is prompted to open one.
Files other than
.B ~~sam~~
are marked with one of the characters
.B -+*
according as zero, one, or more windows
are open on the file.
A further mark
.L .
appears on the file in the current window and
a single quote,
.BR ' ,
on a file modified since last write.
.PP
The command window, created automatically when
.B sam
starts, is an ordinary window except that text typed to it
is interpreted as commands for the editor rather than passive text,
and text printed by editor commands appears in it.
The behavior is like
.IR rio ,
with an `output point' that separates commands being typed from
previous output.
Commands typed in the command window apply to the
current open file\(emthe file in the most recently
current window.
.SS Manipulating text
Button 1 changes selection, much like
.IR rio .
Pointing to a non-current window with button 1 makes it current;
within the current window, button 1 selects text, thus setting dot.
Double-clicking selects text to the boundaries of words, lines,
quoted strings or bracketed strings, depending on the text at the click.
.PP
Button 2 provides a menu of editing commands:
.TF /regexp
.TP
.B cut
Delete dot and save the deleted text in the snarf buffer.
.TP
.B paste
Replace the text in dot by the contents of the snarf buffer.
.TP
.B snarf
Save the text in dot in the snarf buffer.
.TP
.B plumb
Send the text in the selection as a plumb
message. If the selection is empty,
the white-space-delimited block of text is sent as a plumb message
with a
.B click
attribute defining where the selection lies (see
.IR plumb (6)).
.TP
.B look
Search forward for the next occurrence of the literal text in dot.
If dot is the null string, the text in the snarf buffer is
used.
The snarf buffer is unaffected.
.TP
.B <rio>
Exchange snarf buffers with
.IR rio .
.TP
.BI / regexp
Search forward for the next match of the last regular expression
typed in a command.
(Not in command window.)
.TP
.B send
Send the text in dot, or the snarf buffer if
dot is the null string, as if it were typed to the command window.
Saves the sent text in the snarf buffer.
(Command window only.)
.PD
.SS External communication
.I Sam
listens to the
.B edit
plumb port.
If plumbing is not active,
on invocation
.I sam
creates a named pipe
.BI /srv/sam. user
which acts as an additional source of commands. Characters written to
the named pipe are treated as if they had been typed in the command window.
.PP
.I B
is a shell-level command that causes an instance of
.I sam
running on the same terminal to load the named
.IR files .
.I B
uses either plumbing or the named pipe, whichever service is available.
If plumbing is not enabled,
the option allows a line number to be specified for
the initial position to display in the last named file
(plumbing provides a more general mechanism for this ability).
.SS Abnormal termination
If
.I sam
terminates other than by a
.B q
command (by hangup, deleting its window, etc.), modified
files are saved in an
executable file,
.BR $home/sam.save .
This program, when executed, asks whether to write
each file back to a external file.
The answer
.L y
causes writing; anything else skips the file.
.SH FILES
.TF /sys/src/cmd/samterm
.TP
.B $home/sam.save
.TP
.B $home/sam.err
.TP
.B /sys/lib/samsave
the program called to unpack
.BR $home/sam.save .
.SH SOURCE
.TF /sys/src/cmd/samterm
.TP
.B /sys/src/cmd/sam
source for
.I sam
itself
.TP
.B /sys/src/cmd/samterm
source for the separate terminal part
.TP
.B /rc/bin/B
.SH SEE ALSO
.IR ed (1),
.IR sed (1),
.IR grep (1),
.IR rio (1),
.IR regexp (6).
.PP
Rob Pike,
``The text editor sam''.

75
man/man1/seq.1 Normal file
View File

@@ -0,0 +1,75 @@
.TH SEQ 1
.SH NAME
seq \- print sequences of numbers
.SH SYNOPSIS
.B seq
[
.B -w
]
[
.BI -f format
]
[
.I first
[
.I incr
]
]
.I last
.SH DESCRIPTION
.I Seq
prints a sequence of numbers, one per line, from
.I first
(default 1) to as near
.I last
as possible, in increments of
.I incr
(default 1).
The loop is:
.sp
.EX
for(val = min; val <= max; val += incr) print val;
.EE
.sp
The numbers are interpreted as floating point.
.PP
Normally integer values are printed as decimal integers.
The options are
.TP "\w'\fL-f \fIformat\fLXX'u"
.BI -f format
Use the
.IR print (2)-style
.I format
.IR print
for printing each (floating point) number.
The default is
.LR %g .
.TP
.B -w
Equalize the widths of all numbers by padding with
leading zeros as necessary.
Not effective with option
.BR -f ,
nor with numbers in exponential notation.
.SH EXAMPLES
.TP
.L
seq 0 .05 .1
Print
.BR "0 0.05 0.1"
(on separate lines).
.TP
.L
seq -w 0 .05 .1
Print
.BR "0.00 0.05 0.10" .
.SH SOURCE
.B /sys/src/cmd/seq.c
.SH BUGS
Option
.B -w
always surveys every value in advance.
Thus
.L
seq -w 1000000000
is a painful way to get an `infinite' sequence.

31
man/man1/sleep.1 Normal file
View File

@@ -0,0 +1,31 @@
.TH SLEEP 1
.SH NAME
sleep \- suspend execution for an interval
.SH SYNOPSIS
.B sleep
.I time
.SH DESCRIPTION
.I Sleep
suspends execution for
.I time
seconds.
.SH EXAMPLES
Execute a command
100 seconds hence.
.IP
.EX
{sleep 100; command}&
.EE
.PP
Repeat a command every 30 seconds.
.IP
.EX
while (){
command
sleep 30
}
.EE
.SH SOURCE
.B /sys/src/cmd/sleep.c
.SH "SEE ALSO"
.IR sleep (2)

260
man/man1/sort.1 Normal file
View File

@@ -0,0 +1,260 @@
.TH SORT 1
.SH NAME
sort \- sort and/or merge files
.SH SYNOPSIS
.B sort
[
.BI -cmuMbdf\&inrwt x
]
[
.BI + pos1
[
.BI - pos2
] ...
] ...
[
.B -k
.I pos1
[
.I ,pos2
]
] ...
[
.B -o
.I output
]
[
.B -T
.I dir
\&...
]
[
.I option
\&...
]
[
.I file
\&...
]
.SH DESCRIPTION
.I Sort\^
sorts
lines of all the
.I files
together and writes the result on
the standard output.
If no input files are named, the standard input is sorted.
.PP
The default sort key is an entire line.
Default ordering is
lexicographic by runes.
The ordering is affected globally by the following options,
one or more of which may appear.
.TP
.B -M
Compare as months.
The first three
non-white space characters
of the field
are folded
to upper case
and compared
so that
.L JAN
precedes
.LR FEB ,
etc.
Invalid fields
compare low to
.LR JAN .
.TP
.B -b
Ignore leading white space (spaces and tabs) in field comparisons.
.TP
.B -d
`Phone directory' order:
only letters,
accented letters,
digits and white space
are significant in comparisons.
.TP
.B -f
Fold lower case
letters onto upper case.
Accented characters are folded to their
non-accented upper case form.
.TP
.B -i
Ignore characters outside the
.SM ASCII
range 040-0176
in non-numeric comparisons.
.TP
.B -w
Like
.BR -i ,
but ignore only tabs and spaces.
.TP
.B -n
An initial numeric string,
consisting of optional white space,
optional plus or minus sign,
and zero or more digits with optional decimal point,
is sorted by arithmetic value.
.TP
.B -g
Numbers, like
.B -n
but with optional
.BR e -style
exponents, are sorted by value.
.TP
.B -r
Reverse the sense of comparisons.
.TP
.BI -t x\^
`Tab character' separating fields is
.IR x .
.PP
The notation
.BI + "pos1\| " - pos2\^
restricts a sort key to a field beginning at
.I pos1\^
and ending just before
.IR pos2 .
.I Pos1\^
and
.I pos2\^
each have the form
.IB m . n\f1,
optionally followed by one or more of the flags
.BR Mbdfginr ,
where
.I m\^
tells a number of fields to skip from the beginning of the line and
.I n\^
tells a number of characters to skip further.
If any flags are present they override all the global
ordering options for this key.
A missing
.BI \&. n\^
means
.BR \&.0 ;
a missing
.BI - pos2\^
means the end of the line.
Under the
.BI -t x\^
option, fields are strings separated by
.IR x ;
otherwise fields are
non-empty strings separated by white space.
White space before a field
is part of the field, except under option
.BR -b .
A
.B b
flag may be attached independently to
.IR pos1
and
.IR pos2.
.PP
The notation
.B -k
.IR pos1 [, pos2 ]
is how POSIX
.I sort
defines fields:
.I pos1
and
.I pos2
have the same format but different meanings.
The value of
.I m\^
is origin 1 instead of origin 0
and a missing
.BI \&. n\^
in
.I pos2
is the end of the field.
.PP
When there are multiple sort keys, later keys
are compared only after all earlier keys
compare equal.
Lines that otherwise compare equal are ordered
with all bytes significant.
.PP
These option arguments are also understood:
.TP \w'\fL-z\fIrecsize\fLXX'u
.B -c
Check that the single input file is sorted according to the ordering rules;
give no output unless the file is out of sort.
.TP
.B -m
Merge; assume the input files are already sorted.
.TP
.B -u
Suppress all but one in each
set of equal lines.
Ignored bytes
and bytes outside keys
do not participate in
this comparison.
.TP
.B -o
The next argument is the name of an output file
to use instead of the standard output.
This file may be the same as one of the inputs.
.TP
.BI -T dir
Put temporary files in
.I dir
rather than in
.BR /tmp .
.ne 4
.SH EXAMPLES
.TP
.L sort -u +0f +0 list
Print in alphabetical order all the unique spellings
in a list of words
where capitalized words differ from uncapitalized.
.TP
.L sort -t: +1 /adm/users
Print the users file
sorted by user name
(the second colon-separated field).
.TP
.L sort -umM dates
Print the first instance of each month in an already sorted file.
Options
.B -um
with just one input file make the choice of a
unique representative from a set of equal lines predictable.
.TP
.L
grep -n '^' input | sort -t: +1f +0n | sed 's/[0-9]*://'
A stable sort: input lines that compare equal will
come out in their original order.
.SH FILES
.BI /tmp/sort. <pid>.<ordinal>
.SH SOURCE
.B /sys/src/cmd/sort.c
.SH SEE ALSO
.IR uniq (1),
.IR look (1)
.SH DIAGNOSTICS
.I Sort
comments and exits with non-null status for various trouble
conditions and for disorder discovered under option
.BR -c .
.SH BUGS
An external null character can be confused
with an internally generated end-of-field character.
The result can make a sub-field not sort
less than a longer field.
.PP
Some of the options, e.g.
.B -i
and
.BR -M ,
are hopelessly provincial.

96
man/man1/spell.1 Normal file
View File

@@ -0,0 +1,96 @@
.TH SPELL 1
.SH NAME
spell, sprog \- find spelling errors
.SH SYNOPSIS
.B spell
[
.I options
]
\&...
[
.I file
]
\&...
.PP
.B sprog
[
.I options
]
[
.B -f
.I file
]
.SH DESCRIPTION
.I Spell
looks up words from the named
.I files
(standard input default)
in a spelling list and places
possible misspellings\(emwords
not sanctioned there\(emon the standard output.
.PP
.I Spell
ignores constructs of
.IR troff (1)
and its standard preprocessors.
It understands these options:
.TP
.B -b
Check British spelling.
.TP
.B -v
Print all words not literally in the spelling list, with
derivations.
.TP
.B -x
Print, marked with
.LR = ,
every stem as it is looked up in the spelling list,
along with its affix classes.
.PP
As a matter of policy,
.I spell
does not admit multiple spellings of the same word.
Variants that follow general rules are preferred
over those that don't, even when the unruly spelling is
more common.
Thus, in American usage, `modelled', `sizeable', and `judgment' are
rejected in favor of `modeled', `sizable', and `judgement'.
Agglutinated variants are shunned: `crewmember' and `backyard'
cede to `crew member' and `back yard' (noun) or `back-yard'
(adjective).
.SH FILES
.TF /sys/lib/brspell
.TP
.B /sys/lib/amspell
American spelling list
.TP
.B /sys/lib/brspell
British spelling list
.TP
.B /bin/aux/sprog
The actual spelling checker.
It expects one word per line on standard input,
and takes the same arguments as
.IR spell .
.SH SOURCE
.TF /sys/src/cmd/spell
.TP
.B /rc/bin/spell
the script
.TP
.B /sys/src/cmd/spell
source for
.I sprog
.SH SEE ALSO
.IR deroff (1)
.SH BUGS
The heuristics of
.IR deroff (1)
used to excise formatting information are imperfect.
.br
The spelling list's coverage is uneven;
in particular biology, medicine, and chemistry, and
perforce proper names,
not to mention languages other than English,
are covered very lightly.

82
man/man1/split.1 Normal file
View File

@@ -0,0 +1,82 @@
.TH SPLIT 1
.CT 1 files
.SH NAME
split \- split a file into pieces
.SH SYNOPSIS
.B split
[
.I option ...
]
[
.I file
]
.SH DESCRIPTION
.I Split
reads
.I file
(standard input by default)
and writes it in pieces of 1000
lines per output file.
The names of the
output files are
.BR xaa ,
.BR xab ,
and so on to
.BR xzz .
The options are
.TP
.BI -n " n"
Split into
.IR n -line
pieces.
.TP
.BI -l " n"
Synonym for
.B -n
.IR n ,
a nod to Unix's syntax.
.TP
.BI -e " expression"
File divisions occur at each line
that matches a regular
.IR expression ;
see
.IR regexp (6).
Multiple
.B -e
options may appear.
If a subexpression of
.I expression
is contained in parentheses
.BR ( ... ) ,
the output file name is the portion of the
line which matches the subexpression.
.TP
.BI -f " stem
Use
.I stem
instead of
.B x
in output file names.
.TP
.BI -s " suffix
Append
.I suffix
to names identified under
.BR -e .
.TP
.B -x
Exclude the matched input line from the output file.
.TP
.B -i
Ignore case in option
.BR -e ;
force output file names (excluding the suffix)
to lower case.
.SH SOURCE
.B /sys/src/cmd/split.c
.SH SEE ALSO
.IR sed (1),
.IR awk (1),
.IR grep (1),
.IR regexp (6)

28
man/man1/strings.1 Normal file
View File

@@ -0,0 +1,28 @@
.TH STRINGS 1
.SH NAME
strings \- extract printable strings
.SH SYNOPSIS
.B strings
[
.I file ...
]
.SH DESCRIPTION
.I Strings
finds and prints strings containing 6 or more
consecutive printable UTF-encoded characters
in a (typically) binary file, default
standard input.
Printable characters are taken to be
.SM ASCII
characters from blank through tilde (hexadecimal 20 through 7E), inclusive,
and
all other characters from value 00A0 to FFFF.
Strings reports
the decimal offset within the file at which the string starts and the text
of the string. If the string is longer than 70 runes the line is
terminated by three dots and the printing is resumed on the next
line with the offset of the continuation line.
.SH SOURCE
.B /sys/src/cmd/strings.c
.SH SEE ALSO
.IR nm (1)

77
man/man1/sum.1 Normal file
View File

@@ -0,0 +1,77 @@
.TH SUM 1
.SH NAME
sum, md5sum, sha1sum \- sum and count blocks in a file
.SH SYNOPSIS
.B sum
[
.B -5r
]
[
.I file ...
]
.PP
.B md5sum
[
.I file ...
]
.PP
.B sha1sum
[
.I file ...
]
.SH DESCRIPTION
By default,
.I sum
calculates and prints a 32-bit hexadecimal checksum,
a byte count,
and the name of
each
.IR file .
The checksum is also a function of the input length.
If no files are given,
the standard input is
summed.
Other summing algorithms are available.
The options are
.TP
.B -r
Sum with the algorithm of System V's
.B "sum -r"
and print the length (in 1K blocks) of the input.
.TP
.B -5
Sum with System V's default algorithm
and print the length (in 512-byte blocks) of the input.
.PP
.I Sum
is typically used to look for bad spots,
to validate a file communicated over
some transmission line or
as a quick way to determine if two files on different machines might be the same.
.PP
.B Md5sum
computes the 32 hex digit RSA Data Security, Inc. MD5 Message-Digest Algorithm
described in RFC1321.
If no
.I files
are given,
the standard input is
summed.
.PP
.B Sha1sum
computes the 40 hex digit National Institute of Standards and Technology SHA1 secure hash algorithm
described in FIPS PUB 180-1.
If no
.I files
are given,
the standard input is
summed.
.SH SOURCE
.B /sys/src/cmd/sum.c
.br
.B /sys/src/cmd/md5sum.c
.br
.B /sys/src/cmd/sha1sum.c
.SH "SEE ALSO"
.IR cmp (1),
.IR wc (1)

87
man/man1/tail.1 Normal file
View File

@@ -0,0 +1,87 @@
.TH TAIL 1
.SH NAME
tail \- deliver the last part of a file
.SH SYNOPSIS
.B tail
[
.BR +- \fInumber\fP[ lbc ][ rf ]
]
[
.I file
]
.PP
.B tail
[
.B -fr
]
[
.B -n
.I nlines
]
[
.B -c
.I nbytes
]
[
.I file
]
.SH DESCRIPTION
.I Tail
copies the named file to the standard output beginning
at a designated place.
If no file is named, the standard input is copied.
.PP
Copying begins at position
.BI + number
measured from the beginning, or
.BI - number
from the end of the input.
.I Number
is counted in lines, 1K blocks or bytes,
according to the appended flag
.LR l ,
.LR b ,
or
.LR c .
Default is
.B -10l
(ten ell).
.PP
The further flag
.L r
causes tail to print lines from the end of the file in reverse order;
.L f
(follow) causes
.IR tail ,
after printing to the end, to keep watch and
print further data as it appears.
.PP
The second syntax is that promulgated by POSIX, where
the
.I numbers
rather than the options are signed.
.SH EXAMPLES
.TP
.B tail file
Print the last 10 lines of a file.
.TP
.B tail +0f file
Print a file, and continue to watch
data accumulate as it grows.
.TP
.B sed 10q file
Print the first 10 lines of a file.
.SH SOURCE
.B /sys/src/cmd/tail.c
.SH BUGS
Tails relative to the end of the file
are treasured up in a buffer, and thus
are limited in length.
.br
According to custom, option
.BI + number
counts lines from 1, and counts
blocks and bytes from 0.
.br
.I Tail
is ignorant of UTF.

118
man/man1/tar.1 Normal file
View File

@@ -0,0 +1,118 @@
.TH TAR 1
.SH NAME
tar \- archiver
.SH SYNOPSIS
.B tar
.I key
[
.I file ...
]
.SH DESCRIPTION
.PP
.I Tar
saves and restores file trees.
It is most often used to transport a tree of files from one
system to another.
The
.I key
is a string that contains
at most one function letter plus optional modifiers.
Other arguments to the command are names of
files or directories to be dumped or restored.
A directory name implies all the contained
files and subdirectories (recursively).
.PP
The function is one of the following letters:
.TP
.B c
Create a new archive with the given files as contents.
.TP
.B x
Extract the named files from the archive.
If a file is a directory, the directory is extracted recursively.
Modes are restored if possible.
If no file argument is given, extract the entire archive.
If the archive contains multiple entries for a file,
the latest one wins.
.TP
.B t
List all occurrences of each
.I file
in the archive, or of all files if there are no
.I file
arguments.
.TP
.B r
The named files
are appended to the archive.
.PP
The modifiers are:
.TP
.B v
(verbose)
Print the name of each file treated
preceded by the function letter.
With
.BR t ,
give more details about the
archive entries.
.TP
.B f
Use the next argument as the name of the archive instead of
the default standard input (for keys
.B x
and
.BR t )
or standard output (for keys
.B c
and
.BR r ).
.TP
.B u
Use the next (numeric) argument as the user id for files in
the output archive. This is only useful when moving files to
a non-Plan 9 system.
.TP
.B g
Use the next (numeric) argument as the group id for files in
the output archive.
.TP
.B p
Create archive in POSIX ustar format,
which raises the maximum pathname length from 100 to 256 bytes.
Ustar archives are recognised automatically by
.I tar
when reading archives.
.TP
.B R
When extracting, ignore leading slash on file names,
i.e., extract all files relative to the current directory.
.TP
.B T
Modifies the behavior of
.B x
to set the mode and modified time
of each file to that specified in the archive.
.SH EXAMPLES
.I Tar
can be used to copy hierarchies thus:
.IP
.EX
@{cd fromdir && tar cp .} | @{cd todir && tar xT}
.EE
.SH SOURCE
.B /sys/src/cmd/tar.c
.SH SEE ALSO
.IR ar (1),
.IR bundle (1),
.IR tapefs (1)
.SH BUGS
There is no way to ask for any but the last
occurrence of a file.
.br
File path names are limited to
100 characters
(256 when using ustar format).
.br
The tar format allows specification of links and symbolic links,
concepts foreign to Plan 9: they are ignored.

28
man/man1/tee.1 Normal file
View File

@@ -0,0 +1,28 @@
.TH TEE 1
.SH NAME
tee \- pipe fitting
.SH SYNOPSIS
.B tee
[
.B -i
]
[
.B -a
]
.I files
.SH DESCRIPTION
.I Tee
transcribes the standard input to the standard
output and makes copies in the
.IR files .
The options are
.TP
.B -i
Ignore interrupts.
.TP
.B -a
Append the output to the
.I files
rather than rewriting them.
.SH SOURCE
.B /sys/src/cmd/tee.c

211
man/man1/test.1 Normal file
View File

@@ -0,0 +1,211 @@
.TH TEST 1
.SH NAME
test \- set status according to condition
.SH SYNOPSIS
.B test
.I expr
.SH DESCRIPTION
.I Test
evaluates the expression
.IR expr .
If the value is true the exit status is null; otherwise the
exit status is non-null.
If there are no arguments the exit status is non-null.
.PP
The following primitives are used to construct
.IR expr .
.TP "\w'\fIn1 \fL-eq \fIn2\fLXX'u"
.BI -r " file"
True if the file exists (is accessible) and is readable.
.PD0
.TP
.BI -w " file"
True if the file exists and is writable.
.TP
.BI -x " file"
True if the file exists and has execute permission.
.TP
.BI -e " file
True if the file exists.
.TP
.BI -f " file"
True if the file exists and is a plain file.
.TP
.BI -d " file"
True if the file exists and is a directory.
.TP
.BI -s " file"
True if the file exists and has a size greater than zero.
.TP
.BI -t " fildes
True if the open file whose file descriptor number is
.I fildes
(1 by default)
is the same file as
.BR /dev/cons .
.TP
.BI -A " file"
True if the file exists and is append-only.
.TP
.BI -L " file"
True if the file exists and is exclusive-use.
.TP
.BI -T "file"
True if the file exists and is temporary.
.TP
.IB s1 " = " s2
True
if the strings
.I s1
and
.I s2
are identical.
.TP
.IB s1 " != " s2
True
if the strings
.I s1
and
.I s2
are not identical.
.TP
s1
True if
.I s1
is not the null string.
(Deprecated.)
.TP
.BI -n " s1"
True if the length of string
.I s1
is non-zero.
.TP
.BI -z " s1"
True if the length of string
.I s1
is zero.
.TP
.IB n1 " -eq " n2
True if the integers
.I n1
and
.I n2
are arithmetically equal.
Any of the comparisons
.BR -ne ,
.BR -gt ,
.BR -ge ,
.BR -lt ,
or
.BR -le
may be used in place of
.BR -eq .
The (nonstandard) construct
.BI -l " string\f1,
meaning the length of
.IR string ,
may be used in place of an integer.
.TP
.IB a " -nt " b
True if file
.I a
is newer than (modified after) file
.IR b .
.TP
.IB a " -ot " b
True if file
.I a
is older than (modified before) file
.IR b .
.TP
.IB f " -older " t
True if file
.I f
is older than (modified before) time
.IR t .
If
.I t
is a integer followed by the letters
.BR y (years),
.BR M (months),
.BR d (days),
.BR h (hours),
.BR m (minutes),
or
.BR s (seconds),
it represents current time minus the specified time.
If there is no letter, it represents seconds since
epoch.
You can also concatenate mixed units. For example,
.B 3d12h
means three days and twelve hours ago.
.PD
.PP
These primaries may be combined with the
following operators:
.TP "\w'\fL( \fIexpr\fL )XX'u"
.B !
unary negation operator
.PD0
.TP
.B -o
binary
.I or
operator
.TP
.B -a
binary
.I and
operator; higher precedence than
.BR -o
.TP
.BI "( " expr " )"
parentheses for grouping.
.PD
.PP
The primitives
.BR -b ,
.BR -u ,
.BR -g ,
and
.BR -s
return false; they are recognized for compatibility with POSIX.
.PP
Notice that all the operators and flags are separate
arguments to
.IR test .
Notice also that parentheses and equal signs are meaningful
to
.I rc
and must be enclosed in quotes.
.SH EXAMPLES
.I Test
is a dubious way to check for specific character strings:
it uses a process to do what an
.IR rc (1)
match or switch statement can do.
The first example is not only inefficient but wrong, because
.I test
understands the purported string
.B \&"-c"
as an option.
.IP
.EX
if (test $1 '=' "-c") echo OK # wrong!
.EE
.LP
A better way is
.IP
.EX
if (~ $1 -c) echo OK
.EE
.PP
Test whether
.L abc
is in the current directory.
.IP
.B test -f abc -o -d abc
.SH SOURCE
.B /sys/src/cmd/test.c
.SH "SEE ALSO"
.IR rc (1)

21
man/man1/time.1 Normal file
View File

@@ -0,0 +1,21 @@
.TH TIME 1
.SH NAME
time \- time a command
.SH SYNOPSIS
.B time
.I command
[
.I arg ...
]
.SH DESCRIPTION
The
.I command
is executed with the given arguments; after it is complete,
.I time
reports on standard error the program's elapsed user time,
system time, and real time, in seconds,
followed by the command line.
.SH SOURCE
.B /sys/src/cmd/time.c
.SH "SEE ALSO"
.IR prof (1)

35
man/man1/touch.1 Normal file
View File

@@ -0,0 +1,35 @@
.TH TOUCH 1
.SH NAME
touch \- set modification date of a file
.SH SYNOPSIS
.B touch
[
.B -c
]
[
.B -t
.I time
]
.I file ...
.SH DESCRIPTION
.I Touch
attempts to set the modification time of the
.I files
to
.I time
(by default, the current time).
If a
.I file
does not exist,
it will be created unless option
.B -c
is present.
.SH SOURCE
.B /sys/src/cmd/touch.c
.SH SEE ALSO
.IR ls (1),
.IR stat (2),
.IR chmod (1)
.SH BUGS
.I Touch
will not touch directories.

97
man/man1/tr.1 Normal file
View File

@@ -0,0 +1,97 @@
.TH TR 1
.SH NAME
tr \- translate characters
.SH SYNOPSIS
.B tr
[
.B -cds
]
[
.I string1
[
.I string2
]
]
.SH DESCRIPTION
.I Tr
copies the standard input to the standard output with
substitution or deletion of selected characters (runes).
Input characters found in
.I string1
are mapped into the corresponding characters of
.IR string2 .
When
.I string2
is short it is padded to the length of
.I string1
by duplicating its last character.
Any combination of the options
.B -cds
may be used:
.TP
.B -c
Complement
.IR string1 :
replace it with a lexicographically ordered
list of all other characters.
.TP
.B -d
Delete from input all characters in
.IR string1 .
.TP
.B -s
Squeeze repeated output characters that occur in
.I string2
to single characters.
.PP
In either string a noninitial sequence
.BI - x\f1,
where
.I x
is any character (possibly quoted), stands for
a range of characters:
a possibly empty sequence of codes running from
the successor of the previous code up through
the code for
.IR x .
The character
.L \e
followed by 1, 2 or 3 octal digits stands for the
character whose
16-bit
value is given by those digits.
The character sequence
.L \ex
followed by 1, 2, 3, or 4 hexadecimal digits stands
for the character whose
16-bit value is given by those digits.
A
.L \e
followed by any other character stands
for that character.
.SH EXAMPLES
Replace all upper-case
.SM ASCII
letters by lower-case.
.IP
.EX
tr A-Z a-z <mixed >lower
.EE
.PP
Create a list of all
the words in
.L file1
one per line in
.LR file2 ,
where a word is taken to be a maximal string of alphabetics.
.I String2
is given as a quoted newline.
.IP
.EX
tr -cs A-Za-z '
\&' <file1 >file2
.EE
.SH SOURCE
.B /sys/src/cmd/tr.c
.SH "SEE ALSO"
.IR sed (1)

59
man/man1/uniq.1 Normal file
View File

@@ -0,0 +1,59 @@
.TH UNIQ 1
.SH NAME
uniq \- report repeated lines in a file
.SH SYNOPSIS
.B uniq
[
.B -udc
[
.BI +- num
]
]
[
.I file
]
.SH DESCRIPTION
.I Uniq
copies the input
.IR file ,
or the standard input, to the
standard output, comparing adjacent lines.
In the normal case, the second and succeeding copies
of repeated lines are
removed.
Repeated lines must be adjacent
in order to be found.
.TP
.B -u
Print unique lines.
.TP
.B -d
Print (one copy of) duplicated lines.
.TP
.B -c
Prefix a repetition count and a tab to each output line.
Implies
.B -u
and
.BR -d .
.TP
.BI - num
The first
.IR num
fields
together with any blanks before each are ignored.
A field is defined as a string of non-space, non-tab characters
separated by tabs and spaces from its neighbors.
.TP
.BI + num
The first
.IR num
characters are ignored.
Fields are skipped before characters.
.SH SOURCE
.B /sys/src/cmd/uniq.c
.SH "SEE ALSO"
.IR sort (1)
.SH BUGS
Field selection and comparison should be compatible with
.IR sort (1).

53
man/man1/wc.1 Normal file
View File

@@ -0,0 +1,53 @@
.TH WC 1
.SH NAME
wc \- word count
.SH SYNOPSIS
.B wc
[
.B -lwrbc
]
[
.I file ...
]
.SH DESCRIPTION
.I Wc
counts lines, words, runes, syntactically-invalid
.SM UTF
codes and bytes in the named
.IR files ,
or in the standard input if no file is named.
A word is a maximal string of characters
delimited by spaces, tabs or newlines.
The count of runes includes invalid codes.
.PP
If the optional argument is present,
just the specified counts (lines, words, runes, broken
.SM UTF
codes or bytes)
are selected by the letters
.BR l ,
.BR w ,
.BR r ,
.BR b ,
or
.BR c .
Otherwise, lines, words and bytes
.RB ( -lwc )
are reported.
.SH SOURCE
.B /sys/src/cmd/wc.c
.SH BUGS
The Unicode Standard has many blank characters scattered through it,
but
.I wc
looks for only
.SM ASCII
space, tab and newline.
.br
.I Wc
should have options to count suboptimal
.SM UTF
codes
and bytes that cannot occur in any
.SM UTF
code.

87
man/man1/xd.1 Normal file
View File

@@ -0,0 +1,87 @@
.TH XD 1
.SH NAME
xd \- hex, octal, decimal, or ASCII dump
.SH SYNOPSIS
.B xd
[
.I option ...
]
[
.BI - "format ...
] [
.I file ...
]
.SH DESCRIPTION
.I Xd
concatenates and dumps the
.I files
(standard input by default)
in one or more formats.
Groups of 16 bytes are printed in each of the named formats, one
format per line.
Each line of output is prefixed by its address (byte offset)
in the input file.
The first line of output for each group is zero-padded; subsequent are blank-padded.
.PP
Formats other than
.B -c
are specified by pairs of characters telling size and style,
.L 4x
by default.
The sizes are
.TP \w'2\ or\ w\ \ \ 'u
.BR 1 " or " b
1-byte units.
.PD0
.TP
.BR 2 " or " w
2-byte big-endian units.
.TP
.BR 4 " or " l
4-byte big-endian units.
.TP
.BR 8 " or " v
8-byte big-endian units.
.PD
.PP
The styles are
.TP 0
.B o
Octal.
.PD0
.TP
.B x
Hexadecimal.
.TP
.B d
Decimal.
.PD
.PP
Other options are
.TP \w'\fL-a\fIstyle\fLXX'u
.B -c
Format as
.B 1x
but print
.SM ASCII
representations or C escape sequences where possible.
.TP
.BI -a style
Print file addresses in the given style (and size 4).
.TP
.B -u
(Unbuffered) Flush the output buffer after each 16-byte sequence.
.TP
.B -s
Reverse (swab) the order of bytes in each group of 4 before printing.
.TP
.B -r
Print repeating groups of identical 16-byte sequences as the first group
followed by an asterisk.
.SH SOURCE
.B /sys/src/cmd/xd.c
.SH "SEE ALSO"
.IR db (1)
.SH BUGS
The various output formats don't line up properly in the output of
.IR xd .

167
man/man1/yacc.1 Normal file
View File

@@ -0,0 +1,167 @@
.TH YACC 1
.SH NAME
yacc \- yet another compiler-compiler
.SH SYNOPSIS
.B yacc
[
.I option ...
]
.I grammar
.SH DESCRIPTION
.I Yacc
converts a context-free grammar and translation code
into a set of
tables for an LR(1) parser and translator.
The grammar may be ambiguous;
specified precedence rules are used to break ambiguities.
.PP
The output file,
.BR y.tab.c ,
must be compiled by the C compiler
to produce a program
.LR yyparse .
This program must be loaded with a lexical analyzer function,
.B yylex(void)
(often generated by
.IR lex (1)),
with a
.B main(int argc, char *argv[])
program, and with an error handling routine,
.BR yyerror(char*) .
.PP
The options are
.TP "\w'\fL-o \fIoutput\fLXX'u"
.BI -o " output
Direct output to the specified file instead of
.BR y.tab.c .
.TP
.BI -D n
Create file
.BR y.debug ,
containing diagnostic messages.
To incorporate them in the parser, compile it with preprocessor symbol
.B yydebug
defined.
The amount of
diagnostic output from the parser is regulated by
value
.IR n .
The value 0 reports errors; 1 reports reductions;
higher values (up to 4) include more information about
state transitions.
.TP
.B -v
Create file
.BR y.output ,
containing a description of the parsing tables and of
conflicts arising from ambiguities in the grammar.
.TP
.B -d
Create file
.BR y.tab.h ,
containing
.B #define
statements that associate
.IR yacc -assigned
`token codes' with user-declared `token names'.
Include it in source files other than
.B y.tab.c
to give access to the token codes.
.TP
.BI -s " stem
Change the prefix
.L y
of the file names
.BR y.tab.c ,
.BR y.tab.h ,
.BR y.debug ,
and
.B y.output
to
.IR stem .
.TP
.B -S
Write a parser that uses
Stdio
instead of the
.B print
routines in libc.
.PP
The specification of
.I yacc
itself is essentially the same as the UNIX version
described in the references mentioned below.
Besides the
.B -D
option, the main relevant differences are:
.IP
The interface to the C environment is by default through
.B <libc.h>
rather than
.BR <stdio.h> ;
the
.B -S
option reverses this.
.IP
The parser accepts
.SM UTF
input text (see
.IR utf (6)),
which has a couple of effects.
First, the return value of
.B yylex()
no longer fits in a
.BR short ;
second, the starting value for non-terminals is now 0xE000 rather than 257.
.IP
The generated parser can be recursive: actions can call
.IR yyparse ,
for example to implement a sort of
.B #include
statement in an interpreter.
.IP
Finally, some undocumented inner workings of the parser have been
changed, which may affect programs that know too much about its structure.
.SH FILES
.TF /sys/lib/yaccpars
.TP
.B y.output
.TP
.B y.tab.c
.TP
.B y.tab.h
.TP
.B y.debug
.TP
.B y.tmp.*
temporary file
.TP
.B y.acts.*
temporary file
.TP
.B /sys/lib/yaccpar
parser prototype
.TP
.B /sys/lib/yaccpars
parser prototype using stdio
.SH SOURCE
.B /sys/src/cmd/yacc.c
.SH "SEE ALSO"
.IR lex (1)
.br
S. C. Johnson and R. Sethi,
``Yacc: A parser generator'',
.I
Unix Research System Programmer's Manual,
Tenth Edition, Volume 2
.br
B. W. Kernighan and Rob Pike,
.I
The UNIX Programming Environment,
Prentice Hall, 1984
.SH BUGS
The parser may not have full information when it writes to
.B y.debug
so that the names of the tokens returned by
.L yylex
may be missing.

760
man/man3/9p.3 Normal file
View File

@@ -0,0 +1,760 @@
.TH 9P 3
.SH NAME
Srv,
dirread9p,
emalloc9p,
erealloc9p,
estrdup9p,
postfd,
postmountsrv,
readbuf,
readstr,
respond,
threadpostmountsrv,
srv \- 9P file service
.SH SYNOPSIS
.ft L
.nf
#include <u.h>
#include <libc.h>
#include <fcall.h>
#include <thread.h>
#include <9p.h>
.fi
.PP
.ft L
.nf
.ta \w'\fL1234'u +\w'\fLTree* 'u
typedef struct Srv {
Tree* tree;
void (*attach)(Req *r);
void (*auth)(Req *r);
void (*open)(Req *r);
void (*create)(Req *r);
void (*read)(Req *r);
void (*write)(Req *r);
void (*remove)(Req *r);
void (*flush)(Req *r);
void (*stat)(Req *r);
void (*wstat)(Req *r);
void (*walk)(Req *r);
char* (*walk1)(Fid *fid, char *name, Qid *qid);
char* (*clone)(Fid *oldfid, Fid *newfid);
void (*destroyfid)(Fid *fid);
void (*destroyreq)(Req *r);
void (*end)(Srv *s);
void* aux;
int infd;
int outfd;
int srvfd;
int nopipe;
} Srv;
.fi
.PP
.nf
.ft L
.ta \w'\fLvoid* 'u
int srv(Srv *s)
void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
int postfd(char *srvname, int fd)
void respond(Req *r, char *error)
ulong readstr(Req *r, char *src)
ulong readbuf(Req *r, void *src, ulong nsrc)
typedef int Dirgen(int n, Dir *dir, void *aux)
void dirread9p(Req *r, Dirgen *gen, void *aux)
void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
char *(*clone)(Fid *old, Fid *new, void *v), void *v)
.fi
.PP
.nf
.ft L
.ta \w'\fLvoid* 'u
void* emalloc9p(ulong n)
void* erealloc9p(void *v, ulong n)
char* estrdup9p(char *s)
.fi
.PP
.nf
.ft L
extern int chatty9p;
.fi
.SH DESCRIPTION
The function
.I srv
serves a 9P session by reading requests from
.BR s->infd ,
dispatching them to the function pointers kept in
.BR Srv ,
and
writing the responses to
.BR s->outfd .
(Typically,
.I postmountsrv
or
.I threadpostmountsrv
initializes the
.B infd
and
.B outfd
structure members. See the description below.)
.PP
.B Req
and
.B Fid
structures are allocated one-to-one with uncompleted
requests and active fids, and are described in
.IR 9pfid (2).
.PP
The behavior of
.I srv
depends on whether there is a file tree
(see
.IR 9pfile (2))
associated with the server, that is,
whether the
.B tree
element is nonzero.
The differences are made explicit in the
discussion of the service loop below.
The
.B aux
element is the client's, to do with as it pleases.
.PP
.I Srv
does not return until the 9P conversation is finished.
Since it is usually run in a separate process so that
the caller can exit, the service loop has little chance
to return gracefully on out of memory errors.
It calls
.IR emalloc9p ,
.IR erealloc9p ,
and
.I estrdup9p
to obtain its memory.
The default implementations of these functions
act as
.IR malloc ,
.IR realloc ,
and
.I strdup
but abort the program if they run out of memory.
If alternate behavior is desired, clients can link against
alternate implementations of these functions.
.PP
.I Postmountsrv
and
.I threadpostmountsrv
are wrappers that create a separate process in which to run
.IR srv .
They do the following:
.IP
If
.IB s -> nopipe
is zero (the common case),
initialize
.IB s -> infd
and
.IB s -> outfd
to be one end of a freshly allocated pipe,
with
.IB s -> srvfd
initialized as the other end.
.IP
If
.B name
is non-nil, call
.BI postfd( s -> srvfd ,
.IB name )
to post
.IB s -> srvfd
as
.BI /srv/ name .
.IP
Fork a child process via
.I rfork
(see
.IR fork (2))
or
.I procrfork
(see
.IR thread (2)),
using the
.BR RFFDG ,
.RR RFNOTEG ,
.BR RFNAMEG ,
and
.BR RFMEM
flags.
The child process
calls
.IB close( s -> srvfd )
and then
.IB srv( s ) \fR;
it will exit once
.I srv
returns.
.IP
If
.I mtpt
is non-nil,
call
.BI amount( s -> srvfd,
.IB mtpt ,
.IB flag ,
\fB"")\fR;
otherwise, close
.IB s -> srvfd \fR.
.IP
The parent returns to the caller.
.LP
If any error occurs during
this process, the entire process is terminated by calling
.I sysfatal
(see
.IR perror (2)).
.SS Service functions
The functions in a
.B Srv
structure named after 9P transactions
are called to satisfy requests as they arrive.
If a function is provided, it
.I must
arrange for
.I respond
to be called when the request is satisfied.
The only parameter of each service function
is a
.B Req*
parameter (say
.IR r ).
The incoming request parameters are stored in
.IB r -> ifcall \fR;
.IB r -> fid
and
.IB r -> newfid
are pointers to
.B Fid
structures corresponding to the
numeric fids in
.IB r -> ifcall \fR;
similarly,
.IB r -> oldreq
is the
.B Req
structure corresponding to
.IB r -> ifcall.oldtag \fR.
The outgoing response data should be stored in
.IB r -> ofcall \fR.
The one exception to this rule is that
.I stat
should fill in
.IB r -> d
rather than
.IB r -> ofcall.stat \fR:
the library will convert the structure into the machine-independent
wire representation.
Similarly,
.I wstat
may consult
.IB r -> d
rather than decoding
.IB r -> ifcall . stat
itself.
When a request has been handled,
.I respond
should be called with
.I r
and an error string.
If the request was satisfied successfully, the error
string should be a nil pointer.
Note that it is permissible for a function to return
without itself calling
.IR respond ,
as long as it has arranged for
.I respond
to be called at some point in the future
by another proc sharing its address space,
but see the discussion of
.I flush
below.
Once
.I respond
has been called, the
.B Req*
as well as any pointers it once contained must
be considered freed and not referenced.
.PP
If the service loop detects an error in a request
(e.g., an attempt to reuse an extant fid, an open of
an already open fid, a read from a fid opened for write, etc.)
it will reply with an error without consulting
the service functions.
.PP
The service loop provided by
.I srv
(and indirectly by
.I postmountsrv
and
.IR threadpostmountsrv )
is single-threaded.
If it is expected that some requests might
block, arranging for alternate processes
to handle them is suggested.
.PP
The constraints on the service functions are as follows.
These constraints are checked while the server executes.
If a service function fails to do something it ought to have,
.I srv
will call
.I endsrv
and then abort.
.TP
.I Auth
If authentication is desired,
the
.I auth
function should record that
.I afid
is the new authentication fid and
set
.I afid->qid
and
.IR ofcall.qid .
.I Auth
may be nil, in which case it will be treated as having
responded with the error
.RI `` "argv0: authentication not required" ,''
where
.I argv0
is the program name variable as set by
.I ARGBEGIN
(see
.IR arg (2)).
.TP
.I Attach
The
.I attach
function should check the authentication state of
.I afid
if desired,
and set
.IB r -> fid -> qid
and
.I ofcall.qid
to the qid of the file system root.
.I Attach
may be nil only if file trees are in use;
in this case, the qid will be filled from the root
of the tree, and no authentication will be done.
.TP
.I Walk
If file trees are in use,
.I walk
is handled internally, and
.IB srv -> walk
is never called.
.IP
If file trees are not in use,
.I walk
should consult
.IB r -> ifcall . wname
and
.IB r -> ifcall . nwname \fR,
filling in
.IB ofcall . qid
and
.IB ofcall . nqid \fR,
and also copying any necessary
.I aux
state from
.IB r -> fid
to
.IB r -> newfid
when the two are different.
As long as
.I walk
sets
.IB ofcall . nqid
appropriately, it can
.I respond
with a nil error string even when 9P
demands an error
.RI ( e.g. ,
in the case of a short walk);
the library detects error conditions and handles them appropriately.
.IP
Because implementing the full walk message is intricate and
prone to error, the helper routine
.I walkandclone
will handle the request given pointers to two functions
.I walk1
and (optionally)
.I clone .
.IR Clone ,
if non-nil, is called to signal the creation of
.I newfid
from
.IR oldfid .
Typically a
.I clone
routine will copy or increment a reference count in
.IR oldfid 's
.I aux
element.
.I Walk1
should walk
.I fid
to
.IR name ,
initializing
.IB fid -> qid
to the new path's qid.
Both should return nil
on success or an error message on error.
.I Walkandclone
will call
.I respond
after handling the request.
.TP
.I Walk1\fR, \fPClone
If the client provides functions
.IB srv -> walk1
and (optionally)
.IB srv -> clone \fR,
the 9P service loop will call
.I walkandclone
with these functions to handle the request.
Unlike the
.I walk1
above,
.IB srv -> walk1
must fill in both
.IB fid -> qid
and
.BI * qid
with the new qid on a successful walk.
.TP
.I Open
If file trees are in use, the file
metadata will be consulted on open, create, remove, and wstat
to see if the requester has the appropriate permissions.
If not, an error will be sent back without consulting a service function.
.PP
If not using file trees or the user has the appropriate permissions,
.I open
is called with
.IB r -> ofcall . qid
already initialized to the one stored in the
.B Fid
structure (that is, the one returned in the previous walk).
If the qid changes, both should be updated.
.TP
.I Create
The
.I create
function must fill in
both
.IB r -> fid -> qid
and
.IB r -> ofcall . qid
on success.
When using file trees,
.I create
should allocate a new
.B File
with
.IR createfile ;
note that
.I createfile
may return nil (because, say, the file already exists).
If the
.I create
function is nil,
.I srv
behaves as though it were a function that always responded
with the error ``create prohibited''.
.TP
.I Remove
.I Remove
should mark the file as removed, whether
by calling
.I removefile
when using file trees, or by updating an internal data structure.
In general it is not a good idea to clean up the
.I aux
information associated with the corresponding
.B File
at this time, to avoid memory errors if other
fids have references to that file.
Instead, it is suggested that
.I remove
simply mark the file as removed (so that further
operations on it know to fail) and wait until the
file tree's destroy function is called to reclaim the
.I aux
pointer.
If not using file trees, it is prudent to take the
analogous measures.
If
.I remove
is not provided, all remove requests will draw
``remove prohibited'' errors.
.TP
.I Read
The
.I read
function must be provided; it fills
.IB r -> ofcall . data
with at most
.IB r -> ifcall . count
bytes of data from offset
.IB r -> ifcall . offset
of the file.
It also sets
.IB r -> ofcall . count
to the number of bytes being returned.
If using file trees,
.I srv
will handle reads of directories internally, only
calling
.I read
for requests on files.
.I Readstr
and
.I readbuf
are useful for satisfying read requests on a string or buffer.
Consulting the request in
.IB r -> ifcall \fR,
they fill
.IB r -> ofcall . data
and set
.IB r -> ofcall . count \fR;
they do not call
.IB respond .
Similarly,
.I dirread9p
can be used to handle directory reads in servers
not using file trees.
The passed
.I gen
function will be called as necessary to
fill
.I dir
with information for the
.IR n th
entry in the directory.
The string pointers placed in
.I dir
should be fresh copies
made with
.IR estrdup9p ;
they will be freed by
.I dirread9p
after each successful call to
.IR gen .
.I Gen
should return zero if it successfully filled
.IR dir ,
minus one on end of directory.
.TP
.I Write
The
.I write
function is similar but need not be provided.
If it is not, all writes will draw
``write prohibited'' errors.
Otherwise,
.I write
should attempt to write the
.IB r -> ifcall . count
bytes of
.IB r -> ifcall . data
to offset
.IB r -> ifcall . offset
of the file, setting
.IB r -> ofcall . count
to the number of bytes actually written.
Most programs consider it an error to
write less than the requested amount.
.TP
.I Stat
.I Stat
should fill
.IB r -> d
with the stat information for
.IB r -> fid \fR.
If using file trees,
.IB r -> d
will have been initialized with the stat info from
the tree, and
.I stat
itself may be nil.
.TP
.I Wstat
The
.I wstat
consults
.IB r -> d
in changing the metadata for
.IB r -> fid
as described in
.IR stat (5).
When using file trees,
.I srv
will take care to check that the request satisfies
the permissions outlined in
.IR stat (5).
Otherwise
.I wstat
should take care to enforce permissions
where appropriate.
.TP
.I Flush
Single-threaded servers, which always call
.I respond
before returning from the service functions,
need not provide a
.I flush
implementation:
.I flush
is only necessary in multithreaded programs,
which arrange for
.I respond
to be called asynchronously.
.I Flush
should cause the request
.IB r -> oldreq
to be cancelled or hurried along.
If
.I oldreq
is cancelled, this should be signalled by calling
.I respond
on
.I oldreq
with error string
.RB ` interrupted '.
.I Flush
must respond to
.I r
with a nil error string.
.I Flush
may respond to
.I r
before forcing a response to
.IB r -> oldreq \fR.
In this case, the library will delay sending
the
.I Rflush
message until the response to
.IB r -> oldreq
has been sent.
.PD
.PP
.IR Destroyfid ,
.IR destroyreq ,
and
.I end
are auxiliary functions, not called in direct response to 9P requests.
.TP
.I Destroyfid
When a
.BR Fid 's
reference count drops to zero
.RI ( i.e.,
it has been clunked and there are no outstanding
requests referring to it),
.I destroyfid
is called to allow the program to dispose
of the
.IB fid -> aux
pointer.
.TP
.I Destroyreq
Similarly, when a
.BR Req 's
reference count drops to zero
.RI ( i.e. ,
it has been handled via
.I respond
and other outstanding pointers to it have been closed),
.I destroyreq
is called to allow the program to dispose of the
.IB r -> aux
pointer.
.TP
.I End
Once the 9P service loop has finished
(end of file been reached on the service pipe
or a bad message has been read),
.I end
is called (if provided) to allow any final cleanup.
For example, it was used by the Palm Pilot synchronization
file system (never finished) to gracefully terminate the serial conversation once
the file system had been unmounted.
After calling
.IR end ,
the service loop (which runs in a separate process
from its caller) terminates using
.I _exits
(see
.IR exits (2)).
.PD
.PP
If the
.B chatty9p
flag is at least one,
a transcript of the 9P session is printed
on standard error.
If the
.B chatty9p
flag is greater than one,
additional unspecified debugging output is generated.
By convention, servers written using this library
accept the
.B -D
option to increment
.BR chatty9p .
.SH EXAMPLES
.IR Archfs (4),
.IR cdfs (4),
.IR nntpfs (4),
.IR snap (4),
and
.B /sys/src/lib9p/ramfs.c
are good examples of simple single-threaded file servers.
.IR Webfs (4)
and
.I sshnet
(see
.IR ssh (1))
are good examples of multithreaded file servers.
.PP
In general, the
.B File
interface is appropriate for maintaining arbitrary file trees (as in
.IR ramfs ).
The
.B File
interface is best avoided when the
tree structure is easily generated as necessary;
this is true when the tree is highly structured (as in
.I cdfs
and
.IR nntpfs )
or is maintained elsewhere.
.SH SOURCE
.B /sys/src/lib9p
.SH SEE ALSO
.IR 9pfid (2),
.IR 9pfile (2),
.IR srv (3),
.IR intro (5)
.SH BUGS
The switch to 9P2000 was taken as an opportunity to tidy
much of the interface; we promise to avoid such gratuitous change
in the future.

116
man/man3/9pcmdbuf.3 Normal file
View File

@@ -0,0 +1,116 @@
.TH 9PCMDBUF 3
.SH NAME
Cmdbuf, parsecmd, respondcmderror, lookupcmd \- control message parsing
.SH SYNOPSIS
.ft L
.nf
#include <u.h>
#include <libc.h>
#include <fcall.h>
#include <thread.h>
#include <9p.h>
.fi
.PP
.ft L
.nf
.ta \w'\fL1234'u +\w'\fL12345678'u
typedef struct Cmdbuf
{
char *buf;
char **f;
int nf;
} Cmdbuf;
typedef struct Cmdtab
{
int index;
char *cmd;
int narg;
};
Cmdbuf *parsecmd(char *p, int n)
Cmdtab *lookupcmd(Cmdbuf *cb, Cmdtab *tab, int ntab)
void respondcmderror(Req *r, Cmdbuf *cb, char *fmt, ...)
.fi
.SH DESCRIPTION
These data structures and functions provide parsing of textual control messages.
.PP
.I Parsecmd
treats the
.I n
bytes at
.I p
(which need not be NUL-terminated) as a UTF string and splits it
using
.IR tokenize (2).
It returns a
.B Cmdbuf
structure holding pointers to each field in the message.
.PP
.I Lookupcmd
walks through the array
.IR ctab ,
which has
.I ntab
entries,
looking for the first
.B Cmdtab
that matches the parsed command.
(If the parsed command is empty,
.I lookupcmd
returns nil immediately.)
A
.B Cmdtab
matches the command if
.I cmd
is equal to
.IB cb -> f [0]
or if
.I cmd
is
.LR * .
Once a matching
.B Cmdtab
has been found, if
.I narg
is not zero, then the parsed command
must have exactly
.I narg
fields (including the command string itself).
If the command has the wrong number of arguments,
.I lookupcmd
returns nil.
Otherwise, it returns a pointer to the
.B Cmdtab
entry.
If
.I lookupcmd
does not find a matching command at all,
it returns nil.
Whenever
.I lookupcmd
returns nil, it sets the system error string.
.PP
.I Respondcmderror
resoponds to request
.I r
with an error of the form
`\fIfmt\fB:\fI cmd\fR,'
where
.I fmt
is the formatted string and
.I cmd
is a reconstruction of the parsed command.
Fmt
is often simply
.B "%r" .
.SH EXAMPLES
This interface is not used in any distributed 9P servers.
It was lifted from the Plan 9 kernel.
Almost any kernel driver
.RB ( /sys/src/9/*/dev*.c )
is a good example.
.SH SOURCE
.B /sys/src/lib9p/parse.c
.SH SEE ALSO
.IR 9p (2)

204
man/man3/9pfid.3 Normal file
View File

@@ -0,0 +1,204 @@
.TH 9PFID 3
.SH NAME
Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, removefid,
Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq, lookupreq, removereq \- 9P fid, request tracking
.SH SYNOPSIS
.ft L
.nf
#include <u.h>
#include <libc.h>
#include <fcall.h>
#include <thread.h>
#include <9p.h>
.fi
.PP
.ft L
.nf
.ta \w'\fL 'u +\w'\fLulong 'u
typedef struct Fid
{
ulong fid;
char omode; /* -1 if not open */
char *uid;
Qid qid;
File *file;
void *aux;
\fI...\fP
} Fid;
.fi
.PP
.ft L
.nf
.ta \w'\fL 'u +\w'\fLulong 'u
typedef struct Req
{
ulong tag;
Fcall ifcall;
Fcall ofcall;
Req *oldreq;
void *aux;
\fI...\fP
} Req;
.fi
.PP
.ft L
.nf
.ta \w'\fLFidpool* 'u
Fidpool* allocfidpool(void (*destroy)(Fid*))
void freefidpool(Fidpool *p)
Fid* allocfid(Fidpool *p, ulong fid)
Fid* lookupfid(Fidpool *p, ulong fid)
void closefid(Fid *f)
void removefid(Fid *f)
.fi
.PP
.ft L
.nf
.ta \w'\fLReqpool* 'u
Reqpool* allocreqpool(void (*destroy)(Req*))
void freereqpool(Reqpool *p)
Req* allocreq(Reqpool *p, ulong tag)
Req* lookupreq(Reqpool *p, ulong tag)
void closereq(Req *f)
void removereq(Req *r)
.fi
.SH DESCRIPTION
These routines provide management of
.B Fid
and
.B Req
structures from
.BR Fidpool s
and
.BR Reqpool s.
They are primarily used by the 9P server loop
described in
.IR 9p (2).
.PP
.B Fid
structures are intended to represent
active fids in a 9P connection, as
.B Chan
structures do in the Plan 9 kernel.
The
.B fid
element is the integer fid used in the 9P
connection.
.B Omode
is the mode under which the fid was opened, or
.B -1
if this fid has not been opened yet.
Note that in addition to the values
.BR OREAD ,
.BR OWRITE ,
and
.BR ORDWR ,
.B omode
can contain the various flags permissible in
an open call.
To ignore the flags, use
.BR omode&OMASK .
.B Omode
should not be changed by the client.
The fid derives from a successful authentication by
.BR uid .
.B Qid
contains the qid returned in the last successful
.B walk
or
.B create
transaction involving the fid.
In a file tree-based server, the
.BR Fid 's
.B file
element points at a
.B File
structure
(see
.IR 9pfile (2))
corresponding to the fid.
The
.B aux
member is intended for use by the
client to hold information specific to a particular
.BR Fid .
With the exception of
.BR aux ,
these elements should be treated
as read-only by the client.
.PP
.I Allocfidpool
creates a new
.BR Fidpool .
.I Freefidpool
destroys such a pool.
.I Allocfid
returns a new
.B Fid
whose fid number is
.IR fid .
There must not already be an extant
.B Fid
with that number in the pool.
Once a
.B Fid
has been allocated, it can be looked up by
fid number using
.IR lookupfid .
.BR Fid s
are reference counted: both
.I allocfid
and
.I lookupfid
increment the reference count on the
.B Fid
structure before
returning.
When a reference to a
.B Fid
is no longer needed,
.I closefid
should be called to note the destruction of the reference.
When the last reference to a
.B Fid
is removed, if
.I destroy
(supplied when creating the fid pool)
is not zero, it is called with the
.B Fid
as a parameter.
It should perform whatever cleanup is necessary
regarding the
.B aux
element.
.I Removefid
is equivalent to
.I closefid
but also removes the
.B Fid
from the pool.
Note that due to lingering references,
the return of
.I removefid
may not mean that
.I destroy
has been called.
.PP
.IR Allocreqpool ,
.IR freereqpool ,
.IR allocreq ,
.IR lookupreq ,
.IR closereq ,
and
.I removereq
are analogous but
operate on
.BR Reqpool s
and
.B Req
structures.
.SH SOURCE
.B /sys/src/lib9p
.SH SEE ALSO
.IR 9p (2),
.IR 9pfile (2)

223
man/man3/9pfile.3 Normal file
View File

@@ -0,0 +1,223 @@
.TH 9PFILE 3
.SH NAME
Tree, alloctree, freetree,
File, createfile, closefile, removefile, walkfile,
opendirfile, readdirfile, closedirfile, hasperm \- in-memory file hierarchy
.SH SYNOPSIS
.ft L
.nf
#include <u.h>
#include <libc.h>
#include <fcall.h>
#include <thread.h>
#include <9p.h>
.fi
.PP
.ft L
.nf
.ta \w'\fLFile 'u
typedef struct File
{
Ref;
Dir;
void *aux;
\fI...\fP
} File;
.fi
.PP
.ft L
.nf
.ta \w'\fLTree 'u
typedef struct Tree
{
File *root;
\fI...\fP
} Tree;
.fi
.PP
.ft L
.nf
.ta \w'\fLReaddir* 'u +4n +4n
Tree* alloctree(char *uid, char *gid, ulong mode,
void (*destroy)(File*))
void freetree(Tree *tree)
File* createfile(File *dir, char *name, char *uid,
ulong mode, void *aux)
int removefile(File *file)
void closefile(File *file)
File* walkfile(File *dir, char *path)
Readdir* opendirfile(File *dir)
long readdirfile(Readdir *rdir, char *buf, long n)
void closedirfile(Readdir *rdir)
int hasperm(File *file, char *uid, int p)
.fi
.SH DESCRIPTION
.BR File s
and
.BR Tree s
provide an in-memory file hierarchy
intended for use in 9P file servers.
.PP
.I Alloctree
creates a new tree of files, and
.I freetree
destroys it.
The root of the tree
(also the
.B root
element in the structure)
will have mode
.I mode
and be owned by user
.I uid
and group
.IR gid .
.I Destroy
is used when freeing
.B File
structures and is described later.
.PP
.BR File s
(including directories)
other than the root are created using
.IR createfile ,
which attempts to create a file named
.I name
in the directory
.IR dir .
If created, the file will have owner
.I uid
and have a group inherited from
the directory.
.I Mode
and the permissions of
.I dir
are used to calculate the permission bits for
the file as described in
.IR open (5).
It is permissible for
.I name
to be a slash-separated path rather than a single element.
.PP
.I Removefile
removes a file from the file tree.
The file will not be freed until the last
reference to it has been removed.
Directories may only be removed when empty.
.I Removefile
returns zero on success, \-1 on error.
It is correct to consider
.I removefile
to be
.I closefile
with the side effect of removing the file
when possible.
.PP
.I Walkfile
evaluates
.I path
relative to the directory
.IR dir ,
returning the resulting file,
or zero if the named file or any intermediate element
does not exist.
.PP
The
.B File
structure's
.B aux
pointer may be used by the client
for
.RB per- File
storage.
.BR File s
are reference-counted: if not zero,
.I destroy
(specified in the call to
.IR alloctree )
will be called for each file when its
last reference is removed or when the tree is freed.
.I Destroy
should take care of any necessary cleanup related to
.BR aux .
When creating new file references by copying pointers,
call
.I incref
(see
.IR lock (2))
to update the reference count.
To note the removal of a reference to a file, call
.IR closefile .
.I Createfile
and
.I walkfile
return new references.
.IR Removefile ,
.IR closefile ,
and
.I walkfile
(but not
.IR createfile )
consume the passed reference.
.PP
Directories may be read, yielding a directory entry structure
(see
.IR stat (5))
for each file in the directory.
In order to allow concurrent reading of directories,
clients must obtain a
.B Readdir
structure by calling
.I opendirfile
on a directory.
Subsequent calls to
.I readdirfile
will each yield an integral number of machine-independent
stat buffers, until end of directory.
When finished, call
.I closedirfile
to free the
.BR Readdir .
.PP
.I Hasperm
does simplistic permission checking; it assumes only
one-user groups named by uid and returns non-zero if
.I uid
has permission
.I p
(a bitwise-or of
.BR AREAD ,
.BR AWRITE
and
.BR AEXEC )
according to
.IB file ->mode \fR.
9P servers written using
.B File
trees will do standard permission checks automatically;
.I hasperm
may be called explicitly to do additional checks.
A 9P server may link against a different
.I hasperm
implementation to provide more complex groups.
.SH EXAMPLE
The following code correctly handles references
when elementwise walking a path and creating a file.
.IP
.EX
f = tree->root;
incref(f);
for(i=0; i<n && f!=nil; i++)
f = walkfile(f, elem[i]);
if(f == nil)
return nil;
nf = createfile(f, "foo", "nls", 0666, nil);
closefile(f);
return nf;
.EE
.SH SOURCE
.B /sys/src/lib9p/file.c
.SH SEE ALSO
.IR 9p (2)
.SH BUGS
The reference counting is cumbersome.

18
man/man3/abort.3 Normal file
View File

@@ -0,0 +1,18 @@
.TH ABORT 3
.SH NAME
abort \- generate a fault
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.nf
.B
void abort(void)
.fi
.SH DESCRIPTION
.I Abort
causes an access fault, causing the current process to enter the `Broken' state.
The process can then be inspected by a debugger.
.SH SOURCE
.B /sys/src/libc/9sys/abort.c

33
man/man3/abs.3 Normal file
View File

@@ -0,0 +1,33 @@
.TH ABS 3
.SH NAME
abs, labs \- integer absolute values
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int abs(int a)
.PP
.B
long labs(long a)
.SH DESCRIPTION
.I Abs
returns
the absolute value of integer
.IR a ,
and
.I labs
does the same for a long.
.SH SOURCE
.B /sys/src/libc/port/abs.c
.SH SEE ALSO
.IR floor (2)
for
.I fabs
.SH DIAGNOSTICS
.I Abs
and
.I labs
return
the most negative integer or long when the true result is unrepresentable.

60
man/man3/access.3 Normal file
View File

@@ -0,0 +1,60 @@
.TH ACCESS 3
.SH NAME
access \- determine accessibility of file
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int access(char *name, int mode)
.SH DESCRIPTION
.I Access
evaluates the given
file
.I name
for accessibility.
If \fImode\fL&4\fR
is nonzero,
read permission is expected;
if \fImode\fL&2\fR,
write permission;
if \fImode\fL&1\fR,
execute permission.
If \fImode\fL==0\fR,
the file merely need exist.
In any case
all directories leading to the file
must permit searches.
Zero is returned if the desired access is permitted,
\-1 if not.
.PP
Only access for open is checked.
A file may look executable, but
.IR exec (2)
will fail unless it is in proper format.
.PP
The include file
.F <libc.h>
defines
.BR AEXIST =0,
.BR AEXEC =1,
.BR AWRITE =2,
and
.BR AREAD =4.
.PP
.SH SOURCE
.B /sys/src/libc/9sys/access.c
.SH SEE ALSO
.IR stat (2)
.SH DIAGNOSTICS
Sets
.IR errstr .
.SH BUGS
Since file permissions are checked by the server and group information
is not known to the client,
.I access
must open the file to check permissions.
(It calls
.IR stat (2)
to check simple existence.)

188
man/man3/addpt.3 Normal file
View File

@@ -0,0 +1,188 @@
.TH ADDPT 3
.SH NAME
addpt, subpt, mulpt, divpt, rectaddpt, rectsubpt, insetrect, canonrect, eqpt, eqrect, ptinrect, rectinrect, rectXrect, rectclip, combinerect, Dx, Dy, Pt, Rect, Rpt \- arithmetic on points and rectangles
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <draw.h>
.PP
.B
Point addpt(Point p, Point q)
.PP
.B
Point subpt(Point p, Point q)
.PP
.B
Point mulpt(Point p, int a)
.PP
.B
Point divpt(Point p, int a)
.PP
.B
Rectangle rectaddpt(Rectangle r, Point p)
.PP
.B
Rectangle rectsubpt(Rectangle r, Point p)
.PP
.B
Rectangle insetrect(Rectangle r, int n)
.PP
.B
Rectangle canonrect(Rectangle r)
.PP
.B
int eqpt(Point p, Point q)
.PP
.B
int eqrect(Rectangle r, Rectangle s)
.PP
.B
int ptinrect(Point p, Rectangle r)
.PP
.B
int rectinrect(Rectangle r, Rectangle s)
.PP
.B
int rectXrect(Rectangle r, Rectangle s)
.PP
.B
int rectclip(Rectangle *rp, Rectangle b)
.PP
.B
void combinerect(Rectangle *rp, Rectangle b)
.PP
.B
int Dx(Rectangle r)
.PP
.B
int Dy(Rectangle r)
.PP
.B
Point Pt(int x, int y)
.PP
.B
Rectangle Rect(int x0, int y0, int x1, int y1)
.PP
.B
Rectangle Rpt(Point p, Point q)
.SH DESCRIPTION
The functions
.IR Pt ,
.I Rect
and
.I Rpt
construct geometrical data types from their components.
.PP
.I Addpt
returns the Point
sum of its arguments:
.BI Pt( p .x+ q .x,
.IB p .y+ q .y) \f1.
.I Subpt
returns the Point
difference of its arguments:
.BI Pt( p .x- q .x,
.IB p .y- q .y) \f1.
.I Mulpt
returns the Point
.BI Pt( p .x* a ,
.IB p .y* a ) \f1.
.I Divpt
returns the Point
.BI Pt( p .x/ a ,
.IB p .y/ a ) \f1.
.PP
.I Rectaddpt
returns the Rectangle
.BI Rect(add( r .min,
.IB p ) \f1,
.BI add( r .max,
.IB p )) \f1;
.I rectsubpt
returns the Rectangle
.BI Rpt(sub( r .min,
.IB p ),
.BI sub( r .max,
.IB p ))\fR.
.PP
.I Insetrect
returns the Rectangle
.BI Rect( r .min.x+ n \f1,
.IB r .min.y+ n \f1,
.IB r .max.x- n \f1,
.IB r .max.y- n ) \f1.
.PP
.I Canonrect
returns a rectangle with the same extent as
.IR r ,
canonicalized so that
.B min.x
≤
.BR max.x ,
and
.B min.y
≤
.BR max.y .
.PP
.I Eqpt
compares its argument Points and returns
0 if unequal,
1 if equal.
.I Eqrect
does the same for its argument Rectangles.
.PP
.I Ptinrect
returns 1 if
.I p
is a point within
.IR r ,
and 0 otherwise.
.PP
.I Rectinrect
returns 1 if all the pixels in
.I r
are also in
.IR s ,
and 0 otherwise.
.PP
.I RectXrect
returns 1 if
.I r
and
.I s
share any point, and 0 otherwise.
.PP
.I Rectclip
clips in place
the Rectangle pointed to by
.I rp
so that it is completely contained within
.IR b .
The return value is 1 if any part of
.RI * rp
is within
.IR b .
Otherwise, the return value is 0 and
.RI * rp
is unchanged.
.PP
.I Combinerect
overwrites
.B *rp
with the smallest rectangle sufficient to cover all the pixels of
.B *rp
and
.BR b .
.PP
The functions
.I Dx
and
.I Dy
give the width (Δx) and height (Δy) of a Rectangle.
They are implemented as macros.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2)

51
man/man3/aes.3 Normal file
View File

@@ -0,0 +1,51 @@
.TH AES 3
.SH NAME
setupAESstate, aesCBCencrypt, aesCBCdecrypt - advanced encryption standard (rijndael)
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mp.h>
.br
.B #include <libsec.h>
.PP
.B
void setupAESstate(AESstate *s, uchar key[], int keybytes, uchar *ivec)
.PP
.B
void aesCBCencrypt(uchar*, int, AESstate*)
.PP
.B
void aesCBCdecrypt(uchar*, int, AESstate*)
.PP
.SH DESCRIPTION
.PP
DES is being replaced by Rijndael, also known as AES, as the preferred
block ciper.
.IR setupAESstate ,
.IR aesCBCencrypt ,
and
.I aesCBCdecrypt
implement cipher block chaining encryption.
.I Keybytes
should be 16, 24, or 32.
The initialization vector
.I ivec
of
.I AESbsize
bytes should random enough to be unlikely to be reused but does not need to be
cryptographically strongly unpredictable.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR blowfish (2),
.IR des (2),
.IR dsa (2),
.IR elgamal (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)

348
man/man3/allocimage.3 Normal file
View File

@@ -0,0 +1,348 @@
.TH ALLOCIMAGE 3
.SH NAME
allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline \- allocating, freeing, reading, writing images
.SH SYNOPSIS
.nf
.PP
.B
#include <u.h>
.B
#include <libc.h>
.B
#include <draw.h>
.PP
.ta \w'\fLImage 'u
.B
Image *allocimage(Display *d, Rectangle r,
.br
.B
ulong chan, int repl, int col)
.PP
.B
Image *allocimagemix(Display *d, ulong one, ulong three)
.PP
.B
void freeimage(Image *i)
.PP
.B
int nameimage(Image *i, char *name, int in)
.PP
.B
Image *namedimage(Display *d, char *name)
.PP
.B
ulong setalpha(ulong color, uchar alpha)
.PP
.B
int loadimage(Image *i, Rectangle r, uchar *data, int ndata)
.PP
.B
int cloadimage(Image *i, Rectangle r, uchar *data, int ndata)
.PP
.B
int unloadimage(Image *i, Rectangle r, uchar *data, int ndata)
.PP
.B
Image *readimage(Display *d, int fd, int dolock)
.PP
.B
int writeimage(int fd, Image *i, int dolock)
.PP
.B
int bytesperline(Rectangle r, int d)
.PP
.B
int wordsperline(Rectangle r, int d)
.PP
.nf
.B
enum
.nf
.ft L
.ta +4n +20
{
DOpaque = 0xFFFFFFFF,
DTransparent = 0x00000000,
DBlack = 0x000000FF,
DWhite = 0xFFFFFFFF,
DRed = 0xFF0000FF,
DGreen = 0x00FF00FF,
DBlue = 0x0000FFFF,
DCyan = 0x00FFFFFF,
DMagenta = 0xFF00FFFF,
DYellow = 0xFFFF00FF,
DPaleyellow = 0xFFFFAAFF,
DDarkyellow = 0xEEEE9EFF,
DDarkgreen = 0x448844FF,
DPalegreen = 0xAAFFAAFF,
DMedgreen = 0x88CC88FF,
DDarkblue = 0x000055FF,
DPalebluegreen = 0xAAFFFFFF,
DPaleblue = 0x0000BBFF,
DBluegreen = 0x008888FF,
DGreygreen = 0x55AAAAFF,
DPalegreygreen = 0x9EEEEEFF,
DYellowgreen = 0x99994CFF,
DMedblue = 0x000099FF,
DGreyblue = 0x005DBBFF,
DPalegreyblue = 0x4993DDFF,
DPurpleblue = 0x8888CCFF,
DNotacolor = 0xFFFFFF00,
DNofill = DNotacolor,
};
.fi
.SH DESCRIPTION
A new
.B Image
on
.B Display
.B d
is allocated with
.BR allocimage ;
it will have the rectangle, pixel channel format,
and replication flag
given by its arguments.
Convenient pixel channels like
.BR GREY1 ,
.BR GREY2 ,
.BR CMAP8 ,
.BR RGB16 ,
.BR RGB24 ,
and
.BR RGBA32
are predefined.
All the new image's pixels will have initial value
.IR col .
If
.I col
is
.BR DNofill ,
no initialization is done.
Representative useful values of color are predefined:
.BR DBlack ,
.BR DWhite ,
.BR DRed ,
and so on.
Colors are specified by 32-bit numbers comprising,
from most to least significant byte,
8-bit values for red, green, blue, and alpha.
The values correspond to illumination, so 0 is black and 255 is white.
Similarly, for alpha 0 is transparent and 255 is opaque.
The
.I id
field will have been set to the identifying number used by
.B /dev/draw
(see
.IR draw (3)),
and the
.I cache
field will be zero.
If
.I repl
is true, the clip rectangle is set to a very large region; if false, it is set to
.IR r .
The
.I depth
field will be set to the number of bits per pixel specified
by the channel descriptor
(see
.IR image (6)).
.I Allocimage
returns 0 if the server has run out of image memory.
.PP
.I Allocimagemix
is used to allocate background colors.
On 8-bit color-mapped displays, it
returns a 2×2 replicated image with one pixel colored
the color
.I one
and the other three with
.IR three .
(This simulates a wider range of tones than can be represented by a single pixel
value on a color-mapped display.)
On true color displays, it returns a 1×1 replicated image
whose pixel is the result of mixing the two colors in
a one to three ratio.
.PP
.I Freeimage
frees the resources used by its argument image.
.PP
.I Nameimage
publishes in the server the image
.I i
under the given
.IR name .
If
.I in
is non-zero, the image is published; otherwise
.I i
must be already named
.I name
and it is withdrawn from publication.
.I Namedimage
returns a reference to the image published under the given
.I name
on
.B Display
.IR d .
These routines permit unrelated applications sharing a display to share an image;
for example they provide the mechanism behind
.B getwindow
(see
.IR graphics (2)).
.PP
The RGB values in a color are
.I premultiplied
by the alpha value; for example, a 50% red is
.B 0x7F00007F
not
.BR 0xFF00007F .
The function
.I setalpha
performs the alpha computation on a given
.BR color ,
ignoring its initial alpha value, multiplying the components by the supplied
.BR alpha .
For example, to make a 50% red color value, one could execute
.B setalpha(DRed,
.BR 0x7F) .
.PP
The remaining functions deal with moving groups of pixel
values between image and user space or external files.
There is a fixed format for the exchange and storage of
image data
(see
.IR image (6)).
.PP
.I Unloadimage
reads a rectangle of pixels from image
.I i
into
.IR data ,
whose length is specified by
.IR ndata .
It is an error if
.I ndata
is too small to accommodate the pixels.
.PP
.I Loadimage
replaces the specified rectangle in image
.I i
with the
.I ndata
bytes of
.IR data .
.PP
The pixels are presented one horizontal line at a time,
starting with the top-left pixel of
.IR r .
In the data processed by these routines, each scan line starts with a new byte in the array,
leaving the last byte of the previous line partially empty, if necessary.
Pixels are packed as tightly as possible within
.IR data ,
regardless of the rectangle being extracted.
Bytes are filled from most to least significant bit order,
as the
.I x
coordinate increases, aligned so
.IR x =0
would appear as the leftmost pixel of its byte.
Thus, for
.B depth
1, the pixel at
.I x
offset 165 within the rectangle will be in a
.I data
byte at bit-position
.B 0x04
regardless of the overall
rectangle: 165 mod 8 equals 5, and
.B "0x80\ >>\ 5"
equals
.BR 0x04 .
.PP
.B Cloadimage
does the same as
.IR loadimage ,
but for
.I ndata
bytes of compressed image
.I data
(see
.IR image (6)).
On each call to
.IR cloadimage,
the
.I data
must be at the beginning of a compressed data block, in particular,
it should start with the
.B y
coordinate and data length for the block.
.PP
.IR Loadimage ,
.IR cloadimage ,
and
.I unloadimage
return the number of bytes copied.
.PP
.I Readimage
creates an image from data contained in an external file (see
.IR image (6)
for the file format);
.I fd
is a file descriptor obtained by opening such a file for reading.
The returned image is allocated using
.IR allocimage .
The
.I dolock
flag specifies whether the
.B Display
should be synchronized for multithreaded access; single-threaded
programs can leave it zero.
.PP
.I Writeimage
writes image
.I i
onto file descriptor
.IR fd ,
which should be open for writing.
The format is as described for
.IR readimage .
.PP
.I Readimage
and
.I writeimage
do not close
.IR fd .
.PP
.I Bytesperline
and
.I wordsperline
return the number of bytes or words occupied in memory by one scan line of rectangle
.I r
in an image with
.I d
bits per pixel.
.SH EXAMPLE
To allocate a single-pixel replicated image that may be used to paint a region red,
.EX
red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);
.EE
.SH SOURCE
.B /sys/src/libdraw
.SH "SEE ALSO"
.IR graphics (2),
.IR draw (2),
.IR draw (3),
.IR image (6)
.SH DIAGNOSTICS
These functions return pointer 0 or integer \-1 on failure, usually due to insufficient
memory.
.PP
May set
.IR errstr .
.SH BUGS
.B Depth
must be a divisor or multiple of 8.

124
man/man3/arg.3 Normal file
View File

@@ -0,0 +1,124 @@
.TH ARG 3
.SH NAME
ARGBEGIN, ARGEND, ARGC, ARGF, EARGF, arginit, argopt \- process option letters from argv
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.nf
.B ARGBEGIN {
.B char *ARGF();
.B char *EARGF(code);
.B Rune ARGC();
.B } ARGEND
.PP
.B extern char *argv0;
.SH DESCRIPTION
These macros assume the names
.I argc
and
.I argv
are in scope; see
.IR exec (2).
.I ARGBEGIN
and
.I ARGEND
surround code for processing program options.
The code
should be the cases of a C switch on
option characters;
it is executed once for each option character.
Options end after an argument
.BR -- ,
before an argument
.BR - ,
or before an argument that doesn't begin with
.BR - .
.PP
The function macro
.I ARGC
returns the current option character, as an integer.
.PP
The function macro
.I ARGF
returns the current option argument:
a pointer to the rest of the option string if not empty,
or the next argument in
.I argv
if any, or 0.
.I ARGF
must be called just once for each option
that takes an argument.
The macro
.I EARGF
is like
.I ARGF
but instead of returning zero
runs
.I code
and, if that returns, calls
.IR abort (2).
A typical value for
.I code
is
.BR usage() ,
as in
.BR EARGF(usage()) .
.PP
After
.IR ARGBEGIN ,
.I argv0
is a copy of
.BR argv[0]
(conventionally the name of the program).
.PP
After
.IR ARGEND ,
.I argv
points at a zero-terminated list of the remaining
.I argc
arguments.
.SH EXAMPLE
This C program can take option
.B b
and option
.BR f ,
which requires an argument.
.IP
.EX
.ta \w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u
#include <u.h>
#include <libc.h>
void
main(int argc, char *argv[])
{
char *f;
print("%s", argv[0]);
ARGBEGIN {
case 'b':
print(" -b");
break;
case 'f':
print(" -f(%s)", (f=ARGF())? f: "no arg");
break;
default:
print(" badflag('%c')", ARGC());
} ARGEND
print(" %d args:", argc);
while(*argv)
print(" '%s'", *argv++);
print("\en");
exits(nil);
}
.EE
.PP
Here is the output from running the command
.B
prog -bffile1 -r -f file2 arg1 arg2
.IP
.B
prog -b -f(file1) badflag('r') -f(file2) 2 args: 'arg1' 'arg2'
.PP
.SH SOURCE
.B /sys/include/libc.h

25
man/man3/assert.3 Normal file
View File

@@ -0,0 +1,25 @@
.TH ASSERT 3
.SH NAME
assert \- check program invariants
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
#define assert if(cond);else _assert("cond")
.PP
.B
void _assert(int cond)
.SH DESCRIPTION
.I Assert
is a preprocessor macro that
(via
.IR _assert )
prints a message and calls
.I abort
when
.I cond
is false.
.SH SOURCE
.B /sys/src/libc/port/_assert.c

146
man/man3/atof.3 Normal file
View File

@@ -0,0 +1,146 @@
.TH ATOF 3
.SH NAME
atof, atoi, atol, atoll, charstod, strtod, strtol, strtoll, strtoul, strtoull \- convert text to numbers
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.nf
.ta \w'\fLdouble 'u
.B
double atof(char *nptr)
.PP
.B
int atoi(char *nptr)
.PP
.B
long atol(char *nptr)
.PP
.B
vlong atoll(char *nptr)
.PP
.B
double charstod(int (*f)(void *), void *a)
.PP
.B
double strtod(char *nptr, char **rptr)
.PP
.B
long strtol(char *nptr, char **rptr, int base)
.PP
.B
vlong strtoll(char *nptr, char **rptr, int base)
.PP
.B
ulong strtoul(char *nptr, char **rptr, int base)
.PP
.B
vlong strtoull(char *nptr, char **rptr, int base)
.fi
.SH DESCRIPTION
.IR Atof ,
.IR atoi ,
.IR atol ,
and
.I atoll
convert a string pointed to by
.I nptr
to floating, integer, long integer, and long long integer
.RB ( vlong )
representation respectively.
The first unrecognized character ends the string.
Leading C escapes are understood, as in
.I strtol
with
.I base
zero (described below).
.PP
.I Atof
recognizes an optional string of tabs and spaces,
then an optional sign, then
a string of digits optionally containing a decimal
point, then an optional
.L e
or
.L E
followed
by an optionally signed integer.
.PP
.I Atoi
and
.I atol
recognize an optional string of tabs and spaces,
then an optional sign, then a string of
decimal digits.
.PP
.IR Strtod ,
.IR strtol ,
.IR strtoll ,
.IR strtoul ,
and
.I strtoull
behave similarly to
.I atof
and
.I atol
and, if
.I rptr
is not zero, set
.I *rptr
to point to the input character
immediately after the string converted.
.PP
.IR Strtol ,
.IR strtoll ,
.IR strtoul ,
and
.IR strtoull
interpret the digit string in the specified
.IR base ,
from 2 to 36,
each digit being less than the base.
Digits with value over 9 are represented by letters,
a-z or A-Z.
If
.I base
is 0, the input is interpreted as an integral constant in
the style of C (with no suffixed type indicators):
numbers are octal if they begin with
.LR 0 ,
hexadecimal if they begin with
.L 0x
or
.LR 0X ,
otherwise decimal.
.PP
.I Charstod
interprets floating point numbers in the manner of
.IR atof ,
but gets successive characters by calling
.BR (*\fIf\fP)(a) .
The last call to
.I f
terminates the scan, so it must have returned a character that
is not a legal continuation of a number.
Therefore, it may be necessary to back up the input stream one character
after calling
.IR charstod .
.SH SOURCE
.B /sys/src/libc/port
.SH SEE ALSO
.IR fscanf (2)
.SH DIAGNOSTICS
Zero is returned if the beginning of the input string is not
interpretable as a number; even in this case,
.I rptr
will be updated.
.br
These routines set
.IR errstr .
.SH BUGS
.I Atoi
and
.I atol
accept octal and hexadecimal numbers in the style of C,
contrary to the ANSI specification.

395
man/man3/auth.3 Normal file
View File

@@ -0,0 +1,395 @@
.TH AUTH 3
.SH NAME
amount, newns, addns, login, noworld, auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc, auth_rpc, auth_getkey, amount_getkey, auth_freeAI, auth_chuid, auth_challenge, auth_response, auth_freechal, auth_respond, auth_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users
.SH SYNOPSIS
.nf
.PP
.ft L
#include <u.h>
#include <libc.h>
#include <auth.h>
.fi
.ta 11n +4n +4n +4n +4n +4n +4n
.PP
.B
int newns(char *user, char *nsfile);
.PP
.B
int addns(char *user, char *nsfile);
.PP
.B
int amount(int fd, char *old, int flag, char *aname);
.PP
.B
int login(char *user, char *password, char *namespace);
.PP
.B
int noworld(char *user);
.PP
.B
AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...);
.PP
.B
AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey,
.br
.B char *params);
.PP
.B
AuthRpc* auth_allocrpc(int afd);
.PP
.B
void auth_freerpc(AuthRpc *rpc);
.PP
.B
uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n);
.PP
.B
int auth_getkey(char *proto, char *dom);
.PP
.B
int (*amount_getkey)(char*, char*);
.PP
.B
void auth_freeAI(AuthInfo *ai);
.PP
.B
int auth_chuid(AuthInfo *ai, char *ns);
.PP
.B
Chalstate* auth_challenge(char *fmt, ...);
.PP
.B
AuthInfo* auth_response(Chalstate*);
.PP
.B
void auth_freechal(Chalstate*);
.PP
.B
int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...);
.PP
.B
AuthInfo* auth_userpasswd(char*user, char*password);
.PP
.B
UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...);
.PP
.B
AuthInfo* auth_getinfo(int fd);
.SH DESCRIPTION
.PP
This library, in concert with
.IR factotum (4),
is used to authenticate users.
It provides the primary interface to
.IR factotum .
.PP
.I Newns
builds a name space for
.IR user .
It opens the file
.I nsfile
.RB ( /lib/namespace
is used if
.I nsfile
is null),
copies the old environment, erases the current name space,
sets the environment variables
.B user
and
.BR home ,
and interprets the commands in
.IR nsfile .
The format of
.I nsfile
is described in
.IR namespace (6).
.PP
.I Addns
also interprets and executes the commands in
.IR nsfile .
Unlike
.I newns
it applies the command to the current name space
rather than starting from scratch.
.PP
.I Amount
is like
.I mount
but performs any authentication required.
It should be used instead of
.I mount
whenever the file server being mounted requires authentication.
See
.IR bind (2)
for a definition of the arguments to
.I mount
and
.IR amount .
.PP
.I Login
changes the user id of the process
.I user
and recreates the namespace using the file
.I namespace
(default
.BR /lib/nnamespace ).
It uses
.I auth_userpassword
and
.IR auth_chuid .
.PP
.I Noworld
returns 1 if the user is in the group
.B noworld
in
.BR /adm/users .
Otherwise, it returns 0.
.I Noworld
is used by telnetd and ftpd to provide sandboxed
access for some users.
.PP
The following routines use the
.B AuthInfo
structure returned after a successful authentication by
.IR factotum (4).
.PP
.ne 8
.EX
.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
typedef struct
{
char *cuid; /* caller id */
char *suid; /* server id */
char *cap; /* capability */
int nsecret; /* length of secret */
uchar *secret; /* secret */
} AuthInfo;
.EE
.sp
The fields
.B cuid
and
.B suid
point to the authenticated ids of the client and server.
.B Cap
is a capability returned only to the server.
It can be passed to the
.IR cap (3)
device to change the user id of the process.
.B Secret
is an
.BR nsecret -byte
shared secret that can be used by the client and server to
create encryption and hashing keys for the rest of the
conversation.
.PP
.I Auth_proxy
proxies an authentication conversation between a remote
server reading and writing
.I fd
and a
.I factotum
file. The
.I factotum
file used is
.BR /mnt/factotum/rpc .
An
.B sprint
(see
.IR print (2))
of
.I fmt
and the variable arg list yields a key template (see
.IR factotum (4))
specifying the key to use.
The template must specify at least the protocol (
.BI proto= xxx )
and the role (either
.B role=client
or
.BR role=server ).
.I Auth_proxy
either returns an allocated
.B AuthInfo
structure, or sets the error string and
returns nil.
.PP
.I Fauth_proxy
can be used instead of
.I auth_proxy
if a single connection to
.I factotum
will be used for multiple authentications.
This is necessary, for example, for
.I newns
which must open the
.I factotum
file before wiping out the namespace.
.I Fauth_proxy
takes as an argument a pointer to an
.B AuthRPC
structure which contains an fd for an open connection to
.I factotum
in addition to storage and state information for
the protocol.
An
.B AuthRPC
structure is obtained by calling
.I auth_allocrpc
with the fd of an open
.I factotum
connection.
It is freed using
.IR auth_freerpc .
Individual commands can be sent to
.IR factotum (4)
by invoking
.IR auth_rpc .
.PP
Both
.I auth_proxy
and
.I fauth_proxy
take a pointer to a routine,
.IR getkey ,
to invoke should
.I factotum
not posess a key for the authentication. If
.I getkey
is nil, the authentication fails.
.I Getkey
is called with a key template for the desired
key.
We have provided a generic routine,
.IR auth_getkey ,
which queries the user for
the key information and passes it to
.IR factotum .
This is the default for the global variable,
.IR amount_getkey ,
which holds a pointer to the key prompting routine used by
.IR amount .
.PP
.I Auth_chuid
uses the
.B cuid
and
.B cap
fields of an
.B AuthInfo
structure to change the user id of the current
process and uses
.IR ns ,
default
.BR /lib/namespace ,
to build it a new name space.
.PP
.I Auth_challenge
and
.I auth_response
perform challenge/response protocols with
.IR factotum .
State between the challenge and response phase are
kept in the
.B Chalstate
structure:
.sp
.EX
struct Chalstate
{
char *user;
char chal[MAXCHLEN];
int nchal;
void *resp;
int nresp;
/* for implementation only */
int afd;
AuthRpc *rpc;
char userbuf[MAXNAMELEN];
int userinchal;
};
.EE
.sp
.I Auth_challenge
requires a key template generated by an
.B sprint
of
.I fmt
and the variable arguments. It must contain the protocol
(\fBproto=\fIxxx\fR)
and depending on the protocol, the user name (
.BI user= xxx \fR).\fP
.B P9cr
and
.B vnc
expect the user specified as an attribute in
the key template and
.BR apop ,
.BR cram ,
and
.BR chap
expect it in the
.B user
field of the arg to
.IR auth_response .
For all protocols, the response is returned
to
.I auth_response
in the
.I resp
field of the
.BR Chalstate .
.I Chalstate.nresp
must be the length of the response.
.PP
Supply to
.I auth_respond
a challenge string and the fmt and args specifying a key,
and it will use
.I factotum
to return the proper user and response.
.PP
.I Auth_userpasswd
verifies a simple user/password pair.
.I Auth_getuserpasswd
retrieves a user/password pair from
.I factotum
if permitted.
.PP
.I Auth_getinfo
reads an
.B AuthInfo
message from
.I fd
and converts it into a structure. It is only
used by the other routines in this library when
communicating with
.IR factotum .
.PP
.ne 8
.EX
.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
typedef struct UserPasswd {
char *user;
char *passwd;
} UserPasswd;
.EE
.sp
.PP
.I Auth_freeAI
is used to free an
.B AuthInfo
structure returned by one of these routines.
Similary
.I auth_freechal
frees a challenge/response state.
.SH SOURCE
.B /sys/src/libauth
.SH SEE ALSO
.IR factotum (4),
.IR authsrv (2),
.IR bind (2)
.SH DIAGNOSTICS
These routines set
.IR errstr .

223
man/man3/authsrv.3 Normal file
View File

@@ -0,0 +1,223 @@
.TH AUTHSRV 3
.SH NAME
authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp \- routines for communicating with authentication servers
.SH SYNOPSIS
.nf
.PP
.ft L
#include <u.h>
#include <libc.h>
#include <authsrv.h>
.fi
.ta 8n +4n +4n +4n +4n +4n +4n
.PP
.B
int authdial(char *netroot, char *ad);
.PP
.B
int passtokey(char key[DESKEYLEN], char *password)
.PP
.B
uchar nvcsum(void *mem, int len)
.PP
.B
int readnvram(Nvrsafe *nv, int flag);
.PPP
.B
int convT2M(Ticket *t, char *msg, char *key)
.PP
.B
void convM2T(char *msg, Ticket *t, char *key)
.PP
.B
int convA2M(Authenticator *a, char *msg, char *key)
.PP
.B
void convM2A(char *msg, Authenticator *a, char *key)
.PP
.B
int convTR2M(Ticketreq *tr, char *msg)
.PP
.B
void convM2TR(char *msg, Ticketreq *tr)
.PP
.B
int convPR2M(Passwordreq *pr, char *msg, char *key)
.PP
.B
void convM2PR(char *msg, Passwordreq *pr, char *key)
.PP
.B
int _asgetticket(int fd, char *trbuf, char *tbuf);
.PP
.B
int _asrdresp(int fd, char *buf, int len);
.SH DESCRIPTION
.PP
.I Authdial
dials an authentication server over the
network rooted at
.IR net ,
default
.BR /net .
The authentication domain,
.IR ad ,
specifies which server to call.
If
.I ad
is non-nil,
the connection server
.B cs
(see
.IR ndb (8))
is queried for an entry which contains
.B authdom=\fIad\fP
or
.BR dom=\fIad\fP ,
the former having precedence,
and which also contains an
.B auth
attribute.
The string dialed is then
.I netroot\fP!\fIserver\fP!ticket
where
.I server
is the value of the
.B auth
attribute.
If no entry is found, the error string is
set to ``no authentication server found''
and -1 is returned.
If
.I authdom
is nil, the string
.IB netroot !$auth! ticket
is used to make the call.
.PP
.I Passtokey
converts
.I password
into a DES key and stores the result in
.IR key .
It returns 0 if
.I password
could not be converted,
and 1 otherwise.
.PP
.I Readnvram
reads authentication information into the structure:
.EX
.ta 4n +4n +8n +4n +4n +4n +4n
struct Nvrsafe
{
char machkey[DESKEYLEN];
uchar machsum;
char authkey[DESKEYLEN];
uchar authsum;
char config[CONFIGLEN];
uchar configsum;
char authid[ANAMELEN];
uchar authidsum;
char authdom[DOMLEN];
uchar authdomsum;
};
.EE
.PP
On Sparc, MIPS, and SGI machines this information is
in non-volatile ram, accessible in the file
.BR #r/nvram .
On x86s and Alphas
.I readnvram
successively opens the following areas stopping with the
first to succeed:
.PP
\- the partition named by the
.B $nvram
environment variable
(commonly set via
.IR plan9.ini (8))
.br
\- the partition
.B #S/sdC0/nvram
.br
\- a file called
.B plan9.nvr
in the partition
.B #S/sdC0/9fat
.br
\- the partition
.B #S/sd00/nvram
.br
\- a file called
.B plan9.nvr
in the partition
.B #S/sd00/9fat
.br
\- a file called
.B plan9.nvr
on a DOS floppy in drive 0
.br
\- a file called
.B plan9.nvr
on a DOS floppy in drive 1
.PP
The
.IR nvcsum s
of the fields
.BR machkey ,
.BR authid ,
and
.B authdom
must match their respective checksum or that field is zeroed.
If
.I flag
is
.B NVwrite
or at least one checksum fails and
.I flag
is
.BR NVwriteonerr ,
.I readnvram
will prompt for new values on
.B #c/cons
and then write them back to the storage area.
.PP
.IR ConvT2M ,
.IR convA2M ,
.IR convTR2M ,
and
.I convPR2M
convert tickets, authenticators, ticket requests, and password change request
structures into transmittable messages.
.IR ConvM2T ,
.IR convM2A ,
.IR convM2TR ,
and
.I convM2PR
are used to convert them back.
.I Key
is used for encrypting the message before transmission and decrypting
after reception.
.PP
The routine
.I _asgetresp
receives either a character array or an error string.
On error, it sets errstr and returns -1. If successful,
it returns the number of bytes received.
.PP
The routine
.I _asgetticket
sends a ticket request message and then uses
.I _asgetresp
to recieve an answer.
.SH SOURCE
.B /sys/src/libauthsrv
.SH SEE ALSO
.IR passwd (1),
.IR cons (3),
.IR dial (2),
.IR authsrv (6),
.SH DIAGNOSTICS
These routines set
.IR errstr .
Integer-valued functions return -1 on error.

99
man/man3/bin.3 Normal file
View File

@@ -0,0 +1,99 @@
.TH BIN 3
.SH NAME
binalloc, bingrow, binfree \- grouped memory allocation
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <bin.h>
.PP
.ta \w'\fLvoid* 'u
.PP
.B
typedef struct Bin Bin;
.PP
.B
void *binalloc(Bin **bp, ulong size, int clr);
.PP
.B
void *bingrow(Bin **bp, void *op, ulong osize,
.br
.B
ulong size, int clr);
.PP
.B
void binfree(Bin **bp);
.SH DESCRIPTION
These routines provide simple grouped memory allocation and deallocation.
Items allocated with
.I binalloc
are added to the
.I Bin
pointed to by
.IR bp .
All items in a bin may be freed with one call to
.IR binfree ;
there is no way to free a single item.
.PP
.I Binalloc
returns a pointer to a new block of at least
.I size
bytes.
The block is suitably aligned for storage of any type of object.
No two active pointers from
.I binalloc
will have the same value.
The call
.B binalloc(0)
returns a valid pointer rather than null.
If
.I clr
is non-zero, the allocated memory is set to 0;
otherwise, the contents are undefined.
.PP
.I Bingrow
is used to extend the size of a block of memory returned by
.IR binalloc .
.I Bp
must point to the same bin group used to allocate the original block,
and
.I osize
must be the last size used to allocate or grow the block.
A pointer to a block of at least
.I size
bytes is returned, with the same contents in the first
.I osize
locations.
If
.I clr
is non-zero, the remaining bytes are set to 0,
and are undefined otherwise.
If
.I op
is
.BR nil ,
it and
.I osize
are ignored, and the result is the same as calling
.IR binalloc .
.PP
.I Binalloc
and
.I bingrow
allocate large chunks of memory using
.IR malloc (2)
and return pieces of these chunks.
The chunks are
.IR free 'd
upon a call to
.IR binfree .
.SH SOURCE
.B /sys/src/libbin
.SH SEE ALSO
.IR malloc (2)
.SH DIAGNOSTICS
.I binalloc
and
.I bingrow
return 0 if there is no available memory.

117
man/man3/bio.3
View File

@@ -1,9 +1,12 @@
.TH BIO 3
.SH NAME
Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetd, Bungetc, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output
Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output
.SH SYNOPSIS
.ta \w'Biobuf* 'u
.B #include <fmt.h>
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <bio.h>
.PP
.B
@@ -13,64 +16,67 @@ Biobuf* Bopen(char *file, int mode)
int Binit(Biobuf *bp, int fd, int mode)
.PP
.B
int Bterm(Biobuf *bp)
int Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size)
.PP
.B
int Bprint(Biobuf *bp, char *format, ...)
int Bterm(Biobufhdr *bp)
.PP
.B
int Bvprint(Biobuf *bp, char *format, va_list arglist);
int Bprint(Biobufhdr *bp, char *format, ...)
.PP
.B
void* Brdline(Biobuf *bp, int delim)
int Bvprint(Biobufhdr *bp, char *format, va_list arglist);
.PP
.B
char* Brdstr(Biobuf *bp, int delim, int nulldelim)
void* Brdline(Biobufhdr *bp, int delim)
.PP
.B
int Blinelen(Biobuf *bp)
char* Brdstr(Biobufhdr *bp, int delim, int nulldelim)
.PP
.B
off_t Boffset(Biobuf *bp)
int Blinelen(Biobufhdr *bp)
.PP
.B
int Bfildes(Biobuf *bp)
vlong Boffset(Biobufhdr *bp)
.PP
.B
int Bgetc(Biobuf *bp)
int Bfildes(Biobufhdr *bp)
.PP
.B
int Bgetc(Biobufhdr *bp)
.PP
.B
long Bgetrune(Biobufhdr *bp)
.PP
.B
int Bgetd(Biobuf *bp, double *d)
int Bgetd(Biobufhdr *bp, double *d)
.PP
.B
int Bungetc(Biobuf *bp)
int Bungetc(Biobufhdr *bp)
.PP
.B
int Bungetrune(Biobufhdr *bp)
.PP
.B
off_t Bseek(Biobuf *bp, off_t n, int type)
vlong Bseek(Biobufhdr *bp, vlong n, int type)
.PP
.B
int Bputc(Biobuf *bp, int c)
int Bputc(Biobufhdr *bp, int c)
.PP
.B
int Bputrune(Biobufhdr *bp, long c)
.PP
.B
long Bread(Biobuf *bp, void *addr, long nbytes)
long Bread(Biobufhdr *bp, void *addr, long nbytes)
.PP
.B
long Bwrite(Biobuf *bp, void *addr, long nbytes)
long Bwrite(Biobufhdr *bp, void *addr, long nbytes)
.PP
.B
int Bflush(Biobuf *bp)
int Bflush(Biobufhdr *bp)
.PP
.B
int Bbuffered(Biobuf *bp)
int Bbuffered(Biobufhdr *bp)
.PP
.SH DESCRIPTION
These routines implement fast buffered I/O.
@@ -80,20 +86,40 @@ I/O on different file descriptors is independent.
opens
.I file
for mode
.B O_RDONLY
.B OREAD
or creates for mode
.BR O_WRONLY .
.BR OWRITE .
It calls
.IR malloc (3)
.IR malloc (2)
to allocate a buffer.
.PP
.I Binit
initializes a buffer
initializes a standard size buffer, type
.IR Biobuf ,
with the open file descriptor passed in
by the user.
.I Binits
initializes a non-standard size buffer, type
.IR Biobufhdr ,
with the open file descriptor,
buffer area, and buffer size passed in
by the user.
.I Biobuf
and
.I Biobufhdr
are related by the declaration:
.IP
.EX
typedef struct Biobuf Biobuf;
struct Biobuf
{
Biobufhdr;
uchar b[Bungetsize+Bsize];
};
.EE
.PP
Arguments
of types pointer to Biobuf and pointer to Biobuf
of types pointer to Biobuf and pointer to Biobufhdr
can be used interchangeably in the following routines.
.PP
.IR Bopen ,
@@ -133,7 +159,7 @@ of the most recent string returned by
.PP
.I Brdstr
returns a
.IR malloc (3)-allocated
.IR malloc (2)-allocated
buffer containing the next line of input delimited by
.IR delim ,
terminated by a NUL (0) byte.
@@ -152,14 +178,14 @@ the return value of
will be the length of the returned buffer, excluding the NUL.
.PP
.I Bgetc
returns the next byte from
returns the next character from
.IR bp ,
or a negative value
at end of file.
.I Bungetc
may be called immediately after
.I Bgetc
to allow the same byte to be reread.
to allow the same character to be reread.
.PP
.I Bgetrune
calls
@@ -183,8 +209,9 @@ may back up a maximum of five bytes.
.PP
.I Bgetd
uses
.I fmtcharstod
(undocumented)
.I charstod
(see
.IR atof (2))
and
.I Bgetc
to read the formatted
@@ -205,7 +232,7 @@ and a negative value is returned if a read error occurred.
.PP
.I Bseek
applies
.IR lseek (2)
.IR seek (2)
to
.IR bp .
It returns the new file offset.
@@ -279,25 +306,13 @@ returns the number of bytes in the buffer.
When reading, this is the number of bytes still available from the last
read on the file; when writing, it is the number of bytes ready to be
written.
.PP
This library uses
.IR fmt (3)
for diagnostic messages about internal errors,
as well as for the implementation of
.I Bprint
and
.IR Bvprint .
It uses
.IR utf (3)
for the implementation of
.I Bgetrune
and
.IR Bputrune .
.SH SOURCE
.B /sys/src/libbio
.SH SEE ALSO
.IR atexit (3).
.IR open (2),
.IR print (3),
.IR utf (7)
.IR print (2),
.IR exits (2),
.IR utf (6),
.SH DIAGNOSTICS
.I Bio
routines that return integers yield
@@ -307,11 +322,9 @@ if
is not the descriptor of an open file.
.I Bopen
returns zero if the file cannot be opened in the given mode.
.SH HISTORY
The
.IR bio (3)
library originally appeared in Plan 9.
This is a port of the Plan 9 bio library.
All routines set
.I errstr
on error.
.SH BUGS
.I Brdline
returns an error on strings longer than the buffer associated

52
man/man3/blowfish.3 Normal file
View File

@@ -0,0 +1,52 @@
.TH BLOWFISH 3
.SH NAME
setupBFstate, bfCBCencrypt, bfCBCdecrypt, bfECBencrypt, bfECBdecrypt - blowfish encryption
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mp.h>
.br
.B #include <libsec.h>
.PP
.B
void setupBFstate(BFstate *s, uchar key[], int keybytes,
.B
uchar *ivec)
.PP
.B
void bfCBCencrypt(uchar *data, int len, BFstate *s)
.PP
.B
void bfCBCdecrypt(uchar *data, int len, BFstate *s)
.PP
.B
void bfECBencrypt(uchar *data, int len, BFstate *s)
.PP
.B
void bfECBdecrypt(uchar *data, int len, BFstate *s)
.SH DESCRIPTION
.PP
Blowfish is Bruce Schneier's symmetric block cipher. It supports
variable length keys from 32 to 448 bits and has a block size of 64
bits. Both CBC and ECB modes are supported.
.PP
setupBFstate takes a BFstate structure, a key of at most 56 bytes, the
length of the key in bytes, and an initialization vector of 8 bytes
(set to all zeroes if argument is nil). The encryption and decryption
functions take a BFstate structure, a data buffer, and a length, which
must be a multiple of eight bytes as padding is currently unsupported.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR des (2),
.IR dsa (2),
.IR elgamal (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)

313
man/man3/cachechars.3 Normal file
View File

@@ -0,0 +1,313 @@
.TH CACHECHARS 3
.SH NAME
cachechars, agefont, loadchar, Subfont, Fontchar, Font \- font utilities
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <draw.h>
.br
.B #include <draw.h>
.PP
.ta \w'\fLCacheinfo 'u
.PP
.B
int cachechars(Font *f, char **s, Rune **r, ushort *c, int max,
.PP
.B
int *widp, char **sfname)
.PP
.B
int loadchar(Font *f, Rune r, Cacheinfo *c, int h,
.PP
.B
int noclr, char **sfname)
.PP
.B
void agefont(Font *f)
.SH DESCRIPTION
A
.I Font
may contain too many characters to hold in memory
simultaneously.
The graphics library and draw device (see
.IR draw (3))
cooperate to solve this problem by maintaining a cache of recently used
character images.
The details of this cooperation need not be known by most programs:
.I initdraw
and its associated
.I font
variable,
.IR openfont ,
.IR stringwidth ,
.IR string ,
and
.I freefont
are sufficient for most purposes.
The routines described below are used internally by the graphics library
to maintain the font cache.
.PP
A
.B Subfont
is a set of images for a contiguous range of characters, stored as a single
image
with the characters
placed side-by-side on a common baseline.
It is described by the following data structures.
.IP
.EX
.ta 6n +\w'Fontchar 'u +\w'bottom; 'u
typedef
struct Fontchar {
int x; /* left edge of bits */
uchar top; /* first non-zero scan-line */
uchar bottom; /* last non-zero scan-line */
char left; /* offset of baseline */
uchar width; /* width of baseline */
} Fontchar;
typedef
struct Subfont {
char *name;
short n; /* number of chars in subfont */
uchar height; /* height of image */
char ascent; /* top of image to baseline */
Fontchar *info; /* n+1 Fontchars */
Image *bits; /* of font */
} Subfont;
.EE
.PP
The image fills the rectangle
\fL(0, 0, \fIw\fP, height)\fR,
where
.I w
is the sum of the horizontal extents (of non-zero pixels)
for all characters.
The pixels to be displayed for character
.I c
are in the rectangle
\fL(\fIi\fP->x, \fIi\fP->top, (\fIi\fP+1)->x, \%\fIi\fP->bottom)\fR
where
.I i
is
.B
&subfont->info[\fIc\fP]\fR.
When a character is displayed at
.B Point
.B p
in an image,
the character rectangle is placed at
.BI (p.x+ i ->left,
.B p.y)
and the next character of the string is displayed at
.BI (p.x+ i ->width,
.BR p.y) .
The baseline of the characters is
.L ascent
rows down from the top of the subfont image.
The
.L info
array has
.B n+1
elements, one each for characters 0 to
.BR n-1
plus an additional entry so the size of the last character
can be calculated.
Thus the width,
.IR w ,
of the
.B Image
associated with a
.B Subfont
.B s
is
.BR s->info[s->n].x .
.PP
A
.B Font
consists of an overall height and ascent
and a collection of subfonts together with the ranges of runes (see
.IR utf (6))
they represent.
Fonts are described by the following structures.
.IP
.EX
.ta 6n +\w'Cacheinfo 'u +\w'height; 'u
typedef
struct Cachefont {
Rune min; /* value of 0th char in subfont */
Rune max; /* value+1 of last char in subfont */
int offset; /* posn in subfont of char at min */
char *name; /* stored in font */
char *subfontname; /* to access subfont */
} Cachefont;
typedef
struct Cacheinfo {
ushort x; /* left edge of bits */
uchar width; /* width of baseline */
schar left; /* offset of baseline */
Rune value; /* of char at this slot in cache */
ushort age;
} Cacheinfo;
typedef
struct Cachesubf {
ulong age; /* for replacement */
Cachefont *cf; /* font info that owns us */
Subfont *f; /* attached subfont */
} Cachesubf;
typedef
struct Font {
char *name;
Display *display;
short height; /* max ht of image;interline space*/
short ascent; /* top of image to baseline */
short width; /* widest so far; used in caching */
short nsub; /* number of subfonts */
ulong age; /* increasing counter; for LRU */
int ncache; /* size of cache */
int nsubf; /* size of subfont list */
Cacheinfo *cache;
Cachesubf *subf;
Cachefont **sub; /* as read from file */
Image *cacheimage;
} Font;
.EE
.PP
The
.LR height
and
.LR ascent
fields of Font are described in
.IR graphics (2).
.L Sub
contains
.L nsub
pointers to
.BR Cachefonts .
A
.B Cachefont
connects runes
.L min
through
.LR max ,
inclusive, to the subfont
with file name
.LR name ;
it corresponds to a line of the file describing the font.
.PP
The characters
are taken from the subfont starting at character number
.L offset
(usually zero) in the subfont, permitting selection of parts of subfonts.
Thus
the image for rune
.I r
is found in position
.IB r -min+offset
of the subfont.
.PP
For each font, the library, with support from the
graphics server,
maintains a cache of
subfonts and a cache of recently used
character images.
The
.B subf
and
.B cache
fields are used by the library to maintain these caches.
The
.L width
of a font is the maximum of the horizontal extents of the characters
in the cache.
.I String
draws a string by loading the cache and emitting a sequence of
cache indices to draw.
.I Cachechars
guarantees the images for the characters pointed to by
.I *s
or
.I *r
(one of these must be nil in each call)
are in the cache of
.IR f .
It calls
.I loadchar
to put missing characters into the cache.
.I Cachechars
translates the character string into a set of cache indices
which it loads into the array
.IR c ,
up to a maximum of
.I n
indices or the length of the string.
.I Cachechars
returns in
.I c
the number of cache indices emitted,
updates
.I *s
to point to the next character to be processed, and sets
.I *widp
to the total width of the characters processed.
.I Cachechars
may return before the end of the string if it cannot
proceed without destroying active data in the caches.
If it needs to load a new subfont, it will fill
.B *sfname
with the name of the subfont it needs and return \-1.
It can return zero if it is unable to make progress because
it cannot resize the caches.
.PP
.I Loadchar
loads a character image into the character cache.
Then it tells the graphics server to copy the character
into position
.I h
in the character cache.
If the current font
.L width
is smaller than the horizontal extent of the character being loaded,
.I loadfont
clears the cache and resets it to
accept characters with the bigger width, unless
.I noclr
is set, in which case it just returns \-1.
If the character does not exist in the font at all,
.I loadfont
returns 0; if it is unable to load the character
without destroying cached information, it returns \-1,
updating
.B *sfname
as described above.
It returns 1 to indicate success.
.PP
The
.L age
fields record when
subfonts and characters have been used.
The font
.L age
is increased every time the font is used
.RI ( agefont
does this).
A character or subfont
.L age
is set to the font age at each use.
Thus, characters or subfonts with small ages are the best candidates
for replacement when the cache is full.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2),
.IR allocimage (2),
.IR draw (2),
.IR subfont (2),
.IR image (6),
.IR font (6)
.SH DIAGNOSTICS
All of the functions use the graphics error function (see
.IR graphics (2)).

34
man/man3/cleanname.3 Normal file
View File

@@ -0,0 +1,34 @@
.TH CLEANNAME 3
.SH NAME
cleanname \- clean a path name
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.sp
.B
char* cleanname(char *filename)
.SH DESCRIPTION
.I Cleanname
takes a
.I filename
and by lexical processing only returns the shortest string that names the same (possibly
hypothetical) file.
It eliminates multiple and trailing slashes, and it lexically interprets
.B .
and
.B ..
directory components in the name.
The string is overwritten in place.
.PP
The shortest string
.I cleanname
can return is two bytes: the null-terminated string
\f(CW"."\f1.
Therefore
.I filename
must contain room for at least two bytes.
.SH SOURCE
.B /sys/src/libc/port/cleanname.c
.SH SEE ALSO
.IR cleanname (1)

56
man/man3/color.3 Normal file
View File

@@ -0,0 +1,56 @@
.TH COLOR 3
.SH NAME
cmap2rgb, cmap2rgba, rgb2cmap \- colors and color maps
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <draw.h>
.PP
.B
int rgb2cmap(int red, int green, int blue)
.PP
.B
int cmap2rgb(int col)
.PP
.B
int cmap2rgba(int col)
.SH DESCRIPTION
These routines convert between `true color' red/green/blue triples and the Plan 9 color map.
See
.IR color (6)
for a description of RGBV, the standard color map.
.PP
.I Rgb2cmap
takes a trio of color values, scaled from 0 (no intensity) to 255 (full intensity),
and returns the index of the color in RGBV closest to that represented
by those values.
.PP
.I Cmap2rgb
decomposes the color of RGBV index
.I col
and returns a 24-bit integer with the low 8 bits representing the blue value,
the next 8 representing green, and the next 8 representing red.
.I Cmap2rgba
decomposes the color of RGBV index
.I col
and returns a 32-bit integer with the low 8 bits representing an alpha value,
defined to be 255,
and the next 8 representing blue, then green, then red, as for
.I cmap2rgba
shifted up 8 bits.
This 32-bit representation is the format used by
.IR draw (2)
and
.IR memdraw (2)
library routines that
take colors as arguments.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2),
.IR allocimage (2),
.IR draw (2),
.IR image (6),
.IR color (6)

105
man/man3/complete.3 Normal file
View File

@@ -0,0 +1,105 @@
.TH COMPLETE 3
.SH NAME
complete \- file name completion
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <complete.h>
.PP
.ft L
.nf
.ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u
typedef struct Completion Completion;
struct Completion{
uchar advance; /* whether forward progress has been made */
uchar complete; /* whether the completion now represents a file or directory */
char *string; /* the string to advance, suffixed " " or "/" for file or directory */
int nmatch; /* number of files that matched */
int nfile; /* number of files returned */
char **filename; /* their names */
};
.fi
.PP
.B
.ta \w'\fLchar* 'u
.PP
.B
Completion* complete(char *dir, char *s);
.PP
.B
void freecompletion(Completion *c);
.SH DESCRIPTION
The
.I complete
function implements file name completion.
Given a directory
.I dir
and a string
.IR s ,
it returns an analysis of the file names in that directory that begin with the string
.IR s .
The fields
.B nmatch
and
.B nfile
will be set to the number of files that match the prefix and
.B filename
will be filled in with their names.
If the file named is a directory, a slash character will be appended to it.
.PP
If no files match the string,
.B nmatch
will be zero, but
.I complete
will return the full set of files in the directory, with
.I nfile
set to their number.
.PP
The flag
.B advance
reports whether the string
.I s
can be extended without changing the set of files that match. If true,
.B string
will be set to the extension; that is, the value of
.B string
may be appended to
.I s
by the caller to extend the embryonic file name unambiguously.
.PP
The flag
.B complete
reports whether the extended file name uniquely identifies a file.
If true,
.B string
will be suffixed with a blank, or a slash and a blank,
depending on whether the resulting file name identifies a plain file or a directory.
.PP
The
.I freecompletion
function frees a
.B Completion
structure and its contents.
.PP
In
.IR rio (1)
and
.IR acme (1),
file name completion is triggered by a control-F character or an Insert character.
.SH SOURCE
.B /sys/src/libcomplete
.SH SEE ALSO
.IR rio (1),
.IR acme (1)
.SH DIAGNOSTICS
The
.I complete
function returns a null pointer and sets
.I errstr
if the directory is unreadable or there is some other error.
.SH BUGS
The behavior of file name completion should be controlled by the plumber.

34
man/man3/cputime.3 Normal file
View File

@@ -0,0 +1,34 @@
.TH CPUTIME 3
.SH NAME
cputime, times \- cpu time in this process and children
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.ta \w'\fLdouble 'u
.B
int times(long t[4])
.PP
.B
double cputime(void)
.SH DESCRIPTION
If
.I t
is non-null,
.I times
fills it in
with the number of milliseconds spent in user code, system calls,
child processes in user code, and child processes in system calls.
.I Cputime
returns the sum of those same times, converted to seconds.
.I Times
returns the elapsed real time, in milliseconds, that the process has been running.
.PP
These functions read
.BR /dev/cputime ,
opening that file when they are first called.
.SH SOURCE
.B /sys/src/libc/9sys
.SH SEE ALSO
.IR cons (3)

160
man/man3/ctype.3 Normal file
View File

@@ -0,0 +1,160 @@
.TH CTYPE 3
.SH NAME
isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, isgraph, iscntrl, isascii, toascii, _toupper, _tolower, toupper, tolower \- ASCII character classification
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <ctype.h>
.PP
.if t .2C
.B isalpha(c)
.PP
.B isupper(c)
.PP
.B islower(c)
.PP
.B isdigit(c)
.PP
.B isxdigit(c)
.PP
.B isalnum(c)
.PP
.B isspace(c)
.PP
.B ispunct(c)
.PP
.B isprint(c)
.PP
.B isgraph(c)
.PP
.B iscntrl(c)
.PP
.B isascii(c)
.PP
.B _toupper(c)
.PP
.B _tolower(c)
.PP
.B toupper(c)
.PP
.B tolower(c)
.PP
.B toascii(c)
.if t .1C
.SH DESCRIPTION
These macros classify
.SM ASCII\c
-coded integer values
by table lookup.
Each is a predicate returning nonzero for true,
zero for false.
.I Isascii
is defined on all integer values; the rest
are defined only where
.I isascii
is true and on the single non-\c
.SM ASCII
value
.BR EOF ;
see
.IR fopen (2).
.TP "\w'isalnum 'u"
.I isalpha
.I c
is a letter, a\-z or A\-Z
.TP
.I isupper
.I c
is an upper case letter, A\-Z
.TP
.I islower
.I c
is a lower case letter, a\-z
.TP
.I isdigit
.I c
is a digit, 0\-9
.TP
.I isxdigit
.I c
is a hexadecimal digit, 0\-9 or a\-f or A\-F
.TP
.I isalnum
.I c
is an alphanumeric character, a\-z or A\-Z or 0\-9
.TP
.I isspace
.I c
is a space, horizontal tab, newline, vertical tab, formfeed, or carriage return
(0x20, 0x9, 0xA, 0xB, 0xC, 0xD)
.TP
.I ispunct
.I c
is a punctuation character
(one of
.L
!"#$%&'()*+,-./:;<=>?@[\e]^_`{|}~\fR)
.TP
.I isprint
.I c
is a printing character, 0x20 (space)
through 0x7E (tilde)
.TP
.I isgraph
.I c
is a visible printing character, 0x21 (exclamation) through 0x7E
(tilde)
.TP
.I iscntrl
.I c
is a delete character, 0x7F,
or ordinary control character, 0x0 through 0x1F
.TP
.I isascii
.I c
is an
.SM ASCII
character, 0x0 through 0x7F
.PP
.I Toascii
is not a classification macro;
it converts its argument to
.SM ASCII
range by
.IR and ing
with 0x7F.
.PP
If
.I c
is an upper case letter,
.I tolower
returns the lower case version of the character;
otherwise it returns the original character.
.I Toupper
is similar, returning the upper case version of a character
or the original character.
.I Tolower
and
.I toupper
are functions;
.I _tolower
and
.I _toupper
are corresponding macros which should only be used when it
is known that the argument is upper case or lower case, respectively.
.SH SOURCE
.TF /sys/src/libc/port/ctype.c
.TP
.B /sys/include/ctype.h
for the macros.
.TP
.B /sys/src/libc/port/ctype.c
for the tables.
.SH "SEE ALSO
.IR isalpharune (2)
.SH BUGS
These macros are
.SM ASCII \c
-centric.

386
man/man3/debugger.3 Normal file
View File

@@ -0,0 +1,386 @@
.TH DEBUGGER 3
.SH NAME
cisctrace, risctrace, ciscframe, riscframe, localaddr, symoff,
fpformat, beieee80ftos, beieeesftos, beieeedftos, leieee80ftos,
leieeesftos, leieeedftos, ieeesftos, ieeedftos \- machine-independent debugger functions
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <bio.h>
.br
.B #include <mach.h>
.PP
.ta \w'\fLmachines 'u
.nf
.B
int cisctrace(Map *map, ulong pc, ulong sp, ulong link,
.B
Tracer trace)
.PP
.nf
.B
int risctrace(Map *map, ulong pc, ulong sp, ulong link,
.B
Tracer trace)
.PP
.nf
.B
ulong ciscframe(Map *map, ulong addr, ulong pc, ulong sp,
.B
ulong link)
.PP
.nf
.B
ulong riscframe(Map *map, ulong addr, ulong pc, ulong sp,
.B
ulong link)
.PP
.nf
.B
int localaddr(Map *map, char *fn, char *var, long *ret,
.B
Rgetter rget)
.PP
.B
int symoff(char *buf, int n, long addr, int type)
.PP
.B
int fpformat(Map *map, Reglist *rp, char *buf, int n, int code)
.PP
.B
int beieee80ftos(char *buf, int n, void *fp)
.PP
.B
int beieeesftos(char *buf, int n, void *fp)
.PP
.B
int beieeedftos(char *buf, int n, void *fp)
.PP
.B
int leieee80ftos(char *buf, int n, void *fp)
.PP
.B
int leieeesftos(char *buf, int n, void *fp)
.PP
.B
int leieeedftos(char *buf, int n, void *fp)
.PP
.B
int ieeesftos(char *buf, int n, ulong f)
.PP
.B
int ieeedftos(char *buf, int n, ulong high, ulong low)
.PP
.B
extern Machdata *machdata;
.SH DESCRIPTION
These functions provide machine-independent implementations
of common debugger functions.
Many of the functions assume that global variables
.I mach
and
.I machdata
point to the
.I Mach
and
.I Machdata
data structures describing the target architecture.
The former contains machine parameters and a description of
the register set; it is usually
set by invoking
.I crackhdr
(see
.IR mach (2))
to interpret the header of an executable.
The
.I Machdata
structure
is primarily a jump table specifying
functions appropriate for processing an
executable image for a given architecture.
Each application is responsible for setting
.I machdata
to the address of the
.I Machdata
structure for the target architecture.
Many of the functions described here are not
called directly; instead, they are invoked
indirectly through the
.I Machdata
jump table.
.PP
These functions must retrieve data and register contents
from an executing image. The
.I Map
(see
.IR mach (2))
data structure
supports the consistent retrieval of data, but
no uniform access mechanism exists for registers.
The application passes the address of a register
retrieval function as an argument to those functions
requiring register values.
This function, called an
.IR Rgetter ,
is of the form
.PP
.RS
.B "ulong rget(Map *map, char *name);
.RE
.PP
It returns the contents of a register when given
the address of a
.I Map
associated with an executing image and the name of the register.
.PP
.I Cisctrace
and
.I risctrace
unwind the stack for up to 40 levels or until the frame for
.I main
is found. They return the
count of the number of levels unwound. These functions
process stacks conforming to the generic compiler model for
.SM RISC
and
.SM CISC
architectures, respectively.
.I Map
is the address of a
.I Map
data structure associated with the image
of an executing process.
.IR Sp ,
.I pc
and
.I link
are starting values for the stack pointer, program counter, and
link register from which the unwinding is to take place. Normally, they are
the current contents of the appropriate
registers but they can be any values defining a legitimate
process context, for example, an alternate stack in a
multi-threaded process.
.I Trace
is the address of an application-supplied function to be called
on each iteration as the frame unwinds. The prototype of this
function is:
.PP
.RS
.B "void tracer(Map *map, ulong pc, ulong fp, Symbol *s);
.RE
.PP
where
.I Map
is the
.I Map
pointer passed to
.I cisctrace
or
.I risctrace
and
.I pc
and
.I fp
are the program counter and frame pointer.
.I S
is the address of a
.I Symbol
structure, as defined in
.IR symbol (2),
containing the symbol table information for the
function owning the frame (i.e., the function that
caused the frame to be instantiated).
.PP
.I Ciscframe
and
.I riscframe
calculate the frame pointer associated with
a function. They are suitable for
programs conforming to the
.SM CISC
and
.SM RISC
stack models.
.I Map
is the address of a
.I Map
associated with the memory image of an executing
process.
.I Addr
is the entry point of the desired function.
.IR Pc ,
.I sp
and
.I link
are the program counter, stack pointer and link register of
an execution context. As with the stack trace
functions, these can be the current values of the
registers or any legitimate execution context.
The value of the frame pointer is returned. A return
value of zero indicates an error.
.PP
.I Localaddr
fills the location
pointed to by
.I ret
with the address of a local variable.
.I Map
is the address of a
.I Map
associated with an executing memory image.
.I Fn
and
.I var
are pointers to the names of the function and variable of interest.
.I Rget
is the address of a register retrieval function.
If both
.I fn
and
.I var
are non-zero, the frame for function
.I fn
is calculated and the address of the automatic or
argument named
.I var
in that frame is returned.
If
.I var
is zero, the address of the
frame for function
.I fn
is returned.
In all cases, the frame for the function named
.I fn
must be instantiated somewhere on the current stack.
If there are multiple frames for the function (that is, if
it is recursive), the most recent frame is used.
The search starts from the context defined by the
current value of the program counter and stack pointer.
If a valid address is found,
.I localaddr
returns 1. A negative return indicates an error in
resolving the address.
.PP
.I Symoff
converts a virtual address to a symbolic reference. The
string containing that reference is of
the form `name+offset', where `name' is the name of the
nearest symbol with an address less than
or equal to the target address and `offset' is the hexadecimal offset
beyond that symbol. If `offset' is zero, only the name of
the symbol is printed. If no symbol is found within 4,096
bytes of the address, the address is formatted as a hexadecimal
address.
.I Buf
is the address of a buffer of
.I n
characters to receive the formatted string.
.I Addr
is the address to be converted.
.I Type
is the type code of the search space:
.BR CTEXT ,
.BR CDATA ,
or
.BR CANY .
.I Symoff
returns the length of the formatted string contained in
.IR buf .
.PP
.I Fpformat
converts the contents of a floating point register to a
string.
.I Map
is the address of a
.I Map
associated with an executing process.
.I Rp
is the address of a
.I Reglist
data structure describing the desired register.
.I Buf
is the address of a buffer of
.I n
characters to hold the resulting string.
.I Code
must be either
.B F
or
.BR f,
selecting double
or single precision, respectively. If
.I code
is
.BR F ,
the contents of the specified register and
the following register
are interpreted as a double precision floating point
number; this
is only meaningful for architectures that implement
double precision floats by combining adjacent
single precision registers.
For
.I code
.BR f ,
the specified register is formatted
as a single precision float.
.I Fpformat
returns 1 if the number is successfully converted or \-1
in the case of an error.
.PP
.IR Beieee80ftos ,
.I beieeesftos
and
.I beieeedftos
convert big-endian 80-bit extended, 32-bit single precision,
and 64-bit double precision floating point values to
a string.
.IR Leieee80ftos ,
.IR leieeesftos ,
and
.I leieeedftos
are the little-endian counterparts.
.I Buf
is the address of a buffer of
.I n
characters to receive the formatted string.
.I Fp
is the address of the floating point value to be
converted. These functions return the length of
the resulting string.
.PP
.I Ieeesftos
converts the 32-bit single precision floating point value
.IR f ,
to a string in
.IR buf ,
a buffer of
.I n
bytes. It returns the length of the resulting string.
.PP
.I Ieeedftos
converts a 64-bit double precision floating point value
to a character string.
.I Buf
is the address of a buffer of
.I n
characters to hold the resulting string.
.I High
and
.I low
contain the most and least significant 32 bits of
the floating point value, respectively.
.I Ieeedftos
returns the number of characters in the resulting string.
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR mach (2),
.IR symbol (2),
.IR errstr (2)
.SH DIAGNOSTICS
Set
.IR errstr .

144
man/man3/des.3 Normal file
View File

@@ -0,0 +1,144 @@
.TH DES 3
.SH NAME
setupDESstate, des_key_setup, block_cipher, desCBCencrypt, desCBCdecrypt, desECBencrypt, desECBdecrypt, des3CBCencrypt, des3CBCdecrypt, des3ECBencrypt, des3ECBdecrypt, key_setup, des56to64, des64to56, setupDES3state, triple_block_cipher, - single and triple digital encryption standard
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mp.h>
.br
.B #include <libsec.h>
.PP
.B
void des_key_setup(uchar key[8], ulong schedule[32])
.PP
.B
void block_cipher(ulong *schedule, uchar *data,
.B
int decrypting)
.PP
.B
void setupDESstate(DESstate *s, uchar key[8], uchar *ivec)
.PP
.B
void desCBCencrypt(uchar*, int, DESstate*)
.PP
.B
void desCBCdecrypt(uchar*, int, DESstate*)
.PP
.B
void desECBencrypt(uchar*, int, DESstate*)
.PP
.B
void desECBdecrypt(uchar*, int, DESstate*)
.PP
.B
void triple_block_cipher(ulong keys[3][32], uchar*, int)
.PP
.B
void setupDES3state(DES3state *s, uchar key[3][8],
.B
uchar *ivec)
.PP
.B
void des3CBCencrypt(uchar*, int, DES3state*)
.PP
.B
void des3CBCdecrypt(uchar*, int, DES3state*)
.PP
.B
void des3ECBencrypt(uchar*, int, DES3state*)
.PP
.B
void des3ECBdecrypt(uchar*, int, DES3state*)
.PP
.B
void key_setup(uchar[7], ulong[32])
.PP
.B
void des56to64(uchar *k56, uchar *k64)
.PP
.B
void des64to56(uchar *k64, uchar *k56)
.SH DESCRIPTION
.PP
The Digital Encryption Standard (DES)
is a shared key or symmetric encryption using either
a 56 bit key for single DES or three 56 bit keys for triple des.
The keys are encoded into 64 bits where every eight bit
is parity.
.PP
The basic DES function,
.IR block_cipher ,
works on a block of 8 bytes, converting them in place.
It takes a key schedule, a pointer to the block, and
a flag indicating encrypting (0) or decrypting (1).
The key schedule is created from the key using
.IR des_key_setup .
.PP
Since it is a bit awkward,
.I block_cipher
is rarely called directly. Instead, one normally uses
routines that encrypt larger buffers of data and
which may chain the encryption state from one buffer
to the next.
These routines keep track of the state of the
encryption using a
.B DESstate
structure that contains the key schedule and any chained
state.
.I SetupDESstate
sets up the
.B DESstate
structure using the key and an 8 byte initialization vector.
.PP
Electronic code book, using
.I desECBencrypt
and
.IR desECBdecrypt ,
is the less secure mode. The encryption of each 8 bytes
does not depend on the encryption of any other.
Hence the encryption is a substitution
cipher using 64 bit characters.
.PP
Cipher block chaining mode, using
.I desCBCencrypt
and
.IR desCBCdecrypt ,
is more secure. Every block encrypted depends on the initialization
vector and all blocks encrypted before it.
.PP
For both CBC and ECB modes, a stream of data can be encrypted as
multiple buffers. However, all buffers except the last must
be a multiple of 8 bytes to ensure successful decryption of
the stream.
.PP
There are equivalent triple DES functions for each of the
DES functions.
.PP
In the past Plan 9 used a 56 bit or 7 byte
format for DES keys. To be compatible with the rest
of the world, we've abandoned this format.
There are two functions:
.I des56to64
and
.I des64to56
to convert back and forth between the two formats.
Also a key schedule can be set up from the 7 byte format
using
.IR key_setup .
.PP
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR blowfish (2),
.IR dsa (2),
.IR elgamal (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)

331
man/man3/dial.3 Normal file
View File

@@ -0,0 +1,331 @@
.TH DIAL 3
.SH NAME
dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- make and break network connections
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int dial(char *addr, char *local, char *dir, int *cfdp)
.PP
.B
int hangup(int ctl)
.PP
.B
int announce(char *addr, char *dir)
.PP
.B
int listen(char *dir, char *newdir)
.PP
.B
int accept(int ctl, char *dir)
.PP
.B
int reject(int ctl, char *dir, char *cause)
.PP
.B
char* netmkaddr(char *addr, char *defnet, char *defservice)
.PP
.B
void setnetmtpt(char *to, int tolen, char *from)
.PP
.B
NetConnInfo* getnetconninfo(char *conndir, int fd)
.PP
.B
void freenetconninfo(NetConnINfo*)
.SH DESCRIPTION
For these routines,
.I addr
is a network address of the form
.IB network ! netaddr ! service\f1,
.IB network ! netaddr\f1,
or simply
.IR netaddr .
.I Network
is any directory listed in
.B /net
or the special token,
.BR net .
.B Net
is a free variable that stands for any network in common
between the source and the host
.IR netaddr .
.I Netaddr
can be a host name, a domain name, a network address,
or a meta-name of the form
.BI $ attribute\f1,
which
is replaced by
.I value
from the value-attribute pair
.IB attribute = value
most closely associated with the source host in the
network data base (see
.IR ndb (6)).
.PP
If a connection attempt is successful and
.I dir
is non-zero,
the path name of a
.I line directory
that has files for accessing the connection
is copied into
.IR dir .
The path name is guaranteed to be less than 40
bytes long.
One line directory exists for each possible connection.
The
.B data
file in the line directory should be used to communicate with the destination.
The
.B ctl
file in the line directory can be used to send commands to the line.
See
.IR ip (3)
for messages that can be written to the
.B ctl
file.
The last close of the
.B data
or
.B ctl
file will close the connection.
.PP
.I Dial
makes a call to destination
.I addr
on a multiplexed network.
If the network in
.I addr
is
.BR net ,
.I dial
will try in succession all
networks in common between source and destination
until a call succeeds.
It returns a file descriptor open for reading and writing the
.B data
file in the line directory.
The
.B addr
file in the line directory contains the address called.
If the network allows the local address to be set,
as is the case with UDP and TCP port numbers, and
.IR local
is non-zero, the local address will be set to
.IR local .
If
.I cfdp
is non-zero,
.BI * cfdp
is set to a file descriptor open for reading and
writing the control file.
.PP
.I Hangup
is a means of forcing a connection to hang up without
closing the
.B ctl
and
.B data
files.
.P
.I Announce
and
.I listen
are the complements of
.IR dial .
.I Announce
establishes a network
name to which calls can be made.
Like
.IR dial ,
.I announce
returns an open
.B ctl
file.
The
.I netaddr
used in announce may be a local address or an asterisk,
to indicate all local addresses, e.g.
.BR tcp!*!echo .
The
.I listen
routine takes as its first argument the
.I dir
of a previous
.IR announce .
When a call is received,
.I listen
returns an open
.B ctl
file for the line the call was received on.
It sets
.I newdir
to the path name of the new line directory.
.I Accept
accepts a call received by
.IR listen ,
while
.I reject
refuses the call because of
.IR cause .
.I Accept
returns a file descriptor for the data file opened
.BR ORDWR .
.PP
.I Netmkaddr
makes an address suitable for dialing or announcing.
It takes an address along with a default network and service to use
if they are not specified in the address.
It returns a pointer to static data holding the actual address to use.
.PP
.I Getnetconninfo
returns a structure containing information about a
network connection. The structure is:
.EX
typedef struct NetConnInfo NetConnInfo;
struct NetConnInfo
{
char *dir; /* connection directory */
char *root; /* network root */
char *spec; /* binding spec */
char *lsys; /* local system */
char *lserv; /* local service */
char *rsys; /* remote system */
char *rserv; /* remote service */
};
.EE
.PP
The information is obtained from the connection directory,
.IR conndir .
If
.I conndir
is nil, the directory is obtained by performing
.IR fd2path (2)
on
.IR fd .
.I Getnetconninfo
returns either a completely specified structure, or
nil if either the structure can't be allocated or the
network directory can't be determined.
The structure
is freed using
.IR freenetconninfo .
.PP
.I Setnetmtpt
copies the name of the network mount point into
the buffer
.IR to ,
whose length is
.IR tolen .
It exists to merge two pre-existing conventions for specifying
the mount point.
Commands that take a network mount point as a parameter
(such as
.BR dns ,
.BR cs
(see
.IR ndb (8)),
and
.IR ipconfig (8))
should now call
.IR setnetmtpt .
If
.I from
is
.BR nil ,
the mount point is set to the default,
.BR /net .
If
.I from
points to a string starting with a slash,
the mount point is that path.
Otherwise, the mount point is the string pointed to by
.I from
appended to the string
.BR /net .
The last form is obsolete and is should be avoided.
It exists only to aid in conversion.
.SH EXAMPLES
Make a call and return an open file descriptor to
use for communications:
.IP
.EX
int callkremvax(void)
{
return dial("kremvax", 0, 0, 0);
}
.EE
.PP
Call the local authentication server:
.IP
.EX
int dialauth(char *service)
{
return dial(netmkaddr("$auth", 0, service), 0, 0, 0);
}
.EE
.PP
Announce as
.B kremvax
on TCP/IP and
loop forever receiving calls and echoing back
to the caller anything sent:
.IP
.EX
int
bekremvax(void)
{
int dfd, acfd, lcfd;
char adir[40], ldir[40];
int n;
char buf[256];
acfd = announce("tcp!*!7", adir);
if(acfd < 0)
return -1;
for(;;){
/* listen for a call */
lcfd = listen(adir, ldir);
if(lcfd < 0)
return -1;
/* fork a process to echo */
switch(fork()){
case -1:
perror("forking");
close(lcfd);
break;
case 0:
/* accept the call and open the data file */
dfd = accept(lcfd, ldir);
if(dfd < 0)
return -1;
/* echo until EOF */
while((n = read(dfd, buf, sizeof(buf))) > 0)
write(dfd, buf, n);
exits(0);
default:
close(lcfd);
break;
}
}
}
.EE
.SH SOURCE
.BR /sys/src/libc/9sys ,
.B /sys/src/libc/port
.SH "SEE ALSO"
.IR auth (2),
.IR ip (3),
.IR ndb (8)
.SH DIAGNOSTICS
.IR Dial ,
.IR announce ,
and
.I listen
return \-1 if they fail.
.I Hangup
returns nonzero if it fails.

103
man/man3/dirread.3 Normal file
View File

@@ -0,0 +1,103 @@
.TH DIRREAD 3
.SH NAME
dirread, dirreadall \- read directory
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
long dirread(int fd, Dir **buf)
.PP
.B
long dirreadall(int fd, Dir **buf)
.PP
.B
#define STATMAX 65535U
.PP
.B
#define DIRMAX (sizeof(Dir)+STATMAX)
.SH DESCRIPTION
The data returned by a
.IR read (2)
on a directory is a set of complete directory entries
in a machine-independent format, exactly equivalent to
the result of a
.IR stat (2)
on each file or subdirectory in the directory.
.I Dirread
decodes the directory entries into a machine-dependent form.
It reads from
.IR fd
and unpacks the data into an array of
.B Dir
structures
whose address is returned in
.B *buf
(see
.IR stat (2)
for the layout of a
.BR Dir ).
The array is allocated with
.IR malloc (2)
each time
.I dirread
is called.
.PP
.I Dirreadall
is like
.IR dirread ,
but reads in the entire directory; by contrast,
.I dirread
steps through a directory one
.IR read (2)
at a time.
.PP
Directory entries have variable length.
A successful
.I read
of a directory always returns an integral number of complete directory entries;
.I dirread
always returns complete
.B Dir
structures.
See
.IR read (5)
for more information.
.PP
The constant
.B STATMAX
is the maximum size that a directory entry can occupy.
The constant
.B DIRMAX
is an upper limit on the size necessary to hold a
.B Dir
structure and all the associated data.
.PP
.I Dirread
and
.I dirreadall
return the number of
.B Dir
structures filled in
.BR buf .
The file offset is advanced by the number of bytes actually read.
.SH SOURCE
.B /sys/src/libc/9sys/dirread.c
.SH SEE ALSO
.IR intro (2),
.IR open (2),
.IR read (2)
.SH DIAGNOSTICS
.I Dirread
and
.I Dirreadall
return zero for end of file and a negative value for error.
In either case,
.B *buf
is set to
.B nil
so the pointer can always be freed with impunity.
.PP
These functions set
.IR errstr .

821
man/man3/draw.3 Normal file
View File

@@ -0,0 +1,821 @@
.TH DRAW 3
.SH NAME
Image, draw, gendraw, drawreplxy, drawrepl,
replclipr, line, poly, fillpoly, bezier, bezspline, fillbezier, fillbezspline, ellipse,
fillellipse, arc, fillarc, icossin, icossin2, border, string, stringn,
runestring, runestringn, stringbg, stringnbg, runestringbg,
runestringnbg, _string, ARROW, drawsetdebug \- graphics functions
.de PB
.PP
.ft L
.nf
..
.SH SYNOPSIS
.de PB
.PP
.ft L
.nf
..
.PB
#include <u.h>
#include <libc.h>
#include <draw.h>
.PB
typedef
struct Image
{
Display *display; /* display holding data */
int id; /* id of system-held Image */
Rectangle r; /* rectangle in data area, local coords */
Rectangle clipr; /* clipping region */
ulong chan; /* pixel channel format descriptor */
int depth; /* number of bits per pixel */
int repl; /* flag: data replicates to tile clipr */
Screen *screen; /* 0 if not a window */
Image *next; /* next in list of windows */
} Image;
.PB
typedef enum
{
/* Porter-Duff compositing operators */
Clear = 0,
.sp 0.1
SinD = 8,
DinS = 4,
SoutD = 2,
DoutS = 1,
.sp 0.1
S = SinD|SoutD,
SoverD = SinD|SoutD|DoutS,
SatopD = SinD|DoutS,
SxorD = SoutD|DoutS,
.sp 0.1
D = DinS|DoutS,
DoverS = DinS|DoutS|SoutD,
DatopS = DinS|SoutD,
DxorS = DoutS|SoutD, /* == SxorD */
.sp 0.1
Ncomp = 12,
} Drawop;
.PB
.PD 0
.ta +\w'\fL 'u +\w'\fL 'u +6n +4n
void draw(Image *dst, Rectangle r, Image *src,
Image *mask, Point p)
.PB
void drawop(Image *dst, Rectangle r, Image *src,
Image *mask, Point p, Drawop op)
.PB
void gendraw(Image *dst, Rectangle r, Image *src, Point sp,
Image *mask, Point mp)
.PB
void gendrawop(Image *dst, Rectangle r, Image *src, Point sp,
Image *mask, Point mp, Drawop op)
.PB
int drawreplxy(int min, int max, int x)
.PB
Point drawrepl(Rectangle r, Point p)
.PB
void replclipr(Image *i, int repl, Rectangle clipr)
.PB
void line(Image *dst, Point p0, Point p1, int end0, int end1,
int radius, Image *src, Point sp)
.PB
void lineop(Image *dst, Point p0, Point p1, int end0, int end1,
int radius, Image *src, Point sp, Drawop op)
.PB
void poly(Image *dst, Point *p, int np, int end0, int end1,
int radius, Image *src, Point sp)
.PB
void polyop(Image *dst, Point *p, int np, int end0, int end1,
int radius, Image *src, Point sp, Drawop op)
.PB
void fillpoly(Image *dst, Point *p, int np, int wind,
Image *src, Point sp)
.PB
void fillpolyop(Image *dst, Point *p, int np, int wind,
Image *src, Point sp, Drawop op)
.PB
int bezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
int end0, int end1, int radius, Image *src, Point sp)
.PB
int bezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
int end0, int end1, int radius, Image *src, Point sp,
Drawop op)
.PB
int bezspline(Image *dst, Point *pt, int npt, int end0, int end1,
int radius, Image *src, Point sp)
.PB
int bezsplineop(Image *dst, Point *pt, int npt, int end0, int end1,
int radius, Image *src, Point sp, Drawop op)
.PB
int bezsplinepts(Point *pt, int npt, Point **pp)
.PB
int fillbezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
int w, Image *src, Point sp)
.PB
int fillbezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
int w, Image *src, Point sp, Drawop op)
.PB
int fillbezspline(Image *dst, Point *pt, int npt, int w,
Image *src, Point sp)
.PB
int fillbezsplineop(Image *dst, Point *pt, int npt, int w,
Image *src, Point sp, Drawop op)
.PB
void ellipse(Image *dst, Point c, int a, int b, int thick,
Image *src, Point sp)
.PB
void ellipseop(Image *dst, Point c, int a, int b, int thick,
Image *src, Point sp, Drawop op)
.PB
void fillellipse(Image *dst, Point c, int a, int b,
Image *src, Point sp)
.PB
void fillellipseop(Image *dst, Point c, int a, int b,
Image *src, Point sp, Drawop op)
.PB
void arc(Image *dst, Point c, int a, int b, int thick,
Image *src, Point sp, int alpha, int phi)
.PB
void arcop(Image *dst, Point c, int a, int b, int thick,
Image *src, Point sp, int alpha, int phi, Drawop op)
.PB
void fillarc(Image *dst, Point c, int a, int b, Image *src,
Point sp, int alpha, int phi)
.PB
void fillarcop(Image *dst, Point c, int a, int b, Image *src,
Point sp, int alpha, int phi, Drawop op)
.PB
int icossin(int deg, int *cosp, int *sinp)
.PB
int icossin2(int x, int y, int *cosp, int *sinp)
.PB
void border(Image *dst, Rectangle r, int i, Image *color, Point sp)
.br
.PB
Point string(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s)
.PB
Point stringop(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, Drawop op)
.PB
Point stringn(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, int len)
.PB
Point stringnop(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, int len, Drawop op)
.PB
Point runestring(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r)
.PB
Point runestringop(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, Drawop op)
.PB
Point runestringn(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, int len)
.PB
Point runestringnop(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, int len, Drawop op)
.PB
Point stringbg(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, Image *bg, Point bgp)
.PB
Point stringbgop(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, Image *bg, Point bgp, Drawop op)
.PB
Point stringnbg(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, int len, Image *bg, Point bgp)
.PB
Point stringnbgop(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, int len, Image *bg, Point bgp, Drawop op)
.PB
Point runestringbg(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, Image *bg, Point bgp)
.PB
Point runestringbgop(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, Image *bg, Point bgp, Drawop op)
.PB
Point runestringnbg(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, int len, Image *bg, Point bgp)
.PB
Point runestringnbgop(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, int len, Image *bg, Point bgp, Drawop op)
.PB
Point _string(Image *dst, Point p, Image *src,
Point sp, Font *f, char *s, Rune *r, int len,
Rectangle clipr, Image *bg, Point bgp, Drawop op)
.PB
void drawsetdebug(int on)
.PD
.PB
enum
{
/* line ends */
Endsquare = 0,
Enddisc = 1,
Endarrow = 2,
Endmask = 0x1F
};
.PB
#define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23))
.SH DESCRIPTION
The
.B Image
type defines rectangular pictures and the methods to draw upon them;
it is also the building block for higher level objects such as
windows and fonts.
In particular, a window is represented as an
.BR Image ;
no special operators are needed to draw on a window.
.PP
.TP 10
.B r
The coordinates of the rectangle in the plane for which the
.B Image
has defined pixel values.
It should not be modified after the image is created.
.TP
.B clipr
The clipping rectangle: operations that read or write
the image will not access pixels outside
.BR clipr .
Frequently,
.B clipr
is the same as
.BR r ,
but it may differ; see in particular the discussion of
.BR repl .
The clipping region may be modified dynamically using
.I replclipr
.RI ( q.v. ).
.TP
.B chan
The pixel channel format descriptor, as described in
.IR image (6).
The value should not be modified after the image is created.
.TP
.B depth
The
number of bits per pixel in the picture;
it is identically
.B chantodepth(chan)
(see
.IR graphics (2))
and is provided as a convenience.
The value should not be modified after the image is created.
.TP
.B repl
A boolean value specifying whether the image is tiled to cover
the plane when used as a source for a drawing operation.
If
.B repl
is zero, operations are restricted to the intersection of
.B r
and
.BR clipr .
If
.B repl
is set,
.B r
defines the tile to be replicated and
.B clipr
defines the portion of the plane covered by the tiling, in other words,
.B r
is replicated to cover
.BR clipr ;
in such cases
.B r
and
.B clipr
are independent.
.IP
For example, a replicated image with
.B r
set to ((0,\ 0),\ (1,\ 1)) and
.B clipr
set to ((0,\ 0),\ (100,\ 100)),
with the single pixel of
.B r
set to blue,
behaves identically to an image with
.B r
and
.B clipr
both set to ((0,\ 0),\ (100,\ 100)) and all pixels set to blue.
However,
the first image requires far less memory.
The replication flag may be modified dynamically using
.I replclipr
.RI ( q.v. ).
.PP
Most of the drawing functions come in two forms:
a basic form, and an extended form that takes an extra
.B Drawop
to specify a Porter-Duff compositing operator to use.
The basic forms assume the operator is
.BR SoverD ,
which suffices for the vast majority of applications.
The extended forms are named by adding an
.RB - op
suffix to the basic form.
Only the basic forms are listed below.
.TP
.BI draw( dst\fP,\fP\ r\fP,\fP\ src\fP,\fP\ mask\fP,\fP\ p )
.I Draw
is the standard drawing function.
Only those pixels within the intersection of
.IB dst ->r
and
.IB dst ->clipr
will be affected;
.I draw
ignores
.IB dst ->repl\fR.
The operation proceeds as follows
(this is a description of the behavior, not the implementation):
.RS
.IP 1.
If
.B repl
is set in
.I src
or
.IR mask ,
replicate their contents to fill
their clip rectangles.
.IP 2.
Translate
.I src
and
.I mask
so
.I p
is aligned with
.IB r .min\fR.
.IP 3.
Set
.I r
to the intersection of
.I r
and
.IB dst ->r\fR.
.IP 4.
Intersect
.I r
with
.IB src ->clipr\fR.
If
.IB src ->repl
is false, also intersect
.I r
with
.IB src ->r\fR.
.IP 5.
Intersect
.I r
with
.IB mask ->clipr\fR.
If
.IB mask ->repl
is false, also intersect
.I r
with
.IB mask ->r\fR.
.IP 6.
For each location in
.IR r ,
combine the
.I dst
pixel with the
.I src
pixel using the alpha value
corresponding to the
.I mask
pixel.
If the
.I mask
has an explicit alpha channel, the alpha value
corresponding to the
.I mask
pixel is simply that pixel's alpha channel.
Otherwise, the alpha value is the NTSC greyscale equivalent
of the color value, with white meaning opaque and black transparent.
In terms of the Porter-Duff compositing algebra,
.I draw
replaces the
.I dst
pixels with
.RI ( src
in
.IR mask )
over
.IR dst .
(In the extended form,
``over'' is replaced by
.IR op ).
.RE
.IP
The various
pixel channel formats
involved need not be identical.
If the channels involved are smaller than 8-bits, they will
be promoted before the calculation by replicating the extant bits;
after the calculation, they will be truncated to their proper sizes.
.TP
\f5gendraw(\f2dst\fP, \f2r\fP, \f2src\fP, \f2p0\fP, \f2mask\fP, \f2p1\f5)\fP
Similar to
.I draw
except that
.I gendraw
aligns the source and mask differently:
.I src
is aligned so
.I p0
corresponds to
.IB r .min
and
.I mask
is aligned so
.I p1
corresponds to
.IB r .min .
For most purposes with simple masks and source images,
.B draw
is sufficient, but
.B gendraw
is the general operator and the one all other drawing primitives are built upon.
.TP
.BI drawreplxy( min , max , x\f5)
Clips
.I x
to be in the half-open interval [\fImin\fP, \fImax\fP) by adding
or subtracting a multiple of \fImax-min\fP.
.TP
.BI drawrepl( r , p )
Clips the point \fIp\fP to be within the rectangle \fIr\fP
by translating the point horizontally by an integer multiple of rectangle width
and vertically by the height.
.TP
.BI replclipr( i , repl , clipr\f5)
Because the image data is stored on the server, local modifications to the
.B Image
data structure itself will have no effect.
.I Repclipr
modifies the local
.B Image
data structure's
.B repl
and
.B clipr
fields, and notifies the server of their modification.
.TP
\f5line(\f2dst\fP, \f2p0\fP, \f2p1\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
Line
draws in
.I dst
a line of width
.RI 1+2* thick
pixels joining points
.I p0
and
.IR p1 .
The line is drawn using pixels from the
.I src
image aligned so
.I sp
in the source corresponds to
.I p0
in the destination.
The line touches both
.I p0
and
.IR p1 ,
and
.I end0
and
.I end1
specify how the ends of the line are drawn.
.B Endsquare
terminates the line perpendicularly to the direction of the line; a thick line with
.B Endsquare
on both ends will be a rectangle.
.B Enddisc
terminates the line by drawing a disc of diameter
.RI 1+2* thick
centered on the end point.
.B Endarrow
terminates the line with an arrowhead whose tip touches the endpoint.
.IP
The macro
.B ARROW
permits explicit control of the shape of the arrow.
If all three parameters are zero, it produces the default arrowhead,
otherwise,
.I a
sets the distance along line from end of the regular line to tip,
.I b
sets the distance along line from the barb to the tip,
and
.I c
sets the distance perpendicular to the line from edge of line to the tip of the barb,
all in pixels.
.IP
.I Line
and the other geometrical operators are equivalent to calls to
.I gendraw
using a mask produced by the geometric procedure.
.TP
\f5poly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
.I Poly
draws a general polygon; it
is conceptually equivalent to a series of calls to
.I line
joining adjacent points in the
array of
.B Points
.IR p ,
which has
.I np
elements.
The ends of the polygon are specified as in
.IR line ;
interior lines are terminated with
.B Enddisc
to make smooth joins.
The source is aligned so
.I sp
corresponds to
.IB p [0]\f1.
.TP
\f5fillpoly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
.I Fillpoly
is like
.I poly
but fills in the resulting polygon rather than outlining it.
The source is aligned so
.I sp
corresponds to
.IB p [0]\f1.
The winding rule parameter
.I wind
resolves ambiguities about what to fill if the polygon is self-intersecting.
If
.I wind
is
.BR ~0 ,
a pixel is inside the polygon if the polygon's winding number about the point
is non-zero.
If
.I wind
is
.BR 1 ,
a pixel is inside if the winding number is odd.
Complementary values (0 or ~1) cause outside pixels to be filled.
The meaning of other values is undefined.
The polygon is closed with a line if necessary.
.TP
\f5bezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
.I Bezier
draws the
cubic Bezier curve defined by
.B Points
.IR a ,
.IR b ,
.IR c ,
and
.IR d .
The end styles are determined by
.I end0
and
.IR end1 ;
the thickness of the curve is
.RI 1+2* thick .
The source is aligned so
.I sp
in
.I src
corresponds to
.I a
in
.IR dst .
.TP
\f5bezspline(\f2dst\fP, \f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
.I Bezspline
takes the same arguments as
.I poly
but draws a quadratic B-spline (despite its name) rather than a polygon.
If the first and last points in
.I p
are equal, the spline has periodic end conditions.
.TP
\f5bezsplinepts(\f2pt\fP, \f2npt\fP, \f2pp\fP)
.I Bezsplinepts
returns in
.I pp
a list of points making up the open polygon that
.I bezspline
would draw.
The caller is responsible for freeing
.IR *pp .
.TP
\f5fillbezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
.I Fillbezier
is to
.I bezier
as
.I fillpoly
is to
.IR poly .
.TP
\f5fillbezspline(\f2dst\fP, \f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
.I Fillbezspline
is like
.I fillpoly
but fills the quadratic B-spline rather than the polygon outlined by
.IR p .
The spline is closed with a line if necessary.
.TP
\f5ellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
.I Ellipse
draws in
.I dst
an ellipse centered on
.I c
with horizontal and vertical semiaxes
.I a
and
.IR b .
The source is aligned so
.I sp
in
.I src
corresponds to
.I c
in
.IR dst .
The ellipse is drawn with thickness
.RI 1+2* thick .
.TP
\f5fillellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP)
.I Fillellipse
is like
.I ellipse
but fills the ellipse rather than outlining it.
.TP
\f5arc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP)
.I Arc
is like
.IR ellipse ,
but draws only that portion of the ellipse starting at angle
.I alpha
and extending through an angle of
.IR phi .
The angles are measured in degrees counterclockwise from the positive
.I x
axis.
.TP
\f5fillarc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP)
.I Fillarc
is like
.IR arc ,
but fills the sector with the source color.
.TP
\f5icossin(\f2deg\fP, \f2cosp\fP, \f2sinp\fP)
.I Icossin
stores in
.BI * cosp
and
.BI * sinp
scaled integers representing the cosine and sine of the angle
.IR deg ,
measured in integer degrees.
The values are scaled so cos(0) is 1024.
.TP
\f5icossin2(\f2x\fP, \f2y\fP, \f2cosp\fP, \f2sinp\fP)
.I Icossin2
is analogous to
.IR icossin,
with the angle represented not in degrees but implicitly by the point
.RI ( x , y ).
It is to
.I icossin
what
.B atan2
is to
.B atan
(see
.IR sin (2)).
.TP
.BI border( dst\fP,\fP\ r\fP,\fP\ i\fP,\fP\ color\fP,\fP\ sp\fP)
.I Border
draws an outline of rectangle
.I r
in the specified
.IR color .
The outline has width
.IR i ;
if positive, the border goes inside the rectangle; negative, outside.
The source is aligned so
.I sp
corresponds to
.IB r .min .
.TP
.BI string( dst\fP,\fP\ p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ s )
.I String
draws in
.I dst
characters specified by the string
.I s
and
.IR font ;
it is equivalent to a series of calls to
.I gendraw
using source
.I src
and masks determined by the character shapes.
The text is positioned with the left of the first character at
.IB p .x
and the top of the line of text at
.IB p .y\f1.
The source is positioned so
.I sp
in
.I src
corresponds to
.I p
in
.IR dst .
.I String
returns a
.B Point
that is the position of the next character that would be drawn if the string were longer.
.IP
For characters with undefined
or zero-width images in the font, the character at font position 0 (NUL) is drawn.
.IP
The other string routines are variants of this basic form, and
have names that encode their variant behavior.
Routines whose names contain
.B rune
accept a string of Runes rather than
.SM UTF\c
-encoded bytes.
Routines ending in
.B n
accept an argument,
.IR n ,
that defines the number of characters to draw rather than accepting a NUL-terminated
string.
Routines containing
.B bg
draw the background behind the characters in the specified color
.RI ( bg )
and
alignment
.RI ( bgp );
normally the text is drawn leaving the background intact.
.IP
The routine
.I _string
captures all this behavior into a single operator. Whether it draws a
.SM UTF
string
or Rune string depends on whether
.I s
or
.I r
is null (the string length is always determined by
.IR len ).
If
.I bg
is non-null, it is used as a background color.
The
.I clipr
argument allows further management of clipping when drawing the string;
it is intersected with the usual clipping rectangles to further limit the extent of the text.
.TP
.BI drawsetdebug( on )
Turns on or off debugging output (usually
to a serial line) according to whether
.I on
is non-zero.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2),
.IR stringsize (2),
.IR color (6),
.IR utf (6),
.IR addpt (2)
.PP
T. Porter, T. Duff.
``Compositing Digital Images'',
.I "Computer Graphics
(Proc. SIGGRAPH), 18:3, pp. 253-259, 1984.
.SH DIAGNOSTICS
These routines call the graphics error function on fatal errors.
.SH BUGS
Anti-aliased characters can be drawn by defining a font
with multiple bits per pixel, but there are
no anti-aliasing geometric primitives.

132
man/man3/dsa.3 Normal file
View File

@@ -0,0 +1,132 @@
.TH DSA 3
.SH NAME
dsagen, dsasign, dsaverify, dsapuballoc, dsapubfree, dsaprivalloc, dsaprivfree, dsasigalloc, dsasigfree, dsaprivtopub - digital signature algorithm
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mp.h>
.br
.B #include <libsec.h>
.PP
.B
DSApriv* dsagen(DSApub *opub)
.PP
.B
DSAsig* dsasign(DSApriv *k, mpint *m)
.PP
.B
int dsaverify(DSApub *k, DSAsig *sig, mpint *m)
.PP
.B
DSApub* dsapuballoc(void)
.PP
.B
void dsapubfree(DSApub*)
.PP
.B
DSApriv* dsaprivalloc(void)
.PP
.B
void dsaprivfree(DSApriv*)
.PP
.B
DSAsig* dsasigalloc(void)
.PP
.B
void dsasigfree(DSAsig*)
.PP
.B
DSApub* dsaprivtopub(DSApriv*)
.SH DESCRIPTION
.PP
DSA is the NIST approved digital signature algorithm. The owner of a key publishes
the public part of the key:
.EX
struct DSApub
{
mpint *p; // modulus
mpint *q; // group order, q divides p-1
mpint *alpha; // group generator
mpint *key; // alpha**secret mod p
};
.EE
This part can be used for verifying signatures (with
.IR dsaverify )
created by the owner.
The owner signs (with
.IR dsasign )
using his private key:
.EX
struct DSApriv
{
DSApub pub;
mpint *secret; // (decryption key)
};
.EE
.PP
Keys are generated using
.IR dsagen .
If
.IR dsagen 's
argument
.I opub
is
.BR nil ,
a key is created using a new
.B p
and
.B q
generated by
.IR DSAprimes (2).
Otherwise,
.B p
and
.B q
are copied from the old key.
.PP
.I Dsaprivtopub
returns a newly allocated copy of the public key
corresponding to the private key.
.PP
The routines
.IR dsapuballoc ,
.IR dsapubfree ,
.IR dsaprivalloc ,
and
.I dsaprivfree
are provided to manage key storage.
.PP
.I Dsasign
signs message
.I m
using a private key
.I k
yielding a
.EX
struct DSAsig
{
mpint *r, *s;
};
.EE
.I Dsaverify
returns 0 if the signature is valid and \-1 if not.
.PP
The routines
.I dsasigalloc
and
.I dsasigfree
are provided to manage signature storage.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR blowfish (2),
.IR des (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)

42
man/man3/dup.3 Normal file
View File

@@ -0,0 +1,42 @@
.TH DUP 3
.SH NAME
dup \- duplicate an open file descriptor
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int dup(int oldfd, int newfd)
.SH DESCRIPTION
Given a file descriptor,
.IR oldfd ,
referring to an open file,
.I dup
returns a new file descriptor referring to the same file.
.PP
If
.I newfd
is \-1 the system chooses the lowest available file descriptor.
Otherwise,
.I dup
will use
.I newfd
for the new file descriptor
(closing any old file associated with
.IR newfd ).
File descriptors are allocated dynamically,
so to prevent unwarranted growth of the file descriptor table,
.I dup
requires that
.I newfd
be no greater than 20 more than the highest file descriptor ever used by
the program.
.SH SOURCE
.B /sys/src/libc/9syscall
.SH SEE ALSO
.IR intro (2),
.IR dup (3)
.SH DIAGNOSTICS
Sets
.IR errstr .

125
man/man3/elgamal.3 Normal file
View File

@@ -0,0 +1,125 @@
.TH ELGAMAL 3
.SH NAME
eggen, egencrypt, egdecrypt, egsign, egverify, egpuballoc, egpubfree, egprivalloc, egprivfree, egsigalloc, egsigfree, egprivtopub - elgamal encryption
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mp.h>
.br
.B #include <libsec.h>
.PP
.B
EGpriv* eggen(int nlen, int nrep)
.PP
.B
mpint* egencrypt(EGpub *k, mpint *in, mpint *out)
.PP
.B
mpint* egdecrypt(EGpriv *k, mpint *in, mpint *out)
.PP
.B
EGsig* egsign(EGpriv *k, mpint *m)
.PP
.B
int egverify(EGpub *k, EGsig *sig, mpint *m)
.PP
.B
EGpub* egpuballoc(void)
.PP
.B
void egpubfree(EGpub*)
.PP
.B
EGpriv* egprivalloc(void)
.PP
.B
void egprivfree(EGpriv*)
.PP
.B
EGsig* egsigalloc(void)
.PP
.B
void egsigfree(EGsig*)
.PP
.B
EGpub* egprivtopub(EGpriv*)
.SH DESCRIPTION
.PP
Elgamal is a public key encryption and signature algorithm. The owner of a key publishes
the public part of the key:
.EX
struct EGpub
{
mpint *p; // modulus
mpint *alpha; // generator
mpint *key; // (encryption key) alpha**secret mod p
};
.EE
This part can be used for encrypting data (with
.IR egencrypt )
to be sent to the owner.
The owner decrypts (with
.IR egdecrypt )
using his private key:
.EX
struct EGpriv
{
EGpub pub;
mpint *secret; // (decryption key)
};
.EE
.PP
Keys are generated using
.IR eggen .
.I Eggen
takes both bit length of the modulus
and the number of repetitions of the Miller-Rabin
primality test to run. If the latter is 0, it does the default number
of rounds.
.I Egprivtopub
returns a newly allocated copy of the public key
corresponding to the private key.
.PP
The routines
.IR egpuballoc ,
.IR egpubfree ,
.IR egprivalloc ,
and
.I egprivfree
are provided to manage key storage.
.PP
.I Egsign
signs message
.I m
using a private key
.I k
yielding a
.EX
struct EGsig
{
mpint *r, *s;
};
.EE
.I Egverify
returns 0 if the signature is valid and \-1 if not.
.PP
The routines
.I egsigalloc
and
.I egsigfree
are provided to manage signature storage.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR blowfish (2),
.IR des (2),
.IR dsa (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)

85
man/man3/encode.3 Normal file
View File

@@ -0,0 +1,85 @@
.TH ENCODE 3
.SH NAME
dec64, enc64, dec32, enc32, dec16, enc16, encodefmt \- encoding byte arrays as strings
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int dec64(uchar *out, int lim, char *in, int n)
.PP
.B
int enc64(char *out, int lim, uchar *in, int n)
.PP
.B
int dec32(uchar *out, int lim, char *in, int n)
.PP
.B
int enc32(char *out, int lim, uchar *in, int n)
.PP
.B
int dec16(uchar *out, int lim, char *in, int n)
.PP
.B
int enc16(char *out, int lim, uchar *in, int n)
.PP
.B
int encodefmt(Fmt*)
.SH DESCRIPTION
.PP
.IR Enc16 ,
.I enc32
and
.I enc64
create null terminated strings. They return the size of the
encoded string (without the null) or -1 if the encoding fails.
The encoding fails if
.IR lim ,
the length of the output buffer, is too small.
.PP
.IR Dec16 ,
.I dec32
and
.I dec64
return the number of bytes decoded or -1 if the decoding fails.
The decoding fails if the output buffer is not large enough or,
for base 32, if the input buffer length is not a multiple
of 8.
.PP
.I Encodefmt
can be used with
.IR fmtinstall (2)
and
.IR print (2)
to print encoded representations of byte arrays.
The verbs are
.TP
.B H
base 16 (i.e. hexadecimal). The default encoding is
in upper case. The
.B l
flag forces lower case.
.TP
.B <
base 32
.TP
.B [
base 64 (same as MIME)
.PD
.PP
The length of the array is specified as
.IR f2 .
For example, to display a 15 byte array as hex:
.EX
char x[15];
fmtinstall('H', encodefmt);
print("%.*H\\n", sizeof x, x);
.EE
.SH SOURCE
.B /sys/src/libc/port/u32.c
.br
.B /sys/src/libc/port/u64.c

76
man/man3/encrypt.3 Normal file
View File

@@ -0,0 +1,76 @@
.TH ENCRYPT 3
.SH NAME
encrypt, decrypt, netcrypt \- DES encryption
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int encrypt(void *key, void *data, int len)
.PP
.B
int decrypt(void *key, void *data, int len)
.PP
.B
int netcrypt(void *key, void *data)
.SH DESCRIPTION
.I Encrypt
and
.I decrypt
perform DES encryption and decryption.
.I Key
is an array of
.B DESKEYLEN
(defined as 7 in
.BR <auth.h> )
bytes containing the encryption key.
.I Data
is an array of
.I len
bytes;
it must be at least 8 bytes long.
The bytes are encrypted or decrypted in place.
.PP
The DES algorithm encrypts an individual 8-byte block of data.
.I Encrypt
uses the following method to encrypt data longer than 8 bytes.
The first 8 bytes are encrypted as usual.
The last byte of the encrypted result
is prefixed to the next 7 unencrypted bytes to make the next 8
bytes to encrypt.
This is repeated until fewer than 7 bytes remain unencrypted.
Any remaining unencrypted bytes are encrypted with enough of the preceding
encrypted bytes to make a full 8-byte block.
.I Decrypt
uses the inverse algorithm.
.PP
.I Netcrypt
performs the same encryption as a SecureNet Key.
.I Data
points to an
.SM ASCII
string of decimal digits with numeric value between 0 and 10000.
These digits are copied into an 8-byte buffer with trailing binary zero fill
and encrypted as one DES block.
The first four bytes are each formatted as two digit
.SM ASCII
hexadecimal numbers,
and the string is copied into
.IR data .
.SH SOURCE
.B /sys/src/libc/port
.SH DIAGNOSTICS
These routines return 1 if the data was encrypted,
and 0 if the encryption fails.
.I Encrypt
and
.I decrypt
fail if the data passed is less than 8 bytes long.
.I Netcrypt
can fail if it is passed invalid data.
.SH SEE ALSO
.IR securenet (8)
.SH BUGS
The implementation is broken in a way that makes
it unsuitable for anything but authentication.

85
man/man3/errstr.3 Normal file
View File

@@ -0,0 +1,85 @@
.TH ERRSTR 3
.SH NAME
errstr, rerrstr, werrstr \- description of last system call error
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int errstr(char *err, uint nerr)
.PP
.B
void rerrstr(char *err, uint nerr)
.PP
.B
void werrstr(char *fmt, ...)
.SH DESCRIPTION
When a system call fails it returns \-1 and
records a null terminated string describing the error in a per-process buffer.
.I Errstr
swaps the contents of that buffer with the contents of the array
.IR err .
.I Errstr
will write at most
.I nerr
bytes into
.IR err ;
if the per-process error string does not fit,
it is silently truncated at a UTF character boundary.
The returned string is NUL-terminated.
Usually
.I errstr
will be called with an empty string,
but the exchange property provides a mechanism for
libraries to set the return value for the next call to
.IR errstr .
.PP
The per-process buffer is
.B ERRMAX
bytes long. Any error string provided by the user will
be truncated at
.B ERRMAX-1
bytes.
.B ERRMAX
is defined in
.BR <libc.h> .
.PP
If no system call has generated an error since the last call to
.I errstr
with an empty string,
the result is an empty string.
.PP
The verb
.B r
in
.IR print (2)
calls
.I errstr
and outputs the error string.
.PP
.I Rerrstr
reads the error string but does not modify the per-process buffer, so
a subsequent
.I errstr
will recover the same string.
.PP
.I Werrstr
takes a
.I print
style format as its argument and uses it to format
a string to pass to
.IR errstr .
The string returned from
.I errstr
is discarded.
.SH SOURCE
.B /sys/src/libc/9syscall
.br
.B /sys/src/libc/9sys/werrstr.c
.SH DIAGNOSTICS
.I Errstr
always returns 0.
.SH SEE ALSO
.IR intro (2),
.IR perror (2)

384
man/man3/event.3 Normal file
View File

@@ -0,0 +1,384 @@
.TH EVENT 3
.SH NAME
event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu \- graphics events
.SH SYNOPSIS
.nf
.PP
.B
#include <u.h>
.B
#include <libc.h>
.B
#include <draw.h>
.B
#include <event.h>
.B
#include <cursor.h>
.ta \w'\fLRectangle 'u
.PP
.B
void einit(ulong keys)
.PP
.B
ulong event(Event *e)
.PP
.B
Mouse emouse(void)
.PP
.B
int ekbd(void)
.PP
.B
int ecanmouse(void)
.PP
.B
int ecankbd(void)
.PP
.B
int ereadmouse(Mouse *m)
.PP
.B
int eatomouse(Mouse *m, char *buf, int n)
.PP
.B
ulong estart(ulong key, int fd, int n)
.PP
.B
ulong estartfn(int id, ulong key, int fd, int n,
.B
int (*fn)(Event*, uchar*, int))
.PP
.B
ulong etimer(ulong key, int n)
.PP
.B
ulong eread(ulong keys, Event *e)
.PP
.B
int ecanread(ulong keys)
.PP
.B
void eresized(int new)
.PP
.B
Rectangle egetrect(int but, Mouse *m)
.PP
.B
void edrawgetrect(Rectangle r, int up)
.PP
.B
int emenuhit(int but, Mouse *m, Menu *menu)
.PP
.PP
.B
int emoveto(Point p)
.PP
.PP
.B
int esetcursor(Cursor *c)
.PP
.B
extern Mouse *mouse
.PP
.B
enum{
.B
Emouse = 1,
.B
Ekeyboard = 2,
.B
};
.PP
.SH DESCRIPTION
These routines provide an interface to multiple sources of input for unthreaded
programs.
Threaded programs (see
.IR thread (2))
should instead use the threaded mouse and keyboard interface described
in
.IR mouse (2)
and
.IR keyboard (2).
.PP
.I Einit
must be called first.
If the argument to
.I einit
has the
.B Emouse
and
.B Ekeyboard
bits set,
the mouse and keyboard events will be enabled;
in this case,
.IR initdraw
(see
.IR graphics (2))
must have already been called.
The user must provide a function called
.IR eresized
to be called whenever the window in which the process
is running has been resized; the argument
.I new
is a flag specifying whether the program must call
.I getwindow
(see
.IR graphics (2))
to re-establish a connection to its window.
After resizing (and perhaps calling
.IR getwindow ),
the global variable
.B screen
will be updated to point to the new window's
.B Image
structure.
.PP
As characters are typed on the keyboard, they are read by the
event mechanism and put in a queue.
.I Ekbd
returns the next rune from the queue, blocking until the
queue is non-empty.
The characters are read in raw mode
(see
.IR cons (3)),
so they are available as soon as a complete rune is typed.
.PP
When the mouse moves or a mouse button is pressed or released,
a new mouse event is queued by the event mechanism.
.I Emouse
returns the next mouse event from the queue, blocking until the
queue is non-empty.
.I Emouse
returns a
.B Mouse
structure:
.IP
.EX
.ta 6n +\w'Point 'u
struct Mouse
{
int buttons;
Point xy;
ulong msec;
};
.EE
.PP
.B Buttons&1
is set when the left mouse button is pressed,
.B buttons&2
when the middle button is pressed,
and
.B buttons&4
when the right button is pressed.
The current mouse position is always returned in
.BR xy .
.B Msec
is a time stamp in units of milliseconds.
.PP
.I Ecankbd
and
.I ecanmouse
return non-zero when there are keyboard or mouse events available
to be read.
.PP
.I Ereadmouse
reads the next mouse event from the file descriptor connected to the mouse,
converts the textual data into a
.B Mouse
structure by calling
.I eatomouse
with the buffer and count from the read call,
and returns the number of bytes read, or \-1 for an error.
.PP
.I Estart
can be used to register additional file descriptors to scan for input.
It takes as arguments the file descriptor to register,
the maximum length of an event message on that descriptor,
and a key to be used in accessing the event.
The key must be a power of 2 and must not conflict with any previous keys.
If a zero key is given, a key will be allocated and returned.
.I Estartfn
is similar to
.IR estart ,
but processes the data received by calling
.I fn
before returning the event to the user.
The function
.I fn
is called with the
.B id
of the event; it should return
.B id
if the event is to be passed to the user,
.B 0
if it is to be ignored.
The variable
.B Event.v
can be used by
.I fn
to attach an arbitrary data item to the returned
.B Event
structure.
.B
Ekeyboard
and
.B Emouse
are the keyboard and mouse event keys.
.PP
.I Etimer
starts a repeating timer with a period of
.I n
milliseconds; it returns the timer event key, or zero if it fails.
Only one timer can be started.
Extra timer events are not queued and the timer channel has no associated data.
.PP
.I Eread
waits for the next event specified by the mask
.I keys
of event keys submitted to
.IR estart .
It fills in the appropriate field of the argument
.B Event
structure, which looks like:
.IP
.EX
struct Event
{
int kbdc;
Mouse mouse;
int n;
void *v;
uchar data[EMAXMSG];
};
.EE
.PP
.B Data
is an array which is large enough to hold a 9P message.
.I Eread
returns the key for the event which was chosen.
For example, if a mouse event was read,
.B Emouse
will be returned.
.PP
.I Event
waits for the next event of any kind.
The return is the same as for
.IR eread .
.PP
As described in
.IR graphics (2),
the graphics functions are buffered.
.IR Event ,
.IR eread ,
.IR emouse ,
and
.I ekbd
all cause a buffer flush unless there is an event of the
appropriate type already queued.
.PP
.I Ecanread
checks whether a call to
.B eread(keys)
would block, returning 0 if it would, 1 if it would not.
.PP
.I Getrect
prompts the user to sweep a rectangle.
It should be called with
.I m
holding the mouse event that triggered the
.I egetrect
(or, if none, a
.B Mouse
with
.B buttons
set to 7).
It changes to the sweep cursor,
waits for the buttons all to be released,
and then waits for button number
.I but
to be pressed, marking the initial corner.
If another button is pressed instead,
.I egetrect
returns a rectangle
with zero for both corners, after
waiting for all the buttons to be released.
Otherwise,
.I egetrect
continually draws the swept rectangle
until the button is released again, and returns the swept rectangle.
The mouse structure pointed to by
.I m
will contain the final mouse event.
.PP
.I Egetrect
uses successive calls to
.I edrawgetrect
to maintain the red rectangle showing the sweep-in-progress.
The rectangle to be drawn is specified by
.I rc
and the
.I up
parameter says whether to draw (1) or erase (0) the rectangle.
.PP
.I Emenuhit
displays a menu and returns a selected menu item number.
It should be called with
.I m
holding the mouse event that triggered the
.IR emenuhit ;
it will call
.I emouse
to update it.
A
.B Menu
is a structure:
.IP
.EX
struct Menu
{
char **item;
char *(*gen)(int);
int lasthit;
};
.EE
.PP
If
.B item
is nonzero, it should be a null-terminated array of the character strings
to be displayed as menu items.
Otherwise,
.B gen
should be a function that, given an item number, returns the character
string for that item, or zero if the number is past the end of the list.
Items are numbered starting at zero.
.I Menuhit
waits until
.I but
is released, and then returns the number of the selection,
or \-1 for no selection.
The
.I m
argument is filled in with the final mouse event.
.PP
.I Emoveto
moves the mouse cursor to the position
.B p
on the screen.
.PP
.I Esetcursor
changes the cursor image to that described by the
.B Cursor
.I c
(see
.IR mouse (2)).
If
.B c
is nil, it restores the image to the default arrow.
.SH SOURCE
.B /sys/src/libdraw
.SH "SEE ALSO"
.IR rio (1),
.IR graphics (2),
.IR plumb (2),
.IR cons (3),
.IR draw (3)

159
man/man3/exec.3 Normal file
View File

@@ -0,0 +1,159 @@
.TH EXEC 3
.SH NAME
exec, execl, _clock, _privates, _nprivates \- execute a file
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.nf
.B
int exec(char *name, char* argv[])
.PP
.B
int execl(char *name, ...)
.PP
.B
long *_clock;
.PP
.B
void **_privates;
.PP
.B
int _nprivates;
.fi
.SH DESCRIPTION
.I Exec
and
.I execl
overlay the calling process with the named file, then
transfer to the entry point of the image of the file.
.PP
.I Name
points to the name of the file
to be executed; it must not be a directory, and the permissions
must allow the current user to execute it
(see
.IR stat (2)).
It should also be a valid binary image, as defined in the
.IR a.out (6)
for the current machine architecture,
or a shell script
(see
.IR rc (1)).
The first line of a
shell script must begin with
.L #!
followed by the name of the program to interpret the file
and any initial arguments to that program, for example
.IP
.EX
#!/bin/rc
ls | mc
.EE
.PP
When a C program is executed,
it is called as follows:
.IP
.EX
void main(int argc, char *argv[])
.EE
.PP
.I Argv
is a copy of the array of argument pointers passed to
.IR exec ;
that array must end in a null pointer, and
.I argc
is the number of elements before the null pointer.
By convention, the first argument should be the name of
the program to be executed.
.I Execl
is like
.I exec
except that
.I argv
will be an array of the parameters that follow
.I name
in the call. The last argument to
.I execl
must be a null pointer.
.PP
For a file beginning
.BR #! ,
the arguments passed to the program
.RB ( /bin/rc
in the example above) will be the name of the file being
executed, any arguments on the
.B #!
line, the name of the file again,
and finally the second and subsequent arguments given to the original
.I exec
call.
The result honors the two conventions of a program accepting as argument
a file to be interpreted and
.B argv[0]
naming the file being
executed.
.PP
Most attributes of the calling process are carried
into the result; in particular,
files remain open across
.I exec
(except those opened with
.B OCEXEC
OR'd
into the open mode; see
.IR open (2));
and the working directory and environment
(see
.IR env (3))
remain the same.
However, a newly
.I exec'ed
process has no notification handler
(see
.IR notify (2)).
.PP
When the new program begins, the global cell
.B _clock
is set to the address of a cell that keeps approximate time
expended by the process at user level.
The time is measured in milliseconds but is updated at
a system-dependent lower rate.
This clock is typically used by the profiler but is available
to all programs.
.PP
The global cell
.B _privates
points to an array of
.B _nprivates
elements of per-process private data.
This storage is private for each process, even if the processes share data segments.
.PP
The above conventions apply to C programs; the raw system
interface to the new image is as follows:
the word pointed to by the stack pointer is
.BR argc ;
the words beyond that are the zeroth and subsequent elements
of
.BR argv ,
followed by a terminating null pointer; and
the return register (e.g.
.B R0
on the 68020) contains the address of the clock.
.SH SOURCE
.B /sys/src/libc/9syscall
.br
.B /sys/src/libc/port/execl.c
.SH SEE ALSO
.IR prof (1),
.IR intro (2),
.IR stat (2)
.SH DIAGNOSTICS
If these functions fail, they return and set
.IR errstr .
There can be no return from a successful
.I exec
or
.IR execl ;
the calling image is lost.

81
man/man3/exits.3 Normal file
View File

@@ -0,0 +1,81 @@
.TH EXITS 3
.SH NAME
exits, _exits, atexit, atexitdont, terminate \- terminate process, process cleanup
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.nf
.B
void _exits(char *msg)
.B
void exits(char *msg)
.PP
.B
int atexit(void(*)(void))
.PP
.B
void atexitdont(void(*)(void))
.fi
.SH DESCRIPTION
.I Exits
is the conventional way to terminate a process.
.I _Exits
is the underlying system call.
They
can never return.
.PP
.I Msg
conventionally includes a brief (maximum length
.BR ERRLEN )
explanation of the reason for
exiting, or a null pointer or empty string to indicate normal termination.
The string is passed to the parent process, prefixed by the name and process
id of the exiting process, when the parent does a
.IR wait (2).
.PP
Before calling
.I _exits
with
.I msg
as an argument,
.I exits
calls in reverse order all the functions
recorded by
.IR atexit .
.PP
.I Atexit
records
.I fn
as a function to be called by
.IR exits .
It returns zero if it failed,
nonzero otherwise.
A typical use is to register a cleanup routine for an I/O package.
To simplify programs that fork or share memory,
.I exits
only calls those
.IR atexit -registered
functions that were registered by the same
process as that calling
.IR exits .
.PP
Calling
.I atexit
twice (or more) with the same function argument causes
.I exits
to invoke the function twice (or more).
.PP
There is a limit to the number of exit functions
that will be recorded;
.I atexit
returns 0 if that limit has been reached.
.PP
.I Atexitdont
cancels a previous registration of an exit function.
.SH SOURCE
.B /sys/src/libc/port/atexit.c
.SH "SEE ALSO"
.IR fork (2),
.IR wait (2)

357
man/man3/fcall.3 Normal file
View File

@@ -0,0 +1,357 @@
.TH FCALL 3
.SH NAME
Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeS2M, sizeD2M \- interface to Plan 9 File protocol
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.br
.B #include <fcall.h>
.PP
.B
uint convS2M(Fcall *f, uchar *ap, uint nap)
.PP
.B
uint convD2M(Dir *d, uchar *ap, uint nap)
.PP
.B
uint convM2S(uchar *ap, uint nap, Fcall *f)
.PP
.B
uint convM2D(uchar *ap, uint nap, Dir *d, char *strs)
.PP
.B
int dirfmt(Fmt*)
.PP
.B
int fcallfmt(Fmt*)
.PP
.B
int dirmodefmt(Fmt*)
.PP
.B
int read9pmsg(int fd, uchar *buf, uint nbuf)
.PP
.B
int statcheck(uchar *buf, uint nbuf)
.PP
.B
uint sizeS2M(Fcall *f)
.PP
.B
uint sizeD2M(Dir *d)
.SH DESCRIPTION
These
routines convert messages in the machine-independent format of
the Plan 9 file protocol,
9P, to and from a more convenient form,
an
.B Fcall
structure:
.PP
.EX
.if n .ta 4n +6n +5n +6n +18n +4n
.if t .ta \w'xxxx'u +\w'short 'u +\w'xxxx'u +\w'ushort 'u +\w'ticket[TICKETLEN]; 'u +\w'/* 'u
#define MAXWELEM 16
typedef
struct Fcall
{
uchar type;
u32int fid;
ushort tag;
union {
struct {
u32int msize; /* Tversion, Rversion */
char *version; /* Tversion, Rversion */
};
struct {
ushort oldtag; /* Tflush */
};
struct {
char *ename; /* Rerror */
};
struct {
Qid qid; /* Rattach, Ropen, Rcreate */
u32int iounit; /* Ropen, Rcreate */
};
struct {
Qid aqid; /* Rauth */
};
struct {
u32int afid; /* Tauth, Tattach */
char *uname; /* Tauth, Tattach */
char *aname; /* Tauth, Tattach */
};
struct {
u32int perm; /* Tcreate */
char *name; /* Tcreate */
uchar mode; /* Tcreate, Topen */
};
struct {
u32int newfid; /* Twalk */
ushort nwname; /* Twalk */
char *wname[MAXWELEM]; /* Twalk */
};
struct {
ushort nwqid; /* Rwalk */
Qid wqid[MAXWELEM]; /* Rwalk */
};
struct {
vlong offset; /* Tread, Twrite */
u32int count; /* Tread, Twrite, Rread */
char *data; /* Twrite, Rread */
};
struct {
ushort nstat; /* Twstat, Rstat */
uchar *stat; /* Twstat, Rstat */
};
};
} Fcall;
.EE
.EX
/* these are implemented as macros */
uchar GBIT8(uchar*)
ushort GBIT16(uchar*)
ulong GBIT32(uchar*)
vlong GBIT64(uchar*)
void PBIT8(uchar*, uchar)
void PBIT16(uchar*, ushort)
void PBIT32(uchar*, ulong)
void PBIT64(uchar*, vlong)
#define BIT8SZ 1
#define BIT16SZ 2
#define BIT32SZ 4
#define BIT64SZ 8
.EE
.PP
This structure is defined in
.BR <fcall.h> .
See section 5
for a full description of 9P messages and their encoding.
For all message types, the
.B type
field of an
.B Fcall
holds one of
.BR Tversion ,
.BR Rversion ,
.BR Tattach ,
.BR Rattach ,
etc. (defined in an enumerated type in
.BR <fcall.h> ).
.B Fid
is used by most messages, and
.B tag
is used by all messages.
The other fields are used selectively by the message types
given in comments.
.PP
.I ConvM2S
takes a 9P message at
.I ap
of length
.IR nap ,
and uses it to fill in
.B Fcall
structure
.IR f .
If the passed message
including any data for
.B Twrite
and
.B Rread
messages
is formatted properly,
the return value is the number of bytes the message occupied in the buffer
.IR ap ,
which will always be less than or equal to
.IR nap ;
otherwise it is 0.
For
.B Twrite
and
.B Tread
messages,
.B data
is set to a pointer into the argument message,
not a copy.
.PP
.I ConvS2M
does the reverse conversion, turning
.I f
into a message starting at
.IR ap .
The length of the resulting message is returned.
For
.B Twrite
and
.B Rread
messages,
.B count
bytes starting at
.B data
are copied into the message.
.PP
The constant
.B IOHDRSZ
is a suitable amount of buffer to reserve for storing
the 9P header;
the data portion of a
.B Twrite
or
.B Rread
will be no more than the buffer size negotiated in the
.BR Tversion/Rversion
exchange, minus
.BR IOHDRSZ .
.PP
The routine
.I sizeS2M
returns the number of bytes required to store the machine-independent representation of the
.B Fcall
structure
.IR f ,
including its initial 32-bit size field.
In other words, it reports the number of bytes produced
by a successful call to
.IR convS2M .
.PP
Another structure is
.BR Dir ,
used by the routines described in
.IR stat (2).
.I ConvM2D
converts the machine-independent form starting at
.I ap
into
.IR d
and returns the length of the machine-independent encoding.
The strings in the returned
.B Dir
structure are stored at successive locations starting at
.BR strs .
Usually
.B strs
will point to storage immediately after the
.B Dir
itself.
It can also be a
.B nil
pointer, in which case the string pointers in the returned
.B Dir
are all
.BR nil ;
however, the return value still includes their length.
.PP
.I ConvD2M
does the reverse translation,
also returning the length of the encoding.
If the buffer is too short, the return value will be
.B BIT16SZ
and the correct size will be returned in the first
.B BIT16SZ
bytes.
(If the buffer is less that
.BR BIT16SZ ,
the return value is zero; therefore a correct test for
complete packing of the message is that the return value is
greater than
.BR BIT16SZ ).
The macro
.B GBIT16
can be used to extract the correct value.
The related macros with different sizes retrieve the corresponding-sized quantities.
.B PBIT16
and its brethren place values in messages.
With the exception of handling short buffers in
.IR convD2M ,
these macros are not usually needed except by internal routines.
.PP
Analogous to
.IR sizeS2M ,
.I sizeD2M
returns the number of bytes required to store the machine-independent representation of the
.B Dir
structure
.IR d ,
including its initial 16-bit size field.
.PP
The routine
.B statcheck
checks whether the
.I nbuf
bytes of
.I buf
contain a validly formatted machine-independent
.B Dir
entry suitable as an argument, for example, for the
.B wstat
(see
.IR stat (2))
system call.
It checks that the sizes of all the elements of the the entry sum to exactly
.IR nbuf ,
which is a simple but effective test of validity.
.I Nbuf
and
.I buf
should include the second two-byte (16-bit) length field that precedes the entry when
formatted in a 9P message (see
.IR stat (5));
in other words,
.I nbuf
is 2 plus the sum of the sizes of the entry itself.
.I Statcheck
also verifies that the length field has the correct value (that is,
.IB nbuf -2\f1).
It returns
.B 0
for a valid entry and
.B -1
for an incorrectly formatted entry.
.PP
.IR Dirfmt ,
.IR fcallfmt ,
and
.I dirmodefmt
are formatting routines, suitable for
.IR fmtinstall (2).
They convert
.BR Dir* ,
.BR Fcall* ,
and
.BR long
values into string representations of the directory buffer,
.B Fcall
buffer,
or file mode value.
.I Fcallfmt
assumes that
.I dirfmt
has been installed with format letter
.L D
and
.I dirmodefmt
with format letter
.LR M .
.PP
.I Read9pmsg
calls
.IR read (2)
multiple times, if necessary, to read an entire 9P message into
.BR buf .
The return value is 0 for end of file, or -1 for error; it does not return
partial messages.
.SH SOURCE
.B /sys/src/libc/9sys
.SH SEE ALSO
.IR intro (2),
.IR 9p (2),
.IR stat (2),
.IR intro (5)

207
man/man3/flate.3 Normal file
View File

@@ -0,0 +1,207 @@
.TH FLATE 3
.SH NAME
deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, flateerr, mkcrctab, blockcrc, adler32 \- deflate compression
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <flate.h>
.PP
.ta \w'ulongmm'u
.PP
.B
int deflateinit(void)
.PP
.B
int deflate(void *wr, int (*w)(void*,void*,int),
.br
.B
void *rr, int (*r)(void*,void*,int),
.br
.B
int level, int debug)
.PP
.B
int deflatezlib(void *wr, int (*w)(void*,void*,int),
.br
.B
void *rr, int (*r)(void*,void*,int),
.br
.B
int level, int debug)
.PP
.B
int deflateblock(uchar *dst, int dsize,
.br
.B
uchar *src, int ssize,
.br
.B
int level, int debug)
.PP
.B
int deflatezlibblock(uchar *dst, int dsize,
.br
.B
uchar *src, int ssize,
.br
.B
int level, int debug)
.PP
.B
int inflateinit(void)
.PP
.B
int inflate(void *wr, int (*w)(void*, void*, int),
.br
.B
void *getr, int (*get)(void*))
.PP
.B
int inflatezlib(void *wr, int (*w)(void*, void*, int),
.br
.B
void *getr, int (*get)(void*))
.PP
.B
int inflateblock(uchar *dst, int dsize,
.br
.B
uchar *src, int ssize)
.PP
.B
int inflatezlibblock(uchar *dst, int dsize,
.br
.B
uchar *src, int ssize)
.PP
.B
char *flateerr(int error)
.PP
.B
ulong *mkcrctab(ulong poly)
.PP
.B
ulong blockcrc(ulong *tab, ulong crc, void *buf, int n)
.PP
.B
ulong adler32(ulong adler, void *buf, int n)
.SH DESCRIPTION
These routines compress and decompress data using the deflate compression algorithm,
which is used for most gzip, zip, and zlib files.
.PP
.I Deflate
compresses input data retrieved by calls to
.I r
with arguments
.IR rr ,
an input buffer, and a count of bytes to read.
.I R
should return the number of bytes read;
end of input is signaled by returning zero, an input error by
returning a negative number.
The compressed output is written to
.I w
with arguments
.IR wr ,
the output data, and the number of bytes to write.
.I W
should return the number of bytes written;
writing fewer than the requested number of bytes is an error.
.I Level
indicates the amount of computation deflate should do while compressing the data.
Higher
.I levels
usually take more time and produce smaller outputs.
Valid values are 1 to 9, inclusive; 6 is a good compromise.
If
.I debug
is non-zero, cryptic debugging information is produced on standard error.
.PP
.I Inflate
reverses the process, converting compressed data into uncompressed output.
Input is retrieved one byte at a time by calling
.I get
with the argument
.IR getr .
End of input of signaled by returning a negative value.
The uncompressed output is written to
.IR w ,
which has the same interface as for
.IR deflate .
.PP
.I
Deflateblock
and
.I inflateblock
operate on blocks of memory but are otherwise similar to
.I deflate
and
.IR inflate .
.PP
The zlib functions are similar, but operate on files with a zlib header and trailer.
.PP
.I Deflateinit
or
.I inflateinit
must be called once before any call to the corresponding routines.
.PP
If the above routines fail,
they return a negative number indicating the problem.
The possible values are
.IR FlateNoMem ,
.IR FlateInputFail ,
.IR FlateOutputFail ,
.IR FlateCorrupted ,
and
.IR FlateInternal .
.I Flateerr
converts the number into a printable message.
.I FlateOk
is defined to be zero,
the successful return value for
.IR deflateinit ,
.IR deflate ,
.IR deflatezlib ,
.IR inflateinit ,
.IR inflate ,
and
.IR inflatezlib .
The block functions return the number of bytes produced when they succeed.
.PP
.I Mkcrctab
allocates
(using
.IR malloc (2)),
initializes, and returns a table for rapid computation of 32 bit CRC values using the polynomial
.IR poly .
.I Blockcrc
uses
.IR tab ,
a table returned by
.IR mkcrctab ,
to update
.I crc
for the
.I n
bytes of data in
.IR buf ,
and returns the new value.
.I Crc
should initially be zero.
.I Blockcrc
pre-conditions and post-conditions
.I crc
by ones complementation.
.PP
.I Adler32
updates the Adler 32-bit checksum of the
.I n
butes of data in
.IR buf.
The initial value of
.I adler
(that is, its value after seeing zero bytes) should be 1.
.SH SOURCE
.B /sys/src/libflate

117
man/man3/fmtinstall.3
View File

@@ -1,22 +1,17 @@
.TH FMTINSTALL 3
.de EX
.nf
.ft B
..
.de EE
.fi
.ft R
..
.SH NAME
fmtinstall, dofmt, fmtprint, fmtvprint, fmtstrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush \- support for user-defined print formats and output routines
fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, runefmtstrinit, runefmtstrflush, errfmt \- support for user-defined print formats and output routines
.SH SYNOPSIS
.B #include <fmt.h>
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.ft L
.nf
.ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u
typedef struct Fmt Fmt;
struct Fmt{
uchar runes; /* output buffer is runes or chars? */
void *start; /* of buffer */
void *to; /* current place in the buffer */
void *stop; /* end of the buffer; overwritten if flush fails */
@@ -24,10 +19,10 @@ struct Fmt{
void *farg; /* to make flush a closure */
int nfmt; /* num chars formatted so far */
va_list args; /* args passed to dofmt */
int r; /* % format character */
int r; /* % format Rune */
int width;
int prec;
unsigned long flags;
ulong flags;
};
enum{
@@ -43,10 +38,8 @@ enum{
FmtLong = FmtShort << 1,
FmtVLong = FmtLong << 1,
FmtComma = FmtVLong << 1,
FmtByte = FmtComma << 1,
FmtLDouble = FmtByte << 1,
FmtFlag = FmtLDouble << 1
FmtFlag = FmtComma << 1
};
.fi
.PP
@@ -65,6 +58,13 @@ int fmtstrinit(Fmt *f);
.PP
.B
char* fmtstrflush(Fmt *f);
.PP
.B
int runefmtstrinit(Fmt *f);
.PP
.B
Rune* runefmtstrflush(Fmt *f);
.PP
.B
int fmtinstall(int c, int (*fn)(Fmt*));
@@ -73,6 +73,9 @@ int fmtinstall(int c, int (*fn)(Fmt*));
int dofmt(Fmt *f, char *fmt);
.PP
.B
int dorfmt(Fmt*, Rune *fmt);
.PP
.B
int fmtprint(Fmt *f, char *fmt, ...);
.PP
.B
@@ -83,18 +86,24 @@ int fmtrune(Fmt *f, int r);
.PP
.B
int fmtstrcpy(Fmt *f, char *s);
.PP
.B
int fmtrunestrcpy(Fmt *f, Rune *s);
.PP
.B
int errfmt(Fmt *f);
.SH DESCRIPTION
The interface described here allows the construction of custom
.IR print (3)
.IR print (2)
verbs and output routines.
In essence, they provide access to the workings of the formatted print code.
.PP
The
.IR print (3)
.IR print (2)
suite maintains its state with a data structure called
.BR Fmt .
A typical call to
.IR print (3)
.IR print (2)
or its relatives initializes a
.B Fmt
structure, passes it to subsidiary routines to process the output,
@@ -106,7 +115,7 @@ are unimportant to outside users, except insofar as the general
design influences the interface.
The
.B Fmt
records
records whether the output is in runes or bytes,
the verb being processed, its precision and width,
and buffering parameters.
Most important, it also records a
@@ -142,15 +151,15 @@ Then call
or
.IR fmtvprint
to generate the output.
These behave just like
These behave like
.B fprint
(see
.IR print (3))
.IR print (2))
or
.B vfprint
except that the characters are buffered until
.I fmtfdflush
is called.
is called and the return value is either 0 or \-1.
A typical example of this sequence appears in the Examples section.
.PP
The same basic sequence applies when outputting to an allocated string:
@@ -166,6 +175,10 @@ to generate the output.
Finally,
.I fmtstrflush
will return the allocated string, which should be freed after use.
To output to a rune string, use
.I runefmtstrinit
and
.IR runefmtstrflush .
Regardless of the output style or type,
.I fmtprint
or
@@ -194,7 +207,7 @@ In
are the width and precision, and
.IB fp ->flags
the decoded flags for the verb (see
.IR print (3)
.IR print (2)
for a description of these items).
The standard flag values are:
.B FmtSign
@@ -211,12 +224,8 @@ The standard flag values are:
.RB ( l ),
.B FmtShort
.RB ( h ),
.B FmtByte
.RB ( hh ),
.B FmtUnsigned
.RB ( u ),
.B FmtLDouble
.RB ( L ),
and
.B FmtVLong
.RB ( ll ).
@@ -242,8 +251,7 @@ If
.IB fp ->r
is a flag,
.I fn
should return a negative value:
the negation of one of the above flag values, or some otherwise unused power of two.
should return one.
All interpretation of
.IB fp ->width\f1,
.IB fp ->prec\f1,
@@ -259,30 +267,47 @@ and
may be called to
help prepare output in custom conversion routines.
However, these functions clear the width, precision, and flags.
The function
Both functions return 0 for success and \-1 for failure.
.PP
The functions
.I dofmt
is the underlying formatter; it
uses the existing contents of
and
.I dorfmt
are the underlying formatters; they
use the existing contents of
.B Fmt
and should be called only by sophisticated conversion routines.
All these routines return the number of characters
These routines return the number of characters (bytes of UTF or runes)
produced.
.PP
Some internal functions may be useful to format primitive types.
They honor the width, precision and flags as described in
.IR print (3).
.IR print (2).
.I Fmtrune
formats a single character
.BR r .
.I Fmtstrcpy
formats a string
.BR s ;
.I fmtrunestrcpy
formats a rune string
.BR s .
.I Errfmt
formats the system error string.
All these routines return zero for successful execution.
Conversion routines that call these functions will work properly
regardless of whether the output is bytes or runes.
.PP
.IR 2c (1)
describes the C directive
.B #pragma
.B varargck
that can be used to provide type-checking for custom print verbs and output routines.
.SH EXAMPLES
This function prints an error message with a variable
number of arguments and then quits.
Compared to the corresponding example in
.IR print (3),
.IR print (2),
this version uses a smaller buffer, will never truncate
the output message, but might generate multiple
.B write
@@ -290,6 +315,7 @@ system calls to produce its output.
.IP
.EX
.ta 6n +6n +6n +6n +6n +6n +6n +6n +6n
#pragma varargck argpos error 1
void fatal(char *fmt, ...)
{
@@ -316,6 +342,8 @@ struct {
double r, i;
} Complex;
#pragma varargck type "X" Complex
int
Xfmt(Fmt *f)
{
@@ -327,20 +355,19 @@ Xfmt(Fmt *f)
main(...)
{
Complex x;
x.r = 1.5;
x.i = -2.3;
Complex x = (Complex){ 1.5, -2.3 };
fmtinstall('X', Xfmt);
print("x = %X\en", x);
}
.EE
.SH SOURCE
.B /sys/src/libc/fmt
.SH SEE ALSO
.IR print (3)
.SH HISTORY
This formatted print library originally
appeared as part of the Plan 9 C library.
.IR print (2),
.IR utf (6),
.IR errstr (2)
.SH DIAGNOSTICS
These routines return negative numbers or nil for errors and set
.IR errstr .
.SH BUGS
The Plan 9 version supports Unicode strings and produces UTF output.
This version assumes that characters are always represented by 1-byte values.

166
man/man3/fork.3 Normal file
View File

@@ -0,0 +1,166 @@
.TH FORK 3
.SH NAME
fork, rfork \- manipulate process resources
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.nf
.B
int fork(void)
.PP
.B
int rfork(int flags)
.fi
.SH DESCRIPTION
Forking is the only way new processes are created.
The
.I flags
argument to
.I rfork
selects which resources of the
invoking process (parent) are shared
by the new process (child) or initialized to
their default values.
The resources include
the file name space,
the open file descriptor table (which, when shared, permits processes
to open and close files for other processes),
the set of environment variables
(see
.IR env (3)),
the note group
(the set of processes that receive notes written to a member's
.B notepg
file;
see
.IR proc (3)),
the set of rendezvous tags
(see
.IR rendezvous (2));
and open files.
.I Flags
is the logical OR of some subset of
.TF RFCNAMEG
.TP
.B RFPROC
If set a new process is created; otherwise changes affect the
current process.
.TP
.B RFNOWAIT
If set, the child process will be dissociated from the parent. Upon
exit the child will leave no
.B Waitmsg
(see
.IR wait (2))
for the parent to collect.
.TP
.B RFNAMEG
If set, the new process inherits a copy of the parent's name space;
otherwise the new process shares the parent's name space.
Is mutually exclusive with
.BR RFCNAMEG .
.TP
.B RFCNAMEG
If set, the new process starts with a clean name space. A new
name space must be built from a mount of an open file descriptor.
Is mutually exclusive with
.BR RFNAMEG .
.TP
.B RFNOMNT
If set, subsequent mounts into the new name space and dereferencing
of pathnames starting with
.B #
are disallowed.
.TP
.B RFENVG
If set, the environment variables are copied;
otherwise the two processes share environment variables.
Is mutually exclusive with
.BR RFCENVG .
.TP
.B RFCENVG
If set, the new process starts with an empty environment.
Is mutually exclusive with
.BR RFENVG .
.TP
.B RFNOTEG
Each process is a member of a group of processes that all
receive notes when a note is written to any of their
.B notepg
files (see
.IR proc (3)).
The group of a new process is by default the same as its parent, but if
.B RFNOTEG
is set (regardless of
.BR RFPROC ),
the process becomes the first in a new group, isolated from
previous processes.
.TP
.B RFFDG
If set, the invoker's file descriptor table (see
.IR intro (2))
is copied; otherwise the two processes share a
single table.
.TP
.B RFCFDG
If set, the new process starts with a clean file descriptor table.
Is mutually exclusive with
.BR RFFDG .
.TP
.B RFREND
If set, the process will be unable to
.IR rendezvous (2)
with any of its ancestors; its children will, however, be able to
.B rendezvous
with it. In effect,
.B RFREND
makes the process the first in a group of processes that share a space for
.B rendezvous
tags.
.TP
.B RFMEM
If set, the child and the parent will share
.B data
and
.B bss
segments.
Otherwise, the child inherits a copy of those segments.
Other segment types, in particular stack segments, will be unaffected.
May be set only with
.BR RFPROC .
.PD
.PP
File descriptors in a shared file descriptor table are kept
open until either they are explicitly closed
or all processes sharing the table exit.
.PP
If
.B RFPROC
is set, the
value returned in the parent process
is the process id
of the child process; the value returned in the child is zero.
Without
.BR RFPROC ,
the return value is zero.
Process ids range from 1 to the maximum integer
.RB ( int )
value.
.I Rfork
will sleep, if necessary, until required process resources are available.
.PP
.I Fork
is just a call of
.BR rfork(RFFDG|RFREND|RFPROC) .
.SH SOURCE
.B /sys/src/libc/9syscall
.br
.B /sys/src/libc/9sys/fork.c
.SH SEE ALSO
.IR intro (2),
.IR proc (3),
.SH DIAGNOSTICS
These functions set
.IR errstr .

362
man/man3/frame.3 Normal file
View File

@@ -0,0 +1,362 @@
.TH FRAME 3
.SH NAME
frinit, frsetrects, frinittick, frclear, frcharofpt, frptofchar, frinsert, frdelete, frselect, frtick, frselectpaint, frdrawsel, frdrawsel0, frgetmouse \- frames of text
.SH SYNOPSIS
.nf
.B
#include <u.h>
.B
#include <libc.h>
.B
#include <draw.h>
.B
#include <thread.h>
.B
#include <mouse.h>
.B
#include <frame.h>
.PP
.B
void frinit(Frame *f, Rectangle r, Font *ft, Image *b, Image **cols)
.PP
.B
void frsetrects(Frame *f, Rectangle r, Image *b)
.PP
.B
void frinittick(Frame *f)
.PP
.B
void frclear(Frame *f, int resize)
.PP
.B
ulong frcharofpt(Frame *f, Point pt)
.PP
.B
Point frptofchar(Frame *f, ulong p)
.PP
.B
void frinsert(Frame *f, Rune *r0, Rune *r1, ulong p)
.PP
.B
int frdelete(Frame *f, ulong p0, ulong p1)
.PP
.B
void frselect(Frame *f, Mousectl *m)
.PP
.B
void frtick(Frame *f, Point pt, int up)
.PP
.B
void frselectpaint(Frame *f, Point p0, Point p1, Image *col)
.PP
.B
void frdrawsel(Frame *f, Point pt0, ulong p0, ulong p1,
.B
int highlighted)
.PP
.B
void frdrawsel0(Frame *f, Point pt0, ulong p0, ulong p1,
.B
Image *back, Image *text)
.PP
.ft L
enum{
BACK,
HIGH,
BORD,
TEXT,
HTEXT,
NCOL
};
.fi
.SH DESCRIPTION
This library supports
.I frames
of editable text in a single font on raster displays, such as in
.IR sam (1)
and
.IR rio (1).
Frames may hold any character except NUL (0).
Long lines are folded and tabs are at fixed intervals.
.PP
The user-visible data structure, a
.BR Frame ,
is defined in
.BR <frame.h> :
.IP
.EX
.ta 6n +\w'Rectangle 'u +\w'lastlinefull; 'u
typedef struct Frame Frame;
struct Frame
{
Font *font; /* of chars in the frame */
Display *display; /* on which frame appears */
Image *b; /* on which frame appears */
Image *cols[NCOL]; /* text and background colors */
Rectangle r; /* in which text appears */
Rectangle entire; /* of full frame */
Frbox *box;
ulong p0, p1; /* selection */
ushort nbox, nalloc;
ushort maxtab; /* max size of tab, in pixels */
ushort nchars; /* # runes in frame */
ushort nlines; /* # lines with text */
ushort maxlines; /* total # lines in frame */
ushort lastlinefull; /* last line fills frame */
ushort modified; /* changed since frselect() */
Image *tick; /* typing tick */
Image *tickback; /* saved image under tick */
int ticked; /* flag: is tick onscreen? */
};
.EE
.PP
.B Frbox
is an internal type and is not used by the interface.
.B P0
and
.B p1
may be changed by the application provided the selection routines are called
afterwards to maintain a consistent display.
.I Maxtab
determines the size of tab stops.
.I Frinit
sets it to 8 times the width of a
.B 0
(zero)
character in the font;
it may be changed before any text is added to the frame.
The other elements of the structure are maintained by the library and
should not be modified directly.
.PP
The text within frames
is not directly addressable;
instead frames are designed to work alongside
another structure that holds the text.
The typical application is to display a section of a longer document such
as a text file or terminal session.
Usually the program will keep its own copy of the
text in the window (probably as
an array of
.BR Runes )
and pass components of this text to the frame routines to
display the visible portion.
Only the text that is visible is held by the
.BR Frame ;
the application must check
.BR maxlines ,
.BR nlines ,
and
.B lastlinefull
to determine, for example, whether new text needs to be appended
at the end of the
.B Frame
after calling
.I frdelete
(q.v.).
.PP
There are no routines in the library to allocate
.BR Frames ;
instead the interface assumes that
.B Frames
will be components of larger structures.
.I Frinit
prepares the
.B Frame
.I f
so characters drawn in it will appear
in the single
.B Font
.IR ft .
It then calls
.I frsetrects
and
.I frinittick
to initialize the geometry for the
.BR Frame .
The
.B Image
.I b
is where the
.B Frame
is to be drawn;
.B Rectangle
.I r
defines the limit of the portion of the
.B Image
the text will occupy.
The
.B Image
pointer
may be null, allowing the other routines to be called to maintain the
associated data structure in, for example, an obscured window.
.PP
The array of
.B Images
cols sets the colors in which text and borders will be drawn. The background of the frame will be drawn in
.BR cols[BACK] ;
the background of highlighted text in
.BR cols[HIGH] ;
borders and scroll bar in
.BR cols[BORD] ;
regular text in
.BR cols[TEXT] ;
and highlighted text in
.BR cols[HTEXT] .
.PP
.I Frclear
frees the internal structures associated with
.IR f ,
permitting another
.I frinit
or
.I frsetrects
on the
.BR Frame .
It does not clear the associated display.
If
.I f
is to be deallocated, the associated
.B Font
and
.B Image
must be freed separately.
The
.B resize
argument should be non-zero if the frame is to be redrawn with
a different font; otherwise the frame will maintain some
data structures associated with the font.
.PP
To resize a
.BR Frame ,
use
.I frclear
and
.I frinit
and then
.I frinsert
(q.v.) to recreate the display.
If a
.B Frame
is being moved but not resized, that is, if the shape of its containing
rectangle is unchanged, it is sufficient to use
.IR draw (2)
to copy the containing rectangle from the old to the new location and then call
.I frsetrects
to establish the new geometry.
(It is unnecessary to call
.I frinittick
unless the font size has changed.)
No redrawing is necessary.
.PP
.B Frames
hold text as runes,
not as bytes.
.I Frptofchar
returns the location of the upper left corner of the
.I p'th
rune, starting from 0, in the
.B Frame
.IR f .
If
.I f
holds fewer than
.I p
runes,
.I frptofchar
returns the location of the upper right corner of the last character in
.IR f .
.I Frcharofpt
is the inverse: it
returns the index of the closest rune whose image's upper left corner
is up and to the left of
.IR pt .
.PP
.I Frinsert
inserts into
.B Frame
.I f
starting at rune index
.I p
the runes between
.I r0
and
.IR r1 .
If a NUL (0) character
is inserted, chaos will ensue.
Tabs and newlines
are handled by the library, but all other characters,
including control characters, are just displayed.
For example, backspaces are printed; to erase
a character, use
.IR frdelete .
.PP
.I Frdelete
deletes from the
.B Frame
the text between
.I p0
and
.IR p1 ;
.I p1
points at the first rune beyond the deletion.
.PP
.I Frselect
tracks the mouse to select a contiguous string of text in the
.BR Frame .
When called, a mouse button is typically down.
.I Frselect
will return when the button state has changed (some buttons may
still be down) and will set
.IB f ->p0
and
.IB f ->p1
to the selected range of text.
.PP
Programs that wish to manage the selection themselves have several routines to help.
They involve the maintenance of the `tick', the vertical line indicating a null selection
between characters, and the colored region representing a non-null selection.
.I Frtick
draws (if
.I up
is non-zero) or removes (if
.I up
is zero) the tick at the screen position indicated by
.IR pt .
.I Frdrawsel
repaints a section of the frame, delimited by character positions
.I p0
and
.IR p1 ,
either with plain background or
entirely highlighted, according to the flag
.IR highlighted ,
managing the tick appropriately.
The point
.I pt0
is the geometrical location of
.I p0
on the screen; like all of the selection-helper routines'
.B Point
arguments, it must be a value generated by
.IR frptofchar .
.I Frdrawsel0
is a lower-level routine, taking as arguments a background color,
.IR back ,
and text color,
.IR text .
It assumes that the tick is being handled (removed beforehand, replaced afterwards, as required)
by its caller.
.I Frselectpaint
uses a solid color,
.IR col ,
to paint a region of the frame defined by the
.B Points
.I p0
and
.IR p1 .
.SH SOURCE
.B /sys/src/libframe
.SH SEE ALSO
.IR graphics (2),
.IR draw (2),
.IR cachechars (2).

44
man/man3/genrandom.3 Normal file
View File

@@ -0,0 +1,44 @@
.TH GENRANDOM 3
.SH NAME
genrandom, prng \- random number generation
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mp.h>
.br
.B #include <libsec.h>
.PP
.B
void genrandom(uchar *buf, int nbytes)
.PP
.B
void prng(uchar *buf, int nbytes)
.SH DESCRIPTION
.PP
Most security software requires a source of random or, at the
very least, unguessable numbers.
.PP
.I Genrandom
fills a buffer with bytes from the X9.17 pseudo-random
number generator. The X9.17 generator is seeded by 24
truly random bytes read from
.BR /dev/random .
.PP
.I Prng
uses the native
.IR rand (2)
pseudo-random number generator to fill the buffer. Used with
.IR srand ,
this function can produce a reproducible stream of pseudo random
numbers useful in testing.
.PP
Both functions may be passed to
.I mprand
(see
.IR mp (2)).
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2)

38
man/man3/getcallerpc.3 Normal file
View File

@@ -0,0 +1,38 @@
.TH GETCALLERPC 3
.SH NAME
getcallerpc \- fetch return PC of current function
.SH SYNOPSIS
.br
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B ulong getcallerpc(void *firstarg)
.SH DESCRIPTION
.I Getcallerpc
is a portable way to discover the PC to which the current function will return.
.I Firstarg
should be a pointer to the first argument to the function in question.
.SH EXAMPLE
.IP
.EX
void
printpc(ulong arg)
{
print("Called from %.8lux\en", getcallerpc(&arg));
}
void
main(int argc, char *argv[])
{
printpc(0);
printpc(0);
printpc(0);
}
.EE
.SH SOURCE
.B /sys/src/libc/$objtype/getcallerpc.[cs]
.SH BUGS
The
.I firstarg
parameter should not be necessary.

44
man/man3/getenv.3 Normal file
View File

@@ -0,0 +1,44 @@
.TH GETENV 3
.SH NAME
getenv, putenv \- access environment variables
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.nf
.B
char* getenv(char *name)
.br
.B
int putenv(char *name, char *val)
.fi
.SH DESCRIPTION
.I Getenv
reads the contents of
.BI /env/ name
(see
.IR env (3))
into memory allocated with
.IR malloc (2),
0-terminates it,
and returns a pointer to that area.
If no file exists, 0
is returned.
.PP
.I Putenv
creates the file
.BI /env/ name
and writes the string
.I val
to it. The terminating
.B 0
is not written.
If the file value cannot be written, \-1 is returned.
.SH SOURCE
.B /sys/src/libc/9sys
.SH SEE ALSO
.IR env (3)
.SH DIAGNOSTICS
Sets
.IR errstr .

125
man/man3/getfcr.3 Normal file
View File

@@ -0,0 +1,125 @@
.TH GETFCR 3
.SH NAME
getfcr, setfcr, getfsr, setfsr \- control floating point
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
ulong getfcr(void)
.PP
.B
void setfcr(ulong fcr)
.PP
.B
ulong getfsr(void)
.PP
.B
void setfsr(ulong fsr)
.SH DESCRIPTION
These routines provide a fairly portable interface to control the
rounding and exception characteristics of IEEE 754 floating point units.
In effect, they define a pair of pseudo-registers, the floating
point control register,
.BR fcr ,
which affects rounding, precision, and exceptions, and the
floating point status register,
.BR fsr ,
which holds the accrued exception bits.
Each register has a
.I get
routine to retrieve its value, a
.I set
routine to modify it,
and macros that identify its contents.
.PP
The
.B fcr
contains bits that, when set, halt execution upon exceptions:
.B FPINEX
(enable inexact exceptions),
.B FPOVFL
(enable overflow exceptions),
.B FPUNFL
(enable underflow exceptions),
.B FPZDIV
(enable zero divide exceptions), and
.B FPINVAL
(enable invalid operation exceptions).
Rounding is controlled by installing in
.BR fcr ,
under mask
.BR FPRMASK ,
one of the values
.B FPRNR
(round to nearest),
.B FPRZ
(round towards zero),
.B FPRPINF
(round towards positive infinity), and
.B FPRNINF
(round towards negative infinity).
Precision is controlled by installing in
.BR fcr ,
under mask
.BR FPPMASK ,
one of the values
.B FPPEXT
(extended precision),
.B FPPSGL
(single precision), and
.B FPPDBL
(double precision).
.PP
The
.B fsr
holds the accrued exception bits
.BR FPAINEX ,
.BR FPAOVFL ,
.BR FPAUNFL ,
.BR FPAZDIV ,
and
.BR FPAINVAL ,
corresponding to the
.B fsr
bits without the
.B A
in the name.
.PP
Not all machines support all modes. If the corresponding mask
is zero, the machine does not support the rounding or precision modes.
On some machines it is not possible to clear selective accrued
exception bits; a
.I setfsr
clears them all.
The exception bits defined here work on all architectures.
By default, the initial state is equivalent to
.IP
.EX
setfcr(FPPDBL|FPRNR|FPINVAL|FPZDIV|FPOVFL);
.EE
.PP
The default state of the floating point unit is fixed for a given
architecture but is undefined across Plan 9: the default is
to provide what the hardware does most efficiently.
Use these routines
if you need guaranteed behavior.
Also, gradual underflow is not available on some machines.
.SH EXAMPLE
To enable overflow traps and make sure registers are rounded
to double precision (for example on the MC68020, where the
internal registers are 80 bits long):
.EX
.IP
.ft L
ulong fcr;
fcr = getfcr();
fcr |= FPOVFL;
fcr &= ~FPPMASK;
fcr |= FPPDBL;
setfcr(fcr);
.ft
.EE
.SH SOURCE
.B /sys/src/libc/$objtype/getfcr.s

95
man/man3/getfields.3 Normal file
View File

@@ -0,0 +1,95 @@
.TH GETFIELDS 3
.SH NAME
getfields, gettokens, tokenize \- break a string into fields
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.ta \w'\fLchar* \fP'u
.B
int getfields(char *str, char **args, int maxargs, int multiflag,
.br
.B
char *delims)
.PP
.B
int gettokens(char *str, char **args, int maxargs, char *delims)
.PP
.B
int tokenize(char *str, char **args, int maxargs)
.SH DESCRIPTION
.I Getfields
places into the array
.I args
pointers to the first
.I maxargs
fields of the null terminated
.SM UTF
string
.IR str .
Delimiters between these fields are set to null.
.PP
Fields are substrings of
.I str
whose definition depends on the value of
.IR multiflag.
If
.I multiflag
is zero,
adjacent fields are separated by exactly one delimiter.
For example
.EX
getfields("#alice#bob##charles###", arg, 3, 0, "#");
.EE
yields three substrings:
null-string ,
.BR "alice" ,
and
.BR "bob##charles###" .
If the
.I multiflag
argument is not zero,
a field is a non-empty string of non-delimiters.
For example
.EX
getfields("#alice#bob##charles###", arg, 3, 1, "#");
.EE
yields the three substrings:
.BR "alice" ,
.BR "bob" ,
and
.BR "charles###" .
.PP
Getfields returns the number of fields pointed to.
.PP
.I Gettokens
is the same as
.I getfields
with
.I multiflag
non-zero,
except that fields may be quoted using single quotes, in the manner
of
.IR rc (1).
See
.IR quote (2)
for related quote-handling software.
.PP
.I Tokenize
is
.I gettokens
with
.I delims
set to \f5"\et\er\en "\fP.
.SH SOURCE
.B /sys/src/libc/port/tokenize.c
.SH SEE ALSO
.I strtok
in
.IR strcat (2),
.IR quote (2).

41
man/man3/getpid.3 Normal file
View File

@@ -0,0 +1,41 @@
.TH GETPID 3
.SH NAME
getpid, getppid \- get process ids
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int getpid(void)
.PP
.B
int getppid(void)
.SH DESCRIPTION
.I Getpid
reads
.B /dev/pid
(see
.IR cons (3))
and converts it to get the process id of the current process,
a number guaranteed to be unique among all running processes on the machine
executing
.IR getpid .
.PP
.I Getppid
reads
.B /dev/ppid
(see
.IR cons (3))
and converts it to get the id of the parent of the current process.
.SH SOURCE
.B /sys/src/libc/9sys
.SH SEE ALSO
.IR intro (2),
.IR cons (3),
.IR proc (3)
.SH DIAGNOSTICS
Returns 0 and
sets
.I errstr
if unsuccessful.

Some files were not shown because too many files have changed in this diff Show More