8158 Want named threads API
9857 proc manpages should have LIBRARY section

          --- 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      -.\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
        4 +.\" Copyright 2018, Joyent, Inc.
   5    5  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6    6  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7    7  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8      -.TH PROC 4 "Jun 6, 2016"
        8 +.TH PROC 4 "August 22, 2018"
   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      -    lwpsinfo_t pr_lwp;       /* information for representative lwp */
 898  897      taskid_t pr_taskid;      /* task id */
 899  898      projid_t pr_projid;      /* project id */
 900  899      poolid_t pr_poolid;      /* pool id */
 901  900      zoneid_t pr_zoneid;      /* zone id */
 902  901      ctid_t pr_contract;      /* process contract id */
      902 +    lwpsinfo_t pr_lwp;       /* information for representative lwp */
 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 +.SS lwpname
     1488 +A buffer of \fBTHREAD_NAME_MAX\fR bytes representing the LWP name; the buffer is
     1489 +zero-filled if the thread name is shorter than the buffer. If no thread name is
     1490 +set, the buffer contains the empty string. A read with a buffer shorter than
     1491 +\fBTHREAD_NAME_MAX\fR bytes is not guaranteed to be NUL-terminated.  Writing to
     1492 +this file will set the LWP name for the specific lwp.  This file may not be
     1493 +present in older operating system versions. \fBTHREAD_NAME_MAX\fR may increase
     1494 +in the future; clients should be prepared for this.
1487 1495  .SS "lwpstatus"
1488 1496  .LP
1489 1497  lwp-specific state information. This file contains the \fBlwpstatus\fR
1490 1498  structure for the specific lwp as described above for the representative lwp in
1491 1499  the process's \fBstatus\fR file.
1492 1500  .SS "lwpsinfo"
1493 1501  .LP
1494 1502  lwp-specific \fBps\fR(1) information. This file contains the \fBlwpsinfo\fR
1495 1503  structure for the specific lwp as described above for the representative lwp in
1496 1504  the process's \fBpsinfo\fR file. The \fBlwpsinfo\fR file remains accessible

1497 1505  after an lwp becomes a zombie.
1498 1506  .SS "lwpusage"
1499 1507  .LP
1500 1508  This file contains the \fBprusage\fR structure for the specific lwp as
1501 1509  described above for the process's \fBusage\fR file.
1502 1510  .SS "gwindows"
1503 1511  .LP
1504 1512  This file exists only on SPARC based machines. If it is non-empty, it contains
1505 1513  a \fBgwindows_t\fR structure, defined in \fB<sys/regset.h>\fR, with the values
1506 1514  of those SPARC register windows that could not be stored on the stack when the
1507 1515  lwp stopped. Conditions under which register windows are not stored on the
1508 1516  stack are: the stack pointer refers to nonexistent process memory or the stack
1509 1517  pointer is improperly aligned. If the lwp is not stopped or if there are no
1510 1518  register windows that could not be stored on the stack, the file is empty (the
1511 1519  usual case).
1512 1520  .SS "xregs"
1513 1521  .LP
1514 1522  Extra state registers. The extra state register set is architecture dependent;
1515 1523  this file is empty if the system does not support extra state registers. If the
1516 1524  file is non-empty, it contains an architecture dependent structure of type
1517 1525  \fBprxregset_t\fR, defined in \fB<procfs.h>\fR, with the values of the lwp's
1518 1526  extra state registers. If the lwp is not stopped, all register values are
1519 1527  undefined. See also the \fBPCSXREG\fR control operation, below.
1520 1528  .SS "asrs"
1521 1529  .LP
1522 1530  This file exists only for 64-bit SPARC V9 processes. It contains an
1523 1531  \fBasrset_t\fR structure, defined in <\fBsys/regset.h\fR>, containing the
1524 1532  values of the lwp's platform-dependent ancillary state registers. If the lwp is
1525 1533  not stopped, all register values are undefined. See also the \fBPCSASRS\fR
1526 1534  control operation, below.
1527 1535  .SS "spymaster"
1528 1536  .LP
1529 1537  For an agent lwp (see \fBPCAGENT\fR), this file contains a \fBpsinfo_t\fR
1530 1538  structure that corresponds to the process that created the agent lwp at the
1531 1539  time the agent was created. This structure is identical to that retrieved via
1532 1540  the \fBpsinfo\fR file, with one modification: the \fBpr_time\fR field does not
1533 1541  correspond to the CPU time for the process, but rather to the creation time of
1534 1542  the agent lwp.
1535 1543  .SS "templates"
1536 1544  .LP
1537 1545  A directory which contains references to the active templates for the lwp,
1538 1546  named by the contract type. Changes made to an active template descriptor do
1539 1547  not affect the original template which was activated, though they do affect the
1540 1548  active template. It is not possible to activate an active template descriptor.
1541 1549  See \fBcontract\fR(4).
1542 1550  .SH CONTROL MESSAGES
1543 1551  .LP
1544 1552  Process state changes are effected through messages written to a process's
1545 1553  \fBctl\fR file or to an individual lwp's \fBlwpctl\fR file. All control
1546 1554  messages consist of a \fBlong\fR that names the specific operation followed by
1547 1555  additional data containing the operand, if any.
1548 1556  .sp
1549 1557  .LP
1550 1558  Multiple control messages may be combined in a single \fBwrite\fR(2) (or
1551 1559  \fBwritev\fR(2)) to a control file, but no partial writes are permitted. That
1552 1560  is, each control message, operation code plus operand, if any, must be
1553 1561  presented in its entirety to the \fBwrite\fR(2) and not in pieces over several
1554 1562  system calls. If a control operation fails, no subsequent operations contained
1555 1563  in the same \fBwrite\fR(2) are attempted.
1556 1564  .sp
1557 1565  .LP
1558 1566  Descriptions of the allowable control messages follow. In all cases, writing a
1559 1567  message to a control file for a process or lwp that has terminated elicits the
1560 1568  error \fBENOENT\fR.
1561 1569  .SS "PCSTOP PCDSTOP PCWSTOP PCTWSTOP"
1562 1570  .LP
1563 1571  When applied to the process control file, \fBPCSTOP\fR directs all lwps to stop
1564 1572  and waits for them to stop, \fBPCDSTOP\fR directs all lwps to stop without
1565 1573  waiting for them to stop, and \fBPCWSTOP\fR simply waits for all lwps to stop.
1566 1574  When applied to an lwp control file, \fBPCSTOP\fR directs the specific lwp to
1567 1575  stop and waits until it has stopped, \fBPCDSTOP\fR directs the specific lwp to
1568 1576  stop without waiting for it to stop, and \fBPCWSTOP\fR simply waits for the
1569 1577  specific lwp to stop. When applied to an lwp control file, \fBPCSTOP\fR and
1570 1578  \fBPCWSTOP\fR complete when the lwp stops on an event of interest, immediately
1571 1579  if already so stopped; when applied to the process control file, they complete
1572 1580  when every lwp has stopped either on an event of interest or on a
1573 1581  \fBPR_SUSPENDED\fR stop.
1574 1582  .sp
1575 1583  .LP
1576 1584  \fBPCTWSTOP\fR is identical to \fBPCWSTOP\fR except that it enables the
1577 1585  operation to time out, to avoid waiting forever for a process or lwp that may
1578 1586  never stop on an event of interest. \fBPCTWSTOP\fR takes a \fBlong\fR operand
1579 1587  specifying a number of milliseconds; the wait will terminate successfully after
1580 1588  the specified number of milliseconds even if the process or lwp has not
1581 1589  stopped; a timeout value of zero makes the operation identical to
1582 1590  \fBPCWSTOP\fR.
1583 1591  .sp
1584 1592  .LP
1585 1593  An ``event of interest'' is either a \fBPR_REQUESTED\fR stop or a stop that has
1586 1594  been specified in the process's tracing flags (set by \fBPCSTRACE\fR,
1587 1595  \fBPCSFAULT\fR, \fBPCSENTRY\fR, and \fBPCSEXIT\fR). \fBPR_JOBCONTROL\fR and
1588 1596  \fBPR_SUSPENDED\fR stops are specifically not events of interest. (An lwp may
1589 1597  stop twice due to a stop signal, first showing \fBPR_SIGNALLED\fR if the signal
1590 1598  is traced and again showing \fBPR_JOBCONTROL\fR if the lwp is set running
1591 1599  without clearing the signal.) If \fBPCSTOP\fR or \fBPCDSTOP\fR is applied to an
1592 1600  lwp that is stopped, but not on an event of interest, the stop directive takes
1593 1601  effect when the lwp is restarted by the competing mechanism. At that time, the
1594 1602  lwp enters a \fBPR_REQUESTED\fR stop before executing any user-level code.
1595 1603  .sp
1596 1604  .LP
1597 1605  A write of a control message that blocks is interruptible by a signal so that,
1598 1606  for example, an \fBalarm\fR(2) can be set to avoid waiting forever for a
1599 1607  process or lwp that may never stop on an event of interest. If \fBPCSTOP\fR is
1600 1608  interrupted, the lwp stop directives remain in effect even though the
1601 1609  \fBwrite\fR(2) returns an error. (Use of \fBPCTWSTOP\fR with a non-zero timeout
1602 1610  is recommended over \fBPCWSTOP\fR with an \fBalarm\fR(2).)
1603 1611  .sp
1604 1612  .LP
1605 1613  A system process (indicated by the \fBPR_ISSYS\fR flag) never executes at user
1606 1614  level, has no user-level address space visible through \fB/proc\fR, and cannot
1607 1615  be stopped. Applying one of these operations to a system process or any of its
1608 1616  lwps elicits the error \fBEBUSY\fR.
1609 1617  .SS "PCRUN"
1610 1618  .LP
1611 1619  Make an lwp runnable again after a stop. This operation takes a \fBlong\fR
1612 1620  operand containing zero or more of the following flags:
1613 1621  .sp
1614 1622  .ne 2
1615 1623  .na
1616 1624  \fB\fBPRCSIG\fR\fR
1617 1625  .ad
1618 1626  .RS 12n
1619 1627  clears the current signal, if any (see \fBPCCSIG\fR).
1620 1628  .RE
1621 1629  
1622 1630  .sp
1623 1631  .ne 2
1624 1632  .na
1625 1633  \fB\fBPRCFAULT\fR\fR
1626 1634  .ad
1627 1635  .RS 12n
1628 1636  clears the current fault, if any (see \fBPCCFAULT\fR).
1629 1637  .RE
1630 1638  
1631 1639  .sp
1632 1640  .ne 2
1633 1641  .na
1634 1642  \fB\fBPRSTEP\fR\fR
1635 1643  .ad
1636 1644  .RS 12n
1637 1645  directs the lwp to execute a single machine instruction. On completion of the
1638 1646  instruction, a trace trap occurs. If \fBFLTTRACE\fR is being traced, the lwp
1639 1647  stops; otherwise, it is sent \fBSIGTRAP\fR. If \fBSIGTRAP\fR is being traced
1640 1648  and is not blocked, the lwp stops. When the lwp stops on an event of interest,
1641 1649  the single-step directive is cancelled, even if the stop occurs before the
1642 1650  instruction is executed. This operation requires hardware and operating system
1643 1651  support and may not be implemented on all processors. It is implemented on
1644 1652  SPARC and x86-based machines.
1645 1653  .RE
1646 1654  
1647 1655  .sp
1648 1656  .ne 2
1649 1657  .na
1650 1658  \fB\fBPRSABORT\fR\fR
1651 1659  .ad
1652 1660  .RS 12n
1653 1661  is meaningful only if the lwp is in a \fBPR_SYSENTRY\fR stop or is marked
1654 1662  \fBPR_ASLEEP\fR; it instructs the lwp to abort execution of the system call
1655 1663  (see \fBPCSENTRY\fR and \fBPCSEXIT\fR).
1656 1664  .RE
1657 1665  
1658 1666  .sp
1659 1667  .ne 2
1660 1668  .na
1661 1669  \fB\fBPRSTOP\fR\fR
1662 1670  .ad
1663 1671  .RS 12n
1664 1672  directs the lwp to stop again as soon as possible after resuming execution (see
1665 1673  \fBPCDSTOP\fR). In particular, if the lwp is stopped on \fBPR_SIGNALLED\fR or
1666 1674  \fBPR_FAULTED\fR, the next stop will show \fBPR_REQUESTED\fR, no other stop
1667 1675  will have intervened, and the lwp will not have executed any user-level code.
1668 1676  .RE
1669 1677  
1670 1678  .sp
1671 1679  .LP
1672 1680  When applied to an lwp control file, \fBPCRUN\fR clears any outstanding
1673 1681  directed-stop request and makes the specific lwp runnable. The operation fails
1674 1682  with \fBEBUSY\fR if the specific lwp is not stopped on an event of interest or
1675 1683  has not been directed to stop or if the agent lwp exists and this is not the
1676 1684  agent lwp (see \fBPCAGENT\fR).
1677 1685  .sp
1678 1686  .LP
1679 1687  When applied to the process control file, a representative lwp is chosen for
1680 1688  the operation as described for \fB/proc/\fR\fIpid\fR\fB/status\fR. The
1681 1689  operation fails with \fBEBUSY\fR if the representative lwp is not stopped on an
1682 1690  event of interest or has not been directed to stop or if the agent lwp exists.
1683 1691  If \fBPRSTEP\fR or \fBPRSTOP\fR was requested, the representative lwp is made
1684 1692  runnable and its outstanding directed-stop request is cleared; otherwise all
1685 1693  outstanding directed-stop requests are cleared and, if it was stopped on an
1686 1694  event of interest, the representative lwp is marked \fBPR_REQUESTED\fR. If, as
1687 1695  a consequence, all lwps are in the \fBPR_REQUESTED\fR or \fBPR_SUSPENDED\fR
1688 1696  stop state, all lwps showing \fBPR_REQUESTED\fR are made runnable.
1689 1697  .SS "PCSTRACE"
1690 1698  .LP
1691 1699  Define a set of signals to be traced in the process. The receipt of one of
1692 1700  these signals by an lwp causes the lwp to stop. The set of signals is defined
1693 1701  using an operand \fBsigset_t\fR contained in the control message. Receipt of
1694 1702  \fBSIGKILL\fR cannot be traced; if specified, it is silently ignored.
1695 1703  .sp
1696 1704  .LP
1697 1705  If a signal that is included in an lwp's held signal set (the signal mask) is
1698 1706  sent to the lwp, the signal is not received and does not cause a stop until it
1699 1707  is removed from the held signal set, either by the lwp itself or by setting the
1700 1708  held signal set with \fBPCSHOLD\fR.
1701 1709  .SS "PCCSIG"
1702 1710  .LP
1703 1711  The current signal, if any, is cleared from the specific or representative lwp.
1704 1712  .SS "PCSSIG"
1705 1713  .LP
1706 1714  The current signal and its associated signal information for the specific or
1707 1715  representative lwp are set according to the contents of the operand
1708 1716  \fBsiginfo\fR structure (see \fB<sys/siginfo.h>\fR). If the specified signal
1709 1717  number is zero, the current signal is cleared. The semantics of this operation
1710 1718  are different from those of \fBkill\fR(2) in that the signal is delivered to
1711 1719  the lwp immediately after execution is resumed (even if it is being blocked)
1712 1720  and an additional \fBPR_SIGNALLED\fR stop does not intervene even if the signal
1713 1721  is traced. Setting the current signal to \fBSIGKILL\fR terminates the process
1714 1722  immediately.
1715 1723  .SS "PCKILL"
1716 1724  .LP
1717 1725  If applied to the process control file, a signal is sent to the process with
1718 1726  semantics identical to those of \fBkill\fR(2). If applied to an lwp control
1719 1727  file, a directed signal is sent to the specific lwp. The signal is named in a
1720 1728  \fBlong\fR operand contained in the message. Sending \fBSIGKILL\fR terminates
1721 1729  the process immediately.
1722 1730  .SS "PCUNKILL"
1723 1731  .LP
1724 1732  A signal is deleted, that is, it is removed from the set of pending signals. If
1725 1733  applied to the process control file, the signal is deleted from the process's
1726 1734  pending signals. If applied to an lwp control file, the signal is deleted from
1727 1735  the lwp's pending signals. The current signal (if any) is unaffected. The
1728 1736  signal is named in a \fBlong\fR operand in the control message. It is an error
1729 1737  (\fBEINVAL\fR) to attempt to delete \fBSIGKILL\fR.
1730 1738  .SS "PCSHOLD"
1731 1739  .LP
1732 1740  Set the set of held signals for the specific or representative lwp (signals
1733 1741  whose delivery will be blocked if sent to the lwp). The set of signals is
1734 1742  specified with a \fBsigset_t\fR operand. \fBSIGKILL\fR and \fBSIGSTOP\fR cannot
1735 1743  be held; if specified, they are silently ignored.
1736 1744  .SS "PCSFAULT"
1737 1745  .LP
1738 1746  Define a set of hardware faults to be traced in the process. On incurring one
1739 1747  of these faults, an lwp stops. The set is defined via the operand
1740 1748  \fBfltset_t\fR structure. Fault names are defined in \fB<sys/fault.h>\fR and
1741 1749  include the following. Some of these may not occur on all processors; there may
1742 1750  be processor-specific faults in addition to these.
1743 1751  .sp
1744 1752  .ne 2
1745 1753  .na
1746 1754  \fB\fBFLTILL\fR\fR
1747 1755  .ad
1748 1756  .RS 13n
1749 1757  illegal instruction
1750 1758  .RE
1751 1759  
1752 1760  .sp
1753 1761  .ne 2
1754 1762  .na
1755 1763  \fB\fBFLTPRIV\fR\fR
1756 1764  .ad
1757 1765  .RS 13n
1758 1766  privileged instruction
1759 1767  .RE
1760 1768  
1761 1769  .sp
1762 1770  .ne 2
1763 1771  .na
1764 1772  \fB\fBFLTBPT\fR\fR
1765 1773  .ad
1766 1774  .RS 13n
1767 1775  breakpoint trap
1768 1776  .RE
1769 1777  
1770 1778  .sp
1771 1779  .ne 2
1772 1780  .na
1773 1781  \fB\fBFLTTRACE\fR\fR
1774 1782  .ad
1775 1783  .RS 13n
1776 1784  trace trap (single-step)
1777 1785  .RE
1778 1786  
1779 1787  .sp
1780 1788  .ne 2
1781 1789  .na
1782 1790  \fB\fBFLTWATCH\fR\fR
1783 1791  .ad
1784 1792  .RS 13n
1785 1793  watchpoint trap
1786 1794  .RE
1787 1795  
1788 1796  .sp
1789 1797  .ne 2
1790 1798  .na
1791 1799  \fB\fBFLTACCESS\fR\fR
1792 1800  .ad
1793 1801  .RS 13n
1794 1802  memory access fault (bus error)
1795 1803  .RE
1796 1804  
1797 1805  .sp
1798 1806  .ne 2
1799 1807  .na
1800 1808  \fB\fBFLTBOUNDS\fR\fR
1801 1809  .ad
1802 1810  .RS 13n
1803 1811  memory bounds violation
1804 1812  .RE
1805 1813  
1806 1814  .sp
1807 1815  .ne 2
1808 1816  .na
1809 1817  \fB\fBFLTIOVF\fR\fR
1810 1818  .ad
1811 1819  .RS 13n
1812 1820  integer overflow
1813 1821  .RE
1814 1822  
1815 1823  .sp
1816 1824  .ne 2
1817 1825  .na
1818 1826  \fB\fBFLTIZDIV\fR\fR
1819 1827  .ad
1820 1828  .RS 13n
1821 1829  integer zero divide
1822 1830  .RE
1823 1831  
1824 1832  .sp
1825 1833  .ne 2
1826 1834  .na
1827 1835  \fB\fBFLTFPE\fR\fR
1828 1836  .ad
1829 1837  .RS 13n
1830 1838  floating-point exception
1831 1839  .RE
1832 1840  
1833 1841  .sp
1834 1842  .ne 2
1835 1843  .na
1836 1844  \fB\fBFLTSTACK\fR\fR
1837 1845  .ad
1838 1846  .RS 13n
1839 1847  unrecoverable stack fault
1840 1848  .RE
1841 1849  
1842 1850  .sp
1843 1851  .ne 2
1844 1852  .na
1845 1853  \fB\fBFLTPAGE\fR\fR
1846 1854  .ad
1847 1855  .RS 13n
1848 1856  recoverable page fault
1849 1857  .RE
1850 1858  
1851 1859  .sp
1852 1860  .LP
1853 1861  When not traced, a fault normally results in the posting of a signal to the lwp
1854 1862  that incurred the fault. If an lwp stops on a fault, the signal is posted to
1855 1863  the lwp when execution is resumed unless the fault is cleared by \fBPCCFAULT\fR
1856 1864  or by the \fBPRCFAULT\fR option of \fBPCRUN\fR. \fBFLTPAGE\fR is an exception;
1857 1865  no signal is posted. The \fBpr_info\fR field in the \fBlwpstatus\fR structure
1858 1866  identifies the signal to be sent and contains machine-specific information
1859 1867  about the fault.
1860 1868  .SS "PCCFAULT"
1861 1869  .LP
1862 1870  The current fault, if any, is cleared; the associated signal will not be sent
1863 1871  to the specific or representative lwp.
1864 1872  .SS "PCSENTRY PCSEXIT"
1865 1873  .LP
1866 1874  These control operations instruct the process's lwps to stop on entry to or
1867 1875  exit from specified system calls. The set of system calls to be traced is
1868 1876  defined via an operand \fBsysset_t\fR structure.
1869 1877  .sp
1870 1878  .LP
1871 1879  When entry to a system call is being traced, an lwp stops after having begun
1872 1880  the call to the system but before the system call arguments have been fetched
1873 1881  from the lwp. When exit from a system call is being traced, an lwp stops on
1874 1882  completion of the system call just prior to checking for signals and returning
1875 1883  to user level. At this point, all return values have been stored into the lwp's
1876 1884  registers.
1877 1885  .sp
1878 1886  .LP
1879 1887  If an lwp is stopped on entry to a system call (\fBPR_SYSENTRY\fR) or when
1880 1888  sleeping in an interruptible system call (\fBPR_ASLEEP\fR is set), it may be
1881 1889  instructed to go directly to system call exit by specifying the \fBPRSABORT\fR
1882 1890  flag in a \fBPCRUN\fR control message. Unless exit from the system call is
1883 1891  being traced, the lwp returns to user level showing \fBEINTR\fR.
1884 1892  .SS "PCWATCH"
1885 1893  .LP
1886 1894  Set or clear a watched area in the controlled process from a \fBprwatch\fR
1887 1895  structure operand:
1888 1896  .sp
1889 1897  .in +2
1890 1898  .nf
1891 1899  typedef struct prwatch {
1892 1900      uintptr_t pr_vaddr;  /* virtual address of watched area */
1893 1901      size_t pr_size;      /* size of watched area in bytes */
1894 1902      int pr_wflags;       /* watch type flags */
1895 1903  } prwatch_t;
1896 1904  .fi
1897 1905  .in -2
1898 1906  
1899 1907  .sp
1900 1908  .LP
1901 1909  \fBpr_vaddr\fR specifies the virtual address of an area of memory to be watched
1902 1910  in the controlled process. \fBpr_size\fR specifies the size of the area, in
1903 1911  bytes. \fBpr_wflags\fR specifies the type of memory access to be monitored as a
1904 1912  bit-mask of the following flags:
1905 1913  .sp
1906 1914  .ne 2
1907 1915  .na
1908 1916  \fB\fBWA_READ\fR\fR
1909 1917  .ad
1910 1918  .RS 16n
1911 1919  read access
1912 1920  .RE
1913 1921  
1914 1922  .sp
1915 1923  .ne 2
1916 1924  .na
1917 1925  \fB\fBWA_WRITE\fR\fR
1918 1926  .ad
1919 1927  .RS 16n
1920 1928  write access
1921 1929  .RE
1922 1930  
1923 1931  .sp
1924 1932  .ne 2
1925 1933  .na
1926 1934  \fB\fBWA_EXEC\fR\fR
1927 1935  .ad
1928 1936  .RS 16n
1929 1937  execution access
1930 1938  .RE
1931 1939  
1932 1940  .sp
1933 1941  .ne 2
1934 1942  .na
1935 1943  \fB\fBWA_TRAPAFTER\fR\fR
1936 1944  .ad
1937 1945  .RS 16n
1938 1946  trap after the instruction completes
1939 1947  .RE
1940 1948  
1941 1949  .sp
1942 1950  .LP
1943 1951  If \fBpr_wflags\fR is non-empty, a watched area is established for the virtual
1944 1952  address range specified by \fBpr_vaddr\fR and \fBpr_size\fR. If \fBpr_wflags\fR
1945 1953  is empty, any previously-established watched area starting at the specified
1946 1954  virtual address is cleared; \fBpr_size\fR is ignored.
1947 1955  .sp
1948 1956  .LP
1949 1957  A watchpoint is triggered when an lwp in the traced process makes a memory
1950 1958  reference that covers at least one byte of a watched area and the memory
1951 1959  reference is as specified in \fBpr_wflags\fR. When an lwp triggers a
1952 1960  watchpoint, it incurs a watchpoint trap. If \fBFLTWATCH\fR is being traced, the
1953 1961  lwp stops; otherwise, it is sent a \fBSIGTRAP\fR signal; if \fBSIGTRAP\fR is
1954 1962  being traced and is not blocked, the lwp stops.
1955 1963  .sp
1956 1964  .LP
1957 1965  The watchpoint trap occurs before the instruction completes unless
1958 1966  \fBWA_TRAPAFTER\fR was specified, in which case it occurs after the instruction
1959 1967  completes. If it occurs before completion, the memory is not modified. If it
1960 1968  occurs after completion, the memory is modified (if the access is a write
1961 1969  access).
1962 1970  .sp
1963 1971  .LP
1964 1972  Physical i/o is an exception for watchpoint traps. In this instance, there is
1965 1973  no guarantee that memory before the watched area has already been modified (or
1966 1974  in the case of \fBWA_TRAPAFTER\fR, that the memory following the watched area
1967 1975  has not been modified) when the watchpoint trap occurs and the lwp stops.
1968 1976  .sp
1969 1977  .LP
1970 1978  \fBpr_info\fR in the \fBlwpstatus\fR structure contains information pertinent
1971 1979  to the watchpoint trap. In particular, the \fBsi_addr\fR field contains the
1972 1980  virtual address of the memory reference that triggered the watchpoint, and the
1973 1981  \fBsi_code\fR field contains one of \fBTRAP_RWATCH\fR, \fBTRAP_WWATCH\fR, or
1974 1982  \fBTRAP_XWATCH\fR, indicating read, write, or execute access, respectively. The
1975 1983  \fBsi_trapafter\fR field is zero unless \fBWA_TRAPAFTER\fR is in effect for
1976 1984  this watched area; non-zero indicates that the current instruction is not the
1977 1985  instruction that incurred the watchpoint trap. The \fBsi_pc\fR field contains
1978 1986  the virtual address of the instruction that incurred the trap.
1979 1987  .sp
1980 1988  .LP
1981 1989  A watchpoint trap may be triggered while executing a system call that makes
1982 1990  reference to the traced process's memory. The lwp that is executing the system
1983 1991  call incurs the watchpoint trap while still in the system call. If it stops as
1984 1992  a result, the \fBlwpstatus\fR structure contains the system call number and its
1985 1993  arguments. If the lwp does not stop, or if it is set running again without
1986 1994  clearing the signal or fault, the system call fails with \fBEFAULT\fR. If
1987 1995  \fBWA_TRAPAFTER\fR was specified, the memory reference will have completed and
1988 1996  the memory will have been modified (if the access was a write access) when the
1989 1997  watchpoint trap occurs.
1990 1998  .sp
1991 1999  .LP
1992 2000  If more than one of \fBWA_READ\fR, \fBWA_WRITE\fR, and \fBWA_EXEC\fR is
1993 2001  specified for a watched area, and a single instruction incurs more than one of
1994 2002  the specified types, only one is reported when the watchpoint trap occurs. The
1995 2003  precedence is \fBWA_EXEC\fR, \fBWA_READ\fR, \fBWA_WRITE\fR (\fBWA_EXEC\fR and
1996 2004  \fBWA_READ\fR take precedence over \fBWA_WRITE\fR), unless \fBWA_TRAPAFTER\fR
1997 2005  was specified, in which case it is \fBWA_WRITE\fR, \fBWA_READ\fR, \fBWA_EXEC\fR
1998 2006  (\fBWA_WRITE\fR takes precedence).
1999 2007  .sp
2000 2008  .LP
2001 2009  \fBPCWATCH\fR fails with \fBEINVAL\fR if an attempt is made to specify
2002 2010  overlapping watched areas or if \fBpr_wflags\fR contains flags other than those
2003 2011  specified above. It fails with \fBENOMEM\fR if an attempt is made to establish
2004 2012  more watched areas than the system can support (the system can support
2005 2013  thousands).
2006 2014  .sp
2007 2015  .LP
2008 2016  The child of a \fBvfork\fR(2) borrows the parent's address space. When a
2009 2017  \fBvfork\fR(2) is executed by a traced process, all watched areas established
2010 2018  for the parent are suspended until the child terminates or performs an
2011 2019  \fBexec\fR(2). Any watched areas established independently in the child are
2012 2020  cancelled when the parent resumes after the child's termination or
2013 2021  \fBexec\fR(2). \fBPCWATCH\fR fails with \fBEBUSY\fR if applied to the parent of
2014 2022  a \fBvfork\fR(2) before the child has terminated or performed an \fBexec\fR(2).
2015 2023  The \fBPR_VFORKP\fR flag is set in the \fBpstatus\fR structure for such a
2016 2024  parent process.
2017 2025  .sp
2018 2026  .LP
2019 2027  Certain accesses of the traced process's address space by the operating system
2020 2028  are immune to watchpoints. The initial construction of a signal stack frame
2021 2029  when a signal is delivered to an lwp will not trigger a watchpoint trap even if
2022 2030  the new frame covers watched areas of the stack. Once the signal handler is
2023 2031  entered, watchpoint traps occur normally. On SPARC based machines, register
2024 2032  window overflow and underflow will not trigger watchpoint traps, even if the
2025 2033  register window save areas cover watched areas of the stack.
2026 2034  .sp
2027 2035  .LP
2028 2036  Watched areas are not inherited by child processes, even if the traced
2029 2037  process's inherit-on-fork mode, \fBPR_FORK\fR, is set (see \fBPCSET\fR, below).
2030 2038  All watched areas are cancelled when the traced process performs a successful
2031 2039  \fBexec\fR(2).
2032 2040  .SS "PCSET PCUNSET"
2033 2041  .LP
2034 2042  \fBPCSET\fR sets one or more modes of operation for the traced process.
2035 2043  \fBPCUNSET\fR unsets these modes. The modes to be set or unset are specified by
2036 2044  flags in an operand \fBlong\fR in the control message:
2037 2045  .sp
2038 2046  .ne 2
2039 2047  .na
2040 2048  \fB\fBPR_FORK\fR\fR
2041 2049  .ad
2042 2050  .RS 13n
2043 2051  (inherit-on-fork): When set, the process's tracing flags and its
2044 2052  inherit-on-fork mode are inherited by the child of a \fBfork\fR(2),
2045 2053  \fBfork1\fR(2), or \fBvfork\fR(2). When unset, child processes start with all
2046 2054  tracing flags cleared.
2047 2055  .RE
2048 2056  
2049 2057  .sp
2050 2058  .ne 2
2051 2059  .na
2052 2060  \fB\fBPR_RLC\fR\fR
2053 2061  .ad
2054 2062  .RS 13n
2055 2063  (run-on-last-close): When set and the last writable \fB/proc\fR file descriptor
2056 2064  referring to the traced process or any of its lwps is closed, all of the
2057 2065  process's tracing flags and watched areas are cleared, any outstanding stop
2058 2066  directives are canceled, and if any lwps are stopped on events of interest,
2059 2067  they are set running as though \fBPCRUN\fR had been applied to them. When
2060 2068  unset, the process's tracing flags and watched areas are retained and lwps are
2061 2069  not set running on last close.
2062 2070  .RE
2063 2071  
2064 2072  .sp
2065 2073  .ne 2
2066 2074  .na
2067 2075  \fB\fBPR_KLC\fR\fR
2068 2076  .ad
2069 2077  .RS 13n
2070 2078  (kill-on-last-close): When set and the last writable \fB/proc\fR file
2071 2079  descriptor referring to the traced process or any of its lwps is closed, the
2072 2080  process is terminated with \fBSIGKILL\fR.
2073 2081  .RE
2074 2082  
2075 2083  .sp
2076 2084  .ne 2
2077 2085  .na
2078 2086  \fB\fBPR_ASYNC\fR\fR
2079 2087  .ad
2080 2088  .RS 13n
2081 2089  (asynchronous-stop): When set, a stop on an event of interest by one lwp does
2082 2090  not directly affect any other lwp in the process. When unset and an lwp stops
2083 2091  on an event of interest other than \fBPR_REQUESTED\fR, all other lwps in the
2084 2092  process are directed to stop.
2085 2093  .RE
2086 2094  
2087 2095  .sp
2088 2096  .ne 2
2089 2097  .na
2090 2098  \fB\fBPR_MSACCT\fR\fR
2091 2099  .ad
2092 2100  .RS 13n
2093 2101  (microstate accounting): Microstate accounting is now continuously enabled.
2094 2102  This flag is deprecated and no longer has any effect upon microstate
2095 2103  accounting. Applications may toggle this flag; however, microstate accounting
2096 2104  will remain enabled regardless.
2097 2105  .RE
2098 2106  
2099 2107  .sp
2100 2108  .ne 2
2101 2109  .na
2102 2110  \fB\fBPR_MSFORK\fR\fR
2103 2111  .ad
2104 2112  .RS 13n
2105 2113  (inherit microstate accounting): All processes now inherit microstate
2106 2114  accounting, as it is continuously enabled. This flag has been deprecated and
2107 2115  its use no longer has any effect upon the behavior of microstate accounting.
2108 2116  .RE
2109 2117  
2110 2118  .sp
2111 2119  .ne 2
2112 2120  .na
2113 2121  \fB\fBPR_BPTADJ\fR\fR
2114 2122  .ad
2115 2123  .RS 13n
2116 2124  (breakpoint trap pc adjustment): On x86-based machines, a breakpoint trap
2117 2125  leaves the program counter (the \fBEIP\fR) referring to the breakpointed
2118 2126  instruction plus one byte. When \fBPR_BPTADJ\fR is set, the system will adjust
2119 2127  the program counter back to the location of the breakpointed instruction when
2120 2128  the lwp stops on a breakpoint. This flag has no effect on SPARC based machines,
2121 2129  where breakpoint traps leave the program counter referring to the breakpointed
2122 2130  instruction.
2123 2131  .RE
2124 2132  
2125 2133  .sp
2126 2134  .ne 2
2127 2135  .na
2128 2136  \fB\fBPR_PTRACE\fR\fR
2129 2137  .ad
2130 2138  .RS 13n
2131 2139  (ptrace-compatibility): When set, a stop on an event of interest by the traced
2132 2140  process is reported to the parent of the traced process by \fBwait\fR(3C),
2133 2141  \fBSIGTRAP\fR is sent to the traced process when it executes a successful
2134 2142  \fBexec\fR(2), setuid/setgid flags are not honored for execs performed by the
2135 2143  traced process, any exec of an object file that the traced process cannot read
2136 2144  fails, and the process dies when its parent dies. This mode is deprecated; it
2137 2145  is provided only to allow \fBptrace\fR(3C) to be implemented as a library
2138 2146  function using \fB/proc\fR.
2139 2147  .RE
2140 2148  
2141 2149  .sp
2142 2150  .LP
2143 2151  It is an error (\fBEINVAL\fR) to specify flags other than those described above
2144 2152  or to apply these operations to a system process. The current modes are
2145 2153  reported in the \fBpr_flags\fR field of \fB/proc/\fR\fIpid\fR\fB/status\fR and
2146 2154  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwp\fR\fB/lwpstatus\fR.
2147 2155  .SS "PCSREG"
2148 2156  .LP
2149 2157  Set the general registers for the specific or representative lwp according to
2150 2158  the operand \fBprgregset_t\fR structure.
2151 2159  .sp
2152 2160  .LP
2153 2161  On SPARC based systems, only the condition-code bits of the processor-status
2154 2162  register (R_PSR) of SPARC V8 (32-bit) processes can be modified by
2155 2163  \fBPCSREG\fR. Other privileged registers cannot be modified at all.
2156 2164  .sp
2157 2165  .LP
2158 2166  On x86-based systems, only certain bits of the flags register (EFL) can be
2159 2167  modified by \fBPCSREG\fR: these include the condition codes, direction-bit, and
2160 2168  overflow-bit.
2161 2169  .sp
2162 2170  .LP
2163 2171  \fBPCSREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an event of
2164 2172  interest.
2165 2173  .SS "PCSVADDR"
2166 2174  .LP
2167 2175  Set the address at which execution will resume for the specific or
2168 2176  representative lwp from the operand \fBlong\fR. On SPARC based systems, both
2169 2177  %pc and %npc are set, with %npc set to the instruction following the virtual
2170 2178  address. On x86-based systems, only %eip is set. \fBPCSVADDR\fR fails with
2171 2179  \fBEBUSY\fR if the lwp is not stopped on an event of interest.
2172 2180  .SS "PCSFPREG"
2173 2181  .LP
2174 2182  Set the floating-point registers for the specific or representative lwp
2175 2183  according to the operand \fBprfpregset_t\fR structure. An error (\fBEINVAL\fR)
2176 2184  is returned if the system does not support floating-point operations (no
2177 2185  floating-point hardware and the system does not emulate floating-point machine
2178 2186  instructions). \fBPCSFPREG\fR fails with \fBEBUSY\fR if the lwp is not stopped
2179 2187  on an event of interest.
2180 2188  .SS "PCSXREG"
2181 2189  .LP
2182 2190  Set the extra state registers for the specific or representative lwp according
2183 2191  to the architecture-dependent operand \fBprxregset_t\fR structure. An error
2184 2192  (\fBEINVAL\fR) is returned if the system does not support extra state
2185 2193  registers. \fBPCSXREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an
2186 2194  event of interest.
2187 2195  .SS "PCSASRS"
2188 2196  .LP
2189 2197  Set the ancillary state registers for the specific or representative lwp
2190 2198  according to the SPARC V9 platform-dependent operand \fBasrset_t\fR structure.
2191 2199  An error (\fBEINVAL\fR) is returned if either the target process or the
2192 2200  controlling process is not a 64-bit SPARC V9 process. Most of the ancillary
2193 2201  state registers are privileged registers that cannot be modified. Only those
2194 2202  that can be modified are set; all others are silently ignored. \fBPCSASRS\fR
2195 2203  fails with \fBEBUSY\fR if the lwp is not stopped on an event of interest.
2196 2204  .SS "PCAGENT"
2197 2205  .LP
2198 2206  Create an agent lwp in the controlled process with register values from the
2199 2207  operand \fBprgregset_t\fR structure (see \fBPCSREG\fR, above). The agent lwp is
2200 2208  created in the stopped state showing \fBPR_REQUESTED\fR and with its held
2201 2209  signal set (the signal mask) having all signals except \fBSIGKILL\fR and
2202 2210  \fBSIGSTOP\fR blocked.
2203 2211  .sp
2204 2212  .LP
2205 2213  The \fBPCAGENT\fR operation fails with \fBEBUSY\fR unless the process is fully
2206 2214  stopped via \fB/proc\fR, that is, unless all of the lwps in the process are
2207 2215  stopped either on events of interest or on \fBPR_SUSPENDED\fR, or are stopped
2208 2216  on \fBPR_JOBCONTROL\fR and have been directed to stop via \fBPCDSTOP\fR.  It
2209 2217  fails with \fBEBUSY\fR if an agent lwp already exists. It fails with
2210 2218  \fBENOMEM\fR if system resources for creating new lwps have been exhausted.
2211 2219  .sp
2212 2220  .LP
2213 2221  Any \fBPCRUN\fR operation applied to the process control file or to the control
2214 2222  file of an lwp other than the agent lwp fails with \fBEBUSY\fR as long as the
2215 2223  agent lwp exists. The agent lwp must be caused to terminate by executing the
2216 2224  \fBSYS_lwp_exit\fR system call trap before the process can be restarted.
2217 2225  .sp
2218 2226  .LP
2219 2227  Once the agent lwp is created, its lwp-ID can be found by reading the process
2220 2228  status file. To facilitate opening the agent lwp's control and status files,
2221 2229  the directory name \fB/propc/\fR\fIpid\fR\fB/lwp/agent\fR is accepted for
2222 2230  lookup operations as an invisible alias for
2223 2231  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid,\fR \fIlwpid\fR being the lwp-ID of
2224 2232  the agent lwp (invisible in the sense that the name ``agent'' does not appear
2225 2233  in a directory listing of \fB/proc/\fR\fIpid\fR\fB/lwp\fR obtained from
2226 2234  \fBls\fR(1), \fBgetdents\fR(2), or \fBreaddir\fR(3C)).
2227 2235  .sp
2228 2236  .LP
2229 2237  The purpose of the agent lwp is to perform operations in the controlled process
2230 2238  on behalf of the controlling process: to gather information not directly
2231 2239  available via \fB/proc\fR files, or in general to make the process change state
2232 2240  in ways not directly available via \fB/proc\fR control operations. To make use
2233 2241  of an agent lwp, the controlling process must be capable of making it execute
2234 2242  system calls (specifically, the \fBSYS_lwp_exit\fR system call trap). The
2235 2243  register values given to the agent lwp on creation are typically the registers
2236 2244  of the representative lwp, so that the agent lwp can use its stack.
2237 2245  .sp
2238 2246  .LP
2239 2247  If the controlling process neglects to force the agent lwp to execute the
2240 2248  \fBSYS_lwp_exit\fR system call (due to either logic error or fatal failure on
2241 2249  the part of the controlling process), the agent lwp will remain in the target
2242 2250  process.  For purposes of being able to debug these otherwise rogue agents,
2243 2251  information as to the creator of the agent lwp is reflected in that lwp's
2244 2252  \fBspymaster\fR file in \fB/proc\fR. Should the target process generate a core
2245 2253  dump with the agent lwp in place, this information will be available via the
2246 2254  \fBNT_SPYMASTER\fR note in the core file (see \fBcore\fR(4)).
2247 2255  .sp
2248 2256  .LP
2249 2257  The agent lwp is not allowed to execute any variation of the \fBSYS_fork\fR or
2250 2258  \fBSYS_exec\fR system call traps. Attempts to do so yield \fBENOTSUP\fR to the
2251 2259  agent lwp.
2252 2260  .sp
2253 2261  .LP
2254 2262  Symbolic constants for system call trap numbers like \fBSYS_lwp_exit\fR and
2255 2263  \fBSYS_lwp_create\fR can be found in the header file <\fBsys/syscall.h\fR>.
2256 2264  .SS "PCREAD PCWRITE"
2257 2265  .LP
2258 2266  Read or write the target process's address space via a \fBpriovec\fR structure
2259 2267  operand:
2260 2268  .sp
2261 2269  .in +2
2262 2270  .nf
2263 2271  typedef struct priovec {
2264 2272      void *pio_base;      /* buffer in controlling process */
2265 2273      size_t pio_len;      /* size of read/write request in bytes */
2266 2274      off_t pio_offset;    /* virtual address in target process */
2267 2275  } priovec_t;
2268 2276  .fi
2269 2277  .in -2
2270 2278  
2271 2279  .sp
2272 2280  .LP
2273 2281  These operations have the same effect as \fBpread\fR(2) and \fBpwrite\fR(2),
2274 2282  respectively, of the target process's address space file. The difference is
2275 2283  that more than one \fBPCREAD\fR or \fBPCWRITE\fR control operation can be
2276 2284  written to the control file at once, and they can be interspersed with other
2277 2285  control operations in a single write to the control file. This is useful, for
2278 2286  example, when planting many breakpoint instructions in the process's address
2279 2287  space, or when stepping over a breakpointed instruction. Unlike \fBpread\fR(2)
2280 2288  and \fBpwrite\fR(2), no provision is made for partial reads or writes; if the
2281 2289  operation cannot be performed completely, it fails with \fBEIO\fR.
2282 2290  .SS "PCNICE"
2283 2291  .LP
2284 2292  The traced process's \fBnice\fR(2) value is incremented by the amount in the
2285 2293  operand \fBlong\fR. Only a process with the {\fBPRIV_PROC_PRIOCNTL\fR}
2286 2294  privilege asserted in its effective set can better a process's priority in this
2287 2295  way, but any user may lower the priority. This operation is not meaningful for
2288 2296  all scheduling classes.
2289 2297  .SS "PCSCRED"
2290 2298  .LP
2291 2299  Set the target process credentials to the values contained in the
2292 2300  \fBprcred_t\fR structure operand (see \fB/proc/\fR\fIpid\fR\fB/cred\fR). The
2293 2301  effective, real, and saved user-IDs and group-IDs of the target process are
2294 2302  set. The target process's supplementary groups are not changed; the
2295 2303  \fBpr_ngroups\fR and \fBpr_groups\fR members of the structure operand are
2296 2304  ignored. Only the privileged processes can perform this operation; for all
2297 2305  others it fails with \fBEPERM\fR.
2298 2306  .SS "PCSCREDX"
2299 2307  .LP
2300 2308  Operates like \fBPCSCRED\fR but also sets the supplementary groups; the length
2301 2309  of the data written with this control operation should be "sizeof
2302 2310  (\fBprcred_t\fR) + sizeof (\fBgid_t)\fR * (#groups - 1)".
2303 2311  .SS "PCSPRIV"
2304 2312  .LP
2305 2313  Set the target process privilege to the values contained in the \fBprpriv_t\fR
2306 2314  operand (see \fB/proc/pid/priv\fR). The effective, permitted, inheritable, and
2307 2315  limit sets are all changed. Privilege flags can also be set. The process is
2308 2316  made privilege aware unless it can relinquish privilege awareness. See
2309 2317  \fBprivileges\fR(5).
2310 2318  .sp
2311 2319  .LP
2312 2320  The limit set of the target process cannot be grown. The other privilege sets
2313 2321  must be subsets of the intersection of the effective set of the calling process
2314 2322  with the new limit set of the target process or subsets of the original values
2315 2323  of the sets in the target process.
2316 2324  .sp
2317 2325  .LP
2318 2326  If any of the above restrictions are not met, \fBEPERM\fR is returned. If the
2319 2327  structure written is improperly formatted, \fBEINVAL\fR is returned.
2320 2328  .SH PROGRAMMING NOTES
2321 2329  .LP
2322 2330  For security reasons, except for the \fBpsinfo\fR, \fBusage\fR, \fBlpsinfo\fR,
2323 2331  \fBlusage\fR, \fBlwpsinfo\fR, and \fBlwpusage\fR files, which are
2324 2332  world-readable, and except for privileged processes, an open of a \fB/proc\fR
2325 2333  file fails unless both the user-ID and group-ID of the caller match those of
2326 2334  the traced process and the process's object file is readable by the caller. The
2327 2335  effective set of the caller is a superset of both the inheritable and the
2328 2336  permitted set of the target process. The limit set of the caller is a superset
2329 2337  of the limit set of the target process. Except for the world-readable files
2330 2338  just mentioned, files corresponding to setuid and setgid processes can be
2331 2339  opened only by the appropriately privileged process.
2332 2340  .sp
2333 2341  .LP
2334 2342  A process that is missing the basic privilege {\fBPRIV_PROC_INFO\fR} cannot see
2335 2343  any processes under \fB/proc\fR that it cannot send a signal to.
2336 2344  .sp
2337 2345  .LP
2338 2346  A process that has {\fBPRIV_PROC_OWNER\fR} asserted in its effective set can
2339 2347  open any file for reading. To manipulate or control a process, the controlling
2340 2348  process must have at least as many privileges in its effective set as the
2341 2349  target process has in its effective, inheritable, and permitted sets. The limit
2342 2350  set of the controlling process must be a superset of the limit set of the
2343 2351  target process. Additional restrictions apply if any of the uids of the target
2344 2352  process are 0. See \fBprivileges\fR(5).
2345 2353  .sp
2346 2354  .LP
2347 2355  Even if held by a privileged process, an open process or lwp file descriptor
2348 2356  (other than file descriptors for the world-readable files) becomes invalid if
2349 2357  the traced process performs an \fBexec\fR(2) of a setuid/setgid object file or
2350 2358  an object file that the traced process cannot read. Any operation performed on
2351 2359  an invalid file descriptor, except \fBclose\fR(2), fails with \fBEAGAIN\fR. In
2352 2360  this situation, if any tracing flags are set and the process or any lwp file
2353 2361  descriptor is open for writing, the process will have been directed to stop and
2354 2362  its run-on-last-close flag will have been set (see \fBPCSET\fR). This enables a
2355 2363  controlling process (if it has permission) to reopen the \fB/proc\fR files to
2356 2364  get new valid file descriptors, close the invalid file descriptors, unset the
2357 2365  run-on-last-close flag (if desired), and proceed. Just closing the invalid file
2358 2366  descriptors causes the traced process to resume execution with all tracing
2359 2367  flags cleared. Any process not currently open for writing via \fB/proc\fR, but
2360 2368  that has left-over tracing flags from a previous open, and that executes a
2361 2369  setuid/setgid or unreadable object file, will not be stopped but will have all
2362 2370  its tracing flags cleared.
2363 2371  .sp
2364 2372  .LP
2365 2373  To wait for one or more of a set of processes or lwps to stop or terminate,
2366 2374  \fB/proc\fR file descriptors (other than those obtained by opening the
2367 2375  \fBcwd\fR or \fBroot\fR directories or by opening files in the \fBfd\fR or
2368 2376  \fBobject\fR directories) can be used in a \fBpoll\fR(2) system call. When
2369 2377  requested and returned, either of the polling events \fBPOLLPRI\fR or
2370 2378  \fBPOLLWRNORM\fR indicates that the process or lwp stopped on an event of
2371 2379  interest. Although they cannot be requested, the polling events \fBPOLLHUP\fR,
2372 2380  \fBPOLLERR\fR, and \fBPOLLNVAL\fR may be returned. \fBPOLLHUP\fR indicates that
2373 2381  the process or lwp has terminated. \fBPOLLERR\fR indicates that the file
2374 2382  descriptor has become invalid. \fBPOLLNVAL\fR is returned immediately if
2375 2383  \fBPOLLPRI\fR or \fBPOLLWRNORM\fR is requested on a file descriptor referring
2376 2384  to a system process (see \fBPCSTOP\fR). The requested events may be empty to
2377 2385  wait simply for termination.
2378 2386  .SH FILES
2379 2387  .ne 2
2380 2388  .na
2381 2389  \fB\fB/proc\fR\fR
2382 2390  .ad
2383 2391  .sp .6
2384 2392  .RS 4n
2385 2393  directory (list of processes)
2386 2394  .RE
2387 2395  
2388 2396  .sp
2389 2397  .ne 2
2390 2398  .na
2391 2399  \fB\fB/proc/\fIpid\fR\fR\fR
2392 2400  .ad
2393 2401  .sp .6
2394 2402  .RS 4n
2395 2403  specific process directory
2396 2404  .RE
2397 2405  
2398 2406  .sp
2399 2407  .ne 2
2400 2408  .na
2401 2409  \fB\fB/proc/self\fR\fR
2402 2410  .ad
2403 2411  .sp .6
2404 2412  .RS 4n
2405 2413  alias for a process's own directory
2406 2414  .RE
2407 2415  
2408 2416  .sp
2409 2417  .ne 2
2410 2418  .na
2411 2419  \fB\fB/proc/\fIpid\fR/as\fR\fR
2412 2420  .ad
2413 2421  .sp .6
2414 2422  .RS 4n
2415 2423  address space file
2416 2424  .RE
2417 2425  
2418 2426  .sp
2419 2427  .ne 2
2420 2428  .na
2421 2429  \fB\fB/proc/\fIpid\fR/ctl\fR\fR
2422 2430  .ad
2423 2431  .sp .6
2424 2432  .RS 4n
2425 2433  process control file
2426 2434  .RE
2427 2435  
2428 2436  .sp
2429 2437  .ne 2
2430 2438  .na
2431 2439  \fB\fB/proc/\fIpid\fR/status\fR\fR
2432 2440  .ad
2433 2441  .sp .6
2434 2442  .RS 4n
2435 2443  process status
2436 2444  .RE
2437 2445  
2438 2446  .sp
2439 2447  .ne 2
2440 2448  .na
2441 2449  \fB\fB/proc/\fIpid\fR/lstatus\fR\fR
2442 2450  .ad
2443 2451  .sp .6
2444 2452  .RS 4n
2445 2453  array of lwp status structs
2446 2454  .RE
2447 2455  
2448 2456  .sp
2449 2457  .ne 2
2450 2458  .na
2451 2459  \fB\fB/proc/\fIpid\fR/psinfo\fR\fR
2452 2460  .ad
2453 2461  .sp .6
2454 2462  .RS 4n
2455 2463  process \fBps\fR(1) info
2456 2464  .RE
2457 2465  
2458 2466  .sp
2459 2467  .ne 2
2460 2468  .na
2461 2469  \fB\fB/proc/\fIpid\fR/lpsinfo\fR\fR
2462 2470  .ad
2463 2471  .sp .6
2464 2472  .RS 4n
2465 2473  array of lwp \fBps\fR(1) info structs
2466 2474  .RE
2467 2475  
2468 2476  .sp
2469 2477  .ne 2
2470 2478  .na
2471 2479  \fB\fB/proc/\fIpid\fR/map\fR\fR
2472 2480  .ad
2473 2481  .sp .6
2474 2482  .RS 4n
2475 2483  address space map
2476 2484  .RE
2477 2485  
2478 2486  .sp
2479 2487  .ne 2
2480 2488  .na
2481 2489  \fB\fB/proc/\fIpid\fR/xmap\fR\fR
2482 2490  .ad
2483 2491  .sp .6
2484 2492  .RS 4n
2485 2493  extended address space map
2486 2494  .RE
2487 2495  
2488 2496  .sp
2489 2497  .ne 2
2490 2498  .na
2491 2499  \fB\fB/proc/\fIpid\fR/rmap\fR\fR
2492 2500  .ad
2493 2501  .sp .6
2494 2502  .RS 4n
2495 2503  reserved address map
2496 2504  .RE
2497 2505  
2498 2506  .sp
2499 2507  .ne 2
2500 2508  .na
2501 2509  \fB\fB/proc/\fIpid\fR/cred\fR\fR
2502 2510  .ad
2503 2511  .sp .6
2504 2512  .RS 4n
2505 2513  process credentials
2506 2514  .RE
2507 2515  
2508 2516  .sp
2509 2517  .ne 2
2510 2518  .na
2511 2519  \fB\fB/proc/\fIpid\fR/priv\fR\fR
2512 2520  .ad
2513 2521  .sp .6
2514 2522  .RS 4n
2515 2523  process privileges
2516 2524  .RE
2517 2525  
2518 2526  .sp
2519 2527  .ne 2
2520 2528  .na
2521 2529  \fB\fB/proc/\fIpid\fR/sigact\fR\fR
2522 2530  .ad
2523 2531  .sp .6
2524 2532  .RS 4n
2525 2533  process signal actions
2526 2534  .RE
2527 2535  
2528 2536  .sp
2529 2537  .ne 2
2530 2538  .na
2531 2539  \fB\fB/proc/\fIpid\fR/auxv\fR\fR
2532 2540  .ad
2533 2541  .sp .6
2534 2542  .RS 4n
2535 2543  process aux vector
2536 2544  .RE
2537 2545  
2538 2546  .sp
2539 2547  .ne 2
2540 2548  .na
2541 2549  \fB\fB/proc/\fIpid\fR/ldt\fR\fR
2542 2550  .ad
2543 2551  .sp .6
2544 2552  .RS 4n
2545 2553  process \fBLDT\fR (x86 only)
2546 2554  .RE
2547 2555  
2548 2556  .sp
2549 2557  .ne 2
2550 2558  .na
2551 2559  \fB\fB/proc/\fIpid\fR/usage\fR\fR
2552 2560  .ad
2553 2561  .sp .6
2554 2562  .RS 4n
2555 2563  process usage
2556 2564  .RE
2557 2565  
2558 2566  .sp
2559 2567  .ne 2
2560 2568  .na
2561 2569  \fB\fB/proc/\fIpid\fR/lusage\fR\fR
2562 2570  .ad
2563 2571  .sp .6
2564 2572  .RS 4n
2565 2573  array of lwp usage structs
2566 2574  .RE
2567 2575  
2568 2576  .sp
2569 2577  .ne 2
2570 2578  .na
2571 2579  \fB\fB/proc/\fIpid\fR/path\fR\fR
2572 2580  .ad
2573 2581  .sp .6
2574 2582  .RS 4n
2575 2583  symbolic links to process open files
2576 2584  .RE
2577 2585  
2578 2586  .sp
2579 2587  .ne 2
2580 2588  .na
2581 2589  \fB\fB/proc/\fIpid\fR/pagedata\fR\fR
2582 2590  .ad
2583 2591  .sp .6
2584 2592  .RS 4n
2585 2593  process page data
2586 2594  .RE
2587 2595  
2588 2596  .sp
2589 2597  .ne 2
2590 2598  .na
2591 2599  \fB\fB/proc/\fIpid\fR/watch\fR\fR
2592 2600  .ad
2593 2601  .sp .6
2594 2602  .RS 4n
2595 2603  active watchpoints
2596 2604  .RE
2597 2605  
2598 2606  .sp
2599 2607  .ne 2
2600 2608  .na
2601 2609  \fB\fB/proc/\fIpid\fR/cwd\fR\fR
2602 2610  .ad
2603 2611  .sp .6
2604 2612  .RS 4n
2605 2613  alias for the current working directory
2606 2614  .RE
2607 2615  
2608 2616  .sp
2609 2617  .ne 2
2610 2618  .na
2611 2619  \fB\fB/proc/\fIpid\fR/root\fR\fR
2612 2620  .ad
2613 2621  .sp .6
2614 2622  .RS 4n
2615 2623  alias for the root directory
2616 2624  .RE
2617 2625  
2618 2626  .sp
2619 2627  .ne 2
2620 2628  .na
2621 2629  \fB\fB/proc/\fIpid\fR/fd\fR\fR
2622 2630  .ad
2623 2631  .sp .6
2624 2632  .RS 4n
2625 2633  directory (list of open files)
2626 2634  .RE
2627 2635  
2628 2636  .sp
2629 2637  .ne 2
2630 2638  .na
2631 2639  \fB\fB/proc/\fIpid\fR/fd/*\fR\fR
2632 2640  .ad
2633 2641  .sp .6
2634 2642  .RS 4n
2635 2643  aliases for process's open files
2636 2644  .RE
2637 2645  
2638 2646  .sp
2639 2647  .ne 2
2640 2648  .na
2641 2649  \fB\fB/proc/\fIpid\fR/object\fR\fR
2642 2650  .ad
2643 2651  .sp .6
2644 2652  .RS 4n
2645 2653  directory (list of mapped files)
2646 2654  .RE
2647 2655  
2648 2656  .sp
2649 2657  .ne 2
2650 2658  .na
2651 2659  \fB\fB/proc/\fIpid\fR/object/a.out\fR\fR
2652 2660  .ad
2653 2661  .sp .6
2654 2662  .RS 4n
2655 2663  alias for process's executable file
2656 2664  .RE
2657 2665  
2658 2666  .sp
2659 2667  .ne 2
2660 2668  .na
2661 2669  \fB\fB/proc/\fIpid\fR/object/*\fR\fR
2662 2670  .ad
2663 2671  .sp .6
2664 2672  .RS 4n
2665 2673  aliases for other mapped files
2666 2674  .RE
2667 2675  
2668 2676  .sp
2669 2677  .ne 2
2670 2678  .na
2671 2679  \fB\fB/proc/\fIpid\fR/lwp\fR\fR
2672 2680  .ad
2673 2681  .sp .6
2674 2682  .RS 4n
2675 2683  directory (list of lwps)
2676 2684  .RE
2677 2685  
2678 2686  .sp
2679 2687  .ne 2
2680 2688  .na
2681 2689  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR\fR\fR
2682 2690  .ad
2683 2691  .sp .6
2684 2692  .RS 4n
2685 2693  specific lwp directory
2686 2694  .RE
2687 2695  
2688 2696  .sp
2689 2697  .ne 2
2690 2698  .na
2691 2699  \fB\fB/proc/\fIpid\fR/lwp/agent\fR\fR
2692 2700  .ad
2693 2701  .sp .6
2694 2702  .RS 4n
2695 2703  alias for the agent lwp directory
2696 2704  .RE
2697 2705  
2698 2706  .sp
2699 2707  .ne 2
2700 2708  .na
2701 2709  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpctl\fR\fR
2702 2710  .ad
2703 2711  .sp .6
2704 2712  .RS 4n
2705 2713  lwp control file
2706 2714  .RE
2707 2715  
2708 2716  .sp
2709 2717  .ne 2
2710 2718  .na
2711 2719  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpstatus\fR\fR
2712 2720  .ad
2713 2721  .sp .6
2714 2722  .RS 4n
2715 2723  lwp status
2716 2724  .RE
2717 2725  
2718 2726  .sp
2719 2727  .ne 2
2720 2728  .na
2721 2729  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpsinfo\fR\fR
2722 2730  .ad
2723 2731  .sp .6
2724 2732  .RS 4n
2725 2733  lwp \fBps\fR(1) info
2726 2734  .RE
2727 2735  
2728 2736  .sp
2729 2737  .ne 2
2730 2738  .na
2731 2739  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpusage\fR\fR
2732 2740  .ad
2733 2741  .sp .6
2734 2742  .RS 4n
2735 2743  lwp usage
2736 2744  .RE
2737 2745  
2738 2746  .sp
2739 2747  .ne 2
2740 2748  .na
2741 2749  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/gwindows\fR\fR
2742 2750  .ad
2743 2751  .sp .6
2744 2752  .RS 4n
2745 2753  register windows (SPARC only)
2746 2754  .RE
2747 2755  
2748 2756  .sp
2749 2757  .ne 2
2750 2758  .na
2751 2759  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/xregs\fR\fR
2752 2760  .ad
2753 2761  .sp .6
2754 2762  .RS 4n
2755 2763  extra state registers
2756 2764  .RE
2757 2765  
2758 2766  .sp
2759 2767  .ne 2
2760 2768  .na
2761 2769  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/asrs\fR\fR
2762 2770  .ad
2763 2771  .sp .6
2764 2772  .RS 4n
2765 2773  ancillary state registers (SPARC V9 only)
2766 2774  .RE
2767 2775  
2768 2776  .sp
2769 2777  .ne 2
2770 2778  .na
2771 2779  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/spymaster\fR\fR
2772 2780  .ad
2773 2781  .sp .6
2774 2782  .RS 4n
2775 2783  For an agent LWP, the controlling process
2776 2784  .RE
2777 2785  
2778 2786  .SH SEE ALSO
2779 2787  .LP
2780 2788  \fBls\fR(1), \fBps\fR(1), \fBchroot\fR(1M), \fBalarm\fR(2), \fBbrk\fR(2),
2781 2789  \fBchdir\fR(2), \fBchroot\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2),
2782 2790  \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2), \fBfork1\fR(2), \fBfstat\fR(2),
2783 2791  \fBgetdents\fR(2), \fBgetustack\fR(2), \fBkill\fR(2), \fBlseek\fR(2),
2784 2792  \fBmmap\fR(2), \fBnice\fR(2), \fBopen\fR(2), \fBpoll\fR(2), \fBpread\fR(2),
2785 2793  \fBptrace\fR(3C), \fBpwrite\fR(2), \fBread\fR(2), \fBreadlink\fR(2),
2786 2794  \fBreadv\fR(2), \fBshmget\fR(2), \fBsigaction\fR(2), \fBsigaltstack\fR(2),
2787 2795  \fBvfork\fR(2), \fBwrite\fR(2), \fBwritev\fR(2), \fB_stack_grow\fR(3C),
2788 2796  \fBreaddir\fR(3C), \fBpthread_create\fR(3C), \fBpthread_join\fR(3C),
2789 2797  \fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), \fBthr_create\fR(3C),
2790 2798  \fBthr_join\fR(3C), \fBtypes32.h\fR(3HEAD), \fBucontext.h\fR(3HEAD),
2791 2799  \fBwait\fR(3C), \fBcontract\fR(4), \fBcore\fR(4), \fBprocess\fR(4),
2792 2800  \fBlfcompile\fR(5), \fBprivileges\fR(5), \fBsecurity-flags\fR(5)
2793 2801  .SH DIAGNOSTICS
2794 2802  .LP
2795 2803  Errors that can occur in addition to the errors normally associated with file
2796 2804  system access:
2797 2805  .sp
2798 2806  .ne 2
2799 2807  .na
2800 2808  \fB\fBE2BIG\fR\fR
2801 2809  .ad
2802 2810  .RS 13n
2803 2811  Data to be returned in a \fBread\fR(2) of the page data file exceeds the size
2804 2812  of the read buffer provided by the caller.
2805 2813  .RE
2806 2814  
2807 2815  .sp
2808 2816  .ne 2
2809 2817  .na
2810 2818  \fB\fBEACCES\fR\fR
2811 2819  .ad
2812 2820  .RS 13n
2813 2821  An attempt was made to examine a process that ran under a different uid than
2814 2822  the controlling process and {\fBPRIV_PROC_OWNER\fR} was not asserted in the
2815 2823  effective set.
2816 2824  .RE
2817 2825  
2818 2826  .sp
2819 2827  .ne 2
2820 2828  .na
2821 2829  \fB\fBEAGAIN\fR\fR
2822 2830  .ad
2823 2831  .RS 13n
2824 2832  The traced process has performed an \fBexec\fR(2) of a setuid/setgid object
2825 2833  file or of an object file that it cannot read; all further operations on the
2826 2834  process or lwp file descriptor (except \fBclose\fR(2)) elicit this error.
2827 2835  .RE
2828 2836  
2829 2837  .sp
2830 2838  .ne 2
2831 2839  .na
2832 2840  \fB\fBEBUSY\fR\fR
2833 2841  .ad
2834 2842  .RS 13n
2835 2843  \fBPCSTOP\fR, \fBPCDSTOP\fR, \fBPCWSTOP\fR, or \fBPCTWSTOP\fR was applied to a
2836 2844  system process; an exclusive \fBopen\fR(2) was attempted on a \fB/proc\fR file
2837 2845  for a process already open for writing; \fBPCRUN\fR, \fBPCSREG\fR,
2838 2846  \fBPCSVADDR\fR, \fBPCSFPREG\fR, or \fBPCSXREG\fR was applied to a process or
2839 2847  lwp not stopped on an event of interest; an attempt was made to mount
2840 2848  \fB/proc\fR when it was already mounted; \fBPCAGENT\fR was applied to a process
2841 2849  that was not fully stopped or that already had an agent lwp.
2842 2850  .RE
2843 2851  
2844 2852  .sp
2845 2853  .ne 2
2846 2854  .na
2847 2855  \fB\fBEINVAL\fR\fR
2848 2856  .ad
2849 2857  .RS 13n
2850 2858  In general, this means that some invalid argument was supplied to a system
2851 2859  call. A non-exhaustive list of conditions eliciting this error includes: a
2852 2860  control message operation code is undefined; an out-of-range signal number was
2853 2861  specified with \fBPCSSIG\fR, \fBPCKILL\fR, or \fBPCUNKILL\fR; \fBSIGKILL\fR was
2854 2862  specified with \fBPCUNKILL\fR; \fBPCSFPREG\fR was applied on a system that does
2855 2863  not support floating-point operations; \fBPCSXREG\fR was applied on a system
2856 2864  that does not support extra state registers.
2857 2865  .RE
2858 2866  
2859 2867  .sp
2860 2868  .ne 2
2861 2869  .na
2862 2870  \fB\fBEINTR\fR\fR
2863 2871  .ad
2864 2872  .RS 13n
2865 2873  A signal was received by the controlling process while waiting for the traced
2866 2874  process or lwp to stop via \fBPCSTOP\fR, \fBPCWSTOP\fR, or \fBPCTWSTOP\fR.
2867 2875  .RE
2868 2876  
2869 2877  .sp
2870 2878  .ne 2
2871 2879  .na
2872 2880  \fB\fBEIO\fR\fR
2873 2881  .ad
2874 2882  .RS 13n
2875 2883  A \fBwrite\fR(2) was attempted at an illegal address in the traced process.
2876 2884  .RE
2877 2885  
2878 2886  .sp
2879 2887  .ne 2
2880 2888  .na
2881 2889  \fB\fBENOENT\fR\fR
2882 2890  .ad
2883 2891  .RS 13n
2884 2892  The traced process or lwp has terminated after being opened. The basic
2885 2893  privilege {\fBPRIV_PROC_INFO\fR} is not asserted in the effective set of the
2886 2894  calling process and the calling process cannot send a signal to the target
2887 2895  process.
2888 2896  .RE
2889 2897  
2890 2898  .sp
2891 2899  .ne 2
2892 2900  .na
2893 2901  \fB\fBENOMEM\fR\fR
2894 2902  .ad
2895 2903  .RS 13n
2896 2904  The system-imposed limit on the number of page data file descriptors was
2897 2905  reached on an open of \fB/proc/\fR\fIpid\fR\fB/pagedata\fR; an attempt was made
2898 2906  with \fBPCWATCH\fR to establish more watched areas than the system can support;
2899 2907  the \fBPCAGENT\fR operation was issued when the system was out of resources for
2900 2908  creating lwps.
2901 2909  .RE
2902 2910  
2903 2911  .sp
2904 2912  .ne 2
2905 2913  .na
2906 2914  \fB\fBENOSYS\fR\fR
2907 2915  .ad
2908 2916  .RS 13n
2909 2917  An attempt was made to perform an unsupported operation (such as
2910 2918  \fBcreat\fR(2), \fBlink\fR(2), or \fBunlink\fR(2)) on an entry in \fB/proc\fR.
2911 2919  .RE
2912 2920  
2913 2921  .sp
2914 2922  .ne 2
2915 2923  .na
2916 2924  \fB\fBEOVERFLOW\fR\fR
2917 2925  .ad
2918 2926  .RS 13n
2919 2927  A 32-bit controlling process attempted to read or write the \fBas\fR file or
2920 2928  attempted to read the \fBmap\fR, \fBrmap\fR, or \fBpagedata\fR file of a 64-bit
2921 2929  target process. A 32-bit controlling process attempted to apply one of the
2922 2930  control operations \fBPCSREG\fR, \fBPCSXREG\fR, \fBPCSVADDR\fR, \fBPCWATCH\fR,
2923 2931  \fBPCAGENT\fR, \fBPCREAD\fR, \fBPCWRITE\fR to a 64-bit target process.
2924 2932  .RE
2925 2933  
2926 2934  .sp
2927 2935  .ne 2
2928 2936  .na
2929 2937  \fB\fBEPERM\fR\fR
2930 2938  .ad
2931 2939  .RS 13n
2932 2940  The process that issued the \fBPCSCRED\fR or \fBPCSCREDX\fR operation did not
2933 2941  have the {\fBPRIV_PROC_SETID\fR} privilege asserted in its effective set, or
2934 2942  the process that issued the \fBPCNICE\fR operation did not have the
2935 2943  {\fBPRIV_PROC_PRIOCNTL\fR} in its effective set.
2936 2944  .sp
2937 2945  An attempt was made to control a process of which the E, P, and I privilege
2938 2946  sets were not a subset of the effective set of the controlling process or the
2939 2947  limit set of the controlling process is not a superset of limit set of the
2940 2948  controlled process.
2941 2949  .sp
2942 2950  Any of the uids of the target process are 0 or an attempt was made to change
2943 2951  any of the uids to 0 using PCSCRED and the security policy imposed additional
2944 2952  restrictions. See \fBprivileges\fR(5).
2945 2953  .RE
2946 2954  
2947 2955  .SH NOTES
2948 2956  .LP
2949 2957  Descriptions of structures in this document include only interesting structure
2950 2958  elements, not filler and padding fields, and may show elements out of order for
2951 2959  descriptive clarity. The actual structure definitions are contained in
2952 2960  \fB<procfs.h>\fR\&.
2953 2961  .SH BUGS
2954 2962  .LP
2955 2963  Because the old \fBioctl\fR(2)-based version of \fB/proc\fR is currently
2956 2964  supported for binary compatibility with old applications, the top-level
2957 2965  directory for a process, \fB/proc/\fR\fIpid\fR, is not world-readable, but it
2958 2966  is world-searchable. Thus, anyone can open \fB/proc/\fR\fIpid\fR\fB/psinfo\fR
2959 2967  even though \fBls\fR(1) applied to \fB/proc/\fR\fIpid\fR will fail for anyone
2960 2968  but the owner or an appropriately privileged process. Support for the old
2961 2969  \fBioctl\fR(2)-based version of \fB/proc\fR will be dropped in a future
2962 2970  release, at which time the top-level directory for a process will be made
2963 2971  world-readable.
2964 2972  .sp
2965 2973  .LP
2966 2974  On SPARC based machines, the types \fBgregset_t\fR and \fBfpregset_t\fR defined
2967 2975  in <\fBsys/regset.h\fR> are similar to but not the same as the types
2968 2976  \fBprgregset_t\fR and \fBprfpregset_t\fR defined in <\fBprocfs.h\fR>.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX