Contains state information about processes and threads in the system.
The /proc file system provides access to the state of each active process and thread in the system. The name of each entry in the /proc file system is a decimal number corresponding to the process ID. These entries are subdirectories and the owner of each is determined by the user ID of the process. Access to the process state is provided by additional files contained within each subdirectory. Except where otherwise specified, the term /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.
The various /proc directory, file, and field names contain the term lwp (light weight process). This term refers to a kernel thread. The /proc files do not refer to user space pthreads. While the operating system does not use the term lwp to describe its threads, it is used in the /proc file system for compatibility with other UNIX operating systems.
The following standard subroutine interfaces are used to access the /proc files:
- open subroutine
- close subroutine
- read subroutine
- write subroutine
Most files describe process state and are intended to be read-only. The ctl (control) and lwpctl (thread control) files permit manipulation of process state and can only be opened for writing. The as (address space) file contains the image of the running process and can be opened for both reading and writing. A write open allows process control while a read-only open allows inspection but not process control. Thus, a process is described as open for reading or writing if any of its associated /proc files is opened for reading or writing, respectively.
In general, more than one process can open the same /proc file at the same time. Exclusive open is intended to allow process control without another process attempting to open the file at the same time. A process can obtain exclusive control of a target process if it successfully opens any /proc file in the target process for writing (the as or ctl files, or the lwpctl file of any kernel thread) while specifying the O_EXCL flag in the open subroutine. Such a call of the open subroutine fails if the target process is already open for writing (that is, if a ctl, as, or lwpctl file is open for writing). Multiple concurrent read-only instances of the open subroutine can exist; the O_EXCL flag is ignored on the open subroutine for reading. The first open for writing by a controlling process should use the O_EXCL flag. Multiple processes trying to control the same target process usually results in errors.
Data may be transferred from or to any locations in the address space of the traced process by calling the lseek subroutine to position the as file at the virtual address of interest, followed by a call to the read or write subroutine. An I/O request extending into an unmapped area is truncated at the boundary. A read or write request beginning at an unmapped virtual address fails with errno set to EFAULT.
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 if flag is turned on */
Either the prfillset or premptyset macro must be used to initialize the pr_sigset_t or fltset_t type before it is used in any other operation. The flag parameter must be a member of the enumeration that corresponds to the appropriate set.
int num; /* Specifies the systemcall's number from sysent */ uint64_t sysnum; /* Specifies the number of elements in pr_set array */ uint64_t syssize; /* Allocates the size */ sysset_t *set; /* Specifies the pointer to sysset_t */ sysnum = (num - 1)/64 + 1; syssize = (sysnum + 1) * sizeof(uint64_t); set = (sysset_t *)malloc(syssize); set->pr_size = sysnum; prfillsysset(set) /* set all syscalls in the sysset */ premptysysset(set) /* clear all syscalls in the sysset */ praddsysset(set, num) /* set specified syscall in the sysset */ prdelsysset(set, num) /* clear specified syscall in the sysset */ prissyssetmember(set, num) /* !=0 if specified syscall is set */
See the description of the sysent file for more information about system calls.
Every active process contains at least one kernel thread. Every kernel thread represents a flow of execution that is independently scheduled by the operating system. All kernel threads in a process share address space as well as many other attributes. Using the ctl and lwpctl files, you can manipulate individual kernel threads in a process or manipulate all of them at once, depending on the operation.
When a process has more than one kernel thread, a representative thread is chosen by the system for certain process status file and control operations. The representative thread is stopped only if all the process's threads are stopped. The representative thread may be stopped on an event of interest only if all threads are stopped, or it may be stopped by a PR_REQUESTED stop only if no other events of interest exist.
The representative thread remains fixed as long as all the threads are stopped on events of interest or are in PR_SUSPENDED stop and the PCRUN operand is not applied to any of them.
When applied to the process control file (ctl), every /proc control operation that affects a kernel thread uses the same algorithm to choose which kernel thread to act on. With synchronous stopping (see PCSET), this behavior enables an application to control a multiple thread process using only the process level status and control files. For more control, use the thread-specific lwpctl files.
The /proc file system can be used by both 32-bit and 64-bit control processes to get information about both 32-bit and 64-bit target processes. The /proc files provide 64-bit enabled mode invariant files to all observers. The mode of the controlling process does not affect the format of the /proc data. Data is returned in the same format to both 32-bit and 64-bit control processes. Addresses and applicable length and offset fields in the /proc files are 8 bytes long.
At the top level, the /proc directory contains entries, each of which names an existing process in the system. The names of entries in this directory are process ID (pid) numbers. These entries are directories. Except where otherwise noted, the files described below are read-only. In addition, if a process becomes a zombie (one that has been terminated by its parent with an exit call but has not been suspended by a wait call), most of its associated /proc files disappear from the directory structure. Normally, later attempts to open or to read or write to files that are opened before the process is terminated elicit the ENOENT message. Exceptions are noted.
The /proc files contain data that presents the state of processes and threads in the system. This state is constantly changing while the system is operating. To lessen the load on system performance caused by reading /proc files, the /proc file system does not stop system activity while gathering the data for those files. A single read of a /proc file generally returns a coherent and fairly accurate representation of process or thread state. However, because the state changes as the process or thread runs, multiple reads of /proc files may return representations that show different data and therefore appear to be inconsistent with each other.
The /proc/pid File Structure
The /proc/pid directory contains (but is not limited to) the following entries:
- Contains the address space image of the process. The as file can be opened for both reading and writing. The lseek subroutine is used to position the file at the virtual address of interest. Afterwards, you can view and modify the address space with the read and write subroutines, respectively.
- 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, see types of control messages for more information. Individual threads 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.
- Contains state information about the process and one of its representative
thread. The file is formatted as a struct pstatus type containing
the following members:
uint32_t pr_flag; /* process flags from proc struct p_flag */ uint32_t pr_flag2; /* process flags from proc struct p_flag2 */ uint32_t pr_flags; /* /proc flags */ uint32_t pr_nlwp; /* number of threads in the process */ char pr_stat; /* process state from proc p_stat */ char pr_dmodel; /* data model for the process */ char pr__pad1; /* reserved for future use */ pr_sigset_t pr_sigpend; /* set of process pending signals */ prptr64_t pr_brkbase; /* address of the process heap */ uint64_t pr_brksize; /* size of the process heap, in bytes */ prptr64_t pr_stkbase; /* address of the process stack */ uint64_t pr_stksize; /* size of the process stack, in bytes */ pid64_t pr_pid; /* process id */ pid64_t pr_ppid; /* parent process id */ pid64_t pr_pgid; /* process group id */ pid64_t pr_sid; /* session id */ struct pr_timestruc64_t pr_utime; /* process user cpu time */ struct pr_timestruc64_t pr_stime; /* process system cpu time */ struct pr_timestruc64_t pr_cutime; /* sum of children's user times */ struct pr_timestruc64_t pr_cstime; /* sum of children's system times */ pr_sigset_t pr_sigtrace; /* mask of traced signals */ fltset_t pr_flttrace; /* mask of traced hardware faults */ uint32_t pr_sysentry_offset; /* offset into pstatus file of sysset_t * identifying system calls traced on * entry. If 0, then no entry syscalls * are being traced. */ uint32_t pr_sysexit_offset; /* offset into pstatus file of sysset_t * identifying system calls traced on * exit. If 0, then no exit syscalls * are being traced. */ uint64_t pr__pad; /* reserved for future use */ lwpstatus_t pr_lwp; /* "representative" thread status */
The members of the status file are described below:
- Specifies a bit-mask holding these flags:
- Process is a kernel process (see PCSTOP)
- Process has its inherit-on-fork flag set (see PCSET)
- Process has its run-on-last-close flag set (see PCSET)
- Process has its kill-on-last-close flag set (see PCSET)
- Process has its asynchronous-stop flag set (see PCSET)
- Process is controlled by the ptrace subroutine
- Specifies the total number of threads in the process
- Specifies the virtual address of the process heap
- Specifies the size, in bytes, of the process heap Note: The address formed by the sum of the pr_brkbase and pr_brksize is the process break (see the brk subroutine).
- Specifies the virtual address of the process stack
- Specifies the size, in bytes, of the process stack Note: Each thread runs on a separate stack. The operating system grows the process stack as necessary.
- Specifies the process ID
- Specifies the parent process ID
- Specifies the process group ID
- Specifies the session ID of the process
- Specifies the user CPU time consumed by the process
- Specifies the system CPU process time consumed by the process
- Specifies the cumulative user CPU time consumed by the children of the process, expressed in seconds and nanoseconds
- Specifies the cumulative system CPU time, in seconds and nanoseconds, consumed by the process's children
- Specifies the set of signals that are being traced (see the PCSTRACE signal)
- Specifies the set of hardware faults that are being traced (see the PCSFAULT signal)
- If non-zero, contains offsets into the status file to the sysset_t sets of system calls being traced on system call entry (see the PCSENTRY signal). This flag is zero if system call tracing is not active for the process.
- If non-zero, contains offsets into the status file to the sysset_t sets of system calls being traced on system call exit (see the PCSEXIT signal). This field is zero if system call tracing is not active for the process.
- If the process is not a zombie, contains an lwpstatus_t structure describing a representative thread. The contents of this structure have the same meaning as if it was read from a lwpstatus file.
- Contains information about the process needed by the ps command. If the process contains more than one thread, a representative
thread is used to derive the lwpsinfo information. The file
is formatted as a struct psinfo type and contains the following
uint32_t pr_flag; /* process flags from proc struct p_flag */ uint32_t pr_flag2; /* process flags from proc struct p_flag2 */ uint32_t pr_nlwp; /* number of threads in process */ uid_t pr_uid; /* real user id */ uid_t pr_euid; /* effective user id */ gid_t pr_gid; /* real group id */ gid_t pr_egid; /* effective group id */ uint32_t pr_argc; /* initial argument count */ pid64_t pr_pid; /* unique process id */ pid64_t pr_ppid; /* process id of parent */ pid64_t pr_pgid; /* pid of process group leader */ pid64_t pr_sid; /* session id */ dev64_t pr_ttydev; /* controlling tty device */ prptr64_t pr_addr; /* internal address of proc struct */ uint64_t pr_size; /* size of process image in KB (1024) units */ uint64_t pr_rssize; /* resident set size in KB (1024) units */ struct pr_timestruc64_t pr_start; /* process start time, time since epoch */ struct pr_timestruc64_t pr_time; /* usr+sys cpu time for this process */ prptr64_t pr_argv; /* address of initial argument vector in user process */ prptr64_t pr_envp; /* address of initial environment vector in user process */ char pr_fname[PRFNSZ]; /* last component of exec()ed pathname*/ char pr_psargs[PRARGSZ]; /* initial characters of arg list */ uint64_t pr__pad; /* reserved for future use */ struct lwpsinfo pr_lwp; /* "representative" thread info */Note: Some of the entries in the psinfo file, such as pr_flag, pr_flag2, and pr_addr, refer to internal kernel data structures and might not retain their meanings across different versions of the operating system. They mean nothing to a program and are only useful for manual interpretation by a user aware of the implementation details.
The psinfo file is accessible after a process becomes a zombie.
The pr_lwp flag describes the representative thread chosen. If the process is a zombie, the pr_nlwp and pr_lwp.pr_lwpid flags are zero and the other fields of pr_lwp are undefined.
- Contains 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. Note: The map file might contain entries only for the virtual address regions of the process that contain the objects that are loaded into the process.The prmap structure contains the following members:
uint64_t pr_size; /* size of mapping in bytes */ prptr64_t pr_vaddr; /* virtual address base */ char pr_mapname[PRMAPSZ]; /* name in the /proc/pid/object object */ uint64_t pr_off; /* offset to the mapped object, if any */ uint32_t pr_mflags; /* protection and attribute flags */ uint32_t pr_pathoff; /* if map indicates the entry for a loaded object, * offset points to a null-terminated path name followed * by a null-terminated member name. * If the offset is mapped to a file and it is not an * archive file, the member name is null. * The offset is 0 if map entry is * not applicable for a loaded object. */ int32_t pr_shmid; /* shared memory ID for the MA_SHM or * MA_RTSHM region. * <0 indicates that teh shared memory ID is not * available. */ dev64_t pr_dev; /* the dev_t data structure for the MA_FILEMAP file. * -1 indicates that the dev_t is not available * -2 indicates that the file is on remote filesystem, * -3 indicates that the file is in a WPAR. */ ino64_t pr_ino; /* The inode datastructure for the MA_FILEMAP file. * -1 indicates that the ino_t data structure is not * available */ vmid64_t pr_vsid; /* virtual segment ID for the first segment * in the region. */
The members are described below:
- Specifies the virtual address of the mapping within the traced process
- Specifies the size of the mapping within the traced process
- If not an empty string, contains the name of a file that resides in the object directory and contains a file descriptor for the object to which the virtual address is mapped. The file is opened with the open subroutine.
- Contains the offset within the mapped object (if any) to which the virtual address is mapped
- If non-zero, contains an offset into the map file to the path name and archive member name of a loaded object
- Specifies a bit-mask of protection and the following attribute flags:
- Indicates that mapping applies to the main executable in the process.
- Indicates that mapping applies to the program data and heap ranges in the process.
- Indicates that the mapping applies to stack range in the process.
- Indicates that mapping applies to an object that is mapped to the process by using the mmap subroutine.
- Indicates that mapping applies to POSIX real-time objects that are created by the shm_open subroutine.
- These objects are mapped to the process by using the
- Indicates that mapping applies to an object that is mapped to the process by using the shmat subroutine.
- Indicates that mapping applies to a file object that is mapped to the process by using the
mmapsubroutine or the
- Indicates that mapping applies to memory that is mapped to the process by the loader or by other kernel subsystem.
- Indicates that mapping applies to a memory or I/O region that is mapped into the process by using the rmmap_create subroutine.
- Indicates that mapping applies to kernel memory that is mapped to the process.
- Indicates that mapping is supported by 4 KB blocks of physical memory.
- Indicates that mapping is supported by 64 KB blocks of physical memory.
- Indicates that mapping is supported by 16 MB blocks of physical memory.
- Indicates that mapping is supported by 16 GB blocks of physical memory.
- Indicates that mapping is readable by the traced process.
- Indicates that mapping is writable by the traced process.
- Indicates that mapping is executable by the traced process.
- Indicates that mapping changes are shared by the mapped object.
- For the MA_SHM mapping, contains the System V shared memory ID of the mapping. Use the ipcs -m command to display the shared memory IDs.
- For the MA_FILEMAP mapping, contains the device ID number of the mapped file.
- For MA_FILEMAP mapping, contains the inode number of the mapped file relative to the device ID
- Contains the first Virtual Memory Manager segment ID in the mapping.
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. Read and write operations to private mappings always succeed. Read and write operations to unmapped addresses always fail.
- Contains a description of the credentials associated with the
process. The file is formatted as a struct prcred type and
contains 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) */ uint32_t pr_ngroups; /* number of supplementary groups */ gid_t pr_groups; /* array of supplementary groups */
- Contains information about the system calls available to the process.
The file can be used to find the number of a specific system call
to trace. It can be used to find the name of a system call associated
with a system call number returned in a lwpstatus file.
The file consists of a header section followed by an array of entries, each of which corresponds to a system call provided to the process. Each array entry contains the system call number and an offset into the sysent file to that system call's null-terminated name.
The sysent file is characterized by the following attributes:
- The system call names are the actual kernel name of the exported system call.
- The entries in the array do not have any specific ordering.
- There may be gaps in the system call numbers.
- Different processes may have different system call names and numbers, especially between a 32-bit process and a 64-bit process. Do not assume that the same names or numbers cross different processes.
- The set of system calls may change during while the operating system is running. You can add system calls while the operating system is running.
- The names and numbers of the system calls may change within different releases or when service is applied to the system.
- A link that provides access to the current working directory of the process. Any process can access the current working directory of the process through this link, provided it has the necessary permissions.
- Contains files for all open file descriptors of the process. Each entry is a decimal number corresponding to an open file descriptor in the process. If an enty refers to a regular file, it can be opened with normal file semantics. To ensure that the contolling process cannot gain greater access, there are no file access modes other than its own read/write open modes in the controlled process. Directories will be displayed as links. An attempt to open any other type of entry will fail (hence it will display 0 permission when listed).
- 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), without the process first obtaining the specific path names of those files.
- A link that provides access to the current root directory of the process. Any process can access the current root directory of the process through this link, provided that the process (that is attempting to access the root directory) has the necessary permissions.
- A file that contains an array of stat64x structures. Each structure describes information about a file that is associated with a memory-mapped area that is owned by the process.
- A directory containing entries each of which names a kernel thread within the containing process. The names of entries in this directory are thread ID (tid) numbers. These entries are directories containing additional files described below.
The /proc/pid/lwp/tid Structure
The directory /proc/pid/lwp/tid contains the following entries:
- This is a write-only control file. The messages written to this file affect only the associated thread rather than the process as a whole (where appropriate).
- Contains thread-specific state information. This information is
also present in the status file of the process for its representative
thread. The file is formatted as a struct lwpstatus and contains
the following members:
uint64_t pr_lwpid; /* specific thread id */ uint32_t pr_flags; /* thread status flags */ char pr_state; /* thread state - from thread.h t_state */ uint16_t pr_cursig; /* current signal */ uint16_t pr_why; /* reason for stop (if stopped) */ uint16_t pr_what; /* more detailed reason */ uint32_t pr_policy; /* scheduling policy */ char pr_clname[PRCLSZ]; /* printable character representing pr_policy */ pr_sigset_t pr_lwppend; /* set of signals pending to the thread */ pr_sigset_t pr_lwphold; /* set of signals blocked by the thread */ pr_siginfo64_t pr_info; /* info associated with signal or fault */ pr_stack64_t pr_altstack; /* alternate signal stack info */ struct pr_sigaction64 pr_action; /* signal action for current signal */ uint16_t pr_syscall; /* system call number (if in syscall) */ uint16_t pr_nsysarg; /* number of arguments to this syscall */ uint64_t pr_sysarg[PRSYSARGS]; /* arguments to this syscall */ prgregset_t pr_reg; /* general and special registers */ prfpregset_t pr_fpreg; /* floating point registers */ pfamily_t pr_family; /* hardware platform specific information */
The members of the lwpstatus file are described below:
- Specifies a bit-mask holding these flags:
- Indicates that the thread is stopped
- Indicates that the thread is stopped on an event of interest (see the PCSTOP signal)
- Indicates that the thread has a stop directive in effect (see the PCSTOP signal)
- Thread is in an interruptible sleep within a system call
- No register state was provided for the thread
- pr_why and pr_what
- Provides the reason for why a thread was stopped. The following
are possible values of the pr_why member:
- Shows that the thread was stopped in response to a stop directive, normally because the PCSTOP signal was applied or because another thread stopped on an event of interest and the asynchronous-stop flag (see the PCSET signal) was not set for the process. The pr_what member is unused in this case.
- Shows that the thread stopped on receipt of a signal (see the PCSTRACE signal). The pr_what signal holds the signal number that caused the stop (for a newly-stopped thread, the same value is given with the pr_cursig member).
- Shows that the thread stopped upon incurring a hardware fault (see the PCSFAULT signal). The pr_what member contains the fault number that caused the stop.
- Shows a stop on entry to a system call (see the PCSENTRY signal). The pr_what member contains the system call number.
- Shows a stop on exit from a system call (see the PCSEXIT signal). The pr_what contains the system call number.
- Shows that the thread stopped because of the default action of a job control stop signal (see the sigaction subroutine). The pr_what member contains the stopping signal number.
- Names the specific thread I/O
- Names the current signal, which is the next signal to be delivered to the thread. When the thread is stopped by the PR_SIGNALLED or PR_FAULTED signal, the pr_info member contains additional information pertinent to the particular signal or fault. The amount of data contained in the pr_info member depends on the stop type and whether on not the application specified the SA_SIGINFO flag when the signal handler was established. For PR_FAULTED stops and PR_SIGNALLED stops when the SA_SIGINFO flag was not specified, only the si_signo, si_code, and si_addr pr_info fields contain data. For PR_SIGNALLED stops when the SA_SIGINFO flag is specified, the other pr_info fields contain data as well.
- Contains the signal action information about the current signal. This member is undefined if the pr_cursig member is zero. See the sigaction subroutine.
- Identifies any synchronously generated or thread-directed signals pending for the thread. It does not include signals pending at the process level.
- Contains the alternate signal stack information for the thread. See the sigaltstack subroutine.
- Specifies the number of the system call, if any, that is being
executed by the thread. It is non-zero if and only if the thread
is stopped on PR_SYSENTRY or PR_SYSEXIT.
If the pr_syscall member is non-zero, the pr_nsysarg member is the number of arguments to the system call and the pr_sysarg array contains the arguments. The pr_nsysarg member is always set to 8, the maximum number of system call parameters. The pr_sysarg member always contain eight arguments.
- Contains the name of the scheduling class of the thread
- Structure containing the threads general and special registers. The size and field names of this structure are machine dependent. See the <sys/m_procfs.h> header file for description of this structure for your particular machine. The contents of this structure are undefined if the thread is not stopped.
- Structure containing the threads floating point registers. The size and field names of this structure are machine dependent. The contents of this structure are undefined if the thread is not stopped.
- Contains the machine-specific information about the thread. Use of this field is not portable across different architectures. The pr_family structure contains extended context offset and size fields, which, if non-zero, indicate the availability of extended machine context information for the thread. A subsequent read of the status or lwpstatus file at the specified offset and size will retrieve the extended context information corresponding to a prextset structure. Alternatively, the entire lwpstatus file can be read and formatted as a struct lwpstatusx, which includes the prextset extension. The pr_family extended context offset and size members, if non-zero, indicate if the prextset member of the lwpstatusx structure is valid.
- Contains information about the thread needed by the ps command. This information is also present
in the psinfo file of the process for its representative thread
if it has one. The file is formatted as a struct lwpsinfo type
containing the following members:
uint64_t pr_lwpid; /* thread id */ prptr64_t pr_addr; /* internal address of thread */ prptr64_t pr_wchan; /* wait addr for sleeping thread */ uint32_t pr_flag; /* thread flags */ uchar_t pr_wtype; /* type of thread wait */ 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*/ uint32_t pr_policy; /* scheduling policy */ char pr_clname[PRCLSZ]; /* printable character representing pr_policy */ cpu_t pr_onpro; /* processor on which thread last ran */ cpu_t pr_bindpro; /* processor to which thread is bound */
Some of the entries in the lwpsinfo file, such as pr_flag, pr_addr, pr_state, pr_wtype, and pr_wchan, 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.
Process state changes are effected through messages written to the ctl file of the process or to the lwpctl file of an individual thread. All control messages consist of an int operation code identifying the specific operation followed by additional data containing operands (if any). Multiple control messages can be combined in a single write subroutine to a control file, but no partial writes are permitted. Each control message (operation code plus operands) must be presented in its entirety to the write subroutine, not in pieces through several system calls.
- PCSTOP, PCDSTOP, PCWSTOP
- When applied to the process control file,
- PCSTOP directs all threads to stop and waits for them to stop;
- PCDSTOP directs all threads to stop without waiting for them to stop;
- PCWSTOP simply waits for all threads to stop.
When applied to a thread control file,
- PCSTOP directs the specific thread to stop and waits until it has stopped;
- PCDSTOP directs the specific thread to stop without waiting for it to stop;
- PCWSTOP simply waits for the thread to stop.
When applied to a thread control file, PCSTOP and PCWSTOP complete when the thread stops on an event of interest and immediately if the thread is already stopped.
When applied to the process control file, PCSTOP and PCWSTOP complete when every thread 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). PR_JOBCONTROL and PR_SUSPENDED stops are not events of interest. (A thread may stop twice because of a stop signal; first showing PR_SIGNALLED if the signal is traced and again showing PR_JOBCONTROL if the thread is set running without clearing the signal.) If PCSTOP or PCDSTOP is applied to a thread that is stopped, but not because of an event of interest, the stop directive takes effect when the thread is restarted by the competing mechanism; at that time the thread enters a PR_REQUESTED stop before executing any user-level code.
A write operation of a control message that blocks is interruptible by a signal so that, for example, an alarm subroutine can be set to avoid waiting for a process or thread that may never stop on an event of interest. If PCSTOP is interrupted, the thread stop directives remain in effect even though the write subroutine returns an error.
A kernel process (indicated by the PR_ISSYS flag) is never executed at user level and cannot be stopped. It has no user-level address space visible through the /proc file system. Applying PCSTOP, PCDSTOP, or PCWSTOP to a system process or any of its threads elicits the error EBUSY.
- Executes a thread again after it was stopped. The operand is a
set of flags, contained in an int operand, describing optional
The allowed flags for PCRUN are described below:
- Clears the current signal, if any. See PCSSIG.
- Clears the current fault, if any. See PCCFAULT.
- Directs the thread to execute a single machine instruction. On completion of the instruction, a trace trap occurs. If FLTTRACE is being traced, the thread stops, otherwise it is sent SIGTRAP. If SIGTRAP is being traced and not held, the thread stops. When the thread stops on an event of interest the single-step directive is cancelled, even if the stop occurs before the instruction is executed.
- Instructs the thread to abort execution of the system call. See PCSENTRY, and PCSEXIT. It is significant only if the thread is in a PR_SYSENTRY stop or is marked PR_ASLEEP.
- Directs the thread to stop again as soon as possible after resuming execution. See PCSTOP. In particular, if the thread is stopped on PR_SIGNALLED or PR_FAULTED, the next stop shows PR_REQUESTED, no other stop intervenes, and the thread does not execute any user-level code.
When applied to a thread control file, PCRUN makes the specific thread runnable. The operation fails and returns the error EBUSY if the specific thread is not stopped on an event of interest.
When applied to the process control file, a representative thread is chosen for the operation as described for the /proc/pid/status file. The operation fails and returns the error EBUSY if the representative thread is not stopped on an event of interest. If PRSTEP or PRSTOP were requested, PCRUN makes the representative thread runnable. Otherwise, the chosen thread is marked PR_REQUESTED. If as a result all threads are in the PR_REQUESTED stop state, they all become runnable.
Once PCRUN makes a thread runnable, it is no longer stopped on an event of interest, even if it remains stopped because of a competing mechanism.
- Defines a set of signals to be traced in the process. Upon receipt
of one of these signals, the thread stops. The set of signals is
defined using an operand pr_sigset_t contained in the control
message. Receipt of SIGKILL cannot be traced. If you specify SIGKILL, the thread ignores it.
If a signal that is included in a thread's held signal set is sent to that thread, the signal is not received and does not cause a stop until it is removed from the held signal set. Either the thread itself removes it or you remove it by setting the held signal set with PCSHOLD or the PRSHOLD option of PCRUN.
- Specifies the current signal and its associated signal information
for the specific thread or representative thread. This information
is set according with the operand pr_siginfo64 structure.
If the specified signal number is zero, the current signal is cleared.
The error EBUSY is returned if the thread is not stopped on
an event of interest.
The syntax of this operation are different from those of the kill subroutine, pthread__kill subroutine, or PCKILL. With PCSSIG, the signal is delivered to the thread 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.
- If applied to the process control file, a signal is sent to the process with syntax identical to those of the kill subroutine. If applied to a thread control file, a signal is sent to the thread with syntax identical to those of the pthread__kill subroutine. The signal is named in an operand int contained in the message. Sending SIGKILL ends the process or thread immediately.
- Specifies a signal to be 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 a thread control file, the signal is deleted from the thread's pending signals. The current signal (if any) is unaffected. The signal is named in an operand int in the control message. An attempt to delete SIGKILL results in the error EINVAL.
- Sets the set of held signals for the specific or representative thread according to the operand sigset_t structure. Held signals are those whose delivery is delayed if sent to the thread. SIGKILL or SIGSTOP cannot be held. If specified, they are silently ignored.
- Defines a set of hardware faults to be traced in the process.
When incurring one of these faults, a thread stops. The set is defined
via the operand fltset_t structure. Fault names are defined
in the <sys/procfs.h> file and include the following: Note: Some of these may not occur on all processors; other processor-specific faults may exist in addition to those described here.
- Illegal instruction
- Privileged instruction
- Breakpoint trap
- Trace trap
- Memory access fault (bus error)
- Memory bounds violation
- Integer overflow
- Integer zero divide
- Floating-point exception
- Unrecoverable stack fault
When not traced, a fault normally results in the posting of a signal to the thread that incurred the fault. If a thread stops on a fault, the signal is posted to the thread when execution is resumed unless the fault is cleared by PCCFAULT or by the PRCFAULT option of PCRUN. The pr_info field in /proc/pid/status or in /proc/pid/lwp/tid/lwpstatus identifies the signal to be sent and contains machine-specific information about the fault.
- Specifies the current fault, if any, to be cleared. The associated signal is not sent to the specified thread or representative thread.
- Instructs the process's threads to stop on entry to 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, a thread stops after having begun the call to the
system but before the system call arguments have been fetched from
If a thread 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 thread returns to user level showing error EINTR.
- Instructs the process's threads to stop on exit from specified system calls. The set of system calls to be traced is defined via an operand sysset_t structure. When exit from a system call is being traced, a thread 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 threads's registers.
- PCSET, PCRESET, PCUNSET
- PCSET sets one or more modes of operation for the traced
process. PCRESET or PCUNSET resets these modes. The
modes to be set or reset are specified by flags in an operand int 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 or vfork subroutine. 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 thread is closed, all the tracing flags of the process are cleared, any outstanding stop directives are cancelled, and if any threads 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 threads 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 threads is closed, the process is exited with SIGKILL.
- PR_ASYNC (asynchronous-stop)
- When set, a stop on an event of interest by one thread does not directly affect other threads in the process. When reset and a thread stops on an event of interest other than PR_REQUESTED, all other threads in the process are directed to stop.
The error EINVAL is returned if you 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 the /proc/pid/status file.
- Sets the general and special registers for the specific or representative thread according to the operand prgregset_t structure. There may be machine-specific restrictions on the allowable set of changes. PCSREG fails and returns the error EBUSY if the thread is not stopped on an event of interest or is stopped in the kernel.
- Sets the floating point registers for the specific or representative thread according to the operand fpregset_t structure. The 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 and returns the error EBUSY if the thread is not stopped on an event of interest or is stopped in the kernel.
- Sets the vector registers for the specific or representative thread according to the operand prvregset_t structure. The error EINVAL is returned if the system does not support vector operations (no vector hardware and the system does not emulate vector machine instructions), or if the representative thread has not referenced the vector unit. PCSVREG fails and returns the error EBUSY if the thread is not stopped on an event of interest or is stopped in the kernel.
- The traced process's nice priority is incremented by the amount contained in the operand int. Only the superuser may better a process's priority in this way, but any user may make the priority worse. This operation is significant only when applied to a process in the time-sharing scheduling class.
|/proc||Directory (list of processes)|
|/proc/pid||Directory for the process pid|
|/proc/pid/status||Status of process pid|
|/proc/pid/ctl||Control file for process pid|
|/proc/pid/psinfo||ps info for process pid|
|/proc/pid/as||Address space of process pid|
|/proc/pid/map||as map info for process pid|
|/proc/pid/cred||Credentials information for process pid|
|/proc/pid/object||Directory for objects for process pid|
|/proc/pid/root||Link to the current root directory for process pid|
|/proc/pid/mmap||Memory-mapped files information for process pid|
|/proc/pid/sigact||Signal actions for process pid|
|/proc/pid/sysent||System call information for process pid|
|/proc/pid/cwd||Link to the current working directory for process pid|
|/proc/pid/fd||Directory for open file descriptors for process pid|
|/proc/pid/lwp/tid||Directory for thread tid|
|proc/pid/lwp/tid/lwpstatus||Status of thread tid|
|/proc/pid/lwp/tid/lwpctl||Control file for thread tid|
|/proc/pid/lwp/tid/lwpsinfo||ps info for thread tid|
Other errors can occur in addition to the errors normally associated with file system access:
|ENOENT||The traced process or thread has exited after being opened.|
|EFAULT||A read or write request was begun at an invalid virtual address.|
|EIO||A write subroutine was attempted at an illegal address in the traced process.|
|EBUSY||This error is returned because of one of the following reasons:
|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 the /proc file system.|
|EINVAL||An invalid argument was supplied to a system call. The following
are some—but not all—possible conditions that can elicit this error:
|EINTR||A signal was received by the controlling process while waiting for the traced process or thread to stop via PCSTOP or PCWSTOP.|
|EBADF||The traced process performed an exec subroutine on a setuid/setgid object file or on an object file that is not readable for the process. All further operations on the process or thread file descriptor (except the close subroutine) elicit this error.|
The effect of a control message is guaranteed to be atomic with respect to the traced process.
For security reasons, except for the privileged user, an open subroutine of a /proc file fails unless both the effective user ID and effective 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 thread file descriptor becomes invalid if the traced process performs an exec subroutine on a setuid/setgid object file or on an object file that it cannot read. Any operation performed on an invalid file descriptor, except for the close subroutine, fails with EBADF. In this case, if any tracing flags are set and the process or any thread file is open for writing, the process is directed to stop and its run-on-last-close flag is set (see PCSET).
This feature enables a controlling process (that has the necessary permission) to reopen the process file to obtain 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 that is not currently open for writing with tracing flags left over from a previous open subroutine and that performs an exec subroutine on a setuid/setgid or unreadable object file is not stopped. However, that process does not have all its tracing flags cleared.