path: root/static/unix-v10/man4/proc.4

.TH PROC 4
.CT 2 proc_man
.SH NAME
proc \- process file system
.SH SYNOPSIS
.B #include <sys/proc.h>
.br
.B #include <sys/pioctl.h>
.SH DESCRIPTION
.I Proc
is a file-system mount point that provides access to the image of each
running process in the system.
The name of each entry in the
.F /proc
directory is a five-digit decimal number corresponding to the process
id.
The owner of each file is the userid of the process;
the group is \-1.
If the process's text file is readable, the owner is granted
read-write permission and the group is granted read permission.
The size of a file is
the total virtual memory size of the process.
The security label is shared with the process, unless the
process has had capability
.B T_NOCHK
(see
.IR getplab (2))
since last
.IR exec (2),
in which case the lattice value of the label is lattice
top and the privilege fields contain some past value of the
process' privilege fields.
.PP
The standard system-call interface is used to access
.I proc.
.I Open
and
.IR close (2)
behave as usual.
The object process is unaffected, except that setuid bits
will be ignored if it does an
.IR exec (2).
(Setuid bits are also ignored if the
.IR exec "ing"
process has traced signals, or stops on
.IR exec ;
see the description of
.B PIOCSMASK
and
.B PIOCSEXEC
below.)
Data may be transferred
from or to any locations in the object's address space through
.I lseek,
.I read,
and
.IR write (2).
The
.I text segment
begins at virtual address 0; the
.I data segment
starts above the text.
The
.I user area
extends downward below virtual address 0x80000000, and is
.B UPAGES*NBPG
bytes long; the
.I stack segment
grows downward below the user area.
Between the end of the data and
the beginning of the stack lies no-man's land.
The text, data, and stack sizes
may be determined from the process's
.L proc
structure (see below).
There are two differences from reading and writing ordinary files:
(1) no I/O transfer may span a segment boundary;
(2) the user area is writable only in the locations of saved user registers.
.PP
Several process control actions are available through an
.IR ioctl (2)
of the form
.IP
.L
union { struct proc p; long i; } buffer;
.br
.L retval = ioctl(fildes, code, &buffer);
.LP
The possible
.I codes
are as follows:
.TF PIOCSMASK
.TP
.B PIOCGETPR
copies the object's proc structure from the kernel process table
into
.BR buffer.p .
Since this information resides in system space, it is not accessible
via a normal read.
.PD
.TP
.B PIOCSTOP
sends the signal
.B SIGSTOP
to the object, and waits for it to
enter the stopped state.
.TP
.B PIOCWSTOP
simply waits for the object to stop.
.TP
.B PIOCRUN
makes the object runnable again after a stop.
.TP
.B PIOCSMASK
defines (via the bit mask
.BR buffer.i )
a set of signals to be traced;
i.e., the arrival of such a signal will cause the object to stop.
(The signal numbered
.I n
is specified by the bit
.BI "1<<(" n "-1)\fR.)"
A mask of zeroes turns off the trace.
The traced state and mask bits are inherited by the child of a
.IR fork (2).
When the object is closed, the mask bits are lost, but
the traced state is retained for side effects.
.TP
.B PIOCSEXEC
causes the object to stop after
.IR exec "ing."
This condition is inherited by children and is retained when the
object is closed.
.TP
.B PIOCREXEC
reverses the effect of
.BR PIOCSEXEC .
.TP
.B PIOCCSIG
clears the object's currently pending signal (if any).
.TP
.B PIOCKILL
sends a signal to the process.
.TP
.B PIOCOPENT
provides, in
.BR retval ,
a read-only file descriptor
for the object process's text file.
This allows a debugger to find the
symbol table without having to know any path names.
.TP
.B PIOCNICE
increments the object's
.IR nice (2)
priority by the amount
.BR buffer.i .
Only the super user may better a process's priority in this way, but any
user may make the priority worse.
.PP
All system calls are interruptible by signals, so that, for example,
an
.IR alarm (2)
may be set to avoid waiting forever for a process that may never stop.
Any system call is guaranteed to be atomic with respect to the object,
but, as with ordinary files, there is nothing to prevent more than one
process from trying to control the same object.
.PP
The following header files are useful in analyzing
.I proc
files:
.PP
.TF <sys/param.h>
.TP
.B <signal.h>
list of signal numbers
.TP
.B <sys/param.h>
size parameters
.TP
.B <sys/types.h>
special system types
.TP
.B <sys/user.h>
user structure
.TP
.B <sys/proc.h>
proc structure
.TP
.B <sys/reg.h>
locations of saved user registers
.TP
.B <sys/pioctl.h>
ioctl codes
.PD
.SH FILES
.F /proc/*
.SH SEE ALSO
.IR ps (1), 
.IR hang (1),
.IR fmount (2),
.IR signal (2),
.IR mount (8),
.IR pi (9.1)
.SH DIAGNOSTICS
This is a list of errors which can occur in addition to the
errors normally associated with the file system; see
.IR intro (2):
.TF ENOENT
.TP
.B ENOENT
is returned if the object process has exited after being opened.
.TP
.B EIO
is returned if I/O is attempted at an illegal address in the object.
.TP
.B EBUSY
is returned if the object is in the midst of changing virtual memory
attributes, or has pages locked for physical I/O.
.TP
.B ENOSPC
is returned if a write is attempted on a shared text segment, but there
is no room on the swap space to make a copy.
.TP
.B EPERM
is returned if someone other than the super user attempts to better
a process's priority by issuing a
.BR PIOCNICE .
.SH BUGS
A process must be swapped in for reading and writing (but not
.IR ioctl );
this consumes minimal system resources, but may involve a noticeable
delay.
.br
The spectrum of states which result in the
.B EBUSY
error is too conservative.
.br
A process loaded from a text file with magic number 0407 does not have as
a read-only text segment; in this (presumably rare) case
.B PIOCOPENT
does not work, and the process is accessible even if the
text file is read-only.