proc(F)

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(S), close(S), read(S), and write(S). 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 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(S) 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(S) 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).

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(S) 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(S) 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 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.

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(S)). 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 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(C) 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.

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:

       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:

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:

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(S)); 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(S)); 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(S)).

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(S). 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(C). 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 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(S) 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 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(S) 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 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(S), _lwp_kill(S), 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.

PCKILL

If applied to the process control file, a signal is sent to the process with semantics identical to those of kill(S). If applied to an LWP control file, a signal is sent to the LWP with semantics identical to those of _lwp_kill(S). 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

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(S) or vfork(S). When reset, child processes start with all tracing flags cleared.
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(S) 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 may make the priority worse. This operation is significant only when applied to an LWP in the time-sharing scheduling class.

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

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(S) 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.
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.

close(S), intro(S), open(S), poll(S), read(S), sigaction(S), siginfo(M), signal(S), signal(M), write(S)

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(S) 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(S), 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.

For reasons of symmetry and efficiency there are more control operations than strictly necessary.

The lwpstatus structure has been enhanced to handle floating point context changes on Pentium III processors; see ``Pentium III extended floating point support'' in New features for more information.

/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*