diff options
Diffstat (limited to 'static/plan9-4e/man3/proc.3')
| -rw-r--r-- | static/plan9-4e/man3/proc.3 | 328 |
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 |