o5r/plan9port
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rewrite page(2) references to page(3).

Browse source 
Add description of new libmach.
This commit is contained in:
rsc 2004-04-11 03:42:27 +00:00
parent cfa37a7b11
commit bf8a59fa01
91 changed files with 1624 additions and 1607 deletions
Download patch file Download diff file Expand all files Collapse all files

18
man/man3/9p.3
View file

@ -108,13 +108,13 @@ and
.B Fid
structures are allocated one-to-one with uncompleted
requests and active fids, and are described in
.IR 9pfid (2).
.IR 9pfid (3).
.PP
The behavior of
.I srv
depends on whether there is a file tree
(see
.IR 9pfile (2))
.IR 9pfile (3))
associated with the server, that is,
whether the
.B tree
@ -178,11 +178,11 @@ as
Fork a child process via
.I rfork
(see
.IR fork (2))
.IR fork (3))
or
.I procrfork
(see
.IR thread (2)),
.IR thread (3)),
using the
.BR RFFDG ,
.RR RFNOTEG ,
@ -216,7 +216,7 @@ If any error occurs during
this process, the entire process is terminated by calling
.I sysfatal
(see
.IR perror (2)).
.IR perror (3)).
.SS Service functions
The functions in a
.B Srv
@ -334,7 +334,7 @@ where
is the program name variable as set by
.I ARGBEGIN
(see
.IR arg (2)).
.IR arg (3)).
.TP
.I Attach
The
@ -702,7 +702,7 @@ the service loop (which runs in a separate process
from its caller) terminates using
.I _exits
(see
.IR exits (2)).
.IR exits (3)).
.PD
.PP
If the
@ -750,8 +750,8 @@ or is maintained elsewhere.
.SH SOURCE
.B /sys/src/lib9p
.SH SEE ALSO
.IR 9pfid (2),
.IR 9pfile (2),
.IR 9pfid (3),
.IR 9pfile (3),
.IR srv (3),
.IR intro (5)
.SH BUGS

4
man/man3/9pcmdbuf.3
View file

@ -42,7 +42,7 @@ bytes at
.I p
(which need not be NUL-terminated) as a UTF string and splits it
using
.IR tokenize (2).
.IR tokenize (3).
It returns a
.B Cmdbuf
structure holding pointers to each field in the message.
@ -113,4 +113,4 @@ is a good example.
.SH SOURCE
.B /sys/src/lib9p/parse.c
.SH SEE ALSO
.IR 9p (2)
.IR 9p (3)

8
man/man3/9pfid.3
View file

@ -73,7 +73,7 @@ and
.BR Reqpool s.
They are primarily used by the 9P server loop
described in
.IR 9p (2).
.IR 9p (3).
.PP
.B Fid
structures are intended to represent
@ -115,7 +115,7 @@ element points at a
.B File
structure
(see
.IR 9pfile (2))
.IR 9pfile (3))
corresponding to the fid.
The
.B aux
@ -200,5 +200,5 @@ structures.
.SH SOURCE
.B /sys/src/lib9p
.SH SEE ALSO
.IR 9p (2),
.IR 9pfile (2)
.IR 9p (3),
.IR 9pfile (3)

4
man/man3/9pfile.3
View file

@ -144,7 +144,7 @@ When creating new file references by copying pointers,
call
.I incref
(see
.IR lock (2))
.IR lock (3))
to update the reference count.
To note the removal of a reference to a file, call
.IR closefile .
@ -218,6 +218,6 @@ return nf;
.SH SOURCE
.B /sys/src/lib9p/file.c
.SH SEE ALSO
.IR 9p (2)
.IR 9p (3)
.SH BUGS
The reference counting is cumbersome.

2
man/man3/abs.3
View file

@ -22,7 +22,7 @@ does the same for a long.
.SH SOURCE
.B /sys/src/libc/port/abs.c
.SH SEE ALSO
.IR floor (2)
.IR floor (3)
for
.I fabs
.SH DIAGNOSTICS

6
man/man3/access.3
View file

@ -31,7 +31,7 @@ Zero is returned if the desired access is permitted,
.PP
Only access for open is checked.
A file may look executable, but
.IR exec (2)
.IR exec (3)
will fail unless it is in proper format.
.PP
The include file
@ -46,7 +46,7 @@ and
.SH SOURCE
.B /sys/src/libc/9sys/access.c
.SH SEE ALSO
.IR stat (2)
.IR stat (3)
.SH DIAGNOSTICS
Sets
.IR errstr .
@ -56,5 +56,5 @@ is not known to the client,
.I access
must open the file to check permissions.
(It calls
.IR stat (2)
.IR stat (3)
to check simple existence.)

2
man/man3/addpt.3
View file

@ -185,4 +185,4 @@ They are implemented as macros.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2)
.IR graphics (3)

20
man/man3/aes.3
View file

@ -39,13 +39,13 @@ cryptographically strongly unpredictable.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR blowfish (2),
.IR des (2),
.IR dsa (2),
.IR elgamal (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)
.IR mp (3),
.IR blowfish (3),
.IR des (3),
.IR dsa (3),
.IR elgamal (3),
.IR rc4 (3),
.IR rsa (3),
.IR sechash (3),
.IR prime (3),
.IR rand (3)

6
man/man3/allocimage.3
View file

@ -191,7 +191,7 @@ These routines permit unrelated applications sharing a display to share an image
for example they provide the mechanism behind
.B getwindow
(see
.IR graphics (2)).
.IR graphics (3)).
.PP
The RGB values in a color are
.I premultiplied
@ -333,8 +333,8 @@ To allocate a single-pixel replicated image that may be used to paint a region r
.SH SOURCE
.B /sys/src/libdraw
.SH "SEE ALSO"
.IR graphics (2),
.IR draw (2),
.IR graphics (3),
.IR draw (3),
.IR draw (3),
.IR image (6)
.SH DIAGNOSTICS

4
man/man3/arg.3
View file

@ -20,7 +20,7 @@ These macros assume the names
and
.I argv
are in scope; see
.IR exec (2).
.IR exec (3).
.I ARGBEGIN
and
.I ARGEND
@ -58,7 +58,7 @@ but instead of returning zero
runs
.I code
and, if that returns, calls
.IR abort (2).
.IR abort (3).
A typical value for
.I code
is

2
man/man3/atof.3
View file

@ -129,7 +129,7 @@ after calling
.SH SOURCE
.B /sys/src/libc/port
.SH SEE ALSO
.IR fscanf (2)
.IR fscanf (3)
.SH DIAGNOSTICS
Zero is returned if the beginning of the input string is not
interpretable as a number; even in this case,

8
man/man3/auth.3
View file

@ -120,7 +120,7 @@ It should be used instead of
.I mount
whenever the file server being mounted requires authentication.
See
.IR bind (2)
.IR bind (3)
for a definition of the arguments to
.I mount
and
@ -196,7 +196,7 @@ file used is
An
.B sprint
(see
.IR print (2))
.IR print (3))
of
.I fmt
and the variable arg list yields a key template (see
@ -388,8 +388,8 @@ frees a challenge/response state.
.B /sys/src/libauth
.SH SEE ALSO
.IR factotum (4),
.IR authsrv (2),
.IR bind (2)
.IR authsrv (3),
.IR bind (3)
.SH DIAGNOSTICS
These routines set
.IR errstr .

2
man/man3/authsrv.3
View file

@ -215,7 +215,7 @@ to recieve an answer.
.SH SEE ALSO
.IR passwd (1),
.IR cons (3),
.IR dial (2),
.IR dial (3),
.IR authsrv (6),
.SH DIAGNOSTICS
These routines set

4
man/man3/bin.3
View file

@ -82,7 +82,7 @@ are ignored, and the result is the same as calling
and
.I bingrow
allocate large chunks of memory using
.IR malloc (2)
.IR malloc (3)
and return pieces of these chunks.
The chunks are
.IR free 'd
@ -91,7 +91,7 @@ upon a call to
.SH SOURCE
.B /sys/src/libbin
.SH SEE ALSO
.IR malloc (2)
.IR malloc (3)
.SH DIAGNOSTICS
.I binalloc
and

16
man/man3/bio.3
View file

@ -90,7 +90,7 @@ for mode
or creates for mode
.BR OWRITE .
It calls
.IR malloc (2)
.IR malloc (3)
to allocate a buffer.
.PP
.I Binit
@ -159,7 +159,7 @@ of the most recent string returned by
.PP
.I Brdstr
returns a
.IR malloc (2)-allocated
.IR malloc (3)-allocated
buffer containing the next line of input delimited by
.IR delim ,
terminated by a NUL (0) byte.
@ -211,7 +211,7 @@ may back up a maximum of five bytes.
uses
.I charstod
(see
.IR atof (2))
.IR atof (3))
and
.I Bgetc
to read the formatted
@ -232,7 +232,7 @@ and a negative value is returned if a read error occurred.
.PP
.I Bseek
applies
.IR seek (2)
.IR seek (3)
to
.IR bp .
It returns the new file offset.
@ -264,7 +264,7 @@ on the output stream.
.PP
.I Bprint
is a buffered interface to
.IR print (2).
.IR print (3).
If this causes a
.IR write
to occur and there is an error,
@ -309,9 +309,9 @@ written.
.SH SOURCE
.B /sys/src/libbio
.SH SEE ALSO
.IR open (2),
.IR print (2),
.IR exits (2),
.IR open (3),
.IR print (3),
.IR exits (3),
.IR utf (6),
.SH DIAGNOSTICS
.I Bio

20
man/man3/blowfish.3
View file

@ -40,13 +40,13 @@ must be a multiple of eight bytes as padding is currently unsupported.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR des (2),
.IR dsa (2),
.IR elgamal (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)
.IR mp (3),
.IR aes (3),
.IR des (3),
.IR dsa (3),
.IR elgamal (3),
.IR rc4 (3),
.IR rsa (3),
.IR sechash (3),
.IR prime (3),
.IR rand (3)

12
man/man3/cachechars.3
View file

@ -181,7 +181,7 @@ The
and
.LR ascent
fields of Font are described in
.IR graphics (2).
.IR graphics (3).
.L Sub
contains
.L nsub
@ -302,12 +302,12 @@ for replacement when the cache is full.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2),
.IR allocimage (2),
.IR draw (2),
.IR subfont (2),
.IR graphics (3),
.IR allocimage (3),
.IR draw (3),
.IR subfont (3),
.IR image (6),
.IR font (6)
.SH DIAGNOSTICS
All of the functions use the graphics error function (see
.IR graphics (2)).
.IR graphics (3)).

10
man/man3/color.3
View file

@ -41,16 +41,16 @@ and the next 8 representing blue, then green, then red, as for
.I cmap2rgba
shifted up 8 bits.
This 32-bit representation is the format used by
.IR draw (2)
.IR draw (3)
and
.IR memdraw (2)
.IR memdraw (3)
library routines that
take colors as arguments.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2),
.IR allocimage (2),
.IR draw (2),
.IR graphics (3),
.IR allocimage (3),
.IR draw (3),
.IR image (6),
.IR color (6)

4
man/man3/ctype.3
View file

@ -59,7 +59,7 @@ is true and on the single non-\c
value
.BR EOF ;
see
.IR fopen (2).
.IR fopen (3).
.TP "\w'isalnum 'u"
.I isalpha
.I c
@ -153,7 +153,7 @@ for the macros.
.B /sys/src/libc/port/ctype.c
for the tables.
.SH "SEE ALSO
.IR isalpharune (2)
.IR isalpharune (3)
.SH BUGS
These macros are
.SM ASCII \c

386
man/man3/debugger.3
View file

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

20
man/man3/des.3
View file

@ -132,13 +132,13 @@ using
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR blowfish (2),
.IR dsa (2),
.IR elgamal (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)
.IR mp (3),
.IR aes (3),
.IR blowfish (3),
.IR dsa (3),
.IR elgamal (3),
.IR rc4 (3),
.IR rsa (3),
.IR sechash (3),
.IR prime (3),
.IR rand (3)

4
man/man3/dial.3
View file

@ -203,7 +203,7 @@ The information is obtained from the connection directory,
If
.I conndir
is nil, the directory is obtained by performing
.IR fd2path (2)
.IR fd2path (3)
on
.IR fd .
.I Getnetconninfo
@ -318,7 +318,7 @@ bekremvax(void)
.BR /sys/src/libc/9sys ,
.B /sys/src/libc/port
.SH "SEE ALSO"
.IR auth (2),
.IR auth (3),
.IR ip (3),
.IR ndb (8)
.SH DIAGNOSTICS

16
man/man3/dirread.3
View file

@ -19,11 +19,11 @@ long dirreadall(int fd, Dir **buf)
#define DIRMAX (sizeof(Dir)+STATMAX)
.SH DESCRIPTION
The data returned by a
.IR read (2)
.IR read (3)
on a directory is a set of complete directory entries
in a machine-independent format, exactly equivalent to
the result of a
.IR stat (2)
.IR stat (3)
on each file or subdirectory in the directory.
.I Dirread
decodes the directory entries into a machine-dependent form.
@ -35,11 +35,11 @@ structures
whose address is returned in
.B *buf
(see
.IR stat (2)
.IR stat (3)
for the layout of a
.BR Dir ).
The array is allocated with
.IR malloc (2)
.IR malloc (3)
each time
.I dirread
is called.
@ -50,7 +50,7 @@ is like
but reads in the entire directory; by contrast,
.I dirread
steps through a directory one
.IR read (2)
.IR read (3)
at a time.
.PP
Directory entries have variable length.
@ -85,9 +85,9 @@ The file offset is advanced by the number of bytes actually read.
.SH SOURCE
.B /sys/src/libc/9sys/dirread.c
.SH SEE ALSO
.IR intro (2),
.IR open (2),
.IR read (2)
.IR intro (3),
.IR open (3),
.IR read (3)
.SH DIAGNOSTICS
.I Dirread
and

10
man/man3/draw.3
View file

@ -261,7 +261,7 @@ number of bits per pixel in the picture;
it is identically
.B chantodepth(chan)
(see
.IR graphics (2))
.IR graphics (3))
and is provided as a convenience.
The value should not be modified after the image is created.
.TP
@ -705,7 +705,7 @@ what
is to
.B atan
(see
.IR sin (2)).
.IR sin (3)).
.TP
.BI border( dst\fP,\fP\ r\fP,\fP\ i\fP,\fP\ color\fP,\fP\ sp\fP)
.I Border
@ -803,11 +803,11 @@ is non-zero.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2),
.IR stringsize (2),
.IR graphics (3),
.IR stringsize (3),
.IR color (6),
.IR utf (6),
.IR addpt (2)
.IR addpt (3)
.PP
T. Porter, T. Duff.
``Compositing Digital Images'',

20
man/man3/dsa.3
View file

@ -79,7 +79,7 @@ a key is created using a new
and
.B q
generated by
.IR DSAprimes (2).
.IR DSAprimes (3).
Otherwise,
.B p
and
@ -121,12 +121,12 @@ are provided to manage signature storage.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR blowfish (2),
.IR des (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)
.IR mp (3),
.IR aes (3),
.IR blowfish (3),
.IR des (3),
.IR rc4 (3),
.IR rsa (3),
.IR sechash (3),
.IR prime (3),
.IR rand (3)

2
man/man3/dup.3
View file

@ -35,7 +35,7 @@ the program.
.SH SOURCE
.B /sys/src/libc/9syscall
.SH SEE ALSO
.IR intro (2),
.IR intro (3),
.IR dup (3)
.SH DIAGNOSTICS
Sets

20
man/man3/elgamal.3
View file

@ -113,13 +113,13 @@ are provided to manage signature storage.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR blowfish (2),
.IR des (2),
.IR dsa (2),
.IR rc4 (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)
.IR mp (3),
.IR aes (3),
.IR blowfish (3),
.IR des (3),
.IR dsa (3),
.IR rc4 (3),
.IR rsa (3),
.IR sechash (3),
.IR prime (3),
.IR rand (3)

4
man/man3/encode.3
View file

@ -49,9 +49,9 @@ of 8.
.PP
.I Encodefmt
can be used with
.IR fmtinstall (2)
.IR fmtinstall (3)
and
.IR print (2)
.IR print (3)
to print encoded representations of byte arrays.
The verbs are
.TP

6
man/man3/errstr.3
View file

@ -53,7 +53,7 @@ the result is an empty string.
The verb
.B r
in
.IR print (2)
.IR print (3)
calls
.I errstr
and outputs the error string.
@ -81,5 +81,5 @@ is discarded.
.I Errstr
always returns 0.
.SH SEE ALSO
.IR intro (2),
.IR perror (2)
.IR intro (3),
.IR perror (3)

18
man/man3/event.3
View file

@ -93,12 +93,12 @@ enum{
These routines provide an interface to multiple sources of input for unthreaded
programs.
Threaded programs (see
.IR thread (2))
.IR thread (3))
should instead use the threaded mouse and keyboard interface described
in
.IR mouse (2)
.IR mouse (3)
and
.IR keyboard (2).
.IR keyboard (3).
.PP
.I Einit
must be called first.
@ -113,7 +113,7 @@ the mouse and keyboard events will be enabled;
in this case,
.IR initdraw
(see
.IR graphics (2))
.IR graphics (3))
must have already been called.
The user must provide a function called
.IR eresized
@ -123,7 +123,7 @@ is running has been resized; the argument
is a flag specifying whether the program must call
.I getwindow
(see
.IR graphics (2))
.IR graphics (3))
to re-establish a connection to its window.
After resizing (and perhaps calling
.IR getwindow ),
@ -266,7 +266,7 @@ The return is the same as for
.IR eread .
.PP
As described in
.IR graphics (2),
.IR graphics (3),
the graphics functions are buffered.
.IR Event ,
.IR eread ,
@ -370,7 +370,7 @@ changes the cursor image to that described by the
.B Cursor
.I c
(see
.IR mouse (2)).
.IR mouse (3)).
If
.B c
is nil, it restores the image to the default arrow.
@ -378,7 +378,7 @@ is nil, it restores the image to the default arrow.
.B /sys/src/libdraw
.SH "SEE ALSO"
.IR rio (1),
.IR graphics (2),
.IR plumb (2),
.IR graphics (3),
.IR plumb (3),
.IR cons (3),
.IR draw (3)

10
man/man3/exec.3
View file

@ -34,7 +34,7 @@ points to the name of the file
to be executed; it must not be a directory, and the permissions
must allow the current user to execute it
(see
.IR stat (2)).
.IR stat (3)).
It should also be a valid binary image, as defined in the
.IR a.out (6)
for the current machine architecture,
@ -103,7 +103,7 @@ files remain open across
.B OCEXEC
OR'd
into the open mode; see
.IR open (2));
.IR open (3));
and the working directory and environment
(see
.IR env (3))
@ -112,7 +112,7 @@ However, a newly
.I exec'ed
process has no notification handler
(see
.IR notify (2)).
.IR notify (3)).
.PP
When the new program begins, the global cell
.B _clock
@ -147,8 +147,8 @@ on the 68020) contains the address of the clock.
.B /sys/src/libc/port/execl.c
.SH SEE ALSO
.IR prof (1),
.IR intro (2),
.IR stat (2)
.IR intro (3),
.IR stat (3)
.SH DIAGNOSTICS
If these functions fail, they return and set
.IR errstr .

6
man/man3/exits.3
View file

@ -33,7 +33,7 @@ explanation of the reason for
exiting, or a null pointer or empty string to indicate normal termination.
The string is passed to the parent process, prefixed by the name and process
id of the exiting process, when the parent does a
.IR wait (2).
.IR wait (3).
.PP
Before calling
.I _exits
@ -77,5 +77,5 @@ cancels a previous registration of an exit function.
.SH SOURCE
.B /sys/src/libc/port/atexit.c
.SH "SEE ALSO"
.IR fork (2),
.IR wait (2)
.IR fork (3),
.IR wait (3)

14
man/man3/fcall.3
View file

@ -225,7 +225,7 @@ by a successful call to
Another structure is
.BR Dir ,
used by the routines described in
.IR stat (2).
.IR stat (3).
.I ConvM2D
converts the machine-independent form starting at
.I ap
@ -293,7 +293,7 @@ contain a validly formatted machine-independent
entry suitable as an argument, for example, for the
.B wstat
(see
.IR stat (2))
.IR stat (3))
system call.
It checks that the sizes of all the elements of the the entry sum to exactly
.IR nbuf ,
@ -321,7 +321,7 @@ for an incorrectly formatted entry.
and
.I dirmodefmt
are formatting routines, suitable for
.IR fmtinstall (2).
.IR fmtinstall (3).
They convert
.BR Dir* ,
.BR Fcall* ,
@ -343,7 +343,7 @@ with format letter
.PP
.I Read9pmsg
calls
.IR read (2)
.IR read (3)
multiple times, if necessary, to read an entire 9P message into
.BR buf .
The return value is 0 for end of file, or -1 for error; it does not return
@ -351,7 +351,7 @@ partial messages.
.SH SOURCE
.B /sys/src/libc/9sys
.SH SEE ALSO
.IR intro (2),
.IR 9p (2),
.IR stat (2),
.IR intro (3),
.IR 9p (3),
.IR stat (3),
.IR intro (5)

2
man/man3/flate.3
View file

@ -173,7 +173,7 @@ The block functions return the number of bytes produced when they succeed.
.I Mkcrctab
allocates
(using
.IR malloc (2)),
.IR malloc (3)),
initializes, and returns a table for rapid computation of 32 bit CRC values using the polynomial
.IR poly .
.I Blockcrc

18
man/man3/fmtinstall.3
View file

@ -94,16 +94,16 @@ int fmtrunestrcpy(Fmt *f, Rune *s);
int errfmt(Fmt *f);
.SH DESCRIPTION
The interface described here allows the construction of custom
.IR print (2)
.IR print (3)
verbs and output routines.
In essence, they provide access to the workings of the formatted print code.
.PP
The
.IR print (2)
.IR print (3)
suite maintains its state with a data structure called
.BR Fmt .
A typical call to
.IR print (2)
.IR print (3)
or its relatives initializes a
.B Fmt
structure, passes it to subsidiary routines to process the output,
@ -154,7 +154,7 @@ to generate the output.
These behave like
.B fprint
(see
.IR print (2))
.IR print (3))
or
.B vfprint
except that the characters are buffered until
@ -207,7 +207,7 @@ In
are the width and precision, and
.IB fp ->flags
the decoded flags for the verb (see
.IR print (2)
.IR print (3)
for a description of these items).
The standard flag values are:
.B FmtSign
@ -282,7 +282,7 @@ produced.
.PP
Some internal functions may be useful to format primitive types.
They honor the width, precision and flags as described in
.IR print (2).
.IR print (3).
.I Fmtrune
formats a single character
.BR r .
@ -307,7 +307,7 @@ that can be used to provide type-checking for custom print verbs and output rout
This function prints an error message with a variable
number of arguments and then quits.
Compared to the corresponding example in
.IR print (2),
.IR print (3),
this version uses a smaller buffer, will never truncate
the output message, but might generate multiple
.B write
@ -364,9 +364,9 @@ main(...)
.SH SOURCE
.B /sys/src/libc/fmt
.SH SEE ALSO
.IR print (2),
.IR print (3),
.IR utf (6),
.IR errstr (2)
.IR errstr (3)
.SH DIAGNOSTICS
These routines return negative numbers or nil for errors and set
.IR errstr .

10
man/man3/fork.3
View file

@ -38,7 +38,7 @@ see
.IR proc (3)),
the set of rendezvous tags
(see
.IR rendezvous (2));
.IR rendezvous (3));
and open files.
.I Flags
is the logical OR of some subset of
@ -53,7 +53,7 @@ If set, the child process will be dissociated from the parent. Upon
exit the child will leave no
.B Waitmsg
(see
.IR wait (2))
.IR wait (3))
for the parent to collect.
.TP
.B RFNAMEG
@ -100,7 +100,7 @@ previous processes.
.TP
.B RFFDG
If set, the invoker's file descriptor table (see
.IR intro (2))
.IR intro (3))
is copied; otherwise the two processes share a
single table.
.TP
@ -111,7 +111,7 @@ Is mutually exclusive with
.TP
.B RFREND
If set, the process will be unable to
.IR rendezvous (2)
.IR rendezvous (3)
with any of its ancestors; its children will, however, be able to
.B rendezvous
with it. In effect,
@ -159,7 +159,7 @@ is just a call of
.br
.B /sys/src/libc/9sys/fork.c
.SH SEE ALSO
.IR intro (2),
.IR intro (3),
.IR proc (3),
.SH DIAGNOSTICS
These functions set

8
man/man3/frame.3
View file

@ -239,7 +239,7 @@ If a
.B Frame
is being moved but not resized, that is, if the shape of its containing
rectangle is unchanged, it is sufficient to use
.IR draw (2)
.IR draw (3)
to copy the containing rectangle from the old to the new location and then call
.I frsetrects
to establish the new geometry.
@ -357,6 +357,6 @@ and
.SH SOURCE
.B /sys/src/libframe
.SH SEE ALSO
.IR graphics (2),
.IR draw (2),
.IR cachechars (2).
.IR graphics (3),
.IR draw (3),
.IR cachechars (3).

6
man/man3/genrandom.3
View file

@ -28,7 +28,7 @@ truly random bytes read from
.PP
.I Prng
uses the native
.IR rand (2)
.IR rand (3)
pseudo-random number generator to fill the buffer. Used with
.IR srand ,
this function can produce a reproducible stream of pseudo random
@ -37,8 +37,8 @@ numbers useful in testing.
Both functions may be passed to
.I mprand
(see
.IR mp (2)).
.IR mp (3)).
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2)
.IR mp (3)

2
man/man3/getenv.3
View file

@ -20,7 +20,7 @@ reads the contents of
(see
.IR env (3))
into memory allocated with
.IR malloc (2),
.IR malloc (3),
0-terminates it,
and returns a pointer to that area.
If no file exists, 0

6
man/man3/getfields.3
View file

@ -77,7 +77,7 @@ except that fields may be quoted using single quotes, in the manner
of
.IR rc (1).
See
.IR quote (2)
.IR quote (3)
for related quote-handling software.
.PP
.I Tokenize
@ -91,5 +91,5 @@ set to \f5"\et\er\en "\fP.
.SH SEE ALSO
.I strtok
in
.IR strcat (2),
.IR quote (2).
.IR strcat (3),
.IR quote (3).

2
man/man3/getpid.3
View file

@ -31,7 +31,7 @@ and converts it to get the id of the parent of the current process.
.SH SOURCE
.B /sys/src/libc/9sys
.SH SEE ALSO
.IR intro (2),
.IR intro (3),
.IR cons (3),
.IR proc (3)
.SH DIAGNOSTICS

2
man/man3/getuser.3
View file

@ -33,5 +33,5 @@ caches the string, reading the file only once.
.SH SOURCE
.B /sys/src/libc/port/getuser.c
.SH SEE ALSO
.IR intro (2),
.IR intro (3),
.IR cons (3)

4
man/man3/getwd.3
View file

@ -24,10 +24,10 @@ bytes in the buffer provided.
.B /sys/src/libc/9sys/getwd.c
.SH "SEE ALSO"
.IR pwd (1),
.IR fd2path (2)
.IR fd2path (3)
.SH DIAGNOSTICS
On error, zero is returned.
.IR Errstr (2)
.IR Errstr (3)
may be consulted for more information.
.SH BUGS
Although the name returned by

50
man/man3/graphics.3
View file

@ -135,7 +135,7 @@ A
.B Point
is a location in an Image
(see below and
.IR draw (2)),
.IR draw (3)),
such as the display, and is defined as:
.IP
.EX
@ -184,7 +184,7 @@ contains the coordinates of the first point beyond the rectangle.
The
.B Image
data structure is defined in
.IR draw (2).
.IR draw (3).
.PP
A
.B Font
@ -195,7 +195,7 @@ The images are organized into
each containing the images for a small, contiguous set of runes.
The detailed format of these data structures,
which are described in detail in
.IR cachechars (2),
.IR cachechars (3),
is immaterial for most applications.
.B Font
and
@ -210,7 +210,7 @@ and
the distance from the top of the highest character to the bottom of
the lowest character (and hence, the interline spacing).
See
.IR cachechars (2)
.IR cachechars (3)
for more details.
.PP
.I Buildfont
@ -221,7 +221,7 @@ returning a
pointer that can be used by
.B string
(see
.IR draw (2))
.IR draw (3))
to draw characters from the font.
.I Openfont
does the same, but reads the description
@ -335,7 +335,7 @@ is nil, the library provides a default, called
Another effect of
.I initdraw
is that it installs
.IR print (2)
.IR print (3)
formats
.I Pfmt
and
@ -375,7 +375,7 @@ files; and
specifies the refresh function to be used to create the window, if running under
.IR rio (1)
(see
.IR window (2)).
.IR window (3)).
.PP
The function
.I newwindow
@ -452,11 +452,11 @@ by looking in
to find the name of the window and opening it using
.B namedimage
(see
.IR allocimage (2)).
.IR allocimage (3)).
The resulting window will be created using the refresh method
.I ref
(see
.IR window (2));
.IR window (3));
this should almost always be
.B Refnone
because
@ -473,7 +473,7 @@ defining the window (or the overall display, if no window system is running); an
a pointer to the
.B Screen
representing the root of the window's hierarchy. (See
.IR window (2).
.IR window (3).
The overloading of the
.B screen
word is an unfortunate historical accident.)
@ -517,11 +517,11 @@ the window boundaries; otherwise
is a no-op.
.PP
The graphics functions described in
.IR draw (2),
.IR allocimage (2),
.IR cachechars (2),
.IR draw (3),
.IR allocimage (3),
.IR cachechars (3),
and
.IR subfont (2)
.IR subfont (3)
are implemented by writing commands to files under
.B /dev/draw
(see
@ -535,7 +535,7 @@ is non-zero, any changes are also copied from the `soft screen' (if any) in the
driver to the visible frame buffer.
The various allocation routines in the library flush automatically, as does the event
package (see
.IR event (2));
.IR event (3));
most programs do not need to call
.IR flushimage .
It returns \-1 on error.
@ -620,22 +620,22 @@ if(gengetwindow(display, "/tmp/winname",
.B /sys/src/libdraw
.SH "SEE ALSO"
.IR rio (1),
.IR addpt (2),
.IR allocimage (2),
.IR cachechars (2),
.IR subfont (2),
.IR draw (2),
.IR event (2),
.IR frame (2),
.IR print (2),
.IR window (2),
.IR addpt (3),
.IR allocimage (3),
.IR cachechars (3),
.IR subfont (3),
.IR draw (3),
.IR event (3),
.IR frame (3),
.IR print (3),
.IR window (3),
.IR draw (3),
.IR rio (4),
.IR image (6),
.IR font (6)
.SH DIAGNOSTICS
An error function may call
.IR errstr (2)
.IR errstr (3)
for further diagnostics.
.SH BUGS
The names

4
man/man3/intmap.3
View file

@ -122,5 +122,5 @@ and
.SH SOURCE
.B /sys/src/lib9p/intmap.c
.SH SEE ALSO
.IR 9p (2),
.IR 9pfid (2).
.IR 9p (3),
.IR 9pfid (3).

14
man/man3/ioproc.3
View file

@ -68,10 +68,10 @@ and
are execute the
similarly named library or system calls
(see
.IR open (2),
.IR read (2),
.IR open (3),
.IR read (3),
and
.IR dial (2))
.IR dial (3))
in the slave process associated with
.IR io .
It is an error to execute more than one call
@ -172,8 +172,8 @@ ioread(Ioproc *io, int fd, void *a, long n)
.SH SOURCE
.B /sys/src/libthread/io*.c
.SH SEE ALSO
.IR dial (2),
.IR open (2),
.IR read (2),
.IR thread (2)
.IR dial (3),
.IR open (3),
.IR read (3),
.IR thread (3)

4
man/man3/ip.3
View file

@ -120,7 +120,7 @@ The string representation of Ethernet addresses is exactly
.PP
.I Eipfmt
is a
.IR print (2)
.IR print (3)
formatter for Ethernet (verb
.BR E )
addresses,
@ -332,4 +332,4 @@ point to point.
.SH SOURCE
.B /sys/src/libip
.SH SEE ALSO
.IR print (2)
.IR print (3)

4
man/man3/isalpharune.3
View file

@ -35,7 +35,7 @@ in particular a subset of their properties as defined in the Unicode standard.
Unicode defines some characters as alphabetic and specifies three cases:
upper, lower, and title.
Analogously to
.IR ctype (2)
.IR ctype (3)
for
.SM ASCII\c
,
@ -47,5 +47,5 @@ The case-conversion routines return the character unchanged if it has no case.
.SH SOURCE
.B /sys/src/libc/port/runetype.c
.SH "SEE ALSO
.IR ctype (2) ,
.IR ctype (3) ,
.IR "The Unicode Standard" .

14
man/man3/keyboard.3
View file

@ -23,14 +23,14 @@ void closekeyboard(Keyboard *kc)
.SH DESCRIPTION
These functions access and control a keyboard interface
for character-at-a-time I/O in a multi-threaded environment, usually in combination with
.IR mouse (2).
.IR mouse (3).
They use the message-passing
.B Channel
interface in the threads library
(see
.IR thread (2));
.IR thread (3));
programs that wish a more event-driven, single-threaded approach should use
.IR event (2).
.IR event (3).
.PP
.I Initkeyboard
opens a connection to the keyboard and returns a
@ -94,10 +94,10 @@ structure.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2),
.IR draw (2),
.IR event (2),
.IR thread (2).
.IR graphics (3),
.IR draw (3),
.IR event (3),
.IR thread (3).
.SH BUGS
Because the interface delivers complete runes,
there is no way to report lesser actions such as

6
man/man3/lock.3
View file

@ -80,9 +80,9 @@ are rendezvous points.
Locks and rendezvous points work in regular programs as
well as programs that use the thread library
(see
.IR thread (2)).
.IR thread (3)).
The thread library replaces the
.IR rendezvous (2)
.IR rendezvous (3)
system call
with its own implementation,
.IR threadrendezvous ,
@ -207,7 +207,7 @@ and returns zero if the resulting value is zero, non-zero otherwise.
.SH SEE ALSO
.I rfork
in
.IR fork (2)
.IR fork (3)
.SH BUGS
.B Locks
are not strictly spin locks.

152
man/man3/mach-file.3 Normal file
View file

@ -0,0 +1,152 @@
.TH MACH-FILE 3
.SH NAME
crackhdr, uncrackhdr, mapfile, mapproc, detachproc, ctlproc,
procnotes \- machine-independent access to exectuable files and running processes
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mach.h>
.PP
.ft B
.ta \w'\fBxxxxxx'u +\w'xxxxxx'u
int crackhdr(int fd, Fhdr *hdr)
.br
void uncrackhdr(Fhdr *hdr)
.PP
.ft B
int mapfile(Map *map, ulong base, Fhdr *hdr)
.br
int mapproc(Map *map, int pid)
.br
int detachproc(int pid)
.br
int ctlproc(int pid, char *msg)
.br
int procnotes(int pid, char ***notes)
.SH DESCRIPTION
These functions parse executable files and
provide access to those files and to running processes.
.PP
.I Crackhdr
opens and parses the named executable file.
The returned data structure
.I hdr
is initialized with a machine-independent description
of the header information. The following fields are the
most commonly used:
.TP
.B mach
a pointer to the
.B Mach
structure for the target architecture
.TP
.B mname
the name of the target architecture
.TP
.B fname
a description of the kind of file
(e.g., executable, core dump)
.TP
.B aname
a description of the application binary interface
this file uses; typically it is the name of an operating system
.PD
If the global variable
.I mach
is nil,
.I crackhdr
points it to the same
.B Mach
structure.
.PP
.I Mapfile
adds the segments found in
.I hdr
to
.IR map .
If
.I hdr
is an executable file, there are typically three segments:
.IR text ,
.IR data ,
and a zero-backed
.IR bss .
If
.I hdr
is a dynamic shared library, its segments are relocated by
.I base
before being mapping.
.PP
If
.I hdr
is a core file, there is one segment named
.I core
for each contiguous section of memory recorded in the core file.
There are often quite a few of these, as most operating systems
omit clean memory pages when writing core files
(Mac OS X is the only exception among the supported systems).
Because core files have such holes, it is typically necessary to
construct the core map by calling
.I mapfile
on the executable and then calling it again on the core file.
Newly-added segments are mapped on top of existing segments,
so this arrangement will use the core file for the segments it contains
but fall back to the executable for the rest.
.PP
.I Mapproc
attaches to a running program and adds its segments to the given map.
It adds one segment for each contiguous section of
mapped memory.
On systems where this information cannot be determined, it adds
a single segment covering the entire address space.
Accessing areas of this segment that are actually not mapped
in the process address space will cause the get/put routines to return errors.
.I Detachproc
detaches from a previously-attached program.
.PP
.I Ctlproc
manipulates the process with id
.I pid
according to the message
.IR msg .
Valid messages include:
.TP
.B kill
terminate the process
.TP
.B startstop
start the process and wait for it to stop
.TP
.B sysstop
arrange for the process to stop at its next system call,
start the process, and then wait for it to stop
.TP
.B waitstop
wait for the process to stop
.TP
.B start
start the process
.PD
.PP
.I Procnotes
fills
.BI * notes
with a pointer to an array of strings
representing pending notes waiting
for the process.
(On Unix, these notes are textual descriptions
of any pending signals.)
.I Procnotes
returns the number of pending notes.
The memory at
.BI * notes
should be freed via
.IR free (3)
when no longer needed.
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR mach (3),
.IR mach-map (3)

419
man/man3/mach-map.3 Normal file
View file

@ -0,0 +1,419 @@
.TH MACH-MAP 3
.SH NAME
allocmap, addseg, addregseg, findseg, addrtoseg,
addrtosegafter, removeseg, freemap,
get1, get2, get4, get8,
put1, put2, put4, put8,
rget1, rget2, rget4, rget8,
rput1, rput2, rput4, rput8,
locaddr, locconst, locreg, locindir,
loccmp, loceval, locfmt, locredir,
lget1, lget2, lget4, lget8,
lput1, lput2, lput4, lput8 \- machine-independent
access to address spaces and register sets
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mach.h>
.PP
.B
.ta \w'\fBxxxxxx'u +\w'xxxxxxx'u
.nf
typedef struct Map Map;
typedef struct Seg Seg;
.PP
.B
.nf
struct Seg
{
char *name;
char *file;
int fd;
ulong base;
ulong size;
ulong offset;
int (*rw)(Map*, Seg*, ulong, void*, uint, int);
};
.PP
.B
.nf
struct Map
{
Seg *seg;
int nseg;
\fI...\fR
};
.PP
.B
Map *allocmap(void)
.br
int addseg(Map *map, Seg seg)
.br
int findseg(Map *map, char *name, char *file)
.br
int addrtoseg(Map *map, ulong addr, Seg *seg)
.br
int addrtosegafter(Map *map, ulong addr, Seg *seg)
.br
void removeseg(Map *map, int i)
.br
void freemap(Map *map)
.PP
.B
int get1(Map *map, ulong addr, uchar *a, uint n)
.br
int get2(Map *map, ulong addr, u16int *u)
.br
int get4(Map *map, ulong addr, u32int *u)
.br
int get8(Map *map, ulong addr, u64int *u)
.PP
.B
int put1(Map *map, ulong addr, uchar *a, uint n)
.br
int put2(Map *map, ulong addr, u16int u)
.br
int put4(Map *map, ulong addr, u32int u)
.br
int put8(Map *map, ulong addr, u64int u)
.PP
.B
int rget1(Map *map, char *reg, u8int *u)
.br
int rget2(Map *map, char *reg, u16int *u)
.br
int rget4(Map *map, char *reg, u32int *u)
.br
int rget8(Map *map, char *reg, u64int *u)
.br
int fpformat(Map *map, char *reg, char *a, uint n, char code);
.PP
.B
int rput1(Map *map, char *reg, u8int u)
.br
int rput2(Map *map, char *reg, u16int u)
.br
int rput4(Map *map, char *reg, u32int u)
.br
int rput8(Map *map, char *reg, u64int u)
.PP
.B
Loc locaddr(ulong addr)
.br
Loc locconst(ulong con)
.br
Loc locreg(char *reg)
.br
Loc locindir(char *reg, long offset)
.PP
.B
int loccmp(Loc *a, Loc *b)
.br
int loceval(Map *map, Loc loc, ulong *addr)
.br
int locfmt(Fmt *fmt)
.br
int locredir(Map *map, Loc *regs, Loc loc, Loc *newloc)
.PP
.B
int lget1(Map *map, Loc loc, uchar *a, uint n)
.br
int lget2(Map *map, Loc loc, u16int *u)
.br
int lget4(Map *map, Loc loc, u32int *u)
.br
int lget8(Map *map, Loc loc, u64int *u)
.PP
.B
int lput1(Map *map, Loc loc, uchar *a, uint n)
.br
int lput2(Map *map, Loc loc, u16int u)
.br
int lput4(Map *map, Loc loc, u32int u)
.br
int lput8(Map *map, Loc loc, u64int u)
.PP
.SH DESCRIPTION
These functions provide
a processor-independent interface for accessing
executable files, core files, and running processes
via
.IR maps ,
data structures that provides access to an address space
and register set.
The functions described in
.IR mach-file (3)
are typically used to construct these maps.
Related library functions described in
.IR mach-symbol (3)
provide similar access to symbol tables.
.PP
Each
.I map
comprises an optional register set and one or more
.BR segments ,
each associating a non-overlapping range of
memory addresses with a logical section of
an executable file or of a running process's address space.
Other library functions then use a map
and the architecture-specific data structures
to provide a generic interface to the
processor-dependent data.
.PP
Each segment has a name (e.g.,
.B text
or
.BR data )
and may be associated with a particular file.
A segment represents a range of accessible address space.
Segments may be backed an arbitary access function
(if the
.B rw
pointer is non-nil),
or by the contents of an open file
(using the
.B fd
file descriptor).
Each range has a starting address in the space
.RB ( base )
and
an extent
.RB ( size ).
In segments mapped by files,
the range begins at byte
.B offset
in the file.
The
.B rw
function is most commonly used to provide
access to executing processes via
.IR ptrace (2)
and to zeroed segments.
.PP
.I Allocmap
creates an empty map;
.IR freemap
frees a map.
.PP
.I Addseg
adds the given segment to the map, resizing the map's
.I seg
array if necessary.
A negative return value indicates an allocation error.
.PP
.I Findseg
returns the index of the segment with the given name (and, if
.I file
is non-nil, the given file),
or \-1 if no such segment is found.
.PP
.I Addrtoseg
returns the index of the segment containing
for the given address, or \-1 if that address is not mapped.
Segments may have overlapping address ranges:
.I addseg
appends segments to the end of the
.I seg
array in the map, and
.I addrtoseg
searches the map backwards from the end,
so the most recently mapped segment wins.
.PP
.I Addrtosegafter
returns the index of the segment containing the lowest mapped
address greater than
.IR addr .
.PP
.I Removeseg
removes the segment at the given index.
.PP
.IR Get1 ,
.IR get2 ,
.IR get4 ,
and
.I get8
retrieve the data stored at address
.I addr
in the address space associated
with
.IR map .
.I Get1
retrieves
.I n
bytes of data beginning at
.I addr
into
.IR buf .
.IR Get2 ,
.I get4
and
.I get8
retrieve 16-bit, 32-bit and 64-bit values respectively,
into the location pointed to by
.IR u .
The value is byte-swapped if the source
byte order differs from that of the current architecture.
This implies that the value returned by
.IR get2 ,
.IR get4 ,
and
.I get8
may not be the same as the byte sequences
returned by
.I get1
when
.I n
is two, four or eight; the former may be byte-swapped, the
latter reflects the byte order of the target architecture.
These functions return the number
of bytes read or a \-1 when there is an error.
.PP
.IR Put1 ,
.IR put2 ,
.IR put4 ,
and
.I put8
write to
the address space associated with
.IR map .
The address is translated using the
map parameters and multi-byte quantities are
byte-swapped, if necessary, before they are written.
.I Put1
transfers
.I n
bytes stored at
.IR buf ;
.IR put2 ,
.IR put4 ,
and
.I put8
write the 16-bit, 32-bit or 64-bit quantity contained in
.IR val ,
respectively. The number of bytes transferred is returned.
A \-1 return value indicates an error.
.PP
When representing core files or running programs,
maps also provide access to the register set.
.IR Rget1 ,
.IR rget2 ,
.IR rget4 ,
.IR rget8 ,
.IR rput1 ,
.IR rput2 ,
.IR rput4 ,
and
.IR rput8
read or write the 1-, 2-, 4-, or 8-byte register
named by
.IR reg .
If the register is not the requested size, the
behavior is undefined.
.PP
.I Fpformat
converts the contents of a floating-point register to a string.
.I Buf
is the address of a buffer of
.I n
bytes to hold the resulting string.
.I Code
must be either
.L F
or
.LR f ,
selecting double or single precision, respectively.
If
.I code
is
.LR F ,
the contents of the specified register and the
following register are interpreted as a double-precision
floating-point number;
this is meaningful only for architectures that implement
double-precision floats by combining adjacent single-precision
registers.
.PP
A
.I location
represents a place in an executing image capable of
storing a value.
Note that locations are typically passed by value rather than by reference.
.PP
.I Locnone
returns an unreadable, unwritable location.
.I Locaddr
returns a location representing the memory address
.IR addr .
.I Locreg
returns a location representing the register
.IR reg .
.I Locindir
returns an location representing the memory address
at
.I offset
added to the value of
.IR reg .
.I Locconst
returns an imaginary unwritable location holding the constant
.IR con ;
such locations are useful for passing specific constants to
functions expect locations, such as
.I unwind
(see
.IR mach-stack (3)).
.PP
.I Loccmp
compares two locations, returning negative, zero, or positive
values if
.B *a
is less than, equal to, or greater than
.BR *b ,
respectively.
Register locations are ordered before memory addresses,
which are ordered before indirections.
.PP
.I Locfmt
is a
.IR print (3)-verb
that formats a
.B Loc
structure
.RI ( not
a pointer to one).
.PP
Indirection locations are needed in some contexts (e.g., when
using
.I findlsym
(see
.IR mach-symbol (3))),
but bothersome in most.
.I Locsimplify
rewrites indirections as absolute memory addresses, by evaluating
the register using the given map and adding the offset.
.PP
The functions
.IR lget1 ,
.IR lget2 ,
.IR lget4 ,
.IR lget8 ,
.IR lput1 ,
.IR lput2 ,
.IR lput4 ,
and
.I lput8
read and write the given locations, using the
.IR get ,
.IR put ,
.IR rget ,
and
.I rput
function families as necessary.
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR mach(3), mach-file(3)
.SH DIAGNOSTICS
These routines set
.IR errstr .

137
man/man3/mach-stack.3 Normal file
View file

@ -0,0 +1,137 @@
.TH MACH-STACK 3
.SH NAME
stacktrace,
localaddr,
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mach.h>
.PP
.ft B
.ta \w'\fBxxxxxx'u +\w'\fBxxxxxx'u
int stacktrace(Map *map, Rgetter rget, Tracer trace)
.PP
.ft B
int localvar(Map *map, char *fn, char *val, Loc *loc)
.SH DESCRIPTION
.I Stacktrace
provides machine-independent
implementations of process stack traces.
They must retrieve data and register contents from an executing
image. Sometimes the desired registers are not the current
registers but rather a set of saved registers stored elsewhere
in memory.
The caller may specify an initial register set in the form of an
.I Rgetter
function, of the form
.PP
.RS
.B "ulong rget(Map *map, char *name)
.RE
.PP
It returns the contents of a register when given a map
and a register name.
It is usually sufficient for the register function
to return meaningful values only for
.BR SP
and
.BR PC ,
and for the link register
(usually
.BR LR )
on CISC machines.
.PP
Given the map and the rgetter,
.I stacktrace
unwinds the stack starting at the innermost function.
At each level in the trace, it calls the tracer function, which has the form
.PP
.RS
.B "int trace(Map *map, ulong pc, ulong callerpc,
.br
.B " Rgetter rget, Symbol *s)
.RE
.PP
The tracer is passed the map, the current program counter,
the program counter of the caller (zero if the caller is unknown),
a new
.I rget
function, and a symbol
(see
.IR mach-symbol (3))
describing the current function
(nil if no symbol is known).
The value returned by the tracer
controls whether the stack trace continues:
a zero or negative return value stops the trace,
while a positive return value continues it.
.PP
The rgetter passed to the tracer is not the rgetter
passed to
.B stacktrace
itself.
Instead, it is a function returning the register values
at the time of the call, to the extent that they can be
reconstructed.
The most common use for this rgetter
is as an argument to
.IR lget4 ,
etc., when evaluating the locations of local variables.
.PP
.I Localvar
uses
.I stacktrace
to walk up the stack looking for the innermost instance of a function named
.I fn ;
once it finds the function,
it looks for the parameter or local variable
.IR var ,
storing the location of the variable in
.IR loc .
.SH EXAMPLE
The following code writes a simple stack trace to standard output,
stopping after at most 20 stack frames.
.RS
.ft B
.nf
.ta \w'xxxx'u +\w'xxxx'u +\w'xxxx'u +\w'xxxx'u +\w'xxxx'u
static int
trace(Map *map, ulong pc, ulong callerpc,
Rgetter rget, Symbol *s, int depth)
{
char buf[512];
int i, first;
u32int v;
Symbol s2;
if(sym)
print("%s+%lx", s->name, pc - loceval(s->loc));
else
print("%lux", pc);
print("(");
first = 0;
for(i=0; indexlsym(s, &i, &s2)>=0; i++){
if(s.class != CPARAM)
continue;
if(first++)
print(", ");
if(lget4(map, rget, s->loc, &v) >= 0)
print("%s=%#lux", s->name, (ulong)v);
else
print("%s=???", s->name);
}
print(") called from ");
symoff(buf, sizeof buf, callerpc, CTEXT);
print("%s\en", buf);
return depth < 20;
}
if(stacktrace(map, nil, trace) <= 0)
print("no stack frame\n");
.RE
.SH SOURCE
.B /sys/src/libmach
.SH SEE ALSO
.IR mach (3)

117
man/man3/mach-swap.3 Normal file
View file

@ -0,0 +1,117 @@
.TH MACH-SWAP 3
.SH NAME
beswap2, beswap4, beswap8, beieeeftoa32, beieeeftoa64, beieeeftoa80,
beload2, beload4, beload8,
leswap2, leswap4, leswap8, leieeeftoa32, leieeeftoa64, leieeeftoa80,
leload2, leload4, leload8, ieeeftoa32, ieeeftoa64 \- machine-independent access to byte-ordered data
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mach.h>
.PP
.ta \w'\fBu64intxx'u
.B
u16int beswap2(u16int u)
.br
u32int beswap4(u32int u)
.br
u64int beswap8(u64int u)
.PP
.B
int beieeeftoa32(char *a, uint n, void *f)
.br
int beieeeftoa64(char *a, uint n, void *f)
.br
int beieeeftoa80(char *a, uint n, void *f)
.PP
.B
u16int beload2(uchar *p)
.br
u32int beload4(uchar *p)
.br
u64int beload8(uchar *p)
.PP
.B
u16int leswap2(u16int u)
.br
u32int leswap4(u32int u)
.br
u64int leswap8(u64int u)
.PP
.B
int leieeeftoa32(char *a, uint n, void *f)
.br
int leieeeftoa64(char *a, uint n, void *f)
.br
int leieeeftoa80(char *a, uint n, void *f)
.PP
.B
u16int leload2(uchar *p)
.br
u32int leload4(uchar *p)
.br
u64int leload8(uchar *p)
.PP
.B
int ieeeftoa32(char *a, uint n, u32int u)
.br
int ieeeftoa64(char *a, uint n, u32int hi, u32int lo)
.SH DESCRIPTION
These functions provide
machine-independent access to data in a particular byte order.
.PP
.IR Beswap2 ,
.IR beswap4 ,
and
.I beswap8
return the 2-byte, 4-byte, and 8-byte
big-endian representation of the bytes in
.IR val ,
respectively.
.PP
.IR Beload2 ,
.IR beload4 ,
and
.I beload8
return the 2-byte, 4-byte, and 8-byte
big-endian interpretation of the bytes at
.IR p ,
respectively.
.PP
.IR Beieeeftoa32 ,
.IR beieeeftoa64 ,
and
.I beieeeftoa80
format the big-endian 4-byte, 8-byte, or 10-byte IEEE floating-point value
at
.IR f
into the
.IR n -byte
string buffer
.IR a .
.PP
.IR Leswap2 ,
.IR leswap4 ,
etc. are the little-endian equivalents of the routines just described.
.PP
.I Ieeeftoa32
and
.I ieeeftoa64
format a local machine byte-order floating-point value into the
.IR n -byte
string buffer
.IR a .
.I Ieeeftoa32
expects a 32-bit floating-point value stored in the bits of
.IR u .
.I Ieeeftoa64
expects a 64-bit floating-point value whose high 32-bits are in
.I hi
and low 32-bits are in
.IR lo .
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR mach (3)

324
man/man3/mach-symbol.3 Normal file
View file

@ -0,0 +1,324 @@
.TH MACH-SYMBOL 3
.SH NAME
symopen, symclose, indexsym, lookupsym, findsym,
lookuplsym, indexlsym, findlsym,
symoff, pc2file, file2pc, line2pc, fnbound, fileline,
pc2line \- symbol table access functions
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <mach.h>
.PP
.ta \w'\fBxxxxxx'u +\w'\fBxxxxxx'u
.ft B
int symopen(Fhdr *hdr)
.br
void symclose(Fhdr *hdr)
.PP
.ft B
int indexsym(uint n, Symbol *s)
.br
int lookupsym(char *fn, char *var, Symbol *s)
.br
int findsym(Loc loc, uint class, Symbol *s)
.PP
.ft B
int indexlsym(Symbol *s1, uint n, Symbol *s2)
.br
int lookuplsym(Symbol *s1, char *name, Symbol *s2)
.br
int findlsym(Symbol *s1, Loc loc, Symbol *s2)
.PP
.ft B
int symoff(char *a, uint n, ulong addr, uint class)
.PP
.ft B
int pc2file(ulong pc, char *file, uint n, ulong *line)
.br
int pc2line(ulong pc, ulong *line)
.br
int fileline(ulong pc, char *buf, uint n)
.br
int file2pc(char *file, ulong line, ulong *pc)
.br
int line2pc(ulong basepc, ulong line, ulong *pc)
.br
int fnbound(ulong pc, ulong bounds[2])
.SH DESCRIPTION
These functions provide machine-independent access to the
symbol table of an executable file or executing process.
.IR Mach (3),
.IR mach-file (3),
and
.IR mach-map (3)
describe additional library functions for
accessing executable files and executing processes.
.PP
.IR Symopen
uses the data in the
.B Fhdr
structure filled by
.I crackhdr
(see
.IR mach-file (3))
to initialize in-memory structures used to access the symbol
tables contained in the file.
.IR Symclose
frees the structures.
The rest of the functions described here access a composite
symbol table made up of all currently open tables.
.PP
The
.B Symbol
data structure:
.IP
.RS
.ft B
.nf
typedef struct Symbol Symbol;
struct Symbol
{
char *name;
Loc loc;
Loc hiloc;
char class;
char type;
\fI...\fP
};
.fi
.RE
.LP
describes a symbol table entry.
The
.B value
field contains the offset of the symbol within its
address space: global variables relative to the beginning
of the data segment, text beyond the start of the text
segment, and automatic variables and parameters relative
to the stack frame. The
.B type
field contains the type of the symbol:
.RS
.TP
.B T
text segment symbol
.TP
.B t
static text segment symbol
.TP
.B D
data segment symbol
.TP
.B d
static data segment symbol
.TP
.B B
bss segment symbol
.TP
.B b
static bss segment symbol
.TP
.B a
automatic (local) variable symbol
.TP
.B p
function parameter symbol
.RE
.PD
.LP
The
.B class
field assigns the symbol to a general class;
.BR CTEXT ,
.BR CDATA ,
.BR CAUTO ,
and
.B CPARAM
are the most popular.
.PP
.I Indexsym
stores information for the
.I n th
symbol into
.IR s .
The symbols are ordered by increasing address.
.PP
.I Lookupsym
fills a
.B Symbol
structure with symbol table information. Global variables
and functions are represented by a single name; local variables
and parameters are uniquely specified by a function and
variable name pair. Arguments
.I fn
and
.I var
contain the
name of a function and variable, respectively.
If both
are non-zero, the symbol table is searched for a parameter
or automatic variable. If only
.I var
is
zero, the text symbol table is searched for function
.IR fn .
If only
.I fn
is zero, the global variable table
is searched for
.IR var .
.PP
.I Findsym
returns the symbol table entry of type
.I class
stored near
.IR addr .
The selected symbol is a global variable or function with
address nearest to and less than or equal to
.IR addr .
Class specification
.B CDATA
searches only the global variable symbol table; class
.B CTEXT
limits the search to the text symbol table.
Class specification
.B CANY
searches the text table first, then the global table.
.PP
.IR Indexlsym ,
.IR lookuplsym ,
and
.IR findlsym
are similar to
.IR indexsym ,
.IR lookupsym ,
and
.IR findsym ,
but operate on the smaller symbol table of parameters and
variables local to the function represented by symbol
.IR s1 .
.PP
.I Indexlsym
writes symbol information for the
.IR n th
local symbol of function
.I s1
to
.IR s2 .
Function parameters appear first in the ordering, followed by local symbols.
.PP
.I Lookuplsym
writes symbol information for the symbol named
.I name
in function
.I s1
to
.IR s2 .
.PP
.I Findlsym
searches for a symbol local to the function
.I s1
whose location is exactly
.IR loc ,
writing its symbol information to
.IR s2 .
.I Loc
is almost always an indirection through a frame pointer register;
the details vary from architecture to architecture.
.PP
.I Symoff
converts a location to a symbol reference.
The string containing that reference is of the form
`name+offset', where `name' is the name of the
nearest symbol with an address less than or equal to the
target address, and `offset' is the hexadecimal offset beyond
that symbol. If `offset' is zero, only the name of the
symbol is printed.
If no symbol is found within 4096 bytes of the address, the address
is formatted as a hexadecimal address.
.I Buf
is the address of a buffer of
.I n
bytes to receive the formatted string.
.I Addr
is the address to be converted.
.I Type
is the type code of the search space:
.BR CTEXT ,
.BR CDATA ,
or
.BR CANY .
.I Symoff
returns the length of the formatted string contained in
.IR buf .
.PP
.I Pc2file
searches the symbol table to find the file and line number
corresponding to the instruction at program counter
.IR pc .
.I File
is the address of a buffer of
.I n
bytes to receive the file name.
.I Line
receives the line number.
.PP
.I Pc2line
is like
.I pc2file
but neglects to return information about the source file.
.PP
.I Fileline
is also like
.IR pc2file ,
but returns the file and line number in the
.IR n -byte
text buffer
.IR buf ,
formatted as
`file:line'.
.PP
.I File2pc
performs the opposite mapping:
it stores in
.I pc
a text address associated with
line
.I line
in file
.IR file .
.PP
.I Line2pc
is similar: it converts a line number to an
instruction address, storing it in
.IR pc .
Since a line number does not uniquely identify an
instruction (e.g., every source file has line 1),
.I basepc
specifies a text address from which
the search begins.
Usually this is the address of the first function in the
file of interest.
.PP
.I Fnbound
returns the start and end addresses of the function containing
the text address supplied as the first argument.
The second argument is an array of two unsigned longs;
.I fnbound
places the bounding addresses of the function in the
first and second elements of this array.
The start address is the address of the first instruction of the function;
the end address is the first address beyond the end of the target function.
.PP
All functions return 0 on success and \-1 on error.
When an error occurs, a message describing it is stored
in the system error buffer where it is available via
.IR errstr .
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR mach (3),
.IR mach-file (3),
.IR mach-map (3)

416
man/man3/mach.3
View file

@ -1,20 +1,13 @@
.TH MACH 3
.SH NAME
crackhdr, machbytype, machbyname, newmap, setmap, findseg, unusemap,
loadmap, attachproc, get1, get2, get4, get8, put1, put2, put4, put8,
beswab, beswal, beswav, leswab, leswal, leswav \- machine-independent access to executable files
machbytype, machbyname \- machine-independent access to executables and programs
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <bio.h>
.br
.B #include <mach.h>
.PP
.ta \w'\fLmachines 'u
.B
int crackhdr(int fd, Fhdr *fp)
.PP
.B
void machbytype(int type)
@ -23,371 +16,68 @@ void machbytype(int type)
int machbyname(char *name)
.PP
.B
Map *newmap(Map *map, int n)
.PP
.B
int setmap(Map *map, int fd, ulong base, ulong end,
.PP
.B
ulong foffset, char *name)
.PP
.B
int findseg(Map *map, char *name)
.PP
.B
void unusemap(Map *map, int seg)
.PP
.B
Map *loadmap(Map *map, int fd, Fhdr *fp)
.PP
.B
Map *attachproc(int pid, int kflag, int corefd, Fhdr *fp)
.PP
.B
int get1(Map *map, ulong addr, uchar *buf, int n)
.PP
.B
int get2(Map *map, ulong addr, ushort *val)
.PP
.B
int get4(Map *map, ulong addr, long *val)
.PP
.B
int get8(Map *map, ulong addr, vlong *val)
.PP
.B
int put1(Map *map, ulong addr, uchar *buf, int n)
.PP
.B
int put2(Map *map, ulong addr, ushort val)
.PP
.B
int put4(Map *map, ulong addr, long val)
.PP
.B
int put8(Map *map, ulong addr, vlong val)
.PP
.B
ushort beswab(ushort val)
.PP
.B
long beswal(long val)
.PP
.B
long beswav(vlong val)
.PP
.B
ushort leswab(ushort val)
.PP
.B
long leswal(long val)
.PP
.B
long leswav(vlong val)
.PP
.B
extern Mach mach;
.PP
.B
extern Machdata machdata;
extern Mach *mach;
.SH DESCRIPTION
These functions provide
a processor-independent interface for accessing
the executable files or executing images of all
architectures.
Related library functions described in
.IR symbol (2)
and
.IR object (2)
provide similar access to symbol tables and object files.
.I Libmach
provides an interface for accessing
the executable files and executing images of various architectures
and operating systems.
The interface is machine-independent, meaning that, for example,
Mac OS X core dumps may be inspected using an x86 Linux machine
and vice versa.
In its current form,
the library is mainly useful for writing debuggers
of one sort or another.
.PP
An
.I executable
is a file containing an executable program or the
.B text
file of the
.B /proc
file system associated with an executing process as
described in
.IR proc (3).
After opening an executable, an application
invokes a library function which parses the
file header,
determines the target architecture and
initializes data structures with parameters
and pointers to functions appropriate for
that architecture. Next, the application
invokes functions to construct one or more
.IR maps ,
data structures that translate references
in the address space of the executable
to offsets in the file. Each
.I map
comprises one or more
.BR segments ,
each associating a non-overlapping range of
memory addresses with a logical section of
the executable.
Other library functions then use a map
and the architecture-specific data structures
to provide a generic interface to the
processor-dependent data.
.PP
.I Crackhdr
interprets the header of the executable
associated with
the open file descriptor
.IR fd .
It loads the data structure
.I fp
with a machine-independent description
of the header information and
points global variable
.I mach
to the
An architecture is described primarily by a
.B Mach
data structure containing processor-dependent parameters
of the target architecture.
.PP
.I Machbytype
selects architecture-specific data structures and parameter
values based on
the code stored in the
field named
.I type
in the
.B Fhdr
data structure.
.I Machbyname
performs the same selection based
on the name of a processor class; see
.IR 2c (1)
for a list of valid names.
Both functions point global variables
structure, which contains
data structures and parameters describing the
particular architecture.
Most library functions assume that the global variable
.I mach
and
.I machdata
to the
.I Mach
and
.I Machdata
data structures appropriate for the
target architecture and load global variable
.I asstype
with the proper disassembler type code.
points at the structure for the architecture being debugged.
It is set implicitly by
.I crackhdr
(see
.IR mach-file (3))
and can be set explicitly by calling
.I machbyname
or
.IR machbytype .
.PP
.I Newmap
creates an empty map with
.I n
segments.
If
.I map
is zero, the new map is dynamically
allocated, otherwise it is assumed to
point to an existing dynamically allocated map whose
size is adjusted, as necessary.
A zero return value indicates an allocation error.
There is no operating system-specific structure akin to
.IR mach .
Typically the choice of operating system on a particular
architecture affects only the executable and core dump formats;
the various file parsers deduce the operating system from
information in the binary files themselves and adjust
accordingly.
.PP
.I Setmap
loads the first unused segment in
.I map
with the
segment mapping parameters.
.I Fd
is an open file descriptor associated with
an executable.
.I Base
and
.I end
contain the lowest and highest virtual addresses
mapped by the segment.
.I Foffset
is the offset to the start of the segment in the file.
.I Name
is a name to be attached to the segment.
Other manual pages
describe the library functions in detail.
.PP
.I Findseg
returns the index of the the
segment named
.I name
in
.IR map .
A return of -1 indicates that no
segment matches
.IR name .
.I Mach-file (3)
describes the manipulation of binary files.
.PP
.I Unusemap
marks segment number
.I seg
in map
.I map
unused. Other
segments in the map remain unaffected.
.I Mach-map (3)
describes the interface to address spaces and register sets
in executable files and executing programs.
.PP
.I Loadmap
initializes a default map containing
segments named `text' and `data' that
map the instruction and data segments
of the executable described in the
.B Fhdr
structure pointed to by
.IR fp .
Usually that structure was loaded by
.IR crackhdr
and can be passed to this function without
modification.
If
.I map
is non-zero, that map, which must have been
dynamically allocated, is resized to contain two segments;
otherwise a new map is allocated.
This function returns zero if allocation fails.
.I Loadmap
is usually used to build a map for accessing
a static executable, for example, an executable
program file.
.I Mach-stack (3)
describes support for unwinding the stack.
.PP
.I Attachproc
constructs a map for accessing a
running process. It
returns the address of a
.I Map
containing segments mapping the
address space of the running process
whose process ID is
.BR pid .
If
.B kflag
is non-zero, the process is assumed to be
a kernel process.
.B Corefd
is an file descriptor opened to
.BR /proc/\fIpid\fP/mem .
.B Fp
points to the
.I Fhdr
structure describing the header
of the executable. For most architectures
the resulting
.I Map
contains four segments named `text', `data',
`regs' and `fpregs'. The latter two provide access to
the general and floating point registers, respectively.
If the executable is a kernel process (indicated by a
non-zero
.B kflag
argument), the data segment extends to the maximum
supported address, currently 0xffffffff, and the
register sets are read-only. In user-level programs,
the data segment extends to the
top of the stack or 0x7fffffff if the stack top
cannot be found, and the register sets are readable
and writable.
.I Attachproc
returns zero if it is unable to build the map
for the specified process.
.I Mach-swap (3)
describes helper functions for accessing data
in a particular byte order.
.PP
.IR Get1 ,
.IR get2 ,
.IR get4 ,
and
.I get8
retrieve the data stored at address
.I addr
in the executable associated
with
.IR map .
.I Get1
retrieves
.I n
bytes of data beginning at
.I addr
into
.IR buf .
.IR Get2 ,
.I get4
and
.I get8
retrieve 16-bit, 32-bit and 64-bit values respectively,
into the location pointed to by
.IR val .
The value is byte-swapped if the source
byte order differs from that of the current architecture.
This implies that the value returned by
.IR get2 ,
.IR get4 ,
and
.I get8
may not be the same as the byte sequences
returned by
.I get1
when
.I n
is two, four or eight; the former may be byte-swapped, the
latter reflects the byte order of the target architecture.
If the file descriptor associated with the applicable segment in
.I map
is negative, the address itself is placed in the
return location. These functions return the number
of bytes read or a \-1 when there is an error.
.PP
.IR Put1 ,
.IR put2 ,
.IR put4 ,
and
.I put8
write to
the executable associated with
.IR map .
The address is translated using the
map parameters and multi-byte quantities are
byte-swapped, if necessary, before they are written.
.I Put1
transfers
.I n
bytes stored at
.IR buf ;
.IR put2 ,
.IR put4 ,
and
.I put8
write the 16-bit, 32-bit or 64-bit quantity contained in
.IR val ,
respectively. The number of bytes transferred is returned.
A \-1 return value indicates an error.
.PP
.IR Beswab ,
.IR beswal ,
and
.I beswav
return the
.BR ushort ,
.BR long ,
and
.B vlong
big-endian representation of
.IR val ,
respectively.
.IR Leswab ,
.IR leswal ,
and
.I leswav
return the little-endian representation of the
.BR ushort ,
.BR long ,
and
.B vlong
contained in
.IR val .
.I Mach-symbol (3)
describes the interface to debugging symbol information.
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR 2c (1),
.IR symbol (2),
.IR object (2),
.IR errstr (2),
.IR proc (3),
.IR a.out (6)
.SH DIAGNOSTICS
These routines set
.IR errstr .
.SH "SEE ALSO
.IR mach-file (3),
.IR mach-map (3),
.IR mach-stack (3),
.IR mach-swap (3),
.IR mach-symbol (3)

12
man/man3/malloc.3
View file

@ -132,7 +132,7 @@ these tags will be set properly.
If a custom allocator wrapper is used,
the allocator wrapper can set the tags
itself (usually by passing the result of
.IR getcallerpc (2)
.IR getcallerpc (3)
to
.IR setmalloctag )
to provide more useful information about
@ -143,7 +143,7 @@ takes the address of a block returned by
.I malloc
and returns the address of the corresponding
block allocated by the
.IR pool (2)
.IR pool (3)
routines.
.SH SOURCE
.B /sys/src/libc/port/malloc.c
@ -152,9 +152,9 @@ routines.
.I trump
(in
.IR acid (1)),
.IR brk (2),
.IR getcallerpc (2),
.IR pool (2)
.IR brk (3),
.IR getcallerpc (3),
.IR pool (3)
.SH DIAGNOSTICS
.I Malloc, realloc
and
@ -198,7 +198,7 @@ is bizarre.
.PP
User errors can corrupt the storage arena.
The most common gaffes are (1) freeing an already freed block,
(2) storing beyond the bounds of an allocated block, and (3)
(3) storing beyond the bounds of an allocated block, and (3)
freeing data that was not obtained from the allocator.
When
.I malloc

28
man/man3/memdraw.3
View file

@ -169,7 +169,7 @@ type defines memory-resident rectangular pictures and the methods to draw upon t
differ from
.BR Image s
(see
.IR draw (2))
.IR draw (3))
in that they are manipulated directly in user memory rather than by
RPCs to the
.B /dev/draw
@ -233,7 +233,7 @@ points back at the
.B Memdata
structure, so that the
memory allocator (see
.IR pool (2))
.IR pool (3))
can compact image memory
using
.IR memimagemove .
@ -273,7 +273,7 @@ images with a given rectangle and channel descriptor
(see
.B strtochan
in
.IR graphics (2)),
.IR graphics (3)),
creating a fresh
.B Memdata
structure and associated storage.
@ -326,7 +326,7 @@ and \-1 in case of an error.
.I Memfillcolor
fills an image with the given color, a 32-bit number as
described in
.IR color (2).
.IR color (3).
.PP
.IR Memarc ,
.IR mempoly ,
@ -344,7 +344,7 @@ are identical to the
and
.IR gendraw ,
routines described in
.IR draw (2),
.IR draw (3),
except that they operate on
.BR Memimage s
rather than
@ -368,9 +368,9 @@ analogues of
and
.B string
(see
.IR subfont (2)
.IR subfont (3)
and
.IR graphics (2)),
.IR graphics (3)),
except that they operate
only on
.BR Memsubfont s
@ -435,13 +435,13 @@ prints to a serial line rather than the screen, for obvious reasons.
.SH SOURCE
.B /sys/src/libmemdraw
.SH SEE ALSO
.IR addpt (2),
.IR color (2),
.IR draw (2),
.IR graphics (2),
.IR memlayer (2),
.IR stringsize (2),
.IR subfont (2),
.IR addpt (3),
.IR color (3),
.IR draw (3),
.IR graphics (3),
.IR memlayer (3),
.IR stringsize (3),
.IR subfont (3),
.IR color (6),
.IR utf (6)
.SH BUGS

16
man/man3/memlayer.3
View file

@ -97,18 +97,18 @@ int memunload(Memimage *i, Rectangle r,
.PP
.SH DESCRIPTION
These functions build upon the
.IR memdraw (2)
.IR memdraw (3)
interface to maintain overlapping graphical windows on in-memory images.
They are used by the kernel to implement the windows interface presented by
.IR draw (3)
and
.IR window (2)
.IR window (3)
and probably have little use outside of the kernel.
.PP
The basic function is to extend the definition of a
.B Memimage
(see
.IR memdraw (2))
.IR memdraw (3))
to include overlapping windows defined by the
.B Memlayer
type.
@ -270,7 +270,7 @@ They have the signatures of
and
.I memimageline
(see
.IR memdraw (2))
.IR memdraw (3))
but accept
.B Memlayer
or
@ -298,8 +298,8 @@ are in compressed image format
.SH SOURCE
.B /sys/src/libmemlayer
.SH SEE ALSO
.IR graphics (2),
.IR memdraw (2),
.IR stringsize (2),
.IR window (2),
.IR graphics (3),
.IR memdraw (3),
.IR stringsize (3),
.IR window (3),
.IR draw (3)

6
man/man3/mktemp.3
View file

@ -27,7 +27,7 @@ to
.L z
are tried until a name that can be accessed
(see
.IR access (2))
.IR access (3))
is generated.
If no such name can be generated,
.I mktemp
@ -36,5 +36,5 @@ returns
.SH SOURCE
.B /sys/src/libc/port/mktemp.c
.SH "SEE ALSO"
.IR getpid (2),
.IR access (2)
.IR getpid (3),
.IR access (3)

26
man/man3/mouse.3
View file

@ -49,9 +49,9 @@ They use the message-passing
.B Channel
interface in the threads library
(see
.IR thread (2));
.IR thread (3));
programs that wish a more event-driven, single-threaded approach should use
.IR event (2).
.IR event (3).
.PP
The state of the mouse is recorded in a structure,
.BR Mouse ,
@ -107,7 +107,7 @@ are a
naming the device file connected to the mouse and an
.I Image
(see
.IR draw (2))
.IR draw (3))
on which the mouse will be visible.
Typically the file is
nil,
@ -136,7 +136,7 @@ The actual value sent may be discarded; the receipt of the message
tells the program that it should call
.B getwindow
(see
.IR graphics (2))
.IR graphics (3))
to reconnect to the window.
.PP
.I Readmouse
@ -150,7 +150,7 @@ or message sent on the channel.
It calls
.B flushimage
(see
.IR graphics (2))
.IR graphics (3))
before blocking, so any buffered graphics requests are displayed.
.PP
.I Closemouse
@ -172,7 +172,7 @@ is nil, the cursor is set to the default.
The format of the cursor data is spelled out in
.B <cursor.h>
and described in
.IR graphics (2).
.IR graphics (3).
.PP
.I Getrect
returns the dimensions of a rectangle swept by the user, using the mouse,
@ -218,7 +218,7 @@ struct Menu
behaves the same as its namesake
.I emenuhit
described in
.IR event (2),
.IR event (3),
with two exceptions.
First, it uses a
.B Mousectl
@ -228,7 +228,7 @@ it creates the menu as a true window on the
.B Screen
.I scr
(see
.IR window (2)),
.IR window (3)),
permitting the menu to be displayed in parallel with other activities on the display.
If
.I scr
@ -242,8 +242,8 @@ restoring the display when the menu is removed.
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2),
.IR draw (2),
.IR event (2),
.IR keyboard (2),
.IR thread (2).
.IR graphics (3),
.IR draw (3),
.IR event (3),
.IR keyboard (3),
.IR thread (3).

4
man/man3/mp.3
View file

@ -313,9 +313,9 @@ is
the buffer is allocated.
.I Mpfmt
can be used with
.IR fmtinstall (2)
.IR fmtinstall (3)
and
.IR print (2)
.IR print (3)
to print hexadecimal representations of
.BR mpint s.
.PP

14
man/man3/notify.3
View file

@ -22,7 +22,7 @@ is posted to communicate the exception.
A note may also be posted by a
.I write
(see
.IR read (2))
.IR read (3))
to the process's
.BI /proc/ n /note
file or to the
@ -55,10 +55,10 @@ replaces the previous handler, if any.
An argument of zero cancels a previous handler,
restoring the default action.
A
.IR fork (2)
.IR fork (3)
system call leaves the handler registered in
both the parent and the child;
.IR exec (2)
.IR exec (3)
restores the default behavior.
Handlers may not perform floating point operations.
.PP
@ -115,7 +115,7 @@ set up with
using the
.I notejmp
function (see
.IR setjmp (2)),
.IR setjmp (3)),
which is implemented by modifying the saved state and calling
.BR noted(NCONT) .
.PP
@ -233,12 +233,12 @@ portions of the notes are machine-dependent.
.br
.B /sys/src/libc/port/atnotify.c
.SH SEE ALSO
.IR intro (2),
.IR intro (3),
.I notejmp
in
.IR setjmp (2)
.IR setjmp (3)
.SH BUGS
Since
.IR exec (2)
.IR exec (3)
discards the notification handler, there is a window
of vulnerability to notes in a new process.

16
man/man3/open.3
View file

@ -34,7 +34,7 @@ says to truncate the file
to zero length before opening it;
.B OCEXEC
says to close the file when an
.IR exec (2)
.IR exec (3)
or
.I execl
system call is made;
@ -45,7 +45,7 @@ says to remove the file when it is closed (by everyone who has a copy of the fil
fails if the file does not exist or the user does not have
permission to open it for the requested purpose
(see
.IR stat (2)
.IR stat (3)
for a description of permissions).
The user must have write permission on the
.I file
@ -58,7 +58,7 @@ system call
(unlike the implicit
.I open
in
.IR exec (2)),
.IR exec (3)),
.B OEXEC
is actually identical to
.BR OREAD .
@ -108,10 +108,10 @@ In the last case, the file may be created even when
an error is returned.
If the file is new and the directory in which it is created is
a union directory (see
.IR intro (2))
.IR intro (3))
then the constituent directory where the file is created
depends on the structure of the union: see
.IR bind (2).
.IR bind (3).
.PP
Since
.I create
@ -140,9 +140,9 @@ allows the file descriptor to be reused.
.SH SOURCE
.B /sys/src/libc/9syscall
.SH SEE ALSO
.IR intro (2),
.IR bind (2),
.IR stat (2)
.IR intro (3),
.IR bind (3),
.IR stat (3)
.SH DIAGNOSTICS
These functions set
.IR errstr .

12
man/man3/pipe.3
View file

@ -25,7 +25,7 @@ is available for reading from
After the pipe has been established,
cooperating processes
created by subsequent
.IR fork (2)
.IR fork (3)
calls may pass data through the
pipe with
.I read
@ -41,7 +41,7 @@ when the read buffer is full or after reading the last byte
of a write, whichever comes first.
.PP
The number of bytes available to a
.IR read (2)
.IR read (3)
is reported
in the
.B Length
@ -50,17 +50,17 @@ field returned by
or
.I dirfstat
on a pipe (see
.IR stat (2)).
.IR stat (3)).
.PP
When all the data has been read from a pipe and the writer has closed the pipe or exited,
.IR read (2)
.IR read (3)
will return 0 bytes. Writes to a pipe with no reader will generate a note
.BR "sys: write on closed pipe" .
.SH SOURCE
.B /sys/src/libc/9syscall
.SH SEE ALSO
.IR intro (2),
.IR read (2),
.IR intro (3),
.IR read (3),
.IR pipe (3)
.SH DIAGNOSTICS
Sets

8
man/man3/plumb.3
View file

@ -84,7 +84,7 @@ struct Plumbattr
opens the named plumb
.IR port ,
using
.IR open (2)
.IR open (3)
mode
.IR omode .
If
@ -97,7 +97,7 @@ searches for the location of the
service and opens the port there.
.PP
For programs using the
.IR event (2)
.IR event (3)
interface,
.I eplumb
registers, using the given
@ -130,7 +130,7 @@ to
frees all the data associated with the message
.IR m ,
all the components of which must therefore have been allocated with
.IR malloc (2).
.IR malloc (3).
.PP
.I Plumbrecv
returns the next message available on the file descriptor
@ -230,7 +230,7 @@ is a no-op if no such attribute exists.
.B /sys/src/libplumb
.SH SEE ALSO
.IR plumb (1),
.IR event (2),
.IR event (3),
.IR plumber (4),
.IR plumb (6)
.SH DIAGNOSTICS

8
man/man3/pool.3
View file

@ -213,7 +213,7 @@ when finished.
When internal corruption is detected,
.B panic
is called with a
.IR print (2)
.IR print (3)
style argument that specifies what happened.
It is assumed that
.B panic
@ -222,7 +222,7 @@ 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 (2)
.IR print (3)
style argument.
.PP
.B Flags
@ -322,8 +322,8 @@ return it to the free pool.
.SH SOURCE
.B /sys/src/libc/port/pool.c
.SH SEE ALSO
.IR malloc (2),
.IR brk (2)
.IR malloc (3),
.IR brk (3)
.PP
.B /sys/src/libc/port/malloc.c
is a complete example.

4
man/man3/postnote.3
View file

@ -41,8 +41,8 @@ Otherwise \-1 is returned.
.SH SOURCE
.B /sys/src/libc/9sys/postnote.c
.SH "SEE ALSO"
.IR notify (2),
.IR intro (2),
.IR notify (3),
.IR intro (3),
.IR proc (3)
.SH DIAGNOSTICS
Sets

10
man/man3/prime.3
View file

@ -93,8 +93,8 @@ slow algorithm.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR aes (2)
.IR blowfish (2),
.IR des (2),
.IR elgamal (2),
.IR rsa (2),
.IR aes (3)
.IR blowfish (3),
.IR des (3),
.IR elgamal (3),
.IR rsa (3),

16
man/man3/quote.3
View file

@ -58,10 +58,10 @@ The empty string is represented by two quotes,
The first four functions act as variants of
.B strdup
(see
.IR strcat (2)).
.IR strcat (3)).
Each returns a
freshly allocated copy of the string, created using
.IR malloc (2).
.IR malloc (3).
.I Quotestrdup
returns a quoted copy of
.IR s ,
@ -75,7 +75,7 @@ The
versions of these functions do the same for
.CW Rune
strings (see
.IR runestrcat (2)).
.IR runestrcat (3)).
.PP
The string returned by
.I quotestrdup
@ -130,7 +130,7 @@ function that flags any character special to
and
.I quoterunestrfmt
are
.IR print (2)
.IR print (3)
formatting routines that produce quoted strings as output.
They may be installed by hand, but
.I quotefmtinstall
@ -154,7 +154,7 @@ statements so the compiler can type-check uses of
and
.B %Q
in
.IR print (2)
.IR print (3)
format strings.
.SH SOURCE
.B /sys/src/libc/port/quote.c
@ -162,6 +162,6 @@ format strings.
.B /sys/src/libc/fmt/fmtquote.c
.SH "SEE ALSO
.IR rc (1),
.IR malloc (2),
.IR print (2),
.IR strcat (2)
.IR malloc (3),
.IR print (3),
.IR strcat (3)

6
man/man3/rand.3
View file

@ -125,7 +125,7 @@ truly random bytes read from
.PP
.I Prng
uses the native
.IR rand (2)
.IR rand (3)
pseudo-random number generator to fill the buffer. Used with
.IR srand ,
this function can produce a reproducible stream of pseudo random
@ -138,7 +138,7 @@ and
may be passed to
.I mprand
(see
.IR mp (2)).
.IR mp (3)).
.PP
.I Fastrand
uses
@ -167,7 +167,7 @@ to return a uniform
.B /sys/src/libsec/port/*fastrand.c
.SH "SEE ALSO
.IR cons (3),
.IR mp (2),
.IR mp (3),
.SH BUGS
.I Truerand
and

20
man/man3/rc4.3
View file

@ -43,13 +43,13 @@ structure keeps track of the algorithm.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR blowfish (2),
.IR des (2),
.IR dsa (2),
.IR elgamal (2),
.IR rsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)
.IR mp (3),
.IR aes (3),
.IR blowfish (3),
.IR des (3),
.IR dsa (3),
.IR elgamal (3),
.IR rsa (3),
.IR sechash (3),
.IR prime (3),
.IR rand (3)

12
man/man3/read.3
View file

@ -65,7 +65,7 @@ if this is not the same as requested.
and
.I Pwrite
equivalent to a
.IR seek (2)
.IR seek (3)
to
.I offset
followed by a
@ -85,11 +85,11 @@ without interference.
.br
.B /sys/src/libc/port/readn.c
.SH SEE ALSO
.IR intro (2),
.IR open (2),
.IR dup (2),
.IR pipe (2),
.IR readv (2)
.IR intro (3),
.IR open (3),
.IR dup (3),
.IR pipe (3),
.IR readv (3)
.SH DIAGNOSTICS
These functions set
.IR errstr .

8
man/man3/readv.3
View file

@ -29,7 +29,7 @@ long writev(int fd, IOchunk *io, int nio)
long pwritev(int fd, IOchunk *io, int nio, vlong off)
.SH DESCRIPTION
These functions supplement the standard read and write operations of
.IR read (2)
.IR read (3)
with facilities for scatter/gather I/O.
The set of I/O buffers is collected into an array of
.B IOchunk
@ -67,14 +67,14 @@ are the analogous write routines.
.br
.B /sys/src/libc/9sys/writev.c
.SH SEE ALSO
.IR intro (2),
.IR read (2)
.IR intro (3),
.IR read (3)
.SH DIAGNOSTICS
These functions set
.IR errstr .
.SH BUGS
The implementations use
.IR malloc (2)
.IR malloc (3)
to build a single buffer for a standard call to
.B read
or

2
man/man3/regexp.3
View file

@ -42,7 +42,7 @@ compiles a
regular expression and returns
a pointer to the generated description.
The space is allocated by
.IR malloc (2)
.IR malloc (3)
and may be released by
.IR free .
Regular expressions are exactly as in

4
man/man3/remove.3
View file

@ -20,12 +20,12 @@ is a directory, it must be empty.
.SH SOURCE
.B /sys/src/libc/9syscall
.SH SEE ALSO
.IR intro (2),
.IR intro (3),
.IR remove (5),
the description of
.B ORCLOSE
in
.IR open (2).
.IR open (3).
.SH DIAGNOSTICS
Sets
.IR errstr .

10
man/man3/rendezvous.3
View file

@ -13,9 +13,9 @@ The rendezvous system call allows two processes to synchronize and
exchange a value.
In conjunction with the shared memory system calls
(see
.IR segattach (2)
.IR segattach (3)
and
.IR fork (2)),
.IR fork (3)),
it enables parallel programs to control their scheduling.
.PP
Two processes wishing to synchronize call
@ -42,7 +42,7 @@ inherited when a process forks, unless
is set in the argument to
.BR rfork ;
see
.IR fork (2).
.IR fork (3).
.PP
If a rendezvous is interrupted the return value is
.BR ~0 ,
@ -50,8 +50,8 @@ so that value should not be used in normal communication.
.SH SOURCE
.B /sys/src/libc/9syscall
.SH SEE ALSO
.IR segattach (2),
.IR fork (2)
.IR segattach (3),
.IR fork (3)
.SH DIAGNOSTICS
Sets
.IR errstr .

22
man/man3/rsa.3
View file

@ -162,7 +162,7 @@ The subject line is conventionally of the form
"C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric"
.EE
using the quoting conventions of
.IR tokenize (2).
.IR tokenize (3).
.PP
.I Asn1toRSApriv
converts an ASN1 formatted RSA private key into the corresponding
@ -189,14 +189,14 @@ is undefined.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR blowfish (2),
.IR des (2),
.IR dsa (2),
.IR elgamal (2),
.IR rc4 (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2),
.IR mp (3),
.IR aes (3),
.IR blowfish (3),
.IR des (3),
.IR dsa (3),
.IR elgamal (3),
.IR rc4 (3),
.IR sechash (3),
.IR prime (3),
.IR rand (3),
.IR x509 (8)

8
man/man3/runestrcat.3
View file

@ -56,12 +56,12 @@ Rune* runestrstr(Rune *s1, Rune *s2)
.SH DESCRIPTION
These functions are rune string analogues of
the corresponding functions in
.IR strcat (2).
.IR strcat (3).
.SH SOURCE
.B /sys/src/libc/port
.SH SEE ALSO
.IR memory (2),
.IR rune (2),
.IR strcat (2)
.IR memory (3),
.IR rune (3),
.IR strcat (3)
.SH BUGS
The outcome of overlapping moves varies among implementations.

14
man/man3/sechash.3
View file

@ -137,14 +137,14 @@ and
.I sha1unpickle
unmarshal a pickled digest.
All four routines return a pointer to a newly
.IR malloc (2)'d
.IR malloc (3)'d
object.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR aes (2),
.IR blowfish (2),
.IR des (2),
.IR elgamal (2),
.IR rc4 (2),
.IR rsa (2)
.IR aes (3),
.IR blowfish (3),
.IR des (3),
.IR elgamal (3),
.IR rc4 (3),
.IR rsa (3)

4
man/man3/seek.3
View file

@ -39,8 +39,8 @@ Seeking in a pipe is a no-op.
.SH SOURCE
.B /sys/src/libc/9syscall
.SH SEE ALSO
.IR intro (2),
.IR open (2)
.IR intro (3),
.IR open (3)
.SH DIAGNOSTICS
Sets
.IR errstr .

4
man/man3/setjmp.3
View file

@ -46,7 +46,7 @@ was called.
is the same as
.I longjmp
except that it is to be called from within a note handler (see
.IR notify (2)).
.IR notify (3)).
The
.I uregs
argument should be the first argument passed to the note handler.
@ -90,7 +90,7 @@ setlabel(void)
.br
.B /sys/src/libc/$objtype/notejmp.c
.SH SEE ALSO
.IR notify (2)
.IR notify (3)
.SH BUGS
.PP
.I Notejmp

4
man/man3/sleep.3
View file

@ -27,7 +27,7 @@ Sleep returns \-1 if interrupted, 0 otherwise.
causes an
.B alarm
note (see
.IR notify (2))
.IR notify (3))
to be sent to the invoking process after the number of milliseconds
given by the argument.
Successive calls to
@ -39,7 +39,7 @@ the alarm clock.
.SH SOURCE
.B /sys/src/libc/9syscall
.SH SEE ALSO
.IR intro (2)
.IR intro (3)
.SH DIAGNOSTICS
These functions set
.IR errstr .

10
man/man3/stat.3
View file

@ -105,7 +105,7 @@ struct Dir {
.EE
.PP
The returned structure is allocated by
.IR malloc (2);
.IR malloc (3);
freeing it also frees the associated strings.
.PP
This structure and
@ -292,9 +292,9 @@ routines
for the routines prefixed
.B dir
.SH SEE ALSO
.IR intro (2),
.IR fcall (2),
.IR dirread (2),
.IR intro (3),
.IR fcall (3),
.IR dirread (3),
.IR stat (5)
.SH DIAGNOSTICS
The
@ -314,7 +314,7 @@ or
is too short for the returned data, the return value will be
.B BIT16SZ
(see
.IR fcall (2))
.IR fcall (3))
and the two bytes
returned will contain the initial count field of the
returned data;

10
man/man3/strcat.3
View file

@ -222,7 +222,7 @@ is returned.
returns a pointer to a distinct copy of the null-terminated string
.I s
in space obtained from
.IR malloc (2)
.IR malloc (3)
or
.L 0
if no space can be obtained.
@ -248,14 +248,14 @@ Many also have machine-dependent assembly language
implementations in
.BR /sys/src/libc/$objtype .
.SH SEE ALSO
.IR memory (2),
.IR rune (2),
.IR runestrcat (2)
.IR memory (3),
.IR rune (3),
.IR runestrcat (3)
.SH BUGS
These routines know nothing about
.SM UTF.
Use the routines in
.IR rune (2)
.IR rune (3)
as appropriate.
Note, however, that the definition of
.SM UTF

2
man/man3/string.3
View file

@ -233,4 +233,4 @@ and discard all other lines beginning with
.SH SOURCE
.B /sys/src/libString
.SH SEE ALSO
.IR bio (2)
.IR bio (3)

8
man/man3/stringsize.3
View file

@ -57,10 +57,10 @@ are analogous, but accept an array of runes rather than
.SH SOURCE
.B /sys/src/libdraw
.SH "SEE ALSO"
.IR addpt (2),
.IR cachechars (2),
.IR subfont (2),
.IR draw (2),
.IR addpt (3),
.IR cachechars (3),
.IR subfont (3),
.IR draw (3),
.IR draw (3),
.IR image (6),
.IR font (6)

20
man/man3/subfont.3
View file

@ -53,13 +53,13 @@ Font* mkfont(Subfont *f, Rune min)
.SH DESCRIPTION
Subfonts are the components of fonts that hold the character images.
A font comprises an array of subfonts; see
.IR cachechars (2).
.IR cachechars (3).
A new
.B Subfont
is allocated and initialized with
.IR allocsubfont .
See
.IR cachechars (2)
.IR cachechars (3)
for the meaning of
.IR n ,
.IR height ,
@ -97,7 +97,7 @@ on
if
.B f->info
was not allocated by
.IR malloc (2)
.IR malloc (3)
it should be zeroed before calling
.IR subffree .
.PP
@ -181,13 +181,13 @@ the part of a subfont file that comes after the image. It should be preceded by
a call to
.IR writeimage
(see
.IR allocimage (2)).
.IR allocimage (3)).
.PP
.I Stringsubfont
is analogous to
.B string
(see
.IR draw (2))
.IR draw (3))
for subfonts. Rather than use the underlying font caching primitives,
it calls
.B draw
@ -224,12 +224,12 @@ bitmap font file tree
.SH SOURCE
.B /sys/src/libdraw
.SH SEE ALSO
.IR graphics (2),
.IR allocimage (2),
.IR draw (2),
.IR cachechars (2),
.IR graphics (3),
.IR allocimage (3),
.IR draw (3),
.IR cachechars (3),
.IR image (6),
.IR font (6)
.SH DIAGNOSTICS
All of the functions use the graphics error function (see
.IR graphics (2)).
.IR graphics (3)).

436
man/man3/symbol.3
View file

@ -1,436 +0,0 @@
.TH SYMBOL 3
.SH NAME
syminit, getsym, symbase, pc2sp, pc2line, textseg, line2addr, lookup, findlocal,
getauto, findsym, localsym, globalsym, textsym, file2pc, fileelem, filesym,
fileline, fnbound \- symbol table access functions
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <bio.h>
.br
.B #include <mach.h>
.PP
.ta \w'\fLmachines 'u
.B
int syminit(int fd, Fhdr *fp)
.PP
.B
Sym *getsym(int index)
.PP
.B
Sym *symbase(long *nsyms)
.PP
.B
int fileelem(Sym **fp, uchar *encname, char *buf, int n)
.PP
.B
int filesym(int index, char *buf, int n)
.PP
.B
long pc2sp(ulong pc)
.PP
.B
long pc2line(ulong pc)
.PP
.B
void textseg(ulong base, Fhdr *fp)
.PP
.B
long line2addr(ulong line, ulong basepc)
.PP
.B
int lookup(char *fn, char *var, Symbol *s)
.PP
.B
int findlocal(Symbol *s1, char *name, Symbol *s2)
.PP
.B
int getauto(Symbol *s1, int off, int class, Symbol *s2)
.PP
.B
int findsym(long addr, int class, Symbol *s)
.PP
.B
int localsym(Symbol *s, int index)
.PP
.B
int globalsym(Symbol *s, int index)
.PP
.B
int textsym(Symbol *s, int index)
.PP
.B
long file2pc(char *file, ulong line)
.PP
.B
int fileline(char *str, int n, ulong addr)
.PP
.B
int fnbound(long addr, ulong *bounds)
.SH DESCRIPTION
These functions provide machine-independent access to the
symbol table of an executable file or executing process.
The latter is accessible by opening the device
.B /proc/\fIpid\fP/text
as described in
.IR proc (3).
.IR Mach (2)
and
.IR object (2)
describe additional library functions
for processing executable and object files.
.PP
.IR Syminit ,
.IR getsym ,
.IR symbase ,
.IR fileelem ,
.IR pc2sp ,
.IR pc2line ,
and
.I line2addr
process the symbol table contained in an executable file
or the
.B text
image of an executing program.
The symbol table is stored internally as an array of
.B Sym
data structures as defined in
.IR a.out (6).
.PP
.I Syminit
uses the data in the
.B Fhdr
structure filled by
.I crackhdr
(see
.IR mach (2))
to read the raw symbol tables from the open file descriptor
.IR fd .
It returns the count of the number of symbols
or \-1 if an error occurs.
.PP
.I Getsym
returns the address of the
.IR i th
.B Sym
structure or zero if
.I index
is out of range.
.PP
.I Symbase
returns the address of the first
.B Sym
structure in the symbol table. The number of
entries in the symbol table is returned in
.IR nsyms .
.PP
.I Fileelem
converts a file name, encoded as described in
.IR a.out (6),
to a character string.
.I Fp
is the base of
an array of pointers to file path components ordered by path index.
.I Encname
is the address of an array of encoded
file path components in the form of a
.B z
symbol table entry.
.I Buf
and
.I n
specify the
address of a receiving character buffer and its length.
.I Fileelem
returns the length of the null-terminated string
that is at most
.IR n \-1
bytes long.
.PP
.I Filesym
is a higher-level interface to
.IR fileelem .
It fills
.I buf
with the name of the
.IR i th
file and returns the length of the null-terminated string
that is at most
.IR n \-1
bytes long.
File names are retrieved in no particular order, although
the order of retrieval does not vary from one pass to the next.
A zero is returned when
.I index
is too large or too small or an error occurs during file name
conversion.
.PP
.I Pc2sp
returns an offset associated with
a given value of the program counter. Adding this offset
to the current value of the stack pointer gives the address
of the current stack frame. This approach only applies
to the 68020 architecture; other architectures
use a fixed stack frame offset by a constant contained
in a dummy local variable (called
.BR .frame )
in the symbol table.
.PP
.I Pc2line
returns the line number of the statement associated
with the instruction address
.IR pc .
The
line number is the absolute line number in the
source file as seen by the compiler after pre-processing; the
original line number in the source file may be derived from this
value using the history stacks contained in the symbol table.
.PP
.I Pc2sp
and
.I pc2line
must know the start and end addresses of the text segment
for proper operation. These values are calculated from the
file header by function
.IR syminit .
If the text segment address is changed, the application
program must invoke
.I textseg
to recalculate the boundaries of the segment.
.I Base
is the new base address of the text segment and
.I fp
points to the
.I Fhdr
data structure filled by
.IR crackhdr .
.PP
.I Line2addr
converts a line number to an instruction address. The
first argument is the absolute line number in
a file. Since a line number does not uniquely identify
an instruction location (e.g., every source file has line 1),
a second argument specifies a text address
from which the search begins. Usually this
is the address of the first function in the file of interest.
.PP
.IR Pc2sp ,
.IR pc2line ,
and
.I line2addr
return \-1 in the case of an error.
.PP
.IR Lookup ,
.IR findlocal ,
.IR getauto ,
.IR findsym ,
.IR localsym ,
.IR globalsym ,
.IR textsym ,
.IR file2pc ,
and
.I fileline
operate on data structures riding above the raw symbol table.
These data structures occupy memory
and impose a startup penalty but speed retrievals
and provide higher-level access to the basic symbol
table data.
.I Syminit
must be called
prior to using these functions.
The
.B Symbol
data structure:
.IP
.EX
typedef struct {
void *handle; /* private */
struct {
char *name;
long value;
char type;
char class;
};
} Symbol;
.EE
.LP
describes a symbol table entry.
The
.B value
field contains the offset of the symbol within its
address space: global variables relative to the beginning
of the data segment, text beyond the start of the text
segment, and automatic variables and parameters relative
to the stack frame. The
.B type
field contains the type of the symbol as defined in
.IR a.out (6).
The
.B class
field assigns the symbol to a general class;
.BR CTEXT ,
.BR CDATA ,
.BR CAUTO ,
and
.B CPARAM
are the most popular.
.PP
.I Lookup
fills a
.B Symbol
structure with symbol table information. Global variables
and functions are represented by a single name; local variables
and parameters are uniquely specified by a function and
variable name pair. Arguments
.I fn
and
.I var
contain the
name of a function and variable, respectively.
If both
are non-zero, the symbol table is searched for a parameter
or automatic variable. If only
.I var
is
zero, the text symbol table is searched for function
.IR fn .
If only
.I fn
is zero, the global variable table
is searched for
.IR var .
.PP
.I Findlocal
fills
.I s2
with the symbol table data of the automatic variable
or parameter matching
.IR name .
.I S1
is a
.B Symbol
data structure describing a function or a local variable;
the latter resolves to its owning function.
.PP
.I Getauto
searches the local symbols associated with function
.I s1
for an automatic variable or parameter located at stack
offset
.IR off .
.I Class
selects the class of
variable:
.B CAUTO
or
.BR CPARAM .
.I S2
is the address of a
.B Symbol
data structure to receive the symbol table information
of the desired symbol.
.PP
.I Findsym
returns the symbol table entry of type
.I class
stored near
.IR addr .
The selected symbol is a global variable or function
with address nearest to and less than or equal to
.IR addr .
Class specification
.B CDATA
searches only the global variable symbol table; class
.B CTEXT
limits the search to the text symbol table.
Class specification
.B CANY
searches the text table first, then the global table.
.PP
.I Localsym
returns the
.IR i th
local variable in the function
associated with
.IR s .
.I S
may reference a function or a local variable; the latter
resolves to its owning function.
If the
.IR i th
local symbol exists,
.I s
is filled with the data describing it.
.PP
.I Globalsym
loads
.I s
with the symbol table information of the
.IR i th
global variable.
.PP
.I Textsym
loads
.I s
with the symbol table information of the
.IR i th
text symbol. The text symbols are ordered
by increasing address.
.PP
.I File2pc
returns a text address associated with
.I line
in file
.IR file ,
or -1 on an error.
.PP
.I Fileline
converts text address
.I addr
to its equivalent
line number in a source file. The result,
a null terminated character string of
the form
.LR file:line ,
is placed in buffer
.I str
of
.I n
bytes.
.PP
.I Fnbound
returns the start and end addresses of the function containing
the text address supplied as the first argument. The second
argument is an array of two unsigned longs;
.I fnbound
places the bounding addresses of the function in the first
and second elements of this array. The start address is the
address of the first instruction of the function; the end
address is the address of the start of the next function
in memory, so it is beyond the end of the target function.
.I Fnbound
returns 1 if the address is within a text function, or zero
if the address selects no function.
.PP
Functions
.I file2pc
and
.I fileline
may produce inaccurate results when applied to
optimized code.
.PP
Unless otherwise specified, all functions return 1
on success, or 0 on error. When an error occurs,
a message describing it is stored in the system
error buffer where it is available via
.IR errstr .
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR mach (2),
.IR object (2),
.IR errstr (2),
.IR proc (3),
.IR a.out (6)

26
man/man3/thread.3
View file

@ -181,7 +181,7 @@ returning the id of the created thread.
creates the new proc by calling
.B rfork
(see
.IR fork (2))
.IR fork (3))
with flags
.BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
(The thread library depends on all its procs
@ -243,10 +243,10 @@ in arbitrary ways and should synchronize their
actions using
.B qlocks
(see
.IR lock (2))
.IR lock (3))
or channel communication.
System calls such as
.IR read (2)
.IR read (3)
block the entire proc;
all threads in a proc block until the system call finishes.
.PP
@ -315,7 +315,7 @@ are threaded analogues of
and
.I execl
(see
.IR exec (2));
.IR exec (3));
on success,
they replace the calling thread (which must be the only thread in its proc)
and invoke the external program, never returning.
@ -345,14 +345,14 @@ response.
returns a channel of pointers to
.B Waitmsg
structures (see
.IR wait (2)).
.IR wait (3)).
When an exec'ed process exits, a pointer to a
.B Waitmsg
is sent to this channel.
These
.B Waitmsg
structures have been allocated with
.IR malloc (2)
.IR malloc (3)
and should be freed after use.
.PP
A
@ -508,13 +508,13 @@ calls.
.PP
.I Chanprint
formats its arguments in the manner of
.IR print (2)
.IR print (3)
and sends the result to the channel
.IR c.
The string delivered by
.I chanprint
is allocated with
.IR malloc (2)
.IR malloc (3)
and should be freed upon receipt.
.PP
Thread library functions do not return on failure;
@ -525,12 +525,12 @@ Threaded programs should use
in place of
.I atnotify
(see
.IR notify (2)).
.IR notify (3)).
.PP
It is safe to use
.B sysfatal
(see
.IR perror (2))
.IR perror (3))
in threaded programs.
.I Sysfatal
will print the error string and call
@ -539,7 +539,7 @@ will print the error string and call
It is safe to use
.IR rfork
(see
.IR fork (2))
.IR fork (3))
to manage the namespace, file descriptors, note group, and environment of a
single process.
That is, it is safe to call
@ -572,5 +572,5 @@ contains a full example program.
.SH SOURCE
.B /sys/src/libthread
.SH SEE ALSO
.IR intro (2),
.IR ioproc (2)
.IR intro (3),
.IR ioproc (3)

12
man/man3/wait.3
View file

@ -17,7 +17,7 @@ int await(char *s, int n)
.SH DESCRIPTION
.I Wait
causes a process to wait for any child process (see
.IR fork (2))
.IR fork (3))
to exit.
It returns a
.B Waitmsg
@ -48,7 +48,7 @@ the time spent in system calls, and the child's elapsed real time,
all in units of milliseconds.
.B Msg
contains the message that the child specified in
.IR exits (2).
.IR exits (3).
For a normal exit,
.B msg[0]
is zero,
@ -64,7 +64,7 @@ returns immediately, with return value nil.
The
.B Waitmsg
structure is allocated by
.IR malloc (2)
.IR malloc (3)
and should be freed after use.
For programs that only need the pid of the exiting program,
.I waitpid
@ -83,7 +83,7 @@ The buffer filled in by
may be parsed (after appending a NUL) using
.IR tokenize
(see
.IR getfields (2));
.IR getfields (3));
the resulting fields are, in order, pid, the three times, and the exit string,
which will be
.B ''
@ -106,8 +106,8 @@ returns
.SH SOURCE
.B /sys/src/libc/9syscall
.SH "SEE ALSO"
.IR fork (2),
.IR exits (2),
.IR fork (3),
.IR exits (3),
the
.B wait
file in