commit - 058b0118a52061ad57694c01fc8763b22b789c4d
commit + a19c44b83b96fefad131ef324c3eb2916e8c604c
blob - 5841043c272bb0d5735fc7926e15c9dc94c3d3c4 (mode 644)
blob + /dev/null
--- man/man1/9nm.1
+++ /dev/null
-.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)
-
blob - 2f4345ca890e00b4e28da443e1679bcd007bb826 (mode 644)
blob + /dev/null
--- man/man1/9sed.1
+++ /dev/null
-.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.
blob - 00ac041417e15a6bf0dd46f348e4993e0f737df9 (mode 644)
blob + /dev/null
--- man/man1/tar.1
+++ /dev/null
-.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.
blob - 2615f5b52d6444151d09159c1925e3c48c06a450 (mode 644)
blob + /dev/null
--- man/man3/abort.3
+++ /dev/null
-.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
blob - d98d88a5e17ac05644baaadfc4a935ad5b483995 (mode 644)
blob + /dev/null
--- man/man3/access.3
+++ /dev/null
-.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.)
blob - 82c43d08305927c6976de2abbbac6a29c7ec20bd (mode 644)
blob + /dev/null
--- man/man3/assert.3
+++ /dev/null
-.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
blob - bb3f3327fa6b31131acd1d63452b0657655b2f19 (mode 644)
blob + /dev/null
--- man/man3/ctype.3
+++ /dev/null
-.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.
blob - 577180a73db30f2e82761efc12c74c327dcaf5b3 (mode 644)
blob + /dev/null
--- man/man3/getfcr.3
+++ /dev/null
-.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
blob - a539c72ed79552ac108f790dfa554894db885c3f (mode 644)
blob + /dev/null
--- man/man3/hypot.3
+++ /dev/null
-.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
blob - 9ab13cba948b89dc66aee75ef1dbc53e53b6fdcd (mode 644)
blob + /dev/null
--- man/man3/mktemp.3
+++ /dev/null
-.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)
blob - 12be5792fa789adfddd7a75441d0a9b8ad2aabda (mode 644)
blob + /dev/null
--- man/man3/pool.3
+++ /dev/null
-.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.
blob - d74957e3ef64739578de4c779709b9a11f7dbb73 (mode 644)
blob + /dev/null
--- man/man3/readv.3
+++ /dev/null
-.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.
blob - ff195b9325eb2a44bc0baacd45f8958179a3e64a (mode 644)
blob + /dev/null
--- man/man3/remove.3
+++ /dev/null
-.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 .
blob - d08aca3bb29e2130291ff48c7dd84c923f7acc85 (mode 644)
blob + /dev/null
--- man/man5/venti.conf.5
+++ /dev/null
-.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)
blob - be112a6af8d98fa97a344b21fb207976ea59e259 (mode 644)
blob + /dev/null
--- man/man8/venti.8
+++ /dev/null
-.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.
blob - fb6d852271223dfde1b6923f26db4f68da2c6d4c (mode 644)
blob + /dev/null
--- man/man8/ventiaux.8
+++ /dev/null
-.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.
blob - /dev/null
blob + cbe71705d85e51860f6c15c753675df4c1bc1bd8 (mode 644)
--- /dev/null
+++ man/mkfile
+LIB=$PLAN9/lib
+
+indices:V:
+ for i in man*
+ do
+ ./secindex $i > $i/INDEX
+ done
+
blob - /dev/null
blob + 6dd0d51eaf86f8071f4cc01fe6eaad21c5bd8f79 (mode 755)
--- /dev/null
+++ man/secindex
+#!/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
