proc(4) proc(4)
NAME
proc - process file system
SYNOPSIS
#include <sys/types.h>
#include <sys/procfs.h>
#include <sys/fault.h>
#include <sys/syscall.h>
#include <signal.h>
#include <fcntl.h>
DESCRIPTION
/proc is a file system that provides access to the state of
each active process and LWP (Light Weight Process) in the
system. The name of each entry in the /proc directory is a
decimal number corresponding to the process ID. These entries
are sub-directories, and the owner of each is determined by
the user-ID of the process. Access to process state is
provided by additional files contained within each sub-
directory; this hierarchy is described more completely below.
Except where otherwise specified, ``/proc file'' is meant to
refer to a non-directory file within the hierarchy rooted at
/proc. The owner of each file is determined by the user-ID of
the process.
Standard system call interfaces are used to access /proc
files: open(2), close(2), read(2), and write(2). Most files
describe process state and can only be open for reading. ctl
(control) and lwpctl files permit manipulation of process
state and can only be open for writing. as (address space)
files contain the image of the running process and can be open
for both reading and writing. An open for writing allows
process control; a read-only open allows inspection, but not
control. (For purposes of this discussion we refer to the
process as open for reading or writing if any of its
associated /proc files is open respectively for reading or
writing.) In general more than one process can open the same
/proc file at the same time. Exclusive open is an advisory
mechanism provided to allow cooperating controlling processes
to avoid collisions. A process can obtain exclusive control
of a target process, with respect to other cooperating
processes, if it successfully opens any /proc file in the
target process for writing (the as or ctl files, or the lwpctl
file of any LWP) while specifying O_EXCL in the open. Such an
open will fail if the target process is already open for
writing (that is, if a ctl, as, or lwpctl file is open for
Copyright 1994 Novell, Inc. Page 1
proc(4) proc(4)
writing). There can be any number of concurrent read-only
opens; O_EXCL is ignored on opens for reading.
Data may be transferred from or to any locations in the
address space of the traced process by applying lseek(2) to
position the as file at the virtual address of interest
followed by read or write. The address-map file /proc/pid/map
can be examined to determine the accessible areas (mappings)
of the address space. I/O transfers may span contiguous
mappings. An I/O request extending into an unmapped area is
truncated at the boundary. A write request beginning at an
unmapped virtual address fails with errno set to EIO; a read
request beginning at an unmapped virtual address returns zero
(that is, an end-of-file indication).
Information and control operations are provided through
additional files. sys/procfs.h contains definitions of data
structures and message formats used with these files. Some of
these definitions involve the use of sets of flags. The set
types sigset_t, fltset_t, and sysset_t 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.
Every active process contains at least one Light Weight
Process (LWP). Each LWP represents a flow of execution that
is independently scheduled by the operating system. See
intro(2) for an explanation of LWPs and their relationship to
the threads library. All LWPs in a process share address
space as well as many other attributes. Using ctl files,
described below, it is possible to affect individual LWPs in a
process or to affect all of them at once (depending on the
operation).
Copyright 1994 Novell, Inc. Page 2
proc(4) proc(4)
DIRECTORY STRUCTURE
At the top level, the directory /proc contains entries each of
which names an existing process in the system. These entries
are directories. Except where otherwise noted, the files
described below can be open for reading only. In addition, if
a process becomes a zombie (one that has exited but whose
parent has not yet performed a wait(2) on it), most of its
associated /proc files disappear from the hierarchy; later
attempts to open them, or to read or write files opened before
the process exited, elicit ENOENT. The exceptions are noted.
Although process state and consequently the contents of /proc
files can change from instant to instant, a single read(2) of
a /proc file is guaranteed to return a ``sane'' representation
of state, that is, the read will be an atomic snapshot of the
state of the process. No such guarantee applies to successive
reads applied to a /proc file for a running process. In
addition, atomicity is specifically not guaranteed for any I/O
applied to the as (address-space) file; the contents of any
process's address space might be concurrently modified by an
LWP of that process or any other process in the system.
Multiple structure definitions are used to describe the files.
Unless explicitly stated otherwise, these definitions may be
incomplete: the file may contain additional information. More
specifically, these structures may grow between releases of
the system and programs should not assume that they will not.
STRUCTURE OF /proc/pid
A given directory /proc/pid contains the following entries:
as Contains the address-space image of the process; the file
can be opened for both reading and writing. lseek is
used to position the file at the virtual address of
interest and then the address space can be examined or
changed through read and write.
ctl A write-only file to which structured messages are
written directing the system to change some aspect of the
process's state or control its behavior in some way. The
seek offset is not relevant when writing to this file.
The types of control messages are described in detail
below. Individual LWPs also have associated lwpctl
files. A control message may be written either to the
ctl file of the process or to a specific lwpctl file with
operation-specific effects as described. The effect of a
Copyright 1994 Novell, Inc. Page 3
proc(4) proc(4)
control message is immediately reflected in the state of
the process visible through appropriate status and
information files.
status
Contains state information about the process and one of
its LWPs (chosen according to rules described below).
The file is formatted as a struct pstatus containing the
following members:
long pr_flags; /* Flags */
ushort_t pr_nlwp; /* Number of lwps in the process */
sigset_t pr_sigpend; /* Set of process pending signals */
vaddr_t pr_brkbase; /* Address of the process heap */
ulong_t pr_brksize; /* Size of the process heap, in bytes */
vaddr_t pr_stkbase; /* Address of the process stack */
ulong_t pr_stksize; /* Size of the process stack, in bytes */
pid_t pr_pid; /* Process id */
pid_t pr_ppid; /* Parent process id */
pid_t pr_pgid; /* Process group id */
pid_t pr_sid; /* Session id */
timestruc_t pr_utime; /* Process user cpu time */
timestruc_t pr_stime; /* Process system cpu time */
timestruc_t pr_cutime; /* Sum of children's user times */
timestruc_t pr_cstime; /* Sum of children's system times */
sigset_t pr_sigtrace; /* Mask of traced signals */
fltset_t pr_flttrace; /* Mask of traced faults */
sysset_t pr_sysentry; /* Mask of system calls traced on entry */
sysset_t pr_sysexit; /* Mask of system calls traced on exit */
lwpstatus_t pr_lwp; /* "representative" LWP */
pr_flags is a bit-mask holding these flags:
PR_ISSYS process is a system process (see PCSTOP)
PR_FORK process has its inherit-on-fork flag set
(see PCSET)
PR_RLC process has its run-on-last-close flag set
(see PCSET)
PR_KLC process has its kill-on-last-close flag set
(see PCSET)
PR_ASYNC process has its asynchronous-stop flag set
(see PCSET)
pr_nlwp is the total number of LWPs in the process.
Copyright 1994 Novell, Inc. Page 4
proc(4) proc(4)
pr_brkbase is the virtual address of the process heap and
pr_brksize is its size in bytes. The address formed by
the sum of these values is the process break (see
brk(2)). pr_stkbase and pr_stksize are, respectively,
the virtual address of the process stack and its size in
bytes. (Each LWP runs on a separate stack; the process
stack is distinguished in that the operating system will
grow it as necessary.)
pr_pid, pr_ppid, pr_pgid, and pr_sid are, respectively,
the process ID, parent process ID, process group ID, and
session ID of the process.
pr_utime, pr_stime, pr_cutime, and pr_cstime are,
respectively, the user CPU and system CPU time consumed
by the process, and the cumulative user CPU and system
CPU time consumed by the process's children, in seconds
and nanoseconds.
pr_sigtrace and pr_flttrace contain, respectively, the
set of signals and the set of hardware faults that are
being traced (see PCSTRACE and PCSFAULT).
pr_sysentry and pr_sysexit contain, respectively, the
sets of system calls being traced on entry and exit (see
PCSENTRY and PCSEXIT).
If the process is not a zombie, pr_lwp contains an
lwpstatus_t structure describing a representative LWP.
The contents of this structure have the same meaning as
if it were read from an lwpstatus file (see below).
When the process has more than one LWP, its
representative LWP is chosen by the /proc implementation.
The chosen LWP is a stopped LWP only if all the process's
LWPs are stopped, is stopped on an event of interest only
if all the LWPs are so stopped, or is in a PR_REQUESTED
stop only if there are no other events of interest to be
found. The chosen LWP remains fixed as long as all the
LWPs are stopped on events of interest and PCRUN is not
applied to any of them.
When applied to the process control file, every /proc
control operation that must act on an LWP uses the same
algorithm to choose which LWP to act on. Together with
synchronous stopping (see PCSET), this enables an
Copyright 1994 Novell, Inc. Page 5
proc(4) proc(4)
application to control a multiple-LWP process using only
the process-level status and control files if it so
chooses. More fine-grained control can be achieved using
the LWP-specific files.
psinfo
Information about the process needed by the ps(1)
command. If the process contains more than one LWP, a
representative LWP (chosen according to the rules
described for the status file) is used to derive the
status information. The file is formatted as a struct
psinfo containing the following members:
ulong_t pr_flag; /* process flags */
ulong_t pr_nlwp; /* number of LWPs in process */
uid_t pr_uid; /* real user id */
gid_t pr_gid; /* real group id */
pid_t pr_pid; /* unique process id */
pid_t pr_ppid; /* process id of parent */
pid_t pr_pgid; /* pid of process group leader */
pid_t pr_sid; /* session id */
caddr_t pr_addr; /* internal address of process */
long pr_size; /* size of process image in pages */
long pr_rssize; /* resident set size in pages */
timestruc_t pr_start; /* process start time, time since epoch */
timestruc_t pr_time; /* usr+sys cpu time for this process */
dev_t pr_ttydev; /* controlling tty device (or PRNODEV)*/
char pr_fname[PRFNSZ]; /* last component of exec()ed pathname*/
char pr_psargs[PRARGSZ]; /* initial characters of arg list */
struct lwpsinfo pr_lwp; /* "representative" LWP */
Some of the entries in psinfo, such as pr_flag and
pr_addr, refer to internal kernel data structures and
should not be expected to retain their meanings across
different versions of the operating system. They have no
meaning to a program and are only useful for manual
interpretation by a user aware of the implementation
details.
psinfo is still accessible even after a process becomes a
zombie.
pr_lwp describes the representative LWP chosen as
described under the pstatus file above. If the process
is a zombie, pr_nlwp and pr_lwp.pr_lwpid are zero and the
other fields of pr_lwp are undefined.
Copyright 1994 Novell, Inc. Page 6
proc(4) proc(4)
map Information about the virtual address map of the process.
The file contains an array of prmap structures, each of
which describes a contiguous virtual address region in
the address space of the traced process. The prmap
structure contains the following members:
caddr_t pr_vaddr; /* Virtual address */
ulong_t pr_size; /* Size of mapping in bytes */
char pr_mapname[32]; /* Name in /proc/pid/object */
off_t pr_off; /* Offset into mapped object, if any */
long pr_mflags; /* Protection and attribute flags */
long pr_filler[9]; /* For future use */
pr_vaddr is the virtual address of the mapping within the
traced process and pr_size is its size in bytes. If
pr_mapname does not contain an empty string then it holds
the name of a file in the object directory that can be
opened for reading to yield a file descriptor for the
object to which the virtual address is mapped. pr_off is
the offset within the mapped object (if any) to which the
virtual address is mapped.
pr_mflags is a bit-mask of protection and attribute
flags:
MA_READ mapping is readable by the traced process
MA_WRITE mapping is writable by the traced process
MA_EXEC mapping is executable by the traced process
MA_SHARED mapping changes are shared by the mapped
object
A contiguous area of the address space having the same
underlying mapped object may appear as multiple mappings
because of varying read, write, execute, and shared
attributes. The underlying mapped object does not change
over the range of a single mapping. An I/O operation to
a mapping marked MA_SHARED fails if applied at a virtual
address not corresponding to a valid page in the
underlying mapped object. Reads and writes to private
mappings always succeed. Reads and writes to unmapped
addresses always fail.
cred A description of the credentials associated with the
process. The file is formatted as a struct prcred
containing the following members:
Copyright 1994 Novell, Inc. Page 7
proc(4) proc(4)
uid_t pr_euid; /* Effective user id */
uid_t pr_ruid; /* Real user id */
uid_t pr_suid; /* Saved user id (from exec) */
gid_t pr_egid; /* Effective group id */
gid_t pr_rgid; /* Real group id */
gid_t pr_sgid; /* Saved group id (from exec) */
uint_t pr_ngroups; /* Number of supplementary groups */
gid_t pr_groups[1]; /* Array of supplementary groups */
The list of associated supplementary groups in pr_groups
is of variable length; pr_ngroups specifies the number of
groups.
sigact
Contains an array of sigaction structures describing the
current dispositions of all signals associated with the
traced process. Signal numbers are displaced by 1 from
array indexes, so that the action for signal number n
appears in position n-1 of the array.
object
A directory containing read-only files with names as they
appear in the entries of the map file, corresponding to
objects mapped into the address space of the target
process. Opening such a file yields a descriptor for the
mapped file associated with a particular address-space
region. The name a.out also appears in the directory as
a synonym for the executable file associated with the
``text'' of the running process.
The object directory makes it possible for a controlling
process to get access to the object file and any shared
libraries (and consequently the symbol tables)-in
general, any mapped files-without having to know the
specific path names of those files.
lwp A directory containing entries each of which names an LWP
within the containing process. These entries are
directories containing additional files described below.
STRUCTURE OF /proc/pid/lwp/lwpid
A given directory /proc/pid/lwp/lwpid contains the following
entries:
Copyright 1994 Novell, Inc. Page 8
proc(4) proc(4)
lwpctl
Write-only control file (as described above); the
messages written to this file affect only the associated
LWP rather than the process as a whole (where
appropriate).
lwpstatus
LWP-specific state information. This information is
present in the status file of the process for its
representative LWP, also. The file is formatted as a
struct lwpstatus containing the following members:
long pr_flags; /* Flags */
short pr_why; /* Reason for stop (if stopped) */
short pr_what; /* More detailed reason */
lwpid_t pr_lwpid; /* Specific LWP identifier */
short pr_cursig; /* Current signal */
siginfo_t pr_info; /* Info associated with signal or fault */
struct sigaction pr_action; /* Signal action for current signal */
sigset_t pr_lwppend; /* Set of LWP pending signals */
stack_t pr_altstack; /* Alternate signal stack info */
short pr_syscall; /* System call number (if in syscall) */
short pr_nsysarg; /* Number of arguments to this syscall */
long pr_sysarg[PRSYSARGS];/* Arguments to this syscall */
char pr_clname[PRCLSZ]; /* Scheduling class name */
ucontext_t pr_context; /* LWP context */
pfamily_t pr_family; /* Processor family-specific information */
pr_flags is a bit-mask holding these flags:
PR_STOPPED LWP is stopped
PR_ISTOP LWP is stopped on an event of interest (see
PCSTOP)
PR_DSTOP LWP has a stop directive in effect (see
PCSTOP)
PR_STEP LWP has a single-step directive in effect
(see PCRUN)
PR_ASLEEP LWP is in an interruptible sleep within a
system call
PR_PCINVAL LWP program counter register does not point
to a valid address
pr_why and pr_what together describe, for a stopped LWP,
the reason for the stop. Possible values of pr_why:
Copyright 1994 Novell, Inc. Page 9
proc(4) proc(4)
PR_REQUESTED shows that the stop occurred in
response to a stop directive, normally because
PCSTOP was applied or because another LWP stopped
on an event of interest and the asynchronous-stop
flag (see PCSET) was not set for the process.
pr_what is unused in this case.
PR_SIGNALLED shows that the LWP stopped on receipt
of a signal (see PCSTRACE); pr_what holds the
signal number that caused the stop (for a newly-
stopped LWP, the same value is in pr_cursig).
PR_FAULTED shows that the LWP stopped on incurring
a hardware fault (see PCSFAULT); pr_what holds the
fault number that caused the stop.
PR_SYSENTRY and PR_SYSEXIT show a stop on entry to
or exit from a system call (see PCSENTRY and
PCSEXIT); pr_what holds the system call number.
PR_JOBCONTROL shows that the LWP stopped because of
the default action of a job control stop signal
(see sigaction(2)); pr_what holds the stopping
signal number.
pr_lwpid names the specific LWP described.
pr_cursig names the current signal, that is, the next
signal to be delivered to the LWP. pr_info, when the LWP
is in a PR_SIGNALLED or PR_FAULTED stop, contains
additional information pertinent to the particular signal
or fault (see sys/siginfo.h).
pr_action contains the signal action information about
the current signal (see sigaction(2)); it is undefined if
pr_cursig is zero.
pr_lwppend identifies any synchronously-generated or
LWP-directed signals pending for the LWP. It does not
include signals pending at the process level.
pr_altstack contains the alternate signal stack
information for the LWP (see sigaltstack(2)).
Copyright 1994 Novell, Inc. Page 10
proc(4) proc(4)
pr_syscall is the number of the system call, if any,
being executed by the LWP; it is non-zero if and only if
the LWP is stopped on PR_SYSENTRY or PR_SYSEXIT, or is
asleep within a system call (PR_ASLEEP is set). If
pr_syscall is non-zero, pr_nsysarg is the number of
arguments to the system call and the pr_sysarg array
contains the arguments.
pr_clname contains the name of the scheduling class of
the LWP.
pr_context contains the user context of the LWP, as if it
had called getcontext(2). If the LWP is not stopped, all
context values are undefined.
pr_family contains the CPU-family specific information
about the LWP. Use of this field is not portable across
different architectures.
lwpsinfo
Information about the LWP needed by ps(1). This
information also is present in the psinfo file of the
process for its representative LWP if it has one. The
file is formatted as a struct psinfo containing the
following members:
ulong_t pr_flag; /* LWP flags */
lwpid_t pr_lwpid; /* LWP id */
caddr_t pr_addr; /* internal address of LWP */
caddr_t pr_wchan; /* wait addr for sleeping LWP */
uchar_t pr_stype; /* synchronization event type */
uchar_t pr_state; /* numeric scheduling state */
char pr_sname; /* printable character representing pr_state */
uchar_t pr_nice; /* nice for cpu usage */
int pr_pri; /* priority, high value = high priority */
timestruc_t pr_time; /* usr+sys cpu time for this LWP */
char pr_clname[8]; /* Scheduling class name */
char pr_name[PRFNSZ]; /* name of system LWP */
processorid_t pr_onpro; /* processor on which LWP is running */
processorid_t pr_bindpro; /* processor to which LWP is bound */
processorid_t pr_exbindpro; /* processor to which LWP is exbound */
Some of the entries in lwpsinfo, such as pr_flag,
pr_addr, pr_state, pr_stype, pr_wchan, and pr_name, refer
to internal kernel data structures and should not be
Copyright 1994 Novell, Inc. Page 11
proc(4) proc(4)
expected to retain their meanings across different
versions of the operating system. They have no meaning
to a program and are only useful for manual
interpretation by a user aware of the implementation
details.
CONTROL MESSAGES
Process state changes are effected through messages written to
the ctl file of the process or to the lwpctl file of an
individual LWP. All control messages consist of an int naming
the specific operation followed by additional data containing
operands (if any). Multiple control messages can be combined
in a single write(2) to a control file, but no partial writes
are permitted; that is, each control message (operation code
plus operands) must be presented in its entirety to the write
and not in pieces over several system calls.
Descriptions of the allowable control messages follow. Note
that writing a message to a control file for a process or LWP
that has exited elicits the error ENOENT.
PCSTOP, PCDSTOP, PCWSTOP
When applied to the process control file, PCSTOP directs all
LWPs to stop and waits for them to stop, PCDSTOP directs all
LWPs to stop without waiting for them to stop, and PCWSTOP
simply waits for all LWPs to stop. When applied to an LWP
control file, PCSTOP directs the specific LWP to stop and
waits until it has stopped, PCDSTOP directs the specific LWP
to stop without waiting for it to stop, and PCWSTOP simply
waits for the LWP to stop. When applied to an LWP control
file, PCSTOP and PCWSTOP complete when the LWP stops on an
event of interest, immediately if already so stopped; when
applied to the process control file, they complete when every
LWP has stopped on an event of interest.
An event of interest is either a PR_REQUESTED stop or a stop
that has been specified in the process's tracing flags (set by
PCSTRACE, PCSFAULT, PCSENTRY, and PCSEXIT). A PR_JOBCONTROL
stop is specifically not an event of interest. (An LWP may
stop twice because of a stop signal; first showing
PR_SIGNALLED if the signal is traced and again showing
PR_JOBCONTROL if the LWP is set running without clearing the
signal.) If PCSTOP or PCDSTOP is applied to an LWP that is
stopped, but not on an event of interest, the stop directive
takes effect when the LWP is restarted by the competing
mechanism; at that time the LWP enters a PR_REQUESTED stop
Copyright 1994 Novell, Inc. Page 12
proc(4) proc(4)
before executing any user-level code.
A write of a control message that blocks is interruptible by a
signal so that, for example, an alarm(2) can be set to avoid
waiting forever for a process or LWP that may never stop on an
event of interest. If PCSTOP is interrupted, the LWP stop
directives remain in effect even though the write returns an
error.
A system process (indicated by the PR_ISSYS flag) never
executes at user level, has no user-level address space
visible through /proc, and cannot be stopped. Applying
PCSTOP, PCDSTOP, or PCWSTOP to a system process or any of its
LWPs elicits the error EBUSY.
PCRUN
Make an LWP runnable again after a stop. The operand is a set
of flags, contained in a ulong_t, describing optional
additional actions. Flag definitions:
PRCSIG clears the current signal, if any (see PCSSIG).
PRCFAULT clears the current fault, if any (see
PCCFAULT).
PRSTEP directs the LWP to execute a single machine
instruction. On completion of the instruction, a trace
trap occurs. If FLTTRACE is being traced, the LWP
stops, otherwise it is sent SIGTRAP; if SIGTRAP is being
traced and not held, the LWP stops. When the LWP stops
on an event of interest the single-step directive is
cancelled, even if the stop occurs before the
instruction is executed. This operation requires
hardware and operating system support and may not be
implemented on all processors.
PRSABORT is significant only if the LWP is in a
PR_SYSENTRY stop or is marked PR_ASLEEP; it instructs
the LWP to abort execution of the system call (see
PCSENTRY, PCSEXIT).
PRSTOP directs the LWP to stop again as soon as possible
after resuming execution (see PCSTOP). In particular if
the LWP is stopped on PR_SIGNALLED or PR_FAULTED, the
next stop will show PR_REQUESTED, no other stop will
have intervened, and the LWP will not have executed any
Copyright 1994 Novell, Inc. Page 13
proc(4) proc(4)
user-level code.
When applied to an LWP control file PCRUN makes the specific
LWP runnable. The operation fails (EBUSY) if the specific LWP
is not stopped on an event of interest.
When applied to the process control file an LWP is chosen for
the operation as described for /proc/pid/status. The
operation fails (EBUSY) if the chosen LWP is not stopped on an
event of interest. If PRSTEP or PRSTOP were requested, the
chosen LWP is made runnable; otherwise, the chosen LWP is
marked PR_REQUESTED. If as a result all LWPs are in the
PR_REQUESTED stop state, they are all made runnable.
Once an LWP has been made runnable by PCRUN, it is no longer
stopped on an event of interest even if, because of a
competing mechanism, it remains stopped.
PCSTRACE
Define a set of signals to be traced in the process: the
receipt of one of these signals by an LWP causes the LWP to
stop. The set of signals is defined using an operand sigset_t
contained in the control message. Receipt of SIGKILL cannot
be traced; if specified, it is silently ignored.
If a signal that is included in a held signal set of an LWP is
sent to the LWP, the signal is not received and does not cause
a stop until it is removed from the held signal set, either by
the LWP itself or by setting the held signal set with PCSHOLD
or the PRSHOLD option of PCRUN.
PCSSIG
The current signal and its associated signal information for
the specific or chosen LWP are set according to the contents
of the operand siginfo structure (see <sys/siginfo.h>). If
the specified signal number is zero, the current signal is
cleared. An error (EBUSY) is returned if the LWP is not
stopped on an event of interest. The semantics of this
operation are different from those of kill(2), _lwp_kill(2),
or PCKILL in that the signal is delivered to the LWP
immediately after execution is resumed (even if the signal is
being held) and an additional PR_SIGNALLED stop does not
intervene even if the signal is being traced. Setting the
current signal to SIGKILL ends the process immediately.
Copyright 1994 Novell, Inc. Page 14
proc(4) proc(4)
PCKILL
If applied to the process control file, a signal is sent to
the process with semantics identical to those of kill(2). If
applied to an LWP control file, a signal is sent to the LWP
with semantics identical to those of _lwp_kill(2). The signal
is named in an operand int contained in the message. Sending
SIGKILL ends the process or LWP immediately.
PCUNKILL
A signal is deleted, that is, it is removed from the set of
pending signals. If applied to the process control file, the
signal is deleted from the process's pending signals. If
applied to an LWP control file, the signal is deleted from the
LWP's pending signals. The current signal (if any) is
unaffected. The signal is named in an operand int in the
control message. It is an error (EINVAL) to attempt to delete
SIGKILL.
PCSHOLD
Set the set of held signals for the specific or chosen LWP
(signals whose delivery will be delayed if sent to the LWP)
according to the operand sigset_t structure. SIGKILL or
SIGSTOP cannot be held; if specified, they are silently
ignored.
PCSFAULT
Define a set of hardware faults to be traced in the process:
on incurring one of these faults an LWP stops. The set is
defined via the operand fltset_t structure. 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 (bus error)
FLTBOUNDS memory bounds violation
FLTIOVF integer overflow
FLTIZDIV integer zero divide
FLTFPE floating-point exception
FLTSTACK unrecoverable stack fault
FLTPAGE recoverable page fault
Copyright 1994 Novell, Inc. Page 15
proc(4) proc(4)
When not traced, a fault normally results in the posting of a
signal to the LWP that incurred the fault. If an LWP stops on
a fault, the signal is posted to the LWP when execution is
resumed unless the fault is cleared by PCCFAULT or by the
PRCFAULT option of PCRUN. FLTPAGE is an exception; no signal
is posted. There may be additional processor-specific faults
like this. The pr_info field in /proc/pid/status or in
/proc/pid/lwp/lwpid/lwpstatus identifies the signal to be sent
and contains machine-specific information about the fault.
PCCFAULT
The current fault (if any) is cleared; the associated signal
is not sent to the specific or chosen LWP.
PCSENTRY, PCSEXIT
These control operations instruct the process's LWPs to stop
on entry to or exit from specified system calls. The set of
system calls to be traced is defined via an operand sysset_t
structure.
When entry to a system call is being traced, an LWP stops
after having begun the call to the system but before the
system call arguments have been fetched from the LWP. When
exit from a system call is being traced, an LWP stops on
completion of the system call just before checking for signals
and returning to user level. At this point all return values
have been stored into the LWP's registers.
If an LWP is stopped on entry to a system call (PR_SYSENTRY)
or when sleeping in an interruptible system call (PR_ASLEEP is
set), it may be instructed to go directly to system call exit
by specifying the PRSABORT flag in a PCRUN control message.
Unless exit from the system call is being traced the LWP
returns to user level showing error EINTR.
PCSET, PCRESET
PCSET sets one or more modes of operation for the traced
process. PCRESET resets these modes. The modes to be set or
reset are specified by flags in an operand long in the control
message:
PR_FORK (inherit-on-fork): When set, the tracing flags
of the process are inherited by the child of a fork(2)
or vfork(2). When reset, child processes start with all
tracing flags cleared.
Copyright 1994 Novell, Inc. Page 16
proc(4) proc(4)
PR_RLC (run-on-last-close): When set and the last
writable /proc file descriptor referring to the traced
process or any of its LWPs is closed, all the tracing
flags of the process are cleared, any outstanding stop
directives are canceled, and if any LWPs are stopped on
events of interest, they are set running as though PCRUN
had been applied to them. When reset, the process's
tracing flags are retained and LWPs are not set running
on last close.
PR_KLC (kill-on-last-close): When set and the last
writable /proc file descriptor referring to the traced
process or any of its LWPs is closed, the process is
exited with SIGKILL.
PR_ASYNC (asynchronous-stop): When set, a stop on an
event of interest by one LWP does not directly affect
any other LWP in the process. When reset and an LWP
stops on an event of interest other than PR_REQUESTED,
all other LWPs in the process are directed to stop.
It is an error (EINVAL) to specify flags other than those
described above or to apply these operations to a system
process. The current modes are reported in the pr_flags field
of /proc/pid/status.
PCSREG
Set the general registers for the specific or chosen LWP
according to the operand gregset_t structure. There may be
machine-specific restrictions on the allowable set of changes.
PCSREG fails (EBUSY) if the LWP is not stopped on an event of
interest.
PCSFPREG
Set the floating-point registers for the specific or chosen
LWP according to the operand fpregset_t structure. An error
(EINVAL) is returned if the system does not support floating-
point operations (no floating-point hardware and the system
does not emulate floating-point machine instructions).
PCSFPREG fails (EBUSY) if the LWP is not stopped on an event
of interest.
PCNICE
The traced (or chosen) LWP's nice(2) priority is incremented
by the amount contained in the operand int. Only the super-
user may better an LWP's priority in this way, but any user
Copyright 1994 Novell, Inc. Page 17
proc(4) proc(4)
may make the priority worse. This operation is significant
only when applied to an LWP in the time-sharing scheduling
class.
NOTICES
The effect of a control message is guaranteed to be atomic
with respect to the traced process, except when applied to a
system process.
To wait for any of a set of processes or LWPs to stop, /proc
file descriptors can be used in a poll(2) system call instead
of writing a PCWSTOP message. Descriptors for /proc/pid/ctl
/proc/pid/lwp/lwpid/lwpctl can be used for this purpose. When
requested and returned, the polling event POLLWRNORM shows
that the process or LWP stopped on an event of interest.
Although they cannot be requested, the polling events POLLHUP,
POLLERR and POLLNVAL may be returned. POLLHUP shows that the
process or LWP has exited. POLLERR shows that the file
descriptor has become invalid. POLLNVAL is returned
immediately if POLLWRNORM is requested on a file descriptor
referring to a system process (see PCSTOP).
For security reasons, except for the privileged 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
privileged user. Even if held by the privileged user, an open
process or LWP 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(2), fails with EBADF.
In this case, if any tracing flags are set and the process or
any LWP 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 PCSET). This enables a controlling process (if it
has permission) to reopen the process file to get new valid
file descriptors, close the invalid file descriptors, and
proceed. Just closing the invalid file descriptors causes the
traced process to resume execution with no tracing flags set.
Any process not currently open for writing by /proc 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.
Copyright 1994 Novell, Inc. Page 18
proc(4) proc(4)
For reasons of symmetry and efficiency there are more control
operations than strictly necessary.
FILES
/proc directory (list of processes)
/proc/nnnnn directory for process nnnnn
/proc/nnnnn/status status of process nnnnn
/proc/nnnnn/ctl control file for process nnnnn
/proc/nnnnn/psinfo ps info for process nnnnn
/proc/nnnnn/as address space of process nnnnn
/proc/nnnnn/map as map info for process nnnnn
/proc/nnnnn/object directory for objects for process nnnnn
/proc/nnnnn/sigact signal actions for process nnnnn
/proc/nnnnn/lwp/lll directory for LWP lll
/proc/nnnnn/lwp/lll/lwpstatus status of LWP lll
/proc/nnnnn/lwp/lll/lwpctl control file for LWP lll
/proc/nnnnn/lwp/lll/lwpsinfo ps info for LWP lll
REFERENCES
close(2), intro(2), open(2), poll(2), read(2), sigaction(2),
siginfo(5), signal(2), signal(5), write(2)
RETURN VALUES
Errors that can occur in addition to the errors normally
associated with file system access:
ENOENT The traced process or LWP has exited after being
opened.
EIO A write(2) was attempted at an illegal address in
the traced process.
EBUSY PCSTOP, PCDSTOP or PCWSTOP was applied to a system
process; an exclusive open was attempted on a
process file already open for writing; PCRUN,
PCSSIG, PCSREG or PCSFPREG was applied to a
process or LWP not stopped on an event of
interest; an attempt was made to mount /proc when
it is already mounted.
EPERM Someone other than the privileged user attempted
to better a process's priority by issuing PCNICE.
ENOSYS An attempt was made to do an unsupported operation
(such as create, remove, link, or unlink) on an
entry in /proc.
Copyright 1994 Novell, Inc. Page 19
proc(4) proc(4)
EINVAL In general this means that some invalid argument
was supplied to a system call. A non-exhaustive
list of conditions eliciting this error includes:
a control message operation code is undefined; a
control message is ill-formed; the PRSTEP option
of the PCRUN operation was used on an
implementation that does not support single-
stepping; an out-of-range signal number was
specified with PCSSIG, PCKILL, or PCUNKILL;
SIGKILL was specified with PCUNKILL; PCSFPREG was
applied on a machine without floating-point
support.
EINTR A signal was received by the controlling process
while waiting for the traced process or LWP to
stop via PCSTOP or PCWSTOP.
EBADF 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 or LWP file descriptor (except close)
elicit this error.
Copyright 1994 Novell, Inc. Page 20