1 PROC(4)                 File Formats and Configurations                PROC(4)
   3 NAME
   4      proc - /proc, the process file system
   7      /proc is a file system that provides access to the state of each process
   8      and light-weight process (lwp) in the system.  The name of each entry in
   9      the /proc directory is a decimal number corresponding to a process-ID.
  10      These entries are themselves subdirectories.  Access to process state is
  11      provided by additional files contained within each subdirectory; the
  12      hierarchy is described more completely below.  In this document, "/proc
  13      file" refers to a non-directory file within the hierarchy rooted at
  14      /proc.  The owner of each /proc file and subdirectory is determined by
  15      the user-ID of the process.
  17      /proc can be mounted on any mount point, in addition to the standard
  18      /proc mount point, and can be mounted several places at once.  Such
  19      additional mounts are allowed in order to facilitate the confinement of
  20      processes to subtrees of the file system via chroot(2) and yet allow such
  21      processes access to commands like ps(1).
  23      Standard system calls are used to access /proc files: open(2), close(2),
  24      read(2), and write(2) (including readv(2), writev(2), pread(2), and
  25      pwrite(2)).  Most files describe process state and can only be opened for
  26      reading.  ctl and lwpctl (control) files permit manipulation of process
  27      state and can only be opened for writing.  as (address space) files
  28      contain the image of the running process and can be opened for both
  29      reading and writing.  An open for writing allows process control; a read-
  30      only open allows inspection but not control.  In this document, we refer
  31      to the process as open for reading or writing if any of its associated
  32      /proc files is open for reading or writing.
  34      In general, more than one process can open the same /proc file at the
  35      same time. Exclusive open is an advisory mechanism provided to allow
  36      controlling processes to avoid collisions with each other.  A process can
  37      obtain exclusive control of a target process, with respect to other
  38      cooperating processes, if it successfully opens any /proc file in the
  39      target process for writing (the as or ctl files, or the lwpctl file of
  40      any lwp) while specifying O_EXCL in the open(2).  Such an open will fail
  41      if the target process is already open for writing (that is, if an as,
  42      ctl, or lwpctl file is already open for writing).  There can be any
  43      number of concurrent read-only opens; O_EXCL is ignored on opens for
  44      reading.  It is recommended that the first open for writing by a
  45      controlling process use the O_EXCL flag; multiple controlling processes
  46      usually result in chaos.
  48      If a process opens one of its own /proc files for writing, the open
  49      succeeds regardless of O_EXCL and regardless of whether some other
  50      process has the process open for writing.  Self-opens do not count when
  51      another process attempts an exclusive open.  (A process cannot exclude a
  52      debugger by opening itself for writing and the application of a debugger
  53      cannot prevent a process from opening itself.)  All self-opens for
  54      writing are forced to be close-on-exec (see the F_SETFD operation of
  55      fcntl(2)).
  57      Data may be transferred from or to any locations in the address space of
  58      the traced process by applying lseek(2) to position the as file at the
  59      virtual address of interest followed by read(2) or write(2) (or by using
  60      pread(2) or pwrite(2) for the combined operation).  The address-map files
  61      /proc/pid/map and /proc/pid/xmap can be read to determine the accessible
  62      areas (mappings) of the address space.  I/O transfers may span contiguous
  63      mappings.  An I/O request extending into an unmapped area is truncated at
  64      the boundary.  A write request beginning at an unmapped virtual address
  65      fails with EIO; a read request beginning at an unmapped virtual address
  66      returns zero (an end-of-file indication).
  68      Information and control operations are provided through additional files.
  69      <procfs.h>   contains definitions of data structures and message formats
  70      used with these files.  Some of these definitions involve the use of sets
  71      of flags.  The set types sigset_t, fltset_t, and sysset_t correspond,
  72      respectively, to signal, fault, and system call enumerations defined in
  73      <sys/signal.h>, <sys/fault.h>, and     <sys/syscall.h>.  Each set type   is
  74      large enough to hold flags for its own enumeration.  Although they are of
  75      different sizes, they have a common structure and can be manipulated by
  76      these macros:
  78            prfillset(&set);         /* turn on all flags in set */
  79            premptyset(&set);                /* turn off all flags in set */
  80            praddset(&set, flag);    /* turn on the specified flag */
  81            prdelset(&set, flag);    /* turn off the specified flag */
  82            r = prismember(&set,     flag);  /* != 0 iff flag is turned on */
  84      One of prfillset() or premptyset() must be used to initialize set before
  85      it is used in any other operation.  flag must be a member of the
  86      enumeration corresponding to set.
  88      Every process contains at least one light-weight process, or lwp.  Each
  89      lwp represents a flow of execution that is independently scheduled by the
  90      operating system.  All lwps in a process share its address space as well
  91      as many other attributes.  Through the use of lwpctl and ctl files as
  92      described below, it is possible to affect individual lwps in a process or
  93      to affect all of them at once, depending on the operation.
  95      When the process has more than one lwp, a representative lwp is chosen by
  96      the system for certain process status files and control operations.  The
  97      representative lwp is a stopped lwp only if all of the process's lwps are
  98      stopped; is stopped on an event of interest only if all of the lwps are
  99      so stopped (excluding PR_SUSPENDED lwps); is in a PR_REQUESTED stop only
 100      if there are no other events of interest to be found; or, failing
 101      everything else, is in a PR_SUSPENDED stop (implying that the process is
 102      deadlocked).  See the description of the status file for definitions of
 103      stopped states.  See the PCSTOP control operation for the definition of
 104      "event of interest".
 106      The representative lwp remains fixed (it will be chosen again on the next
 107      operation) as long as all of the lwps are stopped on events of interest
 108      or are in a PR_SUSPENDED stop and the PCRUN control operation is not
 109      applied to any of them.
 111      When applied to the process control file, every /proc control operation
 112      that must act on an lwp uses the same algorithm to choose which lwp to
 113      act upon.  Together with synchronous stopping (see PCSET), this enables a
 114      debugger to control a multiple-lwp process using only the process-level
 115      status and control files if it so chooses.  More fine-grained control can
 116      be achieved using the lwp-specific files.
 118      The system supports two process data models, the traditional 32-bit data
 119      model in which ints, longs and pointers are all 32 bits wide (the ILP32
 120      data model), and on some platforms the 64-bit data model in which longs
 121      and pointers, but not ints, are 64 bits in width (the LP64 data model).
 122      In the LP64 data model some system data types, notably size_t, off_t,
 123      time_t and dev_t, grow from 32 bits to 64 bits as well.
 125      The /proc interfaces described here are available to both 32-bit and
 126      64-bit controlling processes.  However, many operations attempted by a
 127      32-bit controlling process on a 64-bit target process will fail with
 128      EOVERFLOW because the address space range of a 32-bit process cannot
 129      encompass a 64-bit process or because the data in some 64-bit system data
 130      type cannot be compressed to fit into the corresponding 32-bit type
 131      without loss of information.  Operations that fail in this circumstance
 132      include reading and writing the address space, reading the address-map
 133      files, and setting the target process's registers.  There is no
 134      restriction on operations applied by a 64-bit process to either a 32-bit
 135      or a 64-bit target processes.
 137      The format of the contents of any /proc file depends on the data model of
 138      the observer (the controlling process), not on the data model of the
 139      target process.  A 64-bit debugger does not have to translate the
 140      information it reads from a /proc file for a 32-bit process from 32-bit
 141      format to 64-bit format.  However, it usually has to be aware of the data
 142      model of the target process.  The pr_dmodel field of the status files
 143      indicates the target process's data model.
 145      To help deal with system data structures that are read from 32-bit
 146      processes, a 64-bit controlling program can be compiled with the C
 147      preprocessor symbol _SYSCALL32 defined before system header files are
 148      included.  This makes explicit 32-bit fixed-width data structures (like
 149      struct stat32) visible to the 64-bit program.  See types32.h(3HEAD).
 152      At the top level, the directory /proc contains entries each of which
 153      names an existing process in the system.  These entries are themselves
 154      directories.  Except where otherwise noted, the files described below can
 155      be opened for reading only.  In addition, if a process becomes a zombie
 156      (one that has exited but whose parent has not yet performed a wait(3C)
 157      upon it), most of its associated /proc files disappear from the
 158      hierarchy; subsequent attempts to open them, or to read or write files
 159      opened before the process exited, will elicit the error ENOENT.
 161      Although process state and consequently the contents of /proc files can
 162      change from instant to instant, a single read(2) of a /proc file is
 163      guaranteed to return a sane representation of state; that is, the read
 164      will be atomic with respect to the state of the process.  No such
 165      guarantee applies to successive reads applied to a /proc file for a
 166      running process.  In addition, atomicity is not guaranteed for I/O
 167      applied to the as (address-space) file for a running process or for a
 168      process whose address space contains memory shared by another running
 169      process.
 171      A number of structure definitions are used to describe the files.  These
 172      structures may grow by the addition of elements at the end in future
 173      releases of the system and it is not legitimate for a program to assume
 174      that they will not.
 176 STRUCTURE OF /proc/pid
 177      A given directory /proc/pid contains the following entries.  A process
 178      can use the invisible alias /proc/self if it wishes to open one of its
 179      own /proc files (invisible in the sense that the name "self" does not
 180      appear in a directory listing of /proc obtained from ls(1), getdents(2),
 181      or readdir(3C)).
 183    contracts
 184      A directory containing references to the contracts held by the process.
 185      Each entry is a symlink to the contract's directory under
 186      /system/contract.  See contract(4).
 188    as
 189      Contains the address-space image of the process; it can be opened for
 190      both reading and writing.  lseek(2) is used to position the file at the
 191      virtual address of interest and then the address space can be examined or
 192      changed through read(2) or write(2) (or by using pread(2) or pwrite(2)
 193      for the combined operation).
 195    ctl
 196      A write-only file to which structured messages are written directing the
 197      system to change some aspect of the process's state or control its
 198      behavior in some way.  The seek offset is not relevant when writing to
 199      this file.  Individual lwps also have associated lwpctl files in the lwp
 200      subdirectories.  A control message may be written either to the process's
 201      ctl file or to a specific lwpctl file with operation-specific effects.
 202      The effect of a control message is immediately reflected in the state of
 203      the process visible through appropriate status and information files.
 204      The types of control messages are described in detail later.  See CONTROL
 205      MESSAGES.
 207    status
 208      Contains state information about the process and the representative lwp.
 209      The file contains a pstatus structure which contains an embedded
 210      lwpstatus structure for the representative lwp, as follows:
 212       typedef struct pstatus {
 213            int pr_flags;            /* flags (see below) */
 214            int pr_nlwp;             /* number of active lwps in the process */
 215            int pr_nzomb;            /* number of zombie lwps in the process */
 216            pid_tpr_pid;             /* process id */
 217            pid_tpr_ppid;            /* parent process id */
 218            pid_tpr_pgid;            /* process group id */
 219            pid_tpr_sid;             /* session id */
 220            id_t pr_aslwpid;         /* obsolete */
 221            id_t pr_agentid;         /* lwp-id of the agent lwp, if any */
 222            sigset_t pr_sigpend;     /* set of process pending signals */
 223            uintptr_t pr_brkbase;    /* virtual address of the process heap */
 224            size_t pr_brksize;       /* size of the process heap, in bytes */
 225            uintptr_t pr_stkbase;    /* virtual address of the process stack */
 226            size_tpr_stksize;        /* size of the process stack, in bytes */
 227            timestruc_t pr_utime;    /* process user cpu time */
 228            timestruc_t pr_stime;    /* process system cpu time */
 229            timestruc_t pr_cutime;   /* sum of children's user times */
 230            timestruc_t pr_cstime;   /* sum of children's system times */
 231            sigset_t pr_sigtrace;    /* set of traced signals */
 232            fltset_t pr_flttrace;    /* set of traced faults */
 233            sysset_t pr_sysentry;    /* set of system calls traced on entry */
 234            sysset_t pr_sysexit;     /* set of system calls traced on exit */
 235            char pr_dmodel;          /* data model of the process */
 236            taskid_t pr_taskid;      /* task id */
 237            projid_t pr_projid;      /* project id */
 238            zoneid_t pr_zoneid;      /* zone id */
 239            lwpstatus_t pr_lwp;      /* status of the representative lwp */
 240       } pstatus_t;
 242      pr_flags is a bit-mask holding the following process flags.  For
 243      convenience, it also contains the lwp flags for the representative lwp,
 244      described later.
 246            PR_ISSYS   process is a system process (see PCSTOP).
 248            PR_VFORKP  process is the parent of a vforked child (see PCWATCH).
 250            PR_FORK    process has its inherit-on-fork mode set (see PCSET).
 252            PR_RLC     process has its run-on-last-close mode set (see PCSET).
 254            PR_KLC     process has its kill-on-last-close mode set (see PCSET).
 256            PR_ASYNC   process has its asynchronous-stop mode set (see PCSET).
 258            PR_MSACCT  Set by default in all processes to indicate that
 259                       microstate accounting is enabled.  However, this flag
 260                       has been deprecated and no longer has any effect.
 261                       Microstate accounting may not be disabled; however, it
 262                       is still possible to toggle the flag.
 264            PR_MSFORK  Set by default in all processes to indicate that
 265                       microstate accounting will be enabled for processes that
 266                       this parent fork(2)s.  However, this flag has been
 267                       deprecated and no longer has any effect.  It is possible
 268                       to toggle this flag; however, it is not possible to
 269                       disable microstate accounting.
 271            PR_BPTADJ  process has its breakpoint adjustment mode set (see
 272                       PCSET).
 274            PR_PTRACE  process has its ptrace-compatibility mode set (see
 275                       PCSET).
 277      pr_nlwp is the total number of active lwps in the process.  pr_nzomb is
 278      the total number of zombie lwps in the process.  A zombie lwp is a non-
 279      detached lwp that has terminated but has not been reaped with
 280      thr_join(3C) or pthread_join(3C).
 282      pr_pid, pr_ppi, pr_pgid, and pr_sid are, respectively, the process ID,
 283      the ID of the process's parent, the process's process group ID, and the
 284      process's session ID.
 286      pr_aslwpid is obsolete and is always zero.
 288      pr_agentid is the lwp-ID for the /proc agent lwp (see the PCAGENT control
 289      operation).  It is zero if there is no agent lwp in the process.
 291      pr_sigpend identifies asynchronous signals pending for the process.
 293      pr_brkbase is the virtual address of the process heap and pr_brksize is
 294      its size in bytes.  The address formed by the sum of these values is the
 295      process break (see brk(2)).  pr_stkbase and pr_stksize are, respectively,
 296      the virtual address of the process stack and its size in bytes.  (Each
 297      lwp runs on a separate stack; the distinguishing characteristic of the
 298      process stack is that the operating system will grow it when necessary.)
 300      pr_utime, pr_stime, pr_cutime, and pr_cstime are, respectively, the user
 301      CPU and system CPU time consumed by the process, and the cumulative user
 302      CPU and system CPU time consumed by the process's children, in seconds
 303      and nanoseconds.
 305      pr_sigtrace and pr_flttrace contain, respectively, the set of signals and
 306      the set of hardware faults that are being traced (see PCSTRACE and
 307      PCSFAULT).
 309      pr_sysentry and pr_sysexit contain, respectively, the sets of system
 310      calls being traced on entry and exit (see PCSENTRY and PCSEXIT).
 312      pr_dmodel indicates the data model of the process.  Possible values are:
 314            PR_MODEL_ILP32   process data model is ILP32.
 316            PR_MODEL_LP64    process data model is LP64.
 318            PR_MODEL_NATIVE  process data model is native.
 320      The pr_taskid, pr_projid, and pr_zoneid fields contain respectively, the
 321      numeric IDs of the task, project, and zone in which the process was
 322      running.
 324      The constant PR_MODEL_NATIVE reflects the data model of the controlling
 325      process, that is, its value is PR_MODEL_ILP32 or PR_MODEL_LP64 according
 326      to whether the controlling process has been compiled as a 32-bit program
 327      or a 64-bit program, respectively.
 329      pr_lwp contains the status information for the representative lwp:
 331       typedef struct lwpstatus {
 332         int pr_flags;              /* flags (see below) */
 333         id_t pr_lwpid;             /* specific lwp identifier */
 334         short pr_why;              /* reason for lwp stop, if stopped */
 335         short pr_what;             /* more detailed reason */
 336         short pr_cursig;           /* current signal, if any */
 337         siginfo_t pr_info;         /* info associated with signal or fault */
 338         sigset_t pr_lwppend;       /* set of signals pending to the lwp */
 339         sigset_t pr_lwphold;       /* set of signals blocked by the lwp */
 340         struct sigaction pr_action;/* signal action for current signal */
 341         stack_t pr_altstack;       /* alternate signal stack info */
 342         uintptr_t pr_oldcontext;   /* address of previous ucontext */
 343         short pr_syscall;          /* system call number (if in syscall) */
 344         short pr_nsysarg;          /* number of arguments to this syscall */
 345         int pr_errno;              /* errno for failed syscall */
 346         long pr_sysarg[PRSYSARGS]; /* arguments to this syscall */
 347         long pr_rval1;             /* primary syscall return value */
 348         long pr_rval2;             /* second syscall return value, if any */
 349         char pr_clname[PRCLSZ];    /* scheduling class name */
 350         timestruc_t pr_tstamp;     /* real-time time stamp of stop */
 351         timestruc_t pr_utime;      /* lwp user cpu time */
 352         timestruc_t pr_stime;      /* lwp system cpu time */
 353         uintptr_t pr_ustack;       /* stack boundary data (stack_t) address */
 354         ulong_t pr_instr;          /* current instruction */
 355         prgregset_t pr_reg;        /* general registers */
 356         prfpregset_t pr_fpreg;     /* floating-point registers */
 357       } lwpstatus_t;
 359      pr_flags is a bit-mask holding the following lwp flags.  For convenience,
 360      it also contains the process flags, described previously.
 362            PR_STOPPED  The lwp is stopped.
 364            PR_ISTOP    The lwp is stopped on an event of interest (see
 365                        PCSTOP).
 367            PR_DSTOP    The lwp has a stop directive in effect (see PCSTOP).
 369            PR_STEP     The lwp has a single-step directive in effect (see
 370                        PCRUN).
 372            PR_ASLEEP   The lwp is in an interruptible sleep within a system
 373                        call.
 375            PR_PCINVAL  The lwp's current instruction (pr_instr) is undefined.
 377            PR_DETACH   This is a detached lwp (see pthread_create(3C) and
 378                        pthread_join(3C)).
 380            PR_DAEMON   This is a daemon lwp (see pthread_create(3C)).
 382            PR_ASLWP    This flag is obsolete and is never set.
 384            PR_AGENT    This is the /proc agent lwp for the process.
 386      pr_lwpid names the specific lwp.
 388      pr_why and pr_what together describe, for a stopped lwp, the reason for
 389      the stop.  Possible values of pr_why and the associated pr_what are:
 391          PR_REQUESTED   indicates that the stop occurred in response to a stop
 392                         directive, normally because PCSTOP was applied or
 393                         because another lwp stopped on an event of interest
 394                         and the asynchronous-stop flag (see PCSET) was not set
 395                         for the process.  pr_what is unused in this case.
 397          PR_SIGNALLED   indicates that the lwp stopped on receipt of a signal
 398                         (see PCSTRACE); pr_what holds the signal number that
 399                         caused the stop (for a newly-stopped lwp, the same
 400                         value is in pr_cursig).
 402          PR_FAULTED     indicates that the lwp stopped on incurring a hardware
 403                         fault (see PCSFAULT); pr_what holds the fault number
 404                         that caused the stop.
 406          PR_SYSENTRY
 408          PR_SYSEXIT     indicate a stop on entry to or exit from a system call
 409                         (see PCSENTRY and PCSEXIT); pr_what holds the system
 410                         call number.
 412          PR_JOBCONTROL  indicates that the lwp stopped due to the default
 413                         action of a job control stop signal (see
 414                         sigaction(2)); pr_what holds the stopping signal
 415                         number.
 417          PR_SUSPENDED   indicates that the lwp stopped due to internal
 418                         synchronization of lwps within the process.  pr_what
 419                         is unused in this case.
 421      pr_cursig names the current signal, that is, the next signal to be
 422      delivered to the lwp, if any.  pr_info, when the lwp is in a PR_SIGNALLED
 423      or PR_FAULTED stop, contains additional information pertinent to the
 424      particular signal or fault (see <sys/siginfo.h>).
 426      pr_lwppend identifies any synchronous or directed signals pending for the
 427      lwp.  pr_lwphold identifies those signals whose delivery is being blocked
 428      by the lwp (the signal mask).
 430      pr_action contains the signal action information pertaining to the
 431      current signal (see sigaction(2)); it is undefined if pr_cursig is zero.
 432      pr_altstack contains the alternate signal stack information for the lwp
 433      (see sigaltstack(2)).
 435      pr_oldcontext, if not zero, contains the address on the lwp stack of a
 436      ucontext structure describing the previous user-level context (see
 437      ucontext.h(3HEAD)).  It is non-zero only if the lwp is executing in the
 438      context of a signal handler.
 440      pr_syscall is the number of the system call, if any, being executed by
 441      the lwp; it is non-zero if and only if the lwp is stopped on PR_SYSENTRY
 442      or PR_SYSEXIT, or is asleep within a system call (PR_ASLEEP is set).  If
 443      pr_syscall is non-zero, pr_nsysarg is the number of arguments to the
 444      system call and pr_sysarg contains the actual arguments.
 446      pr_rval1, pr_rval2, and pr_errno are defined only if the lwp is stopped
 447      on PR_SYSEXIT or if the PR_VFORKP flag is set.  If pr_errno is zero,
 448      pr_rval1 and pr_rval2 contain the return values from the system call.
 449      Otherwise, pr_errno contains the error number for the failing system call
 450      (see <sys/errno.h>).
 452      pr_clname contains the name of the lwp's scheduling class.
 454      pr_tstamp, if the lwp is stopped, contains a time stamp marking when the
 455      lwp stopped, in real time seconds and nanoseconds since an arbitrary time
 456      in the past.
 458      pr_utime is the amount of user level CPU time used by this LWP.
 460      pr_stime is the amount of system level CPU time used by this LWP.
 462      pr_ustack is the virtual address of the stack_t that contains the stack
 463      boundaries for this LWP.  See getustack(2) and _stack_grow(3C).
 465      pr_instr contains the machine instruction to which the lwp's program
 466      counter refers.  The amount of data retrieved from the process is
 467      machine-dependent.  On SPARC based machines, it is a 32-bit word.  On
 468      x86-based machines, it is a single byte.  In general, the size is that of
 469      the machine's smallest instruction.  If PR_PCINVAL is set, pr_instr is
 470      undefined; this occurs whenever the lwp is not stopped or when the
 471      program counter refers to an invalid virtual address.
 473      pr_reg is an array holding the contents of a stopped lwp's general
 474      registers.
 476          SPARC              On SPARC-based machines, the predefined constants
 477                             R_G0 ...  R_G7, R_O0 ...  R_O7, R_L0 ...  R_L7,
 478                             R_I0 ...  R_I7, R_PC, R_nPC, and R_Y can be used
 479                             as indices to refer to the corresponding
 480                             registers; previous register windows can be read
 481                             from their overflow locations on the stack
 482                             (however, see the gwindows file in the
 483                             /proc/pid/lwp/lwpid subdirectory).
 485          SPARC V8 (32-bit)  For SPARC V8 (32-bit) controlling processes, the
 486                             predefined constants R_PSR, R_WIM, and R_TBR can
 487                             be used as indices to refer to the corresponding
 488                             special registers.  For SPARC V9 (64-bit)
 489                             controlling processes, the predefined constants
 490                             R_CCR, R_ASI, and R_FPRS can be used as indices to
 491                             refer to the corresponding special registers.
 493          x86 (32-bit)       For 32-bit x86 processes, the predefined constants
 494                             listed belowcan be used as indices to refer to the
 495                             corresponding registers.
 496                                   SS
 497                                   UESP
 498                                   EFL
 499                                   CS
 500                                   EIP
 501                                   ERR
 502                                   TRAPNO
 503                                   EAX
 504                                   ECX
 505                                   EDX
 506                                   EBX
 507                                   ESP
 508                                   EBP
 509                                   ESI
 510                                   EDI
 511                                   DS
 512                                   ES
 513                                   GS
 515                             The preceding constants are listed in
 516                             <sys/regset.h>.
 518                             Note that a 32-bit process can run on an x86
 519                             64-bit system, using the constants listed above.
 521          x86 (64-bit)       To read the registers of a 32- or a 64-bit
 522                             process, a 64-bit x86 process should use the
 523                             predefined constants listed below.
 524                                   REG_GSBASE
 525                                   REG_FSBASE
 526                                   REG_DS
 527                                   REG_ES
 528                                   REG_GS
 529                                   REG_FS
 530                                   REG_SS
 531                                   REG_RSP
 532                                   REG_RFL
 533                                   REG_CS
 534                                   REG_RIP
 535                                   REG_ERR
 536                                   REG_TRAPNO
 537                                   REG_RAX
 538                                   REG_RCX
 539                                   REG_RDX
 540                                   REG_RBX
 541                                   REG_RBP
 542                                   REG_RSI
 543                                   REG_RDI
 544                                   REG_R8
 545                                   REG_R9
 546                                   REG_R10
 547                                   REG_R11
 548                                   REG_R12
 549                                   REG_R13
 550                                   REG_R14
 551                                   REG_R15
 553                             The preceding constants are listed in
 554                             <sys/regset.h>.
 556      pr_fpreg is a structure holding the contents of the floating-point
 557      registers.
 559      SPARC registers, both general and floating-point, as seen by a 64-bit
 560      controlling process are the V9 versions of the registers, even if the
 561      target process is a 32-bit (V8) process.  V8 registers are a subset of
 562      the V9 registers.
 564      If the lwp is not stopped, all register values are undefined.
 566    psinfo
 567      Contains miscellaneous information about the process and the
 568      representative lwp needed by the ps(1) command.  psinfo remains
 569      accessible after a process becomes a zombie.  The file contains a psinfo
 570      structure which contains an embedded lwpsinfo structure for the
 571      representative lwp, as follows:
 573       typedef struct psinfo {
 574           int pr_flag;             /* process flags (DEPRECATED: see below) */
 575           int pr_nlwp;             /* number of active lwps in the process */
 576           int pr_nzomb;            /* number of zombie lwps in the process */
 577           pid_t pr_pid;            /* process id */
 578           pid_t pr_ppid;           /* process id of parent */
 579           pid_t pr_pgid;           /* process id of process group leader */
 580           pid_t pr_sid;            /* session id */
 581           uid_t pr_uid;            /* real user id */
 582           uid_t pr_euid;           /* effective user id */
 583           gid_t pr_gid;            /* real group id */
 584           gid_t pr_egid;           /* effective group id */
 585           uintptr_t pr_addr;       /* address of process */
 586           size_t pr_size;          /* size of process image in Kbytes */
 587           size_t pr_rssize;        /* resident set size in Kbytes */
 588           dev_t pr_ttydev;         /* controlling tty device (or PRNODEV) */
 589           ushort_t pr_pctcpu;      /* % of recent cpu time used by all lwps */
 590           ushort_t pr_pctmem;      /* % of system memory used by process */
 591           timestruc_t pr_start;    /* process start time, from the epoch */
 592           timestruc_t pr_time;     /* cpu time for this process */
 593           timestruc_t pr_ctime;    /* cpu time for reaped children */
 594           char pr_fname[PRFNSZ];   /* name of exec'ed file */
 595           char pr_psargs[PRARGSZ]; /* initial characters of arg list */
 596           int pr_wstat;            /* if zombie, the wait() status */
 597           int pr_argc;             /* initial argument count */
 598           uintptr_t pr_argv;       /* address of initial argument vector */
 599           uintptr_t pr_envp;       /* address of initial environment vector */
 600           char pr_dmodel;          /* data model of the process */
 601           taskid_t pr_taskid;      /* task id */
 602           projid_t pr_projid;      /* project id */
 603           poolid_t pr_poolid;      /* pool id */
 604           zoneid_t pr_zoneid;      /* zone id */
 605           ctid_t pr_contract;      /* process contract id */
 606           lwpsinfo_t pr_lwp;       /* information for representative lwp */
 607       } psinfo_t;
 609      Some of the entries in psinfo, such as pr_addr, refer to internal kernel
 610      data structures and should not be expected to retain their meanings
 611      across different versions of the operating system.
 613      psinfo_t.pr_flag is a deprecated interface that should no longer be used.
 614      Applications currently relying on the SSYS bit in pr_flag should migrate
 615      to checking PR_ISSYS in the pstatus structure's pr_flags field.
 617      pr_pctcpu and pr_pctmem are 16-bit binary fractions in the range 0.0 to
 618      1.0 with the binary point to the right of the high-order bit (1.0 ==
 619      0x8000).  pr_pctcpu is the summation over all lwps in the process.
 621      pr_lwp contains the ps(1) information for the representative lwp.  If the
 622      process is a zombie, pr_nlwp, pr_nzomb, and pr_lwp.pr_lwpid are zero and
 623      the other fields of pr_lwp are undefined:
 625       typedef struct lwpsinfo {
 626           int pr_flag;             /* lwp flags (DEPRECATED: see below) */
 627           id_t pr_lwpid;           /* lwp id */
 628           uintptr_t pr_addr;       /* internal address of lwp */
 629           uintptr_t pr_wchan;      /* wait addr for sleeping lwp */
 630           char pr_stype;           /* synchronization event type */
 631           char pr_state;           /* numeric lwp state */
 632           char pr_sname;           /* printable character for pr_state */
 633           char pr_nice;            /* nice for cpu usage */
 634           short pr_syscall;        /* system call number (if in syscall) */
 635           char pr_oldpri;          /* pre-SVR4, low value is high priority */
 636           char pr_cpu;             /* pre-SVR4, cpu usage for scheduling */
 637           int pr_pri;              /* priority, high value = high priority */
 638           ushort_t pr_pctcpu;      /* % of recent cpu time used by this lwp */
 639           timestruc_t pr_start;    /* lwp start time, from the epoch */
 640           timestruc_t pr_time;     /* cpu time for this lwp */
 641           char pr_clname[PRCLSZ];  /* scheduling class name */
 642           char pr_name[PRFNSZ];    /* name of system lwp */
 643           processorid_t pr_onpro;  /* processor which last ran this lwp */
 644           processorid_t pr_bindpro;/* processor to which lwp is bound */
 645           psetid_t pr_bindpset;    /* processor set to which lwp is bound */
 646           lgrp_id_t pr_lgrp;       /* home lgroup */
 647       } lwpsinfo_t;
 649      Some of the entries in lwpsinfo, such as pr_addr, pr_wchan, pr_stype,
 650      pr_state, and pr_name, refer to internal kernel data structures and
 651      should not be expected to retain their meanings across different versions
 652      of the operating system.
 654      lwpsinfo_t.pr_flag is a deprecated interface that should no longer be
 655      used.
 657      pr_pctcpu is a 16-bit binary fraction, as described above.  It represents
 658      the CPU time used by the specific lwp.  On a multi-processor machine, the
 659      maximum value is 1/N, where N is the number of CPUs.
 661      pr_contract is the id of the process contract of which the process is a
 662      member.  See contract(4) and process(4).
 664    cred
 665      Contains a description of the credentials associated with the process:
 667       typedef struct prcred {
 668               uid_t pr_euid;      /* effective user id */
 669               uid_t pr_ruid;      /* real user id */
 670               uid_t pr_suid;      /* saved user id (from exec) */
 671               gid_t pr_egid;      /* effective group id */
 672               gid_t pr_rgid;      /* real group id */
 673               gid_t pr_sgid;      /* saved group id (from exec) */
 674               int pr_ngroups;     /* number of supplementary groups */
 675               gid_t pr_groups[1]; /* array of supplementary groups */
 676       } prcred_t;
 678      The array of associated supplementary groups in pr_groups
 679       is of variable length; the cred file contains all of the supplementary
 680      groups.  pr_ngroups indicates the number of supplementary groups. (See
 681      also the PCSCRED and PCSCREDX control operations.)
 683    priv
 684      Contains a description of the privileges associated with the process:
 686       typedef struct prpriv {
 687            uint32_t        pr_nsets;      /* number of privilege set */
 688            uint32_t        pr_setsize;    /* size of privilege set */
 689            uint32_t        pr_infosize;   /* size of supplementary data */
 690            priv_chunk_t    pr_sets[1];    /* array of sets */
 691       } prpriv_t;
 693      The actual dimension of the pr_sets[] field is
 694            pr_sets[pr_nsets][pr_setsize]
 696      which is followed by additional information about the process state
 697      pr_infosize bytes in size.
 699      The full size of the structure can be computed using
 700      PRIV_PRPRIV_SIZE(prpriv_t *).
 702    secflags
 703      This file contains the security-flags of the process.  It contains a
 704      description of the security flags associated with the process.
 706       typedef struct prsecflags {
 707               uint32_t pr_version;            /* ABI Versioning of this structure */
 708               secflagset_t pr_effective;      /* Effective flags */
 709               secflagset_t pr_inherit;        /* Inheritable flags */
 710               secflagset_t pr_lower;          /* Lower flags */
 711               secflagset_t pr_upper;          /* Upper flags */
 712       } prsecflags_t;
 714      The pr_version field is a version number for the structure, currently
 717    sigact
 718      Contains an array of sigaction structures describing the current
 719      dispositions of all signals associated with the traced process (see
 720      sigaction(2)).  Signal numbers are displaced by 1 from array indices, so
 721      that the action for signal number n appears in position n-1 of the array.
 723    auxv
 724      Contains the initial values of the process's aux vector in an array of
 725      auxv_t structures (see <sys/auxv.h>).  The   values are those that were
 726      passed by the operating system as startup information to the dynamic
 727      linker.
 729    ldt
 730      This file exists only on x86-based machines.  It is non-empty only if the
 731      process has established a local descriptor table (LDT).  If non-empty,
 732      the file contains the array of currently active LDT entries in an array
 733      of elements of type struct ssd, defined in <sys/sysi86.h>,   one element
 734      for each active LDT entry.
 736    map, xmap
 737      Contain information about the virtual address map of the process.  The
 738      map file contains an array of prmap structures while the xmap file
 739      contains an array of prxmap structures.  Each structure describes a
 740      contiguous virtual address region in the address space of the traced
 741      process:
 743       typedef struct prmap {
 744               uintptr_tpr_vaddr;         /* virtual address of mapping */
 745               size_t pr_size;            /* size of mapping in bytes */
 746               char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
 747               offset_t pr_offset;        /* offset into mapped object, if any */
 748               int pr_mflags;             /* protection and attribute flags */
 749               int pr_pagesize;           /* pagesize for this mapping in bytes */
 750               int pr_shmid;              /* SysV shared memory identifier */
 751       } prmap_t;
 753       typedef struct prxmap {
 754               uintptr_t pr_vaddr;        /* virtual address of mapping */
 755               size_t pr_size;            /* size of mapping in bytes */
 756               char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
 757               offset_t pr_offset;        /* offset into mapped object, if any */
 758               int pr_mflags;             /* protection and attribute flags */
 759               int pr_pagesize;           /* pagesize for this mapping in bytes */
 760               int pr_shmid;              /* SysV shared memory identifier */
 761               dev_t pr_dev;              /* device of mapped object, if any */
 762               uint64_t pr_ino;           /* inode of mapped object, if any */
 763               size_t pr_rss;             /* pages of resident memory */
 764               size_t pr_anon;            /* pages of resident anonymous memory */
 765               size_t pr_locked;          /* pages of locked memory */
 766               uint64_t pr_hatpagesize;   /* pagesize of mapping */
 767       } prxmap_t;
 769      pr_vaddr is the virtual address of the mapping within the traced process
 770      and pr_size is its size in bytes.  pr_mapname, if it does not contain a
 771      null string, contains the name of a file in the object directory (see
 772      below) that can be opened read-only to obtain a file descriptor for the
 773      mapped file associated with the mapping.  This enables a debugger to find
 774      object file symbol tables without having to know the real path names of
 775      the executable file and shared libraries of the process.  pr_offset is
 776      the 64-bit offset within the mapped file (if any) to which the virtual
 777      address is mapped.
 779      pr_mflags is a bit-mask of protection and attribute flags:
 781          MA_READ       mapping is readable by the traced process.
 783          MA_WRITE      mapping is writable by the traced process.
 785          MA_EXEC       mapping is executable by the traced process.
 787          MA_SHARED     mapping changes are shared by the mapped object.
 789          MA_ISM        mapping is intimate shared memory (shared MMU
 790                        resources)
 792          MAP_NORESERVE
 793                        mapping does not have swap space reserved (mapped with
 794                        MAP_NORESERVE)
 796          MA_SHM        mapping System V shared memory
 798      A contiguous area of the address space having the same underlying mapped
 799      object may appear as multiple mappings due to varying read, write, and
 800      execute attributes.  The underlying mapped object does not change over
 801      the range of a single mapping.  An I/O operation to a mapping marked
 802      MA_SHARED fails if applied at a virtual address not corresponding to a
 803      valid page in the underlying mapped object.  A write to a MA_SHARED
 804      mapping that is not marked MA_WRITE fails.  Reads and writes to private
 805      mappings always succeed.  Reads and writes to unmapped addresses fail.
 807      pr_pagesize is the page size for the mapping, currently always the system
 808      pagesize.
 810      pr_shmid is the shared memory identifier, if any, for the mapping.  Its
 811      value is -1 if the mapping is not System V shared memory.  See shmget(2).
 813      pr_dev is the device of the mapped object, if any, for the mapping.  Its
 814      value is PRNODEV (-1) if the mapping does not have a device.
 816      pr_ino is the inode of the mapped object, if any, for the mapping.  Its
 817      contents are only valid if pr_dev is not PRNODEV.
 819      pr_rss is the number of resident pages of memory for the mapping.  The
 820      number of resident bytes for the mapping may be determined by multiplying
 821      pr_rss by the page size given by pr_pagesize.
 823      pr_anon is the number of resident anonymous memory pages (pages which are
 824      private to this process) for the mapping.
 826      pr_locked is the number of locked pages for the mapping.  Pages which are
 827      locked are always resident in memory.
 829      pr_hatpagesize is the size, in bytes, of the HAT (MMU) translation for
 830      the mapping.  pr_hatpagesize may be different than pr_pagesize.  The
 831      possible values are hardware architecture specific, and may change over a
 832      mapping's lifetime.
 834    rmap
 835      Contains information about the reserved address ranges of the process.
 836      The file contains an array of prmap structures, as defined above for the
 837      map file.  Each structure describes a contiguous virtual address region
 838      in the address space of the traced process that is reserved by the system
 839      in the sense that an mmap(2) system call that does not specify MAP_FIXED
 840      will not use any part of it for the new mapping.  Examples of such
 841      reservations include the address ranges reserved for the process stack
 842      and the individual thread stacks of a multi-threaded process.
 844    cwd
 845      A symbolic link to the process's current working directory.  See
 846      chdir(2).  A readlink(2) of /proc/pid/cwd yields a null string.  However,
 847      it can be opened, listed, and searched as a directory, and can be the
 848      target of chdir(2).
 850    root
 851      A symbolic link to the process's root directory.  /proc/pid/root can
 852      differ from the system root directory if the process or one of its
 853      ancestors executed chroot(2) as super user.  It has the same semantics as
 854      /proc/pid/cwd.
 856    fd
 857      A directory containing references to the open files of the process.  Each
 858      entry is a decimal number corresponding to an open file descriptor in the
 859      process.
 861      If an entry refers to a regular file, it can be opened with normal file
 862      system semantics but, to ensure that the controlling process cannot gain
 863      greater access than the controlled process, with no file access modes
 864      other than its read/write open modes in the controlled process.  If an
 865      entry refers to a directory, it can be accessed with the same semantics
 866      as /proc/pid/cwd.  An attempt to open any other type of entry fails with
 867      EACCES.
 869    fdinfo
 870      A directory containing information about each of the process's open
 871      files.  Each entry is a decimal number corresponding to an open file
 872      descriptor in the process.  Each file contains a prfdinfo_t structure
 873      defined as follows:
 875       typedef struct prfdinfo {
 876           int     pr_fd;          /* file descriptor number */
 877           mode_t  pr_mode;        /* (see st_mode in stat(2)) */
 878           uint64_t pr_ino;        /* inode number */
 879           uint64_t pr_size;       /* file size */
 880           int64_t pr_offset;      /* current offset of file descriptor */
 881           uid_t   pr_uid;         /* owner's user id */
 882           gid_t   pr_gid;         /* owner's group id */
 883           major_t pr_major;       /* major number of device containing file */
 884           minor_t pr_minor;       /* minor number of device containing file */
 885           major_t pr_rmajor;      /* major number (if special file) */
 886           minor_t pr_rminor;      /* minor number (if special file) */
 887           int     pr_fileflags;   /* (see F_GETXFL in fcntl(2)) */
 888           int     pr_fdflags;     /* (see F_GETFD in fcntl(2)) */
 889           short   pr_locktype;    /* (see F_GETLK in fcntl(2)) */
 890           pid_t   pr_lockpid;     /* process holding file lock (see F_GETLK) */
 891           int     pr_locksysid;   /* sysid of locking process (see F_GETLK) */
 892           pid_t   pr_peerpid;     /* peer process (socket, door) */
 893           int     pr_filler[25];  /* reserved for future use */
 894           char    pr_peername[PRFNSZ]; /* peer process name */
 895       #if __STDC_VERSION__ >= 199901L
 896           char    pr_misc[];      /* self describing structures */
 897       #else
 898           char    pr_misc[1];
 899       #endif
 900       } prfdinfo_t;
 902      The pr_misc element points to a list of additional miscellaneous data
 903      items, each of which has a header of type pr_misc_header_t specifying the
 904      size and type, and some data which immediately follow the header.
 906       typedef struct pr_misc_header {
 907           uint_t          pr_misc_size;
 908           uint_t          pr_misc_type;
 909       } pr_misc_header_t;
 911      The pr_misc_size field is the sum of the sizes of the header and the
 912      associated data and any trailing padding bytes which will be set to zero.
 913      The end of the list is indicated by a header with a zero size and a type
 914      with all bits set.
 916      The following miscellaneous data types can be present:
 918          PR_PATHNAME                The file descriptor's path in the
 919                                     filesystem.  This is a NUL-terminated
 920                                     sequence of characters.
 922          PR_SOCKETNAME              A sockaddr structure representing the
 923                                     local socket name for this file
 924                                     descriptor, as would be returned by
 925                                     calling getsockname() within the process.
 927          PR_PEERSOCKNAME            A sockaddr structure representing the peer
 928                                     socket name for this file descriptor, as
 929                                     would be returned by calling getpeername()
 930                                     within the process.
 932          PR_SOCKOPTS_BOOL_OPTS      An unsigned integer which has bits set
 933                                     corresponding to options which are set on
 934                                     the underlying socket.  The following bits
 935                                     may be set:
 937                                     PR_SO_DEBUG
 939                                     PR_SO_REUSEADDR
 941                                     PR_SO_REUSEPORT
 943                                     PR_SO_KEEPALIVE
 945                                     PR_SO_DONTROUTE
 947                                     PR_SO_BROADCAST
 949                                     PR_SO_OOBINLINE
 951                                     PR_SO_DGRAM_ERRIND
 953                                     PR_SO_ALLZONES
 955                                     PR_SO_MAC_EXEMPT
 957                                     PR_SO_EXCLBIND
 959                                     PR_SO_PASSIVE_CONNECT
 961                                     PR_SO_ACCEPTCONN
 963                                     PR_UDP_NAT_T_ENDPOINT
 965                                     PR_SO_VRRP
 967                                     PR_SO_MAC_IMPLICIT
 969          PR_SOCKOPT_LINGER          A struct linger as would be returned by
 970                                     calling getsockopt(SO_LINGER) within the
 971                                     process.
 973          PR_SOCKOPT_SNDBUF          The data that would be returned by calling
 974                                     getsockopt(SO_SNDBUF) within the process.
 976          PR_SOCKOPT_RCVBUF          The data that would be returned by calling
 977                                     getsockopt(SO_RCVBUF) within the process.
 979          PR_SOCKOPT_IP_NEXTHOP      The data that would be returned by calling
 980                                     getsockopt(IPPROTO_IP, IP_NEXTHOP) within
 981                                     the process.
 983          PR_SOCKOPT_IPV6_NEXTHOP    The data that would be returned by calling
 984                                     getsockopt(IPPROTO_IPV6, IPV6_NEXTHOP)
 985                                     within the process.
 987          PR_SOCKOPT_TYPE            The data that would be returned by calling
 988                                     getsockopt(SO_TYPE) within the process.
 990          PR_SOCKOPT_TCP_CONGESTION  For TCP sockets, the data that would be
 991                                     returned by calling
 992                                     getsockopt(IPPROTO_TCP, TCP_CONGESTION)
 993                                     within the process.  This is a NUL-
 994                                     terminated character array containing the
 995                                     name of the congestion algorithm in use
 996                                     for the socket.
 998          PR_SOCKFILTERS_PRIV        Private data relating to up to the first
 999                                     32 socket filters pushed on this
1000                                     descriptor.
1002    object
1003      A directory containing read-only files with names corresponding to the
1004      pr_mapname entries in the map and pagedata files.  Opening such a file
1005      yields a file descriptor for the underlying mapped file associated with
1006      an address-space mapping in the process.  The file name a.out appears in
1007      the directory as an alias for the process's executable file.
1009      The object directory makes it possible for a controlling process to gain
1010      access to the object file and any shared libraries (and consequently the
1011      symbol tables) without having to know the actual path names of the
1012      executable files.
1014    path
1015      A directory containing symbolic links to files opened by the process.
1016      The directory includes one entry for cwd and root.  The directory also
1017      contains a numerical entry for each file descriptor in the fd directory,
1018      and entries matching those in the object directory.  If this information
1019      is not available, any attempt to read the contents of the symbolic link
1020      will fail.  This is most common for files that do not exist in the
1021      filesystem namespace (such as FIFOs and sockets), but can also happen for
1022      regular files.  For the file descriptor entries, the path may be
1023      different from the one used by the process to open the file.
1025    pagedata
1026      Opening the page data file enables tracking of address space references
1027      and modifications on a per-page basis.
1029      A read(2) of the page data file descriptor returns structured page data
1030      and atomically clears the page data maintained for the file by the
1031      system.  That is to say, each read returns data collected since the last
1032      read; the first read returns data collected since the file was opened.
1033      When the call completes, the read buffer contains the following structure
1034      as its header and thereafter contains a number of section header
1035      structures and associated byte arrays that must be accessed by walking
1036      linearly through the buffer.
1038       typedef struct prpageheader {
1039           timestruc_t pr_tstamp; /* real time stamp, time of read() */
1040           ulong_t pr_nmap;       /* number of address space mappings */
1041           ulong_t pr_npage;      /* total number of pages */
1042       } prpageheader_t;
1044      The header is followed by pr_nmap prasmap structures and associated data
1045      arrays.  The prasmap structure contains the following elements:
1047       typedef struct prasmap {
1048           uintptr_t pr_vaddr;        /* virtual address of mapping */
1049           ulong_t pr_npage;          /* number of pages in mapping */
1050           char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1051           offset_t pr_offset;        /* offset into mapped object, if any */
1052           int pr_mflags;             /* protection and attribute flags */
1053           int pr_pagesize;           /* pagesize for this mapping in bytes */
1054           int pr_shmid;              /* SysV shared memory identifier */
1055       } prasmap_t;
1057      Each section header is followed by pr_npage bytes, one byte for each page
1058      in the mapping, plus 0-7 null bytes at the end so that the next prasmap
1059      structure begins on an eight-byte aligned boundary.  Each data byte may
1060      contain these flags:
1062       PG_REFERENCED  page has been referenced.
1064       PG_MODIFIED    page has been modified.
1066      If the read buffer is not large enough to contain all of the page data,
1067      the read fails with E2BIG and the page data is not cleared.  The required
1068      size of the read buffer can be determined through fstat(2).  Application
1069      of lseek(2) to the page data file descriptor is ineffective; every read
1070      starts from the beginning of the file.  Closing the page data file
1071      descriptor terminates the system overhead associated with collecting the
1072      data.
1074      More than one page data file descriptor for the same process can be
1075      opened, up to a system-imposed limit per traced process.  A read of one
1076      does not affect the data being collected by the system for the others.
1077      An open of the page data file will fail with ENOMEM if the system-imposed
1078      limit would be exceeded.
1080    watch
1081      Contains an array of prwatch structures, one for each watched area
1082      established by the PCWATCH control operation.  See PCWATCH for details.
1084    usage
1085      Contains process usage information described by a prusage structure which
1086      contains at least the following fields:
1088       typedef struct prusage {
1089           id_t pr_lwpid;           /* lwp id.  0: process or defunct */
1090           int pr_count;            /* number of contributing lwps */
1091           timestruc_t pr_tstamp;   /* real time stamp, time of read() */
1092           timestruc_t pr_create;   /* process/lwp creation time stamp */
1093           timestruc_t pr_term;     /* process/lwp termination time stamp */
1094           timestruc_t pr_rtime;    /* total lwp real (elapsed) time */
1095           timestruc_t pr_utime;    /* user level CPU time */
1096           timestruc_t pr_stime;    /* system call CPU time */
1097           timestruc_t pr_ttime;    /* other system trap CPU time */
1098           timestruc_t pr_tftime;   /* text page fault sleep time */
1099           timestruc_t pr_dftime;   /* data page fault sleep time */
1100           timestruc_t pr_kftime;   /* kernel page fault sleep time */
1101           timestruc_t pr_ltime;    /* user lock wait sleep time */
1102           timestruc_t pr_slptime;  /* all other sleep time */
1103           timestruc_t pr_wtime;    /* wait-cpu (latency) time */
1104           timestruc_t pr_stoptime; /* stopped time */
1105           ulong_t pr_minf;         /* minor page faults */
1106           ulong_t pr_majf;         /* major page faults */
1107           ulong_t pr_nswap;        /* swaps */
1108           ulong_t pr_inblk;        /* input blocks */
1109           ulong_t pr_oublk;        /* output blocks */
1110           ulong_t pr_msnd;         /* messages sent */
1111           ulong_t pr_mrcv;         /* messages received */
1112           ulong_t pr_sigs;         /* signals received */
1113           ulong_t pr_vctx;         /* voluntary context switches */
1114           ulong_t pr_ictx;         /* involuntary context switches */
1115           ulong_t pr_sysc;         /* system calls */
1116           ulong_t pr_ioch;         /* chars read and written */
1117       } prusage_t;
1119      Microstate accounting is now continuously enabled.  While this
1120      information was previously an estimate, if microstate accounting were not
1121      enabled, the current information is now never an estimate represents time
1122      the process has spent in various states.
1124    lstatus
1125      Contains a prheader structure followed by an array of lwpstatus
1126      structures, one for each active lwp in the process (see also
1127      /proc/pid/lwp/lwpid/lwpstatus, below).  The prheader structure describes
1128      the number and size of the array entries that follow.
1130       typedef struct prheader {
1131           long pr_nent;        /* number of entries */
1132           size_t pr_entsize;   /* size of each entry, in bytes */
1133       } prheader_t;
1135      The lwpstatus structure may grow by the addition of elements at the end
1136      in future releases of the system.  Programs must use pr_entsize in the
1137      file header to index through the array.  These comments apply to all
1138      /proc files that include a prheader structure (lpsinfo and lusage,
1139      below).
1141    lpsinfo
1142      Contains a prheader structure followed by an array of lwpsinfo
1143      structures, one for eachactive and zombie lwp in the process.  See also
1144      /proc/pid/lwp/lwpid/lwpsinfo, below.
1146    lusage
1147      Contains a prheader structure followed by an array of prusage structures,
1148      one for each active lwp in the process, plus an additional element at the
1149      beginning that contains the summation over all defunct lwps (lwps that
1150      once existed but no longer exist in the process).  Excluding the
1151      pr_lwpid, pr_tstamp, pr_create, and pr_term entries, the entry-by-entry
1152      summation over all these structures is the definition of the process
1153      usage information obtained from the usage file. (See also
1154      /proc/pid/lwp/lwpid/lwpusage, below.)
1156    lwp
1157      A directory containing entries each of which names an active or zombie
1158      lwp within the process.  These entries are themselves directories
1159      containing additional files as described below.  Only the lwpsinfo file
1160      exists in the directory of a zombie lwp.
1162 STRUCTURE OF /proc/pid/lwp/lwpid
1163      A given directory /proc/pid/lwp/lwpid contains the following entries:
1165    lwpctl
1166      Write-only control file.  The messages written to this file affect the
1167      specific lwp rather than the representative lwp, as is the case for the
1168      process's ctl file.
1170    lwpname
1171      A buffer of THREAD_NAME_MAX bytes representing the LWP name; the buffer
1172      is zero-filled if the thread name is shorter than the buffer.  If no
1173      thread name is set, the buffer contains the empty string.  A read with a
1174      buffer shorter than THREAD_NAME_MAX bytes is not guaranteed to be NUL-
1175      terminated.  Writing to this file will set the LWP name for the specific
1176      lwp.  This file may not be present in older operating system versions.
1177      THREAD_NAME_MAX may increase in the future; clients should be prepared
1178      for this.
1180    lwpstatus
1181      lwp-specific state information.  This file contains the lwpstatus
1182      structure for the specific lwp as described above for the representative
1183      lwp in the process's status file.
1185    lwpsinfo
1186      lwp-specific ps(1) information.  This file contains the lwpsinfo
1187      structure for the specific lwp as described above for the representative
1188      lwp in the process's psinfo file.  The lwpsinfo file remains accessible
1189      after an lwp becomes a zombie.
1191    lwpusage
1192      This file contains the prusage structure for the specific lwp as
1193      described above for the process's usage file.
1195    gwindows
1196      This file exists only on SPARC based machines.  If it is non-empty, it
1197      contains a gwindows_t structure, defined in <sys/regset.h>, with the
1198      values of those SPARC register windows that could not be stored on the
1199      stack when the lwp stopped.  Conditions under which register windows are
1200      not stored on the stack are: the stack pointer refers to nonexistent
1201      process memory or the stack pointer is improperly aligned.  If the lwp is
1202      not stopped or if there are no register windows that could not be stored
1203      on the stack, the file is empty (the usual case).
1205    xregs
1206      Extra state registers.  The extra state register set is architecture
1207      dependent; this file is empty if the system does not support extra state
1208      registers.  If the file is non-empty, it contains an architecture
1209      dependent structure of type prxregset_t, defined in <procfs.h>, with the
1210      values of the lwp's extra state registers.  If the lwp is not stopped,
1211      all register values are undefined.  See also the PCSXREG control
1212      operation, below.
1214    asrs
1215      This file exists only for 64-bit SPARC V9 processes.  It contains an
1216      asrset_t structure, defined in <sys/regset.h>, containing the values of
1217      the lwp's platform-dependent ancillary state registers.  If the lwp is
1218      not stopped, all register values are undefined.  See also the PCSASRS
1219      control operation, below.
1221    spymaster
1222      For an agent lwp (see PCAGENT), this file contains a psinfo_t structure
1223      that corresponds to the process that created the agent lwp at the time
1224      the agent was created.  This structure is identical to that retrieved via
1225      the psinfo file, with one modification: the pr_time field does not
1226      correspond to the CPU time for the process, but rather to the creation
1227      time of the agent lwp.
1229    templates
1230      A directory which contains references to the active templates for the
1231      lwp, named by the contract type.  Changes made to an active template
1232      descriptor do not affect the original template which was activated,
1233      though they do affect the active template.  It is not possible to
1234      activate an active template descriptor.  See contract(4).
1237      Process state changes are effected through messages written to a
1238      process's ctl file or to an individual lwp's lwpctl file.  All control
1239      messages consist of a long that names the specific operation followed by
1240      additional data containing the operand, if any.
1242      Multiple control messages may be combined in a single write(2) (or
1243      writev(2)) to a control file, but no partial writes are permitted.  That
1244      is, each control message, operation code plus operand, if any, must be
1245      presented in its entirety to the write(2) and not in pieces over several
1246      system calls.  If a control operation fails, no subsequent operations
1247      contained in the same write(2) are attempted.
1249      Descriptions of the allowable control messages follow.  In all cases,
1250      writing a message to a control file for a process or lwp that has
1251      terminated elicits the error ENOENT.
1254      When applied to the process control file, PCSTOP directs all lwps to stop
1255      and waits for them to stop, PCDSTOP directs all lwps to stop without
1256      waiting for them to stop, and PCWSTOP simply waits for all lwps to stop.
1257      When applied to an lwp control file, PCSTOP directs the specific lwp to
1258      stop and waits until it has stopped, PCDSTOP directs the specific lwp to
1259      stop without waiting for it to stop, and PCWSTOP
1260       simply waits for the specific lwp to stop.  When applied to an lwp
1261      control file, PCSTOP and PCWSTOP complete when the lwp stops on an event
1262      of interest, immediately if already so stopped; when applied to the
1263      process control file, they complete when every lwp has stopped either on
1264      an event of interest or on a PR_SUSPENDED stop.
1266      PCTWSTOP is identical to PCWSTOP except that it enables the operation to
1267      time out, to avoid waiting forever for a process or lwp that may never
1268      stop on an event of interest.  PCTWSTOP takes a long operand specifying a
1269      number of milliseconds; the wait will terminate successfully after the
1270      specified number of milliseconds even if the process or lwp has not
1271      stopped; a timeout value of zero makes the operation identical to
1272      PCWSTOP.
1274      An "event of interest" is either a PR_REQUESTED stop or a stop that has
1275      been specified in the process's tracing flags (set by PCSTRACE, PCSFAULT,
1277       and PR_SUSPENDED stops are specifically not events of interest.  (An lwp
1278      may stop twice due to a stop signal, first showing PR_SIGNALLED if the
1279      signal is traced and again showing PR_JOBCONTROL if the lwp is set
1280      running without clearing the signal.)  If PCSTOP or PCDSTOP is applied to
1281      an lwp that is stopped, but not on an event of interest, the stop
1282      directive takes effect when the lwp is restarted by the competing
1283      mechanism.  At that time, the lwp enters a PR_REQUESTED stop before
1284      executing any user-level code.
1286      A write of a control message that blocks is interruptible by a signal so
1287      that, for example, an alarm(2) can be set to avoid waiting forever for a
1288      process or lwp that may never stop on an event of interest.  If PCSTOP is
1289      interrupted, the lwp stop directives remain in effect even though the
1290      write(2) returns an error.  (Use of PCTWSTOP with a non-zero timeout is
1291      recommended over PCWSTOP with an alarm(2).)
1293      A system process (indicated by the PR_ISSYS flag) never executes at user
1294      level, has no user-level address space visible through /proc, and cannot
1295      be stopped.  Applying one of these operations to a system process or any
1296      of its lwps elicits the error EBUSY.
1298    PCRUN
1299      Make an lwp runnable again after a stop.  This operation takes a long
1300      operand containing zero or more of the following flags:
1302          PRCSIG    clears the current signal, if any (see PCCSIG).
1304          PRCFAULT  clears the current fault, if any (see PCCFAULT).
1306          PRSTEP    directs the lwp to execute a single machine instruction.
1307                    On completion of the instruction, a trace trap occurs.  If
1308                    FLTTRACE is being traced, the lwp stops; otherwise, it is
1309                    sent SIGTRAP.  If SIGTRAP is being traced and is not
1310                    blocked, the lwp stops.  When the lwp stops on an event of
1311                    interest, the single-step directive is cancelled, even if
1312                    the stop occurs before the instruction is executed.  This
1313                    operation requires hardware and operating system support
1314                    and may not be implemented on all processors.  It is
1315                    implemented on SPARC and x86-based machines.
1317          PRSABORT  is meaningful only if the lwp is in a PR_SYSENTRY stop or
1318                    is marked PR_ASLEEP; it instructs the lwp to abort
1319                    execution of the system call (see PCSENTRY and PCSEXIT).
1321          PRSTOP    directs the lwp to stop again as soon as possible after
1322                    resuming execution (see PCDSTOP).  In particular, if the
1323                    lwp is stopped on PR_SIGNALLED or PR_FAULTED, the next stop
1324                    will show PR_REQUESTED, no other stop will have intervened,
1325                    and the lwp will not have executed any user-level code.
1327      When applied to an lwp control file, PCRUN clears any outstanding
1328      directed-stop request and makes the specific lwp runnable.  The operation
1329      fails with EBUSY if the specific lwp is not stopped on an event of
1330      interest or has not been directed to stop or if the agent lwp exists and
1331      this is not the agent lwp (see PCAGENT).
1333      When applied to the process control file, a representative lwp is chosen
1334      for the operation as described for /proc/pid/status.  The operation fails
1335      with EBUSY if the representative lwp is not stopped on an event of
1336      interest or has not been directed to stop or if the agent lwp exists.  If
1337      PRSTEP or PRSTOP was requested, the representative lwp is made runnable
1338      and its outstanding directed-stop request is cleared; otherwise all
1339      outstanding directed-stop requests are cleared and, if it was stopped on
1340      an event of interest, the representative lwp is marked PR_REQUESTED.  If,
1341      as a consequence, all lwps are in the PR_REQUESTED or PR_SUSPENDED stop
1342      state, all lwps showing PR_REQUESTED are made runnable.
1344    PCSTRACE
1345      Define a set of signals to be traced in the process.  The receipt of one
1346      of these signals by an lwp causes the lwp to stop.  The set of signals is
1347      defined using an operand sigset_t contained in the control message.
1348      Receipt of SIGKILL cannot be traced; if specified, it is silently
1349      ignored.
1351      If a signal that is included in an lwp's held signal set (the signal
1352      mask) is sent to the lwp, the signal is not received and does not cause a
1353      stop until it is removed from the held signal set, either by the lwp
1354      itself or by setting the held signal set with PCSHOLD.
1356    PCCSIG
1357      The current signal, if any, is cleared from the specific or
1358      representative lwp.
1360    PCSSIG
1361      The current signal and its associated signal information for the specific
1362      or representative lwp are set according to the contents of the operand
1363      siginfo structure (see <sys/siginfo.h>).  If the specified   signal number
1364      is zero, the current signal is cleared.  The semantics of this operation
1365      are different from those of kill(2) in that the signal is delivered to
1366      the lwp immediately after execution is resumed (even if it is being
1367      blocked) and an additional PR_SIGNALLED stop does not intervene even if
1368      the signal is traced.  Setting the current signal to SIGKILL terminates
1369      the process immediately.
1371    PCKILL
1372      If applied to the process control file, a signal is sent to the process
1373      with semantics identical to those of kill(2) If applied to an lwp control
1374      file, a directed signal is sent to the specific lwp.  The signal is named
1375      in a long operand contained in the message.  Sending SIGKILL terminates
1376      the process immediately.
1378    PCUNKILL
1379      A signal is deleted, that is, it is removed from the set of pending
1380      signals.  If applied to the process control file, the signal is deleted
1381      from the process's pending signals.  If applied to an lwp control file,
1382      the signal is deleted from the lwp's pending signals.  The current signal
1383      (if any) is unaffected.  The signal is named in a long operand in the
1384      control message.  It is an error (EINVAL) to attempt to delete SIGKILL.
1386    PCSHOLD
1387      Set the set of held signals for the specific or representative lwp
1388      (signals whose delivery will be blocked if sent to the lwp).  The set of
1389      signals is specified with a sigset_t operand.  SIGKILL and SIGSTOP cannot
1390      be held; if specified, they are silently ignored.
1392    PCSFAULT
1393      Define a set of hardware faults to be traced in the process.  On
1394      incurring one of these faults, an lwp stops.  The set is defined via the
1395      operand fltset_t structure.  Fault names are defined in <sys/fault.h> and
1396      include the following.  Some of these may not occur on all processors;
1397      there may be processor-specific faults in addition to these.
1399            FLTILL     illegal instruction
1401            FLTPRIV    privileged instruction
1403            FLTBPT     breakpoint trap
1405            FLTTRACE   trace trap (single-step)
1407            FLTWATCH   watchpoint trap
1409            FLTACCESS  memory access fault (bus error)
1411            FLTBOUNDS  memory bounds violation
1413            FLTIOVF    integer overflow
1415            FLTIZDIV   integer zero divide
1417            FLTFPE     floating-point exception
1419            FLTSTACK   unrecoverable stack fault
1421            FLTPAGE    recoverable page fault
1423      When not traced, a fault normally results in the posting of a signal to
1424      the lwp that incurred the fault.  If an lwp stops on a fault, the signal
1425      is posted to the lwp when execution is resumed unless the fault is
1426      cleared by PCCFAULT or by the PRCFAULT option of PCRUN.  FLTPAGE is an
1427      exception; no signal is posted.  The pr_info field in the lwpstatus
1428      structure identifies the signal to be sent and contains machine-specific
1429      information about the fault.
1431    PCCFAULT
1432      The current fault, if any, is cleared; the associated signal will not be
1433      sent to the specific or representative lwp.
1436      These control operations instruct the process's lwps to stop on entry to
1437      or exit from specified system calls.  The set of system calls to be
1438      traced is defined via an operand sysset_t structure.
1440      When entry to a system call is being traced, an lwp stops after having
1441      begun the call to the system but before the system call arguments have
1442      been fetched from the lwp.  When exit from a system call is being traced,
1443      an lwp stops on completion of the system call just prior to checking for
1444      signals and returning to user level.  At this point, all return values
1445      have been stored into the lwp's registers.
1447      If an lwp is stopped on entry to a system call (PR_SYSENTRY) or when
1448      sleeping in an interruptible system call (PR_ASLEEP is set), it may be
1449      instructed to go directly to system call exit by specifying the PRSABORT
1450      flag in a PCRUN control message.  Unless exit from the system call is
1451      being traced, the lwp returns to user level showing EINTR.
1453    PCWATCH
1454      Set or clear a watched area in the controlled process from a prwatch
1455      structure operand:
1457       typedef struct prwatch {
1458           uintptr_t pr_vaddr;  /* virtual address of watched area */
1459           size_t pr_size;      /* size of watched area in bytes */
1460           int pr_wflags;       /* watch type flags */
1461       } prwatch_t;
1463      pr_vaddr specifies the virtual address of an area of memory to be watched
1464      in the controlled process.  pr_size specifies the size of the area, in
1465      bytes.  pr_wflags specifies the type of memory access to be monitored as
1466      a bit-mask of the following flags:
1468            WA_READ       read access
1470            WA_WRITE      write access
1472            WA_EXEC       execution access
1474            WA_TRAPAFTER  trap after the instruction completes
1476      If pr_wflags is non-empty, a watched area is established for the virtual
1477      address range specified by pr_vaddr and pr_size.  If pr_wflags is empty,
1478      any previously-established watched area starting at the specified virtual
1479      address is cleared; pr_size is ignored.
1481      A watchpoint is triggered when an lwp in the traced process makes a
1482      memory reference that covers at least one byte of a watched area and the
1483      memory reference is as specified in pr_wflags.  When an lwp triggers a
1484      watchpoint, it incurs a watchpoint trap.  If FLTWATCH is being traced,
1485      the lwp stops; otherwise, it is sent a SIGTRAP signal; if SIGTRAP is
1486      being traced and is not blocked, the lwp stops.
1488      The watchpoint trap occurs before the instruction completes unless
1489      WA_TRAPAFTER was specified, in which case it occurs after the instruction
1490      completes.  If it occurs before completion, the memory is not modified.
1491      If it occurs after completion, the memory is modified (if the access is a
1492      write access).
1494      Physical i/o is an exception for watchpoint traps.  In this instance,
1495      there is no guarantee that memory before the watched area has already
1496      been modified (or in the case of WA_TRAPAFTER, that the memory following
1497      the watched area has not been modified) when the watchpoint trap occurs
1498      and the lwp stops.
1500      pr_info in the lwpstatus structure contains information pertinent to the
1501      watchpoint trap.  In particular, the si_addr field contains the virtual
1502      address of the memory reference that triggered the watchpoint, and the
1503      si_code field contains one of TRAP_RWATCH, TRAP_WWATCH, or TRAP_XWATCH,
1504      indicating read, write, or execute access, respectively.  The
1505      si_trapafter field is zero unless WA_TRAPAFTER is in effect for this
1506      watched area; non-zero indicates that the current instruction is not the
1507      instruction that incurred the watchpoint trap.  The si_pc field contains
1508      the virtual address of the instruction that incurred the trap.
1510      A watchpoint trap may be triggered while executing a system call that
1511      makes reference to the traced process's memory.  The lwp that is
1512      executing the system call incurs the watchpoint trap while still in the
1513      system call.  If it stops as a result, the lwpstatus structure contains
1514      the system call number and its arguments.  If the lwp does not stop, or
1515      if it is set running again without clearing the signal or fault, the
1516      system call fails with EFAULT.  If WA_TRAPAFTER was specified, the memory
1517      reference will have completed and the memory will have been modified (if
1518      the access was a write access) when the watchpoint trap occurs.
1520      If more than one of WA_READ, WA_WRITE, and WA_EXEC is specified for a
1521      watched area, and a single instruction incurs more than one of the
1522      specified types, only one is reported when the watchpoint trap occurs.
1523      The precedence is WA_EXEC, WA_READ, WA_WRITE (WA_EXEC and WA_READ take
1524      precedence over WA_WRITE), unless WA_TRAPAFTER was specified, in which
1525      case it is WA_WRITE, WA_READ, WA_EXEC (WA_WRITE takes precedence).
1527      PCWATCH fails with EINVAL if an attempt is made to specify overlapping
1528      watched areas or if pr_wflags contains flags other than those specified
1529      above.  It fails with ENOMEM if an attempt is made to establish more
1530      watched areas than the system can support (the system can support
1531      thousands).
1533      The child of a vfork(2) borrows the parent's address space.  When a
1534      vfork(2) is executed by a traced process, all watched areas established
1535      for the parent are suspended until the child terminates or performs an
1536      exec(2).  Any watched areas established independently in the child are
1537      cancelled when the parent resumes after the child's termination or
1538      exec(2).  PCWATCH fails with EBUSY if applied to the parent of a vfork(2)
1539      before the child has terminated or performed an exec(2).  The PR_VFORKP
1540      flag is set in the pstatus structure for such a parent process.
1542      Certain accesses of the traced process's address space by the operating
1543      system are immune to watchpoints.  The initial construction of a signal
1544      stack frame when a signal is delivered to an lwp will not trigger a
1545      watchpoint trap even if the new frame covers watched areas of the stack.
1546      Once the signal handler is entered, watchpoint traps occur normally.  On
1547      SPARC based machines, register window overflow and underflow will not
1548      trigger watchpoint traps, even if the register window save areas cover
1549      watched areas of the stack.
1551      Watched areas are not inherited by child processes, even if the traced
1552      process's inherit-on-fork mode, PR_FORK, is set (see PCSET, below).  All
1553      watched areas are cancelled when the traced process performs a successful
1554      exec(2).
1557      PCSET sets one or more modes of operation for the traced process.
1558      PCUNSET unsets these modes.  The modes to be set or unset are specified
1559      by flags in an operand long in the control message:
1561          PR_FORK    (inherit-on-fork): When set, the process's tracing flags
1562                     and its inherit-on-fork mode are inherited by the child of
1563                     a fork(2), fork1(2), or vfork(2).  When unset, child
1564                     processes start with all tracing flags cleared.
1566          PR_RLC     (run-on-last-close): When set and the last writable /proc
1567                     file descriptor referring to the traced process or any of
1568                     its lwps is closed, all of the process's tracing flags and
1569                     watched areas are cleared, any outstanding stop directives
1570                     are canceled, and if any lwps are stopped on events of
1571                     interest, they are set running as though PCRUN had been
1572                     applied to them.  When unset, the process's tracing flags
1573                     and watched areas are retained and lwps are not set
1574                     running on last close.
1576          PR_KLC     (kill-on-last-close): When set and the last writable /proc
1577                     file descriptor referring to the traced process or any of
1578                     its lwps is closed, the process is terminated with
1579                     SIGKILL.
1581          PR_ASYNC   (asynchronous-stop): When set, a stop on an event of
1582                     interest by one lwp does not directly affect any other lwp
1583                     in the process.  When unset and an lwp stops on an event
1584                     of interest other than PR_REQUESTED, all other lwps in the
1585                     process are directed to stop.
1587          PR_MSACCT  (microstate accounting): Microstate accounting is now
1588                     continuously enabled.  This flag is deprecated and no
1589                     longer has any effect upon microstate accounting.
1590                     Applications may toggle this flag; however, microstate
1591                     accounting will remain enabled regardless.
1593          PR_MSFORK  (inherit microstate accounting): All processes now inherit
1594                     microstate accounting, as it is continuously enabled.
1595                     This flag has been deprecated and its use no longer has
1596                     any effect upon the behavior of microstate accounting.
1598          PR_BPTADJ  (breakpoint trap pc adjustment): On x86-based machines, a
1599                     breakpoint trap leaves the program counter (the EIP)
1600                     referring to the breakpointed instruction plus one byte.
1601                     When PR_BPTADJ is set, the system will adjust the program
1602                     counter back to the location of the breakpointed
1603                     instruction when the lwp stops on a breakpoint.  This flag
1604                     has no effect on SPARC based machines, where breakpoint
1605                     traps leave the program counter referring to the
1606                     breakpointed instruction.
1608          PR_PTRACE  (ptrace-compatibility): When set, a stop on an event of
1609                     interest by the traced process is reported to the parent
1610                     of the traced process by wait(3C), SIGTRAP is sent to the
1611                     traced process when it executes a successful exec(2),
1612                     setuid/setgid flags are not honored for execs performed by
1613                     the traced process, any exec of an object file that the
1614                     traced process cannot read fails, and the process dies
1615                     when its parent dies.  This mode is deprecated; it is
1616                     provided only to allow ptrace(3C) to be implemented as a
1617                     library function using /proc.
1619      It is an error (EINVAL) to specify flags other than those described above
1620      or to apply these operations to a system process.  The current modes are
1621      reported in the pr_flags field of /proc/pid/status and
1622      /proc/pid/lwp/lwp/lwpstatus.
1624    PCSREG
1625      Set the general registers for the specific or representative lwp
1626      according to the operand prgregset_t structure.
1628      On SPARC based systems, only the condition-code bits of the processor-
1629      status register (R_PSR) of SPARC V8 (32-bit) processes can be modified by
1630      PCSREG.  Other privileged registers cannot be modified at all.
1632      On x86-based systems, only certain bits of the flags register (EFL) can
1633      be modified by PCSREG: these include the condition codes, direction-bit,
1634      and overflow-bit.
1636      PCSREG fails with EBUSY if the lwp is not stopped on an event of
1637      interest.
1639    PCSVADDR
1640      Set the address at which execution will resume for the specific or
1641      representative lwp from the operand long.  On SPARC based systems, both
1642      %pc and %npc are set, with %npc set to the instruction following the
1643      virtual address.  On x86-based systems, only %eip is set.  PCSVADDR fails
1644      with EBUSY if the lwp is not stopped on an event of interest.
1646    PCSFPREG
1647      Set the floating-point registers for the specific or representative lwp
1648      according to the operand prfpregset_t structure.  An error (EINVAL) is
1649      returned if the system does not support floating-point operations (no
1650      floating-point hardware and the system does not emulate floating-point
1651      machine instructions).  PCSFPREG fails with EBUSY if the lwp is not
1652      stopped on an event of interest.
1654    PCSXREG
1655      Set the extra state registers for the specific or representative lwp
1656      according to the architecture-dependent operand prxregset_t structure.
1657      An error (EINVAL) is returned if the system does not support extra state
1658      registers.  PCSXREG fails with EBUSY if the lwp is not stopped on an
1659      event of interest.
1661    PCSASRS
1662      Set the ancillary state registers for the specific or representative lwp
1663      according to the SPARC V9 platform-dependent operand asrset_t structure.
1664      An error (EINVAL) is returned if either the target process or the
1665      controlling process is not a 64-bit SPARC V9 process.  Most of the
1666      ancillary state registers are privileged registers that cannot be
1667      modified.  Only those that can be modified are set; all others are
1668      silently ignored.  PCSASRS fails with EBUSY if the lwp is not stopped on
1669      an event of interest.
1671    PCAGENT
1672      Create an agent lwp in the controlled process with register values from
1673      the operand prgregset_t structure (see PCSREG, above).  The agent lwp is
1674      created in the stopped state showing PR_REQUESTED and with its held
1675      signal set (the signal mask) having all signals except SIGKILL and
1676      SIGSTOP blocked.
1678      The PCAGENT operation fails with EBUSY unless the process is fully
1679      stopped via /proc, that is, unless all of the lwps in the process are
1680      stopped either on events of interest or on PR_SUSPENDED, or are stopped
1681      on PR_JOBCONTROL and have been directed to stop via PCDSTOP.  It fails
1682      with EBUSY if an agent lwp already exists.  It fails with ENOMEM if
1683      system resources for creating new lwps have been exhausted.
1685      Any PCRUN operation applied to the process control file or to the control
1686      file of an lwp other than the agent lwp fails with EBUSY as long as the
1687      agent lwp exists.  The agent lwp must be caused to terminate by executing
1688      the SYS_lwp_exit system call trap before the process can be restarted.
1690      Once the agent lwp is created, its lwp-ID can be found by reading the
1691      process status file.  To facilitate opening the agent lwp's control and
1692      status files, the directory name /proc/pid/lwp/agent is accepted for
1693      lookup operations as an invisible alias for /proc/pid/lwp/lwpid, lwpid
1694      being the lwp-ID of the agent lwp (invisible in the sense that the name
1695      "agent" does not appear in a directory listing of /proc/pid/lwp obtained
1696      from ls(1), getdents(2), or readdir(3C).
1698      The purpose of the agent lwp is to perform operations in the controlled
1699      process on behalf of the controlling process: to gather information not
1700      directly available via /proc files, or in general to make the process
1701      change state in ways not directly available via /proc control operations.
1702      To make use of an agent lwp, the controlling process must be capable of
1703      making it execute system calls (specifically, the SYS_lwp_exit system
1704      call trap).  The register values given to the agent lwp on creation are
1705      typically the registers of the representative lwp, so that the agent lwp
1706      can use its stack.
1708      If the controlling process neglects to force the agent lwp to execute the
1709      SYS_lwp_exit system call (due to either logic error or fatal failure on
1710      the part of the controlling process), the agent lwp will remain in the
1711      target process.  For purposes of being able to debug these otherwise
1712      rogue agents, information as to the creator of the agent lwp is reflected
1713      in that lwp's spymaster file in /proc.  Should the target process
1714      generate a core dump with the agent lwp in place, this information will
1715      be available via the NT_SPYMASTER note in the core file (see core(4)).
1717      The agent lwp is not allowed to execute any variation of the SYS_fork or
1718      SYS_exec system call traps.  Attempts to do so yield ENOTSUP to the agent
1719      lwp.
1721      Symbolic constants for system call trap numbers like SYS_lwp_exit and
1722      SYS_lwp_create can be found in the header file <sys/syscall.h>.
1725      Read or write the target process's address space via a priovec structure
1726      operand:
1728       typedef struct priovec {
1729           void *pio_base;      /* buffer in controlling process */
1730           size_t pio_len;      /* size of read/write request in bytes */
1731           off_t pio_offset;    /* virtual address in target process */
1732       } priovec_t;
1734      These operations have the same effect as pread(2) and pwrite(2),
1735      respectively, of the target process's address space file.  The difference
1736      is that more than one PCREAD or PCWRITE control operation can be written
1737      to the control file at once, and they can be interspersed with other
1738      control operations in a single write to the control file.  This is
1739      useful, for example, when planting many breakpoint instructions in the
1740      process's address space, or when stepping over a breakpointed
1741      instruction.  Unlike pread(2) and pwrite(2), no provision is made for
1742      partial reads or writes; if the operation cannot be performed completely,
1743      it fails with EIO.
1745    PCNICE
1746      The traced process's nice(2) value is incremented by the amount in the
1747      operand long.  Only a process with the {PRIV_PROC_PRIOCNTL} privilege
1748      asserted in its effective set can better a process's priority in this
1749      way, but any user may lower the priority.  This operation is not
1750      meaningful for all scheduling classes.
1752    PCSCRED
1753      Set the target process credentials to the values contained in the
1754      prcred_t structure operand (see /proc/pid/cred).  The effective, real,
1755      and saved user-IDs and group-IDs of the target process are set.  The
1756      target process's supplementary groups are not changed; the pr_ngroups and
1757      pr_groups members of the structure operand are ignored.  Only the
1758      privileged processes can perform this operation; for all others it fails
1759      with EPERM.
1761    PCSCREDX
1762      Operates like PCSCRED but also sets the supplementary groups; the length
1763      of the data written with this control operation should be "sizeof
1764      (prcred_t) + sizeof (gid_t) * (#groups - 1)".
1766    PCSPRIV
1767      Set the target process privilege to the values contained in the prpriv_t
1768      operand (see /proc/pid/priv).  The effective, permitted, inheritable, and
1769      limit sets are all changed.  Privilege flags can also be set.  The
1770      process is made privilege aware unless it can relinquish privilege
1771      awareness.  See privileges(5).
1773      The limit set of the target process cannot be grown.  The other privilege
1774      sets must be subsets of the intersection of the effective set of the
1775      calling process with the new limit set of the target process or subsets
1776      of the original values of the sets in the target process.
1778      If any of the above restrictions are not met, EPERM is returned.  If the
1779      structure written is improperly formatted, EINVAL is returned.
1782      For security reasons, except for the psinfo, usage, lpsinfo, lusage,
1783      lwpsinfo, and lwpusage files, which are world-readable, and except for
1784      privileged processes, an open of a /proc file fails unless both the user-
1785      ID and group-ID of the caller match those of the traced process and the
1786      process's object file is readable by the caller.  The effective set of
1787      the caller is a superset of both the inheritable and the permitted set of
1788      the target process.  The limit set of the caller is a superset of the
1789      limit set of the target process.  Except for the world-readable files
1790      just mentioned, files corresponding to setuid and setgid processes can be
1791      opened only by the appropriately privileged process.
1793      A process that is missing the basic privilege {PRIV_PROC_INFO} cannot see
1794      any processes under /proc that it cannot send a signal to.
1796      A process that has {PRIV_PROC_OWNER} asserted in its effective set can
1797      open any file for reading.  To manipulate or control a process, the
1798      controlling process must have at least as many privileges in its
1799      effective set as the target process has in its effective, inheritable,
1800      and permitted sets.  The limit set of the controlling process must be a
1801      superset of the limit set of the target process.  Additional restrictions
1802      apply if any of the uids of the target process are 0.  See privileges(5).
1804      Even if held by a privileged process, an open process or lwp file
1805      descriptor (other than file descriptors for the world-readable files)
1806      becomes invalid if the traced process performs an exec(2) of a
1807      setuid/setgid object file or an object file that the traced process
1808      cannot read.  Any operation performed on an invalid file descriptor,
1809      except close(2), fails with EAGAIN.  In this situation, if any tracing
1810      flags are set and the process or any lwp file descriptor is open for
1811      writing, the process will have been directed to stop and its run-on-last-
1812      close flag will have been set (see PCSET).  This enables a controlling
1813      process (if it has permission) to reopen the /proc files to get new valid
1814      file descriptors, close the invalid file descriptors, unset the run-on-
1815      last-close flag (if desired), and proceed.  Just closing the invalid file
1816      descriptors causes the traced process to resume execution with all
1817      tracing flags cleared.  Any process not currently open for writing via
1818      /proc, but that has left-over tracing flags from a previous open, and
1819      that executes a setuid/setgid or unreadable object file, will not be
1820      stopped but will have all its tracing flags cleared.
1822      To wait for one or more of a set of processes or lwps to stop or
1823      terminate, /proc file descriptors (other than those obtained by opening
1824      the cwd or root directories or by opening files in the fd or object
1825      directories) can be used in a poll(2) system call.  When requested and
1826      returned, either of the polling events POLLPRI or POLLWRNORM indicates
1827      that the process or lwp stopped on an event of interest.  Although they
1828      cannot be requested, the polling events POLLHUP, POLLERR, and POLLNVAL
1829      may be returned.  POLLHUP indicates that the process or lwp has
1830      terminated.  POLLERR indicates that the file descriptor has become
1831      invalid.  POLLNVAL is returned immediately if POLLPRI or POLLWRNORM is
1832      requested on a file descriptor referring to a system process (see
1833      PCSTOP).  The requested events may be empty to wait simply for
1834      termination.
1836 FILES
1837      /proc   directory (list of processes)
1838      /proc/pid
1839              specific process directory
1840      /proc/self
1841              alias for a process's own directory
1842      /proc/pid/as
1843              address space file
1844      /proc/pid/ctl
1845              process control file
1846      /proc/pid/status
1847              process status
1848      /proc/pid/lstatus
1849              array of lwp status structs
1850      /proc/pid/psinfo
1851              process ps(1) info
1852      /proc/pid/lpsinfo
1853              array of lwp ps(1) info structs
1854      /proc/pid/map
1855              address space map
1856      /proc/pid/xmap
1857              extended address space map
1858      /proc/pid/rmap
1859              reserved address map
1860      /proc/pid/cred
1861              process credentials
1862      /proc/pid/priv
1863              process privileges
1864      /proc/pid/sigact
1865              process signal actions
1866      /proc/pid/auxv
1867              process aux vector
1868      /proc/pid/ldt
1869              process LDT (x86 only)
1870      /proc/pid/usage
1871              process usage
1872      /proc/pid/lusage
1873              array of lwp usage structs
1874      /proc/pid/path
1875              symbolic links to process open files
1876      /proc/pid/pagedata
1877              process page data
1878      /proc/pid/watch
1879              active watchpoints
1880      /proc/pid/cwd
1881              alias for the current working directory
1882      /proc/pid/root
1883              alias for the root directory
1884      /proc/pid/fd
1885              directory (list of open files)
1886      /proc/pid/fd/*
1887              aliases for process's open files
1888      /proc/pid/object
1889              directory (list of mapped files)
1890      /proc/pid/object/a.out
1891              alias for process's executable file
1892      /proc/pid/object/*
1893              aliases for other mapped files
1894      /proc/pid/lwp
1895              directory (list of lwps)
1896      /proc/pid/lwp/lwpid
1897              specific lwp directory
1898      /proc/pid/lwp/agent
1899              alias for the agent lwp directory
1900      /proc/pid/lwp/lwpid/lwpctl
1901              lwp control file
1902      /proc/pid/lwp/lwpid/lwpstatus
1903              lwp status
1904      /proc/pid/lwp/lwpid/lwpsinfo
1905              lwp ps(1) info
1906      /proc/pid/lwp/lwpid/lwpusage
1907              lwp usage
1908      /proc/pid/lwp/lwpid/gwindows
1909              register windows (SPARC only)
1910      /proc/pid/lwp/lwpid/xregs
1911              extra state registers
1912      /proc/pid/lwp/lwpid/asrs
1913              ancillary state registers (SPARC V9 only)
1914      /proc/pid/lwp/lwpid/spymaster
1915              For an agent LWP, the controlling process
1918      Errors that can occur in addition to the errors normally associated with
1919      file system access:
1921          E2BIG      Data to be returned in a read(2) of the page data file
1922                     exceeds the size of the read buffer provided by the
1923                     caller.
1925          EACCES     An attempt was made to examine a process that ran under a
1926                     different uid than the controlling process and
1927                     {PRIV_PROC_OWNER} was not asserted in the effective set.
1929          EAGAIN     The traced process has performed an exec(2) of a
1930                     setuid/setgid object file or of an object file that it
1931                     cannot read; all further operations on the process or lwp
1932                     file descriptor (except close(2)) elicit this error.
1934          EBUSY      PCSTOP, PCDSTOP, PCWSTOP, or PCTWSTOP was applied to a
1935                     system process; an exclusive open(2) was attempted on a
1936                     /proc file for a process already open for writing; PCRUN,
1937                     PCSREG, PCSVADDR, PCSFPREG, or PCSXREG was applied to a
1938                     process or lwp not stopped on an event of interest; an
1939                     attempt was made to mount /proc when it was already
1940                     mounted; PCAGENT was applied to a process that was not
1941                     fully stopped or that already had an agent lwp.
1943          EINVAL     In general, this means that some invalid argument was
1944                     supplied to a system call.  A non-exhaustive list of
1945                     conditions eliciting this error includes: a control
1946                     message operation code is undefined; an out-of-range
1947                     signal number was specified with PCSSIG, PCKILL, or
1948                     PCUNKILL; SIGKILL was specified with PCUNKILL; PCSFPREG
1949                     was applied on a system that does not support floating-
1950                     point operations; PCSXREG was applied on a system that
1951                     does not support extra state registers.
1953          EINTR      A signal was received by the controlling process while
1954                     waiting for the traced process or lwp to stop via PCSTOP,
1955                     PCWSTOP, or PCTWSTOP.
1957          EIO        A write(2) was attempted at an illegal address in the
1958                     traced process.
1960          ENOENT     The traced process or lwp has terminated after being
1961                     opened.  The basic privilege {PRIV_PROC_INFO} is not
1962                     asserted in the effective set of the calling process and
1963                     the calling process cannot send a signal to the target
1964                     process.
1966          ENOMEM     The system-imposed limit on the number of page data file
1967                     descriptors was reached on an open of /proc/pid/pagedata;
1968                     an attempt was made with PCWATCH to establish more watched
1969                     areas than the system can support; the PCAGENT operation
1970                     was issued when the system was out of resources for
1971                     creating lwps.
1973          ENOSYS     An attempt was made to perform an unsupported operation
1974                     (such as creat(2), link(2), or unlink(2)) on an entry in
1975                     /proc.
1977          EOVERFLOW  A 32-bit controlling process attempted to read or write
1978                     the as file or attempted to read the map, rmap, or
1979                     pagedata file of a 64-bit target process.  A 32-bit
1980                     controlling process attempted to apply one of the control
1981                     operations PCSREG, PCSXREG, PCSVADDR, PCWATCH, PCAGENT,
1982                     PCREAD, PCWRITE to a 64-bit target process.
1984          EPERM      The process that issued the PCSCRED or PCSCREDX operation
1985                     did not have the {PRIV_PROC_SETID} privilege asserted in
1986                     its effective set, or the process that issued the PCNICE
1987                     operation did not have the {PRIV_PROC_PRIOCNTL} in its
1988                     effective set.
1990                     An attempt was made to control a process of which the E,
1991                     P, and I privilege sets were not a subset of the effective
1992                     set of the controlling process or the limit set of the
1993                     controlling process is not a superset of limit set of the
1994                     controlled process.
1996                     Any of the uids of the target process are 0 or an attempt
1997                     was made to change any of the uids to 0 using PCSCRED and
1998                     the security policy imposed additional restrictions.  See
1999                     privileges(5).
2002      ls(1), ps(1), chroot(1M), alarm(2), brk(2), chdir(2), chroot(2),
2003      close(2), creat(2), dup(2), exec(2), fcntl(2), fork(2), fork1(2),
2004      fstat(2), getdents(2), getustack(2), kill(2), lseek(2), mmap(2), nice(2),
2005      open(2), poll(2), pread(2), pwrite(2), read(2), readlink(2), readv(2),
2006      shmget(2), sigaction(2), sigaltstack(2), vfork(2), write(2), writev(2),
2007      _stack_grow(3C), pthread_create(3C), pthread_join(3C), ptrace(3C),
2008      readdir(3C), thr_create(3C), thr_join(3C), wait(3C), siginfo.h(3HEAD),
2009      signal.h(3HEAD), types32.h(3HEAD), ucontext.h(3HEAD), contract(4),
2010      core(4), process(4), lfcompile(5), privileges(5), security-flags(5)
2012 NOTES
2013      Descriptions of structures in this document include only interesting
2014      structure elements, not filler and padding fields, and may show elements
2015      out of order for descriptive clarity.  The actual structure definitions
2016      are contained in <procfs.h>.
2018 BUGS
2019      Because the old ioctl(2)-based version of /proc is currently supported
2020      for binary compatibility with old applications, the top-level directory
2021      for a process, /proc/pid, is not world-readable, but it is world-
2022      searchable.  Thus, anyone can open /proc/pid/psinfo even though ls(1)
2023      applied to /proc/pid will fail for anyone but the owner or an
2024      appropriately privileged process.  Support for the old ioctl(2)-based
2025      version of /proc will be dropped in a future release, at which time the
2026      top-level directory for a process will be made world-readable.
2028      On SPARC based machines, the types gregset_t and fpregset_t defined in
2029      <sys/regset.h> are   similar to but not the same as the types prgregset_t
2030      and prfpregset_t defined in <procfs.h>.
2032 illumos                          May 17, 2020                          illumos