Code review comments from jeffpc

          --- 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 (c) 2013, Joyent, Inc. All rights reserved.
   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      -.TH PROC 4 "Jul 23, 2015"
        8 +.TH PROC 4 "Jun 6, 2016"
   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  .LP
 669  669  \fBpr_cursig\fR names the current signal, that is, the next signal to be
 670  670  delivered to the lwp, if any. \fBpr_info\fR, when the lwp is in a
 671  671  \fBPR_SIGNALLED\fR or \fBPR_FAULTED\fR stop, contains additional information
 672  672  pertinent to the particular signal or fault (see \fB<sys/siginfo.h>\fR).
 673  673  .sp
 674  674  .LP
 675  675  \fBpr_lwppend\fR identifies any synchronous or directed signals pending for the
 676  676  lwp. \fBpr_lwphold\fR identifies those signals whose delivery is being blocked
 677  677  by the lwp (the signal mask).
 678  678  .sp
 679  679  .LP
 680  680  \fBpr_action\fR contains the signal action information pertaining to the
 681  681  current signal (see \fBsigaction\fR(2)); it is undefined if \fBpr_cursig\fR is
 682  682  zero. \fBpr_altstack\fR contains the alternate signal stack information for the
 683  683  lwp (see \fBsigaltstack\fR(2)).
 684  684  .sp
 685  685  .LP
 686  686  \fBpr_oldcontext\fR, if not zero, contains the address on the lwp stack of a
 687  687  \fBucontext\fR structure describing the previous user-level context (see
 688  688  \fBucontext.h\fR(3HEAD)). It is non-zero only if the lwp is executing in the
 689  689  context of a signal handler.
 690  690  .sp
 691  691  .LP
 692  692  \fBpr_syscall\fR is the number of the system call, if any, being executed by
 693  693  the lwp; it is non-zero if and only if the lwp is stopped on \fBPR_SYSENTRY\fR
 694  694  or \fBPR_SYSEXIT\fR, or is asleep within a system call ( \fBPR_ASLEEP\fR is
 695  695  set). If \fBpr_syscall\fR is non-zero, \fBpr_nsysarg\fR is the number of
 696  696  arguments to the system call and \fBpr_sysarg\fR contains the actual arguments.
 697  697  .sp
 698  698  .LP
 699  699  \fBpr_rval1\fR, \fBpr_rval2\fR, and \fBpr_errno\fR are defined only if the lwp
 700  700  is stopped on \fBPR_SYSEXIT\fR or if the \fBPR_VFORKP\fR flag is set. If
 701  701  \fBpr_errno\fR is zero, \fBpr_rval1\fR and \fBpr_rval2\fR contain the return
 702  702  values from the system call. Otherwise, \fBpr_errno\fR contains the error
 703  703  number for the failing system call (see \fB<sys/errno.h>\fR).
 704  704  .sp
 705  705  .LP
 706  706  \fBpr_clname\fR contains the name of the lwp's scheduling class.
 707  707  .sp
 708  708  .LP
 709  709  \fBpr_tstamp\fR, if the lwp is stopped, contains a time stamp marking when the
 710  710  lwp stopped, in real time seconds and nanoseconds since an arbitrary time in
 711  711  the past.
 712  712  .sp
 713  713  .LP
 714  714  \fBpr_utime\fR is the amount of user level CPU time used by this LWP.
 715  715  .sp
 716  716  .LP
 717  717  \fBpr_stime\fR is the amount of system level CPU time used by this LWP.
 718  718  .sp
 719  719  .LP
 720  720  \fBpr_ustack\fR is the virtual address of the \fBstack_t\fR that contains the
 721  721  stack boundaries for this LWP. See \fBgetustack\fR(2) and
 722  722  \fB_stack_grow\fR(3C).
 723  723  .sp
 724  724  .LP
 725  725  \fBpr_instr\fR contains the machine instruction to which the lwp's program
 726  726  counter refers. The amount of data retrieved from the process is
 727  727  machine-dependent. On SPARC based machines, it is a 32-bit word. On x86-based
 728  728  machines, it is a single byte. In general, the size is that of the machine's
 729  729  smallest instruction. If \fBPR_PCINVAL\fR is set, \fBpr_instr\fR is undefined;
 730  730  this occurs whenever the lwp is not stopped or when the program counter refers
 731  731  to an invalid virtual address.
 732  732  .sp
 733  733  .LP
 734  734  \fBpr_reg\fR is an array holding the contents of a stopped lwp's general
 735  735  registers.
 736  736  .sp
 737  737  .ne 2
 738  738  .na
 739  739  \fBSPARC\fR
 740  740  .ad
 741  741  .RS 21n
 742  742  On SPARC-based machines, the predefined constants \fBR_G0\fR ... \fBR_G7\fR,
 743  743  \fBR_O0\fR ... \fBR_O7\fR, \fBR_L0\fR ... \fBR_L7\fR, \fBR_I0\fR ...
 744  744  \fBR_I7\fR, \fBR_PC\fR, \fBR_nPC\fR, and \fBR_Y\fR can be used as indices to
 745  745  refer to the corresponding registers; previous register windows can be read
 746  746  from their overflow locations on the stack (however, see the \fBgwindows\fR
 747  747  file in the \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR subdirectory).
 748  748  .RE
 749  749  
 750  750  .sp
 751  751  .ne 2
 752  752  .na
 753  753  \fBSPARC V8 (32-bit)\fR
 754  754  .ad
 755  755  .RS 21n
 756  756  For SPARC V8 (32-bit) controlling processes, the predefined constants
 757  757  \fBR_PSR\fR, \fBR_WIM\fR, and \fBR_TBR\fR can be used as indices to refer to
 758  758  the corresponding special registers. For SPARC V9 (64-bit) controlling
 759  759  processes, the predefined constants \fBR_CCR\fR, \fBR_ASI\fR, and \fBR_FPRS\fR
 760  760  can be used as indices to refer to the corresponding special registers.
 761  761  .RE
 762  762  
 763  763  .sp
 764  764  .ne 2
 765  765  .na
 766  766  \fBx86 (32-bit)\fR
 767  767  .ad
 768  768  .RS 21n
 769  769  For 32-bit x86 processes, the predefined constants listed belowcan be used as
 770  770  indices to refer to the corresponding registers.
 771  771  .sp
 772  772  .in +2
 773  773  .nf
 774  774  SS
 775  775  UESP
 776  776  EFL
 777  777  CS
 778  778  EIP
 779  779  ERR
 780  780  TRAPNO
 781  781  EAX
 782  782  ECX
 783  783  EDX
 784  784  EBX
 785  785  ESP
 786  786  EBP
 787  787  ESI
 788  788  EDI
 789  789  DS
 790  790  ES
 791  791  GS
 792  792  .fi
 793  793  .in -2
 794  794  
 795  795  The preceding constants are listed in \fB<sys/regset.h>\fR\&.
 796  796  .sp
 797  797  Note that a 32-bit process can run on an x86 64-bit system, using the constants
 798  798  listed above.
 799  799  .RE
 800  800  
 801  801  .sp
 802  802  .ne 2
 803  803  .na
 804  804  \fBx86 (64-bit)\fR
 805  805  .ad
 806  806  .RS 21n
 807  807  To read the registers of a 32- \fBor\fR a 64-bit process, a 64-bit x86 process
 808  808  should use the predefined constants listed below.
 809  809  .sp
 810  810  .in +2
 811  811  .nf
 812  812  REG_GSBASE
 813  813  REG_FSBASE
 814  814  REG_DS
 815  815  REG_ES
 816  816  REG_GS
 817  817  REG_FS
 818  818  REG_SS
 819  819  REG_RSP
 820  820  REG_RFL
 821  821  REG_CS
 822  822  REG_RIP
 823  823  REG_ERR
 824  824  REG_TRAPNO
 825  825  REG_RAX
 826  826  REG_RCX
 827  827  REG_RDX
 828  828  REG_RBX
 829  829  REG_RBP
 830  830  REG_RSI
 831  831  REG_RDI
 832  832  REG_R8
 833  833  REG_R9
 834  834  REG_R10
 835  835  REG_R11
 836  836  REG_R12
 837  837  REG_R13
 838  838  REG_R14
 839  839  REG_R15
 840  840  .fi
 841  841  .in -2
 842  842  
 843  843  The preceding constants are listed in \fB<sys/regset.h>\fR\&.
 844  844  .RE
 845  845  
 846  846  .sp
 847  847  .LP
 848  848  \fBpr_fpreg\fR is a structure holding the contents of the floating-point
 849  849  registers.
 850  850  .sp
 851  851  .LP
 852  852  SPARC registers, both general and floating-point, as seen by a 64-bit
 853  853  controlling process are the V9 versions of the registers, even if the target
 854  854  process is a 32-bit (V8) process. V8 registers are a subset of the V9
 855  855  registers.
 856  856  .sp
 857  857  .LP
 858  858  If the lwp is not stopped, all register values are undefined.
 859  859  .SS "psinfo"
 860  860  .LP
 861  861  Contains miscellaneous information about the process and the representative lwp
 862  862  needed by the \fBps\fR(1) command. \fBpsinfo\fR remains accessible after a
 863  863  process becomes a \fIzombie\fR. The file contains a \fBpsinfo\fR structure
 864  864  which contains an embedded \fBlwpsinfo\fR structure for the representative lwp,
 865  865  as follows:
 866  866  .sp
 867  867  .in +2
 868  868  .nf
 869  869  typedef struct psinfo {
 870  870      int pr_flag;             /* process flags (DEPRECATED: see below) */
 871  871      int pr_nlwp;             /* number of active lwps in the process */
 872  872      int pr_nzomb;            /* number of zombie lwps in the process */
 873  873      pid_t pr_pid;            /* process id */
 874  874      pid_t pr_ppid;           /* process id of parent */
 875  875      pid_t pr_pgid;           /* process id of process group leader */
 876  876      pid_t pr_sid;            /* session id */
 877  877      uid_t pr_uid;            /* real user id */
 878  878      uid_t pr_euid;           /* effective user id */
 879  879      gid_t pr_gid;            /* real group id */
 880  880      gid_t pr_egid;           /* effective group id */
 881  881      uintptr_t pr_addr;       /* address of process */
 882  882      size_t pr_size;          /* size of process image in Kbytes */
 883  883      size_t pr_rssize;        /* resident set size in Kbytes */
 884  884      dev_t pr_ttydev;         /* controlling tty device (or PRNODEV) */
 885  885      ushort_t pr_pctcpu;      /* % of recent cpu time used by all lwps */
 886  886      ushort_t pr_pctmem;      /* % of system memory used by process */
 887  887      timestruc_t pr_start;    /* process start time, from the epoch */
 888  888      timestruc_t pr_time;     /* cpu time for this process */
 889  889      timestruc_t pr_ctime;    /* cpu time for reaped children */
 890  890      char pr_fname[PRFNSZ];   /* name of exec'ed file */
 891  891      char pr_psargs[PRARGSZ]; /* initial characters of arg list */
 892  892      int pr_wstat;            /* if zombie, the wait() status */
 893  893      int pr_argc;             /* initial argument count */
 894  894      uintptr_t pr_argv;       /* address of initial argument vector */
 895  895      uintptr_t pr_envp;       /* address of initial environment vector */
 896  896      char pr_dmodel;          /* data model of the process */
 897  897      lwpsinfo_t pr_lwp;       /* information for representative lwp */
 898  898      taskid_t pr_taskid;      /* task id */
 899  899      projid_t pr_projid;      /* project id */
 900  900      poolid_t pr_poolid;      /* pool id */
 901  901      zoneid_t pr_zoneid;      /* zone id */
 902  902      ctid_t pr_contract;      /* process contract id */
 903  903  } psinfo_t;
 904  904  .fi
 905  905  .in -2
 906  906  
 907  907  .sp
 908  908  .LP
 909  909  Some of the entries in \fBpsinfo\fR, such as \fBpr_addr\fR, refer to internal
 910  910  kernel data structures and should not be expected to retain their meanings
 911  911  across different versions of the operating system.
 912  912  .sp
 913  913  .LP
 914  914  \fBpsinfo_t.pr_flag\fR is a deprecated interface that should no longer be used.
 915  915  Applications currently relying on the \fBSSYS\fR bit in \fBpr_flag\fR should
 916  916  migrate to checking \fBPR_ISSYS\fR in the \fBpstatus\fR structure's
 917  917  \fBpr_flags\fR field.
 918  918  .sp
 919  919  .LP
 920  920  \fBpr_pctcpu\fR and \fBpr_pctmem\fR are 16-bit binary fractions in the range
 921  921  0.0 to 1.0 with the binary point to the right of the high-order bit (1.0 ==
 922  922  0x8000). \fBpr_pctcpu\fR is the summation over all lwps in the process.
 923  923  .sp
 924  924  .LP
 925  925  \fBpr_lwp\fR contains the \fBps\fR(1) information for the representative lwp.
 926  926  If the process is a \fIzombie\fR, \fBpr_nlwp\fR, \fBpr_nzomb\fR, and
 927  927  \fBpr_lwp.pr_lwpid\fR are zero and the other fields of \fBpr_lwp\fR are
 928  928  undefined:
 929  929  .sp
 930  930  .in +2
 931  931  .nf
 932  932  typedef struct lwpsinfo {
 933  933      int pr_flag;             /* lwp flags (DEPRECATED: see below) */
 934  934      id_t pr_lwpid;           /* lwp id */
 935  935      uintptr_t pr_addr;       /* internal address of lwp */
 936  936      uintptr_t pr_wchan;      /* wait addr for sleeping lwp */
 937  937      char pr_stype;           /* synchronization event type */
 938  938      char pr_state;           /* numeric lwp state */
 939  939      char pr_sname;           /* printable character for pr_state */
 940  940      char pr_nice;            /* nice for cpu usage */
 941  941      short pr_syscall;        /* system call number (if in syscall) */
 942  942      char pr_oldpri;          /* pre-SVR4, low value is high priority */
 943  943      char pr_cpu;             /* pre-SVR4, cpu usage for scheduling */
 944  944      int pr_pri;              /* priority, high value = high priority */
 945  945      ushort_t pr_pctcpu;      /* % of recent cpu time used by this lwp */
 946  946      timestruc_t pr_start;    /* lwp start time, from the epoch */
 947  947      timestruc_t pr_time;     /* cpu time for this lwp */
 948  948      char pr_clname[PRCLSZ];  /* scheduling class name */
 949  949      char pr_name[PRFNSZ];    /* name of system lwp */
 950  950      processorid_t pr_onpro;  /* processor which last ran this lwp */
 951  951      processorid_t pr_bindpro;/* processor to which lwp is bound */
 952  952      psetid_t pr_bindpset;    /* processor set to which lwp is bound */
 953  953      lgrp_id_t pr_lgrp         /* home lgroup */
 954  954  } lwpsinfo_t;
 955  955  .fi
 956  956  .in -2
 957  957  
 958  958  .sp
 959  959  .LP
 960  960  Some of the entries in \fBlwpsinfo\fR, such as \fBpr_addr\fR, \fBpr_wchan\fR,
 961  961  \fBpr_stype\fR, \fBpr_state\fR, and \fBpr_name\fR, refer to internal kernel
 962  962  data structures and should not be expected to retain their meanings across
 963  963  different versions of the operating system.
 964  964  .sp
 965  965  .LP
 966  966  \fBlwpsinfo_t.pr_flag\fR is a deprecated interface that should no longer be
 967  967  used.
 968  968  .sp
 969  969  .LP
 970  970  \fBpr_pctcpu\fR is a 16-bit binary fraction, as described above. It represents
 971  971  the \fBCPU\fR time used by the specific lwp. On a multi-processor machine, the
 972  972  maximum value is 1/N, where N is the number of \fBCPU\fRs.
 973  973  .sp
 974  974  .LP
 975  975  \fBpr_contract\fR is the id of the process contract of which the process is a
 976  976  member. See \fBcontract\fR(4) and \fBprocess\fR(4).
 977  977  .SS "cred"
 978  978  .LP
 979  979  Contains a description of the credentials associated with the process:
 980  980  .sp
 981  981  .in +2
 982  982  .nf
 983  983  typedef struct prcred {
 984  984          uid_t pr_euid;      /* effective user id */
 985  985          uid_t pr_ruid;      /* real user id */
 986  986          uid_t pr_suid;      /* saved user id (from exec) */
 987  987          gid_t pr_egid;      /* effective group id */
 988  988          gid_t pr_rgid;      /* real group id */
 989  989          gid_t pr_sgid;      /* saved group id (from exec) */
 990  990          int pr_ngroups;     /* number of supplementary groups */
 991  991          gid_t pr_groups[1]; /* array of supplementary groups */
 992  992  } prcred_t;
 993  993  .fi
 994  994  .in -2
 995  995  .sp
 996  996  
 997  997  .sp
 998  998  .LP
 999  999  The array of associated supplementary groups in \fBpr_groups\fR is of variable
1000 1000  length; the \fBcred\fR file contains all of the supplementary groups.
1001 1001  \fBpr_ngroups\fR indicates the number of supplementary groups. (See also the
1002 1002  \fBPCSCRED\fR and \fBPCSCREDX\fR control operations.)
1003 1003  .SS "priv"
1004 1004  .LP
1005 1005  Contains a description of the privileges associated with the process:
1006 1006  .sp
1007 1007  .in +2
1008 1008  .nf
1009 1009  typedef struct prpriv {
1010 1010       uint32_t        pr_nsets;      /* number of privilege set */
1011 1011       uint32_t        pr_setsize;    /* size of privilege set */
1012 1012       uint32_t        pr_infosize;   /* size of supplementary data */
1013 1013       priv_chunk_t    pr_sets[1];    /* array of sets */
1014 1014  } prpriv_t;
1015 1015  .fi
1016 1016  .in -2
1017 1017  
1018 1018  .sp
1019 1019  .LP
1020 1020  The actual dimension of the \fBpr_sets\fR[] field is
1021 1021  .sp
1022 1022  .in +2
1023 1023  .nf
1024 1024  pr_sets[pr_nsets][pr_setsize]
1025 1025  .fi
1026 1026  .in -2
1027 1027  
1028 1028  .sp
1029 1029  .LP
1030 1030  which is followed by additional information about the process state
1031 1031  \fBpr_infosize\fR bytes in size.
1032 1032  .sp
1033 1033  .LP
1034 1034  The full size of the structure can be computed using
1035 1035  \fBPRIV_PRPRIV_SIZE\fR(\fBprpriv_t *\fR).
1036 1036  .SS "secflags"
1037 1037  .LP
1038 1038  This file contains the security-flags of the process.  It contains a
1039 1039  description of the security flags associated with the process.
1040 1040  .sp
1041 1041  .in +2
1042 1042  .nf
1043 1043  typedef struct prsecflags {
1044 1044          uint32_t pr_version;            /* ABI Versioning of this structure */
1045 1045          secflagset_t pr_effective;      /* Effective flags */
1046 1046          secflagset_t pr_inherit;        /* Inheritable flags */
1047 1047          secflagset_t pr_lower;          /* Lower flags */
1048 1048          secflagset_t pr_upper;          /* Upper flags */
1049 1049  } prsecflags_t;
1050 1050  .in -2
1051 1051  
1052 1052  .sp
1053 1053  .LP
1054 1054  The \fBpr_version\fR field is a version number for the structure, currently
1055 1055  \fBPRSECFLAGS_VERSION_1\fR.
1056 1056  .SS "sigact"
1057 1057  .LP
1058 1058  Contains an array of \fBsigaction structures\fR describing the current
1059 1059  dispositions of all signals associated with the traced process (see
1060 1060  \fBsigaction\fR(2)). Signal numbers are displaced by 1 from array indices, so
1061 1061  that the action for signal number \fIn\fR appears in position \fIn\fR-1 of the
1062 1062  array.
1063 1063  .SS "auxv"
1064 1064  .LP
1065 1065  Contains the initial values of the process's aux vector in an array of
1066 1066  \fBauxv_t\fR structures (see \fB<sys/auxv.h>\fR). The values are those that
1067 1067  were passed by the operating system as startup information to the dynamic
1068 1068  linker.
1069 1069  .SS "ldt"
1070 1070  .LP
1071 1071  This file exists only on x86-based machines. It is non-empty only if the
1072 1072  process has established a local descriptor table (\fBLDT\fR). If non-empty, the
1073 1073  file contains the array of currently active \fBLDT\fR entries in an array of
1074 1074  elements of type \fBstruct ssd\fR, defined in \fB<sys/sysi86.h>\fR, one element
1075 1075  for each active \fBLDT\fR entry.
1076 1076  .SS "map, xmap"
1077 1077  .LP
1078 1078  Contain information about the virtual address map of the process. The map file
1079 1079  contains an array of \fBprmap\fR structures while the xmap file contains an
1080 1080  array of \fBprxmap\fR structures. Each structure describes a contiguous virtual
1081 1081  address region in the address space of the traced process:
1082 1082  .sp
1083 1083  .in +2
1084 1084  .nf
1085 1085  typedef struct prmap {
1086 1086          uintptr_tpr_vaddr;         /* virtual address of mapping */
1087 1087          size_t pr_size;            /* size of mapping in bytes */
1088 1088          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1089 1089          offset_t pr_offset;        /* offset into mapped object, if any */
1090 1090          int pr_mflags;             /* protection and attribute flags */
1091 1091          int pr_pagesize;           /* pagesize for this mapping in bytes */
1092 1092          int pr_shmid;              /* SysV shared memory identifier */
1093 1093  } prmap_t;
1094 1094  .fi
1095 1095  .in -2
1096 1096  .sp
1097 1097  
1098 1098  .sp
1099 1099  .in +2
1100 1100  .nf
1101 1101  typedef struct prxmap {
1102 1102          uintptr_t pr_vaddr;        /* virtual address of mapping */
1103 1103          size_t pr_size;            /* size of mapping in bytes */
1104 1104          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1105 1105          offset_t pr_offset;        /* offset into mapped object, if any */
1106 1106          int pr_mflags;             /* protection and attribute flags */
1107 1107          int pr_pagesize;           /* pagesize for this mapping in bytes */
1108 1108          int pr_shmid;              /* SysV shared memory identifier */
1109 1109          dev_t pr_dev;              /* device of mapped object, if any */
1110 1110          uint64_t pr_ino;           /* inode of mapped object, if any */
1111 1111          size_t pr_rss;             /* pages of resident memory */
1112 1112          size_t pr_anon;            /* pages of resident anonymous memory */
1113 1113          size_t pr_locked;          /* pages of locked memory */
1114 1114          uint64_t pr_hatpagesize;   /* pagesize of mapping */
1115 1115  } prxmap_t;
1116 1116  .fi
1117 1117  .in -2
1118 1118  .sp
1119 1119  
1120 1120  .sp
1121 1121  .LP
1122 1122  \fBpr_vaddr\fR is the virtual address of the mapping within the traced process
1123 1123  and \fBpr_size\fR is its size in bytes. \fBpr_mapname\fR, if it does not
1124 1124  contain a null string, contains the name of a file in the \fBobject\fR
1125 1125  directory (see below) that can be opened read-only to obtain a file descriptor
1126 1126  for the mapped file associated with the mapping. This enables a debugger to
1127 1127  find object file symbol tables without having to know the real path names of
1128 1128  the executable file and shared libraries of the process. \fBpr_offset\fR is the
1129 1129  64-bit offset within the mapped file (if any) to which the virtual address is
1130 1130  mapped.
1131 1131  .sp
1132 1132  .LP
1133 1133  \fBpr_mflags\fR is a bit-mask of protection and attribute flags:
1134 1134  .sp
1135 1135  .ne 2
1136 1136  .na
1137 1137  \fB\fBMA_READ\fR\fR
1138 1138  .ad
1139 1139  .RS 17n
1140 1140  mapping is readable by the traced process.
1141 1141  .RE
1142 1142  
1143 1143  .sp
1144 1144  .ne 2
1145 1145  .na
1146 1146  \fB\fBMA_WRITE\fR\fR
1147 1147  .ad
1148 1148  .RS 17n
1149 1149  mapping is writable by the traced process.
1150 1150  .RE
1151 1151  
1152 1152  .sp
1153 1153  .ne 2
1154 1154  .na
1155 1155  \fB\fBMA_EXEC\fR\fR
1156 1156  .ad
1157 1157  .RS 17n
1158 1158  mapping is executable by the traced process.
1159 1159  .RE
1160 1160  
1161 1161  .sp
1162 1162  .ne 2
1163 1163  .na
1164 1164  \fB\fBMA_SHARED\fR\fR
1165 1165  .ad
1166 1166  .RS 17n
1167 1167  mapping changes are shared by the mapped object.
1168 1168  .RE
1169 1169  
1170 1170  .sp
1171 1171  .ne 2
1172 1172  .na
1173 1173  \fB\fBMA_ISM\fR\fR
1174 1174  .ad
1175 1175  .RS 17n
1176 1176  mapping is intimate shared memory (shared MMU resources)
1177 1177  .RE
1178 1178  
1179 1179  .sp
1180 1180  .ne 2
1181 1181  .na
1182 1182  \fB\fBMAP_NORESERVE\fR\fR
1183 1183  .ad
1184 1184  .RS 17n
1185 1185  mapping does not have swap space reserved (mapped with MAP_NORESERVE)
1186 1186  .RE
1187 1187  
1188 1188  .sp
1189 1189  .ne 2
1190 1190  .na
1191 1191  \fB\fBMA_SHM\fR\fR
1192 1192  .ad
1193 1193  .RS 17n
1194 1194  mapping System V shared memory
1195 1195  .RE
1196 1196  
1197 1197  .sp
1198 1198  .LP
1199 1199  A contiguous area of the address space having the same underlying mapped object
1200 1200  may appear as multiple mappings due to varying read, write, and execute
1201 1201  attributes. The underlying mapped object does not change over the range of a
1202 1202  single mapping. An \fBI/O\fR operation to a mapping marked \fBMA_SHARED\fR
1203 1203  fails if applied at a virtual address not corresponding to a valid page in the
1204 1204  underlying mapped object. A write to a \fBMA_SHARED\fR mapping that is not
1205 1205  marked \fBMA_WRITE\fR fails. Reads and writes to private mappings always
1206 1206  succeed. Reads and writes to unmapped addresses fail.
1207 1207  .sp
1208 1208  .LP
1209 1209  \fBpr_pagesize\fR is the page size for the mapping, currently always the system
1210 1210  pagesize.
1211 1211  .sp
1212 1212  .LP
1213 1213  \fBpr_shmid\fR is the shared memory identifier, if any, for the mapping. Its
1214 1214  value is \fB\(mi1\fR if the mapping is not System V shared memory. See
1215 1215  \fBshmget\fR(2).
1216 1216  .sp
1217 1217  .LP
1218 1218  \fBpr_dev\fR is the device of the mapped object, if any, for the mapping. Its
1219 1219  value is \fBPRNODEV\fR (-1) if the mapping does not have a device.
1220 1220  .sp
1221 1221  .LP
1222 1222  \fBpr_ino\fR is the inode of the mapped object, if any, for the mapping. Its
1223 1223  contents are only valid if \fBpr_dev\fR is not \fBPRNODEV.\fR
1224 1224  .sp
1225 1225  .LP
1226 1226  \fBpr_rss\fR is the number of resident pages of memory for the mapping. The
1227 1227  number of resident bytes for the mapping may be determined by multiplying
1228 1228  \fBpr_rss\fR by the page size given by \fBpr_pagesize.\fR
1229 1229  .sp
1230 1230  .LP
1231 1231  \fBpr_anon\fR is the number of resident anonymous memory pages (pages which are
1232 1232  private to this process) for the mapping.
1233 1233  .sp
1234 1234  .LP
1235 1235  \fBpr_locked\fR is the number of locked pages for the mapping. Pages which are
1236 1236  locked are always resident in memory.
1237 1237  .sp
1238 1238  .LP
1239 1239  \fBpr_hatpagesize\fR is the size, in bytes, of the \fBHAT\fR (\fBMMU\fR)
1240 1240  translation for the mapping. \fBpr_hatpagesize\fR may be different than
1241 1241  \fBpr_pagesize.\fR The possible values are hardware architecture specific, and
1242 1242  may change over a mapping's lifetime.
1243 1243  .SS "rmap"
1244 1244  .LP
1245 1245  Contains information about the reserved address ranges of the process. The file
1246 1246  contains an array of \fBprmap\fR structures, as defined above for the \fBmap\fR
1247 1247  file. Each structure describes a contiguous virtual address region in the
1248 1248  address space of the traced process that is reserved by the system in the sense
1249 1249  that an \fBmmap\fR(2) system call that does not specify \fBMAP_FIXED\fR will
1250 1250  not use any part of it for the new mapping. Examples of such reservations
1251 1251  include the address ranges reserved for the process stack and the individual
1252 1252  thread stacks of a multi-threaded process.
1253 1253  .SS "cwd"
1254 1254  .LP
1255 1255  A symbolic link to the process's current working directory. See \fBchdir\fR(2).
1256 1256  A \fBreadlink\fR(2) of \fB/proc/\fIpid\fR/cwd\fR yields a null string. However,
1257 1257  it can be opened, listed, and searched as a directory, and can be the target of
1258 1258  \fBchdir\fR(2).
1259 1259  .SS "root"
1260 1260  .LP
1261 1261  A symbolic link to the process's root directory.
1262 1262  \fB/proc/\fR\fIpid\fR\fB/root\fR can differ from the system root directory if
1263 1263  the process or one of its ancestors executed \fBchroot\fR(2) as super user. It
1264 1264  has the same semantics as \fB/proc/\fR\fIpid\fR\fB/cwd\fR.
1265 1265  .SS "fd"
1266 1266  .LP
1267 1267  A directory containing references to the open files of the process. Each entry
1268 1268  is a decimal number corresponding to an open file descriptor in the process.
1269 1269  .sp
1270 1270  .LP
1271 1271  If an entry refers to a regular file, it can be opened with normal file system
1272 1272  semantics but, to ensure that the controlling process cannot gain greater
1273 1273  access than the controlled process, with no file access modes other than its
1274 1274  read/write open modes in the controlled process. If an entry refers to a
1275 1275  directory, it can be accessed with the same semantics as
1276 1276  \fB/proc/\fIpid\fR/cwd\fR. An attempt to open any other type of entry fails
1277 1277  with \fBEACCES\fR.
1278 1278  .SS "object"
1279 1279  .LP
1280 1280  A directory containing read-only files with names corresponding to the
1281 1281  \fBpr_mapname\fR entries in the \fBmap\fR and \fBpagedata\fR files. Opening
1282 1282  such a file yields a file descriptor for the underlying mapped file associated
1283 1283  with an address-space mapping in the process. The file name \fBa.out\fR appears
1284 1284  in the directory as an alias for the process's executable file.
1285 1285  .sp
1286 1286  .LP
1287 1287  The \fBobject\fR directory makes it possible for a controlling process to gain
1288 1288  access to the object file and any shared libraries (and consequently the symbol
1289 1289  tables) without having to know the actual path names of the executable files.
1290 1290  .SS "path"
1291 1291  .LP
1292 1292  A directory containing symbolic links to files opened by the process. The
1293 1293  directory includes one entry for \fBcwd\fR and \fBroot\fR. The directory also
1294 1294  contains a numerical entry for each file descriptor in the \fBfd\fR directory,
1295 1295  and entries matching those in the \fBobject\fR directory. If this information
1296 1296  is not available, any attempt to read the contents of the symbolic link will
1297 1297  fail. This is most common for files that do not exist in the filesystem
1298 1298  namespace (such as \fBFIFO\fRs and sockets), but can also happen for regular
1299 1299  files. For the file descriptor entries, the path may be different from the one
1300 1300  used by the process to open the file.
1301 1301  .SS "pagedata"
1302 1302  .LP
1303 1303  Opening the page data file enables tracking of address space references and
1304 1304  modifications on a per-page basis.
1305 1305  .sp
1306 1306  .LP
1307 1307  A \fBread\fR(2) of the page data file descriptor returns structured page data
1308 1308  and atomically clears the page data maintained for the file by the system. That
1309 1309  is to say, each read returns data collected since the last read; the first read
1310 1310  returns data collected since the file was opened. When the call completes, the
1311 1311  read buffer contains the following structure as its header and thereafter
1312 1312  contains a number of section header structures and associated byte arrays that
1313 1313  must be accessed by walking linearly through the buffer.
1314 1314  .sp
1315 1315  .in +2
1316 1316  .nf
1317 1317  typedef struct prpageheader {
1318 1318      timestruc_t pr_tstamp; /* real time stamp, time of read() */
1319 1319      ulong_t pr_nmap;       /* number of address space mappings */
1320 1320      ulong_t pr_npage;      /* total number of pages */
1321 1321  } prpageheader_t;
1322 1322  .fi
1323 1323  .in -2
1324 1324  
1325 1325  .sp
1326 1326  .LP
1327 1327  The header is followed by \fBpr_nmap prasmap\fR structures and associated data
1328 1328  arrays. The \fBprasmap\fR structure contains the following elements:
1329 1329  .sp
1330 1330  .in +2
1331 1331  .nf
1332 1332  typedef struct prasmap {
1333 1333      uintptr_t pr_vaddr;        /* virtual address of mapping */
1334 1334      ulong_t pr_npage;          /* number of pages in mapping */
1335 1335      char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1336 1336      offset_t pr_offset;        /* offset into mapped object, if any */
1337 1337      int pr_mflags;             /* protection and attribute flags */
1338 1338      int pr_pagesize;           /* pagesize for this mapping in bytes */
1339 1339      int pr_shmid;              /* SysV shared memory identifier */
1340 1340  } prasmap_t;
1341 1341  .fi
1342 1342  .in -2
1343 1343  
1344 1344  .sp
1345 1345  .LP
1346 1346  Each section header is followed by \fBpr_npage\fR bytes, one byte for each page
1347 1347  in the mapping, plus 0-7 null bytes at the end so that the next \fBprasmap\fR
1348 1348  structure begins on an eight-byte aligned boundary. Each data byte may contain
1349 1349  these flags:
1350 1350  .sp
1351 1351  .ne 2
1352 1352  .na
1353 1353  \fB\fBPG_REFERENCED\fR\fR
1354 1354  .ad
1355 1355  .RS 17n
1356 1356  page has been referenced.
1357 1357  .RE
1358 1358  
1359 1359  .sp
1360 1360  .ne 2
1361 1361  .na
1362 1362  \fB\fBPG_MODIFIED\fR\fR
1363 1363  .ad
1364 1364  .RS 17n
1365 1365  page has been modified.
1366 1366  .RE
1367 1367  
1368 1368  .sp
1369 1369  .LP
1370 1370  If the read buffer is not large enough to contain all of the page data, the
1371 1371  read fails with \fBE2BIG\fR and the page data is not cleared. The required size
1372 1372  of the read buffer can be determined through \fBfstat\fR(2). Application of
1373 1373  \fBlseek\fR(2) to the page data file descriptor is ineffective; every read
1374 1374  starts from the beginning of the file. Closing the page data file descriptor
1375 1375  terminates the system overhead associated with collecting the data.
1376 1376  .sp
1377 1377  .LP
1378 1378  More than one page data file descriptor for the same process can be opened, up
1379 1379  to a system-imposed limit per traced process. A read of one does not affect the
1380 1380  data being collected by the system for the others. An open of the page data
1381 1381  file will fail with \fBENOMEM\fR if the system-imposed limit would be exceeded.
1382 1382  .SS "watch"
1383 1383  .LP
1384 1384  Contains an array of \fBprwatch\fR structures, one for each watched area
1385 1385  established by the \fBPCWATCH\fR control operation. See \fBPCWATCH\fR for
1386 1386  details.
1387 1387  .SS "usage"
1388 1388  .LP
1389 1389  Contains process usage information described by a \fBprusage\fR structure which
1390 1390  contains at least the following fields:
1391 1391  .sp
1392 1392  .in +2
1393 1393  .nf
1394 1394  typedef struct prusage {
1395 1395      id_t pr_lwpid;           /* lwp id.  0: process or defunct */
1396 1396      int pr_count;            /* number of contributing lwps */
1397 1397      timestruc_t pr_tstamp;   /* real time stamp, time of read() */
1398 1398      timestruc_t pr_create;   /* process/lwp creation time stamp */
1399 1399      timestruc_t pr_term;     /* process/lwp termination time stamp */
1400 1400      timestruc_t pr_rtime;    /* total lwp real (elapsed) time */
1401 1401      timestruc_t pr_utime;    /* user level CPU time */
1402 1402      timestruc_t pr_stime;    /* system call CPU time */
1403 1403      timestruc_t pr_ttime;    /* other system trap CPU time */
1404 1404      timestruc_t pr_tftime;   /* text page fault sleep time */
1405 1405      timestruc_t pr_dftime;   /* data page fault sleep time */
1406 1406      timestruc_t pr_kftime;   /* kernel page fault sleep time */
1407 1407      timestruc_t pr_ltime;    /* user lock wait sleep time */
1408 1408      timestruc_t pr_slptime;  /* all other sleep time */
1409 1409      timestruc_t pr_wtime;    /* wait-cpu (latency) time */
1410 1410      timestruc_t pr_stoptime; /* stopped time */
1411 1411      ulong_t pr_minf;         /* minor page faults */
1412 1412      ulong_t pr_majf;         /* major page faults */
1413 1413      ulong_t pr_nswap;        /* swaps */
1414 1414      ulong_t pr_inblk;        /* input blocks */
1415 1415      ulong_t pr_oublk;        /* output blocks */
1416 1416      ulong_t pr_msnd;         /* messages sent */
1417 1417      ulong_t pr_mrcv;         /* messages received */
1418 1418      ulong_t pr_sigs;         /* signals received */
1419 1419      ulong_t pr_vctx;         /* voluntary context switches */
1420 1420      ulong_t pr_ictx;         /* involuntary context switches */
1421 1421      ulong_t pr_sysc;         /* system calls */
1422 1422      ulong_t pr_ioch;         /* chars read and written */
1423 1423  } prusage_t;
1424 1424  .fi
1425 1425  .in -2
1426 1426  
1427 1427  .sp
1428 1428  .LP
1429 1429  Microstate accounting is now continuously enabled. While this information was
1430 1430  previously an estimate, if microstate accounting were not enabled, the current
1431 1431  information is now never an estimate represents time the process has spent in
1432 1432  various states.
1433 1433  .SS "lstatus"
1434 1434  .LP
1435 1435  Contains a \fBprheader\fR structure followed by an array of \fBlwpstatus\fR
1436 1436  structures, one for each active lwp in the process (see also
1437 1437  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpstatus\fR, below). The
1438 1438  \fBprheader\fR structure describes the number and size of the array entries
1439 1439  that follow.
1440 1440  .sp
1441 1441  .in +2
1442 1442  .nf
1443 1443  typedef struct prheader {
1444 1444      long pr_nent;        /* number of entries */
1445 1445      size_t pr_entsize;   /* size of each entry, in bytes */
1446 1446  } prheader_t;
1447 1447  .fi
1448 1448  .in -2
1449 1449  
1450 1450  .sp
1451 1451  .LP
1452 1452  The \fBlwpstatus\fR structure may grow by the addition of elements at the end
1453 1453  in future releases of the system. Programs must use \fBpr_entsize\fR in the
1454 1454  file header to index through the array. These comments apply to all \fB/proc\fR
1455 1455  files that include a \fBprheader\fR structure (\fBlpsinfo\fR and \fBlusage\fR,
1456 1456  below).
1457 1457  .SS "lpsinfo"
1458 1458  .LP
1459 1459  Contains a \fBprheader\fR structure followed by an array of \fBlwpsinfo\fR
1460 1460  structures, one for eachactive and zombie lwp in the process. See also
1461 1461  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpsinfo\fR, below.
1462 1462  .SS "lusage"
1463 1463  .LP
1464 1464  Contains a \fBprheader\fR structure followed by an array of \fBprusage\fR
1465 1465  structures, one for each active lwp in the process, plus an additional element
1466 1466  at the beginning that contains the summation over all defunct lwps (lwps that
1467 1467  once existed but no longer exist in the process). Excluding the \fBpr_lwpid\fR,
1468 1468  \fBpr_tstamp\fR, \fBpr_create\fR, and \fBpr_term\fR entries, the entry-by-entry
1469 1469  summation over all these structures is the definition of the process usage
1470 1470  information obtained from the \fBusage\fR file. (See also
1471 1471  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpusage\fR, below.)
1472 1472  .SS "lwp"
1473 1473  .LP
1474 1474  A directory containing entries each of which names an active or zombie lwp
1475 1475  within the process. These entries are themselves directories containing
1476 1476  additional files as described below. Only the \fBlwpsinfo\fR file exists in the
1477 1477  directory of a zombie lwp.
1478 1478  .SH STRUCTURE OF \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR
1479 1479  .LP
1480 1480  A given directory \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR contains the
1481 1481  following entries:
1482 1482  .SS "lwpctl"
1483 1483  .LP
1484 1484  Write-only control file. The messages written to this file affect the specific
1485 1485  lwp rather than the representative lwp, as is the case for the process's
1486 1486  \fBctl\fR file.
1487 1487  .SS "lwpstatus"
1488 1488  .LP
1489 1489  lwp-specific state information. This file contains the \fBlwpstatus\fR
1490 1490  structure for the specific lwp as described above for the representative lwp in
1491 1491  the process's \fBstatus\fR file.
1492 1492  .SS "lwpsinfo"
1493 1493  .LP
1494 1494  lwp-specific \fBps\fR(1) information. This file contains the \fBlwpsinfo\fR
1495 1495  structure for the specific lwp as described above for the representative lwp in
1496 1496  the process's \fBpsinfo\fR file. The \fBlwpsinfo\fR file remains accessible
1497 1497  after an lwp becomes a zombie.
1498 1498  .SS "lwpusage"
1499 1499  .LP
1500 1500  This file contains the \fBprusage\fR structure for the specific lwp as
1501 1501  described above for the process's \fBusage\fR file.
1502 1502  .SS "gwindows"
1503 1503  .LP
1504 1504  This file exists only on SPARC based machines. If it is non-empty, it contains
1505 1505  a \fBgwindows_t\fR structure, defined in \fB<sys/regset.h>\fR, with the values
1506 1506  of those SPARC register windows that could not be stored on the stack when the
1507 1507  lwp stopped. Conditions under which register windows are not stored on the
1508 1508  stack are: the stack pointer refers to nonexistent process memory or the stack
1509 1509  pointer is improperly aligned. If the lwp is not stopped or if there are no
1510 1510  register windows that could not be stored on the stack, the file is empty (the
1511 1511  usual case).
1512 1512  .SS "xregs"
1513 1513  .LP
1514 1514  Extra state registers. The extra state register set is architecture dependent;
1515 1515  this file is empty if the system does not support extra state registers. If the
1516 1516  file is non-empty, it contains an architecture dependent structure of type
1517 1517  \fBprxregset_t\fR, defined in \fB<procfs.h>\fR, with the values of the lwp's
1518 1518  extra state registers. If the lwp is not stopped, all register values are
1519 1519  undefined. See also the \fBPCSXREG\fR control operation, below.
1520 1520  .SS "asrs"
1521 1521  .LP
1522 1522  This file exists only for 64-bit SPARC V9 processes. It contains an
1523 1523  \fBasrset_t\fR structure, defined in <\fBsys/regset.h\fR>, containing the
1524 1524  values of the lwp's platform-dependent ancillary state registers. If the lwp is
1525 1525  not stopped, all register values are undefined. See also the \fBPCSASRS\fR
1526 1526  control operation, below.
1527 1527  .SS "spymaster"
1528 1528  .LP
1529 1529  For an agent lwp (see \fBPCAGENT\fR), this file contains a \fBpsinfo_t\fR
1530 1530  structure that corresponds to the process that created the agent lwp at the
1531 1531  time the agent was created. This structure is identical to that retrieved via
1532 1532  the \fBpsinfo\fR file, with one modification: the \fBpr_time\fR field does not
1533 1533  correspond to the CPU time for the process, but rather to the creation time of
1534 1534  the agent lwp.
1535 1535  .SS "templates"
1536 1536  .LP
1537 1537  A directory which contains references to the active templates for the lwp,
1538 1538  named by the contract type. Changes made to an active template descriptor do
1539 1539  not affect the original template which was activated, though they do affect the
1540 1540  active template. It is not possible to activate an active template descriptor.
1541 1541  See \fBcontract\fR(4).
1542 1542  .SH CONTROL MESSAGES
1543 1543  .LP
1544 1544  Process state changes are effected through messages written to a process's
1545 1545  \fBctl\fR file or to an individual lwp's \fBlwpctl\fR file. All control
1546 1546  messages consist of a \fBlong\fR that names the specific operation followed by
1547 1547  additional data containing the operand, if any.
1548 1548  .sp
1549 1549  .LP
1550 1550  Multiple control messages may be combined in a single \fBwrite\fR(2) (or
1551 1551  \fBwritev\fR(2)) to a control file, but no partial writes are permitted. That
1552 1552  is, each control message, operation code plus operand, if any, must be
1553 1553  presented in its entirety to the \fBwrite\fR(2) and not in pieces over several
1554 1554  system calls. If a control operation fails, no subsequent operations contained
1555 1555  in the same \fBwrite\fR(2) are attempted.
1556 1556  .sp
1557 1557  .LP
1558 1558  Descriptions of the allowable control messages follow. In all cases, writing a
1559 1559  message to a control file for a process or lwp that has terminated elicits the
1560 1560  error \fBENOENT\fR.
1561 1561  .SS "PCSTOP PCDSTOP PCWSTOP PCTWSTOP"
1562 1562  .LP
1563 1563  When applied to the process control file, \fBPCSTOP\fR directs all lwps to stop
1564 1564  and waits for them to stop, \fBPCDSTOP\fR directs all lwps to stop without
1565 1565  waiting for them to stop, and \fBPCWSTOP\fR simply waits for all lwps to stop.
1566 1566  When applied to an lwp control file, \fBPCSTOP\fR directs the specific lwp to
1567 1567  stop and waits until it has stopped, \fBPCDSTOP\fR directs the specific lwp to
1568 1568  stop without waiting for it to stop, and \fBPCWSTOP\fR simply waits for the
1569 1569  specific lwp to stop. When applied to an lwp control file, \fBPCSTOP\fR and
1570 1570  \fBPCWSTOP\fR complete when the lwp stops on an event of interest, immediately
1571 1571  if already so stopped; when applied to the process control file, they complete
1572 1572  when every lwp has stopped either on an event of interest or on a
1573 1573  \fBPR_SUSPENDED\fR stop.
1574 1574  .sp
1575 1575  .LP
1576 1576  \fBPCTWSTOP\fR is identical to \fBPCWSTOP\fR except that it enables the
1577 1577  operation to time out, to avoid waiting forever for a process or lwp that may
1578 1578  never stop on an event of interest. \fBPCTWSTOP\fR takes a \fBlong\fR operand
1579 1579  specifying a number of milliseconds; the wait will terminate successfully after
1580 1580  the specified number of milliseconds even if the process or lwp has not
1581 1581  stopped; a timeout value of zero makes the operation identical to
1582 1582  \fBPCWSTOP\fR.
1583 1583  .sp
1584 1584  .LP
1585 1585  An ``event of interest'' is either a \fBPR_REQUESTED\fR stop or a stop that has
1586 1586  been specified in the process's tracing flags (set by \fBPCSTRACE\fR,
1587 1587  \fBPCSFAULT\fR, \fBPCSENTRY\fR, and \fBPCSEXIT\fR). \fBPR_JOBCONTROL\fR and
1588 1588  \fBPR_SUSPENDED\fR stops are specifically not events of interest. (An lwp may
1589 1589  stop twice due to a stop signal, first showing \fBPR_SIGNALLED\fR if the signal
1590 1590  is traced and again showing \fBPR_JOBCONTROL\fR if the lwp is set running
1591 1591  without clearing the signal.) If \fBPCSTOP\fR or \fBPCDSTOP\fR is applied to an
1592 1592  lwp that is stopped, but not on an event of interest, the stop directive takes
1593 1593  effect when the lwp is restarted by the competing mechanism. At that time, the
1594 1594  lwp enters a \fBPR_REQUESTED\fR stop before executing any user-level code.
1595 1595  .sp
1596 1596  .LP
1597 1597  A write of a control message that blocks is interruptible by a signal so that,
1598 1598  for example, an \fBalarm\fR(2) can be set to avoid waiting forever for a
1599 1599  process or lwp that may never stop on an event of interest. If \fBPCSTOP\fR is
1600 1600  interrupted, the lwp stop directives remain in effect even though the
1601 1601  \fBwrite\fR(2) returns an error. (Use of \fBPCTWSTOP\fR with a non-zero timeout
1602 1602  is recommended over \fBPCWSTOP\fR with an \fBalarm\fR(2).)
1603 1603  .sp
1604 1604  .LP
1605 1605  A system process (indicated by the \fBPR_ISSYS\fR flag) never executes at user
1606 1606  level, has no user-level address space visible through \fB/proc\fR, and cannot
1607 1607  be stopped. Applying one of these operations to a system process or any of its
1608 1608  lwps elicits the error \fBEBUSY\fR.
1609 1609  .SS "PCRUN"
1610 1610  .LP
1611 1611  Make an lwp runnable again after a stop. This operation takes a \fBlong\fR
1612 1612  operand containing zero or more of the following flags:
1613 1613  .sp
1614 1614  .ne 2
1615 1615  .na
1616 1616  \fB\fBPRCSIG\fR\fR
1617 1617  .ad
1618 1618  .RS 12n
1619 1619  clears the current signal, if any (see \fBPCCSIG\fR).
1620 1620  .RE
1621 1621  
1622 1622  .sp
1623 1623  .ne 2
1624 1624  .na
1625 1625  \fB\fBPRCFAULT\fR\fR
1626 1626  .ad
1627 1627  .RS 12n
1628 1628  clears the current fault, if any (see \fBPCCFAULT\fR).
1629 1629  .RE
1630 1630  
1631 1631  .sp
1632 1632  .ne 2
1633 1633  .na
1634 1634  \fB\fBPRSTEP\fR\fR
1635 1635  .ad
1636 1636  .RS 12n
1637 1637  directs the lwp to execute a single machine instruction. On completion of the
1638 1638  instruction, a trace trap occurs. If \fBFLTTRACE\fR is being traced, the lwp
1639 1639  stops; otherwise, it is sent \fBSIGTRAP\fR. If \fBSIGTRAP\fR is being traced
1640 1640  and is not blocked, the lwp stops. When the lwp stops on an event of interest,
1641 1641  the single-step directive is cancelled, even if the stop occurs before the
1642 1642  instruction is executed. This operation requires hardware and operating system
1643 1643  support and may not be implemented on all processors. It is implemented on
1644 1644  SPARC and x86-based machines.
1645 1645  .RE
1646 1646  
1647 1647  .sp
1648 1648  .ne 2
1649 1649  .na
1650 1650  \fB\fBPRSABORT\fR\fR
1651 1651  .ad
1652 1652  .RS 12n
1653 1653  is meaningful only if the lwp is in a \fBPR_SYSENTRY\fR stop or is marked
1654 1654  \fBPR_ASLEEP\fR; it instructs the lwp to abort execution of the system call
1655 1655  (see \fBPCSENTRY\fR and \fBPCSEXIT\fR).
1656 1656  .RE
1657 1657  
1658 1658  .sp
1659 1659  .ne 2
1660 1660  .na
1661 1661  \fB\fBPRSTOP\fR\fR
1662 1662  .ad
1663 1663  .RS 12n
1664 1664  directs the lwp to stop again as soon as possible after resuming execution (see
1665 1665  \fBPCDSTOP\fR). In particular, if the lwp is stopped on \fBPR_SIGNALLED\fR or
1666 1666  \fBPR_FAULTED\fR, the next stop will show \fBPR_REQUESTED\fR, no other stop
1667 1667  will have intervened, and the lwp will not have executed any user-level code.
1668 1668  .RE
1669 1669  
1670 1670  .sp
1671 1671  .LP
1672 1672  When applied to an lwp control file, \fBPCRUN\fR clears any outstanding
1673 1673  directed-stop request and makes the specific lwp runnable. The operation fails
1674 1674  with \fBEBUSY\fR if the specific lwp is not stopped on an event of interest or
1675 1675  has not been directed to stop or if the agent lwp exists and this is not the
1676 1676  agent lwp (see \fBPCAGENT\fR).
1677 1677  .sp
1678 1678  .LP
1679 1679  When applied to the process control file, a representative lwp is chosen for
1680 1680  the operation as described for \fB/proc/\fR\fIpid\fR\fB/status\fR. The
1681 1681  operation fails with \fBEBUSY\fR if the representative lwp is not stopped on an
1682 1682  event of interest or has not been directed to stop or if the agent lwp exists.
1683 1683  If \fBPRSTEP\fR or \fBPRSTOP\fR was requested, the representative lwp is made
1684 1684  runnable and its outstanding directed-stop request is cleared; otherwise all
1685 1685  outstanding directed-stop requests are cleared and, if it was stopped on an
1686 1686  event of interest, the representative lwp is marked \fBPR_REQUESTED\fR. If, as
1687 1687  a consequence, all lwps are in the \fBPR_REQUESTED\fR or \fBPR_SUSPENDED\fR
1688 1688  stop state, all lwps showing \fBPR_REQUESTED\fR are made runnable.
1689 1689  .SS "PCSTRACE"
1690 1690  .LP
1691 1691  Define a set of signals to be traced in the process. The receipt of one of
1692 1692  these signals by an lwp causes the lwp to stop. The set of signals is defined
1693 1693  using an operand \fBsigset_t\fR contained in the control message. Receipt of
1694 1694  \fBSIGKILL\fR cannot be traced; if specified, it is silently ignored.
1695 1695  .sp
1696 1696  .LP
1697 1697  If a signal that is included in an lwp's held signal set (the signal mask) is
1698 1698  sent to the lwp, the signal is not received and does not cause a stop until it
1699 1699  is removed from the held signal set, either by the lwp itself or by setting the
1700 1700  held signal set with \fBPCSHOLD\fR.
1701 1701  .SS "PCCSIG"
1702 1702  .LP
1703 1703  The current signal, if any, is cleared from the specific or representative lwp.
1704 1704  .SS "PCSSIG"
1705 1705  .LP
1706 1706  The current signal and its associated signal information for the specific or
1707 1707  representative lwp are set according to the contents of the operand
1708 1708  \fBsiginfo\fR structure (see \fB<sys/siginfo.h>\fR). If the specified signal
1709 1709  number is zero, the current signal is cleared. The semantics of this operation
1710 1710  are different from those of \fBkill\fR(2) in that the signal is delivered to
1711 1711  the lwp immediately after execution is resumed (even if it is being blocked)
1712 1712  and an additional \fBPR_SIGNALLED\fR stop does not intervene even if the signal
1713 1713  is traced. Setting the current signal to \fBSIGKILL\fR terminates the process
1714 1714  immediately.
1715 1715  .SS "PCKILL"
1716 1716  .LP
1717 1717  If applied to the process control file, a signal is sent to the process with
1718 1718  semantics identical to those of \fBkill\fR(2). If applied to an lwp control
1719 1719  file, a directed signal is sent to the specific lwp. The signal is named in a
1720 1720  \fBlong\fR operand contained in the message. Sending \fBSIGKILL\fR terminates
1721 1721  the process immediately.
1722 1722  .SS "PCUNKILL"
1723 1723  .LP
1724 1724  A signal is deleted, that is, it is removed from the set of pending signals. If
1725 1725  applied to the process control file, the signal is deleted from the process's
1726 1726  pending signals. If applied to an lwp control file, the signal is deleted from
1727 1727  the lwp's pending signals. The current signal (if any) is unaffected. The
1728 1728  signal is named in a \fBlong\fR operand in the control message. It is an error
1729 1729  (\fBEINVAL\fR) to attempt to delete \fBSIGKILL\fR.
1730 1730  .SS "PCSHOLD"
1731 1731  .LP
1732 1732  Set the set of held signals for the specific or representative lwp (signals
1733 1733  whose delivery will be blocked if sent to the lwp). The set of signals is
1734 1734  specified with a \fBsigset_t\fR operand. \fBSIGKILL\fR and \fBSIGSTOP\fR cannot
1735 1735  be held; if specified, they are silently ignored.
1736 1736  .SS "PCSFAULT"
1737 1737  .LP
1738 1738  Define a set of hardware faults to be traced in the process. On incurring one
1739 1739  of these faults, an lwp stops. The set is defined via the operand
1740 1740  \fBfltset_t\fR structure. Fault names are defined in \fB<sys/fault.h>\fR and
1741 1741  include the following. Some of these may not occur on all processors; there may
1742 1742  be processor-specific faults in addition to these.
1743 1743  .sp
1744 1744  .ne 2
1745 1745  .na
1746 1746  \fB\fBFLTILL\fR\fR
1747 1747  .ad
1748 1748  .RS 13n
1749 1749  illegal instruction
1750 1750  .RE
1751 1751  
1752 1752  .sp
1753 1753  .ne 2
1754 1754  .na
1755 1755  \fB\fBFLTPRIV\fR\fR
1756 1756  .ad
1757 1757  .RS 13n
1758 1758  privileged instruction
1759 1759  .RE
1760 1760  
1761 1761  .sp
1762 1762  .ne 2
1763 1763  .na
1764 1764  \fB\fBFLTBPT\fR\fR
1765 1765  .ad
1766 1766  .RS 13n
1767 1767  breakpoint trap
1768 1768  .RE
1769 1769  
1770 1770  .sp
1771 1771  .ne 2
1772 1772  .na
1773 1773  \fB\fBFLTTRACE\fR\fR
1774 1774  .ad
1775 1775  .RS 13n
1776 1776  trace trap (single-step)
1777 1777  .RE
1778 1778  
1779 1779  .sp
1780 1780  .ne 2
1781 1781  .na
1782 1782  \fB\fBFLTWATCH\fR\fR
1783 1783  .ad
1784 1784  .RS 13n
1785 1785  watchpoint trap
1786 1786  .RE
1787 1787  
1788 1788  .sp
1789 1789  .ne 2
1790 1790  .na
1791 1791  \fB\fBFLTACCESS\fR\fR
1792 1792  .ad
1793 1793  .RS 13n
1794 1794  memory access fault (bus error)
1795 1795  .RE
1796 1796  
1797 1797  .sp
1798 1798  .ne 2
1799 1799  .na
1800 1800  \fB\fBFLTBOUNDS\fR\fR
1801 1801  .ad
1802 1802  .RS 13n
1803 1803  memory bounds violation
1804 1804  .RE
1805 1805  
1806 1806  .sp
1807 1807  .ne 2
1808 1808  .na
1809 1809  \fB\fBFLTIOVF\fR\fR
1810 1810  .ad
1811 1811  .RS 13n
1812 1812  integer overflow
1813 1813  .RE
1814 1814  
1815 1815  .sp
1816 1816  .ne 2
1817 1817  .na
1818 1818  \fB\fBFLTIZDIV\fR\fR
1819 1819  .ad
1820 1820  .RS 13n
1821 1821  integer zero divide
1822 1822  .RE
1823 1823  
1824 1824  .sp
1825 1825  .ne 2
1826 1826  .na
1827 1827  \fB\fBFLTFPE\fR\fR
1828 1828  .ad
1829 1829  .RS 13n
1830 1830  floating-point exception
1831 1831  .RE
1832 1832  
1833 1833  .sp
1834 1834  .ne 2
1835 1835  .na
1836 1836  \fB\fBFLTSTACK\fR\fR
1837 1837  .ad
1838 1838  .RS 13n
1839 1839  unrecoverable stack fault
1840 1840  .RE
1841 1841  
1842 1842  .sp
1843 1843  .ne 2
1844 1844  .na
1845 1845  \fB\fBFLTPAGE\fR\fR
1846 1846  .ad
1847 1847  .RS 13n
1848 1848  recoverable page fault
1849 1849  .RE
1850 1850  
1851 1851  .sp
1852 1852  .LP
1853 1853  When not traced, a fault normally results in the posting of a signal to the lwp
1854 1854  that incurred the fault. If an lwp stops on a fault, the signal is posted to
1855 1855  the lwp when execution is resumed unless the fault is cleared by \fBPCCFAULT\fR
1856 1856  or by the \fBPRCFAULT\fR option of \fBPCRUN\fR. \fBFLTPAGE\fR is an exception;
1857 1857  no signal is posted. The \fBpr_info\fR field in the \fBlwpstatus\fR structure
1858 1858  identifies the signal to be sent and contains machine-specific information
1859 1859  about the fault.
1860 1860  .SS "PCCFAULT"
1861 1861  .LP
1862 1862  The current fault, if any, is cleared; the associated signal will not be sent
1863 1863  to the specific or representative lwp.
1864 1864  .SS "PCSENTRY PCSEXIT"
1865 1865  .LP
1866 1866  These control operations instruct the process's lwps to stop on entry to or
1867 1867  exit from specified system calls. The set of system calls to be traced is
1868 1868  defined via an operand \fBsysset_t\fR structure.
1869 1869  .sp
1870 1870  .LP
1871 1871  When entry to a system call is being traced, an lwp stops after having begun
1872 1872  the call to the system but before the system call arguments have been fetched
1873 1873  from the lwp. When exit from a system call is being traced, an lwp stops on
1874 1874  completion of the system call just prior to checking for signals and returning
1875 1875  to user level. At this point, all return values have been stored into the lwp's
1876 1876  registers.
1877 1877  .sp
1878 1878  .LP
1879 1879  If an lwp is stopped on entry to a system call (\fBPR_SYSENTRY\fR) or when
1880 1880  sleeping in an interruptible system call (\fBPR_ASLEEP\fR is set), it may be
1881 1881  instructed to go directly to system call exit by specifying the \fBPRSABORT\fR
1882 1882  flag in a \fBPCRUN\fR control message. Unless exit from the system call is
1883 1883  being traced, the lwp returns to user level showing \fBEINTR\fR.
1884 1884  .SS "PCWATCH"
1885 1885  .LP
1886 1886  Set or clear a watched area in the controlled process from a \fBprwatch\fR
1887 1887  structure operand:
1888 1888  .sp
1889 1889  .in +2
1890 1890  .nf
1891 1891  typedef struct prwatch {
1892 1892      uintptr_t pr_vaddr;  /* virtual address of watched area */
1893 1893      size_t pr_size;      /* size of watched area in bytes */
1894 1894      int pr_wflags;       /* watch type flags */
1895 1895  } prwatch_t;
1896 1896  .fi
1897 1897  .in -2
1898 1898  
1899 1899  .sp
1900 1900  .LP
1901 1901  \fBpr_vaddr\fR specifies the virtual address of an area of memory to be watched
1902 1902  in the controlled process. \fBpr_size\fR specifies the size of the area, in
1903 1903  bytes. \fBpr_wflags\fR specifies the type of memory access to be monitored as a
1904 1904  bit-mask of the following flags:
1905 1905  .sp
1906 1906  .ne 2
1907 1907  .na
1908 1908  \fB\fBWA_READ\fR\fR
1909 1909  .ad
1910 1910  .RS 16n
1911 1911  read access
1912 1912  .RE
1913 1913  
1914 1914  .sp
1915 1915  .ne 2
1916 1916  .na
1917 1917  \fB\fBWA_WRITE\fR\fR
1918 1918  .ad
1919 1919  .RS 16n
1920 1920  write access
1921 1921  .RE
1922 1922  
1923 1923  .sp
1924 1924  .ne 2
1925 1925  .na
1926 1926  \fB\fBWA_EXEC\fR\fR
1927 1927  .ad
1928 1928  .RS 16n
1929 1929  execution access
1930 1930  .RE
1931 1931  
1932 1932  .sp
1933 1933  .ne 2
1934 1934  .na
1935 1935  \fB\fBWA_TRAPAFTER\fR\fR
1936 1936  .ad
1937 1937  .RS 16n
1938 1938  trap after the instruction completes
1939 1939  .RE
1940 1940  
1941 1941  .sp
1942 1942  .LP
1943 1943  If \fBpr_wflags\fR is non-empty, a watched area is established for the virtual
1944 1944  address range specified by \fBpr_vaddr\fR and \fBpr_size\fR. If \fBpr_wflags\fR
1945 1945  is empty, any previously-established watched area starting at the specified
1946 1946  virtual address is cleared; \fBpr_size\fR is ignored.
1947 1947  .sp
1948 1948  .LP
1949 1949  A watchpoint is triggered when an lwp in the traced process makes a memory
1950 1950  reference that covers at least one byte of a watched area and the memory
1951 1951  reference is as specified in \fBpr_wflags\fR. When an lwp triggers a
1952 1952  watchpoint, it incurs a watchpoint trap. If \fBFLTWATCH\fR is being traced, the
1953 1953  lwp stops; otherwise, it is sent a \fBSIGTRAP\fR signal; if \fBSIGTRAP\fR is
1954 1954  being traced and is not blocked, the lwp stops.
1955 1955  .sp
1956 1956  .LP
1957 1957  The watchpoint trap occurs before the instruction completes unless
1958 1958  \fBWA_TRAPAFTER\fR was specified, in which case it occurs after the instruction
1959 1959  completes. If it occurs before completion, the memory is not modified. If it
1960 1960  occurs after completion, the memory is modified (if the access is a write
1961 1961  access).
1962 1962  .sp
1963 1963  .LP
1964 1964  Physical i/o is an exception for watchpoint traps. In this instance, there is
1965 1965  no guarantee that memory before the watched area has already been modified (or
1966 1966  in the case of \fBWA_TRAPAFTER\fR, that the memory following the watched area
1967 1967  has not been modified) when the watchpoint trap occurs and the lwp stops.
1968 1968  .sp
1969 1969  .LP
1970 1970  \fBpr_info\fR in the \fBlwpstatus\fR structure contains information pertinent
1971 1971  to the watchpoint trap. In particular, the \fBsi_addr\fR field contains the
1972 1972  virtual address of the memory reference that triggered the watchpoint, and the
1973 1973  \fBsi_code\fR field contains one of \fBTRAP_RWATCH\fR, \fBTRAP_WWATCH\fR, or
1974 1974  \fBTRAP_XWATCH\fR, indicating read, write, or execute access, respectively. The
1975 1975  \fBsi_trapafter\fR field is zero unless \fBWA_TRAPAFTER\fR is in effect for
1976 1976  this watched area; non-zero indicates that the current instruction is not the
1977 1977  instruction that incurred the watchpoint trap. The \fBsi_pc\fR field contains
1978 1978  the virtual address of the instruction that incurred the trap.
1979 1979  .sp
1980 1980  .LP
1981 1981  A watchpoint trap may be triggered while executing a system call that makes
1982 1982  reference to the traced process's memory. The lwp that is executing the system
1983 1983  call incurs the watchpoint trap while still in the system call. If it stops as
1984 1984  a result, the \fBlwpstatus\fR structure contains the system call number and its
1985 1985  arguments. If the lwp does not stop, or if it is set running again without
1986 1986  clearing the signal or fault, the system call fails with \fBEFAULT\fR. If
1987 1987  \fBWA_TRAPAFTER\fR was specified, the memory reference will have completed and
1988 1988  the memory will have been modified (if the access was a write access) when the
1989 1989  watchpoint trap occurs.
1990 1990  .sp
1991 1991  .LP
1992 1992  If more than one of \fBWA_READ\fR, \fBWA_WRITE\fR, and \fBWA_EXEC\fR is
1993 1993  specified for a watched area, and a single instruction incurs more than one of
1994 1994  the specified types, only one is reported when the watchpoint trap occurs. The
1995 1995  precedence is \fBWA_EXEC\fR, \fBWA_READ\fR, \fBWA_WRITE\fR (\fBWA_EXEC\fR and
1996 1996  \fBWA_READ\fR take precedence over \fBWA_WRITE\fR), unless \fBWA_TRAPAFTER\fR
1997 1997  was specified, in which case it is \fBWA_WRITE\fR, \fBWA_READ\fR, \fBWA_EXEC\fR
1998 1998  (\fBWA_WRITE\fR takes precedence).
1999 1999  .sp
2000 2000  .LP
2001 2001  \fBPCWATCH\fR fails with \fBEINVAL\fR if an attempt is made to specify
2002 2002  overlapping watched areas or if \fBpr_wflags\fR contains flags other than those
2003 2003  specified above. It fails with \fBENOMEM\fR if an attempt is made to establish
2004 2004  more watched areas than the system can support (the system can support
2005 2005  thousands).
2006 2006  .sp
2007 2007  .LP
2008 2008  The child of a \fBvfork\fR(2) borrows the parent's address space. When a
2009 2009  \fBvfork\fR(2) is executed by a traced process, all watched areas established
2010 2010  for the parent are suspended until the child terminates or performs an
2011 2011  \fBexec\fR(2). Any watched areas established independently in the child are
2012 2012  cancelled when the parent resumes after the child's termination or
2013 2013  \fBexec\fR(2). \fBPCWATCH\fR fails with \fBEBUSY\fR if applied to the parent of
2014 2014  a \fBvfork\fR(2) before the child has terminated or performed an \fBexec\fR(2).
2015 2015  The \fBPR_VFORKP\fR flag is set in the \fBpstatus\fR structure for such a
2016 2016  parent process.
2017 2017  .sp
2018 2018  .LP
2019 2019  Certain accesses of the traced process's address space by the operating system
2020 2020  are immune to watchpoints. The initial construction of a signal stack frame
2021 2021  when a signal is delivered to an lwp will not trigger a watchpoint trap even if
2022 2022  the new frame covers watched areas of the stack. Once the signal handler is
2023 2023  entered, watchpoint traps occur normally. On SPARC based machines, register
2024 2024  window overflow and underflow will not trigger watchpoint traps, even if the
2025 2025  register window save areas cover watched areas of the stack.
2026 2026  .sp
2027 2027  .LP
2028 2028  Watched areas are not inherited by child processes, even if the traced
2029 2029  process's inherit-on-fork mode, \fBPR_FORK\fR, is set (see \fBPCSET\fR, below).
2030 2030  All watched areas are cancelled when the traced process performs a successful
2031 2031  \fBexec\fR(2).
2032 2032  .SS "PCSET PCUNSET"
2033 2033  .LP
2034 2034  \fBPCSET\fR sets one or more modes of operation for the traced process.
2035 2035  \fBPCUNSET\fR unsets these modes. The modes to be set or unset are specified by
2036 2036  flags in an operand \fBlong\fR in the control message:
2037 2037  .sp
2038 2038  .ne 2
2039 2039  .na
2040 2040  \fB\fBPR_FORK\fR\fR
2041 2041  .ad
2042 2042  .RS 13n
2043 2043  (inherit-on-fork): When set, the process's tracing flags and its
2044 2044  inherit-on-fork mode are inherited by the child of a \fBfork\fR(2),
2045 2045  \fBfork1\fR(2), or \fBvfork\fR(2). When unset, child processes start with all
2046 2046  tracing flags cleared.
2047 2047  .RE
2048 2048  
2049 2049  .sp
2050 2050  .ne 2
2051 2051  .na
2052 2052  \fB\fBPR_RLC\fR\fR
2053 2053  .ad
2054 2054  .RS 13n
2055 2055  (run-on-last-close): When set and the last writable \fB/proc\fR file descriptor
2056 2056  referring to the traced process or any of its lwps is closed, all of the
2057 2057  process's tracing flags and watched areas are cleared, any outstanding stop
2058 2058  directives are canceled, and if any lwps are stopped on events of interest,
2059 2059  they are set running as though \fBPCRUN\fR had been applied to them. When
2060 2060  unset, the process's tracing flags and watched areas are retained and lwps are
2061 2061  not set running on last close.
2062 2062  .RE
2063 2063  
2064 2064  .sp
2065 2065  .ne 2
2066 2066  .na
2067 2067  \fB\fBPR_KLC\fR\fR
2068 2068  .ad
2069 2069  .RS 13n
2070 2070  (kill-on-last-close): When set and the last writable \fB/proc\fR file
2071 2071  descriptor referring to the traced process or any of its lwps is closed, the
2072 2072  process is terminated with \fBSIGKILL\fR.
2073 2073  .RE
2074 2074  
2075 2075  .sp
2076 2076  .ne 2
2077 2077  .na
2078 2078  \fB\fBPR_ASYNC\fR\fR
2079 2079  .ad
2080 2080  .RS 13n
2081 2081  (asynchronous-stop): When set, a stop on an event of interest by one lwp does
2082 2082  not directly affect any other lwp in the process. When unset and an lwp stops
2083 2083  on an event of interest other than \fBPR_REQUESTED\fR, all other lwps in the
2084 2084  process are directed to stop.
2085 2085  .RE
2086 2086  
2087 2087  .sp
2088 2088  .ne 2
2089 2089  .na
2090 2090  \fB\fBPR_MSACCT\fR\fR
2091 2091  .ad
2092 2092  .RS 13n
2093 2093  (microstate accounting): Microstate accounting is now continuously enabled.
2094 2094  This flag is deprecated and no longer has any effect upon microstate
2095 2095  accounting. Applications may toggle this flag; however, microstate accounting
2096 2096  will remain enabled regardless.
2097 2097  .RE
2098 2098  
2099 2099  .sp
2100 2100  .ne 2
2101 2101  .na
2102 2102  \fB\fBPR_MSFORK\fR\fR
2103 2103  .ad
2104 2104  .RS 13n
2105 2105  (inherit microstate accounting): All processes now inherit microstate
2106 2106  accounting, as it is continuously enabled. This flag has been deprecated and
2107 2107  its use no longer has any effect upon the behavior of microstate accounting.
2108 2108  .RE
2109 2109  
2110 2110  .sp
2111 2111  .ne 2
2112 2112  .na
2113 2113  \fB\fBPR_BPTADJ\fR\fR
2114 2114  .ad
2115 2115  .RS 13n
2116 2116  (breakpoint trap pc adjustment): On x86-based machines, a breakpoint trap
2117 2117  leaves the program counter (the \fBEIP\fR) referring to the breakpointed
2118 2118  instruction plus one byte. When \fBPR_BPTADJ\fR is set, the system will adjust
2119 2119  the program counter back to the location of the breakpointed instruction when
2120 2120  the lwp stops on a breakpoint. This flag has no effect on SPARC based machines,
2121 2121  where breakpoint traps leave the program counter referring to the breakpointed
2122 2122  instruction.
2123 2123  .RE
2124 2124  
2125 2125  .sp
2126 2126  .ne 2
2127 2127  .na
2128 2128  \fB\fBPR_PTRACE\fR\fR
2129 2129  .ad
2130 2130  .RS 13n
2131 2131  (ptrace-compatibility): When set, a stop on an event of interest by the traced
2132 2132  process is reported to the parent of the traced process by \fBwait\fR(3C),
2133 2133  \fBSIGTRAP\fR is sent to the traced process when it executes a successful
2134 2134  \fBexec\fR(2), setuid/setgid flags are not honored for execs performed by the
2135 2135  traced process, any exec of an object file that the traced process cannot read
2136 2136  fails, and the process dies when its parent dies. This mode is deprecated; it
2137 2137  is provided only to allow \fBptrace\fR(3C) to be implemented as a library
2138 2138  function using \fB/proc\fR.
2139 2139  .RE
2140 2140  
2141 2141  .sp
2142 2142  .LP
2143 2143  It is an error (\fBEINVAL\fR) to specify flags other than those described above
2144 2144  or to apply these operations to a system process. The current modes are
2145 2145  reported in the \fBpr_flags\fR field of \fB/proc/\fR\fIpid\fR\fB/status\fR and
2146 2146  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwp\fR\fB/lwpstatus\fR.
2147 2147  .SS "PCSREG"
2148 2148  .LP
2149 2149  Set the general registers for the specific or representative lwp according to
2150 2150  the operand \fBprgregset_t\fR structure.
2151 2151  .sp
2152 2152  .LP
2153 2153  On SPARC based systems, only the condition-code bits of the processor-status
2154 2154  register (R_PSR) of SPARC V8 (32-bit) processes can be modified by
2155 2155  \fBPCSREG\fR. Other privileged registers cannot be modified at all.
2156 2156  .sp
2157 2157  .LP
2158 2158  On x86-based systems, only certain bits of the flags register (EFL) can be
2159 2159  modified by \fBPCSREG\fR: these include the condition codes, direction-bit, and
2160 2160  overflow-bit.
2161 2161  .sp
2162 2162  .LP
2163 2163  \fBPCSREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an event of
2164 2164  interest.
2165 2165  .SS "PCSVADDR"
2166 2166  .LP
2167 2167  Set the address at which execution will resume for the specific or
2168 2168  representative lwp from the operand \fBlong\fR. On SPARC based systems, both
2169 2169  %pc and %npc are set, with %npc set to the instruction following the virtual
2170 2170  address. On x86-based systems, only %eip is set. \fBPCSVADDR\fR fails with
2171 2171  \fBEBUSY\fR if the lwp is not stopped on an event of interest.
2172 2172  .SS "PCSFPREG"
2173 2173  .LP
2174 2174  Set the floating-point registers for the specific or representative lwp
2175 2175  according to the operand \fBprfpregset_t\fR structure. An error (\fBEINVAL\fR)
2176 2176  is returned if the system does not support floating-point operations (no
2177 2177  floating-point hardware and the system does not emulate floating-point machine
2178 2178  instructions). \fBPCSFPREG\fR fails with \fBEBUSY\fR if the lwp is not stopped
2179 2179  on an event of interest.
2180 2180  .SS "PCSXREG"
2181 2181  .LP
2182 2182  Set the extra state registers for the specific or representative lwp according
2183 2183  to the architecture-dependent operand \fBprxregset_t\fR structure. An error
2184 2184  (\fBEINVAL\fR) is returned if the system does not support extra state
2185 2185  registers. \fBPCSXREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an
2186 2186  event of interest.
2187 2187  .SS "PCSASRS"
2188 2188  .LP
2189 2189  Set the ancillary state registers for the specific or representative lwp
2190 2190  according to the SPARC V9 platform-dependent operand \fBasrset_t\fR structure.
2191 2191  An error (\fBEINVAL\fR) is returned if either the target process or the
2192 2192  controlling process is not a 64-bit SPARC V9 process. Most of the ancillary
2193 2193  state registers are privileged registers that cannot be modified. Only those
2194 2194  that can be modified are set; all others are silently ignored. \fBPCSASRS\fR
2195 2195  fails with \fBEBUSY\fR if the lwp is not stopped on an event of interest.
2196 2196  .SS "PCAGENT"
2197 2197  .LP
2198 2198  Create an agent lwp in the controlled process with register values from the
2199 2199  operand \fBprgregset_t\fR structure (see \fBPCSREG\fR, above). The agent lwp is
2200 2200  created in the stopped state showing \fBPR_REQUESTED\fR and with its held
2201 2201  signal set (the signal mask) having all signals except \fBSIGKILL\fR and
2202 2202  \fBSIGSTOP\fR blocked.
2203 2203  .sp
2204 2204  .LP
2205 2205  The \fBPCAGENT\fR operation fails with \fBEBUSY\fR unless the process is fully
2206 2206  stopped via \fB/proc\fR, that is, unless all of the lwps in the process are
2207 2207  stopped either on events of interest or on \fBPR_SUSPENDED\fR, or are stopped
2208 2208  on \fBPR_JOBCONTROL\fR and have been directed to stop via \fBPCDSTOP\fR.  It
2209 2209  fails with \fBEBUSY\fR if an agent lwp already exists. It fails with
2210 2210  \fBENOMEM\fR if system resources for creating new lwps have been exhausted.
2211 2211  .sp
2212 2212  .LP
2213 2213  Any \fBPCRUN\fR operation applied to the process control file or to the control
2214 2214  file of an lwp other than the agent lwp fails with \fBEBUSY\fR as long as the
2215 2215  agent lwp exists. The agent lwp must be caused to terminate by executing the
2216 2216  \fBSYS_lwp_exit\fR system call trap before the process can be restarted.
2217 2217  .sp
2218 2218  .LP
2219 2219  Once the agent lwp is created, its lwp-ID can be found by reading the process
2220 2220  status file. To facilitate opening the agent lwp's control and status files,
2221 2221  the directory name \fB/propc/\fR\fIpid\fR\fB/lwp/agent\fR is accepted for
2222 2222  lookup operations as an invisible alias for
2223 2223  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid,\fR \fIlwpid\fR being the lwp-ID of
2224 2224  the agent lwp (invisible in the sense that the name ``agent'' does not appear
2225 2225  in a directory listing of \fB/proc/\fR\fIpid\fR\fB/lwp\fR obtained from
2226 2226  \fBls\fR(1), \fBgetdents\fR(2), or \fBreaddir\fR(3C)).
2227 2227  .sp
2228 2228  .LP
2229 2229  The purpose of the agent lwp is to perform operations in the controlled process
2230 2230  on behalf of the controlling process: to gather information not directly
2231 2231  available via \fB/proc\fR files, or in general to make the process change state
2232 2232  in ways not directly available via \fB/proc\fR control operations. To make use
2233 2233  of an agent lwp, the controlling process must be capable of making it execute
2234 2234  system calls (specifically, the \fBSYS_lwp_exit\fR system call trap). The
2235 2235  register values given to the agent lwp on creation are typically the registers
2236 2236  of the representative lwp, so that the agent lwp can use its stack.
2237 2237  .sp
2238 2238  .LP
2239 2239  If the controlling process neglects to force the agent lwp to execute the
2240 2240  \fBSYS_lwp_exit\fR system call (due to either logic error or fatal failure on
2241 2241  the part of the controlling process), the agent lwp will remain in the target
2242 2242  process.  For purposes of being able to debug these otherwise rogue agents,
2243 2243  information as to the creator of the agent lwp is reflected in that lwp's
2244 2244  \fBspymaster\fR file in \fB/proc\fR. Should the target process generate a core
2245 2245  dump with the agent lwp in place, this information will be available via the
2246 2246  \fBNT_SPYMASTER\fR note in the core file (see \fBcore\fR(4)).
2247 2247  .sp
2248 2248  .LP
2249 2249  The agent lwp is not allowed to execute any variation of the \fBSYS_fork\fR or
2250 2250  \fBSYS_exec\fR system call traps. Attempts to do so yield \fBENOTSUP\fR to the
2251 2251  agent lwp.
2252 2252  .sp
2253 2253  .LP
2254 2254  Symbolic constants for system call trap numbers like \fBSYS_lwp_exit\fR and
2255 2255  \fBSYS_lwp_create\fR can be found in the header file <\fBsys/syscall.h\fR>.
2256 2256  .SS "PCREAD PCWRITE"
2257 2257  .LP
2258 2258  Read or write the target process's address space via a \fBpriovec\fR structure
2259 2259  operand:
2260 2260  .sp
2261 2261  .in +2
2262 2262  .nf
2263 2263  typedef struct priovec {
2264 2264      void *pio_base;      /* buffer in controlling process */
2265 2265      size_t pio_len;      /* size of read/write request in bytes */
2266 2266      off_t pio_offset;    /* virtual address in target process */
2267 2267  } priovec_t;
2268 2268  .fi
2269 2269  .in -2
2270 2270  
2271 2271  .sp
2272 2272  .LP
2273 2273  These operations have the same effect as \fBpread\fR(2) and \fBpwrite\fR(2),
2274 2274  respectively, of the target process's address space file. The difference is
2275 2275  that more than one \fBPCREAD\fR or \fBPCWRITE\fR control operation can be
2276 2276  written to the control file at once, and they can be interspersed with other
2277 2277  control operations in a single write to the control file. This is useful, for
2278 2278  example, when planting many breakpoint instructions in the process's address
2279 2279  space, or when stepping over a breakpointed instruction. Unlike \fBpread\fR(2)
2280 2280  and \fBpwrite\fR(2), no provision is made for partial reads or writes; if the
2281 2281  operation cannot be performed completely, it fails with \fBEIO\fR.
2282 2282  .SS "PCNICE"
2283 2283  .LP
2284 2284  The traced process's \fBnice\fR(2) value is incremented by the amount in the
2285 2285  operand \fBlong\fR. Only a process with the {\fBPRIV_PROC_PRIOCNTL\fR}
2286 2286  privilege asserted in its effective set can better a process's priority in this
2287 2287  way, but any user may lower the priority. This operation is not meaningful for
2288 2288  all scheduling classes.
2289 2289  .SS "PCSCRED"
2290 2290  .LP
2291 2291  Set the target process credentials to the values contained in the
2292 2292  \fBprcred_t\fR structure operand (see \fB/proc/\fR\fIpid\fR\fB/cred\fR). The
2293 2293  effective, real, and saved user-IDs and group-IDs of the target process are
2294 2294  set. The target process's supplementary groups are not changed; the
2295 2295  \fBpr_ngroups\fR and \fBpr_groups\fR members of the structure operand are
2296 2296  ignored. Only the privileged processes can perform this operation; for all
2297 2297  others it fails with \fBEPERM\fR.
2298 2298  .SS "PCSCREDX"
2299 2299  .LP
2300 2300  Operates like \fBPCSCRED\fR but also sets the supplementary groups; the length
2301 2301  of the data written with this control operation should be "sizeof
2302 2302  (\fBprcred_t\fR) + sizeof (\fBgid_t)\fR * (#groups - 1)".
2303 2303  .SS "PCSPRIV"
2304 2304  .LP
2305 2305  Set the target process privilege to the values contained in the \fBprpriv_t\fR
2306 2306  operand (see \fB/proc/pid/priv\fR). The effective, permitted, inheritable, and
2307 2307  limit sets are all changed. Privilege flags can also be set. The process is
2308 2308  made privilege aware unless it can relinquish privilege awareness. See
2309 2309  \fBprivileges\fR(5).
2310 2310  .sp
2311 2311  .LP
2312 2312  The limit set of the target process cannot be grown. The other privilege sets
2313 2313  must be subsets of the intersection of the effective set of the calling process
2314 2314  with the new limit set of the target process or subsets of the original values
2315 2315  of the sets in the target process.
2316 2316  .sp
2317 2317  .LP
2318 2318  If any of the above restrictions are not met, \fBEPERM\fR is returned. If the
2319 2319  structure written is improperly formatted, \fBEINVAL\fR is returned.
2320 2320  .SH PROGRAMMING NOTES
2321 2321  .LP
2322 2322  For security reasons, except for the \fBpsinfo\fR, \fBusage\fR, \fBlpsinfo\fR,
2323 2323  \fBlusage\fR, \fBlwpsinfo\fR, and \fBlwpusage\fR files, which are
2324 2324  world-readable, and except for privileged processes, an open of a \fB/proc\fR
2325 2325  file fails unless both the user-ID and group-ID of the caller match those of
2326 2326  the traced process and the process's object file is readable by the caller. The
2327 2327  effective set of the caller is a superset of both the inheritable and the
2328 2328  permitted set of the target process. The limit set of the caller is a superset
2329 2329  of the limit set of the target process. Except for the world-readable files
2330 2330  just mentioned, files corresponding to setuid and setgid processes can be
2331 2331  opened only by the appropriately privileged process.
2332 2332  .sp
2333 2333  .LP
2334 2334  A process that is missing the basic privilege {\fBPRIV_PROC_INFO\fR} cannot see
2335 2335  any processes under \fB/proc\fR that it cannot send a signal to.
2336 2336  .sp
2337 2337  .LP
2338 2338  A process that has {\fBPRIV_PROC_OWNER\fR} asserted in its effective set can
2339 2339  open any file for reading. To manipulate or control a process, the controlling
2340 2340  process must have at least as many privileges in its effective set as the
2341 2341  target process has in its effective, inheritable, and permitted sets. The limit
2342 2342  set of the controlling process must be a superset of the limit set of the
2343 2343  target process. Additional restrictions apply if any of the uids of the target
2344 2344  process are 0. See \fBprivileges\fR(5).
2345 2345  .sp
2346 2346  .LP
2347 2347  Even if held by a privileged process, an open process or lwp file descriptor
2348 2348  (other than file descriptors for the world-readable files) becomes invalid if
2349 2349  the traced process performs an \fBexec\fR(2) of a setuid/setgid object file or
2350 2350  an object file that the traced process cannot read. Any operation performed on
2351 2351  an invalid file descriptor, except \fBclose\fR(2), fails with \fBEAGAIN\fR. In
2352 2352  this situation, if any tracing flags are set and the process or any lwp file
2353 2353  descriptor is open for writing, the process will have been directed to stop and
2354 2354  its run-on-last-close flag will have been set (see \fBPCSET\fR). This enables a
2355 2355  controlling process (if it has permission) to reopen the \fB/proc\fR files to
2356 2356  get new valid file descriptors, close the invalid file descriptors, unset the
2357 2357  run-on-last-close flag (if desired), and proceed. Just closing the invalid file
2358 2358  descriptors causes the traced process to resume execution with all tracing
2359 2359  flags cleared. Any process not currently open for writing via \fB/proc\fR, but
2360 2360  that has left-over tracing flags from a previous open, and that executes a
2361 2361  setuid/setgid or unreadable object file, will not be stopped but will have all
2362 2362  its tracing flags cleared.
2363 2363  .sp
2364 2364  .LP
2365 2365  To wait for one or more of a set of processes or lwps to stop or terminate,
2366 2366  \fB/proc\fR file descriptors (other than those obtained by opening the
2367 2367  \fBcwd\fR or \fBroot\fR directories or by opening files in the \fBfd\fR or
2368 2368  \fBobject\fR directories) can be used in a \fBpoll\fR(2) system call. When
2369 2369  requested and returned, either of the polling events \fBPOLLPRI\fR or
2370 2370  \fBPOLLWRNORM\fR indicates that the process or lwp stopped on an event of
2371 2371  interest. Although they cannot be requested, the polling events \fBPOLLHUP\fR,
2372 2372  \fBPOLLERR\fR, and \fBPOLLNVAL\fR may be returned. \fBPOLLHUP\fR indicates that
2373 2373  the process or lwp has terminated. \fBPOLLERR\fR indicates that the file
2374 2374  descriptor has become invalid. \fBPOLLNVAL\fR is returned immediately if
2375 2375  \fBPOLLPRI\fR or \fBPOLLWRNORM\fR is requested on a file descriptor referring
2376 2376  to a system process (see \fBPCSTOP\fR). The requested events may be empty to
2377 2377  wait simply for termination.
2378 2378  .SH FILES
2379 2379  .ne 2
2380 2380  .na
2381 2381  \fB\fB/proc\fR\fR
2382 2382  .ad
2383 2383  .sp .6
2384 2384  .RS 4n
2385 2385  directory (list of processes)
2386 2386  .RE
2387 2387  
2388 2388  .sp
2389 2389  .ne 2
2390 2390  .na
2391 2391  \fB\fB/proc/\fIpid\fR\fR\fR
2392 2392  .ad
2393 2393  .sp .6
2394 2394  .RS 4n
2395 2395  specific process directory
2396 2396  .RE
2397 2397  
2398 2398  .sp
2399 2399  .ne 2
2400 2400  .na
2401 2401  \fB\fB/proc/self\fR\fR
2402 2402  .ad
2403 2403  .sp .6
2404 2404  .RS 4n
2405 2405  alias for a process's own directory
2406 2406  .RE
2407 2407  
2408 2408  .sp
2409 2409  .ne 2
2410 2410  .na
2411 2411  \fB\fB/proc/\fIpid\fR/as\fR\fR
2412 2412  .ad
2413 2413  .sp .6
2414 2414  .RS 4n
2415 2415  address space file
2416 2416  .RE
2417 2417  
2418 2418  .sp
2419 2419  .ne 2
2420 2420  .na
2421 2421  \fB\fB/proc/\fIpid\fR/ctl\fR\fR
2422 2422  .ad
2423 2423  .sp .6
2424 2424  .RS 4n
2425 2425  process control file
2426 2426  .RE
2427 2427  
2428 2428  .sp
2429 2429  .ne 2
2430 2430  .na
2431 2431  \fB\fB/proc/\fIpid\fR/status\fR\fR
2432 2432  .ad
2433 2433  .sp .6
2434 2434  .RS 4n
2435 2435  process status
2436 2436  .RE
2437 2437  
2438 2438  .sp
2439 2439  .ne 2
2440 2440  .na
2441 2441  \fB\fB/proc/\fIpid\fR/lstatus\fR\fR
2442 2442  .ad
2443 2443  .sp .6
2444 2444  .RS 4n
2445 2445  array of lwp status structs
2446 2446  .RE
2447 2447  
2448 2448  .sp
2449 2449  .ne 2
2450 2450  .na
2451 2451  \fB\fB/proc/\fIpid\fR/psinfo\fR\fR
2452 2452  .ad
2453 2453  .sp .6
2454 2454  .RS 4n
2455 2455  process \fBps\fR(1) info
2456 2456  .RE
2457 2457  
2458 2458  .sp
2459 2459  .ne 2
2460 2460  .na
2461 2461  \fB\fB/proc/\fIpid\fR/lpsinfo\fR\fR
2462 2462  .ad
2463 2463  .sp .6
2464 2464  .RS 4n
2465 2465  array of lwp \fBps\fR(1) info structs
2466 2466  .RE
2467 2467  
2468 2468  .sp
2469 2469  .ne 2
2470 2470  .na
2471 2471  \fB\fB/proc/\fIpid\fR/map\fR\fR
2472 2472  .ad
2473 2473  .sp .6
2474 2474  .RS 4n
2475 2475  address space map
2476 2476  .RE
2477 2477  
2478 2478  .sp
2479 2479  .ne 2
2480 2480  .na
2481 2481  \fB\fB/proc/\fIpid\fR/xmap\fR\fR
2482 2482  .ad
2483 2483  .sp .6
2484 2484  .RS 4n
2485 2485  extended address space map
2486 2486  .RE
2487 2487  
2488 2488  .sp
2489 2489  .ne 2
2490 2490  .na
2491 2491  \fB\fB/proc/\fIpid\fR/rmap\fR\fR
2492 2492  .ad
2493 2493  .sp .6
2494 2494  .RS 4n
2495 2495  reserved address map
2496 2496  .RE
2497 2497  
2498 2498  .sp
2499 2499  .ne 2
2500 2500  .na
2501 2501  \fB\fB/proc/\fIpid\fR/cred\fR\fR
2502 2502  .ad
2503 2503  .sp .6
2504 2504  .RS 4n
2505 2505  process credentials
2506 2506  .RE
2507 2507  
2508 2508  .sp
2509 2509  .ne 2
2510 2510  .na
2511 2511  \fB\fB/proc/\fIpid\fR/priv\fR\fR
2512 2512  .ad
2513 2513  .sp .6
2514 2514  .RS 4n
2515 2515  process privileges
2516 2516  .RE
2517 2517  
2518 2518  .sp
2519 2519  .ne 2
2520 2520  .na
2521 2521  \fB\fB/proc/\fIpid\fR/sigact\fR\fR
2522 2522  .ad
2523 2523  .sp .6
2524 2524  .RS 4n
2525 2525  process signal actions
2526 2526  .RE
2527 2527  
2528 2528  .sp
2529 2529  .ne 2
2530 2530  .na
2531 2531  \fB\fB/proc/\fIpid\fR/auxv\fR\fR
2532 2532  .ad
2533 2533  .sp .6
2534 2534  .RS 4n
2535 2535  process aux vector
2536 2536  .RE
2537 2537  
2538 2538  .sp
2539 2539  .ne 2
2540 2540  .na
2541 2541  \fB\fB/proc/\fIpid\fR/ldt\fR\fR
2542 2542  .ad
2543 2543  .sp .6
2544 2544  .RS 4n
2545 2545  process \fBLDT\fR (x86 only)
2546 2546  .RE
2547 2547  
2548 2548  .sp
2549 2549  .ne 2
2550 2550  .na
2551 2551  \fB\fB/proc/\fIpid\fR/usage\fR\fR
2552 2552  .ad
2553 2553  .sp .6
2554 2554  .RS 4n
2555 2555  process usage
2556 2556  .RE
2557 2557  
2558 2558  .sp
2559 2559  .ne 2
2560 2560  .na
2561 2561  \fB\fB/proc/\fIpid\fR/lusage\fR\fR
2562 2562  .ad
2563 2563  .sp .6
2564 2564  .RS 4n
2565 2565  array of lwp usage structs
2566 2566  .RE
2567 2567  
2568 2568  .sp
2569 2569  .ne 2
2570 2570  .na
2571 2571  \fB\fB/proc/\fIpid\fR/path\fR\fR
2572 2572  .ad
2573 2573  .sp .6
2574 2574  .RS 4n
2575 2575  symbolic links to process open files
2576 2576  .RE
2577 2577  
2578 2578  .sp
2579 2579  .ne 2
2580 2580  .na
2581 2581  \fB\fB/proc/\fIpid\fR/pagedata\fR\fR
2582 2582  .ad
2583 2583  .sp .6
2584 2584  .RS 4n
2585 2585  process page data
2586 2586  .RE
2587 2587  
2588 2588  .sp
2589 2589  .ne 2
2590 2590  .na
2591 2591  \fB\fB/proc/\fIpid\fR/watch\fR\fR
2592 2592  .ad
2593 2593  .sp .6
2594 2594  .RS 4n
2595 2595  active watchpoints
2596 2596  .RE
2597 2597  
2598 2598  .sp
2599 2599  .ne 2
2600 2600  .na
2601 2601  \fB\fB/proc/\fIpid\fR/cwd\fR\fR
2602 2602  .ad
2603 2603  .sp .6
2604 2604  .RS 4n
2605 2605  alias for the current working directory
2606 2606  .RE
2607 2607  
2608 2608  .sp
2609 2609  .ne 2
2610 2610  .na
2611 2611  \fB\fB/proc/\fIpid\fR/root\fR\fR
2612 2612  .ad
2613 2613  .sp .6
2614 2614  .RS 4n
2615 2615  alias for the root directory
2616 2616  .RE
2617 2617  
2618 2618  .sp
2619 2619  .ne 2
2620 2620  .na
2621 2621  \fB\fB/proc/\fIpid\fR/fd\fR\fR
2622 2622  .ad
2623 2623  .sp .6
2624 2624  .RS 4n
2625 2625  directory (list of open files)
2626 2626  .RE
2627 2627  
2628 2628  .sp
2629 2629  .ne 2
2630 2630  .na
2631 2631  \fB\fB/proc/\fIpid\fR/fd/*\fR\fR
2632 2632  .ad
2633 2633  .sp .6
2634 2634  .RS 4n
2635 2635  aliases for process's open files
2636 2636  .RE
2637 2637  
2638 2638  .sp
2639 2639  .ne 2
2640 2640  .na
2641 2641  \fB\fB/proc/\fIpid\fR/object\fR\fR
2642 2642  .ad
2643 2643  .sp .6
2644 2644  .RS 4n
2645 2645  directory (list of mapped files)
2646 2646  .RE
2647 2647  
2648 2648  .sp
2649 2649  .ne 2
2650 2650  .na
2651 2651  \fB\fB/proc/\fIpid\fR/object/a.out\fR\fR
2652 2652  .ad
2653 2653  .sp .6
2654 2654  .RS 4n
2655 2655  alias for process's executable file
2656 2656  .RE
2657 2657  
2658 2658  .sp
2659 2659  .ne 2
2660 2660  .na
2661 2661  \fB\fB/proc/\fIpid\fR/object/*\fR\fR
2662 2662  .ad
2663 2663  .sp .6
2664 2664  .RS 4n
2665 2665  aliases for other mapped files
2666 2666  .RE
2667 2667  
2668 2668  .sp
2669 2669  .ne 2
2670 2670  .na
2671 2671  \fB\fB/proc/\fIpid\fR/lwp\fR\fR
2672 2672  .ad
2673 2673  .sp .6
2674 2674  .RS 4n
2675 2675  directory (list of lwps)
2676 2676  .RE
2677 2677  
2678 2678  .sp
2679 2679  .ne 2
2680 2680  .na
2681 2681  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR\fR\fR
2682 2682  .ad
2683 2683  .sp .6
2684 2684  .RS 4n
2685 2685  specific lwp directory
2686 2686  .RE
2687 2687  
2688 2688  .sp
2689 2689  .ne 2
2690 2690  .na
2691 2691  \fB\fB/proc/\fIpid\fR/lwp/agent\fR\fR
2692 2692  .ad
2693 2693  .sp .6
2694 2694  .RS 4n
2695 2695  alias for the agent lwp directory
2696 2696  .RE
2697 2697  
2698 2698  .sp
2699 2699  .ne 2
2700 2700  .na
2701 2701  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpctl\fR\fR
2702 2702  .ad
2703 2703  .sp .6
2704 2704  .RS 4n
2705 2705  lwp control file
2706 2706  .RE
2707 2707  
2708 2708  .sp
2709 2709  .ne 2
2710 2710  .na
2711 2711  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpstatus\fR\fR
2712 2712  .ad
2713 2713  .sp .6
2714 2714  .RS 4n
2715 2715  lwp status
2716 2716  .RE
2717 2717  
2718 2718  .sp
2719 2719  .ne 2
2720 2720  .na
2721 2721  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpsinfo\fR\fR
2722 2722  .ad
2723 2723  .sp .6
2724 2724  .RS 4n
2725 2725  lwp \fBps\fR(1) info
2726 2726  .RE
2727 2727  
2728 2728  .sp
2729 2729  .ne 2
2730 2730  .na
2731 2731  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpusage\fR\fR
2732 2732  .ad
2733 2733  .sp .6
2734 2734  .RS 4n
2735 2735  lwp usage
2736 2736  .RE
2737 2737  
2738 2738  .sp
2739 2739  .ne 2
2740 2740  .na
2741 2741  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/gwindows\fR\fR
2742 2742  .ad
2743 2743  .sp .6
2744 2744  .RS 4n
2745 2745  register windows (SPARC only)
2746 2746  .RE
2747 2747  
2748 2748  .sp
2749 2749  .ne 2
2750 2750  .na
2751 2751  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/xregs\fR\fR
2752 2752  .ad
2753 2753  .sp .6
2754 2754  .RS 4n
2755 2755  extra state registers
2756 2756  .RE
2757 2757  
2758 2758  .sp
2759 2759  .ne 2
2760 2760  .na
2761 2761  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/asrs\fR\fR
2762 2762  .ad
2763 2763  .sp .6
2764 2764  .RS 4n
2765 2765  ancillary state registers (SPARC V9 only)
2766 2766  .RE
2767 2767  
2768 2768  .sp
2769 2769  .ne 2
2770 2770  .na
2771 2771  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/spymaster\fR\fR
2772 2772  .ad
2773 2773  .sp .6
2774 2774  .RS 4n
2775 2775  For an agent LWP, the controlling process
2776 2776  .RE
2777 2777  
2778 2778  .SH SEE ALSO
2779 2779  .LP
2780 2780  \fBls\fR(1), \fBps\fR(1), \fBchroot\fR(1M), \fBalarm\fR(2), \fBbrk\fR(2),
2781 2781  \fBchdir\fR(2), \fBchroot\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2),
2782 2782  \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2), \fBfork1\fR(2), \fBfstat\fR(2),
2783 2783  \fBgetdents\fR(2), \fBgetustack\fR(2), \fBkill\fR(2), \fBlseek\fR(2),
2784 2784  \fBmmap\fR(2), \fBnice\fR(2), \fBopen\fR(2), \fBpoll\fR(2), \fBpread\fR(2),
2785 2785  \fBptrace\fR(3C), \fBpwrite\fR(2), \fBread\fR(2), \fBreadlink\fR(2),
2786 2786  \fBreadv\fR(2), \fBshmget\fR(2), \fBsigaction\fR(2), \fBsigaltstack\fR(2),
2787 2787  \fBvfork\fR(2), \fBwrite\fR(2), \fBwritev\fR(2), \fB_stack_grow\fR(3C),
2788 2788  \fBreaddir\fR(3C), \fBpthread_create\fR(3C), \fBpthread_join\fR(3C),
2789 2789  \fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), \fBthr_create\fR(3C),
2790 2790  \fBthr_join\fR(3C), \fBtypes32.h\fR(3HEAD), \fBucontext.h\fR(3HEAD),
2791 2791  \fBwait\fR(3C), \fBcontract\fR(4), \fBcore\fR(4), \fBprocess\fR(4),
2792 2792  \fBlfcompile\fR(5), \fBprivileges\fR(5), \fBsecurity-flags\fR(5)
2793 2793  .SH DIAGNOSTICS
2794 2794  .LP
2795 2795  Errors that can occur in addition to the errors normally associated with file
2796 2796  system access:
2797 2797  .sp
2798 2798  .ne 2
2799 2799  .na
2800 2800  \fB\fBE2BIG\fR\fR
2801 2801  .ad
2802 2802  .RS 13n
2803 2803  Data to be returned in a \fBread\fR(2) of the page data file exceeds the size
2804 2804  of the read buffer provided by the caller.
2805 2805  .RE
2806 2806  
2807 2807  .sp
2808 2808  .ne 2
2809 2809  .na
2810 2810  \fB\fBEACCES\fR\fR
2811 2811  .ad
2812 2812  .RS 13n
2813 2813  An attempt was made to examine a process that ran under a different uid than
2814 2814  the controlling process and {\fBPRIV_PROC_OWNER\fR} was not asserted in the
2815 2815  effective set.
2816 2816  .RE
2817 2817  
2818 2818  .sp
2819 2819  .ne 2
2820 2820  .na
2821 2821  \fB\fBEAGAIN\fR\fR
2822 2822  .ad
2823 2823  .RS 13n
2824 2824  The traced process has performed an \fBexec\fR(2) of a setuid/setgid object
2825 2825  file or of an object file that it cannot read; all further operations on the
2826 2826  process or lwp file descriptor (except \fBclose\fR(2)) elicit this error.
2827 2827  .RE
2828 2828  
2829 2829  .sp
2830 2830  .ne 2
2831 2831  .na
2832 2832  \fB\fBEBUSY\fR\fR
2833 2833  .ad
2834 2834  .RS 13n
2835 2835  \fBPCSTOP\fR, \fBPCDSTOP\fR, \fBPCWSTOP\fR, or \fBPCTWSTOP\fR was applied to a
2836 2836  system process; an exclusive \fBopen\fR(2) was attempted on a \fB/proc\fR file
2837 2837  for a process already open for writing; \fBPCRUN\fR, \fBPCSREG\fR,
2838 2838  \fBPCSVADDR\fR, \fBPCSFPREG\fR, or \fBPCSXREG\fR was applied to a process or
2839 2839  lwp not stopped on an event of interest; an attempt was made to mount
2840 2840  \fB/proc\fR when it was already mounted; \fBPCAGENT\fR was applied to a process
2841 2841  that was not fully stopped or that already had an agent lwp.
2842 2842  .RE
2843 2843  
2844 2844  .sp
2845 2845  .ne 2
2846 2846  .na
2847 2847  \fB\fBEINVAL\fR\fR
2848 2848  .ad
2849 2849  .RS 13n
2850 2850  In general, this means that some invalid argument was supplied to a system
2851 2851  call. A non-exhaustive list of conditions eliciting this error includes: a
2852 2852  control message operation code is undefined; an out-of-range signal number was
2853 2853  specified with \fBPCSSIG\fR, \fBPCKILL\fR, or \fBPCUNKILL\fR; \fBSIGKILL\fR was
2854 2854  specified with \fBPCUNKILL\fR; \fBPCSFPREG\fR was applied on a system that does
2855 2855  not support floating-point operations; \fBPCSXREG\fR was applied on a system
2856 2856  that does not support extra state registers.
2857 2857  .RE
2858 2858  
2859 2859  .sp
2860 2860  .ne 2
2861 2861  .na
2862 2862  \fB\fBEINTR\fR\fR
2863 2863  .ad
2864 2864  .RS 13n
2865 2865  A signal was received by the controlling process while waiting for the traced
2866 2866  process or lwp to stop via \fBPCSTOP\fR, \fBPCWSTOP\fR, or \fBPCTWSTOP\fR.
2867 2867  .RE
2868 2868  
2869 2869  .sp
2870 2870  .ne 2
2871 2871  .na
2872 2872  \fB\fBEIO\fR\fR
2873 2873  .ad
2874 2874  .RS 13n
2875 2875  A \fBwrite\fR(2) was attempted at an illegal address in the traced process.
2876 2876  .RE
2877 2877  
2878 2878  .sp
2879 2879  .ne 2
2880 2880  .na
2881 2881  \fB\fBENOENT\fR\fR
2882 2882  .ad
2883 2883  .RS 13n
2884 2884  The traced process or lwp has terminated after being opened. The basic
2885 2885  privilege {\fBPRIV_PROC_INFO\fR} is not asserted in the effective set of the
2886 2886  calling process and the calling process cannot send a signal to the target
2887 2887  process.
2888 2888  .RE
2889 2889  
2890 2890  .sp
2891 2891  .ne 2
2892 2892  .na
2893 2893  \fB\fBENOMEM\fR\fR
2894 2894  .ad
2895 2895  .RS 13n
2896 2896  The system-imposed limit on the number of page data file descriptors was
2897 2897  reached on an open of \fB/proc/\fR\fIpid\fR\fB/pagedata\fR; an attempt was made
2898 2898  with \fBPCWATCH\fR to establish more watched areas than the system can support;
2899 2899  the \fBPCAGENT\fR operation was issued when the system was out of resources for
2900 2900  creating lwps.
2901 2901  .RE
2902 2902  
2903 2903  .sp
2904 2904  .ne 2
2905 2905  .na
2906 2906  \fB\fBENOSYS\fR\fR
2907 2907  .ad
2908 2908  .RS 13n
2909 2909  An attempt was made to perform an unsupported operation (such as
2910 2910  \fBcreat\fR(2), \fBlink\fR(2), or \fBunlink\fR(2)) on an entry in \fB/proc\fR.
2911 2911  .RE
2912 2912  
2913 2913  .sp
2914 2914  .ne 2
2915 2915  .na
2916 2916  \fB\fBEOVERFLOW\fR\fR
2917 2917  .ad
2918 2918  .RS 13n
2919 2919  A 32-bit controlling process attempted to read or write the \fBas\fR file or
2920 2920  attempted to read the \fBmap\fR, \fBrmap\fR, or \fBpagedata\fR file of a 64-bit
2921 2921  target process. A 32-bit controlling process attempted to apply one of the
2922 2922  control operations \fBPCSREG\fR, \fBPCSXREG\fR, \fBPCSVADDR\fR, \fBPCWATCH\fR,
2923 2923  \fBPCAGENT\fR, \fBPCREAD\fR, \fBPCWRITE\fR to a 64-bit target process.
2924 2924  .RE
2925 2925  
2926 2926  .sp
2927 2927  .ne 2
2928 2928  .na
2929 2929  \fB\fBEPERM\fR\fR
2930 2930  .ad
2931 2931  .RS 13n
2932 2932  The process that issued the \fBPCSCRED\fR or \fBPCSCREDX\fR operation did not
2933 2933  have the {\fBPRIV_PROC_SETID\fR} privilege asserted in its effective set, or
2934 2934  the process that issued the \fBPCNICE\fR operation did not have the
2935 2935  {\fBPRIV_PROC_PRIOCNTL\fR} in its effective set.
2936 2936  .sp
2937 2937  An attempt was made to control a process of which the E, P, and I privilege
2938 2938  sets were not a subset of the effective set of the controlling process or the
2939 2939  limit set of the controlling process is not a superset of limit set of the
2940 2940  controlled process.
2941 2941  .sp
2942 2942  Any of the uids of the target process are 0 or an attempt was made to change
2943 2943  any of the uids to 0 using PCSCRED and the security policy imposed additional
2944 2944  restrictions. See \fBprivileges\fR(5).
2945 2945  .RE
2946 2946  
2947 2947  .SH NOTES
2948 2948  .LP
2949 2949  Descriptions of structures in this document include only interesting structure
2950 2950  elements, not filler and padding fields, and may show elements out of order for
2951 2951  descriptive clarity. The actual structure definitions are contained in
2952 2952  \fB<procfs.h>\fR\&.
2953 2953  .SH BUGS
2954 2954  .LP
2955 2955  Because the old \fBioctl\fR(2)-based version of \fB/proc\fR is currently
2956 2956  supported for binary compatibility with old applications, the top-level
2957 2957  directory for a process, \fB/proc/\fR\fIpid\fR, is not world-readable, but it
2958 2958  is world-searchable. Thus, anyone can open \fB/proc/\fR\fIpid\fR\fB/psinfo\fR
2959 2959  even though \fBls\fR(1) applied to \fB/proc/\fR\fIpid\fR will fail for anyone
2960 2960  but the owner or an appropriately privileged process. Support for the old
2961 2961  \fBioctl\fR(2)-based version of \fB/proc\fR will be dropped in a future
2962 2962  release, at which time the top-level directory for a process will be made
2963 2963  world-readable.
2964 2964  .sp
2965 2965  .LP
2966 2966  On SPARC based machines, the types \fBgregset_t\fR and \fBfpregset_t\fR defined
2967 2967  in <\fBsys/regset.h\fR> are similar to but not the same as the types
2968 2968  \fBprgregset_t\fR and \fBprfpregset_t\fR defined in <\fBprocfs.h\fR>.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX