/proc File

Purpose

Contains state information about processes and threads in the system.

Syntax

   #include <sys/procfs.h>

Description

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.

Information and control operations are provided through additional files. The <sys/procfs.h> file contains definitions of data structures and message formats used with these files. Some of these definitions use sets of flags. The set types pr_sigset_t, fltset_t, and sysset_t correspond to signal, fault, and system call enumerations, respectively. These enumerations are defined in the <sys/procfs.h> files. The pr_sigset_t and fltset_t types are 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 the following 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 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.

The sysset_t set type has a different format, set of macros, and a variable length structure to accommodate the varying number of available system calls. You can determine the total number of system calls, their names, and number of each individual call by reading the sysent file. You can then allocate memory for the appropriately sized sysset_t structure, by ensuring that the pr_sysset array needs an element for every 64 system call numbers, initialize its pr_size field, and then use the following macros to manipulate the system call 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.

Directory Structure

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.

An atomic representation is a representation of the process or thread at a single and discrete point in time. If you want an atomic snapshot of process or thread state, stop the process and thread before reading the state. There is no guarantee that the data is an atomic snapshot for successive reads of /proc files for a running process. In addition, a representation is not guaranteed to be atomic for any I/O applied to the as (address space) file. The contents of any process address space might be simultaneously modified by a thread of that process or any other process in the system.

Note: Multiple structure definitions are used to describe the /proc files. A /proc file may contain additional information other than the definitions presented here. In future releases of the operating system, these structures may grow by the addition of fields at the end of the structures.

The /proc/pid File Structure

The /proc/pid directory contains (but is not limited to) the following entries:

as

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.

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

status

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[6];               /* 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[8];                /* reserved for future use */
lwpstatus_t pr_lwp;                 /* "representative" thread status */

The members of the status file are described below:

pr_flags

Specifies a bit-mask holding these flags:

PR_ISSYS: Process is a kernel 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_PTRACE: Process is controlled by the ptrace subroutine

pr_nlwp

Specifies the total number of threads in the process

pr_brkbase

Specifies the virtual address of the process heap

pr_brksize

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

pr_stkbase

Specifies the virtual address of the process stack

pr_stksize

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.

pr_pid

Specifies the process ID

pr_ppid

Specifies the parent process ID

pr_pgid

Specifies the process group ID

pr_sid

Specifies the session ID of the process

pr_utime

Specifies the user CPU time consumed by the process

pr_stime

Specifies the system CPU process time consumed by the process

pr_cutime

Specifies the cumulative user CPU time consumed by the children of the process, expressed in seconds and nanoseconds

pr_cstime

Specifies the cumulative system CPU time, in seconds and nanoseconds, consumed by the process's children

pr_sigtrace

Specifies the set of signals that are being traced (see the PCSTRACE signal)

pr_flttrace

Specifies the set of hardware faults that are being traced (see the PCSFAULT signal)

pr_sysentry_offset

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.

pr_sysexit_offset

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.

pr_lwp

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.

psinfo

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 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_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[8];                /* 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.

map

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:

pr_vaddr

Specifies the virtual address of the mapping within the traced process

pr_size

Specifies the size of the mapping within the traced process

pr_mapname

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.

pr_off

Contains the offset within the mapped object (if any) to which the virtual address is mapped

pr_pathoff

If non-zero, contains an offset into the map file to the path name and archive member name of a loaded object

pr_mflags

Specifies a bit-mask of protection and the following attribute flags:

MA_MAINEXEC

Indicates that mapping applies to the main executable in the process.

MA_BREAK

Indicates that mapping applies to the program data and heap ranges in the process.

MA_STACK

Indicates that the mapping applies to stack range in the process.

MA_MMAP

Indicates that mapping applies to an object that is mapped to the process by using the mmap subroutine.

MA_RTSHM

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 mmap subroutine.

MA_SHM

Indicates that mapping applies to an object that is mapped to the process by using the shmat subroutine.

MA_FILEMAP

Indicates that mapping applies to a file object that is mapped to the process by using the mmap subroutine or the shmat subroutine.

MA_WORK

Indicates that mapping applies to memory that is mapped to the process by the loader or by other kernel subsystem.

MA_RMMAP

Indicates that mapping applies to a memory or I/O region that is mapped into the process by using the rmmap_create subroutine.

MA_KERNTEXT

Indicates that mapping applies to kernel memory that is mapped to the process.

MA_PS4K

Indicates that mapping is supported by 4 KB blocks of physical memory.

MA_PS64K

Indicates that mapping is supported by 64 KB blocks of physical memory.

MA_PS16M

Indicates that mapping is supported by 16 MB blocks of physical memory.

MA_PS16G

Indicates that mapping is supported by 16 GB blocks of physical memory.

MA_READ

Indicates that mapping is readable by the traced process.

MA_WRITE

Indicates that mapping is writable by the traced process.

MA_EXEC

Indicates that mapping is executable by the traced process.

MA_SHARED

Indicates that mapping changes are shared by the mapped object.

pr_shmid

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.

pr_dev

For the MA_FILEMAP mapping, contains the device ID number of the mapped file.

pr_ino

For MA_FILEMAP mapping, contains the inode number of the mapped file relative to the device ID in the pr_dev field.

pr_vsid

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.

cred

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[1];           /* array of supplementary groups */

sysent

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.

cwd

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.

fd

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

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), without the process first obtaining the specific path names of those files.

root

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.

mmap

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.

lwp

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:

lwpctl

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

lwpstatus

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:

pr_flags

Specifies a bit-mask holding these flags:

PR_STOPPED: Indicates that the thread is stopped
PR_ISTOP: Indicates that the thread is stopped on an event of interest (see the PCSTOP signal)
PR_DSTOP: Indicates that the thread has a stop directive in effect (see the PCSTOP signal)
PR_ASLEEP: Thread is in an interruptible sleep within a system call
PR_NOREGS: 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:

PR_REQUESTED: 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.
PR_SIGNALLED: 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).
PR_FAULTED: 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.
PR_SYSENTRY: Shows a stop on entry to a system call (see the PCSENTRY signal). The pr_what member contains the system call number.
PR_SYSEXIT: Shows a stop on exit from a system call (see the PCSEXIT signal). The pr_what contains the system call number.
PR_JOBCONTROL: 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.

pr_lwpid

Names the specific thread I/O

pr_cursig

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.

pr_action

Contains the signal action information about the current signal. This member is undefined if the pr_cursig member is zero. See the sigaction subroutine.

pr_lwppend

Identifies any synchronously generated or thread-directed signals pending for the thread. It does not include signals pending at the process level.

pr_altstack

Contains the alternate signal stack information for the thread. See the sigaltstack subroutine.

pr_syscall

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.

pr_clname

Contains the name of the scheduling class of the thread

pr_reg

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.

pr_fpreg

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.

pr_family

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.

lwpsinfo

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.

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

The following are allowed control messages:

Note: Writing a message to a control file for a process or thread that has already exited elicits the error ENOENT.

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.

PCRUN

Executes a thread again after it was stopped. The operand is a set of flags, contained in an int operand, describing optional additional actions.

The allowed flags for PCRUN are described below:

PRCSIG: Clears the current signal, if any. See PCSSIG.
PRCFAULT: Clears the current fault, if any. See PCCFAULT.
PRSTEP: 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.
PRSABORT: 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.
PRSTOP: 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.

PCSTRACE

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.

PCSSIG

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.

PCKILL

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.

PCUNKILL

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.

PCSHOLD

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.

PCSFAULT

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.

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

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.

PCCFAULT

Specifies the current fault, if any, to be cleared. The associated signal is not sent to the specified thread or representative thread.

PCSENTRY

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 the thread.

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.

PCSEXIT

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.

PCSREG

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.

PCSFPREG

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.

PCSVREG

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.

PCNICE

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.

Files

Item	Description
/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

Error Codes

Other errors can occur in addition to the errors normally associated with file system access:

Error Code	Description
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: PCSTOP, PCDSTOP or PCWSTOP was applied to a system process. An exclusive open subroutine was attempted on a process file already open for writing. PCRUN, PCSSIG, PCSREG or PCSFPREG was applied to a process or thread that was not stopped on an event of interest. An attempt was made to mount the /proc file system 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 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: 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. PCSVREG was applied on a machine without vector support or was applied to a thread that has not referenced the vector unit.
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.

Security

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.