build: Better Build System

1 files changed, 328 insertions, 0 deletions

diff --git a/static/plan9-4e/man3/proc.3 b/static/plan9-4e/man3/proc.3
new file mode 100644
index 00000000..45d5d40e
--- /dev/null
+++ b/static/plan9-4e/man3/proc.3
@@ -0,0 +1,328 @@
+.TH PROC 3 
+.SH NAME
+proc \- running processes
+.SH SYNOPSIS
+.nf
+.B bind #p /proc
+
+.BI /proc/ n /args
+.BI /proc/ n /ctl
+.BI /proc/ n /fd
+.BI /proc/ n /fpregs
+.BI /proc/ n /kregs
+.BI /proc/ n /mem
+.BI /proc/ n /note
+.BI /proc/ n /noteid
+.BI /proc/ n /notepg
+.BI /proc/ n /ns
+.BI /proc/ n /proc
+.BI /proc/ n /profile
+.BI /proc/ n /regs
+.BI /proc/ n /segment
+.BI /proc/ n /status
+.BI /proc/ n /text
+.BI /proc/ n /wait
+\&...
+.fi
+.SH DESCRIPTION
+The
+.I proc
+device serves a two-level directory structure.
+The first level contains numbered directories
+corresponding to pids of live processes;
+each such directory contains a set of files
+representing the corresponding process.
+.PP
+The
+.B mem
+file contains the current memory image of the process.
+A read or write at offset
+.IR o ,
+which must be a valid virtual address,
+accesses bytes from address
+.IR o
+up to the end of the memory segment containing
+.IR o .
+Kernel virtual memory, including the kernel stack for the process and
+saved user registers (whose addresses are machine-dependent),
+can be accessed through
+.BR mem .
+Writes are permitted only while the process is in the
+.B Stopped
+state and only to user addresses or registers.
+.PP
+The read-only
+.B proc
+file contains the kernel per-process
+structure.
+Its main use is to recover the kernel stack and program counter
+for kernel debugging.
+.PP
+The files
+.BR regs ,
+.BR fpregs ,
+and
+.BR kregs
+hold representations of the user-level registers, floating-point registers,
+and kernel registers in machine-dependent form.
+The
+.B kregs
+file is read-only.
+.PP
+The read-only
+.B fd
+file lists the open file descriptors of the process.
+The first line of the file is its current directory; subsequent lines list, one per line,
+the open files, giving the decimal file descriptor number; whether the file is open for read
+.RB ( r ),
+write,
+.RB ( w ),
+or both
+.RB ( rw );
+the type, device number, and qid of the file; its I/O unit (the amount of data
+that may be transferred on the file as a contiguous piece; see
+.IR iounit (2)),
+its I/O offset; and its name at the time it was opened.
+.PP
+The read-only
+.B ns
+file contains a textual representation of the process's file name space, in the format of
+.IR namespace (6)
+accepted by
+.B newns
+(see
+.IR auth (2)).
+The last line of the file identifies the current working directory of the process, in the form of a
+.B cd
+command
+(see
+.IR rc (1)).
+The information in this file is based on the names files had when the name space was assembled,
+so the names it contains may be inaccessible if the files have been subsequently renamed or rearranged.
+.PP
+The read-only
+.B segment
+file contains a textual display of the memory segments
+attached to the process.  Each line has multiple fields:
+the type of segment (\c
+.BR Stack ,
+.BR Text ,
+.BR Data ,
+.BR Bss ,
+etc.); one-letter flags such as
+.B R
+for read-only, if any;
+starting virtual address, in hexadecimal;
+ending virtual address, and reference count.
+.PP
+The read-only
+.B status
+file contains a string with twelve fields, each followed by a space.
+The fields are:
+.IP \-
+the process name and user name, each 27 characters left justified
+.IP \-
+the process state, 11 characters left justified (see
+.IR ps (1))
+.IP \-
+the six 11-character numbers also held in the process's
+.B #c/cputime
+file
+.IP \-
+the amount of memory used by the process, except its stack,
+in units of 1024 bytes
+.IP \-
+the base and current scheduling priority, each 11 character numbers
+.PP
+The read-only
+.B args
+file contains the arguments of the program when it was created by
+.IR exec (2).
+If the program was not created by
+.BR exec ,
+such as by
+.IR fork (2),
+its
+.B args
+file will be empty.
+The format of the file is a list of quoted strings suitable for
+.BR tokenize ;
+see
+.IR getfields (2).
+.PP
+The
+.B text
+file is a pseudonym for the file
+from which the process was executed;
+its main use is to recover the symbol table of the process.
+.PP
+The
+.B wait
+file may be read to recover
+records from the exiting children of the process in the format of
+.B await
+(see
+.IR wait (2)).
+If the process has no extant children, living or exited,
+a read of
+.B wait
+will block.
+It is an error for a process to attempt to read its own
+.B wait
+file when it has no children.
+When a process's
+.B wait
+file is being read,
+the process will draw an error
+if it attempts an
+.B await
+system call; similarly, if a process is in an
+.B await
+system call, its
+.B wait
+file cannot be read by any process.
+.PP
+Textual messages written to the
+.B ctl
+file control the execution of the process.
+Some require that the process is in a particular state
+and return an error if it is not.
+.TP 10n
+.B stop
+Suspend execution of the process, putting it in the
+.B Stopped
+state.
+.TP 10n
+.B start
+Resume execution of a
+.B Stopped
+process.
+.TP 10n
+.B waitstop
+Do not affect the process directly but, like all other messages ending with
+.BR stop ,
+block the process writing the
+.B ctl
+file until the target process is in the
+.B Stopped
+state or exits.
+Also like other
+.B stop
+control messages,
+if the target process would receive a note while the message is pending,
+it is instead stopped and the debugging process is resumed.
+.TP 10n
+.B startstop
+Allow a
+.B Stopped
+process to resume, and then do a
+.B waitstop
+action.
+.TP 10n
+.B hang
+Set a bit in the process so that,
+when it completes an
+.IR exec (2)
+system call, it will enter the
+.B Stopped
+state before returning to user mode.
+This bit is inherited across
+.IR fork (2)
+and
+.IR exec (2).
+.TP 10n
+.B "close\ \fIn
+Close file descriptor
+.I n
+in the process.
+.TP 10n
+.B closefiles
+Close all open file descriptors in the process.
+.TP 10n
+.B nohang
+Clear the hang bit.
+.TP 10n
+.B kill
+Kill the process the next time it crosses the user/kernel boundary.
+.TP 10n
+.B private
+Make it impossible to read the process's user memory.
+This property is inherited on fork, cleared on
+.IR exec (2),
+and is not otherwise resettable.
+.TP 10n
+.B "pri\ \fIn
+Set the base priority for the process to the integer
+.IR n .
+.TP 10n
+.B "wire\ \fIn
+Wire the process to processor
+.IR n .
+.PD
+.PP
+The priority is interpreted by Plan 9's multilevel process scheduler.
+Priorities run from 0 to 19, with higher
+numbers representing higher priorities.
+A process has a base priority and
+a running priority which is less than or equal to the base priority.
+As a process uses up more of its allocated time, its priority is lowered.
+Unless
+explicitly set, user processes have base priority 10, kernel processes
+13.
+Children inherit the parent's base priority.
+.PP
+The read-only
+.B profile
+file contains the instruction frequency count information used for multiprocess profiling; see
+.B tprof
+in
+.IR prof (1).
+The information is gleaned by sampling the program's user-level program counter
+at interrupt time.
+.PP
+Strings written to the
+.B note
+file will be posted as a note to the process
+(see
+.IR notify (2)).
+The note should be less than
+.B ERRLEN-1
+characters long;
+the last character is reserved for a terminating NUL character.
+A read of at least
+.B ERRLEN
+characters will retrieve the oldest note posted to the
+process and prevent its delivery to the process.
+The
+.B notepg
+file is similar, but the note will be delivered to all the
+processes in the target process's
+.I note group
+(see
+.IR fork (2)).
+However, if the process doing the write is in the group,
+it will not receive the note.
+The
+.B notepg
+file is write-only.
+.PP
+The textual
+.B noteid
+file may be read to recover an integer identifying the note group of the process
+(see
+.B RFNOTEG
+in
+.IR fork (2)).
+The file may be written to cause the process to change to another note group,
+provided the group exists and is owned by the same user.
+.SH FILES
+.nf
+.B /sys/src/9/*/mem.h
+.B /sys/src/9/*/dat.h
+.fi
+.SH SEE ALSO
+.IR debugger (2),
+.IR mach (2),
+.IR cons (3)
+.SH SOURCE
+.B /sys/src/9/port/devproc.c