proc(4) FILE FORMATS proc(4)
NAME
/proc - process file system
DESCRIPTION
/proc is a file system that provides access to the image of
each active process in the system. The name of each entry
in the /proc directory is a decimal number corresponding to
the process ID. The owner of each ``file'' is determined by
the process's user-ID.
Standard system call interfaces are used to access /proc
files: open, close, read, write, and ioctl. An open for
reading and writing enables process control; a read-only
open allows inspection but not control. As with ordinary
files, more than one process can open the same /proc file at
the same time. Exclusive open is provided to allow control-
ling processes to avoid collisions: an open for writing
that specifies OEXCL fails if the file is already open for
writing; if such an exclusive open succeeds, subsequent
attempts to open the file for writing, with or without the
OEXCL flag, fail until the exclusively-opened file descrip-
tor is closed. (Exception: a super-user open that does not
specify OEXCL succeeds even if the file is exclusively
opened.) There can be any number of read-only opens, even
when an exclusive write open is in effect on the file.
Data may be transferred from or to any locations in the
traced process's address space by applying lseek to position
the file at the virtual address of interest followed by read
or write. The PIOCMAP operation can be applied to determine
the accessible areas (mappings) of the address space. A
contiguous area of the address space may appear as multiple
mappings due to varying read/write/execute permissions. I/O
transfers may span contiguous mappings. An I/O request
extending into an unmapped area is truncated at the boun-
dary.
Information and control operations are provided through
ioctl. These have the form:
#include <sys/types.h>
#include <sys/signal.h>
#include <sys/fault.h>
#include <sys/syscall.h>
#include <sys/procfs.h>
void *p;
retval = ioctl(fildes, code, p);
The argument p is a generic pointer whose type depends on
the specific ioctl code. Where not specifically mentioned
below, its value should be zero. <sys/procfs.h> contains
definitions of ioctl codes and data structures used by the
1
proc(4) FILE FORMATS proc(4)
operations. Certain operations can be performed only if the
process file is open for writing; these include all opera-
tions that affect process control.
Process information and control operations involve the use
of sets of flags. The set types sigsett, fltsett, and
syssett correspond, respectively, to signal, fault, and
system call enumerations defined in <sys/signal.h>,
<sys/fault.h>, and <sys/syscall.h>. Each set type is large
enough to hold flags for its own enumeration. Although they
are of different sizes, they have a common structure and can
be manipulated by these macros:
prfillset(&set); /* turn on all flags in set */
premptyset(&set); /* turn off all flags in set */
praddset(&set, flag); /* turn on the specified flag */
prdelset(&set, flag); /* turn off the specified flag */
r = prismember(&set, flag); /* != 0 iff flag is turned on */
One of prfillset or premptyset must be used to initialize
set before it is used in any other operation. flag must be
a member of the enumeration corresponding to set.
The allowable ioctl codes follow. Those requiring write
access are marked with an asterisk (*). Except where noted,
an ioctl to a process that has terminated elicits the error
ENOENT.
PIOCSTATUS
This returns status information for the process; p is a
pointer to a prstatus structure:
typedef struct prstatus {
long prflags; /* Process flags */
short prwhy; /* Reason for process stop (if stopped) */
short prwhat; /* More detailed reason */
struct siginfo prinfo; /* Info associated with signal or fault */
short prcursig; /* Current signal */
sigsett prsigpend; /* Set of other pending signals */
sigsett prsighold; /* Set of held signals */
struct sigaltstack praltstack; /* Alternate signal stack info */
struct sigaction praction; /* Signal action for current signal */
pidt prpid; /* Process id */
pidt prppid; /* Parent process id */
pidt prpgrp; /* Process group id */
pidt prsid; /* Session id */
timestruct prutime; /* Process user cpu time */
timestruct prstime; /* Process system cpu time */
timestruct prcutime; /* Sum of children's user times */
timestruct prcstime; /* Sum of children's system times */
char prclname[8]; /* Scheduling class name */
long prfiller[20];/* Filler area for future expansion */
2
proc(4) FILE FORMATS proc(4)
long prinstr; /* Current instruction */
gregsett prreg; /* General registers */
} prstatust;
prflags is a bit-mask holding these flags:
PRSTOPPED process is stopped
PRISTOP process is stopped on an event of
interest (see PIOCSTOP)
PRDSTOP process has a stop directive in effect
(see PIOCSTOP)
PRASLEEP process is in an interruptible sleep
within a system call
PRFORK process has its inherit-on-fork flag set
(see PIOCSFORK)
PRRLC process has its run-on-last-close flag
set (see PIOCSRLC)
PRPTRACE process is being traced via ptrace
PRPCINVAL process program counter refers to an
invalid address
PRISSYS process is a system process (see
PIOCSTOP)
prwhy and prwhat together describe, for a stopped process,
the reason that the process is stopped. Possible values of
prwhy are:
PRREQUESTED indicates that the process stopped because
PIOCSTOP was applied; prwhat is unused in this case.
PRSIGNALLED indicates that the process stopped on
receipt of a signal (see PIOCSTRACE); prwhat holds the
signal number that caused the stop (for a newly-stopped
process, the same value is in prcursig).
PRFAULTED indicates that the process stopped on incur-
ring a hardware fault (see PIOCSFAULT); prwhat holds
the fault number that caused the stop.
PRSYSENTRY and PRSYSEXIT indicate a stop on entry to
or exit from a system call (see PIOCSENTRY and
PIOCSEXIT); prwhat holds the system call number.
PRJOBCONTROL indicates that the process stopped due to
the default action of a job control stop signal (see
sigaction); prwhat holds the stopping signal number.
prinfo, when the process is in a PRSIGNALLED or
PRFAULTED stop, contains additional information per-
tinent to the particular signal or fault (see
<sys/siginfo.h>). prcursig names the current signal-
that is, the next signal to be delivered to the pro-
cess. prsigpend identifies any other pending signals.
prsighold identifies those signals whose delivery is
being delayed if sent to the process. praltstack con-
tains the alternate signal stack information for the
3
proc(4) FILE FORMATS proc(4)
process (see sigaltstack). praction contains the
signal action information pertaining to the current
signal (see sigaction); it is undefined if prcursig is
zero. prpid, prppid, prpgrp, and prsid are,
respectively, the process id, the id of the process's
parent, the process's process group id, and the
process's session id. prutime, prstime, prcutime,
and prcstime are, respectively, the user and system
time consumed by the process, and the cumulative user
and system time consumed by the process's children, in
seconds and nanoseconds. prclname contains the name
of the process's scheduling class. The prfiller area
is reserved for future use. prinstr contains the
machine instruction to which the program counter
refers. The amount of data retrieved from the process
is machine-dependent; on the Mips R3000, it is a word.
In general, the size is that of the machine's smallest
instruction. If the program counter refers to an
invalid address, PRPCINVAL is set and prinstr is
undefined. prreg is an array holding the contents of
the general registers. On the Mips R3000 the prede-
fined constants EFAT, EFV0, ... EFSP, EFFP, and
EFRA can be used as indices to refer to the
corresponding registers.
PIOCSTOP*, PIOCWSTOP
PIOCSTOP directs the process to stop and waits until it has
stopped; PIOCWSTOP simply waits for the process to stop.
These operations complete when the process stops on an event
of interest, immediately if already so stopped. If p is
non-zero it points to an instance of prstatust to be filled
with status information for the stopped process. An ``event
of interest'' is either a PRREQUESTED stop or a stop that
has been specified in the process's tracing flags (set by
PIOCSTRACE, PIOCSFAULT, PIOCSENTRY, and PIOCSEXIT). A
PRJOBCONTROL stop is specifically not an event of interest.
(A process may stop twice due to a stop signal, first show-
ing PRSIGNALLED if the signal is traced and again showing
PRJOBCONTROL if the process is set running without clearing
the signal.) If the process is controlled by ptrace, it
comes to a PRSIGNALLED stop on receipt of any signal; this
is an event of interest only if the signal is in the traced
signal set. If PIOCSTOP is applied to a process that is
stopped, but not on an event of interest, the stop directive
takes effect when the process is restarted by the competing
mechanism; at that time the process enters a PRREQUESTED
stop before executing any user-level code. ioctls are
interruptible by signals so that, for example, an alarm can
be set to avoid waiting forever for a process that may never
stop on an event of interest. If PIOCSTOP is interrupted,
the stop directive remains in effect even though the ioctl
returns an error. A system process (indicated by the
4
proc(4) FILE FORMATS proc(4)
PRISSYS flag) never executes at user level, has no user-
level address space visible through /proc, and cannot be
stopped. Applying PIOCSTOP or PIOCWSTOP to a system process
elicits the error EBUSY.
PIOCRUN*
The traced process is made runnable again after a stop. If
p is non-zero it points to a prrun structure describing
additional actions to be performed:
typedef struct prrun {
long prflags; /* Flags */
sigsett prtrace; /* Set of signals to be traced */
sigsett prsighold; /* Set of signals to be held */
fltsett prfault; /* Set of faults to be traced */
caddrt prvaddr; /* Virtual address at which to resume */
long prfiller[8]; /* Filler area for future expansion */
} prrunt;
prflags is a bit-mask describing optional actions; the
remainder of the entries are meaningful only if the
appropriate bits are set in prflags. prfiller is reserved
for future use; this area must be filled with zeros by the
user's program. Flag definitions:
PRCSIG clears the current signal, if any (see
PIOCSSIG).
PRCFAULT clears the current fault, if any (see
PIOCCFAULT).
PRSTRACE sets the traced signal set to prtrace (see
PIOCSTRACE).
PRSHOLD sets the held signal set to prsighold (see
PIOCSHOLD).
PRSFAULT sets the traced fault set to prfault (see
PIOCSFAULT).
PRSVADDR sets the address at which execution resumes to
prvaddr.
PRSTEP directs the process to single-step-i.e., to run
and to execute a single machine instruction. On com-
pletion of the instruction, a hardware trace trap
occurs. If FLTTRACE is being traced, the processs
stops, otherwise it is sent SIGTRAP; if SIGTRAP is
being traced and not held, the process stops. This
operation requires hardware support and may not be
implemented on all processors.
PRSABORT is meaningful only if the process is in a
PRSYSENTRY stop or is marked PRASLEEP; it instructs
5
proc(4) FILE FORMATS proc(4)
the process to abort execution of the system call (see
PIOCSENTRY, PIOCSEXIT).
PRSTOP directs the process to stop again as soon as
possible after resuming execution (see PIOCSTOP). In
particular if the process is stopped on PRSIGNALLED or
PRFAULTED, the next stop will show PRREQUESTED, no
other stop will have intervened, and the process will
not have executed any user-level code. PIOCRUN fails
(EBUSY) if applied to a process that is not stopped on
an event of interest. Once PIOCRUN has been applied,
the process is no longer stopped on an event of
interest even if, due to a competing mechanism, it
remains stopped.
PIOCSTRACE*
This defines a set of signals to be traced: the receipt of
one of these signals causes the traced process to stop. The
set of signals is defined via an instance of sigsett
addressed by p. Receipt of SIGKILL cannot be traced. If a
signal that is included in the held signal set is sent to
the traced process, the signal is not received and does not
cause a process stop until it is removed from the held
signal set, either by the process itself or by setting the
held signal set with PIOCSHOLD or the PRSHOLD option of
PIOCRUN.
PIOCGTRACE
The current traced signal set is returned in an instance of
sigsett addressed by p.
PIOCSSIG*
The current signal and its associated signal information are
set according to the contents of the siginfo structure
addressed by p (see <sys/siginfo.h>). If the specified
signal number is zero or if p is zero, the current signal is
cleared. The semantics of this operation are different from
those of kill or PIOCKILL in that the signal is delivered to
the process immediately after execution is resumed (even if
it is being held) and an additional PRSIGNALLED stop does
not intervene even if the signal is traced. Setting the
current signal to SIGKILL terminates the process immedi-
ately, even if it is stopped.
PIOCKILL*
A signal is sent to the process with semantics identical to
those of kill; p points to an int naming the signal. Send-
ing SIGKILL terminates the process immediately.
PIOCUNKILL*
A signal is deleted, i.e. it is removed from the set of
pending signals; the current signal (if any) is unaffected.
6
proc(4) FILE FORMATS proc(4)
p points to an int naming the signal. It is an error to
attempt to delete SIGKILL.
PIOCGHOLD, PIOCSHOLD*
PIOCGHOLD returns the set of held signals (signals whose
delivery will be delayed if sent to the process) in an
instance of sigsett addressed by p. PIOCSHOLD correspond-
ingly sets the held signal set but does not allow SIGKILL or
SIGSTOP to be held.
PIOCMAXSIG, PIOCACTION
These operations provide information about the signal
actions associated with the traced process (see sigaction).
PIOCMAXSIG returns, in the int addressed by p, the maximum
signal number understood by the system. This can be used to
allocate storage for use with the PIOCACTION operation,
which returns the traced process's signal actions in an
array of sigaction structures addressed by p. Signal
numbers are displaced by 1 from array indices, so that the
action for signal number n appears in position n-1 of the
array.
PIOCSFAULT*
This defines a set of hardware faults to be traced: on
incurring one of these faults the traced process stops. The
set is defined via an instance of fltsett addressed by p.
Fault names are defined in <sys/fault.h> and include the
following. Some of these may not occur on all processors;
there may be processor-specific faults in addition to these.
FLTILL illegal instruction
FLTPRIV privileged instruction
FLTBPT breakpoint trap
FLTTRACE trace trap
FLTACCESS memory access fault
FLTBOUNDS memory bounds violation
FLTIOVF integer overflow
FLTIZDIV integer zero divide
FLTFPE floating-point exception
FLTSTACK unrecoverable stack fault
FLTPAGE recoverable page fault
When not traced, a fault normally results in the posting of
a signal to the process that incurred the fault. If the
process stops on a fault, the signal is posted to the pro-
cess when execution is resumed unless the fault is cleared
by PIOCCFAULT or by the PRCFAULT option of PIOCRUN. FLTPAGE
is an exception; no signal is posted. There may be addi-
tional processor-specific faults like this. prinfo in the
prstatus structure identifies the signal to be sent and con-
tains machine-specific information about the fault.
7
proc(4) FILE FORMATS proc(4)
PIOCGFAULT
The current traced fault set is returned in an instance of
fltsett addressed by p.
PIOCCFAULT*
The current fault (if any) is cleared; the associated signal
is not sent to the process.
PIOCSENTRY*, PIOCSEXIT*
These operations instruct the process to stop on entry to or
exit from specified system calls. The set of syscalls to be
traced is defined via an instance of syssett addressed by
p. When entry to a system call is being traced, the traced
process stops after having begun the call to the system but
before the system call arguments have been fetched from the
process. When exit from a system call is being traced, the
traced process stops on completion of the system call just
prior to checking for signals and returning to user level.
At this point all return values have been stored into the
traced process's saved registers. If the traced process is
stopped on entry to a system call (PRSYSENTRY) or when
sleeping in an interruptible system call (PRASLEEP is set),
it may be instructed to go directly to system call exit by
specifying the PRSABORT flag in a PIOCRUN request. Unless
exit from the system call is being traced the process
returns to user level showing error EINTR.
PIOCGENTRY, PIOCGEXIT
These return the current traced system call entry or exit
set in an instance of syssett addressed by p.
PIOCSFORK*, PIOCRFORK*
PIOCSFORK sets the inherit-on-fork flag in the traced pro-
cess: the process's tracing flags are inherited by the
child of a fork. PIOCRFORK turns this flag off: child
processes start with all tracing flags cleared.
PIOCSRLC*, PIOCRRLC*
PIOCSRLC sets the run-on-last-close flag in the traced pro-
cess: when the last writable /proc file descriptor refer-
ring to the traced process is closed, all of the process's
tracing flags are cleared, any outstanding stop directive is
canceled, and if the process is stopped, it is set running
as though PIOCRUN had been applied to it. PIOCRRLC turns
this flag off: the process's tracing flags are retained and
the process is not set running when the process file is
closed.
PIOCGREG, PIOCSREG*
These operations respectively get and set the saved process
registers into or out of an array addressed by p; the array
has type gregsett. Register contents are accessible using
8
proc(4) FILE FORMATS proc(4)
a set of predefined indices (see PIOCSTATUS). Only certain
bits of the processor-status word (PSW) can be modified by
PIOCSREG; on the 3B2 these include the condition-code bits
and the trace-enable bit. Other privileged registers cannot
be modified at all. PIOCSREG fails (EBUSY) if applied to a
process that is not stopped on an event of interest.
PIOCGFPREG, PIOCSFPREG*
These operations respectively get and set the saved process
floating-point registers into or out of a structure
addressed by p; the structure has type fpregsett. An error
(EINVAL) is returned if there is no floating-point hardware
on the machine. PIOCSFPREG fails (EBUSY) if applied to a
process that is not stopped on an event of interest.
PIOCNICE*
The traced process's nice priority is incremented by the
amount contained in the int addressed by p. Only the
super-user may better a process's priority in this way, but
any user may make the priority worse.
PIOCPSINFO
This returns miscellaneous process information such as that
reported by ps(1). p is a pointer to a prpsinfo structure
containing at least the following fields:
typedef struct prpsinfo {
char prstate; /* numeric process state (see prsname) */
char prsname; /* printable character representing prstate */
char przomb; /* !=0: process terminated but not waited for */
char prnice; /* nice for cpu usage */
ulong prflag; /* process flags */
uidt pruid; /* real user id */
gidt prgid; /* real group id */
pidt prpid; /* unique process id */
pidt prppid; /* process id of parent */
pidt prpgrp; /* pid of process group leader */
pidt prsid; /* session id */
caddrt praddr; /* physical address of process */
long prsize; /* size of process image in pages */
long prrssize; /* resident set size in pages */
caddrt prwchan; /* wait addr for sleeping process */
timestruct prstart; /* process start time, sec+nsec since epoch */
timestruct prtime; /* usr+sys cpu time for this process */
long prpri; /* priority, high value is high priority */
char proldpri; /* pre-SVR4, low value is high priority */
char prcpu; /* pre-SVR4, cpu usage for scheduling */
devt prttydev; /* controlling tty device (PRNODEV if none) */
char prclname[8]; /* Scheduling class name */
char prfname[16]; /* last component of execed pathname */
char prpsargs[PRARGSZ]; /* initial characters of arg list */
long prfiller[20]; /* for future expansion */
} prpsinfot;
9
proc(4) FILE FORMATS proc(4)
Some of the entries in prpsinfo, such as prstate and
prflag, are system-specific and should not be expected to
retain their meanings across different versions of the
operating system. praddr is a vestige of the past and has
no real meaning in current systems. PIOCPSINFO can be
applied to a zombie process (one that has terminated but
whose parent has not yet performed a wait on it).
PIOCNMAP, PIOCMAP
These operations provide information about the memory map-
pings (virtual address ranges) associated with the traced
process. PIOCNMAP returns, in the int addressed by p, the
number of mappings that are currently active. This can be
used to allocate storage for use with the PIOCMAP operation,
which returns the list of currently active mappings. For
PIOCMAP, p addresses an array of elements of type prmapt;
one array element (one structure) is returned for each map-
ping, plus an additional element containing all zeros to
mark the end of the list.
typedef struct prmap {
caddrt prvaddr; /* Virtual address base */
ulong prsize; /* Size of mapping in bytes */
offt proff; /* Offset into mapped object, if any */
long prmflags; /* Protection and attribute flags */
long prfiller[4]; /* Filler for future expansion */
} prmapt;
prvaddr is the virtual address base (the lower limit) of
the mapping within the traced process and prsize is its
size in bytes. proff is the offset within the mapped
object (if any) to which the address base is mapped.
prmflags is a bit-mask of protection and attribute flags:
MAREAD mapping is readable by the traced process
MAWRITE mapping is writable by the traced process
MAEXEC mapping is executable by the traced pro-
cess
MASHARED mapping changes are shared by the mapped
object
MABREAK mapping is grown by the brk system call
MASTACK mapping is grown automatically on stack
faults
PIOCOPENM
The return value retval provides a read-only file descriptor
for a mapped object associated with the traced process. If
p is zero the traced process's execed file (its a.out file)
is found. This enables a debugger to find the object file
symbol table without having to know the path name of the
executable file. If p is non-zero it points to a caddrt
containing a virtual address within the traced process and
the mapped object, if any, associated with that address is
found; this can be used to get a file descriptor for a
10
proc(4) FILE FORMATS proc(4)
shared library that is attached to the process. On error
(invalid address or no mapped object for the designated
address), -1 is returned.
PIOCCRED
Fetch the set of credentials associated with the process. p
points to an instance of prcredt, which is filled by the
operation:
typedef struct prcred {
uidt preuid; /* Effective user id */
uidt prruid; /* Real user id */
uidt prsuid; /* Saved user id (from exec) */
uidt pregid; /* Effective group id */
uidt prrgid; /* Real group id */
uidt prsgid; /* Saved group id (from exec) */
uint prngroups; /* Number of supplementary groups */
} prcredt;
PIOCGROUPS
Fetch the set of supplementary group IDs associated with the
process. p points to an array of elements of type uidt,
which will be filled by the operation. PIOCCRED can be
applied beforehand to determine the number of groups
(prngroups) that will be returned and the amount of storage
that should be allocated to hold them.
PIOCGETPR, PIOCGETU
These operations copy, respectively, the traced process's
proc structure and user area into the buffer addressed by p.
They are provided for completeness but it should be unneces-
sary to access either of these structures directly since
relevant status information is available through other con-
trol operations. Their use is discouraged because a program
making use of them is tied to a particular version of the
operating system. PIOCGETPR can be applied to a zombie pro-
cess (see PIOCPSINFO).
NOTES
Each operation (ioctl or I/O) is guaranteed to be atomic
with respect to the traced process, except when applied to a
system process.
For security reasons, except for the super-user, an open of
a /proc file fails unless both the user-ID and group-ID of
the caller match those of the traced process and the
process's object file is readable by the caller. Files
corresponding to setuid and setgid processes can be opened
only by the super-user. Even if held by the super-user, an
open process file descriptor becomes invalid if the traced
process performs an exec of a setuid/setgid object file or
an object file that it cannot read. Any operation performed
on an invalid file descriptor, except close, fails with
11
proc(4) FILE FORMATS proc(4)
EAGAIN. In this situation, if any tracing flags are set and
the process file is open for writing, the process will have
been directed to stop and its run-on-last-close flag will
have been set (see PIOCSRLC). This enables a controlling
process (if it has permission) to reopen the process file to
get a new valid file descriptor, close the invalid file
descriptor, and proceed. Just closing the invalid file
descriptor causes the traced process to resume execution
with no tracing flags set. Any process not currently open
for writing via /proc but that has left-over tracing flags
from a previous open and that execs a setuid/setgid or
unreadable object file will not be stopped but will have all
its tracing flags cleared. For reasons of symmetry and
efficiency there are more control operations than strictly
necessary.
FILES
/proc directory (list of active processes)
/proc/nnnnnprocess image
SEE ALSO
open(2), ptrace(2), sigaction(2), signal(2), sigset(2)
DIAGNOSTICS
Errors that can occur in addition to the errors normally
associated with file system access:
ENOENT The traced process has exited after being
opened.
EIO I/O was attempted at an illegal address in the
traced process.
EBADF An I/O or ioctl operation requiring write access
was attempted on a file descriptor not open for
writing.
EBUSY PIOCSTOP or PIOCWSTOP was applied to a system
process; an exclusive open was attempted on a
process file already already open for writing;
an open for writing was attempted and an
exclusive open is in effect on the process file;
PIOCRUN, PIOCSREG or PIOCSFPREG was applied to a
process not stopped on an event of interest; an
attempt was made to mount /proc when it is
already mounted.
EPERM Someone other than the super-user attempted to
better a process's priority by issuing PIOCNICE.
ENOSYS An attempt was made to perform an unsupported
operation (such as create, remove, link, or
12
proc(4) FILE FORMATS proc(4)
unlink) on an entry in /proc.
EFAULT An I/O or ioctl request referred to an invalid
address in the controlling process.
EINVAL In general this means that some invalid argument
was supplied to a system call. The list of con-
ditions eliciting this error includes: the
ioctl code is undefined; an ioctl operation was
issued on a file descriptor referring to the
/proc directory; an out-of-range signal number
was specified with PIOCSSIG, PIOCKILL, or
PIOCUNKILL; SIGKILL was specified with PIOCUNK-
ILL; an illegal virtual address was specified in
a PIOCOPENM request; PIOCGFPREG or PIOCSFPREG
was issued on a machine without floating-point
hardware.
EINTR A signal was received by the controlling process
while waiting for the traced process to stop via
PIOCSTOP or PIOCWSTOP.
EAGAIN The traced process has performed an exec of a
setuid/setgid object file or of an object file
that it cannot read; all further operations on
the process file descriptor (except close) eli-
cit this error.
13