proc(4)


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

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


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_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)).

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 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 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:

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.

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

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:

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

 /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(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.

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(2), intro(2), open(2), poll(2), read(2), sigaction(2), siginfo(5), signal(2), signal(5), write(2)

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.

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.


© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004