mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-27 11:52:03 +00:00
Add mkfile to keep indices up to date.
Remove man pages for things we don't provide.
This commit is contained in:
rsc
parent
058b0118a5
commit
a19c44b83b
18 changed files with 45 additions and 2321 deletions
104
man/man1/9nm.1
104
man/man1/9nm.1
|
|
@ -1,104 +0,0 @@
|
||||||
.TH 9NM 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 /usr/local/plan9/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
385
man/man1/9sed.1
|
|
@ -1,385 +0,0 @@
|
||||||
.TH SED 1
|
|
||||||
.SH NAME
|
|
||||||
9sed \- stream editor
|
|
||||||
.SH SYNOPSIS
|
|
||||||
.B 9sed
|
|
||||||
[
|
|
||||||
.B -n
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -g
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -e
|
|
||||||
.I script
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -f
|
|
||||||
.I sfile
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.I file ...
|
|
||||||
]
|
|
||||||
.SH DESCRIPTION
|
|
||||||
.I Sed
|
|
||||||
copies the named
|
|
||||||
.I files
|
|
||||||
(standard input default) to the standard output,
|
|
||||||
edited according to a script of commands.
|
|
||||||
The
|
|
||||||
.B -f
|
|
||||||
option causes the script to be taken from file
|
|
||||||
.IR sfile ;
|
|
||||||
these options accumulate.
|
|
||||||
If there is just one
|
|
||||||
.B -e
|
|
||||||
option and no
|
|
||||||
.BR -f 's,
|
|
||||||
the flag
|
|
||||||
.B -e
|
|
||||||
may be omitted.
|
|
||||||
The
|
|
||||||
.B -n
|
|
||||||
option suppresses the default output;
|
|
||||||
.B -g
|
|
||||||
causes all substitutions to be global, as if suffixed
|
|
||||||
.BR g .
|
|
||||||
.PP
|
|
||||||
A script consists of editing commands, one per line,
|
|
||||||
of the following form:
|
|
||||||
.IP
|
|
||||||
[\fIaddress\fR [\fL,\fI address\fR] ] \fIfunction\fR [\fIargument\fR ...]
|
|
||||||
.PP
|
|
||||||
In normal operation
|
|
||||||
.I sed
|
|
||||||
cyclically copies a line of input into a
|
|
||||||
.I pattern space
|
|
||||||
(unless there is something left after
|
|
||||||
a
|
|
||||||
.L D
|
|
||||||
command),
|
|
||||||
applies in sequence
|
|
||||||
all commands whose
|
|
||||||
.I addresses
|
|
||||||
select that pattern space,
|
|
||||||
and at the end of the script copies the pattern space
|
|
||||||
to the standard output (except under
|
|
||||||
.BR -n )
|
|
||||||
and deletes the pattern space.
|
|
||||||
.PP
|
|
||||||
An
|
|
||||||
.I address
|
|
||||||
is either a decimal number that counts
|
|
||||||
input lines cumulatively across files, a
|
|
||||||
.L $
|
|
||||||
that
|
|
||||||
addresses the last line of input, or a context address,
|
|
||||||
.BI / regular-expression / \f1,
|
|
||||||
in the style of
|
|
||||||
.IR regexp (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 /usr/local/plan9/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.
|
|
||||||
118
man/man1/tar.1
118
man/man1/tar.1
|
|
@ -1,118 +0,0 @@
|
||||||
.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 /usr/local/plan9/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.
|
|
||||||
|
|
@ -1,18 +0,0 @@
|
||||||
.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 /usr/local/plan9/src/libc/9sys/abort.c
|
|
||||||
|
|
@ -1,60 +0,0 @@
|
||||||
.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 (3)
|
|
||||||
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 /usr/local/plan9/src/libc/9sys/access.c
|
|
||||||
.SH SEE ALSO
|
|
||||||
.IR stat (3)
|
|
||||||
.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 (3)
|
|
||||||
to check simple existence.)
|
|
||||||
|
|
@ -1,25 +0,0 @@
|
||||||
.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 /usr/local/plan9/src/libc/port/_assert.c
|
|
||||||
160
man/man3/ctype.3
160
man/man3/ctype.3
|
|
@ -1,160 +0,0 @@
|
||||||
.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 (3).
|
|
||||||
.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 /usr/local/plan9/src/libc/port/ctype.c
|
|
||||||
.TP
|
|
||||||
.B /sys/include/ctype.h
|
|
||||||
for the macros.
|
|
||||||
.TP
|
|
||||||
.B /usr/local/plan9/src/libc/port/ctype.c
|
|
||||||
for the tables.
|
|
||||||
.SH "SEE ALSO
|
|
||||||
.IR isalpharune (3)
|
|
||||||
.SH BUGS
|
|
||||||
These macros are
|
|
||||||
.SM ASCII \c
|
|
||||||
-centric.
|
|
||||||
|
|
@ -1,125 +0,0 @@
|
||||||
.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 /usr/local/plan9/src/libc/$objtype/getfcr.s
|
|
||||||
|
|
@ -1,21 +0,0 @@
|
||||||
.TH HYPOT 3
|
|
||||||
.SH NAME
|
|
||||||
hypot \- Euclidean distance
|
|
||||||
.SH SYNOPSIS
|
|
||||||
.B #include <u.h>
|
|
||||||
.br
|
|
||||||
.B #include <libc.h>
|
|
||||||
.PP
|
|
||||||
.nf
|
|
||||||
.B
|
|
||||||
double hypot(double x, double y)
|
|
||||||
.fi
|
|
||||||
.SH DESCRIPTION
|
|
||||||
.I Hypot
|
|
||||||
returns
|
|
||||||
.EX
|
|
||||||
sqrt(x*x + y*y)
|
|
||||||
.EE
|
|
||||||
taking precautions against unwarranted overflows.
|
|
||||||
.SH SOURCE
|
|
||||||
.B /usr/local/plan9/src/libc/port/hypot.c
|
|
||||||
|
|
@ -1,40 +0,0 @@
|
||||||
.TH MKTEMP 3
|
|
||||||
.SH NAME
|
|
||||||
mktemp \- make a unique file name
|
|
||||||
.SH SYNOPSIS
|
|
||||||
.B #include <u.h>
|
|
||||||
.br
|
|
||||||
.B #include <libc.h>
|
|
||||||
.PP
|
|
||||||
.nf
|
|
||||||
.B
|
|
||||||
char* mktemp(char *template)
|
|
||||||
.fi
|
|
||||||
.SH DESCRIPTION
|
|
||||||
.I Mktemp
|
|
||||||
replaces
|
|
||||||
.I template
|
|
||||||
by a unique file name, and returns the
|
|
||||||
address of the template.
|
|
||||||
The template should look like a file name with eleven trailing
|
|
||||||
.LR X s.
|
|
||||||
The
|
|
||||||
.LR X s
|
|
||||||
are replaced by a letter followed by the current process id.
|
|
||||||
Letters from
|
|
||||||
.L a
|
|
||||||
to
|
|
||||||
.L z
|
|
||||||
are tried until a name that can be accessed
|
|
||||||
(see
|
|
||||||
.IR access (3))
|
|
||||||
is generated.
|
|
||||||
If no such name can be generated,
|
|
||||||
.I mktemp
|
|
||||||
returns
|
|
||||||
\f5"/"\f1 .
|
|
||||||
.SH SOURCE
|
|
||||||
.B /usr/local/plan9/src/libc/port/mktemp.c
|
|
||||||
.SH "SEE ALSO"
|
|
||||||
.IR getpid (3),
|
|
||||||
.IR access (3)
|
|
||||||
329
man/man3/pool.3
329
man/man3/pool.3
|
|
@ -1,329 +0,0 @@
|
||||||
.TH POOL 3
|
|
||||||
.SH NAME
|
|
||||||
poolalloc, poolfree, poolmsize, poolrealloc, poolcompact, poolcheck, poolblockcheck,
|
|
||||||
pooldump \- general memory management routines
|
|
||||||
.SH SYNOPSIS
|
|
||||||
.B #include <u.h>
|
|
||||||
.PP
|
|
||||||
.B #include <libc.h>
|
|
||||||
.PP
|
|
||||||
.B #include <pool.h>
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
void* poolalloc(Pool* pool, ulong size)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
void poolfree(Pool* pool, void* ptr)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
ulong poolmsize(Pool* pool, void* ptr)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
void* poolrealloc(Pool* pool, void* ptr, ulong size)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
void poolcompact(Pool* pool)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
void poolcheck(Pool *pool)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
void poolblockcheck(Pool *pool, void *ptr)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
void pooldump(Pool *pool);
|
|
||||||
.SH DESCRIPTION
|
|
||||||
These routines provide a general memory management facility.
|
|
||||||
Memory is retrieved from a coarser allocator (e.g.
|
|
||||||
.I sbrk
|
|
||||||
or the kernel's
|
|
||||||
.IR xalloc )
|
|
||||||
and then allocated to callers.
|
|
||||||
The routines are locked and thus may safely be used in
|
|
||||||
multiprocess programs.
|
|
||||||
.PP
|
|
||||||
.I Poolalloc
|
|
||||||
attempts to allocate a block of size
|
|
||||||
.BR size ;
|
|
||||||
it returns a pointer to the block when successful and nil otherwise.
|
|
||||||
The call
|
|
||||||
.B "poolalloc(0)
|
|
||||||
returns a non-nil pointer.
|
|
||||||
.I Poolfree
|
|
||||||
returns an allocated block to the pool.
|
|
||||||
It is an error to free a block more than once or to free a
|
|
||||||
pointer not returned by
|
|
||||||
.IR poolalloc .
|
|
||||||
The call
|
|
||||||
.B "poolfree(nil)
|
|
||||||
is legal and is a no-op.
|
|
||||||
.I Poolrealloc
|
|
||||||
attempts to resize to
|
|
||||||
.B nsize
|
|
||||||
bytes the block associated with
|
|
||||||
.BR ptr ,
|
|
||||||
which must have been previously returned by
|
|
||||||
.I poolalloc
|
|
||||||
or
|
|
||||||
.IR poolrealloc .
|
|
||||||
If the block's size can be adjusted, a (possibly different) pointer to the new block is returned.
|
|
||||||
The contents up to the lesser of the old and new sizes are unchanged.
|
|
||||||
After a successful call to
|
|
||||||
.IR poolrealloc ,
|
|
||||||
the return value should be used rather than
|
|
||||||
.B ptr
|
|
||||||
to access the block.
|
|
||||||
If the request cannot be satisfied,
|
|
||||||
.I poolrealloc
|
|
||||||
returns nil, and the old pointer remains valid.
|
|
||||||
.PP
|
|
||||||
When blocks are allocated, there is often some extra space left at the end
|
|
||||||
that would usually go unused.
|
|
||||||
.IR Poolmsize
|
|
||||||
grows the block to encompass this extra space and returns the new size.
|
|
||||||
.PP
|
|
||||||
The
|
|
||||||
.I poolblockcheck
|
|
||||||
and
|
|
||||||
.I poolcheck
|
|
||||||
routines validate a single allocated block or the entire pool, respectively.
|
|
||||||
They call
|
|
||||||
.B panic
|
|
||||||
(see below)
|
|
||||||
if corruption is detected.
|
|
||||||
.I Pooldump
|
|
||||||
prints a summary line for every block in the
|
|
||||||
pool, using the
|
|
||||||
.B print
|
|
||||||
function (see below).
|
|
||||||
.PP
|
|
||||||
The
|
|
||||||
.B Pool
|
|
||||||
structure itself provides much of the setup interface.
|
|
||||||
.IP
|
|
||||||
.EX
|
|
||||||
.ta \w'\fL 'u +\w'\fLulong 'u +\w'\fLlastcompact; 'u
|
|
||||||
typedef struct Pool Pool;
|
|
||||||
struct Pool {
|
|
||||||
char* name;
|
|
||||||
ulong maxsize; /* of entire Pool */
|
|
||||||
ulong cursize; /* of Pool */
|
|
||||||
ulong curfree; /* total free bytes in Pool */
|
|
||||||
ulong curalloc; /* total allocated bytes in Pool */
|
|
||||||
ulong minarena; /* smallest size of new arena */
|
|
||||||
ulong quantum; /* allocated blocks should be multiple of */
|
|
||||||
ulong minblock; /* smallest newly allocated block */
|
|
||||||
int flags;
|
|
||||||
int nfree; /* number of calls to free */
|
|
||||||
int lastcompact; /* nfree at time of last poolcompact */
|
|
||||||
void* (*alloc)(ulong);
|
|
||||||
int (*merge)(void*, void*);
|
|
||||||
void (*move)(void* from, void* to);
|
|
||||||
void (*lock)(Pool*);
|
|
||||||
void (*unlock)(Pool*);
|
|
||||||
void (*print)(Pool*, char*, ...);
|
|
||||||
void (*panic)(Pool*, char*, ...);
|
|
||||||
void (*logstack)(Pool*);
|
|
||||||
void* private;
|
|
||||||
};
|
|
||||||
.ta \w'\fL 'u +\w'POOL_ANTAGONISM 'u
|
|
||||||
enum { /* flags */
|
|
||||||
POOL_ANTAGONISM = 1<<0,
|
|
||||||
POOL_PARANOIA = 1<<1,
|
|
||||||
POOL_VERBOSITY = 1<<2,
|
|
||||||
POOL_DEBUGGING = 1<<3,
|
|
||||||
POOL_LOGGING = 1<<4,
|
|
||||||
POOL_TOLERANCE = 1<<5,
|
|
||||||
POOL_NOREUSE = 1<<6,
|
|
||||||
};
|
|
||||||
.EE
|
|
||||||
.PP
|
|
||||||
The pool obtains arenas of memory to manage by calling the the given
|
|
||||||
.B alloc
|
|
||||||
routine.
|
|
||||||
The total number of requested bytes will not exceed
|
|
||||||
.BR maxsize .
|
|
||||||
Each allocation request will be for at least
|
|
||||||
.B minarena
|
|
||||||
bytes.
|
|
||||||
.PP
|
|
||||||
When a new arena is allocated, the pool routines try to
|
|
||||||
merge it with the surrounding arenas, in an attempt to combat fragmentation.
|
|
||||||
If
|
|
||||||
.B merge
|
|
||||||
is non-nil, it is called with the addresses of two blocks from
|
|
||||||
.B alloc
|
|
||||||
that the pool routines suspect might be adjacent.
|
|
||||||
If they are not mergeable,
|
|
||||||
.B merge
|
|
||||||
must return zero.
|
|
||||||
If they are mergeable,
|
|
||||||
.B merge
|
|
||||||
should merge them into one block in its own bookkeeping
|
|
||||||
and return non-zero.
|
|
||||||
.PP
|
|
||||||
To ease fragmentation and make
|
|
||||||
block reuse easier, the sizes requested of the pool routines are rounded up to a multiple of
|
|
||||||
.B quantum
|
|
||||||
before
|
|
||||||
the carrying out requests.
|
|
||||||
If, after rounding, the block size is still less than
|
|
||||||
.B minblock
|
|
||||||
bytes,
|
|
||||||
.B minblock
|
|
||||||
will be used as the block size.
|
|
||||||
.PP
|
|
||||||
.I Poolcompact
|
|
||||||
defragments the pool, moving blocks in order to aggregate
|
|
||||||
the free space.
|
|
||||||
Each time it moves a block, it notifies the
|
|
||||||
.B move
|
|
||||||
routine that the contents have moved.
|
|
||||||
At the time that
|
|
||||||
.B move
|
|
||||||
is called, the contents have already moved,
|
|
||||||
so
|
|
||||||
.B from
|
|
||||||
should never be dereferenced.
|
|
||||||
If no
|
|
||||||
.B move
|
|
||||||
routine is supplied (i.e. it is nil), then calling
|
|
||||||
.I poolcompact
|
|
||||||
is a no-op.
|
|
||||||
.PP
|
|
||||||
When the pool routines need to allocate a new arena but cannot,
|
|
||||||
either because
|
|
||||||
.B alloc
|
|
||||||
has returned nil or because doing so would use more than
|
|
||||||
.B maxsize
|
|
||||||
bytes,
|
|
||||||
.I poolcompact
|
|
||||||
is called once to defragment the memory
|
|
||||||
and the request is retried.
|
|
||||||
.PP
|
|
||||||
.I Pools
|
|
||||||
are protected by the pool routines calling
|
|
||||||
.B lock
|
|
||||||
(when non-nil)
|
|
||||||
before modifying the pool, and
|
|
||||||
calling
|
|
||||||
.B unlock
|
|
||||||
when finished.
|
|
||||||
.PP
|
|
||||||
When internal corruption is detected,
|
|
||||||
.B panic
|
|
||||||
is called with a
|
|
||||||
.IR print (3)
|
|
||||||
style argument that specifies what happened.
|
|
||||||
It is assumed that
|
|
||||||
.B panic
|
|
||||||
never returns.
|
|
||||||
When the pool routines wish to convey a message
|
|
||||||
to the caller (usually because logging is turned on; see below),
|
|
||||||
.B print
|
|
||||||
is called, also with a
|
|
||||||
.IR print (3)
|
|
||||||
style argument.
|
|
||||||
.PP
|
|
||||||
.B Flags
|
|
||||||
is a bit vector that tweaks the behavior of the pool routines
|
|
||||||
in various ways.
|
|
||||||
Most are useful for debugging in one way or another.
|
|
||||||
When
|
|
||||||
.B POOL_ANTAGONISM
|
|
||||||
is set,
|
|
||||||
.I poolalloc
|
|
||||||
fills blocks with non-zero garbage before releasing them to the user,
|
|
||||||
and
|
|
||||||
.I poolfree
|
|
||||||
fills the blocks on receipt.
|
|
||||||
This tickles both user programs and the innards of the allocator.
|
|
||||||
Specifically, each 32-bit word of the memory is marked with a pointer value exclusive-or'ed
|
|
||||||
with a constant.
|
|
||||||
The pointer value is the pointer to the beginning of the allocated block
|
|
||||||
and the constant varies in order to distinguish different markings.
|
|
||||||
Freed blocks use the constant
|
|
||||||
.BR 0xF7000000 ,
|
|
||||||
newly allocated blocks
|
|
||||||
.BR 0xF9000000 ,
|
|
||||||
and newly created unallocated blocks
|
|
||||||
.BR 0xF1000000 .
|
|
||||||
For example, if
|
|
||||||
.B POOL_ANTAGONISM
|
|
||||||
is set and
|
|
||||||
.I poolalloc
|
|
||||||
returns a block starting at
|
|
||||||
.BR 0x00012345 ,
|
|
||||||
each word of the block will contain the value
|
|
||||||
.BR 0xF90012345 .
|
|
||||||
Recognizing these numbers in memory-related crashes can
|
|
||||||
help diagnose things like double-frees or dangling pointers.
|
|
||||||
.PP
|
|
||||||
Setting
|
|
||||||
.B POOL_PARANOIA
|
|
||||||
causes the allocator to walk the entire pool whenever locking or unlocking itself,
|
|
||||||
looking for corruption.
|
|
||||||
This slows runtime by a few orders of magnitude
|
|
||||||
when many blocks are in use.
|
|
||||||
If
|
|
||||||
.B POOL_VERBOSITY
|
|
||||||
is set,
|
|
||||||
the entire pool structure is printed
|
|
||||||
(via
|
|
||||||
.BR print )
|
|
||||||
each time the pool is locked or unlocked.
|
|
||||||
.B POOL_DEBUGGING
|
|
||||||
enables internal
|
|
||||||
debugging output,
|
|
||||||
whose format is unspecified and volatile.
|
|
||||||
It should not be used by most programs.
|
|
||||||
When
|
|
||||||
.B POOL_LOGGING
|
|
||||||
is set, a single line is printed via
|
|
||||||
.B print
|
|
||||||
at the beginning and end of each pool call.
|
|
||||||
If
|
|
||||||
.B logstack
|
|
||||||
is not nil,
|
|
||||||
it will be called as well.
|
|
||||||
This provides a mechanism for external programs to search for leaks.
|
|
||||||
(See
|
|
||||||
.IR leak (1)
|
|
||||||
for one such program.)
|
|
||||||
.PP
|
|
||||||
The pool routines are strict about the amount of space callers use.
|
|
||||||
If even a single byte is written past the end of the allotted space of a block, they
|
|
||||||
will notice when that block is next used in a call to
|
|
||||||
.I poolrealloc
|
|
||||||
or
|
|
||||||
.I free
|
|
||||||
(or at the next entry into the allocator, when
|
|
||||||
.B POOL_PARANOIA
|
|
||||||
is set),
|
|
||||||
and
|
|
||||||
.B panic
|
|
||||||
will be called.
|
|
||||||
Since forgetting to allocate space for the
|
|
||||||
terminating NUL on strings is such a common error,
|
|
||||||
if
|
|
||||||
.B POOL_TOLERANCE
|
|
||||||
is set and a single NUL is found written past the end of a block,
|
|
||||||
.B print
|
|
||||||
will be called with a notification, but
|
|
||||||
.B panic
|
|
||||||
will not be.
|
|
||||||
.PP
|
|
||||||
When
|
|
||||||
.B POOL_NOREUSE
|
|
||||||
is set,
|
|
||||||
.B poolfree
|
|
||||||
fills the passed block with garbage rather than
|
|
||||||
return it to the free pool.
|
|
||||||
.SH SOURCE
|
|
||||||
.B /usr/local/plan9/src/libc/port/pool.c
|
|
||||||
.SH SEE ALSO
|
|
||||||
.IR malloc (3),
|
|
||||||
.IR brk (3)
|
|
||||||
.PP
|
|
||||||
.B /usr/local/plan9/src/libc/port/malloc.c
|
|
||||||
is a complete example.
|
|
||||||
|
|
@ -1,82 +0,0 @@
|
||||||
.TH READV 3
|
|
||||||
.SH NAME
|
|
||||||
readv, writev, preadv, pwritev \- scatter/gather read and write
|
|
||||||
.SH SYNOPSIS
|
|
||||||
.B #include <u.h>
|
|
||||||
.br
|
|
||||||
.B #include <libc.h>
|
|
||||||
.PP
|
|
||||||
.nf
|
|
||||||
.ft L
|
|
||||||
typedef
|
|
||||||
struct IOchunk
|
|
||||||
{
|
|
||||||
void *addr;
|
|
||||||
ulong len;
|
|
||||||
} IOchunk;
|
|
||||||
.fi
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
long readv(int fd, IOchunk *io, int nio)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
long preadv(int fd, IOchunk *io, int nio, vlong off)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
long writev(int fd, IOchunk *io, int nio)
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
long pwritev(int fd, IOchunk *io, int nio, vlong off)
|
|
||||||
.SH DESCRIPTION
|
|
||||||
These functions supplement the standard read and write operations of
|
|
||||||
.IR read (3)
|
|
||||||
with facilities for scatter/gather I/O.
|
|
||||||
The set of I/O buffers is collected into an array of
|
|
||||||
.B IOchunk
|
|
||||||
structures passed as an argument.
|
|
||||||
.PP
|
|
||||||
.I Readv
|
|
||||||
reads data from
|
|
||||||
.I fd
|
|
||||||
and returns the total number of bytes received.
|
|
||||||
The received data is stored in the successive
|
|
||||||
.I nio
|
|
||||||
elements of the
|
|
||||||
.B IOchunk
|
|
||||||
array, storing
|
|
||||||
.IB io [0].len
|
|
||||||
bytes at
|
|
||||||
.IB io [0].addr\f1,
|
|
||||||
the next
|
|
||||||
.IB io [1].len
|
|
||||||
at
|
|
||||||
.IB io [1].addr\f1,
|
|
||||||
and so on.
|
|
||||||
.I Preadv
|
|
||||||
does the same, but implicitly seeks to I/O offset
|
|
||||||
.I off
|
|
||||||
by analogy with
|
|
||||||
.IR readv .
|
|
||||||
.PP
|
|
||||||
.I Writev
|
|
||||||
and
|
|
||||||
.I pwritev
|
|
||||||
are the analogous write routines.
|
|
||||||
.SH SOURCE
|
|
||||||
.B /usr/local/plan9/src/libc/9sys/readv.c
|
|
||||||
.br
|
|
||||||
.B /usr/local/plan9/src/libc/9sys/writev.c
|
|
||||||
.SH SEE ALSO
|
|
||||||
.IR intro (3),
|
|
||||||
.IR read (3)
|
|
||||||
.SH DIAGNOSTICS
|
|
||||||
These functions set
|
|
||||||
.IR errstr .
|
|
||||||
.SH BUGS
|
|
||||||
The implementations use
|
|
||||||
.IR malloc (3)
|
|
||||||
to build a single buffer for a standard call to
|
|
||||||
.B read
|
|
||||||
or
|
|
||||||
.BR write .
|
|
||||||
They are placeholders for possible future system calls.
|
|
||||||
|
|
@ -1,31 +0,0 @@
|
||||||
.TH REMOVE 3
|
|
||||||
.SH NAME
|
|
||||||
remove \- remove a file
|
|
||||||
.SH SYNOPSIS
|
|
||||||
.B #include <u.h>
|
|
||||||
.br
|
|
||||||
.B #include <libc.h>
|
|
||||||
.PP
|
|
||||||
.B
|
|
||||||
int remove(char *file)
|
|
||||||
.SH DESCRIPTION
|
|
||||||
.I Remove
|
|
||||||
removes
|
|
||||||
.I file
|
|
||||||
from the directory containing it and discards the contents of the file.
|
|
||||||
The user must have write permission in the containing directory.
|
|
||||||
If
|
|
||||||
.I file
|
|
||||||
is a directory, it must be empty.
|
|
||||||
.SH SOURCE
|
|
||||||
.B /usr/local/plan9/src/libc/9syscall
|
|
||||||
.SH SEE ALSO
|
|
||||||
.IR intro (3),
|
|
||||||
.IR remove (5),
|
|
||||||
the description of
|
|
||||||
.B ORCLOSE
|
|
||||||
in
|
|
||||||
.IR open (3).
|
|
||||||
.SH DIAGNOSTICS
|
|
||||||
Sets
|
|
||||||
.IR errstr .
|
|
||||||
|
|
@ -1,87 +0,0 @@
|
||||||
.TH VENTI.CONF 6
|
|
||||||
.SH NAME
|
|
||||||
venti.conf \- a venti configuration file
|
|
||||||
.SH DESCRIPTION
|
|
||||||
A venti configuration file enumerates the various index sections and
|
|
||||||
arenas that constitute a venti system.
|
|
||||||
The components are indicated by the name of the file, typically
|
|
||||||
a disk partition, in which they reside. The configuration
|
|
||||||
file is the only location that file names are used. Internally,
|
|
||||||
venti uses the names assigned when the components were formatted
|
|
||||||
with
|
|
||||||
.I fmtarenas
|
|
||||||
or
|
|
||||||
.I fmtisect
|
|
||||||
(see
|
|
||||||
.IR ventiaux (8)).
|
|
||||||
In particular, by changing the configuration a
|
|
||||||
component can be copied to a different file.
|
|
||||||
.PP
|
|
||||||
The configuration file consists of lines in the form described below.
|
|
||||||
Lines starting with
|
|
||||||
.B #
|
|
||||||
are comments.
|
|
||||||
.TP
|
|
||||||
.BI index " name
|
|
||||||
Names the index for the system.
|
|
||||||
.TP
|
|
||||||
.BI arenas " file
|
|
||||||
.I File
|
|
||||||
contains a collection of arenas, formatted using
|
|
||||||
.IR fmtarenas .
|
|
||||||
.TP
|
|
||||||
.BI isect " file
|
|
||||||
.I File
|
|
||||||
contains an index section, formatted using
|
|
||||||
.IR fmtisect .
|
|
||||||
.PP
|
|
||||||
After formatting a venti system using
|
|
||||||
.IR fmtindex ,
|
|
||||||
the order of arenas and index sections should not be changed.
|
|
||||||
Additional arenas can be appended to the configuration.
|
|
||||||
.PP
|
|
||||||
The configuration file optionally holds configuration parameters
|
|
||||||
for the venti server itself.
|
|
||||||
These are:
|
|
||||||
.TP
|
|
||||||
.BI mem " cachesize
|
|
||||||
.TP
|
|
||||||
.BI bcmem " blockcachesize
|
|
||||||
.TP
|
|
||||||
.BI icmem " indexcachesize
|
|
||||||
.TP
|
|
||||||
.BI addr " ventiaddress
|
|
||||||
.TP
|
|
||||||
.BI httpaddr " httpaddress
|
|
||||||
.TP
|
|
||||||
.B queuewrites
|
|
||||||
.PD
|
|
||||||
See
|
|
||||||
.IR venti (8)
|
|
||||||
for descriptions of these variables.
|
|
||||||
.SH EXAMPLE
|
|
||||||
.EX
|
|
||||||
# a sample venti configuration file
|
|
||||||
#
|
|
||||||
# formatted with
|
|
||||||
# venti/fmtarenas arena. /tmp/disks/arenas
|
|
||||||
# venti/fmtisect isect0 /tmp/disks/isect0
|
|
||||||
# venti/fmtisect isect1 /tmp/disks/isect1
|
|
||||||
# venti/fmtindex venti.conf
|
|
||||||
#
|
|
||||||
# server is started with
|
|
||||||
# venti/venti
|
|
||||||
|
|
||||||
# the name of the index
|
|
||||||
index main
|
|
||||||
|
|
||||||
# the index sections
|
|
||||||
isect /tmp/disks/isect0
|
|
||||||
isect /tmp/disks/isect1
|
|
||||||
|
|
||||||
# the arenas
|
|
||||||
arenas /tmp/disks/arenas
|
|
||||||
.EE
|
|
||||||
.SH "SEE ALSO"
|
|
||||||
.IR venti (8),
|
|
||||||
.IR ventiaux (8)
|
|
||||||
232
man/man8/venti.8
232
man/man8/venti.8
|
|
@ -1,232 +0,0 @@
|
||||||
.TH VENTI 8
|
|
||||||
.SH NAME
|
|
||||||
venti \- an archival block storage server
|
|
||||||
.SH SYNOPSIS
|
|
||||||
.B venti/venti
|
|
||||||
[
|
|
||||||
.B -dsw
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -a
|
|
||||||
.I ventiaddress
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -B
|
|
||||||
.I blockcachesize
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -c
|
|
||||||
.I config
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -C
|
|
||||||
.I cachesize
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -h
|
|
||||||
.I httpaddress
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -I
|
|
||||||
.I icachesize
|
|
||||||
]
|
|
||||||
.PP
|
|
||||||
.B venti/sync
|
|
||||||
[
|
|
||||||
.B -h
|
|
||||||
.I host
|
|
||||||
]
|
|
||||||
.SH DESCRIPTION
|
|
||||||
.I Venti
|
|
||||||
is a block storage server intended for archival data.
|
|
||||||
In a Venti server,
|
|
||||||
the SHA1 hash of a block's contents acts as the block
|
|
||||||
identifier for read and write operations.
|
|
||||||
This approach enforces a write-once policy, preventing accidental or
|
|
||||||
malicious destruction of data. In addition, duplicate copies of a
|
|
||||||
block are coalesced, reducing the consumption of storage and
|
|
||||||
simplifying the implementation of clients.
|
|
||||||
.PP
|
|
||||||
Storage for
|
|
||||||
.I venti
|
|
||||||
consists of a data log and an index, both of which
|
|
||||||
can be spread across multiple files.
|
|
||||||
The files containing the data log are themselves divided into self-contained sections called arenas.
|
|
||||||
Each arena contains a large number of data blocks and is sized to
|
|
||||||
facilitate operations such as copying to removable media.
|
|
||||||
The index provides a mapping between the a Sha1 fingerprint and
|
|
||||||
the location of the corresponding block in the data log.
|
|
||||||
.PP
|
|
||||||
The index and data log are typically stored on raw disk partitions.
|
|
||||||
To improve the robustness, the data log should be stored on
|
|
||||||
a device that provides RAID functionality. The index does
|
|
||||||
not require such protection, since if necessary, it can
|
|
||||||
can be regenerated from the data log.
|
|
||||||
The performance of
|
|
||||||
.I venti
|
|
||||||
is typically limited to the random access performance
|
|
||||||
of the index. This performance can be improved by spreading the
|
|
||||||
index accross multiple disks.
|
|
||||||
.PP
|
|
||||||
The storage for
|
|
||||||
.I venti
|
|
||||||
is initialized using
|
|
||||||
.IR fmtarenas ,
|
|
||||||
.IR fmtisect ,
|
|
||||||
and
|
|
||||||
.I fmtindex
|
|
||||||
(see
|
|
||||||
.IR ventiaux (8)).
|
|
||||||
A configuration file,
|
|
||||||
.IR venti.conf (6),
|
|
||||||
ties the index sections and data arenas together.
|
|
||||||
.PP
|
|
||||||
A Venti
|
|
||||||
server is accessed via an undocumented network protocol.
|
|
||||||
Two client applications are included in this distribution:
|
|
||||||
.IR vac (1)
|
|
||||||
and
|
|
||||||
.IR vacfs (4).
|
|
||||||
.I Vac
|
|
||||||
copies files from a Plan 9 file system to Venti, creating an
|
|
||||||
archive and returning the fingerprint of the root.
|
|
||||||
This archive can be mounted in Plan 9 using
|
|
||||||
.IR vacfs .
|
|
||||||
These two commands enable a rudimentary backup system.
|
|
||||||
A future release will include a Plan 9 file system that uses
|
|
||||||
Venti as a replacement for the WORM device of
|
|
||||||
.IR fs (4).
|
|
||||||
.PP
|
|
||||||
The
|
|
||||||
.I venti
|
|
||||||
server provides rudimentary status information via
|
|
||||||
a built-in http server. The URL files it serves are:
|
|
||||||
.TP
|
|
||||||
.B stats
|
|
||||||
Various internal statistics.
|
|
||||||
.TP
|
|
||||||
.B index
|
|
||||||
An enumeration of the index sections and all non empty arenas, including various statistics.
|
|
||||||
.TP
|
|
||||||
.B storage
|
|
||||||
A summary of the state of the data log.
|
|
||||||
.TP
|
|
||||||
.B xindex
|
|
||||||
An enumeration of the index sections and all non empty arenas, in XML format.
|
|
||||||
.PP
|
|
||||||
Several auxiliary utilities (see
|
|
||||||
.IR ventiaux (8))
|
|
||||||
aid in maintaining the storage for Venti.
|
|
||||||
With the exception of
|
|
||||||
.I rdarena ,
|
|
||||||
these utilities should generally be run after killing the
|
|
||||||
.I venti
|
|
||||||
server.
|
|
||||||
The utilities are:
|
|
||||||
.TP
|
|
||||||
.I checkarenas
|
|
||||||
Check the integrity, and optionally fix, Venti arenas.
|
|
||||||
.TP
|
|
||||||
.I checkindex
|
|
||||||
Check the integrity, and optionally fix, a Venti index.
|
|
||||||
.TP
|
|
||||||
.I buildindex
|
|
||||||
Rebuild a Venti index from scratch.
|
|
||||||
.TP
|
|
||||||
.I rdarena
|
|
||||||
Extract a Venti arena and write to standard output.
|
|
||||||
.PD
|
|
||||||
.PP
|
|
||||||
Options to
|
|
||||||
.I venti
|
|
||||||
are:
|
|
||||||
.TP
|
|
||||||
.BI -a " ventiaddress
|
|
||||||
The network address on which the server listens for incoming connections.
|
|
||||||
The default is
|
|
||||||
.LR tcp!*!venti .
|
|
||||||
.TP
|
|
||||||
.BI -B " blockcachesize
|
|
||||||
The size, in bytes, of memory allocated to caching raw disk blocks.
|
|
||||||
.TP
|
|
||||||
.BI -c " config
|
|
||||||
Specifies the
|
|
||||||
Venti
|
|
||||||
configuration file.
|
|
||||||
Defaults to
|
|
||||||
.LR venti.conf .
|
|
||||||
.TP
|
|
||||||
.BI -C " cachesize
|
|
||||||
The size, in bytes, of memory allocated to caching
|
|
||||||
Venti
|
|
||||||
blocks.
|
|
||||||
.TP
|
|
||||||
.BI -d
|
|
||||||
Produce various debugging information on standard error.
|
|
||||||
.TP
|
|
||||||
.BI -h " httpaddress
|
|
||||||
The network address of Venti's built-in
|
|
||||||
http
|
|
||||||
server.
|
|
||||||
The default is
|
|
||||||
.LR tcp!*!http .
|
|
||||||
.TP
|
|
||||||
.BI -I " icachesize
|
|
||||||
The size, in bytes, of memory allocated to caching the index mapping fingerprints
|
|
||||||
to locations in
|
|
||||||
.IR venti 's
|
|
||||||
data log.
|
|
||||||
.TP
|
|
||||||
.B -s
|
|
||||||
Do not run in the background.
|
|
||||||
Normally,
|
|
||||||
the foreground process will exit once the Venti server
|
|
||||||
is initialized and ready for connections.
|
|
||||||
.TP
|
|
||||||
.B -w
|
|
||||||
Enable write buffering. This option increase the performance of writes to
|
|
||||||
.I venti
|
|
||||||
at the cost of returning success to the client application before the
|
|
||||||
data has been written to disk.
|
|
||||||
The server implements a
|
|
||||||
.I sync
|
|
||||||
rpc that waits for completion of all the writes buffered at the time
|
|
||||||
the rpc was received.
|
|
||||||
Applications such as
|
|
||||||
.IR vac (1)
|
|
||||||
and the
|
|
||||||
.I sync
|
|
||||||
command described below
|
|
||||||
use this rpc to make sure that the data is correctly written to disk.
|
|
||||||
Use of this option is recommended.
|
|
||||||
.PD
|
|
||||||
.PP
|
|
||||||
The units for the various cache sizes above can be specified by appending a
|
|
||||||
.LR k ,
|
|
||||||
.LR m ,
|
|
||||||
or
|
|
||||||
.LR g
|
|
||||||
to indicate kilobytes, megabytes, or gigabytes respectively.
|
|
||||||
The command line options override options found in the
|
|
||||||
.IR venti.conf (6)
|
|
||||||
file.
|
|
||||||
.PP
|
|
||||||
.I Sync
|
|
||||||
connects to a running Venti server and executes a sync rpc
|
|
||||||
(described with the
|
|
||||||
.B -w
|
|
||||||
option above).
|
|
||||||
If sync exits successfully, it means that all writes buffered at the
|
|
||||||
time the command was issued are now on disk.
|
|
||||||
.SH SOURCE
|
|
||||||
.B /sys/src/cmd/venti
|
|
||||||
.SH "SEE ALSO"
|
|
||||||
.IR venti.conf (6),
|
|
||||||
.IR ventiaux (8),
|
|
||||||
.IR vac (1),
|
|
||||||
.IR vacfs (4).
|
|
||||||
.br
|
|
||||||
Sean Quinlan and Sean Dorward,
|
|
||||||
``Venti: a new approach to archival storage'',
|
|
||||||
.I "Usenix Conference on File and Storage Technologies" ,
|
|
||||||
2002.
|
|
||||||
|
|
@ -1,504 +0,0 @@
|
||||||
.TH VENTIAUX 8
|
|
||||||
.SH NAME
|
|
||||||
buildindex,
|
|
||||||
checkarenas,
|
|
||||||
checkindex,
|
|
||||||
conf,
|
|
||||||
copy,
|
|
||||||
fmtarenas,
|
|
||||||
fmtindex,
|
|
||||||
fmtisect,
|
|
||||||
rdarena,
|
|
||||||
rdarenablocks,
|
|
||||||
read,
|
|
||||||
wrarenablocks,
|
|
||||||
write \- Venti maintenance and debugging commands
|
|
||||||
.SH SYNOPSIS
|
|
||||||
.B venti/buildindex
|
|
||||||
[
|
|
||||||
.B -B
|
|
||||||
.I blockcachesize
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -Z
|
|
||||||
]
|
|
||||||
.I venti.config
|
|
||||||
.I tmp
|
|
||||||
.PP
|
|
||||||
.B venti/checkarenas
|
|
||||||
[
|
|
||||||
.B -afv
|
|
||||||
]
|
|
||||||
.I file
|
|
||||||
.PP
|
|
||||||
.B venti/checkindex
|
|
||||||
[
|
|
||||||
.B -f
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -B
|
|
||||||
.I blockcachesize
|
|
||||||
]
|
|
||||||
.I venti.config
|
|
||||||
.I tmp
|
|
||||||
.PP
|
|
||||||
.B venti/conf
|
|
||||||
[
|
|
||||||
.B -w
|
|
||||||
]
|
|
||||||
.I partition
|
|
||||||
[
|
|
||||||
.I configfile
|
|
||||||
]
|
|
||||||
.PP
|
|
||||||
.B venti/copy
|
|
||||||
[
|
|
||||||
.B -f
|
|
||||||
]
|
|
||||||
.I src
|
|
||||||
.I dst
|
|
||||||
.I score
|
|
||||||
[
|
|
||||||
.I type
|
|
||||||
]
|
|
||||||
.PP
|
|
||||||
.B venti/fmtarenas
|
|
||||||
[
|
|
||||||
.B -Z
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -a
|
|
||||||
.I arenasize
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -b
|
|
||||||
.I blocksize
|
|
||||||
]
|
|
||||||
.I name
|
|
||||||
.I file
|
|
||||||
.PP
|
|
||||||
.B venti/fmtindex
|
|
||||||
[
|
|
||||||
.B -a
|
|
||||||
]
|
|
||||||
.I venti.config
|
|
||||||
.PP
|
|
||||||
.B venti/fmtisect
|
|
||||||
[
|
|
||||||
.B -Z
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -b
|
|
||||||
.I blocksize
|
|
||||||
]
|
|
||||||
.I name
|
|
||||||
.I file
|
|
||||||
.PP
|
|
||||||
.B venti/rdarena
|
|
||||||
[
|
|
||||||
.B -v
|
|
||||||
]
|
|
||||||
.I arenapart
|
|
||||||
.I arenaname
|
|
||||||
.PP
|
|
||||||
.B venti/read
|
|
||||||
[
|
|
||||||
.B -h
|
|
||||||
.I host
|
|
||||||
]
|
|
||||||
.I score
|
|
||||||
[
|
|
||||||
.I type
|
|
||||||
]
|
|
||||||
.PP
|
|
||||||
.B venti/wrarena
|
|
||||||
[
|
|
||||||
.B -o
|
|
||||||
.I fileoffset
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -h
|
|
||||||
.I host
|
|
||||||
]
|
|
||||||
.I arenafile
|
|
||||||
[
|
|
||||||
.I clumpoffset
|
|
||||||
]
|
|
||||||
.PP
|
|
||||||
.B venti/write
|
|
||||||
[
|
|
||||||
.B -h
|
|
||||||
.I host
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -t
|
|
||||||
.I type
|
|
||||||
]
|
|
||||||
[
|
|
||||||
.B -z
|
|
||||||
]
|
|
||||||
.SH DESCRIPTION
|
|
||||||
These commands aid in the setup, maintenance, and debugging of
|
|
||||||
Venti servers.
|
|
||||||
See
|
|
||||||
.IR venti (8)
|
|
||||||
and
|
|
||||||
.IR venti.conf (6)
|
|
||||||
for an overview of the data structures stored by Venti.
|
|
||||||
.PP
|
|
||||||
Note that the units for the various sizes in the following
|
|
||||||
commands can be specified by appending
|
|
||||||
.LR k ,
|
|
||||||
.LR m ,
|
|
||||||
or
|
|
||||||
.LR g
|
|
||||||
to indicate kilobytes, megabytes, or gigabytes respectively.
|
|
||||||
.PP
|
|
||||||
.I Buildindex
|
|
||||||
populates the index for the Venti system described in
|
|
||||||
.IR venti.config .
|
|
||||||
The index must have previously been formatted using
|
|
||||||
.IR fmtindex .
|
|
||||||
This command is typically used to build a new index for a Venti
|
|
||||||
system when the old index becomes too small, or to rebuild
|
|
||||||
an index after media failure.
|
|
||||||
Small errors in an index can usually be fixed with
|
|
||||||
.IR checkindex .
|
|
||||||
.PP
|
|
||||||
The
|
|
||||||
.I tmp
|
|
||||||
file, usually a disk partition, must be large enough to store a copy of the index.
|
|
||||||
This temporary space is used to perform a merge sort of index entries
|
|
||||||
generated by reading the arenas.
|
|
||||||
.PP
|
|
||||||
Options to
|
|
||||||
.I buildindex
|
|
||||||
are:
|
|
||||||
.TP
|
|
||||||
.BI -B " blockcachesize
|
|
||||||
The amount of memory, in bytes, to use for caching raw disk accesses while running
|
|
||||||
.IR buildindex .
|
|
||||||
(This is not a property of the created index.)
|
|
||||||
The default is 8k.
|
|
||||||
.TP
|
|
||||||
.B -Z
|
|
||||||
Do not zero the index.
|
|
||||||
This option should only be used when it is known that the index was already zeroed.
|
|
||||||
.PD
|
|
||||||
.PP
|
|
||||||
.I Checkarenas
|
|
||||||
examines the Venti arenas contained in the given
|
|
||||||
.IR file .
|
|
||||||
The program detects various error conditions, and optionally attempts
|
|
||||||
to fix any errors that are found.
|
|
||||||
.PP
|
|
||||||
Options to
|
|
||||||
.I checkarenas
|
|
||||||
are:
|
|
||||||
.TP
|
|
||||||
.B -a
|
|
||||||
For each arena, scan the entire data section.
|
|
||||||
If this option is omitted, only the end section of
|
|
||||||
the arena is examined.
|
|
||||||
.TP
|
|
||||||
.B -f
|
|
||||||
Attempt to fix any errors that are found.
|
|
||||||
.TP
|
|
||||||
.B -v
|
|
||||||
Increase the verbosity of output.
|
|
||||||
.PD
|
|
||||||
.PP
|
|
||||||
.I Checkindex
|
|
||||||
examines the Venti index described in
|
|
||||||
.IR venti.config .
|
|
||||||
The program detects various error conditions including:
|
|
||||||
blocks that are not indexed, index entries for blocks that do not exist,
|
|
||||||
and duplicate index entries.
|
|
||||||
If requested, an attempt can be made to fix errors that are found.
|
|
||||||
.PP
|
|
||||||
The
|
|
||||||
.I tmp
|
|
||||||
file, usually a disk partition, must be large enough to store a copy of the index.
|
|
||||||
This temporary space is used to perform a merge sort of index entries
|
|
||||||
generated by reading the arenas.
|
|
||||||
.PP
|
|
||||||
Options to
|
|
||||||
.I checkindex
|
|
||||||
are:
|
|
||||||
.TP
|
|
||||||
.BI -B " blockcachesize
|
|
||||||
The amount of memory, in bytes, to use for caching raw disk accesses while running
|
|
||||||
.IR checkindex .
|
|
||||||
The default is 8k.
|
|
||||||
.TP
|
|
||||||
.B -f
|
|
||||||
Attempt to fix any errors that are found.
|
|
||||||
.PD
|
|
||||||
.PP
|
|
||||||
.I Fmtarenas
|
|
||||||
formats the given
|
|
||||||
.IR file ,
|
|
||||||
typically a disk partition, into a number of
|
|
||||||
Venti
|
|
||||||
arenas.
|
|
||||||
The arenas are given names of the form
|
|
||||||
.IR name%d ,
|
|
||||||
where
|
|
||||||
.I %d
|
|
||||||
is replaced with a sequential number starting at 0.
|
|
||||||
.PP
|
|
||||||
Options to
|
|
||||||
.I fmtarenas
|
|
||||||
are:
|
|
||||||
.TP
|
|
||||||
.BI -a " arenasize
|
|
||||||
The arenas are of
|
|
||||||
.I arenasize
|
|
||||||
bytes. The default is 512 megabytes, which was selected to provide a balance
|
|
||||||
between the number of arenas and the ability to copy an arena to external
|
|
||||||
media such as recordable CDs and tapes.
|
|
||||||
.TP
|
|
||||||
.BI -b " blocksize
|
|
||||||
The size, in bytes, for read and write operations to the file.
|
|
||||||
The size is recorded in the file, and is used by applications that access the arenas.
|
|
||||||
The default is 8k.
|
|
||||||
.TP
|
|
||||||
.B -Z
|
|
||||||
Do not zero the data sections of the arenas.
|
|
||||||
Using this option reduces the formatting time
|
|
||||||
but should only be used when it is known that the file was already zeroed.
|
|
||||||
.PD
|
|
||||||
.I Fmtindex
|
|
||||||
takes the
|
|
||||||
.IR venti.conf (6)
|
|
||||||
file
|
|
||||||
.I venti.config
|
|
||||||
and initializes the index sections to form a usable index structure.
|
|
||||||
The arena files and index sections must have previously been formatted
|
|
||||||
using
|
|
||||||
.I fmtarenas
|
|
||||||
and
|
|
||||||
.I fmtisect
|
|
||||||
respectively.
|
|
||||||
.PP
|
|
||||||
The function of a Venti index is to map a SHA1 fingerprint to a location
|
|
||||||
in the data section of one of the arenas. The index is composed of
|
|
||||||
blocks, each of which contains the mapping for a fixed range of possible
|
|
||||||
fingerprint values.
|
|
||||||
.I Fmtindex
|
|
||||||
determines the mapping between SHA1 values and the blocks
|
|
||||||
of the collection of index sections. Once this mapping has been determined,
|
|
||||||
it cannot be changed without rebuilding the index.
|
|
||||||
The basic assumption in the current implementation is that the index
|
|
||||||
structure is sufficiently empty that individual blocks of the index will rarely
|
|
||||||
overflow. The total size of the index should be about 2% to 10% of
|
|
||||||
the total size of the arenas, but the exact depends both the index block size
|
|
||||||
and the compressed size of block stored to Venti.
|
|
||||||
.PP
|
|
||||||
.I Fmtindex
|
|
||||||
also computes a mapping between a linear address space and
|
|
||||||
the data section of the collection of arenas. The
|
|
||||||
.B -a
|
|
||||||
option can be used to add additional arenas to an index.
|
|
||||||
To use this feature,
|
|
||||||
add the new arenas to
|
|
||||||
.I venti.config
|
|
||||||
after the existing arenas and then run
|
|
||||||
.I fmtindex
|
|
||||||
.BR -a .
|
|
||||||
.PP
|
|
||||||
A copy of the above mappings is stored in the header for each of the index sections.
|
|
||||||
These copies enable
|
|
||||||
.I buildindex
|
|
||||||
to restore a single index section without rebuilding the entire index.
|
|
||||||
.PP
|
|
||||||
.I Fmtisect
|
|
||||||
formats the given
|
|
||||||
.IR file ,
|
|
||||||
typically a disk partition, as a Venti index section with the specified
|
|
||||||
.IR name .
|
|
||||||
One or more formatted index sections are combined into a Venti
|
|
||||||
index using
|
|
||||||
.IR fmtindex .
|
|
||||||
Each of the index sections within an index must have a unique name.
|
|
||||||
.PP
|
|
||||||
Options to
|
|
||||||
.I fmtisect
|
|
||||||
are:
|
|
||||||
.TP
|
|
||||||
.BI -b " blocksize
|
|
||||||
The size, in bytes, for read and write operations to the file.
|
|
||||||
All the index sections within a index must have the same block size.
|
|
||||||
The default is 8k.
|
|
||||||
.TP
|
|
||||||
.B -Z
|
|
||||||
Do not zero the index.
|
|
||||||
Using this option reduces the formatting time
|
|
||||||
but should only be used when it is known that the file was already zeroed.
|
|
||||||
.PD
|
|
||||||
.PP
|
|
||||||
.I Rdarena
|
|
||||||
extracts the named
|
|
||||||
.I arena
|
|
||||||
from the arena partition
|
|
||||||
.I arenapart
|
|
||||||
and writes this arena to standard output.
|
|
||||||
This command is typically used to back up an arena to external media.
|
|
||||||
The
|
|
||||||
.B -v
|
|
||||||
option generates more verbose output on standard error.
|
|
||||||
.PP
|
|
||||||
.I Wrarena
|
|
||||||
writes the blocks contained in the arena
|
|
||||||
.I arenafile
|
|
||||||
(typically, the output of
|
|
||||||
.IR rdarena )
|
|
||||||
to a Venti server.
|
|
||||||
It is typically used to reinitialize a Venti server from backups of the arenas.
|
|
||||||
For example,
|
|
||||||
.IP
|
|
||||||
.EX
|
|
||||||
venti/rdarena /dev/sdC0/arenas arena.0 >external.media
|
|
||||||
venti/wrarena -h venti2 external.media
|
|
||||||
.EE
|
|
||||||
.LP
|
|
||||||
writes the blocks contained in
|
|
||||||
.B arena.0
|
|
||||||
to the Venti server
|
|
||||||
.B venti2
|
|
||||||
(typically not the one using
|
|
||||||
.BR /dev/sdC0/arenas ).
|
|
||||||
.PP
|
|
||||||
The
|
|
||||||
.B -o
|
|
||||||
option specifies that the arena starts at byte
|
|
||||||
.I fileoffset
|
|
||||||
(default
|
|
||||||
.BR 0 )
|
|
||||||
in
|
|
||||||
.I arenafile .
|
|
||||||
This is useful for reading directly from
|
|
||||||
the Venti arena partition:
|
|
||||||
.IP
|
|
||||||
.EX
|
|
||||||
venti/wrarena -h venti2 -o 335872 /dev/sdC0/arenas
|
|
||||||
.EE
|
|
||||||
.LP
|
|
||||||
(In this example, 335872 is the offset shown in the Venti
|
|
||||||
server's index list (344064) minus one block (8192).
|
|
||||||
You will need to substitute your own arena offsets
|
|
||||||
and block size.)
|
|
||||||
.PP
|
|
||||||
Finally, the optional
|
|
||||||
.I offset
|
|
||||||
argument specifies that the writing should begin with the
|
|
||||||
clump starting at
|
|
||||||
.I offset
|
|
||||||
within the arena.
|
|
||||||
.I Wrarena
|
|
||||||
prints the offset it stopped at (because there were no more data blocks).
|
|
||||||
This could be used to incrementally back up a Venti server
|
|
||||||
to another Venti server:
|
|
||||||
.IP
|
|
||||||
.EX
|
|
||||||
last=`{cat last}
|
|
||||||
venti/wrarena -h venti2 -o 335872 /dev/sdC0/arenas $last >output
|
|
||||||
awk '/^end offset/ { print $3 }' offset >last
|
|
||||||
.EE
|
|
||||||
.LP
|
|
||||||
Of course, one would need to add wrapper code to keep track
|
|
||||||
of which arenas have been processed.
|
|
||||||
See
|
|
||||||
.B /sys/src/cmd/venti/backup.example
|
|
||||||
for a version that does this.
|
|
||||||
.PP
|
|
||||||
.I Read
|
|
||||||
and
|
|
||||||
.I write
|
|
||||||
read and write blocks from a running Venti server.
|
|
||||||
They are intended to ease debugging of the server.
|
|
||||||
The default
|
|
||||||
.I host
|
|
||||||
is the environment variable
|
|
||||||
.BR $venti ,
|
|
||||||
followed by the network metaname
|
|
||||||
.BR $venti .
|
|
||||||
The
|
|
||||||
.I type
|
|
||||||
is the decimal type of block to be read or written.
|
|
||||||
If no
|
|
||||||
.I type
|
|
||||||
is specified for
|
|
||||||
.I read ,
|
|
||||||
all types are tried, and a command-line is printed to
|
|
||||||
show the type that eventually worked.
|
|
||||||
If no
|
|
||||||
.I type
|
|
||||||
is specified for
|
|
||||||
.I write ,
|
|
||||||
.B VtDataType
|
|
||||||
(13)
|
|
||||||
is used.
|
|
||||||
.I Read
|
|
||||||
reads the block named by
|
|
||||||
.I score
|
|
||||||
(a SHA1 hash)
|
|
||||||
from the Venti server and writes it to standard output.
|
|
||||||
.I Write
|
|
||||||
reads a block from standard input and attempts to write
|
|
||||||
it to the Venti server.
|
|
||||||
If successful, it prints the score of the block on the server.
|
|
||||||
.PP
|
|
||||||
.I Copy
|
|
||||||
walks the entire tree of blocks rooted at
|
|
||||||
.I score ,
|
|
||||||
copying all the blocks visited during the walk from
|
|
||||||
the Venti server at network address
|
|
||||||
.I src
|
|
||||||
to the Venti server at network address
|
|
||||||
.I dst .
|
|
||||||
If
|
|
||||||
.I type
|
|
||||||
(a decimal block type for
|
|
||||||
.IR score )
|
|
||||||
is omitted, all types will be tried in sequence
|
|
||||||
until one is found that works.
|
|
||||||
The
|
|
||||||
.B -f
|
|
||||||
flag runs the copy in ``fast'' mode: if a block is already on
|
|
||||||
.IR dst ,
|
|
||||||
the walk does not descend below it, on the assumption that all its
|
|
||||||
children are also already on
|
|
||||||
.IR dst .
|
|
||||||
Without this flag, the copy often transfers many times more
|
|
||||||
data than necessary.
|
|
||||||
.PP
|
|
||||||
To make it easier to bootstrap servers, the configuration
|
|
||||||
file can be stored at the beginning of any Venti partitions using
|
|
||||||
.IR conf .
|
|
||||||
A partition so branded with a configuration file can
|
|
||||||
be used in place of a configuration file when invoking any
|
|
||||||
of the venti commands.
|
|
||||||
By default,
|
|
||||||
.I conf
|
|
||||||
prints the configuration stored in
|
|
||||||
.IR partition .
|
|
||||||
When invoked with the
|
|
||||||
.B -w
|
|
||||||
flag,
|
|
||||||
.I conf
|
|
||||||
reads a configuration file from
|
|
||||||
.I configfile
|
|
||||||
(or else standard input)
|
|
||||||
and stores it in
|
|
||||||
.IR partition .
|
|
||||||
.SH SOURCE
|
|
||||||
.B /sys/src/cmd/venti
|
|
||||||
.SH "SEE ALSO"
|
|
||||||
.IR venti (8),
|
|
||||||
.IR venti.conf (6)
|
|
||||||
.SH BUGS
|
|
||||||
.I Buildindex
|
|
||||||
should allow an individual index section to be rebuilt.
|
|
||||||
The merge sort could be performed in the space used to store the
|
|
||||||
index rather than requiring a temporary file.
|
|
||||||
8
man/mkfile
Normal file
8
man/mkfile
Normal file
|
|
@ -0,0 +1,8 @@
|
||||||
|
LIB=$PLAN9/lib
|
||||||
|
|
||||||
|
indices:V:
|
||||||
|
for i in man*
|
||||||
|
do
|
||||||
|
./secindex $i > $i/INDEX
|
||||||
|
done
|
||||||
|
|
||||||
37
man/secindex
Executable file
37
man/secindex
Executable file
|
|
@ -0,0 +1,37 @@
|
||||||
|
#!/usr/local/plan9/bin/rc
|
||||||
|
builtin cd $1
|
||||||
|
for (i in [a-z0-9:]*) {
|
||||||
|
b=`{echo $i | sed 's/\..*//'}
|
||||||
|
9sed -n '
|
||||||
|
/SH *NAM/,/SH/{
|
||||||
|
/SH/d
|
||||||
|
s/, *$//
|
||||||
|
ty
|
||||||
|
:y
|
||||||
|
s/ *\\*-.*//
|
||||||
|
tx
|
||||||
|
s/ *\\\(mi.*//
|
||||||
|
tx
|
||||||
|
s/, */\
|
||||||
|
/g
|
||||||
|
s/\n\\n/\
|
||||||
|
/g
|
||||||
|
s/$/ '$i'/g
|
||||||
|
p
|
||||||
|
}
|
||||||
|
/SH *DES/q
|
||||||
|
d
|
||||||
|
:x
|
||||||
|
s/ *\\*-.*//
|
||||||
|
s/ *\\\(mi.*//
|
||||||
|
/^$/d
|
||||||
|
s/, */\
|
||||||
|
/g
|
||||||
|
s/\n\n/\
|
||||||
|
/g
|
||||||
|
s/$/ '$i'/g
|
||||||
|
p
|
||||||
|
q
|
||||||
|
' $i
|
||||||
|
echo $b $i
|
||||||
|
} |sort -u
|
||||||
Loading…
Reference in a new issue