--- old/usr/src/man/man4/proc.4
          +++ new/usr/src/man/man4/proc.4

   1    1  '\" te
   2    2  .\" Copyright 1989 AT&T
   3    3  .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
   4    4  .\" Copyright 2015, Joyent, Inc.
   5    5  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6    6  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7    7  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8    8  .TH PROC 4 "May 19, 2014"
   9    9  .SH NAME
  10   10  proc \- /proc, the process file system
  11   11  .SH DESCRIPTION
  12   12  .LP
  13   13  \fB/proc\fR is a file system that provides access to the state of each process
  14   14  and light-weight process (lwp) in the system. The name of each entry in the
  15   15  \fB/proc\fR directory is a decimal number corresponding to a process-ID. These
  16   16  entries are themselves subdirectories. Access to process state is provided by
  17   17  additional files contained within each subdirectory; the hierarchy is described
  18   18  more completely below. In this document, ``\fB/proc\fR file'' refers to a
  19   19  non-directory file within the hierarchy rooted at \fB/proc\fR. The owner of
  20   20  each \fB/proc\fR file and subdirectory is determined by the user-ID of the
  21   21  process.
  22   22  .sp
  23   23  .LP
  24   24  \fB/proc\fR can be mounted on any mount point, in addition to the standard
  25   25  \fB/proc\fR mount point, and can be mounted several places at once. Such
  26   26  additional mounts are allowed in order to facilitate the confinement of
  27   27  processes to subtrees of the file system via \fBchroot\fR(1M) and yet allow
  28   28  such processes access to commands like \fBps\fR(1).
  29   29  .sp
  30   30  .LP
  31   31  Standard system calls are used to access \fB/proc\fR files: \fBopen\fR(2),
  32   32  \fBclose\fR(2), \fBread\fR(2), and \fBwrite\fR(2) (including \fBreadv\fR(2),
  33   33  \fBwritev\fR(2), \fBpread\fR(2), and \fBpwrite\fR(2)). Most files describe
  34   34  process state and can only be opened for reading. \fBctl\fR and \fBlwpctl\fR
  35   35  (control) files permit manipulation of process state and can only be opened for
  36   36  writing. \fBas\fR (address space) files contain the image of the running
  37   37  process and can be opened for both reading and writing. An open for writing
  38   38  allows process control; a read-only open allows inspection but not control. In
  39   39  this document, we refer to the process as open for reading or writing if any of
  40   40  its associated \fB/proc\fR files is open for reading or writing.
  41   41  .sp
  42   42  .LP
  43   43  In general, more than one process can open the same \fB/proc\fR file at the
  44   44  same time. \fIExclusive\fR \fIopen\fR is an advisory mechanism provided to
  45   45  allow controlling processes to avoid collisions with each other. A process can
  46   46  obtain exclusive control of a target process, with respect to other cooperating
  47   47  processes, if it successfully opens any \fB/proc\fR file in the target process
  48   48  for writing (the \fBas\fR or \fBctl\fR files, or the \fBlwpctl\fR file of any
  49   49  lwp) while specifying \fBO_EXCL\fR in the \fBopen\fR(2). Such an open will fail
  50   50  if the target process is already open for writing (that is, if an \fBas\fR,
  51   51  \fBctl\fR, or \fBlwpctl\fR file is already open for writing). There can be any
  52   52  number of concurrent read-only opens; \fBO_EXCL\fR is ignored on opens for
  53   53  reading. It is recommended that the first open for writing by a controlling
  54   54  process use the \fBO_EXCL\fR flag; multiple controlling processes usually
  55   55  result in chaos.
  56   56  .sp
  57   57  .LP
  58   58  If a process opens one of its own \fB/proc\fR files for writing, the open
  59   59  succeeds regardless of \fBO_EXCL\fR and regardless of whether some other
  60   60  process has the process open for writing. Self-opens do not count when another
  61   61  process attempts an exclusive open. (A process cannot exclude a debugger by
  62   62  opening itself for writing and the application of a debugger cannot prevent a
  63   63  process from opening itself.) All self-opens for writing are forced to be
  64   64  close-on-exec (see the \fBF_SETFD\fR operation of \fBfcntl\fR(2)).
  65   65  .sp
  66   66  .LP
  67   67  Data may be transferred from or to any locations in the address space of the
  68   68  traced process by applying \fBlseek\fR(2) to position the \fBas\fR file at the
  69   69  virtual address of interest followed by \fBread\fR(2) or \fBwrite\fR(2) (or by
  70   70  using \fBpread\fR(2) or \fBpwrite\fR(2) for the combined operation). The
  71   71  address-map files \fB/proc/\fR\fIpid\fR\fB/map\fR and
  72   72  \fB/proc/\fR\fIpid\fR\fB/xmap\fR can be read to determine the accessible areas
  73   73  (mappings) of the address space. \fBI/O\fR transfers may span contiguous
  74   74  mappings. An \fBI/O\fR request extending into an unmapped area is truncated at
  75   75  the boundary. A write request beginning at an unmapped virtual address fails
  76   76  with \fBEIO\fR; a read request beginning at an unmapped virtual address returns
  77   77  zero (an end-of-file indication).
  78   78  .sp
  79   79  .LP
  80   80  Information and control operations are provided through additional files.
  81   81  \fB<procfs.h>\fR contains definitions of data structures and message formats
  82   82  used with these files. Some of these definitions involve the use of sets of
  83   83  flags. The set types \fBsigset_t\fR, \fBfltset_t\fR, and \fBsysset_t\fR
  84   84  correspond, respectively, to signal, fault, and system call enumerations
  85   85  defined in \fB<sys/signal.h>\fR, \fB<sys/fault.h>\fR, and
  86   86  \fB<sys/syscall.h>\fR\&. Each set type is large enough to hold flags for its
  87   87  own enumeration. Although they are of different sizes, they have a common
  88   88  structure and can be manipulated by these macros:
  89   89  .sp
  90   90  .in +2
  91   91  .nf
  92   92  prfillset(&set);             /* turn on all flags in set */
  93   93  premptyset(&set);            /* turn off all flags in set */
  94   94  praddset(&set, flag);        /* turn on the specified flag */
  95   95  prdelset(&set, flag);        /* turn off the specified flag */
  96   96  r = prismember(&set, flag);  /* != 0 iff flag is turned on */
  97   97  .fi
  98   98  .in -2
  99   99  
 100  100  .sp
 101  101  .LP
 102  102  One of \fBprfillset()\fR or \fBpremptyset()\fR must be used to initialize
 103  103  \fBset\fR before it is used in any other operation. \fBflag\fR must be a member
 104  104  of the enumeration corresponding to \fBset\fR.
 105  105  .sp
 106  106  .LP
 107  107  Every process contains at least one \fIlight-weight process\fR, or \fIlwp\fR.
 108  108  Each lwp represents a flow of execution that is independently scheduled by the
 109  109  operating system. All lwps in a process share its address space as well as many
 110  110  other attributes. Through the use of \fBlwpctl\fR and \fBctl\fR files as
 111  111  described below, it is possible to affect individual lwps in a process or to
 112  112  affect all of them at once, depending on the operation.
 113  113  .sp
 114  114  .LP
 115  115  When the process has more than one lwp, a representative lwp is chosen by the
 116  116  system for certain process status files and control operations. The
 117  117  representative lwp is a stopped lwp only if all of the process's lwps are
 118  118  stopped; is stopped on an event of interest only if all of the lwps are so
 119  119  stopped (excluding \fBPR_SUSPENDED\fR lwps); is in a \fBPR_REQUESTED\fR stop
 120  120  only if there are no other events of interest to be found; or, failing
 121  121  everything else, is in a \fBPR_SUSPENDED\fR stop (implying that the process is
 122  122  deadlocked). See the description of the \fBstatus\fR file for definitions of
 123  123  stopped states. See the \fBPCSTOP\fR control operation for the definition of
 124  124  ``event of interest''.
 125  125  .sp
 126  126  .LP
 127  127  The representative lwp remains fixed (it will be chosen again on the next
 128  128  operation) as long as all of the lwps are stopped on events of interest or are
 129  129  in a \fBPR_SUSPENDED\fR stop and the \fBPCRUN\fR control operation is not
 130  130  applied to any of them.
 131  131  .sp
 132  132  .LP
 133  133  When applied to the process control file, every \fB/proc\fR control operation
 134  134  that must act on an lwp uses the same algorithm to choose which lwp to act
 135  135  upon. Together with synchronous stopping (see \fBPCSET\fR), this enables a
 136  136  debugger to control a multiple-lwp process using only the process-level status
 137  137  and control files if it so chooses. More fine-grained control can be achieved
 138  138  using the lwp-specific files.
 139  139  .sp
 140  140  .LP
 141  141  The system supports two process data models, the traditional 32-bit data model
 142  142  in which ints, longs and pointers are all 32 bits wide (the ILP32 data model),
 143  143  and on some platforms the 64-bit data model in which longs and pointers, but
 144  144  not ints, are 64 bits in width (the LP64 data model). In the LP64 data model
 145  145  some system data types, notably \fBsize_t\fR, \fBoff_t\fR, \fBtime_t\fR and
 146  146  \fBdev_t\fR, grow from 32 bits to 64 bits as well.
 147  147  .sp
 148  148  .LP
 149  149  The \fB/proc\fR interfaces described here are available to both 32-bit and
 150  150  64-bit controlling processes. However, many operations attempted by a 32-bit
 151  151  controlling process on a 64-bit target process will fail with \fBEOVERFLOW\fR
 152  152  because the address space range of a 32-bit process cannot encompass a 64-bit
 153  153  process or because the data in some 64-bit system data type cannot be
 154  154  compressed to fit into the corresponding 32-bit type without loss of
 155  155  information. Operations that fail in this circumstance include reading and
 156  156  writing the address space, reading the address-map files, and setting the
 157  157  target process's registers. There is no restriction on operations applied by a
 158  158  64-bit process to either a 32-bit or a 64-bit target processes.
 159  159  .sp
 160  160  .LP
 161  161  The format of the contents of any \fB/proc\fR file depends on the data model of
 162  162  the observer (the controlling process), not on the data model of the target
 163  163  process. A 64-bit debugger does not have to translate the information it reads
 164  164  from a \fB/proc\fR file for a 32-bit process from 32-bit format to 64-bit
 165  165  format. However, it usually has to be aware of the data model of the target
 166  166  process. The \fBpr_dmodel\fR field of the \fBstatus\fR files indicates the
 167  167  target process's data model.
 168  168  .sp
 169  169  .LP
 170  170  To help deal with system data structures that are read from 32-bit processes, a
 171  171  64-bit controlling program can be compiled with the C preprocessor symbol
 172  172  \fB_SYSCALL32\fR defined before system header files are included. This makes
 173  173  explicit 32-bit fixed-width data structures (like \fBcstruct stat32\fR) visible
 174  174  to the 64-bit program. See \fBtypes32.h\fR(3HEAD).
 175  175  .SH DIRECTORY STRUCTURE
 176  176  .LP
 177  177  At the top level, the directory \fB/proc\fR contains entries each of which
 178  178  names an existing process in the system. These entries are themselves
 179  179  directories. Except where otherwise noted, the files described below can be
 180  180  opened for reading only. In addition, if a process becomes a \fIzombie\fR (one
 181  181  that has exited but whose parent has not yet performed a \fBwait\fR(3C) upon
 182  182  it), most of its associated \fB/proc\fR files disappear from the hierarchy;
 183  183  subsequent attempts to open them, or to read or write files opened before the
 184  184  process exited, will elicit the error \fBENOENT\fR.
 185  185  .sp
 186  186  .LP
 187  187  Although process state and consequently the contents of \fB/proc\fR files can
 188  188  change from instant to instant, a single \fBread\fR(2) of a \fB/proc\fR file is
 189  189  guaranteed to return a sane representation of state; that is, the read will be
 190  190  atomic with respect to the state of the process. No such guarantee applies to
 191  191  successive reads applied to a \fB/proc\fR file for a running process. In
 192  192  addition, atomicity is not guaranteed for \fBI/O\fR applied to the \fBas\fR
 193  193  (address-space) file for a running process or for a process whose address space
 194  194  contains memory shared by another running process.
 195  195  .sp
 196  196  .LP
 197  197  A number of structure definitions are used to describe the files. These
 198  198  structures may grow by the addition of elements at the end in future releases
 199  199  of the system and it is not legitimate for a program to assume that they will
 200  200  not.
 201  201  .SH STRUCTURE OF \fB/proc/\fR\fIpid\fR
 202  202  .LP
 203  203  A given directory \fB/proc/\fR\fIpid\fR contains the following entries. A
 204  204  process can use the invisible alias \fB/proc/self\fR if it wishes to open one
 205  205  of its own \fB/proc\fR files (invisible in the sense that the name ``self''
 206  206  does not appear in a directory listing of \fB/proc\fR obtained from
 207  207  \fBls\fR(1), \fBgetdents\fR(2), or \fBreaddir\fR(3C)).
 208  208  .SS "contracts"
 209  209  .LP
 210  210  A directory containing references to the contracts held by the process. Each
 211  211  entry is a symlink to the contract's directory under \fB/system/contract\fR.
 212  212  See \fBcontract\fR(4).
 213  213  .SS "as"
 214  214  .LP
 215  215  Contains the address-space image of the process; it can be opened for both
 216  216  reading and writing. \fBlseek\fR(2) is used to position the file at the virtual
 217  217  address of interest and then the address space can be examined or changed
 218  218  through \fBread\fR(2) or \fBwrite\fR(2) (or by using \fBpread\fR(2) or
 219  219  \fBpwrite\fR(2) for the combined operation).
 220  220  .SS "ctl"
 221  221  .LP
 222  222  A write-only file to which structured messages are written directing the system
 223  223  to change some aspect of the process's state or control its behavior in some
 224  224  way. The seek offset is not relevant when writing to this file. Individual lwps
 225  225  also have associated \fBlwpctl\fR files in the lwp subdirectories. A control
 226  226  message may be written either to the process's \fBctl\fR file or to a specific
 227  227  \fBlwpctl\fR file with operation-specific effects. The effect of a control
 228  228  message is immediately reflected in the state of the process visible through
 229  229  appropriate status and information files. The types of control messages are
 230  230  described in detail later. See \fBCONTROL MESSAGES\fR.
 231  231  .SS "status"
 232  232  .LP
 233  233  Contains state information about the process and the representative lwp. The
 234  234  file contains a \fBpstatus\fR structure which contains an embedded
 235  235  \fBlwpstatus\fR structure for the representative lwp, as follows:
 236  236  .sp
 237  237  .in +2
 238  238  .nf
 239  239  typedef struct pstatus {
 240  240       int pr_flags;            /* flags (see below) */
 241  241       int pr_nlwp;             /* number of active lwps in the process */
 242  242       int pr_nzomb;            /* number of zombie lwps in the process */
 243  243       pid_tpr_pid;             /* process id */
 244  244       pid_tpr_ppid;            /* parent process id */
 245  245       pid_tpr_pgid;            /* process group id */
 246  246       pid_tpr_sid;             /* session id */
 247  247       id_t pr_aslwpid;         /* obsolete */
 248  248       id_t pr_agentid;         /* lwp-id of the agent lwp, if any */
 249  249       sigset_t pr_sigpend;     /* set of process pending signals */
 250  250       uintptr_t pr_brkbase;    /* virtual address of the process heap */
 251  251       size_t pr_brksize;       /* size of the process heap, in bytes */
 252  252       uintptr_t pr_stkbase;    /* virtual address of the process stack */
 253  253       size_tpr_stksize;        /* size of the process stack, in bytes */
 254  254       timestruc_t pr_utime;    /* process user cpu time */
 255  255       timestruc_t pr_stime;    /* process system cpu time */
 256  256       timestruc_t pr_cutime;   /* sum of children's user times */
 257  257       timestruc_t pr_cstime;   /* sum of children's system times */
 258  258       sigset_t pr_sigtrace;    /* set of traced signals */
 259  259       fltset_t pr_flttrace;    /* set of traced faults */
 260  260       sysset_t pr_sysentry;    /* set of system calls traced on entry */
 261  261       sysset_t pr_sysexit;     /* set of system calls traced on exit */
 262  262       char pr_dmodel;          /* data model of the process */
 263  263       taskid_t pr_taskid;      /* task id */
 264  264       projid_t pr_projid;      /* project id */
 265  265       zoneid_t pr_zoneid;      /* zone id */
 266  266       lwpstatus_t pr_lwp;      /* status of the representative lwp */
 267  267  } pstatus_t;
 268  268  .fi
 269  269  .in -2
 270  270  
 271  271  .sp
 272  272  .LP
 273  273  \fBpr_flags\fR is a bit-mask holding the following process flags. For
 274  274  convenience, it also contains the lwp flags for the representative lwp,
 275  275  described later.
 276  276  .sp
 277  277  .ne 2
 278  278  .na
 279  279  \fB\fBPR_ISSYS\fR\fR
 280  280  .ad
 281  281  .RS 13n
 282  282  process is a system process (see \fBPCSTOP\fR).
 283  283  .RE
 284  284  
 285  285  .sp
 286  286  .ne 2
 287  287  .na
 288  288  \fB\fBPR_VFORKP\fR\fR
 289  289  .ad
 290  290  .RS 13n
 291  291  process is the parent of a vforked child (see \fBPCWATCH\fR).
 292  292  .RE
 293  293  
 294  294  .sp
 295  295  .ne 2
 296  296  .na
 297  297  \fB\fBPR_FORK\fR\fR
 298  298  .ad
 299  299  .RS 13n
 300  300  process has its inherit-on-fork mode set (see \fBPCSET\fR).
 301  301  .RE
 302  302  
 303  303  .sp
 304  304  .ne 2
 305  305  .na
 306  306  \fB\fBPR_RLC\fR\fR
 307  307  .ad
 308  308  .RS 13n
 309  309  process has its run-on-last-close mode set (see \fBPCSET\fR).
 310  310  .RE
 311  311  
 312  312  .sp
 313  313  .ne 2
 314  314  .na
 315  315  \fB\fBPR_KLC\fR\fR
 316  316  .ad
 317  317  .RS 13n
 318  318  process has its kill-on-last-close mode set (see \fBPCSET\fR).
 319  319  .RE
 320  320  
 321  321  .sp
 322  322  .ne 2
 323  323  .na
 324  324  \fB\fBPR_ASYNC\fR\fR
 325  325  .ad
 326  326  .RS 13n
 327  327  process has its asynchronous-stop mode set (see \fBPCSET\fR).
 328  328  .RE
 329  329  
 330  330  .sp
 331  331  .ne 2
 332  332  .na
 333  333  \fB\fBPR_MSACCT\fR\fR
 334  334  .ad
 335  335  .RS 13n
 336  336  Set by default in all processes to indicate that microstate accounting is
 337  337  enabled. However, this flag has been deprecated and no longer has any effect.
 338  338  Microstate accounting may not be disabled; however, it is still possible to
 339  339  toggle the flag.
 340  340  .RE
 341  341  
 342  342  .sp
 343  343  .ne 2
 344  344  .na
 345  345  \fB\fBPR_MSFORK\fR\fR
 346  346  .ad
 347  347  .RS 13n
 348  348  Set by default in all processes to indicate that microstate accounting will be
 349  349  enabled for processes that this parent forks(). However, this flag has been
 350  350  deprecated and no longer has any effect. It is possible to toggle this flag;
 351  351  however, it is not possible to disable microstate accounting.
 352  352  .RE
 353  353  
 354  354  .sp
 355  355  .ne 2
 356  356  .na
 357  357  \fB\fBPR_BPTADJ\fR\fR
 358  358  .ad
 359  359  .RS 13n
 360  360  process has its breakpoint adjustment mode set (see \fBPCSET\fR).
 361  361  .RE
 362  362  
 363  363  .sp
 364  364  .ne 2
 365  365  .na
 366  366  \fB\fBPR_PTRACE\fR\fR
 367  367  .ad
 368  368  .RS 13n
 369  369  process has its ptrace-compatibility mode set (see \fBPCSET\fR).
 370  370  .RE
 371  371  
 372  372  .sp
 373  373  .LP
 374  374  \fBpr_nlwp\fR is the total number of active lwps in the process. pr_nzomb is
 375  375  the total number of zombie lwps in the process. A zombie lwp is a non-detached
 376  376  lwp that has terminated but has not been reaped with \fBthr_join\fR(3C) or
 377  377  \fBpthread_join\fR(3C).
 378  378  .sp
 379  379  .LP
 380  380  \fBpr_pid\fR, \fBpr_ppid\fR, \fBpr_pgid\fR, and \fBpr_sid\fR are, respectively,
 381  381  the process ID, the ID of the process's parent, the process's process group ID,
 382  382  and the process's session ID.
 383  383  .sp
 384  384  .LP
 385  385  \fBpr_aslwpid\fR is obsolete and is always zero.
 386  386  .sp
 387  387  .LP
 388  388  \fBpr_agentid\fR is the lwp-ID for the \fB/proc\fR agent lwp (see the
 389  389  \fBPCAGENT\fR control operation). It is zero if there is no agent lwp in the
 390  390  process.
 391  391  .sp
 392  392  .LP
 393  393  \fBpr_sigpend\fR identifies asynchronous signals pending for the process.
 394  394  .sp
 395  395  .LP
 396  396  \fBpr_brkbase\fR is the virtual address of the process heap and
 397  397  \fBpr_brksize\fR is its size in bytes. The address formed by the sum of these
 398  398  values is the process \fBbreak\fR (see \fBbrk\fR(2)). \fBpr_stkbase\fR and
 399  399  \fBpr_stksize\fR are, respectively, the virtual address of the process stack
 400  400  and its size in bytes. (Each lwp runs on a separate stack; the distinguishing
 401  401  characteristic of the process stack is that the operating system will grow it
 402  402  when necessary.)
 403  403  .sp
 404  404  .LP
 405  405  \fBpr_utime\fR, \fBpr_stime\fR, \fBpr_cutime\fR, and \fBpr_cstime\fR are,
 406  406  respectively, the user \fBCPU\fR and system \fBCPU\fR time consumed by the
 407  407  process, and the cumulative user \fBCPU\fR and system \fBCPU\fR time consumed
 408  408  by the process's children, in seconds and nanoseconds.
 409  409  .sp
 410  410  .LP
 411  411  \fBpr_sigtrace\fR and \fBpr_flttrace\fR contain, respectively, the set of
 412  412  signals and the set of hardware faults that are being traced (see
 413  413  \fBPCSTRACE\fR and \fBPCSFAULT\fR).
 414  414  .sp
 415  415  .LP
 416  416  \fBpr_sysentry\fR and \fBpr_sysexit\fR contain, respectively, the sets of
 417  417  system calls being traced on entry and exit (see \fBPCSENTRY\fR and
 418  418  \fBPCSEXIT\fR).
 419  419  .sp
 420  420  .LP
 421  421  \fBpr_dmodel\fR indicates the data model of the process. Possible values are:
 422  422  .sp
 423  423  .ne 2
 424  424  .na
 425  425  \fB\fBPR_MODEL_ILP32\fR\fR
 426  426  .ad
 427  427  .RS 19n
 428  428  process data model is ILP32.
 429  429  .RE
 430  430  
 431  431  .sp
 432  432  .ne 2
 433  433  .na
 434  434  \fB\fBPR_MODEL_LP64\fR\fR
 435  435  .ad
 436  436  .RS 19n
 437  437  process data model is LP64.
 438  438  .RE
 439  439  
 440  440  .sp
 441  441  .ne 2
 442  442  .na
 443  443  \fB\fBPR_MODEL_NATIVE\fR\fR
 444  444  .ad
 445  445  .RS 19n
 446  446  process data model is native.
 447  447  .RE
 448  448  
 449  449  .sp
 450  450  .LP
 451  451  The \fBpr_taskid\fR, \fBpr_projid\fR, and \fBpr_zoneid\fR fields contain
 452  452  respectively, the numeric \fBID\fRs of the task, project, and zone in which the
 453  453  process was running.
 454  454  .sp
 455  455  .LP
 456  456  The constant \fBPR_MODEL_NATIVE\fR reflects the data model of the controlling
 457  457  process, \fIthat is\fR, its value is \fBPR_MODEL_ILP32\fR or
 458  458  \fBPR_MODEL_LP64\fR according to whether the controlling process has been
 459  459  compiled as a 32-bit program or a 64-bit program, respectively.
 460  460  .sp
 461  461  .LP
 462  462  \fBpr_lwp\fR contains the status information for the representative lwp:
 463  463  .sp
 464  464  .in +2
 465  465  .nf
 466  466  typedef struct lwpstatus {
 467  467    int pr_flags;              /* flags (see below) */
 468  468    id_t pr_lwpid;             /* specific lwp identifier */
 469  469    short pr_why;              /* reason for lwp stop, if stopped */
 470  470    short pr_what;             /* more detailed reason */
 471  471    short pr_cursig;           /* current signal, if any */
 472  472    siginfo_t pr_info;         /* info associated with signal or fault */
 473  473    sigset_t pr_lwppend;       /* set of signals pending to the lwp */
 474  474    sigset_t pr_lwphold;       /* set of signals blocked by the lwp */
 475  475    struct sigaction pr_action;/* signal action for current signal */
 476  476    stack_t pr_altstack;       /* alternate signal stack info */
 477  477    uintptr_t pr_oldcontext;   /* address of previous ucontext */
 478  478    short pr_syscall;          /* system call number (if in syscall) */
 479  479    short pr_nsysarg;          /* number of arguments to this syscall */
 480  480    int pr_errno;              /* errno for failed syscall */
 481  481    long pr_sysarg[PRSYSARGS]; /* arguments to this syscall */
 482  482    long pr_rval1;             /* primary syscall return value */
 483  483    long pr_rval2;             /* second syscall return value, if any */
 484  484    char pr_clname[PRCLSZ];    /* scheduling class name */
 485  485    timestruc_t pr_tstamp;     /* real-time time stamp of stop */
 486  486    timestruc_t pr_utime;      /* lwp user cpu time */
 487  487    timestruc_t pr_stime;      /* lwp system cpu time */
 488  488    uintptr_t pr_ustack;       /* stack boundary data (stack_t) address */
 489  489    ulong_t pr_instr;          /* current instruction */
 490  490    prgregset_t pr_reg;        /* general registers */
 491  491    prfpregset_t pr_fpreg;     /* floating-point registers */
 492  492  } lwpstatus_t;
 493  493  .fi
 494  494  .in -2
 495  495  
 496  496  .sp
 497  497  .LP
 498  498  \fBpr_flags\fR is a bit-mask holding the following lwp flags. For convenience,
 499  499  it also contains the process flags, described previously.
 500  500  .sp
 501  501  .ne 2
 502  502  .na
 503  503  \fB\fBPR_STOPPED\fR\fR
 504  504  .ad
 505  505  .RS 14n
 506  506  The lwp is stopped.
 507  507  .RE
 508  508  
 509  509  .sp
 510  510  .ne 2
 511  511  .na
 512  512  \fB\fBPR_ISTOP\fR\fR
 513  513  .ad
 514  514  .RS 14n
 515  515  The lwp is stopped on an event of interest (see \fBPCSTOP\fR).
 516  516  .RE
 517  517  
 518  518  .sp
 519  519  .ne 2
 520  520  .na
 521  521  \fB\fBPR_DSTOP\fR\fR
 522  522  .ad
 523  523  .RS 14n
 524  524  The lwp has a stop directive in effect (see \fBPCSTOP\fR).
 525  525  .RE
 526  526  
 527  527  .sp
 528  528  .ne 2
 529  529  .na
 530  530  \fB\fBPR_STEP\fR\fR
 531  531  .ad
 532  532  .RS 14n
 533  533  The lwp has a single-step directive in effect (see \fBPCRUN\fR).
 534  534  .RE
 535  535  
 536  536  .sp
 537  537  .ne 2
 538  538  .na
 539  539  \fB\fBPR_ASLEEP\fR\fR
 540  540  .ad
 541  541  .RS 14n
 542  542  The lwp is in an interruptible sleep within a system call.
 543  543  .RE
 544  544  
 545  545  .sp
 546  546  .ne 2
 547  547  .na
 548  548  \fB\fBPR_PCINVAL\fR\fR
 549  549  .ad
 550  550  .RS 14n
 551  551  The lwp's current instruction (\fBpr_instr\fR) is undefined.
 552  552  .RE
 553  553  
 554  554  .sp
 555  555  .ne 2
 556  556  .na
 557  557  \fB\fBPR_DETACH\fR\fR
 558  558  .ad
 559  559  .RS 14n
 560  560  This is a detached lwp (see \fBpthread_create\fR(3C) and
 561  561  \fBpthread_join\fR(3C)).
 562  562  .RE
 563  563  
 564  564  .sp
 565  565  .ne 2
 566  566  .na
 567  567  \fB\fBPR_DAEMON\fR\fR
 568  568  .ad
 569  569  .RS 14n
 570  570  This is a daemon lwp (see \fBpthread_create\fR(3C)).
 571  571  .RE
 572  572  
 573  573  .sp
 574  574  .ne 2
 575  575  .na
 576  576  \fB\fBPR_ASLWP\fR\fR
 577  577  .ad
 578  578  .RS 14n
 579  579  This flag is obsolete and is never set.
 580  580  .RE
 581  581  
 582  582  .sp
 583  583  .ne 2
 584  584  .na
 585  585  \fB\fBPR_AGENT\fR\fR
 586  586  .ad
 587  587  .RS 14n
 588  588  This is the \fB/proc\fR agent lwp for the process.
 589  589  .RE
 590  590  
 591  591  .sp
 592  592  .LP
 593  593  \fBpr_lwpid\fR names the specific lwp.
 594  594  .sp
 595  595  .LP
 596  596  \fBpr_why\fR and \fBpr_what\fR together describe, for a stopped lwp, the reason
 597  597  for the stop. Possible values of \fBpr_why\fR and the associated \fBpr_what\fR
 598  598  are:
 599  599  .sp
 600  600  .ne 2
 601  601  .na
 602  602  \fB\fBPR_REQUESTED\fR\fR
 603  603  .ad
 604  604  .RS 17n
 605  605  indicates that the stop occurred in response to a stop directive, normally
 606  606  because \fBPCSTOP\fR was applied or because another lwp stopped on an event of
 607  607  interest and the asynchronous-stop flag (see \fBPCSET\fR) was not set for the
 608  608  process. \fBpr_what\fR is unused in this case.
 609  609  .RE
 610  610  
 611  611  .sp
 612  612  .ne 2
 613  613  .na
 614  614  \fB\fBPR_SIGNALLED\fR\fR
 615  615  .ad
 616  616  .RS 17n
 617  617  indicates that the lwp stopped on receipt of a signal (see \fBPCSTRACE\fR);
 618  618  \fBpr_what\fR holds the signal number that caused the stop (for a newly-stopped
 619  619  lwp, the same value is in \fBpr_cursig\fR).
 620  620  .RE
 621  621  
 622  622  .sp
 623  623  .ne 2
 624  624  .na
 625  625  \fB\fBPR_FAULTED\fR\fR
 626  626  .ad
 627  627  .RS 17n
 628  628  indicates that the lwp stopped on incurring a hardware fault (see
 629  629  \fBPCSFAULT\fR); \fBpr_what\fR holds the fault number that caused the stop.
 630  630  .RE
 631  631  
 632  632  .sp
 633  633  .ne 2
 634  634  .na
 635  635  \fB\fBPR_SYSENTRY\fR\fR
 636  636  .ad
 637  637  .br
 638  638  .na
 639  639  \fB\fBPR_SYSEXIT\fR\fR
 640  640  .ad
 641  641  .RS 17n
 642  642  indicate a stop on entry to or exit from a system call (see \fBPCSENTRY\fR and
 643  643  \fBPCSEXIT\fR); \fBpr_what\fR holds the system call number.
 644  644  .RE
 645  645  
 646  646  .sp
 647  647  .ne 2
 648  648  .na
 649  649  \fB\fBPR_JOBCONTROL\fR\fR
 650  650  .ad
 651  651  .RS 17n
 652  652  indicates that the lwp stopped due to the default action of a job control stop
 653  653  signal (see \fBsigaction\fR(2)); \fBpr_what\fR holds the stopping signal
 654  654  number.
 655  655  .RE
 656  656  
 657  657  .sp
 658  658  .ne 2
 659  659  .na
 660  660  \fB\fBPR_SUSPENDED\fR\fR
 661  661  .ad
 662  662  .RS 17n
 663  663  indicates that the lwp stopped due to internal synchronization of lwps within
 664  664  the process. \fBpr_what\fR is unused in this case.
 665  665  .RE
 666  666  
 667  667  .sp
 668  668  .ne 2
 669  669  .na
 670  670  \fB\fBPR_BRAND\fR\fR
 671  671  .ad
 672  672  .RS 17n
 673  673  indicates that the lwp stopped for a brand-specific reason.  Interpretation
 674  674  of the value of \fBpr_what\fR depends on which zone brand is in use.  It is
 675  675  not generally expected that an lwp stopped in this state will be restarted
 676  676  by native \fBproc\fR(4) consumers.
 677  677  .RE
 678  678  
 679  679  .sp
 680  680  .LP
 681  681  \fBpr_cursig\fR names the current signal, that is, the next signal to be
 682  682  delivered to the lwp, if any. \fBpr_info\fR, when the lwp is in a
 683  683  \fBPR_SIGNALLED\fR or \fBPR_FAULTED\fR stop, contains additional information
 684  684  pertinent to the particular signal or fault (see \fB<sys/siginfo.h>\fR).
 685  685  .sp
 686  686  .LP
 687  687  \fBpr_lwppend\fR identifies any synchronous or directed signals pending for the
 688  688  lwp. \fBpr_lwphold\fR identifies those signals whose delivery is being blocked
 689  689  by the lwp (the signal mask).
 690  690  .sp
 691  691  .LP
 692  692  \fBpr_action\fR contains the signal action information pertaining to the
 693  693  current signal (see \fBsigaction\fR(2)); it is undefined if \fBpr_cursig\fR is
 694  694  zero. \fBpr_altstack\fR contains the alternate signal stack information for the
 695  695  lwp (see \fBsigaltstack\fR(2)).
 696  696  .sp
 697  697  .LP
 698  698  \fBpr_oldcontext\fR, if not zero, contains the address on the lwp stack of a
 699  699  \fBucontext\fR structure describing the previous user-level context (see
 700  700  \fBucontext.h\fR(3HEAD)). It is non-zero only if the lwp is executing in the
 701  701  context of a signal handler.
 702  702  .sp
 703  703  .LP
 704  704  \fBpr_syscall\fR is the number of the system call, if any, being executed by
 705  705  the lwp; it is non-zero if and only if the lwp is stopped on \fBPR_SYSENTRY\fR
 706  706  or \fBPR_SYSEXIT\fR, or is asleep within a system call ( \fBPR_ASLEEP\fR is
 707  707  set). If \fBpr_syscall\fR is non-zero, \fBpr_nsysarg\fR is the number of
 708  708  arguments to the system call and \fBpr_sysarg\fR contains the actual arguments.
 709  709  .sp
 710  710  .LP
 711  711  \fBpr_rval1\fR, \fBpr_rval2\fR, and \fBpr_errno\fR are defined only if the lwp
 712  712  is stopped on \fBPR_SYSEXIT\fR or if the \fBPR_VFORKP\fR flag is set. If
 713  713  \fBpr_errno\fR is zero, \fBpr_rval1\fR and \fBpr_rval2\fR contain the return
 714  714  values from the system call. Otherwise, \fBpr_errno\fR contains the error
 715  715  number for the failing system call (see \fB<sys/errno.h>\fR).
 716  716  .sp
 717  717  .LP
 718  718  \fBpr_clname\fR contains the name of the lwp's scheduling class.
 719  719  .sp
 720  720  .LP
 721  721  \fBpr_tstamp\fR, if the lwp is stopped, contains a time stamp marking when the
 722  722  lwp stopped, in real time seconds and nanoseconds since an arbitrary time in
 723  723  the past.
 724  724  .sp
 725  725  .LP
 726  726  \fBpr_utime\fR is the amount of user level CPU time used by this LWP.
 727  727  .sp
 728  728  .LP
 729  729  \fBpr_stime\fR is the amount of system level CPU time used by this LWP.
 730  730  .sp
 731  731  .LP
 732  732  \fBpr_ustack\fR is the virtual address of the \fBstack_t\fR that contains the
 733  733  stack boundaries for this LWP. See \fBgetustack\fR(2) and
 734  734  \fB_stack_grow\fR(3C).
 735  735  .sp
 736  736  .LP
 737  737  \fBpr_instr\fR contains the machine instruction to which the lwp's program
 738  738  counter refers. The amount of data retrieved from the process is
 739  739  machine-dependent. On SPARC based machines, it is a 32-bit word. On x86-based
 740  740  machines, it is a single byte. In general, the size is that of the machine's
 741  741  smallest instruction. If \fBPR_PCINVAL\fR is set, \fBpr_instr\fR is undefined;
 742  742  this occurs whenever the lwp is not stopped or when the program counter refers
 743  743  to an invalid virtual address.
 744  744  .sp
 745  745  .LP
 746  746  \fBpr_reg\fR is an array holding the contents of a stopped lwp's general
 747  747  registers.
 748  748  .sp
 749  749  .ne 2
 750  750  .na
 751  751  \fBSPARC\fR
 752  752  .ad
 753  753  .RS 21n
 754  754  On SPARC-based machines, the predefined constants \fBR_G0\fR ... \fBR_G7\fR,
 755  755  \fBR_O0\fR ... \fBR_O7\fR, \fBR_L0\fR ... \fBR_L7\fR, \fBR_I0\fR ...
 756  756  \fBR_I7\fR, \fBR_PC\fR, \fBR_nPC\fR, and \fBR_Y\fR can be used as indices to
 757  757  refer to the corresponding registers; previous register windows can be read
 758  758  from their overflow locations on the stack (however, see the \fBgwindows\fR
 759  759  file in the \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR subdirectory).
 760  760  .RE
 761  761  
 762  762  .sp
 763  763  .ne 2
 764  764  .na
 765  765  \fBSPARC V8 (32-bit)\fR
 766  766  .ad
 767  767  .RS 21n
 768  768  For SPARC V8 (32-bit) controlling processes, the predefined constants
 769  769  \fBR_PSR\fR, \fBR_WIM\fR, and \fBR_TBR\fR can be used as indices to refer to
 770  770  the corresponding special registers. For SPARC V9 (64-bit) controlling
 771  771  processes, the predefined constants \fBR_CCR\fR, \fBR_ASI\fR, and \fBR_FPRS\fR
 772  772  can be used as indices to refer to the corresponding special registers.
 773  773  .RE
 774  774  
 775  775  .sp
 776  776  .ne 2
 777  777  .na
 778  778  \fBx86 (32-bit)\fR
 779  779  .ad
 780  780  .RS 21n
 781  781  For 32-bit x86 processes, the predefined constants listed belowcan be used as
 782  782  indices to refer to the corresponding registers.
 783  783  .sp
 784  784  .in +2
 785  785  .nf
 786  786  SS
 787  787  UESP
 788  788  EFL
 789  789  CS
 790  790  EIP
 791  791  ERR
 792  792  TRAPNO
 793  793  EAX
 794  794  ECX
 795  795  EDX
 796  796  EBX
 797  797  ESP
 798  798  EBP
 799  799  ESI
 800  800  EDI
 801  801  DS
 802  802  ES
 803  803  GS
 804  804  .fi
 805  805  .in -2
 806  806  
 807  807  The preceding constants are listed in \fB<sys/regset.h>\fR\&.
 808  808  .sp
 809  809  Note that a 32-bit process can run on an x86 64-bit system, using the constants
 810  810  listed above.
 811  811  .RE
 812  812  
 813  813  .sp
 814  814  .ne 2
 815  815  .na
 816  816  \fBx86 (64-bit)\fR
 817  817  .ad
 818  818  .RS 21n
 819  819  To read the registers of a 32- \fBor\fR a 64-bit process, a 64-bit x86 process
 820  820  should use the predefined constants listed below.
 821  821  .sp
 822  822  .in +2
 823  823  .nf
 824  824  REG_GSBASE
 825  825  REG_FSBASE
 826  826  REG_DS
 827  827  REG_ES
 828  828  REG_GS
 829  829  REG_FS
 830  830  REG_SS
 831  831  REG_RSP
 832  832  REG_RFL
 833  833  REG_CS
 834  834  REG_RIP
 835  835  REG_ERR
 836  836  REG_TRAPNO
 837  837  REG_RAX
 838  838  REG_RCX
 839  839  REG_RDX
 840  840  REG_RBX
 841  841  REG_RBP
 842  842  REG_RSI
 843  843  REG_RDI
 844  844  REG_R8
 845  845  REG_R9
 846  846  REG_R10
 847  847  REG_R11
 848  848  REG_R12
 849  849  REG_R13
 850  850  REG_R14
 851  851  REG_R15
 852  852  .fi
 853  853  .in -2
 854  854  
 855  855  The preceding constants are listed in \fB<sys/regset.h>\fR\&.
 856  856  .RE
 857  857  
 858  858  .sp
 859  859  .LP
 860  860  \fBpr_fpreg\fR is a structure holding the contents of the floating-point
 861  861  registers.
 862  862  .sp
 863  863  .LP
 864  864  SPARC registers, both general and floating-point, as seen by a 64-bit
 865  865  controlling process are the V9 versions of the registers, even if the target
 866  866  process is a 32-bit (V8) process. V8 registers are a subset of the V9
 867  867  registers.
 868  868  .sp
 869  869  .LP
 870  870  If the lwp is not stopped, all register values are undefined.
 871  871  .SS "psinfo"
 872  872  .LP
 873  873  Contains miscellaneous information about the process and the representative lwp
 874  874  needed by the \fBps\fR(1) command. \fBpsinfo\fR remains accessible after a
 875  875  process becomes a \fIzombie\fR. The file contains a \fBpsinfo\fR structure
 876  876  which contains an embedded \fBlwpsinfo\fR structure for the representative lwp,
 877  877  as follows:
 878  878  .sp
 879  879  .in +2
 880  880  .nf
 881  881  typedef struct psinfo {
 882  882      int pr_flag;             /* process flags (DEPRECATED: see below) */
 883  883      int pr_nlwp;             /* number of active lwps in the process */
 884  884      int pr_nzomb;            /* number of zombie lwps in the process */
 885  885      pid_t pr_pid;            /* process id */
 886  886      pid_t pr_ppid;           /* process id of parent */
 887  887      pid_t pr_pgid;           /* process id of process group leader */
 888  888      pid_t pr_sid;            /* session id */
 889  889      uid_t pr_uid;            /* real user id */
 890  890      uid_t pr_euid;           /* effective user id */
 891  891      gid_t pr_gid;            /* real group id */
 892  892      gid_t pr_egid;           /* effective group id */
 893  893      uintptr_t pr_addr;       /* address of process */
 894  894      size_t pr_size;          /* size of process image in Kbytes */
 895  895      size_t pr_rssize;        /* resident set size in Kbytes */
 896  896      dev_t pr_ttydev;         /* controlling tty device (or PRNODEV) */
 897  897      ushort_t pr_pctcpu;      /* % of recent cpu time used by all lwps */
 898  898      ushort_t pr_pctmem;      /* % of system memory used by process */
 899  899      timestruc_t pr_start;    /* process start time, from the epoch */
 900  900      timestruc_t pr_time;     /* cpu time for this process */
 901  901      timestruc_t pr_ctime;    /* cpu time for reaped children */
 902  902      char pr_fname[PRFNSZ];   /* name of exec'ed file */
 903  903      char pr_psargs[PRARGSZ]; /* initial characters of arg list */
 904  904      int pr_wstat;            /* if zombie, the wait() status */
 905  905      int pr_argc;             /* initial argument count */
 906  906      uintptr_t pr_argv;       /* address of initial argument vector */
 907  907      uintptr_t pr_envp;       /* address of initial environment vector */
 908  908      char pr_dmodel;          /* data model of the process */
 909  909      lwpsinfo_t pr_lwp;       /* information for representative lwp */
 910  910      taskid_t pr_taskid;      /* task id */
 911  911      projid_t pr_projid;      /* project id */
 912  912      poolid_t pr_poolid;      /* pool id */
 913  913      zoneid_t pr_zoneid;      /* zone id */
 914  914      ctid_t pr_contract;      /* process contract id */
 915  915  } psinfo_t;
 916  916  .fi
 917  917  .in -2
 918  918  
 919  919  .sp
 920  920  .LP
 921  921  Some of the entries in \fBpsinfo\fR, such as \fBpr_addr\fR, refer to internal
 922  922  kernel data structures and should not be expected to retain their meanings
 923  923  across different versions of the operating system.
 924  924  .sp
 925  925  .LP
 926  926  \fBpsinfo_t.pr_flag\fR is a deprecated interface that should no longer be used.
 927  927  Applications currently relying on the \fBSSYS\fR bit in \fBpr_flag\fR should
 928  928  migrate to checking \fBPR_ISSYS\fR in the \fBpstatus\fR structure's
 929  929  \fBpr_flags\fR field.
 930  930  .sp
 931  931  .LP
 932  932  \fBpr_pctcpu\fR and \fBpr_pctmem\fR are 16-bit binary fractions in the range
 933  933  0.0 to 1.0 with the binary point to the right of the high-order bit (1.0 ==
 934  934  0x8000). \fBpr_pctcpu\fR is the summation over all lwps in the process.
 935  935  .sp
 936  936  .LP
 937  937  The \fBpr_fname\fR and \fBpr_psargs\fR are writable by the owner of the
 938  938  process. To write to them, the \fBpsinfo\fR file should be open for writing
 939  939  and the desired value for the field should be written at the file offset
 940  940  that corresponds to the member of structure.  No other entry may be written
 941  941  to; if a write is attempted to an offset that does not represent one of
 942  942  these two memers, or if the size of the write is not exactly the size of
 943  943  the member being written, no bytes will be written and zero will be returned.
 944  944  .sp
 945  945  .LP
 946  946  \fBpr_lwp\fR contains the \fBps\fR(1) information for the representative lwp.
 947  947  If the process is a \fIzombie\fR, \fBpr_nlwp\fR, \fBpr_nzomb\fR, and
 948  948  \fBpr_lwp.pr_lwpid\fR are zero and the other fields of \fBpr_lwp\fR are
 949  949  undefined:
 950  950  .sp
 951  951  .in +2
 952  952  .nf
 953  953  typedef struct lwpsinfo {
 954  954      int pr_flag;             /* lwp flags (DEPRECATED: see below) */
 955  955      id_t pr_lwpid;           /* lwp id */
 956  956      uintptr_t pr_addr;       /* internal address of lwp */
 957  957      uintptr_t pr_wchan;      /* wait addr for sleeping lwp */
 958  958      char pr_stype;           /* synchronization event type */
 959  959      char pr_state;           /* numeric lwp state */
 960  960      char pr_sname;           /* printable character for pr_state */
 961  961      char pr_nice;            /* nice for cpu usage */
 962  962      short pr_syscall;        /* system call number (if in syscall) */
 963  963      char pr_oldpri;          /* pre-SVR4, low value is high priority */
 964  964      char pr_cpu;             /* pre-SVR4, cpu usage for scheduling */
 965  965      int pr_pri;              /* priority, high value = high priority */
 966  966      ushort_t pr_pctcpu;      /* % of recent cpu time used by this lwp */
 967  967      timestruc_t pr_start;    /* lwp start time, from the epoch */
 968  968      timestruc_t pr_time;     /* cpu time for this lwp */
 969  969      char pr_clname[PRCLSZ];  /* scheduling class name */
 970  970      char pr_name[PRFNSZ];    /* name of system lwp */
 971  971      processorid_t pr_onpro;  /* processor which last ran this lwp */
 972  972      processorid_t pr_bindpro;/* processor to which lwp is bound */
 973  973      psetid_t pr_bindpset;    /* processor set to which lwp is bound */
 974  974      lgrp_id_t pr_lgrp         /* home lgroup */
 975  975  } lwpsinfo_t;
 976  976  .fi
 977  977  .in -2
 978  978  
 979  979  .sp
 980  980  .LP
 981  981  Some of the entries in \fBlwpsinfo\fR, such as \fBpr_addr\fR, \fBpr_wchan\fR,
 982  982  \fBpr_stype\fR, \fBpr_state\fR, and \fBpr_name\fR, refer to internal kernel
 983  983  data structures and should not be expected to retain their meanings across
 984  984  different versions of the operating system.
 985  985  .sp
 986  986  .LP
 987  987  \fBlwpsinfo_t.pr_flag\fR is a deprecated interface that should no longer be
 988  988  used.
 989  989  .sp
 990  990  .LP
 991  991  \fBpr_pctcpu\fR is a 16-bit binary fraction, as described above. It represents
 992  992  the \fBCPU\fR time used by the specific lwp. On a multi-processor machine, the
 993  993  maximum value is 1/N, where N is the number of \fBCPU\fRs.
 994  994  .sp
 995  995  .LP
 996  996  \fBpr_contract\fR is the id of the process contract of which the process is a
 997  997  member. See \fBcontract\fR(4) and \fBprocess\fR(4).
 998  998  .SS "cred"
 999  999  .LP
1000 1000  Contains a description of the credentials associated with the process:
1001 1001  .sp
1002 1002  .in +2
1003 1003  .nf
1004 1004  typedef struct prcred {
1005 1005          uid_t pr_euid;      /* effective user id */
1006 1006          uid_t pr_ruid;      /* real user id */
1007 1007          uid_t pr_suid;      /* saved user id (from exec) */
1008 1008          gid_t pr_egid;      /* effective group id */
1009 1009          gid_t pr_rgid;      /* real group id */
1010 1010          gid_t pr_sgid;      /* saved group id (from exec) */
1011 1011          int pr_ngroups;     /* number of supplementary groups */
1012 1012          gid_t pr_groups[1]; /* array of supplementary groups */
1013 1013  } prcred_t;
1014 1014  .fi
1015 1015  .in -2
1016 1016  .sp
1017 1017  
1018 1018  .sp
1019 1019  .LP
1020 1020  The array of associated supplementary groups in \fBpr_groups\fR is of variable
1021 1021  length; the \fBcred\fR file contains all of the supplementary groups.
1022 1022  \fBpr_ngroups\fR indicates the number of supplementary groups. (See also the
1023 1023  \fBPCSCRED\fR and \fBPCSCREDX\fR control operations.)
1024 1024  .SS "priv"
1025 1025  .LP
1026 1026  Contains a description of the privileges associated with the process:
1027 1027  .sp
1028 1028  .in +2
1029 1029  .nf
1030 1030  typedef struct prpriv {
1031 1031       uint32_t        pr_nsets;      /* number of privilege set */
1032 1032       uint32_t        pr_setsize;    /* size of privilege set */
1033 1033       uint32_t        pr_infosize;   /* size of supplementary data */
1034 1034       priv_chunk_t    pr_sets[1];    /* array of sets */
1035 1035  } prpriv_t;
1036 1036  .fi
1037 1037  .in -2
1038 1038  
1039 1039  .sp
1040 1040  .LP
1041 1041  The actual dimension of the \fBpr_sets\fR[] field is
1042 1042  .sp
1043 1043  .in +2
1044 1044  .nf
1045 1045  pr_sets[pr_nsets][pr_setsize]
1046 1046  .fi
1047 1047  .in -2
1048 1048  
1049 1049  .sp
1050 1050  .LP
1051 1051  which is followed by additional information about the process state
1052 1052  \fBpr_infosize\fR bytes in size.
1053 1053  .sp
1054 1054  .LP
1055 1055  The full size of the structure can be computed using
1056 1056  \fBPRIV_PRPRIV_SIZE\fR(\fBprpriv_t *\fR).
1057 1057  .SS "sigact"
1058 1058  .LP
1059 1059  Contains an array of \fBsigaction structures\fR describing the current
1060 1060  dispositions of all signals associated with the traced process (see
1061 1061  \fBsigaction\fR(2)). Signal numbers are displaced by 1 from array indices, so
1062 1062  that the action for signal number \fIn\fR appears in position \fIn\fR-1 of the
1063 1063  array.
1064 1064  .SS "auxv"
1065 1065  .LP
1066 1066  Contains the initial values of the process's aux vector in an array of
1067 1067  \fBauxv_t\fR structures (see \fB<sys/auxv.h>\fR). The values are those that
1068 1068  were passed by the operating system as startup information to the dynamic
1069 1069  linker.
1070 1070  .SS "argv"
1071 1071  .LP
1072 1072  Contains the concatenation of each of the argument strings, including their
1073 1073  \fBNUL\fR terminators, in the argument vector (\fBargv\fR) for the process. If
1074 1074  the process has modified either its argument vector, or the contents of any of
1075 1075  the strings referenced by that vector, those changes will be visible here.
1076 1076  .SS "ldt"
1077 1077  .LP
1078 1078  This file exists only on x86-based machines. It is non-empty only if the
1079 1079  process has established a local descriptor table (\fBLDT\fR). If non-empty, the
1080 1080  file contains the array of currently active \fBLDT\fR entries in an array of
1081 1081  elements of type \fBstruct ssd\fR, defined in \fB<sys/sysi86.h>\fR, one element
1082 1082  for each active \fBLDT\fR entry.
1083 1083  .SS "map, xmap"
1084 1084  .LP
1085 1085  Contain information about the virtual address map of the process. The map file
1086 1086  contains an array of \fBprmap\fR structures while the xmap file contains an
1087 1087  array of \fBprxmap\fR structures. Each structure describes a contiguous virtual
1088 1088  address region in the address space of the traced process:
1089 1089  .sp
1090 1090  .in +2
1091 1091  .nf
1092 1092  typedef struct prmap {
1093 1093          uintptr_tpr_vaddr;         /* virtual address of mapping */
1094 1094          size_t pr_size;            /* size of mapping in bytes */
1095 1095          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1096 1096          offset_t pr_offset;        /* offset into mapped object, if any */
1097 1097          int pr_mflags;             /* protection and attribute flags */
1098 1098          int pr_pagesize;           /* pagesize for this mapping in bytes */
1099 1099          int pr_shmid;              /* SysV shared memory identifier */
1100 1100  } prmap_t;
1101 1101  .fi
1102 1102  .in -2
1103 1103  .sp
1104 1104  
1105 1105  .sp
1106 1106  .in +2
1107 1107  .nf
1108 1108  typedef struct prxmap {
1109 1109          uintptr_t pr_vaddr;        /* virtual address of mapping */
1110 1110          size_t pr_size;            /* size of mapping in bytes */
1111 1111          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1112 1112          offset_t pr_offset;        /* offset into mapped object, if any */
1113 1113          int pr_mflags;             /* protection and attribute flags */
1114 1114          int pr_pagesize;           /* pagesize for this mapping in bytes */
1115 1115          int pr_shmid;              /* SysV shared memory identifier */
1116 1116          dev_t pr_dev;              /* device of mapped object, if any */
1117 1117          uint64_t pr_ino;           /* inode of mapped object, if any */
1118 1118          size_t pr_rss;             /* pages of resident memory */
1119 1119          size_t pr_anon;            /* pages of resident anonymous memory */
1120 1120          size_t pr_locked;          /* pages of locked memory */
1121 1121          uint64_t pr_hatpagesize;   /* pagesize of mapping */
1122 1122  } prxmap_t;
1123 1123  .fi
1124 1124  .in -2
1125 1125  .sp
1126 1126  
1127 1127  .sp
1128 1128  .LP
1129 1129  \fBpr_vaddr\fR is the virtual address of the mapping within the traced process
1130 1130  and \fBpr_size\fR is its size in bytes. \fBpr_mapname\fR, if it does not
1131 1131  contain a null string, contains the name of a file in the \fBobject\fR
1132 1132  directory (see below) that can be opened read-only to obtain a file descriptor
1133 1133  for the mapped file associated with the mapping. This enables a debugger to
1134 1134  find object file symbol tables without having to know the real path names of
1135 1135  the executable file and shared libraries of the process. \fBpr_offset\fR is the
1136 1136  64-bit offset within the mapped file (if any) to which the virtual address is
1137 1137  mapped.
1138 1138  .sp
1139 1139  .LP
1140 1140  \fBpr_mflags\fR is a bit-mask of protection and attribute flags:
1141 1141  .sp
1142 1142  .ne 2
1143 1143  .na
1144 1144  \fB\fBMA_READ\fR\fR
1145 1145  .ad
1146 1146  .RS 17n
1147 1147  mapping is readable by the traced process.
1148 1148  .RE
1149 1149  
1150 1150  .sp
1151 1151  .ne 2
1152 1152  .na
1153 1153  \fB\fBMA_WRITE\fR\fR
1154 1154  .ad
1155 1155  .RS 17n
1156 1156  mapping is writable by the traced process.
1157 1157  .RE
1158 1158  
1159 1159  .sp
1160 1160  .ne 2
1161 1161  .na
1162 1162  \fB\fBMA_EXEC\fR\fR
1163 1163  .ad
1164 1164  .RS 17n
1165 1165  mapping is executable by the traced process.
1166 1166  .RE
1167 1167  
1168 1168  .sp
1169 1169  .ne 2
1170 1170  .na
1171 1171  \fB\fBMA_SHARED\fR\fR
1172 1172  .ad
1173 1173  .RS 17n
1174 1174  mapping changes are shared by the mapped object.
1175 1175  .RE
1176 1176  
1177 1177  .sp
1178 1178  .ne 2
1179 1179  .na
1180 1180  \fB\fBMA_ISM\fR\fR
1181 1181  .ad
1182 1182  .RS 17n
1183 1183  mapping is intimate shared memory (shared MMU resources)
1184 1184  .RE
1185 1185  
1186 1186  .sp
1187 1187  .ne 2
1188 1188  .na
1189 1189  \fB\fBMAP_NORESERVE\fR\fR
1190 1190  .ad
1191 1191  .RS 17n
1192 1192  mapping does not have swap space reserved (mapped with MAP_NORESERVE)
1193 1193  .RE
1194 1194  
1195 1195  .sp
1196 1196  .ne 2
1197 1197  .na
1198 1198  \fB\fBMA_SHM\fR\fR
1199 1199  .ad
1200 1200  .RS 17n
1201 1201  mapping System V shared memory
1202 1202  .RE
1203 1203  
1204 1204  .sp
1205 1205  .LP
1206 1206  A contiguous area of the address space having the same underlying mapped object
1207 1207  may appear as multiple mappings due to varying read, write, and execute
1208 1208  attributes. The underlying mapped object does not change over the range of a
1209 1209  single mapping. An \fBI/O\fR operation to a mapping marked \fBMA_SHARED\fR
1210 1210  fails if applied at a virtual address not corresponding to a valid page in the
1211 1211  underlying mapped object. A write to a \fBMA_SHARED\fR mapping that is not
1212 1212  marked \fBMA_WRITE\fR fails. Reads and writes to private mappings always
1213 1213  succeed. Reads and writes to unmapped addresses fail.
1214 1214  .sp
1215 1215  .LP
1216 1216  \fBpr_pagesize\fR is the page size for the mapping, currently always the system
1217 1217  pagesize.
1218 1218  .sp
1219 1219  .LP
1220 1220  \fBpr_shmid\fR is the shared memory identifier, if any, for the mapping. Its
1221 1221  value is \fB\(mi1\fR if the mapping is not System V shared memory. See
1222 1222  \fBshmget\fR(2).
1223 1223  .sp
1224 1224  .LP
1225 1225  \fBpr_dev\fR is the device of the mapped object, if any, for the mapping. Its
1226 1226  value is \fBPRNODEV\fR (-1) if the mapping does not have a device.
1227 1227  .sp
1228 1228  .LP
1229 1229  \fBpr_ino\fR is the inode of the mapped object, if any, for the mapping. Its
1230 1230  contents are only valid if \fBpr_dev\fR is not \fBPRNODEV.\fR
1231 1231  .sp
1232 1232  .LP
1233 1233  \fBpr_rss\fR is the number of resident pages of memory for the mapping. The
1234 1234  number of resident bytes for the mapping may be determined by multiplying
1235 1235  \fBpr_rss\fR by the page size given by \fBpr_pagesize.\fR
1236 1236  .sp
1237 1237  .LP
1238 1238  \fBpr_anon\fR is the number of resident anonymous memory pages (pages which are
1239 1239  private to this process) for the mapping.
1240 1240  .sp
1241 1241  .LP
1242 1242  \fBpr_locked\fR is the number of locked pages for the mapping. Pages which are
1243 1243  locked are always resident in memory.
1244 1244  .sp
1245 1245  .LP
1246 1246  \fBpr_hatpagesize\fR is the size, in bytes, of the \fBHAT\fR (\fBMMU\fR)
1247 1247  translation for the mapping. \fBpr_hatpagesize\fR may be different than
1248 1248  \fBpr_pagesize.\fR The possible values are hardware architecture specific, and
1249 1249  may change over a mapping's lifetime.
1250 1250  .SS "rmap"
1251 1251  .LP
1252 1252  Contains information about the reserved address ranges of the process. The file
1253 1253  contains an array of \fBprmap\fR structures, as defined above for the \fBmap\fR
1254 1254  file. Each structure describes a contiguous virtual address region in the
1255 1255  address space of the traced process that is reserved by the system in the sense
1256 1256  that an \fBmmap\fR(2) system call that does not specify \fBMAP_FIXED\fR will
1257 1257  not use any part of it for the new mapping. Examples of such reservations
1258 1258  include the address ranges reserved for the process stack and the individual
1259 1259  thread stacks of a multi-threaded process.
1260 1260  .SS "cwd"
1261 1261  .LP
1262 1262  A symbolic link to the process's current working directory. See \fBchdir\fR(2).
1263 1263  A \fBreadlink\fR(2) of \fB/proc/\fIpid\fR/cwd\fR yields a null string. However,
1264 1264  it can be opened, listed, and searched as a directory, and can be the target of
1265 1265  \fBchdir\fR(2).
1266 1266  .SS "root"
1267 1267  .LP
1268 1268  A symbolic link to the process's root directory.
1269 1269  \fB/proc/\fR\fIpid\fR\fB/root\fR can differ from the system root directory if
1270 1270  the process or one of its ancestors executed \fBchroot\fR(2) as super user. It
1271 1271  has the same semantics as \fB/proc/\fR\fIpid\fR\fB/cwd\fR.
1272 1272  .SS "fd"
1273 1273  .LP
1274 1274  A directory containing references to the open files of the process. Each entry
1275 1275  is a decimal number corresponding to an open file descriptor in the process.
1276 1276  .sp
1277 1277  .LP
1278 1278  If an entry refers to a regular file, it can be opened with normal file system
1279 1279  semantics but, to ensure that the controlling process cannot gain greater
1280 1280  access than the controlled process, with no file access modes other than its
1281 1281  read/write open modes in the controlled process. If an entry refers to a
1282 1282  directory, it can be accessed with the same semantics as
1283 1283  \fB/proc/\fIpid\fR/cwd\fR. An attempt to open any other type of entry fails
1284 1284  with \fBEACCES\fR.
1285 1285  .SS "object"
1286 1286  .LP
1287 1287  A directory containing read-only files with names corresponding to the
1288 1288  \fBpr_mapname\fR entries in the \fBmap\fR and \fBpagedata\fR files. Opening
1289 1289  such a file yields a file descriptor for the underlying mapped file associated
1290 1290  with an address-space mapping in the process. The file name \fBa.out\fR appears
1291 1291  in the directory as an alias for the process's executable file.
1292 1292  .sp
1293 1293  .LP
1294 1294  The \fBobject\fR directory makes it possible for a controlling process to gain
1295 1295  access to the object file and any shared libraries (and consequently the symbol
1296 1296  tables) without having to know the actual path names of the executable files.
1297 1297  .SS "path"
1298 1298  .LP
1299 1299  A directory containing symbolic links to files opened by the process. The
1300 1300  directory includes one entry for \fBcwd\fR and \fBroot\fR. The directory also
1301 1301  contains a numerical entry for each file descriptor in the \fBfd\fR directory,
1302 1302  and entries matching those in the \fBobject\fR directory. If this information
1303 1303  is not available, any attempt to read the contents of the symbolic link will
1304 1304  fail. This is most common for files that do not exist in the filesystem
1305 1305  namespace (such as \fBFIFO\fRs and sockets), but can also happen for regular
1306 1306  files. For the file descriptor entries, the path may be different from the one
1307 1307  used by the process to open the file.
1308 1308  .SS "pagedata"
1309 1309  .LP
1310 1310  Opening the page data file enables tracking of address space references and
1311 1311  modifications on a per-page basis.
1312 1312  .sp
1313 1313  .LP
1314 1314  A \fBread\fR(2) of the page data file descriptor returns structured page data
1315 1315  and atomically clears the page data maintained for the file by the system. That
1316 1316  is to say, each read returns data collected since the last read; the first read
1317 1317  returns data collected since the file was opened. When the call completes, the
1318 1318  read buffer contains the following structure as its header and thereafter
1319 1319  contains a number of section header structures and associated byte arrays that
1320 1320  must be accessed by walking linearly through the buffer.
1321 1321  .sp
1322 1322  .in +2
1323 1323  .nf
1324 1324  typedef struct prpageheader {
1325 1325      timestruc_t pr_tstamp; /* real time stamp, time of read() */
1326 1326      ulong_t pr_nmap;       /* number of address space mappings */
1327 1327      ulong_t pr_npage;      /* total number of pages */
1328 1328  } prpageheader_t;
1329 1329  .fi
1330 1330  .in -2
1331 1331  
1332 1332  .sp
1333 1333  .LP
1334 1334  The header is followed by \fBpr_nmap prasmap\fR structures and associated data
1335 1335  arrays. The \fBprasmap\fR structure contains the following elements:
1336 1336  .sp
1337 1337  .in +2
1338 1338  .nf
1339 1339  typedef struct prasmap {
1340 1340      uintptr_t pr_vaddr;        /* virtual address of mapping */
1341 1341      ulong_t pr_npage;          /* number of pages in mapping */
1342 1342      char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1343 1343      offset_t pr_offset;        /* offset into mapped object, if any */
1344 1344      int pr_mflags;             /* protection and attribute flags */
1345 1345      int pr_pagesize;           /* pagesize for this mapping in bytes */
1346 1346      int pr_shmid;              /* SysV shared memory identifier */
1347 1347  } prasmap_t;
1348 1348  .fi
1349 1349  .in -2
1350 1350  
1351 1351  .sp
1352 1352  .LP
1353 1353  Each section header is followed by \fBpr_npage\fR bytes, one byte for each page
1354 1354  in the mapping, plus 0-7 null bytes at the end so that the next \fBprasmap\fR
1355 1355  structure begins on an eight-byte aligned boundary. Each data byte may contain
1356 1356  these flags:
1357 1357  .sp
1358 1358  .ne 2
1359 1359  .na
1360 1360  \fB\fBPG_REFERENCED\fR\fR
1361 1361  .ad
1362 1362  .RS 17n
1363 1363  page has been referenced.
1364 1364  .RE
1365 1365  
1366 1366  .sp
1367 1367  .ne 2
1368 1368  .na
1369 1369  \fB\fBPG_MODIFIED\fR\fR
1370 1370  .ad
1371 1371  .RS 17n
1372 1372  page has been modified.
1373 1373  .RE
1374 1374  
1375 1375  .sp
1376 1376  .LP
1377 1377  If the read buffer is not large enough to contain all of the page data, the
1378 1378  read fails with \fBE2BIG\fR and the page data is not cleared. The required size
1379 1379  of the read buffer can be determined through \fBfstat\fR(2). Application of
1380 1380  \fBlseek\fR(2) to the page data file descriptor is ineffective; every read
1381 1381  starts from the beginning of the file. Closing the page data file descriptor
1382 1382  terminates the system overhead associated with collecting the data.
1383 1383  .sp
1384 1384  .LP
1385 1385  More than one page data file descriptor for the same process can be opened, up
1386 1386  to a system-imposed limit per traced process. A read of one does not affect the
1387 1387  data being collected by the system for the others. An open of the page data
1388 1388  file will fail with \fBENOMEM\fR if the system-imposed limit would be exceeded.
1389 1389  .SS "watch"
1390 1390  .LP
1391 1391  Contains an array of \fBprwatch\fR structures, one for each watched area
1392 1392  established by the \fBPCWATCH\fR control operation. See \fBPCWATCH\fR for
1393 1393  details.
1394 1394  .SS "usage"
1395 1395  .LP
1396 1396  Contains process usage information described by a \fBprusage\fR structure which
1397 1397  contains at least the following fields:
1398 1398  .sp
1399 1399  .in +2
1400 1400  .nf
1401 1401  typedef struct prusage {
1402 1402      id_t pr_lwpid;           /* lwp id.  0: process or defunct */
1403 1403      int pr_count;            /* number of contributing lwps */
1404 1404      timestruc_t pr_tstamp;   /* real time stamp, time of read() */
1405 1405      timestruc_t pr_create;   /* process/lwp creation time stamp */
1406 1406      timestruc_t pr_term;     /* process/lwp termination time stamp */
1407 1407      timestruc_t pr_rtime;    /* total lwp real (elapsed) time */
1408 1408      timestruc_t pr_utime;    /* user level CPU time */
1409 1409      timestruc_t pr_stime;    /* system call CPU time */
1410 1410      timestruc_t pr_ttime;    /* other system trap CPU time */
1411 1411      timestruc_t pr_tftime;   /* text page fault sleep time */
1412 1412      timestruc_t pr_dftime;   /* data page fault sleep time */
1413 1413      timestruc_t pr_kftime;   /* kernel page fault sleep time */
1414 1414      timestruc_t pr_ltime;    /* user lock wait sleep time */
1415 1415      timestruc_t pr_slptime;  /* all other sleep time */
1416 1416      timestruc_t pr_wtime;    /* wait-cpu (latency) time */
1417 1417      timestruc_t pr_stoptime; /* stopped time */
1418 1418      ulong_t pr_minf;         /* minor page faults */
1419 1419      ulong_t pr_majf;         /* major page faults */
1420 1420      ulong_t pr_nswap;        /* swaps */
1421 1421      ulong_t pr_inblk;        /* input blocks */
1422 1422      ulong_t pr_oublk;        /* output blocks */
1423 1423      ulong_t pr_msnd;         /* messages sent */
1424 1424      ulong_t pr_mrcv;         /* messages received */
1425 1425      ulong_t pr_sigs;         /* signals received */
1426 1426      ulong_t pr_vctx;         /* voluntary context switches */
1427 1427      ulong_t pr_ictx;         /* involuntary context switches */
1428 1428      ulong_t pr_sysc;         /* system calls */
1429 1429      ulong_t pr_ioch;         /* chars read and written */
1430 1430  } prusage_t;
1431 1431  .fi
1432 1432  .in -2
1433 1433  
1434 1434  .sp
1435 1435  .LP
1436 1436  Microstate accounting is now continuously enabled. While this information was
1437 1437  previously an estimate, if microstate accounting were not enabled, the current
1438 1438  information is now never an estimate represents time the process has spent in
1439 1439  various states.
1440 1440  .SS "lstatus"
1441 1441  .LP
1442 1442  Contains a \fBprheader\fR structure followed by an array of \fBlwpstatus\fR
1443 1443  structures, one for each active lwp in the process (see also
1444 1444  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpstatus\fR, below). The
1445 1445  \fBprheader\fR structure describes the number and size of the array entries
1446 1446  that follow.
1447 1447  .sp
1448 1448  .in +2
1449 1449  .nf
1450 1450  typedef struct prheader {
1451 1451      long pr_nent;        /* number of entries */
1452 1452      size_t pr_entsize;   /* size of each entry, in bytes */
1453 1453  } prheader_t;
1454 1454  .fi
1455 1455  .in -2
1456 1456  
1457 1457  .sp
1458 1458  .LP
1459 1459  The \fBlwpstatus\fR structure may grow by the addition of elements at the end
1460 1460  in future releases of the system. Programs must use \fBpr_entsize\fR in the
1461 1461  file header to index through the array. These comments apply to all \fB/proc\fR
1462 1462  files that include a \fBprheader\fR structure (\fBlpsinfo\fR and \fBlusage\fR,
1463 1463  below).
1464 1464  .SS "lpsinfo"
1465 1465  .LP
1466 1466  Contains a \fBprheader\fR structure followed by an array of \fBlwpsinfo\fR
1467 1467  structures, one for eachactive and zombie lwp in the process. See also
1468 1468  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpsinfo\fR, below.
1469 1469  .SS "lusage"
1470 1470  .LP
1471 1471  Contains a \fBprheader\fR structure followed by an array of \fBprusage\fR
1472 1472  structures, one for each active lwp in the process, plus an additional element
1473 1473  at the beginning that contains the summation over all defunct lwps (lwps that
1474 1474  once existed but no longer exist in the process). Excluding the \fBpr_lwpid\fR,
1475 1475  \fBpr_tstamp\fR, \fBpr_create\fR, and \fBpr_term\fR entries, the entry-by-entry
1476 1476  summation over all these structures is the definition of the process usage
1477 1477  information obtained from the \fBusage\fR file. (See also
1478 1478  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpusage\fR, below.)
1479 1479  .SS "lwp"
1480 1480  .LP
1481 1481  A directory containing entries each of which names an active or zombie lwp
1482 1482  within the process. These entries are themselves directories containing
1483 1483  additional files as described below. Only the \fBlwpsinfo\fR file exists in the
1484 1484  directory of a zombie lwp.
1485 1485  .SH STRUCTURE OF \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR
1486 1486  .LP
1487 1487  A given directory \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR contains the
1488 1488  following entries:
1489 1489  .SS "lwpctl"
1490 1490  .LP
1491 1491  Write-only control file. The messages written to this file affect the specific
1492 1492  lwp rather than the representative lwp, as is the case for the process's
1493 1493  \fBctl\fR file.
1494 1494  .SS "lwpstatus"
1495 1495  .LP
1496 1496  lwp-specific state information. This file contains the \fBlwpstatus\fR
1497 1497  structure for the specific lwp as described above for the representative lwp in
1498 1498  the process's \fBstatus\fR file.
1499 1499  .SS "lwpsinfo"
1500 1500  .LP
1501 1501  lwp-specific \fBps\fR(1) information. This file contains the \fBlwpsinfo\fR
1502 1502  structure for the specific lwp as described above for the representative lwp in
1503 1503  the process's \fBpsinfo\fR file. The \fBlwpsinfo\fR file remains accessible
1504 1504  after an lwp becomes a zombie.
1505 1505  .SS "lwpusage"
1506 1506  .LP
1507 1507  This file contains the \fBprusage\fR structure for the specific lwp as
1508 1508  described above for the process's \fBusage\fR file.
1509 1509  .SS "gwindows"
1510 1510  .LP
1511 1511  This file exists only on SPARC based machines. If it is non-empty, it contains
1512 1512  a \fBgwindows_t\fR structure, defined in \fB<sys/regset.h>\fR, with the values
1513 1513  of those SPARC register windows that could not be stored on the stack when the
1514 1514  lwp stopped. Conditions under which register windows are not stored on the
1515 1515  stack are: the stack pointer refers to nonexistent process memory or the stack
1516 1516  pointer is improperly aligned. If the lwp is not stopped or if there are no
1517 1517  register windows that could not be stored on the stack, the file is empty (the
1518 1518  usual case).
1519 1519  .SS "xregs"
1520 1520  .LP
1521 1521  Extra state registers. The extra state register set is architecture dependent;
1522 1522  this file is empty if the system does not support extra state registers. If the
1523 1523  file is non-empty, it contains an architecture dependent structure of type
1524 1524  \fBprxregset_t\fR, defined in \fB<procfs.h>\fR, with the values of the lwp's
1525 1525  extra state registers. If the lwp is not stopped, all register values are
1526 1526  undefined. See also the \fBPCSXREG\fR control operation, below.
1527 1527  .SS "asrs"
1528 1528  .LP
1529 1529  This file exists only for 64-bit SPARC V9 processes. It contains an
1530 1530  \fBasrset_t\fR structure, defined in <\fBsys/regset.h\fR>, containing the
1531 1531  values of the lwp's platform-dependent ancillary state registers. If the lwp is
1532 1532  not stopped, all register values are undefined. See also the \fBPCSASRS\fR
1533 1533  control operation, below.
1534 1534  .SS "spymaster"
1535 1535  .LP
1536 1536  For an agent lwp (see \fBPCAGENT\fR), this file contains a \fBpsinfo_t\fR
1537 1537  structure that corresponds to the process that created the agent lwp at the
1538 1538  time the agent was created. This structure is identical to that retrieved via
1539 1539  the \fBpsinfo\fR file, with one modification: the \fBpr_time\fR field does not
1540 1540  correspond to the CPU time for the process, but rather to the creation time of
1541 1541  the agent lwp.
1542 1542  .SS "templates"
1543 1543  .LP
1544 1544  A directory which contains references to the active templates for the lwp,
1545 1545  named by the contract type. Changes made to an active template descriptor do
1546 1546  not affect the original template which was activated, though they do affect the
1547 1547  active template. It is not possible to activate an active template descriptor.
1548 1548  See \fBcontract\fR(4).
1549 1549  .SH CONTROL MESSAGES
1550 1550  .LP
1551 1551  Process state changes are effected through messages written to a process's
1552 1552  \fBctl\fR file or to an individual lwp's \fBlwpctl\fR file. All control
1553 1553  messages consist of a \fBlong\fR that names the specific operation followed by
1554 1554  additional data containing the operand, if any.
1555 1555  .sp
1556 1556  .LP
1557 1557  Multiple control messages may be combined in a single \fBwrite\fR(2) (or
1558 1558  \fBwritev\fR(2)) to a control file, but no partial writes are permitted. That
1559 1559  is, each control message, operation code plus operand, if any, must be
1560 1560  presented in its entirety to the \fBwrite\fR(2) and not in pieces over several
1561 1561  system calls. If a control operation fails, no subsequent operations contained
1562 1562  in the same \fBwrite\fR(2) are attempted.
1563 1563  .sp
1564 1564  .LP
1565 1565  Descriptions of the allowable control messages follow. In all cases, writing a
1566 1566  message to a control file for a process or lwp that has terminated elicits the
1567 1567  error \fBENOENT\fR.
1568 1568  .SS "PCSTOP PCDSTOP PCWSTOP PCTWSTOP"
1569 1569  .LP
1570 1570  When applied to the process control file, \fBPCSTOP\fR directs all lwps to stop
1571 1571  and waits for them to stop, \fBPCDSTOP\fR directs all lwps to stop without
1572 1572  waiting for them to stop, and \fBPCWSTOP\fR simply waits for all lwps to stop.
1573 1573  When applied to an lwp control file, \fBPCSTOP\fR directs the specific lwp to
1574 1574  stop and waits until it has stopped, \fBPCDSTOP\fR directs the specific lwp to
1575 1575  stop without waiting for it to stop, and \fBPCWSTOP\fR simply waits for the
1576 1576  specific lwp to stop. When applied to an lwp control file, \fBPCSTOP\fR and
1577 1577  \fBPCWSTOP\fR complete when the lwp stops on an event of interest, immediately
1578 1578  if already so stopped; when applied to the process control file, they complete
1579 1579  when every lwp has stopped either on an event of interest or on a
1580 1580  \fBPR_SUSPENDED\fR stop.
1581 1581  .sp
1582 1582  .LP
1583 1583  \fBPCTWSTOP\fR is identical to \fBPCWSTOP\fR except that it enables the
1584 1584  operation to time out, to avoid waiting forever for a process or lwp that may
1585 1585  never stop on an event of interest. \fBPCTWSTOP\fR takes a \fBlong\fR operand
1586 1586  specifying a number of milliseconds; the wait will terminate successfully after
1587 1587  the specified number of milliseconds even if the process or lwp has not
1588 1588  stopped; a timeout value of zero makes the operation identical to
1589 1589  \fBPCWSTOP\fR.
1590 1590  .sp
1591 1591  .LP
1592 1592  An ``event of interest'' is either a \fBPR_REQUESTED\fR stop or a stop that has
1593 1593  been specified in the process's tracing flags (set by \fBPCSTRACE\fR,
1594 1594  \fBPCSFAULT\fR, \fBPCSENTRY\fR, and \fBPCSEXIT\fR). \fBPR_JOBCONTROL\fR and
1595 1595  \fBPR_SUSPENDED\fR stops are specifically not events of interest. (An lwp may
1596 1596  stop twice due to a stop signal, first showing \fBPR_SIGNALLED\fR if the signal
1597 1597  is traced and again showing \fBPR_JOBCONTROL\fR if the lwp is set running
1598 1598  without clearing the signal.) If \fBPCSTOP\fR or \fBPCDSTOP\fR is applied to an
1599 1599  lwp that is stopped, but not on an event of interest, the stop directive takes
1600 1600  effect when the lwp is restarted by the competing mechanism. At that time, the
1601 1601  lwp enters a \fBPR_REQUESTED\fR stop before executing any user-level code.
1602 1602  .sp
1603 1603  .LP
1604 1604  A write of a control message that blocks is interruptible by a signal so that,
1605 1605  for example, an \fBalarm\fR(2) can be set to avoid waiting forever for a
1606 1606  process or lwp that may never stop on an event of interest. If \fBPCSTOP\fR is
1607 1607  interrupted, the lwp stop directives remain in effect even though the
1608 1608  \fBwrite\fR(2) returns an error. (Use of \fBPCTWSTOP\fR with a non-zero timeout
1609 1609  is recommended over \fBPCWSTOP\fR with an \fBalarm\fR(2).)
1610 1610  .sp
1611 1611  .LP
1612 1612  A system process (indicated by the \fBPR_ISSYS\fR flag) never executes at user
1613 1613  level, has no user-level address space visible through \fB/proc\fR, and cannot
1614 1614  be stopped. Applying one of these operations to a system process or any of its
1615 1615  lwps elicits the error \fBEBUSY\fR.
1616 1616  .SS "PCRUN"
1617 1617  .LP
1618 1618  Make an lwp runnable again after a stop. This operation takes a \fBlong\fR
1619 1619  operand containing zero or more of the following flags:
1620 1620  .sp
1621 1621  .ne 2
1622 1622  .na
1623 1623  \fB\fBPRCSIG\fR\fR
1624 1624  .ad
1625 1625  .RS 12n
1626 1626  clears the current signal, if any (see \fBPCCSIG\fR).
1627 1627  .RE
1628 1628  
1629 1629  .sp
1630 1630  .ne 2
1631 1631  .na
1632 1632  \fB\fBPRCFAULT\fR\fR
1633 1633  .ad
1634 1634  .RS 12n
1635 1635  clears the current fault, if any (see \fBPCCFAULT\fR).
1636 1636  .RE
1637 1637  
1638 1638  .sp
1639 1639  .ne 2
1640 1640  .na
1641 1641  \fB\fBPRSTEP\fR\fR
1642 1642  .ad
1643 1643  .RS 12n
1644 1644  directs the lwp to execute a single machine instruction. On completion of the
1645 1645  instruction, a trace trap occurs. If \fBFLTTRACE\fR is being traced, the lwp
1646 1646  stops; otherwise, it is sent \fBSIGTRAP\fR. If \fBSIGTRAP\fR is being traced
1647 1647  and is not blocked, the lwp stops. When the lwp stops on an event of interest,
1648 1648  the single-step directive is cancelled, even if the stop occurs before the
1649 1649  instruction is executed. This operation requires hardware and operating system
1650 1650  support and may not be implemented on all processors. It is implemented on
1651 1651  SPARC and x86-based machines.
1652 1652  .RE
1653 1653  
1654 1654  .sp
1655 1655  .ne 2
1656 1656  .na
1657 1657  \fB\fBPRSABORT\fR\fR
1658 1658  .ad
1659 1659  .RS 12n
1660 1660  is meaningful only if the lwp is in a \fBPR_SYSENTRY\fR stop or is marked
1661 1661  \fBPR_ASLEEP\fR; it instructs the lwp to abort execution of the system call
1662 1662  (see \fBPCSENTRY\fR and \fBPCSEXIT\fR).
1663 1663  .RE
1664 1664  
1665 1665  .sp
1666 1666  .ne 2
1667 1667  .na
1668 1668  \fB\fBPRSTOP\fR\fR
1669 1669  .ad
1670 1670  .RS 12n
1671 1671  directs the lwp to stop again as soon as possible after resuming execution (see
1672 1672  \fBPCDSTOP\fR). In particular, if the lwp is stopped on \fBPR_SIGNALLED\fR or
1673 1673  \fBPR_FAULTED\fR, the next stop will show \fBPR_REQUESTED\fR, no other stop
1674 1674  will have intervened, and the lwp will not have executed any user-level code.
1675 1675  .RE
1676 1676  
1677 1677  .sp
1678 1678  .LP
1679 1679  When applied to an lwp control file, \fBPCRUN\fR clears any outstanding
1680 1680  directed-stop request and makes the specific lwp runnable. The operation fails
1681 1681  with \fBEBUSY\fR if the specific lwp is not stopped on an event of interest or
1682 1682  has not been directed to stop or if the agent lwp exists and this is not the
1683 1683  agent lwp (see \fBPCAGENT\fR).
1684 1684  .sp
1685 1685  .LP
1686 1686  When applied to the process control file, a representative lwp is chosen for
1687 1687  the operation as described for \fB/proc/\fR\fIpid\fR\fB/status\fR. The
1688 1688  operation fails with \fBEBUSY\fR if the representative lwp is not stopped on an
1689 1689  event of interest or has not been directed to stop or if the agent lwp exists.
1690 1690  If \fBPRSTEP\fR or \fBPRSTOP\fR was requested, the representative lwp is made
1691 1691  runnable and its outstanding directed-stop request is cleared; otherwise all
1692 1692  outstanding directed-stop requests are cleared and, if it was stopped on an
1693 1693  event of interest, the representative lwp is marked \fBPR_REQUESTED\fR. If, as
1694 1694  a consequence, all lwps are in the \fBPR_REQUESTED\fR or \fBPR_SUSPENDED\fR
1695 1695  stop state, all lwps showing \fBPR_REQUESTED\fR are made runnable.
1696 1696  .SS "PCSTRACE"
1697 1697  .LP
1698 1698  Define a set of signals to be traced in the process. The receipt of one of
1699 1699  these signals by an lwp causes the lwp to stop. The set of signals is defined
1700 1700  using an operand \fBsigset_t\fR contained in the control message. Receipt of
1701 1701  \fBSIGKILL\fR cannot be traced; if specified, it is silently ignored.
1702 1702  .sp
1703 1703  .LP
1704 1704  If a signal that is included in an lwp's held signal set (the signal mask) is
1705 1705  sent to the lwp, the signal is not received and does not cause a stop until it
1706 1706  is removed from the held signal set, either by the lwp itself or by setting the
1707 1707  held signal set with \fBPCSHOLD\fR.
1708 1708  .SS "PCCSIG"
1709 1709  .LP
1710 1710  The current signal, if any, is cleared from the specific or representative lwp.
1711 1711  .SS "PCSSIG"
1712 1712  .LP
1713 1713  The current signal and its associated signal information for the specific or
1714 1714  representative lwp are set according to the contents of the operand
1715 1715  \fBsiginfo\fR structure (see \fB<sys/siginfo.h>\fR). If the specified signal
1716 1716  number is zero, the current signal is cleared. The semantics of this operation
1717 1717  are different from those of \fBkill\fR(2) in that the signal is delivered to
1718 1718  the lwp immediately after execution is resumed (even if it is being blocked)
1719 1719  and an additional \fBPR_SIGNALLED\fR stop does not intervene even if the signal
1720 1720  is traced. Setting the current signal to \fBSIGKILL\fR terminates the process
1721 1721  immediately.
1722 1722  .SS "PCKILL"
1723 1723  .LP
1724 1724  If applied to the process control file, a signal is sent to the process with
1725 1725  semantics identical to those of \fBkill\fR(2). If applied to an lwp control
1726 1726  file, a directed signal is sent to the specific lwp. The signal is named in a
1727 1727  \fBlong\fR operand contained in the message. Sending \fBSIGKILL\fR terminates
1728 1728  the process immediately.
1729 1729  .SS "PCUNKILL"
1730 1730  .LP
1731 1731  A signal is deleted, that is, it is removed from the set of pending signals. If
1732 1732  applied to the process control file, the signal is deleted from the process's
1733 1733  pending signals. If applied to an lwp control file, the signal is deleted from
1734 1734  the lwp's pending signals. The current signal (if any) is unaffected. The
1735 1735  signal is named in a \fBlong\fR operand in the control message. It is an error
1736 1736  (\fBEINVAL\fR) to attempt to delete \fBSIGKILL\fR.
1737 1737  .SS "PCSHOLD"
1738 1738  .LP
1739 1739  Set the set of held signals for the specific or representative lwp (signals
1740 1740  whose delivery will be blocked if sent to the lwp). The set of signals is
1741 1741  specified with a \fBsigset_t\fR operand. \fBSIGKILL\fR and \fBSIGSTOP\fR cannot
1742 1742  be held; if specified, they are silently ignored.
1743 1743  .SS "PCSFAULT"
1744 1744  .LP
1745 1745  Define a set of hardware faults to be traced in the process. On incurring one
1746 1746  of these faults, an lwp stops. The set is defined via the operand
1747 1747  \fBfltset_t\fR structure. Fault names are defined in \fB<sys/fault.h>\fR and
1748 1748  include the following. Some of these may not occur on all processors; there may
1749 1749  be processor-specific faults in addition to these.
1750 1750  .sp
1751 1751  .ne 2
1752 1752  .na
1753 1753  \fB\fBFLTILL\fR\fR
1754 1754  .ad
1755 1755  .RS 13n
1756 1756  illegal instruction
1757 1757  .RE
1758 1758  
1759 1759  .sp
1760 1760  .ne 2
1761 1761  .na
1762 1762  \fB\fBFLTPRIV\fR\fR
1763 1763  .ad
1764 1764  .RS 13n
1765 1765  privileged instruction
1766 1766  .RE
1767 1767  
1768 1768  .sp
1769 1769  .ne 2
1770 1770  .na
1771 1771  \fB\fBFLTBPT\fR\fR
1772 1772  .ad
1773 1773  .RS 13n
1774 1774  breakpoint trap
1775 1775  .RE
1776 1776  
1777 1777  .sp
1778 1778  .ne 2
1779 1779  .na
1780 1780  \fB\fBFLTTRACE\fR\fR
1781 1781  .ad
1782 1782  .RS 13n
1783 1783  trace trap (single-step)
1784 1784  .RE
1785 1785  
1786 1786  .sp
1787 1787  .ne 2
1788 1788  .na
1789 1789  \fB\fBFLTWATCH\fR\fR
1790 1790  .ad
1791 1791  .RS 13n
1792 1792  watchpoint trap
1793 1793  .RE
1794 1794  
1795 1795  .sp
1796 1796  .ne 2
1797 1797  .na
1798 1798  \fB\fBFLTACCESS\fR\fR
1799 1799  .ad
1800 1800  .RS 13n
1801 1801  memory access fault (bus error)
1802 1802  .RE
1803 1803  
1804 1804  .sp
1805 1805  .ne 2
1806 1806  .na
1807 1807  \fB\fBFLTBOUNDS\fR\fR
1808 1808  .ad
1809 1809  .RS 13n
1810 1810  memory bounds violation
1811 1811  .RE
1812 1812  
1813 1813  .sp
1814 1814  .ne 2
1815 1815  .na
1816 1816  \fB\fBFLTIOVF\fR\fR
1817 1817  .ad
1818 1818  .RS 13n
1819 1819  integer overflow
1820 1820  .RE
1821 1821  
1822 1822  .sp
1823 1823  .ne 2
1824 1824  .na
1825 1825  \fB\fBFLTIZDIV\fR\fR
1826 1826  .ad
1827 1827  .RS 13n
1828 1828  integer zero divide
1829 1829  .RE
1830 1830  
1831 1831  .sp
1832 1832  .ne 2
1833 1833  .na
1834 1834  \fB\fBFLTFPE\fR\fR
1835 1835  .ad
1836 1836  .RS 13n
1837 1837  floating-point exception
1838 1838  .RE
1839 1839  
1840 1840  .sp
1841 1841  .ne 2
1842 1842  .na
1843 1843  \fB\fBFLTSTACK\fR\fR
1844 1844  .ad
1845 1845  .RS 13n
1846 1846  unrecoverable stack fault
1847 1847  .RE
1848 1848  
1849 1849  .sp
1850 1850  .ne 2
1851 1851  .na
1852 1852  \fB\fBFLTPAGE\fR\fR
1853 1853  .ad
1854 1854  .RS 13n
1855 1855  recoverable page fault
1856 1856  .RE
1857 1857  
1858 1858  .sp
1859 1859  .LP
1860 1860  When not traced, a fault normally results in the posting of a signal to the lwp
1861 1861  that incurred the fault. If an lwp stops on a fault, the signal is posted to
1862 1862  the lwp when execution is resumed unless the fault is cleared by \fBPCCFAULT\fR
1863 1863  or by the \fBPRCFAULT\fR option of \fBPCRUN\fR. \fBFLTPAGE\fR is an exception;
1864 1864  no signal is posted. The \fBpr_info\fR field in the \fBlwpstatus\fR structure
1865 1865  identifies the signal to be sent and contains machine-specific information
1866 1866  about the fault.
1867 1867  .SS "PCCFAULT"
1868 1868  .LP
1869 1869  The current fault, if any, is cleared; the associated signal will not be sent
1870 1870  to the specific or representative lwp.
1871 1871  .SS "PCSENTRY PCSEXIT"
1872 1872  .LP
1873 1873  These control operations instruct the process's lwps to stop on entry to or
1874 1874  exit from specified system calls. The set of system calls to be traced is
1875 1875  defined via an operand \fBsysset_t\fR structure.
1876 1876  .sp
1877 1877  .LP
1878 1878  When entry to a system call is being traced, an lwp stops after having begun
1879 1879  the call to the system but before the system call arguments have been fetched
1880 1880  from the lwp. When exit from a system call is being traced, an lwp stops on
1881 1881  completion of the system call just prior to checking for signals and returning
1882 1882  to user level. At this point, all return values have been stored into the lwp's
1883 1883  registers.
1884 1884  .sp
1885 1885  .LP
1886 1886  If an lwp is stopped on entry to a system call (\fBPR_SYSENTRY\fR) or when
1887 1887  sleeping in an interruptible system call (\fBPR_ASLEEP\fR is set), it may be
1888 1888  instructed to go directly to system call exit by specifying the \fBPRSABORT\fR
1889 1889  flag in a \fBPCRUN\fR control message. Unless exit from the system call is
1890 1890  being traced, the lwp returns to user level showing \fBEINTR\fR.
1891 1891  .SS "PCWATCH"
1892 1892  .LP
1893 1893  Set or clear a watched area in the controlled process from a \fBprwatch\fR
1894 1894  structure operand:
1895 1895  .sp
1896 1896  .in +2
1897 1897  .nf
1898 1898  typedef struct prwatch {
1899 1899      uintptr_t pr_vaddr;  /* virtual address of watched area */
1900 1900      size_t pr_size;      /* size of watched area in bytes */
1901 1901      int pr_wflags;       /* watch type flags */
1902 1902  } prwatch_t;
1903 1903  .fi
1904 1904  .in -2
1905 1905  
1906 1906  .sp
1907 1907  .LP
1908 1908  \fBpr_vaddr\fR specifies the virtual address of an area of memory to be watched
1909 1909  in the controlled process. \fBpr_size\fR specifies the size of the area, in
1910 1910  bytes. \fBpr_wflags\fR specifies the type of memory access to be monitored as a
1911 1911  bit-mask of the following flags:
1912 1912  .sp
1913 1913  .ne 2
1914 1914  .na
1915 1915  \fB\fBWA_READ\fR\fR
1916 1916  .ad
1917 1917  .RS 16n
1918 1918  read access
1919 1919  .RE
1920 1920  
1921 1921  .sp
1922 1922  .ne 2
1923 1923  .na
1924 1924  \fB\fBWA_WRITE\fR\fR
1925 1925  .ad
1926 1926  .RS 16n
1927 1927  write access
1928 1928  .RE
1929 1929  
1930 1930  .sp
1931 1931  .ne 2
1932 1932  .na
1933 1933  \fB\fBWA_EXEC\fR\fR
1934 1934  .ad
1935 1935  .RS 16n
1936 1936  execution access
1937 1937  .RE
1938 1938  
1939 1939  .sp
1940 1940  .ne 2
1941 1941  .na
1942 1942  \fB\fBWA_TRAPAFTER\fR\fR
1943 1943  .ad
1944 1944  .RS 16n
1945 1945  trap after the instruction completes
1946 1946  .RE
1947 1947  
1948 1948  .sp
1949 1949  .LP
1950 1950  If \fBpr_wflags\fR is non-empty, a watched area is established for the virtual
1951 1951  address range specified by \fBpr_vaddr\fR and \fBpr_size\fR. If \fBpr_wflags\fR
1952 1952  is empty, any previously-established watched area starting at the specified
1953 1953  virtual address is cleared; \fBpr_size\fR is ignored.
1954 1954  .sp
1955 1955  .LP
1956 1956  A watchpoint is triggered when an lwp in the traced process makes a memory
1957 1957  reference that covers at least one byte of a watched area and the memory
1958 1958  reference is as specified in \fBpr_wflags\fR. When an lwp triggers a
1959 1959  watchpoint, it incurs a watchpoint trap. If \fBFLTWATCH\fR is being traced, the
1960 1960  lwp stops; otherwise, it is sent a \fBSIGTRAP\fR signal; if \fBSIGTRAP\fR is
1961 1961  being traced and is not blocked, the lwp stops.
1962 1962  .sp
1963 1963  .LP
1964 1964  The watchpoint trap occurs before the instruction completes unless
1965 1965  \fBWA_TRAPAFTER\fR was specified, in which case it occurs after the instruction
1966 1966  completes. If it occurs before completion, the memory is not modified. If it
1967 1967  occurs after completion, the memory is modified (if the access is a write
1968 1968  access).
1969 1969  .sp
1970 1970  .LP
1971 1971  Physical i/o is an exception for watchpoint traps. In this instance, there is
1972 1972  no guarantee that memory before the watched area has already been modified (or
1973 1973  in the case of \fBWA_TRAPAFTER\fR, that the memory following the watched area
1974 1974  has not been modified) when the watchpoint trap occurs and the lwp stops.
1975 1975  .sp
1976 1976  .LP
1977 1977  \fBpr_info\fR in the \fBlwpstatus\fR structure contains information pertinent
1978 1978  to the watchpoint trap. In particular, the \fBsi_addr\fR field contains the
1979 1979  virtual address of the memory reference that triggered the watchpoint, and the
1980 1980  \fBsi_code\fR field contains one of \fBTRAP_RWATCH\fR, \fBTRAP_WWATCH\fR, or
1981 1981  \fBTRAP_XWATCH\fR, indicating read, write, or execute access, respectively. The
1982 1982  \fBsi_trapafter\fR field is zero unless \fBWA_TRAPAFTER\fR is in effect for
1983 1983  this watched area; non-zero indicates that the current instruction is not the
1984 1984  instruction that incurred the watchpoint trap. The \fBsi_pc\fR field contains
1985 1985  the virtual address of the instruction that incurred the trap.
1986 1986  .sp
1987 1987  .LP
1988 1988  A watchpoint trap may be triggered while executing a system call that makes
1989 1989  reference to the traced process's memory. The lwp that is executing the system
1990 1990  call incurs the watchpoint trap while still in the system call. If it stops as
1991 1991  a result, the \fBlwpstatus\fR structure contains the system call number and its
1992 1992  arguments. If the lwp does not stop, or if it is set running again without
1993 1993  clearing the signal or fault, the system call fails with \fBEFAULT\fR. If
1994 1994  \fBWA_TRAPAFTER\fR was specified, the memory reference will have completed and
1995 1995  the memory will have been modified (if the access was a write access) when the
1996 1996  watchpoint trap occurs.
1997 1997  .sp
1998 1998  .LP
1999 1999  If more than one of \fBWA_READ\fR, \fBWA_WRITE\fR, and \fBWA_EXEC\fR is
2000 2000  specified for a watched area, and a single instruction incurs more than one of
2001 2001  the specified types, only one is reported when the watchpoint trap occurs. The
2002 2002  precedence is \fBWA_EXEC\fR, \fBWA_READ\fR, \fBWA_WRITE\fR (\fBWA_EXEC\fR and
2003 2003  \fBWA_READ\fR take precedence over \fBWA_WRITE\fR), unless \fBWA_TRAPAFTER\fR
2004 2004  was specified, in which case it is \fBWA_WRITE\fR, \fBWA_READ\fR, \fBWA_EXEC\fR
2005 2005  (\fBWA_WRITE\fR takes precedence).
2006 2006  .sp
2007 2007  .LP
2008 2008  \fBPCWATCH\fR fails with \fBEINVAL\fR if an attempt is made to specify
2009 2009  overlapping watched areas or if \fBpr_wflags\fR contains flags other than those
2010 2010  specified above. It fails with \fBENOMEM\fR if an attempt is made to establish
2011 2011  more watched areas than the system can support (the system can support
2012 2012  thousands).
2013 2013  .sp
2014 2014  .LP
2015 2015  The child of a \fBvfork\fR(2) borrows the parent's address space. When a
2016 2016  \fBvfork\fR(2) is executed by a traced process, all watched areas established
2017 2017  for the parent are suspended until the child terminates or performs an
2018 2018  \fBexec\fR(2). Any watched areas established independently in the child are
2019 2019  cancelled when the parent resumes after the child's termination or
2020 2020  \fBexec\fR(2). \fBPCWATCH\fR fails with \fBEBUSY\fR if applied to the parent of
2021 2021  a \fBvfork\fR(2) before the child has terminated or performed an \fBexec\fR(2).
2022 2022  The \fBPR_VFORKP\fR flag is set in the \fBpstatus\fR structure for such a
2023 2023  parent process.
2024 2024  .sp
2025 2025  .LP
2026 2026  Certain accesses of the traced process's address space by the operating system
2027 2027  are immune to watchpoints. The initial construction of a signal stack frame
2028 2028  when a signal is delivered to an lwp will not trigger a watchpoint trap even if
2029 2029  the new frame covers watched areas of the stack. Once the signal handler is
2030 2030  entered, watchpoint traps occur normally. On SPARC based machines, register
2031 2031  window overflow and underflow will not trigger watchpoint traps, even if the
2032 2032  register window save areas cover watched areas of the stack.
2033 2033  .sp
2034 2034  .LP
2035 2035  Watched areas are not inherited by child processes, even if the traced
2036 2036  process's inherit-on-fork mode, \fBPR_FORK\fR, is set (see \fBPCSET\fR, below).
2037 2037  All watched areas are cancelled when the traced process performs a successful
2038 2038  \fBexec\fR(2).
2039 2039  .SS "PCSET PCUNSET"
2040 2040  .LP
2041 2041  \fBPCSET\fR sets one or more modes of operation for the traced process.
2042 2042  \fBPCUNSET\fR unsets these modes. The modes to be set or unset are specified by
2043 2043  flags in an operand \fBlong\fR in the control message:
2044 2044  .sp
2045 2045  .ne 2
2046 2046  .na
2047 2047  \fB\fBPR_FORK\fR\fR
2048 2048  .ad
2049 2049  .RS 13n
2050 2050  (inherit-on-fork): When set, the process's tracing flags and its
2051 2051  inherit-on-fork mode are inherited by the child of a \fBfork\fR(2),
2052 2052  \fBfork1\fR(2), or \fBvfork\fR(2). When unset, child processes start with all
2053 2053  tracing flags cleared.
2054 2054  .RE
2055 2055  
2056 2056  .sp
2057 2057  .ne 2
2058 2058  .na
2059 2059  \fB\fBPR_RLC\fR\fR
2060 2060  .ad
2061 2061  .RS 13n
2062 2062  (run-on-last-close): When set and the last writable \fB/proc\fR file descriptor
2063 2063  referring to the traced process or any of its lwps is closed, all of the
2064 2064  process's tracing flags and watched areas are cleared, any outstanding stop
2065 2065  directives are canceled, and if any lwps are stopped on events of interest,
2066 2066  they are set running as though \fBPCRUN\fR had been applied to them. When
2067 2067  unset, the process's tracing flags and watched areas are retained and lwps are
2068 2068  not set running on last close.
2069 2069  .RE
2070 2070  
2071 2071  .sp
2072 2072  .ne 2
2073 2073  .na
2074 2074  \fB\fBPR_KLC\fR\fR
2075 2075  .ad
2076 2076  .RS 13n
2077 2077  (kill-on-last-close): When set and the last writable \fB/proc\fR file
2078 2078  descriptor referring to the traced process or any of its lwps is closed, the
2079 2079  process is terminated with \fBSIGKILL\fR.
2080 2080  .RE
2081 2081  
2082 2082  .sp
2083 2083  .ne 2
2084 2084  .na
2085 2085  \fB\fBPR_ASYNC\fR\fR
2086 2086  .ad
2087 2087  .RS 13n
2088 2088  (asynchronous-stop): When set, a stop on an event of interest by one lwp does
2089 2089  not directly affect any other lwp in the process. When unset and an lwp stops
2090 2090  on an event of interest other than \fBPR_REQUESTED\fR, all other lwps in the
2091 2091  process are directed to stop.
2092 2092  .RE
2093 2093  
2094 2094  .sp
2095 2095  .ne 2
2096 2096  .na
2097 2097  \fB\fBPR_MSACCT\fR\fR
2098 2098  .ad
2099 2099  .RS 13n
2100 2100  (microstate accounting): Microstate accounting is now continuously enabled.
2101 2101  This flag is deprecated and no longer has any effect upon microstate
2102 2102  accounting. Applications may toggle this flag; however, microstate accounting
2103 2103  will remain enabled regardless.
2104 2104  .RE
2105 2105  
2106 2106  .sp
2107 2107  .ne 2
2108 2108  .na
2109 2109  \fB\fBPR_MSFORK\fR\fR
2110 2110  .ad
2111 2111  .RS 13n
2112 2112  (inherit microstate accounting): All processes now inherit microstate
2113 2113  accounting, as it is continuously enabled. This flag has been deprecated and
2114 2114  its use no longer has any effect upon the behavior of microstate accounting.
2115 2115  .RE
2116 2116  
2117 2117  .sp
2118 2118  .ne 2
2119 2119  .na
2120 2120  \fB\fBPR_BPTADJ\fR\fR
2121 2121  .ad
2122 2122  .RS 13n
2123 2123  (breakpoint trap pc adjustment): On x86-based machines, a breakpoint trap
2124 2124  leaves the program counter (the \fBEIP\fR) referring to the breakpointed
2125 2125  instruction plus one byte. When \fBPR_BPTADJ\fR is set, the system will adjust
2126 2126  the program counter back to the location of the breakpointed instruction when
2127 2127  the lwp stops on a breakpoint. This flag has no effect on SPARC based machines,
2128 2128  where breakpoint traps leave the program counter referring to the breakpointed
2129 2129  instruction.
2130 2130  .RE
2131 2131  
2132 2132  .sp
2133 2133  .ne 2
2134 2134  .na
2135 2135  \fB\fBPR_PTRACE\fR\fR
2136 2136  .ad
2137 2137  .RS 13n
2138 2138  (ptrace-compatibility): When set, a stop on an event of interest by the traced
2139 2139  process is reported to the parent of the traced process by \fBwait\fR(3C),
2140 2140  \fBSIGTRAP\fR is sent to the traced process when it executes a successful
2141 2141  \fBexec\fR(2), setuid/setgid flags are not honored for execs performed by the
2142 2142  traced process, any exec of an object file that the traced process cannot read
2143 2143  fails, and the process dies when its parent dies. This mode is deprecated; it
2144 2144  is provided only to allow \fBptrace\fR(3C) to be implemented as a library
2145 2145  function using \fB/proc\fR.
2146 2146  .RE
2147 2147  
2148 2148  .sp
2149 2149  .LP
2150 2150  It is an error (\fBEINVAL\fR) to specify flags other than those described above
2151 2151  or to apply these operations to a system process. The current modes are
2152 2152  reported in the \fBpr_flags\fR field of \fB/proc/\fR\fIpid\fR\fB/status\fR and
2153 2153  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwp\fR\fB/lwpstatus\fR.
2154 2154  .SS "PCSREG"
2155 2155  .LP
2156 2156  Set the general registers for the specific or representative lwp according to
2157 2157  the operand \fBprgregset_t\fR structure.
2158 2158  .sp
2159 2159  .LP
2160 2160  On SPARC based systems, only the condition-code bits of the processor-status
2161 2161  register (R_PSR) of SPARC V8 (32-bit) processes can be modified by
2162 2162  \fBPCSREG\fR. Other privileged registers cannot be modified at all.
2163 2163  .sp
2164 2164  .LP
2165 2165  On x86-based systems, only certain bits of the flags register (EFL) can be
2166 2166  modified by \fBPCSREG\fR: these include the condition codes, direction-bit, and
2167 2167  overflow-bit.
2168 2168  .sp
2169 2169  .LP
2170 2170  \fBPCSREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an event of
2171 2171  interest.
2172 2172  .SS "PCSVADDR"
2173 2173  .LP
2174 2174  Set the address at which execution will resume for the specific or
2175 2175  representative lwp from the operand \fBlong\fR. On SPARC based systems, both
2176 2176  %pc and %npc are set, with %npc set to the instruction following the virtual
2177 2177  address. On x86-based systems, only %eip is set. \fBPCSVADDR\fR fails with
2178 2178  \fBEBUSY\fR if the lwp is not stopped on an event of interest.
2179 2179  .SS "PCSFPREG"
2180 2180  .LP
2181 2181  Set the floating-point registers for the specific or representative lwp
2182 2182  according to the operand \fBprfpregset_t\fR structure. An error (\fBEINVAL\fR)
2183 2183  is returned if the system does not support floating-point operations (no
2184 2184  floating-point hardware and the system does not emulate floating-point machine
2185 2185  instructions). \fBPCSFPREG\fR fails with \fBEBUSY\fR if the lwp is not stopped
2186 2186  on an event of interest.
2187 2187  .SS "PCSXREG"
2188 2188  .LP
2189 2189  Set the extra state registers for the specific or representative lwp according
2190 2190  to the architecture-dependent operand \fBprxregset_t\fR structure. An error
2191 2191  (\fBEINVAL\fR) is returned if the system does not support extra state
2192 2192  registers. \fBPCSXREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an
2193 2193  event of interest.
2194 2194  .SS "PCSASRS"
2195 2195  .LP
2196 2196  Set the ancillary state registers for the specific or representative lwp
2197 2197  according to the SPARC V9 platform-dependent operand \fBasrset_t\fR structure.
2198 2198  An error (\fBEINVAL\fR) is returned if either the target process or the
2199 2199  controlling process is not a 64-bit SPARC V9 process. Most of the ancillary
2200 2200  state registers are privileged registers that cannot be modified. Only those
2201 2201  that can be modified are set; all others are silently ignored. \fBPCSASRS\fR
2202 2202  fails with \fBEBUSY\fR if the lwp is not stopped on an event of interest.
2203 2203  .SS "PCAGENT"
2204 2204  .LP
2205 2205  Create an agent lwp in the controlled process with register values from the
2206 2206  operand \fBprgregset_t\fR structure (see \fBPCSREG\fR, above). The agent lwp is
2207 2207  created in the stopped state showing \fBPR_REQUESTED\fR and with its held
2208 2208  signal set (the signal mask) having all signals except \fBSIGKILL\fR and
2209 2209  \fBSIGSTOP\fR blocked.
2210 2210  .sp
2211 2211  .LP
2212 2212  The \fBPCAGENT\fR operation fails with \fBEBUSY\fR unless the process is fully
2213 2213  stopped via \fB/proc\fR, that is, unless all of the lwps in the process are
2214 2214  stopped either on events of interest or on \fBPR_SUSPENDED\fR, or are stopped
2215 2215  on \fBPR_JOBCONTROL\fR and have been directed to stop via \fBPCDSTOP\fR.  It
2216 2216  fails with \fBEBUSY\fR if an agent lwp already exists. It fails with
2217 2217  \fBENOMEM\fR if system resources for creating new lwps have been exhausted.
2218 2218  .sp
2219 2219  .LP
2220 2220  Any \fBPCRUN\fR operation applied to the process control file or to the control
2221 2221  file of an lwp other than the agent lwp fails with \fBEBUSY\fR as long as the
2222 2222  agent lwp exists. The agent lwp must be caused to terminate by executing the
2223 2223  \fBSYS_lwp_exit\fR system call trap before the process can be restarted.
2224 2224  .sp
2225 2225  .LP
2226 2226  Once the agent lwp is created, its lwp-ID can be found by reading the process
2227 2227  status file. To facilitate opening the agent lwp's control and status files,
2228 2228  the directory name \fB/propc/\fR\fIpid\fR\fB/lwp/agent\fR is accepted for
2229 2229  lookup operations as an invisible alias for
2230 2230  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid,\fR \fIlwpid\fR being the lwp-ID of
2231 2231  the agent lwp (invisible in the sense that the name ``agent'' does not appear
2232 2232  in a directory listing of \fB/proc/\fR\fIpid\fR\fB/lwp\fR obtained from
2233 2233  \fBls\fR(1), \fBgetdents\fR(2), or \fBreaddir\fR(3C)).
2234 2234  .sp
2235 2235  .LP
2236 2236  The purpose of the agent lwp is to perform operations in the controlled process
2237 2237  on behalf of the controlling process: to gather information not directly
2238 2238  available via \fB/proc\fR files, or in general to make the process change state
2239 2239  in ways not directly available via \fB/proc\fR control operations. To make use
2240 2240  of an agent lwp, the controlling process must be capable of making it execute
2241 2241  system calls (specifically, the \fBSYS_lwp_exit\fR system call trap). The
2242 2242  register values given to the agent lwp on creation are typically the registers
2243 2243  of the representative lwp, so that the agent lwp can use its stack.
2244 2244  .sp
2245 2245  .LP
2246 2246  If the controlling process neglects to force the agent lwp to execute the
2247 2247  \fBSYS_lwp_exit\fR system call (due to either logic error or fatal failure on
2248 2248  the part of the controlling process), the agent lwp will remain in the target
2249 2249  process.  For purposes of being able to debug these otherwise rogue agents,
2250 2250  information as to the creator of the agent lwp is reflected in that lwp's
2251 2251  \fBspymaster\fR file in \fB/proc\fR. Should the target process generate a core
2252 2252  dump with the agent lwp in place, this information will be available via the
2253 2253  \fBNT_SPYMASTER\fR note in the core file (see \fBcore\fR(4)).
2254 2254  .sp
2255 2255  .LP
2256 2256  The agent lwp is not allowed to execute any variation of the \fBSYS_fork\fR or
2257 2257  \fBSYS_exec\fR system call traps. Attempts to do so yield \fBENOTSUP\fR to the
2258 2258  agent lwp.
2259 2259  .sp
2260 2260  .LP
2261 2261  Symbolic constants for system call trap numbers like \fBSYS_lwp_exit\fR and
2262 2262  \fBSYS_lwp_create\fR can be found in the header file <\fBsys/syscall.h\fR>.
2263 2263  .SS "PCREAD PCWRITE"
2264 2264  .LP
2265 2265  Read or write the target process's address space via a \fBpriovec\fR structure
2266 2266  operand:
2267 2267  .sp
2268 2268  .in +2
2269 2269  .nf
2270 2270  typedef struct priovec {
2271 2271      void *pio_base;      /* buffer in controlling process */
2272 2272      size_t pio_len;      /* size of read/write request in bytes */
2273 2273      off_t pio_offset;    /* virtual address in target process */
2274 2274  } priovec_t;
2275 2275  .fi
2276 2276  .in -2
2277 2277  
2278 2278  .sp
2279 2279  .LP
2280 2280  These operations have the same effect as \fBpread\fR(2) and \fBpwrite\fR(2),
2281 2281  respectively, of the target process's address space file. The difference is
2282 2282  that more than one \fBPCREAD\fR or \fBPCWRITE\fR control operation can be
2283 2283  written to the control file at once, and they can be interspersed with other
2284 2284  control operations in a single write to the control file. This is useful, for
2285 2285  example, when planting many breakpoint instructions in the process's address
2286 2286  space, or when stepping over a breakpointed instruction. Unlike \fBpread\fR(2)
2287 2287  and \fBpwrite\fR(2), no provision is made for partial reads or writes; if the
2288 2288  operation cannot be performed completely, it fails with \fBEIO\fR.
2289 2289  .SS "PCNICE"
2290 2290  .LP
2291 2291  The traced process's \fBnice\fR(2) value is incremented by the amount in the
2292 2292  operand \fBlong\fR. Only a process with the {\fBPRIV_PROC_PRIOCNTL\fR}
2293 2293  privilege asserted in its effective set can better a process's priority in this
2294 2294  way, but any user may lower the priority. This operation is not meaningful for
2295 2295  all scheduling classes.
2296 2296  .SS "PCSCRED"
2297 2297  .LP
2298 2298  Set the target process credentials to the values contained in the
2299 2299  \fBprcred_t\fR structure operand (see \fB/proc/\fR\fIpid\fR\fB/cred\fR). The
2300 2300  effective, real, and saved user-IDs and group-IDs of the target process are
2301 2301  set. The target process's supplementary groups are not changed; the
2302 2302  \fBpr_ngroups\fR and \fBpr_groups\fR members of the structure operand are
2303 2303  ignored. Only the privileged processes can perform this operation; for all
2304 2304  others it fails with \fBEPERM\fR.
2305 2305  .SS "PCSCREDX"
2306 2306  .LP
2307 2307  Operates like \fBPCSCRED\fR but also sets the supplementary groups; the length
2308 2308  of the data written with this control operation should be "sizeof
2309 2309  (\fBprcred_t\fR) + sizeof (\fBgid_t)\fR * (#groups - 1)".
2310 2310  .SS "PCSPRIV"
2311 2311  .LP
2312 2312  Set the target process privilege to the values contained in the \fBprpriv_t\fR
2313 2313  operand (see \fB/proc/pid/priv\fR). The effective, permitted, inheritable, and
2314 2314  limit sets are all changed. Privilege flags can also be set. The process is
2315 2315  made privilege aware unless it can relinquish privilege awareness. See
2316 2316  \fBprivileges\fR(5).
2317 2317  .sp
2318 2318  .LP
2319 2319  The limit set of the target process cannot be grown. The other privilege sets
2320 2320  must be subsets of the intersection of the effective set of the calling process
2321 2321  with the new limit set of the target process or subsets of the original values
2322 2322  of the sets in the target process.
2323 2323  .sp
2324 2324  .LP
2325 2325  If any of the above restrictions are not met, \fBEPERM\fR is returned. If the
2326 2326  structure written is improperly formatted, \fBEINVAL\fR is returned.
2327 2327  .SH PROGRAMMING NOTES
2328 2328  .LP
2329 2329  For security reasons, except for the \fBpsinfo\fR, \fBusage\fR, \fBlpsinfo\fR,
2330 2330  \fBlusage\fR, \fBlwpsinfo\fR, and \fBlwpusage\fR files, which are
2331 2331  world-readable, and except for privileged processes, an open of a \fB/proc\fR
2332 2332  file fails unless both the user-ID and group-ID of the caller match those of
2333 2333  the traced process and the process's object file is readable by the caller. The
2334 2334  effective set of the caller is a superset of both the inheritable and the
2335 2335  permitted set of the target process. The limit set of the caller is a superset
2336 2336  of the limit set of the target process. Except for the world-readable files
2337 2337  just mentioned, files corresponding to setuid and setgid processes can be
2338 2338  opened only by the appropriately privileged process.
2339 2339  .sp
2340 2340  .LP
2341 2341  A process that is missing the basic privilege {\fBPRIV_PROC_INFO\fR} cannot see
2342 2342  any processes under \fB/proc\fR that it cannot send a signal to.
2343 2343  .sp
2344 2344  .LP
2345 2345  A process that has {\fBPRIV_PROC_OWNER\fR} asserted in its effective set can
2346 2346  open any file for reading. To manipulate or control a process, the controlling
2347 2347  process must have at least as many privileges in its effective set as the
2348 2348  target process has in its effective, inheritable, and permitted sets. The limit
2349 2349  set of the controlling process must be a superset of the limit set of the
2350 2350  target process. Additional restrictions apply if any of the uids of the target
2351 2351  process are 0. See \fBprivileges\fR(5).
2352 2352  .sp
2353 2353  .LP
2354 2354  Even if held by a privileged process, an open process or lwp file descriptor
2355 2355  (other than file descriptors for the world-readable files) becomes invalid if
2356 2356  the traced process performs an \fBexec\fR(2) of a setuid/setgid object file or
2357 2357  an object file that the traced process cannot read. Any operation performed on
2358 2358  an invalid file descriptor, except \fBclose\fR(2), fails with \fBEAGAIN\fR. In
2359 2359  this situation, if any tracing flags are set and the process or any lwp file
2360 2360  descriptor is open for writing, the process will have been directed to stop and
2361 2361  its run-on-last-close flag will have been set (see \fBPCSET\fR). This enables a
2362 2362  controlling process (if it has permission) to reopen the \fB/proc\fR files to
2363 2363  get new valid file descriptors, close the invalid file descriptors, unset the
2364 2364  run-on-last-close flag (if desired), and proceed. Just closing the invalid file
2365 2365  descriptors causes the traced process to resume execution with all tracing
2366 2366  flags cleared. Any process not currently open for writing via \fB/proc\fR, but
2367 2367  that has left-over tracing flags from a previous open, and that executes a
2368 2368  setuid/setgid or unreadable object file, will not be stopped but will have all
2369 2369  its tracing flags cleared.
2370 2370  .sp
2371 2371  .LP
2372 2372  To wait for one or more of a set of processes or lwps to stop or terminate,
2373 2373  \fB/proc\fR file descriptors (other than those obtained by opening the
2374 2374  \fBcwd\fR or \fBroot\fR directories or by opening files in the \fBfd\fR or
2375 2375  \fBobject\fR directories) can be used in a \fBpoll\fR(2) system call. When
2376 2376  requested and returned, either of the polling events \fBPOLLPRI\fR or
2377 2377  \fBPOLLWRNORM\fR indicates that the process or lwp stopped on an event of
2378 2378  interest. Although they cannot be requested, the polling events \fBPOLLHUP\fR,
2379 2379  \fBPOLLERR\fR, and \fBPOLLNVAL\fR may be returned. \fBPOLLHUP\fR indicates that
2380 2380  the process or lwp has terminated. \fBPOLLERR\fR indicates that the file
2381 2381  descriptor has become invalid. \fBPOLLNVAL\fR is returned immediately if
2382 2382  \fBPOLLPRI\fR or \fBPOLLWRNORM\fR is requested on a file descriptor referring
2383 2383  to a system process (see \fBPCSTOP\fR). The requested events may be empty to
2384 2384  wait simply for termination.
2385 2385  .SH FILES
2386 2386  .ne 2
2387 2387  .na
2388 2388  \fB\fB/proc\fR\fR
2389 2389  .ad
2390 2390  .sp .6
2391 2391  .RS 4n
2392 2392  directory (list of processes)
2393 2393  .RE
2394 2394  
2395 2395  .sp
2396 2396  .ne 2
2397 2397  .na
2398 2398  \fB\fB/proc/\fIpid\fR\fR\fR
2399 2399  .ad
2400 2400  .sp .6
2401 2401  .RS 4n
2402 2402  specific process directory
2403 2403  .RE
2404 2404  
2405 2405  .sp
2406 2406  .ne 2
2407 2407  .na
2408 2408  \fB\fB/proc/self\fR\fR
2409 2409  .ad
2410 2410  .sp .6
2411 2411  .RS 4n
2412 2412  alias for a process's own directory
2413 2413  .RE
2414 2414  
2415 2415  .sp
2416 2416  .ne 2
2417 2417  .na
2418 2418  \fB\fB/proc/\fIpid\fR/as\fR\fR
2419 2419  .ad
2420 2420  .sp .6
2421 2421  .RS 4n
2422 2422  address space file
2423 2423  .RE
2424 2424  
2425 2425  .sp
2426 2426  .ne 2
2427 2427  .na
2428 2428  \fB\fB/proc/\fIpid\fR/ctl\fR\fR
2429 2429  .ad
2430 2430  .sp .6
2431 2431  .RS 4n
2432 2432  process control file
2433 2433  .RE
2434 2434  
2435 2435  .sp
2436 2436  .ne 2
2437 2437  .na
2438 2438  \fB\fB/proc/\fIpid\fR/status\fR\fR
2439 2439  .ad
2440 2440  .sp .6
2441 2441  .RS 4n
2442 2442  process status
2443 2443  .RE
2444 2444  
2445 2445  .sp
2446 2446  .ne 2
2447 2447  .na
2448 2448  \fB\fB/proc/\fIpid\fR/lstatus\fR\fR
2449 2449  .ad
2450 2450  .sp .6
2451 2451  .RS 4n
2452 2452  array of lwp status structs
2453 2453  .RE
2454 2454  
2455 2455  .sp
2456 2456  .ne 2
2457 2457  .na
2458 2458  \fB\fB/proc/\fIpid\fR/psinfo\fR\fR
2459 2459  .ad
2460 2460  .sp .6
2461 2461  .RS 4n
2462 2462  process \fBps\fR(1) info
2463 2463  .RE
2464 2464  
2465 2465  .sp
2466 2466  .ne 2
2467 2467  .na
2468 2468  \fB\fB/proc/\fIpid\fR/lpsinfo\fR\fR
2469 2469  .ad
2470 2470  .sp .6
2471 2471  .RS 4n
2472 2472  array of lwp \fBps\fR(1) info structs
2473 2473  .RE
2474 2474  
2475 2475  .sp
2476 2476  .ne 2
2477 2477  .na
2478 2478  \fB\fB/proc/\fIpid\fR/map\fR\fR
2479 2479  .ad
2480 2480  .sp .6
2481 2481  .RS 4n
2482 2482  address space map
2483 2483  .RE
2484 2484  
2485 2485  .sp
2486 2486  .ne 2
2487 2487  .na
2488 2488  \fB\fB/proc/\fIpid\fR/xmap\fR\fR
2489 2489  .ad
2490 2490  .sp .6
2491 2491  .RS 4n
2492 2492  extended address space map
2493 2493  .RE
2494 2494  
2495 2495  .sp
2496 2496  .ne 2
2497 2497  .na
2498 2498  \fB\fB/proc/\fIpid\fR/rmap\fR\fR
2499 2499  .ad
2500 2500  .sp .6
2501 2501  .RS 4n
2502 2502  reserved address map
2503 2503  .RE
2504 2504  
2505 2505  .sp
2506 2506  .ne 2
2507 2507  .na
2508 2508  \fB\fB/proc/\fIpid\fR/cred\fR\fR
2509 2509  .ad
2510 2510  .sp .6
2511 2511  .RS 4n
2512 2512  process credentials
2513 2513  .RE
2514 2514  
2515 2515  .sp
2516 2516  .ne 2
2517 2517  .na
2518 2518  \fB\fB/proc/\fIpid\fR/priv\fR\fR
2519 2519  .ad
2520 2520  .sp .6
2521 2521  .RS 4n
2522 2522  process privileges
2523 2523  .RE
2524 2524  
2525 2525  .sp
2526 2526  .ne 2
2527 2527  .na
2528 2528  \fB\fB/proc/\fIpid\fR/sigact\fR\fR
2529 2529  .ad
2530 2530  .sp .6
2531 2531  .RS 4n
2532 2532  process signal actions
2533 2533  .RE
2534 2534  
2535 2535  .sp
2536 2536  .ne 2
2537 2537  .na
2538 2538  \fB\fB/proc/\fIpid\fR/auxv\fR\fR
2539 2539  .ad
2540 2540  .sp .6
2541 2541  .RS 4n
2542 2542  process aux vector
2543 2543  .RE
2544 2544  
2545 2545  .sp
2546 2546  .ne 2
2547 2547  .na
2548 2548  \fB\fB/proc/\fIpid\fR/argv\fR\fR
2549 2549  .ad
2550 2550  .sp .6
2551 2551  .RS 4n
2552 2552  process argument vector
2553 2553  .RE
2554 2554  
2555 2555  .sp
2556 2556  .ne 2
2557 2557  .na
2558 2558  \fB\fB/proc/\fIpid\fR/ldt\fR\fR
2559 2559  .ad
2560 2560  .sp .6
2561 2561  .RS 4n
2562 2562  process \fBLDT\fR (x86 only)
2563 2563  .RE
2564 2564  
2565 2565  .sp
2566 2566  .ne 2
2567 2567  .na
2568 2568  \fB\fB/proc/\fIpid\fR/usage\fR\fR
2569 2569  .ad
2570 2570  .sp .6
2571 2571  .RS 4n
2572 2572  process usage
2573 2573  .RE
2574 2574  
2575 2575  .sp
2576 2576  .ne 2
2577 2577  .na
2578 2578  \fB\fB/proc/\fIpid\fR/lusage\fR\fR
2579 2579  .ad
2580 2580  .sp .6
2581 2581  .RS 4n
2582 2582  array of lwp usage structs
2583 2583  .RE
2584 2584  
2585 2585  .sp
2586 2586  .ne 2
2587 2587  .na
2588 2588  \fB\fB/proc/\fIpid\fR/path\fR\fR
2589 2589  .ad
2590 2590  .sp .6
2591 2591  .RS 4n
2592 2592  symbolic links to process open files
2593 2593  .RE
2594 2594  
2595 2595  .sp
2596 2596  .ne 2
2597 2597  .na
2598 2598  \fB\fB/proc/\fIpid\fR/pagedata\fR\fR
2599 2599  .ad
2600 2600  .sp .6
2601 2601  .RS 4n
2602 2602  process page data
2603 2603  .RE
2604 2604  
2605 2605  .sp
2606 2606  .ne 2
2607 2607  .na
2608 2608  \fB\fB/proc/\fIpid\fR/watch\fR\fR
2609 2609  .ad
2610 2610  .sp .6
2611 2611  .RS 4n
2612 2612  active watchpoints
2613 2613  .RE
2614 2614  
2615 2615  .sp
2616 2616  .ne 2
2617 2617  .na
2618 2618  \fB\fB/proc/\fIpid\fR/cwd\fR\fR
2619 2619  .ad
2620 2620  .sp .6
2621 2621  .RS 4n
2622 2622  alias for the current working directory
2623 2623  .RE
2624 2624  
2625 2625  .sp
2626 2626  .ne 2
2627 2627  .na
2628 2628  \fB\fB/proc/\fIpid\fR/root\fR\fR
2629 2629  .ad
2630 2630  .sp .6
2631 2631  .RS 4n
2632 2632  alias for the root directory
2633 2633  .RE
2634 2634  
2635 2635  .sp
2636 2636  .ne 2
2637 2637  .na
2638 2638  \fB\fB/proc/\fIpid\fR/fd\fR\fR
2639 2639  .ad
2640 2640  .sp .6
2641 2641  .RS 4n
2642 2642  directory (list of open files)
2643 2643  .RE
2644 2644  
2645 2645  .sp
2646 2646  .ne 2
2647 2647  .na
2648 2648  \fB\fB/proc/\fIpid\fR/fd/*\fR\fR
2649 2649  .ad
2650 2650  .sp .6
2651 2651  .RS 4n
2652 2652  aliases for process's open files
2653 2653  .RE
2654 2654  
2655 2655  .sp
2656 2656  .ne 2
2657 2657  .na
2658 2658  \fB\fB/proc/\fIpid\fR/object\fR\fR
2659 2659  .ad
2660 2660  .sp .6
2661 2661  .RS 4n
2662 2662  directory (list of mapped files)
2663 2663  .RE
2664 2664  
2665 2665  .sp
2666 2666  .ne 2
2667 2667  .na
2668 2668  \fB\fB/proc/\fIpid\fR/object/a.out\fR\fR
2669 2669  .ad
2670 2670  .sp .6
2671 2671  .RS 4n
2672 2672  alias for process's executable file
2673 2673  .RE
2674 2674  
2675 2675  .sp
2676 2676  .ne 2
2677 2677  .na
2678 2678  \fB\fB/proc/\fIpid\fR/object/*\fR\fR
2679 2679  .ad
2680 2680  .sp .6
2681 2681  .RS 4n
2682 2682  aliases for other mapped files
2683 2683  .RE
2684 2684  
2685 2685  .sp
2686 2686  .ne 2
2687 2687  .na
2688 2688  \fB\fB/proc/\fIpid\fR/lwp\fR\fR
2689 2689  .ad
2690 2690  .sp .6
2691 2691  .RS 4n
2692 2692  directory (list of lwps)
2693 2693  .RE
2694 2694  
2695 2695  .sp
2696 2696  .ne 2
2697 2697  .na
2698 2698  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR\fR\fR
2699 2699  .ad
2700 2700  .sp .6
2701 2701  .RS 4n
2702 2702  specific lwp directory
2703 2703  .RE
2704 2704  
2705 2705  .sp
2706 2706  .ne 2
2707 2707  .na
2708 2708  \fB\fB/proc/\fIpid\fR/lwp/agent\fR\fR
2709 2709  .ad
2710 2710  .sp .6
2711 2711  .RS 4n
2712 2712  alias for the agent lwp directory
2713 2713  .RE
2714 2714  
2715 2715  .sp
2716 2716  .ne 2
2717 2717  .na
2718 2718  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpctl\fR\fR
2719 2719  .ad
2720 2720  .sp .6
2721 2721  .RS 4n
2722 2722  lwp control file
2723 2723  .RE
2724 2724  
2725 2725  .sp
2726 2726  .ne 2
2727 2727  .na
2728 2728  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpstatus\fR\fR
2729 2729  .ad
2730 2730  .sp .6
2731 2731  .RS 4n
2732 2732  lwp status
2733 2733  .RE
2734 2734  
2735 2735  .sp
2736 2736  .ne 2
2737 2737  .na
2738 2738  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpsinfo\fR\fR
2739 2739  .ad
2740 2740  .sp .6
2741 2741  .RS 4n
2742 2742  lwp \fBps\fR(1) info
2743 2743  .RE
2744 2744  
2745 2745  .sp
2746 2746  .ne 2
2747 2747  .na
2748 2748  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpusage\fR\fR
2749 2749  .ad
2750 2750  .sp .6
2751 2751  .RS 4n
2752 2752  lwp usage
2753 2753  .RE
2754 2754  
2755 2755  .sp
2756 2756  .ne 2
2757 2757  .na
2758 2758  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/gwindows\fR\fR
2759 2759  .ad
2760 2760  .sp .6
2761 2761  .RS 4n
2762 2762  register windows (SPARC only)
2763 2763  .RE
2764 2764  
2765 2765  .sp
2766 2766  .ne 2
2767 2767  .na
2768 2768  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/xregs\fR\fR
2769 2769  .ad
2770 2770  .sp .6
2771 2771  .RS 4n
2772 2772  extra state registers
2773 2773  .RE
2774 2774  
2775 2775  .sp
2776 2776  .ne 2
2777 2777  .na
2778 2778  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/asrs\fR\fR
2779 2779  .ad
2780 2780  .sp .6
2781 2781  .RS 4n
2782 2782  ancillary state registers (SPARC V9 only)
2783 2783  .RE
2784 2784  
2785 2785  .sp
2786 2786  .ne 2
2787 2787  .na
2788 2788  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/spymaster\fR\fR
2789 2789  .ad
2790 2790  .sp .6
2791 2791  .RS 4n
2792 2792  For an agent LWP, the controlling process
2793 2793  .RE
2794 2794  
2795 2795  .SH SEE ALSO
2796 2796  .LP
2797 2797  \fBls\fR(1), \fBps\fR(1), \fBchroot\fR(1M), \fBalarm\fR(2), \fBbrk\fR(2),
2798 2798  \fBchdir\fR(2), \fBchroot\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2),
2799 2799  \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2), \fBfork1\fR(2), \fBfstat\fR(2),
2800 2800  \fBgetdents\fR(2), \fBgetustack\fR(2), \fBkill\fR(2), \fBlseek\fR(2),
2801 2801  \fBmmap\fR(2), \fBnice\fR(2), \fBopen\fR(2), \fBpoll\fR(2), \fBpread\fR(2),
2802 2802  \fBptrace\fR(3C), \fBpwrite\fR(2), \fBread\fR(2), \fBreadlink\fR(2),
2803 2803  \fBreadv\fR(2), \fBshmget\fR(2), \fBsigaction\fR(2), \fBsigaltstack\fR(2),
2804 2804  \fBvfork\fR(2), \fBwrite\fR(2), \fBwritev\fR(2), \fB_stack_grow\fR(3C),
2805 2805  \fBreaddir\fR(3C), \fBpthread_create\fR(3C), \fBpthread_join\fR(3C),
2806 2806  \fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), \fBthr_create\fR(3C),
2807 2807  \fBthr_join\fR(3C), \fBtypes32.h\fR(3HEAD), \fBucontext.h\fR(3HEAD),
2808 2808  \fBwait\fR(3C), \fBcontract\fR(4), \fBcore\fR(4), \fBprocess\fR(4),
2809 2809  \fBlfcompile\fR(5), \fBprivileges\fR(5)
2810 2810  .SH DIAGNOSTICS
2811 2811  .LP
2812 2812  Errors that can occur in addition to the errors normally associated with file
2813 2813  system access:
2814 2814  .sp
2815 2815  .ne 2
2816 2816  .na
2817 2817  \fB\fBE2BIG\fR\fR
2818 2818  .ad
2819 2819  .RS 13n
2820 2820  Data to be returned in a \fBread\fR(2) of the page data file exceeds the size
2821 2821  of the read buffer provided by the caller.
2822 2822  .RE
2823 2823  
2824 2824  .sp
2825 2825  .ne 2
2826 2826  .na
2827 2827  \fB\fBEACCES\fR\fR
2828 2828  .ad
2829 2829  .RS 13n
2830 2830  An attempt was made to examine a process that ran under a different uid than
2831 2831  the controlling process and {\fBPRIV_PROC_OWNER\fR} was not asserted in the
2832 2832  effective set.
2833 2833  .RE
2834 2834  
2835 2835  .sp
2836 2836  .ne 2
2837 2837  .na
2838 2838  \fB\fBEAGAIN\fR\fR
2839 2839  .ad
2840 2840  .RS 13n
2841 2841  The traced process has performed an \fBexec\fR(2) of a setuid/setgid object
2842 2842  file or of an object file that it cannot read; all further operations on the
2843 2843  process or lwp file descriptor (except \fBclose\fR(2)) elicit this error.
2844 2844  .RE
2845 2845  
2846 2846  .sp
2847 2847  .ne 2
2848 2848  .na
2849 2849  \fB\fBEBUSY\fR\fR
2850 2850  .ad
2851 2851  .RS 13n
2852 2852  \fBPCSTOP\fR, \fBPCDSTOP\fR, \fBPCWSTOP\fR, or \fBPCTWSTOP\fR was applied to a
2853 2853  system process; an exclusive \fBopen\fR(2) was attempted on a \fB/proc\fR file
2854 2854  for a process already open for writing; \fBPCRUN\fR, \fBPCSREG\fR,
2855 2855  \fBPCSVADDR\fR, \fBPCSFPREG\fR, or \fBPCSXREG\fR was applied to a process or
2856 2856  lwp not stopped on an event of interest; an attempt was made to mount
2857 2857  \fB/proc\fR when it was already mounted; \fBPCAGENT\fR was applied to a process
2858 2858  that was not fully stopped or that already had an agent lwp.
2859 2859  .RE
2860 2860  
2861 2861  .sp
2862 2862  .ne 2
2863 2863  .na
2864 2864  \fB\fBEINVAL\fR\fR
2865 2865  .ad
2866 2866  .RS 13n
2867 2867  In general, this means that some invalid argument was supplied to a system
2868 2868  call. A non-exhaustive list of conditions eliciting this error includes: a
2869 2869  control message operation code is undefined; an out-of-range signal number was
2870 2870  specified with \fBPCSSIG\fR, \fBPCKILL\fR, or \fBPCUNKILL\fR; \fBSIGKILL\fR was
2871 2871  specified with \fBPCUNKILL\fR; \fBPCSFPREG\fR was applied on a system that does
2872 2872  not support floating-point operations; \fBPCSXREG\fR was applied on a system
2873 2873  that does not support extra state registers.
2874 2874  .RE
2875 2875  
2876 2876  .sp
2877 2877  .ne 2
2878 2878  .na
2879 2879  \fB\fBEINTR\fR\fR
2880 2880  .ad
2881 2881  .RS 13n
2882 2882  A signal was received by the controlling process while waiting for the traced
2883 2883  process or lwp to stop via \fBPCSTOP\fR, \fBPCWSTOP\fR, or \fBPCTWSTOP\fR.
2884 2884  .RE
2885 2885  
2886 2886  .sp
2887 2887  .ne 2
2888 2888  .na
2889 2889  \fB\fBEIO\fR\fR
2890 2890  .ad
2891 2891  .RS 13n
2892 2892  A \fBwrite\fR(2) was attempted at an illegal address in the traced process.
2893 2893  .RE
2894 2894  
2895 2895  .sp
2896 2896  .ne 2
2897 2897  .na
2898 2898  \fB\fBENOENT\fR\fR
2899 2899  .ad
2900 2900  .RS 13n
2901 2901  The traced process or lwp has terminated after being opened. The basic
2902 2902  privilege {\fBPRIV_PROC_INFO\fR} is not asserted in the effective set of the
2903 2903  calling process and the calling process cannot send a signal to the target
2904 2904  process.
2905 2905  .RE
2906 2906  
2907 2907  .sp
2908 2908  .ne 2
2909 2909  .na
2910 2910  \fB\fBENOMEM\fR\fR
2911 2911  .ad
2912 2912  .RS 13n
2913 2913  The system-imposed limit on the number of page data file descriptors was
2914 2914  reached on an open of \fB/proc/\fR\fIpid\fR\fB/pagedata\fR; an attempt was made
2915 2915  with \fBPCWATCH\fR to establish more watched areas than the system can support;
2916 2916  the \fBPCAGENT\fR operation was issued when the system was out of resources for
2917 2917  creating lwps.
2918 2918  .RE
2919 2919  
2920 2920  .sp
2921 2921  .ne 2
2922 2922  .na
2923 2923  \fB\fBENOSYS\fR\fR
2924 2924  .ad
2925 2925  .RS 13n
2926 2926  An attempt was made to perform an unsupported operation (such as
2927 2927  \fBcreat\fR(2), \fBlink\fR(2), or \fBunlink\fR(2)) on an entry in \fB/proc\fR.
2928 2928  .RE
2929 2929  
2930 2930  .sp
2931 2931  .ne 2
2932 2932  .na
2933 2933  \fB\fBEOVERFLOW\fR\fR
2934 2934  .ad
2935 2935  .RS 13n
2936 2936  A 32-bit controlling process attempted to read or write the \fBas\fR file or
2937 2937  attempted to read the \fBmap\fR, \fBrmap\fR, or \fBpagedata\fR file of a 64-bit
2938 2938  target process. A 32-bit controlling process attempted to apply one of the
2939 2939  control operations \fBPCSREG\fR, \fBPCSXREG\fR, \fBPCSVADDR\fR, \fBPCWATCH\fR,
2940 2940  \fBPCAGENT\fR, \fBPCREAD\fR, \fBPCWRITE\fR to a 64-bit target process.
2941 2941  .RE
2942 2942  
2943 2943  .sp
2944 2944  .ne 2
2945 2945  .na
2946 2946  \fB\fBEPERM\fR\fR
2947 2947  .ad
2948 2948  .RS 13n
2949 2949  The process that issued the \fBPCSCRED\fR or \fBPCSCREDX\fR operation did not
2950 2950  have the {\fBPRIV_PROC_SETID\fR} privilege asserted in its effective set, or
2951 2951  the process that issued the \fBPCNICE\fR operation did not have the
2952 2952  {\fBPRIV_PROC_PRIOCNTL\fR} in its effective set.
2953 2953  .sp
2954 2954  An attempt was made to control a process of which the E, P, and I privilege
2955 2955  sets were not a subset of the effective set of the controlling process or the
2956 2956  limit set of the controlling process is not a superset of limit set of the
2957 2957  controlled process.
2958 2958  .sp
2959 2959  Any of the uids of the target process are 0 or an attempt was made to change
2960 2960  any of the uids to 0 using PCSCRED and the security policy imposed additional
2961 2961  restrictions. See \fBprivileges\fR(5).
2962 2962  .RE
2963 2963  
2964 2964  .SH NOTES
2965 2965  .LP
2966 2966  Descriptions of structures in this document include only interesting structure
2967 2967  elements, not filler and padding fields, and may show elements out of order for
2968 2968  descriptive clarity. The actual structure definitions are contained in
2969 2969  \fB<procfs.h>\fR\&.
2970 2970  .SH BUGS
2971 2971  .LP
2972 2972  Because the old \fBioctl\fR(2)-based version of \fB/proc\fR is currently
2973 2973  supported for binary compatibility with old applications, the top-level
2974 2974  directory for a process, \fB/proc/\fR\fIpid\fR, is not world-readable, but it
2975 2975  is world-searchable. Thus, anyone can open \fB/proc/\fR\fIpid\fR\fB/psinfo\fR
2976 2976  even though \fBls\fR(1) applied to \fB/proc/\fR\fIpid\fR will fail for anyone
2977 2977  but the owner or an appropriately privileged process. Support for the old
2978 2978  \fBioctl\fR(2)-based version of \fB/proc\fR will be dropped in a future
2979 2979  release, at which time the top-level directory for a process will be made
2980 2980  world-readable.
2981 2981  .sp
2982 2982  .LP
2983 2983  On SPARC based machines, the types \fBgregset_t\fR and \fBfpregset_t\fR defined
2984 2984  in <\fBsys/regset.h\fR> are similar to but not the same as the types
2985 2985  \fBprgregset_t\fR and \fBprfpregset_t\fR defined in <\fBprocfs.h\fR>.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX