Code review comments from jeffpc
7029 want per-process exploit mitigation features (secflags)
7030 want basic address space layout randomization (aslr)
7031 noexec_user_stack should be a secflag
7032 want a means to forbid mappings around NULL.

          --- old/usr/src/man/man4/proc.4
          +++ new/usr/src/man/man4/proc.4
   1    1  '\" te
   2    2  .\" Copyright 1989 AT&T
   3    3  .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
   4    4  .\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
   5    5  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6    6  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7    7  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8      -.TH PROC 4 "Mar 31, 2013"
        8 +.TH PROC 4 "Jun 6, 2016"
   9    9  .SH NAME
  10   10  proc \- /proc, the process file system
  11   11  .SH DESCRIPTION
  12      -.sp
  13   12  .LP
  14   13  \fB/proc\fR is a file system that provides access to the state of each process
  15   14  and light-weight process (lwp) in the system. The name of each entry in the
  16   15  \fB/proc\fR directory is a decimal number corresponding to a process-ID. These
  17   16  entries are themselves subdirectories. Access to process state is provided by
  18   17  additional files contained within each subdirectory; the hierarchy is described
  19   18  more completely below. In this document, ``\fB/proc\fR file'' refers to a
  20   19  non-directory file within the hierarchy rooted at \fB/proc\fR. The owner of
  21   20  each \fB/proc\fR file and subdirectory is determined by the user-ID of the
  22   21  process.

  23   22  .sp
  24   23  .LP
  25   24  \fB/proc\fR can be mounted on any mount point, in addition to the standard
  26   25  \fB/proc\fR mount point, and can be mounted several places at once. Such
  27   26  additional mounts are allowed in order to facilitate the confinement of
  28   27  processes to subtrees of the file system via \fBchroot\fR(1M) and yet allow
  29   28  such processes access to commands like \fBps\fR(1).
  30   29  .sp
  31   30  .LP
  32   31  Standard system calls are used to access \fB/proc\fR files: \fBopen\fR(2),
  33   32  \fBclose\fR(2), \fBread\fR(2), and \fBwrite\fR(2) (including \fBreadv\fR(2),
  34   33  \fBwritev\fR(2), \fBpread\fR(2), and \fBpwrite\fR(2)). Most files describe
  35   34  process state and can only be opened for reading. \fBctl\fR and \fBlwpctl\fR
  36   35  (control) files permit manipulation of process state and can only be opened for
  37   36  writing. \fBas\fR (address space) files contain the image of the running
  38   37  process and can be opened for both reading and writing. An open for writing
  39   38  allows process control; a read-only open allows inspection but not control. In
  40   39  this document, we refer to the process as open for reading or writing if any of
  41   40  its associated \fB/proc\fR files is open for reading or writing.
  42   41  .sp
  43   42  .LP
  44   43  In general, more than one process can open the same \fB/proc\fR file at the
  45   44  same time. \fIExclusive\fR \fIopen\fR is an advisory mechanism provided to
  46   45  allow controlling processes to avoid collisions with each other. A process can
  47   46  obtain exclusive control of a target process, with respect to other cooperating
  48   47  processes, if it successfully opens any \fB/proc\fR file in the target process
  49   48  for writing (the \fBas\fR or \fBctl\fR files, or the \fBlwpctl\fR file of any
  50   49  lwp) while specifying \fBO_EXCL\fR in the \fBopen\fR(2). Such an open will fail
  51   50  if the target process is already open for writing (that is, if an \fBas\fR,
  52   51  \fBctl\fR, or \fBlwpctl\fR file is already open for writing). There can be any
  53   52  number of concurrent read-only opens; \fBO_EXCL\fR is ignored on opens for
  54   53  reading. It is recommended that the first open for writing by a controlling
  55   54  process use the \fBO_EXCL\fR flag; multiple controlling processes usually
  56   55  result in chaos.
  57   56  .sp
  58   57  .LP
  59   58  If a process opens one of its own \fB/proc\fR files for writing, the open
  60   59  succeeds regardless of \fBO_EXCL\fR and regardless of whether some other
  61   60  process has the process open for writing. Self-opens do not count when another
  62   61  process attempts an exclusive open. (A process cannot exclude a debugger by
  63   62  opening itself for writing and the application of a debugger cannot prevent a
  64   63  process from opening itself.) All self-opens for writing are forced to be
  65   64  close-on-exec (see the \fBF_SETFD\fR operation of \fBfcntl\fR(2)).
  66   65  .sp
  67   66  .LP
  68   67  Data may be transferred from or to any locations in the address space of the
  69   68  traced process by applying \fBlseek\fR(2) to position the \fBas\fR file at the
  70   69  virtual address of interest followed by \fBread\fR(2) or \fBwrite\fR(2) (or by
  71   70  using \fBpread\fR(2) or \fBpwrite\fR(2) for the combined operation). The
  72   71  address-map files \fB/proc/\fR\fIpid\fR\fB/map\fR and
  73   72  \fB/proc/\fR\fIpid\fR\fB/xmap\fR can be read to determine the accessible areas
  74   73  (mappings) of the address space. \fBI/O\fR transfers may span contiguous
  75   74  mappings. An \fBI/O\fR request extending into an unmapped area is truncated at
  76   75  the boundary. A write request beginning at an unmapped virtual address fails
  77   76  with \fBEIO\fR; a read request beginning at an unmapped virtual address returns
  78   77  zero (an end-of-file indication).
  79   78  .sp
  80   79  .LP
  81   80  Information and control operations are provided through additional files.
  82   81  \fB<procfs.h>\fR contains definitions of data structures and message formats
  83   82  used with these files. Some of these definitions involve the use of sets of
  84   83  flags. The set types \fBsigset_t\fR, \fBfltset_t\fR, and \fBsysset_t\fR
  85   84  correspond, respectively, to signal, fault, and system call enumerations
  86   85  defined in \fB<sys/signal.h>\fR, \fB<sys/fault.h>\fR, and
  87   86  \fB<sys/syscall.h>\fR\&. Each set type is large enough to hold flags for its
  88   87  own enumeration. Although they are of different sizes, they have a common
  89   88  structure and can be manipulated by these macros:
  90   89  .sp
  91   90  .in +2
  92   91  .nf
  93   92  prfillset(&set);             /* turn on all flags in set */
  94   93  premptyset(&set);            /* turn off all flags in set */
  95   94  praddset(&set, flag);        /* turn on the specified flag */
  96   95  prdelset(&set, flag);        /* turn off the specified flag */
  97   96  r = prismember(&set, flag);  /* != 0 iff flag is turned on */
  98   97  .fi
  99   98  .in -2
 100   99  
 101  100  .sp
 102  101  .LP
 103  102  One of \fBprfillset()\fR or \fBpremptyset()\fR must be used to initialize
 104  103  \fBset\fR before it is used in any other operation. \fBflag\fR must be a member
 105  104  of the enumeration corresponding to \fBset\fR.
 106  105  .sp
 107  106  .LP
 108  107  Every process contains at least one \fIlight-weight process\fR, or \fIlwp\fR.
 109  108  Each lwp represents a flow of execution that is independently scheduled by the
 110  109  operating system. All lwps in a process share its address space as well as many
 111  110  other attributes. Through the use of \fBlwpctl\fR and \fBctl\fR files as
 112  111  described below, it is possible to affect individual lwps in a process or to
 113  112  affect all of them at once, depending on the operation.
 114  113  .sp
 115  114  .LP
 116  115  When the process has more than one lwp, a representative lwp is chosen by the
 117  116  system for certain process status files and control operations. The
 118  117  representative lwp is a stopped lwp only if all of the process's lwps are
 119  118  stopped; is stopped on an event of interest only if all of the lwps are so
 120  119  stopped (excluding \fBPR_SUSPENDED\fR lwps); is in a \fBPR_REQUESTED\fR stop
 121  120  only if there are no other events of interest to be found; or, failing
 122  121  everything else, is in a \fBPR_SUSPENDED\fR stop (implying that the process is
 123  122  deadlocked). See the description of the \fBstatus\fR file for definitions of
 124  123  stopped states. See the \fBPCSTOP\fR control operation for the definition of
 125  124  ``event of interest''.
 126  125  .sp
 127  126  .LP
 128  127  The representative lwp remains fixed (it will be chosen again on the next
 129  128  operation) as long as all of the lwps are stopped on events of interest or are
 130  129  in a \fBPR_SUSPENDED\fR stop and the \fBPCRUN\fR control operation is not
 131  130  applied to any of them.
 132  131  .sp
 133  132  .LP
 134  133  When applied to the process control file, every \fB/proc\fR control operation
 135  134  that must act on an lwp uses the same algorithm to choose which lwp to act
 136  135  upon. Together with synchronous stopping (see \fBPCSET\fR), this enables a
 137  136  debugger to control a multiple-lwp process using only the process-level status
 138  137  and control files if it so chooses. More fine-grained control can be achieved
 139  138  using the lwp-specific files.
 140  139  .sp
 141  140  .LP
 142  141  The system supports two process data models, the traditional 32-bit data model
 143  142  in which ints, longs and pointers are all 32 bits wide (the ILP32 data model),
 144  143  and on some platforms the 64-bit data model in which longs and pointers, but
 145  144  not ints, are 64 bits in width (the LP64 data model). In the LP64 data model
 146  145  some system data types, notably \fBsize_t\fR, \fBoff_t\fR, \fBtime_t\fR and
 147  146  \fBdev_t\fR, grow from 32 bits to 64 bits as well.
 148  147  .sp
 149  148  .LP
 150  149  The \fB/proc\fR interfaces described here are available to both 32-bit and
 151  150  64-bit controlling processes. However, many operations attempted by a 32-bit
 152  151  controlling process on a 64-bit target process will fail with \fBEOVERFLOW\fR
 153  152  because the address space range of a 32-bit process cannot encompass a 64-bit
 154  153  process or because the data in some 64-bit system data type cannot be
 155  154  compressed to fit into the corresponding 32-bit type without loss of
 156  155  information. Operations that fail in this circumstance include reading and
 157  156  writing the address space, reading the address-map files, and setting the
 158  157  target process's registers. There is no restriction on operations applied by a
 159  158  64-bit process to either a 32-bit or a 64-bit target processes.
 160  159  .sp
 161  160  .LP
 162  161  The format of the contents of any \fB/proc\fR file depends on the data model of
 163  162  the observer (the controlling process), not on the data model of the target
 164  163  process. A 64-bit debugger does not have to translate the information it reads
 165  164  from a \fB/proc\fR file for a 32-bit process from 32-bit format to 64-bit
 166  165  format. However, it usually has to be aware of the data model of the target

 167  166  process. The \fBpr_dmodel\fR field of the \fBstatus\fR files indicates the
 168  167  target process's data model.
 169  168  .sp
 170  169  .LP
 171  170  To help deal with system data structures that are read from 32-bit processes, a
 172  171  64-bit controlling program can be compiled with the C preprocessor symbol
 173  172  \fB_SYSCALL32\fR defined before system header files are included. This makes
 174  173  explicit 32-bit fixed-width data structures (like \fBcstruct stat32\fR) visible
 175  174  to the 64-bit program. See \fBtypes32.h\fR(3HEAD).
 176  175  .SH DIRECTORY STRUCTURE
 177      -.sp
 178  176  .LP
 179  177  At the top level, the directory \fB/proc\fR contains entries each of which
 180  178  names an existing process in the system. These entries are themselves
 181  179  directories. Except where otherwise noted, the files described below can be
 182  180  opened for reading only. In addition, if a process becomes a \fIzombie\fR (one
 183  181  that has exited but whose parent has not yet performed a \fBwait\fR(3C) upon
 184  182  it), most of its associated \fB/proc\fR files disappear from the hierarchy;
 185  183  subsequent attempts to open them, or to read or write files opened before the
 186  184  process exited, will elicit the error \fBENOENT\fR.
 187  185  .sp

 188  186  .LP
 189  187  Although process state and consequently the contents of \fB/proc\fR files can
 190  188  change from instant to instant, a single \fBread\fR(2) of a \fB/proc\fR file is
 191  189  guaranteed to return a sane representation of state; that is, the read will be
 192  190  atomic with respect to the state of the process. No such guarantee applies to
 193  191  successive reads applied to a \fB/proc\fR file for a running process. In

 194  192  addition, atomicity is not guaranteed for \fBI/O\fR applied to the \fBas\fR
 195  193  (address-space) file for a running process or for a process whose address space
 196  194  contains memory shared by another running process.
 197  195  .sp
 198  196  .LP
 199  197  A number of structure definitions are used to describe the files. These
 200  198  structures may grow by the addition of elements at the end in future releases
 201  199  of the system and it is not legitimate for a program to assume that they will
 202  200  not.
 203  201  .SH STRUCTURE OF \fB/proc/\fR\fIpid\fR
 204      -.sp
 205  202  .LP
 206  203  A given directory \fB/proc/\fR\fIpid\fR contains the following entries. A
 207  204  process can use the invisible alias \fB/proc/self\fR if it wishes to open one
 208  205  of its own \fB/proc\fR files (invisible in the sense that the name ``self''
 209  206  does not appear in a directory listing of \fB/proc\fR obtained from
 210  207  \fBls\fR(1), \fBgetdents\fR(2), or \fBreaddir\fR(3C)).
 211  208  .SS "contracts"
 212      -.sp
 213  209  .LP
 214  210  A directory containing references to the contracts held by the process. Each
 215  211  entry is a symlink to the contract's directory under \fB/system/contract\fR.
 216  212  See \fBcontract\fR(4).
 217  213  .SS "as"
 218      -.sp
 219  214  .LP
 220  215  Contains the address-space image of the process; it can be opened for both
 221  216  reading and writing. \fBlseek\fR(2) is used to position the file at the virtual
 222  217  address of interest and then the address space can be examined or changed
 223  218  through \fBread\fR(2) or \fBwrite\fR(2) (or by using \fBpread\fR(2) or
 224  219  \fBpwrite\fR(2) for the combined operation).
 225  220  .SS "ctl"
 226      -.sp
 227  221  .LP
 228  222  A write-only file to which structured messages are written directing the system
 229  223  to change some aspect of the process's state or control its behavior in some
 230  224  way. The seek offset is not relevant when writing to this file. Individual lwps
 231  225  also have associated \fBlwpctl\fR files in the lwp subdirectories. A control
 232  226  message may be written either to the process's \fBctl\fR file or to a specific
 233  227  \fBlwpctl\fR file with operation-specific effects. The effect of a control
 234  228  message is immediately reflected in the state of the process visible through
 235  229  appropriate status and information files. The types of control messages are
 236  230  described in detail later. See \fBCONTROL MESSAGES\fR.
 237  231  .SS "status"
 238      -.sp
 239  232  .LP
 240  233  Contains state information about the process and the representative lwp. The
 241  234  file contains a \fBpstatus\fR structure which contains an embedded
 242  235  \fBlwpstatus\fR structure for the representative lwp, as follows:
 243  236  .sp
 244  237  .in +2
 245  238  .nf
 246  239  typedef struct pstatus {
 247  240       int pr_flags;            /* flags (see below) */
 248  241       int pr_nlwp;             /* number of active lwps in the process */

 249  242       int pr_nzomb;            /* number of zombie lwps in the process */
 250  243       pid_tpr_pid;             /* process id */
 251  244       pid_tpr_ppid;            /* parent process id */
 252  245       pid_tpr_pgid;            /* process group id */
 253  246       pid_tpr_sid;             /* session id */
 254  247       id_t pr_aslwpid;         /* obsolete */
 255  248       id_t pr_agentid;         /* lwp-id of the agent lwp, if any */
 256  249       sigset_t pr_sigpend;     /* set of process pending signals */
 257  250       uintptr_t pr_brkbase;    /* virtual address of the process heap */
 258  251       size_t pr_brksize;       /* size of the process heap, in bytes */
 259  252       uintptr_t pr_stkbase;    /* virtual address of the process stack */
 260  253       size_tpr_stksize;        /* size of the process stack, in bytes */
 261  254       timestruc_t pr_utime;    /* process user cpu time */
 262  255       timestruc_t pr_stime;    /* process system cpu time */
 263  256       timestruc_t pr_cutime;   /* sum of children's user times */
 264  257       timestruc_t pr_cstime;   /* sum of children's system times */
 265  258       sigset_t pr_sigtrace;    /* set of traced signals */
 266  259       fltset_t pr_flttrace;    /* set of traced faults */
 267  260       sysset_t pr_sysentry;    /* set of system calls traced on entry */
 268  261       sysset_t pr_sysexit;     /* set of system calls traced on exit */
 269  262       char pr_dmodel;          /* data model of the process */
 270  263       taskid_t pr_taskid;      /* task id */
 271  264       projid_t pr_projid;      /* project id */
 272  265       zoneid_t pr_zoneid;      /* zone id */
 273  266       lwpstatus_t pr_lwp;      /* status of the representative lwp */
 274  267  } pstatus_t;
 275  268  .fi
 276  269  .in -2
 277  270  
 278  271  .sp
 279  272  .LP
 280  273  \fBpr_flags\fR is a bit-mask holding the following process flags. For
 281  274  convenience, it also contains the lwp flags for the representative lwp,
 282  275  described later.
 283  276  .sp
 284  277  .ne 2
 285  278  .na
 286  279  \fB\fBPR_ISSYS\fR\fR
 287  280  .ad
 288  281  .RS 13n
 289  282  process is a system process (see \fBPCSTOP\fR).
 290  283  .RE
 291  284  
 292  285  .sp
 293  286  .ne 2
 294  287  .na
 295  288  \fB\fBPR_VFORKP\fR\fR
 296  289  .ad
 297  290  .RS 13n
 298  291  process is the parent of a vforked child (see \fBPCWATCH\fR).
 299  292  .RE
 300  293  
 301  294  .sp
 302  295  .ne 2
 303  296  .na
 304  297  \fB\fBPR_FORK\fR\fR
 305  298  .ad
 306  299  .RS 13n
 307  300  process has its inherit-on-fork mode set (see \fBPCSET\fR).
 308  301  .RE
 309  302  
 310  303  .sp
 311  304  .ne 2
 312  305  .na
 313  306  \fB\fBPR_RLC\fR\fR
 314  307  .ad
 315  308  .RS 13n
 316  309  process has its run-on-last-close mode set (see \fBPCSET\fR).
 317  310  .RE
 318  311  
 319  312  .sp
 320  313  .ne 2
 321  314  .na
 322  315  \fB\fBPR_KLC\fR\fR
 323  316  .ad
 324  317  .RS 13n
 325  318  process has its kill-on-last-close mode set (see \fBPCSET\fR).
 326  319  .RE
 327  320  
 328  321  .sp
 329  322  .ne 2
 330  323  .na
 331  324  \fB\fBPR_ASYNC\fR\fR
 332  325  .ad
 333  326  .RS 13n
 334  327  process has its asynchronous-stop mode set (see \fBPCSET\fR).
 335  328  .RE
 336  329  
 337  330  .sp
 338  331  .ne 2
 339  332  .na
 340  333  \fB\fBPR_MSACCT\fR\fR
 341  334  .ad
 342  335  .RS 13n
 343  336  Set by default in all processes to indicate that microstate accounting is
 344  337  enabled. However, this flag has been deprecated and no longer has any effect.
 345  338  Microstate accounting may not be disabled; however, it is still possible to
 346  339  toggle the flag.
 347  340  .RE
 348  341  
 349  342  .sp
 350  343  .ne 2
 351  344  .na
 352  345  \fB\fBPR_MSFORK\fR\fR
 353  346  .ad
 354  347  .RS 13n
 355  348  Set by default in all processes to indicate that microstate accounting will be
 356  349  enabled for processes that this parent forks(). However, this flag has been
 357  350  deprecated and no longer has any effect. It is possible to toggle this flag;
 358  351  however, it is not possible to disable microstate accounting.
 359  352  .RE
 360  353  
 361  354  .sp
 362  355  .ne 2
 363  356  .na
 364  357  \fB\fBPR_BPTADJ\fR\fR
 365  358  .ad
 366  359  .RS 13n
 367  360  process has its breakpoint adjustment mode set (see \fBPCSET\fR).
 368  361  .RE
 369  362  
 370  363  .sp
 371  364  .ne 2
 372  365  .na
 373  366  \fB\fBPR_PTRACE\fR\fR
 374  367  .ad
 375  368  .RS 13n
 376  369  process has its ptrace-compatibility mode set (see \fBPCSET\fR).
 377  370  .RE
 378  371  
 379  372  .sp
 380  373  .LP
 381  374  \fBpr_nlwp\fR is the total number of active lwps in the process. pr_nzomb is
 382  375  the total number of zombie lwps in the process. A zombie lwp is a non-detached
 383  376  lwp that has terminated but has not been reaped with \fBthr_join\fR(3C) or
 384  377  \fBpthread_join\fR(3C).
 385  378  .sp
 386  379  .LP
 387  380  \fBpr_pid\fR, \fBpr_ppid\fR, \fBpr_pgid\fR, and \fBpr_sid\fR are, respectively,
 388  381  the process ID, the ID of the process's parent, the process's process group ID,
 389  382  and the process's session ID.
 390  383  .sp
 391  384  .LP
 392  385  \fBpr_aslwpid\fR is obsolete and is always zero.
 393  386  .sp
 394  387  .LP
 395  388  \fBpr_agentid\fR is the lwp-ID for the \fB/proc\fR agent lwp (see the
 396  389  \fBPCAGENT\fR control operation). It is zero if there is no agent lwp in the
 397  390  process.
 398  391  .sp
 399  392  .LP
 400  393  \fBpr_sigpend\fR identifies asynchronous signals pending for the process.
 401  394  .sp
 402  395  .LP
 403  396  \fBpr_brkbase\fR is the virtual address of the process heap and
 404  397  \fBpr_brksize\fR is its size in bytes. The address formed by the sum of these
 405  398  values is the process \fBbreak\fR (see \fBbrk\fR(2)). \fBpr_stkbase\fR and
 406  399  \fBpr_stksize\fR are, respectively, the virtual address of the process stack
 407  400  and its size in bytes. (Each lwp runs on a separate stack; the distinguishing
 408  401  characteristic of the process stack is that the operating system will grow it
 409  402  when necessary.)
 410  403  .sp
 411  404  .LP
 412  405  \fBpr_utime\fR, \fBpr_stime\fR, \fBpr_cutime\fR, and \fBpr_cstime\fR are,
 413  406  respectively, the user \fBCPU\fR and system \fBCPU\fR time consumed by the
 414  407  process, and the cumulative user \fBCPU\fR and system \fBCPU\fR time consumed
 415  408  by the process's children, in seconds and nanoseconds.
 416  409  .sp
 417  410  .LP
 418  411  \fBpr_sigtrace\fR and \fBpr_flttrace\fR contain, respectively, the set of
 419  412  signals and the set of hardware faults that are being traced (see
 420  413  \fBPCSTRACE\fR and \fBPCSFAULT\fR).
 421  414  .sp
 422  415  .LP
 423  416  \fBpr_sysentry\fR and \fBpr_sysexit\fR contain, respectively, the sets of
 424  417  system calls being traced on entry and exit (see \fBPCSENTRY\fR and
 425  418  \fBPCSEXIT\fR).
 426  419  .sp
 427  420  .LP
 428  421  \fBpr_dmodel\fR indicates the data model of the process. Possible values are:
 429  422  .sp
 430  423  .ne 2
 431  424  .na
 432  425  \fB\fBPR_MODEL_ILP32\fR\fR
 433  426  .ad
 434  427  .RS 19n
 435  428  process data model is ILP32.
 436  429  .RE
 437  430  
 438  431  .sp
 439  432  .ne 2
 440  433  .na
 441  434  \fB\fBPR_MODEL_LP64\fR\fR
 442  435  .ad
 443  436  .RS 19n
 444  437  process data model is LP64.
 445  438  .RE
 446  439  
 447  440  .sp
 448  441  .ne 2
 449  442  .na
 450  443  \fB\fBPR_MODEL_NATIVE\fR\fR
 451  444  .ad
 452  445  .RS 19n
 453  446  process data model is native.
 454  447  .RE
 455  448  
 456  449  .sp
 457  450  .LP
 458  451  The \fBpr_taskid\fR, \fBpr_projid\fR, and \fBpr_zoneid\fR fields contain
 459  452  respectively, the numeric \fBID\fRs of the task, project, and zone in which the
 460  453  process was running.
 461  454  .sp
 462  455  .LP
 463  456  The constant \fBPR_MODEL_NATIVE\fR reflects the data model of the controlling
 464  457  process, \fIthat is\fR, its value is \fBPR_MODEL_ILP32\fR or
 465  458  \fBPR_MODEL_LP64\fR according to whether the controlling process has been
 466  459  compiled as a 32-bit program or a 64-bit program, respectively.
 467  460  .sp
 468  461  .LP
 469  462  \fBpr_lwp\fR contains the status information for the representative lwp:
 470  463  .sp
 471  464  .in +2
 472  465  .nf
 473  466  typedef struct lwpstatus {
 474  467    int pr_flags;              /* flags (see below) */
 475  468    id_t pr_lwpid;             /* specific lwp identifier */
 476  469    short pr_why;              /* reason for lwp stop, if stopped */
 477  470    short pr_what;             /* more detailed reason */
 478  471    short pr_cursig;           /* current signal, if any */
 479  472    siginfo_t pr_info;         /* info associated with signal or fault */
 480  473    sigset_t pr_lwppend;       /* set of signals pending to the lwp */
 481  474    sigset_t pr_lwphold;       /* set of signals blocked by the lwp */
 482  475    struct sigaction pr_action;/* signal action for current signal */
 483  476    stack_t pr_altstack;       /* alternate signal stack info */
 484  477    uintptr_t pr_oldcontext;   /* address of previous ucontext */
 485  478    short pr_syscall;          /* system call number (if in syscall) */
 486  479    short pr_nsysarg;          /* number of arguments to this syscall */
 487  480    int pr_errno;              /* errno for failed syscall */
 488  481    long pr_sysarg[PRSYSARGS]; /* arguments to this syscall */
 489  482    long pr_rval1;             /* primary syscall return value */
 490  483    long pr_rval2;             /* second syscall return value, if any */
 491  484    char pr_clname[PRCLSZ];    /* scheduling class name */
 492  485    timestruc_t pr_tstamp;     /* real-time time stamp of stop */
 493  486    timestruc_t pr_utime;      /* lwp user cpu time */
 494  487    timestruc_t pr_stime;      /* lwp system cpu time */
 495  488    uintptr_t pr_ustack;       /* stack boundary data (stack_t) address */
 496  489    ulong_t pr_instr;          /* current instruction */
 497  490    prgregset_t pr_reg;        /* general registers */
 498  491    prfpregset_t pr_fpreg;     /* floating-point registers */
 499  492  } lwpstatus_t;
 500  493  .fi
 501  494  .in -2
 502  495  
 503  496  .sp
 504  497  .LP
 505  498  \fBpr_flags\fR is a bit-mask holding the following lwp flags. For convenience,
 506  499  it also contains the process flags, described previously.
 507  500  .sp
 508  501  .ne 2
 509  502  .na
 510  503  \fB\fBPR_STOPPED\fR\fR
 511  504  .ad
 512  505  .RS 14n
 513  506  The lwp is stopped.
 514  507  .RE
 515  508  
 516  509  .sp
 517  510  .ne 2
 518  511  .na
 519  512  \fB\fBPR_ISTOP\fR\fR
 520  513  .ad
 521  514  .RS 14n
 522  515  The lwp is stopped on an event of interest (see \fBPCSTOP\fR).
 523  516  .RE
 524  517  
 525  518  .sp
 526  519  .ne 2
 527  520  .na
 528  521  \fB\fBPR_DSTOP\fR\fR
 529  522  .ad
 530  523  .RS 14n
 531  524  The lwp has a stop directive in effect (see \fBPCSTOP\fR).
 532  525  .RE
 533  526  
 534  527  .sp
 535  528  .ne 2
 536  529  .na
 537  530  \fB\fBPR_STEP\fR\fR
 538  531  .ad
 539  532  .RS 14n
 540  533  The lwp has a single-step directive in effect (see \fBPCRUN\fR).
 541  534  .RE
 542  535  
 543  536  .sp
 544  537  .ne 2
 545  538  .na
 546  539  \fB\fBPR_ASLEEP\fR\fR
 547  540  .ad
 548  541  .RS 14n
 549  542  The lwp is in an interruptible sleep within a system call.
 550  543  .RE
 551  544  
 552  545  .sp
 553  546  .ne 2
 554  547  .na
 555  548  \fB\fBPR_PCINVAL\fR\fR
 556  549  .ad
 557  550  .RS 14n
 558  551  The lwp's current instruction (\fBpr_instr\fR) is undefined.
 559  552  .RE
 560  553  
 561  554  .sp
 562  555  .ne 2
 563  556  .na
 564  557  \fB\fBPR_DETACH\fR\fR
 565  558  .ad
 566  559  .RS 14n
 567  560  This is a detached lwp (see \fBpthread_create\fR(3C) and
 568  561  \fBpthread_join\fR(3C)).
 569  562  .RE
 570  563  
 571  564  .sp
 572  565  .ne 2
 573  566  .na
 574  567  \fB\fBPR_DAEMON\fR\fR
 575  568  .ad
 576  569  .RS 14n
 577  570  This is a daemon lwp (see \fBpthread_create\fR(3C)).
 578  571  .RE
 579  572  
 580  573  .sp
 581  574  .ne 2
 582  575  .na
 583  576  \fB\fBPR_ASLWP\fR\fR
 584  577  .ad
 585  578  .RS 14n
 586  579  This flag is obsolete and is never set.
 587  580  .RE
 588  581  
 589  582  .sp
 590  583  .ne 2
 591  584  .na
 592  585  \fB\fBPR_AGENT\fR\fR
 593  586  .ad
 594  587  .RS 14n
 595  588  This is the \fB/proc\fR agent lwp for the process.
 596  589  .RE
 597  590  
 598  591  .sp
 599  592  .LP
 600  593  \fBpr_lwpid\fR names the specific lwp.
 601  594  .sp
 602  595  .LP
 603  596  \fBpr_why\fR and \fBpr_what\fR together describe, for a stopped lwp, the reason
 604  597  for the stop. Possible values of \fBpr_why\fR and the associated \fBpr_what\fR
 605  598  are:
 606  599  .sp
 607  600  .ne 2
 608  601  .na
 609  602  \fB\fBPR_REQUESTED\fR\fR
 610  603  .ad
 611  604  .RS 17n
 612  605  indicates that the stop occurred in response to a stop directive, normally
 613  606  because \fBPCSTOP\fR was applied or because another lwp stopped on an event of
 614  607  interest and the asynchronous-stop flag (see \fBPCSET\fR) was not set for the
 615  608  process. \fBpr_what\fR is unused in this case.
 616  609  .RE
 617  610  
 618  611  .sp
 619  612  .ne 2
 620  613  .na
 621  614  \fB\fBPR_SIGNALLED\fR\fR
 622  615  .ad
 623  616  .RS 17n
 624  617  indicates that the lwp stopped on receipt of a signal (see \fBPCSTRACE\fR);
 625  618  \fBpr_what\fR holds the signal number that caused the stop (for a newly-stopped
 626  619  lwp, the same value is in \fBpr_cursig\fR).
 627  620  .RE
 628  621  
 629  622  .sp
 630  623  .ne 2
 631  624  .na
 632  625  \fB\fBPR_FAULTED\fR\fR
 633  626  .ad
 634  627  .RS 17n
 635  628  indicates that the lwp stopped on incurring a hardware fault (see
 636  629  \fBPCSFAULT\fR); \fBpr_what\fR holds the fault number that caused the stop.
 637  630  .RE
 638  631  
 639  632  .sp
 640  633  .ne 2
 641  634  .na
 642  635  \fB\fBPR_SYSENTRY\fR\fR
 643  636  .ad
 644  637  .br
 645  638  .na
 646  639  \fB\fBPR_SYSEXIT\fR\fR
 647  640  .ad
 648  641  .RS 17n
 649  642  indicate a stop on entry to or exit from a system call (see \fBPCSENTRY\fR and
 650  643  \fBPCSEXIT\fR); \fBpr_what\fR holds the system call number.
 651  644  .RE
 652  645  
 653  646  .sp
 654  647  .ne 2
 655  648  .na
 656  649  \fB\fBPR_JOBCONTROL\fR\fR
 657  650  .ad
 658  651  .RS 17n
 659  652  indicates that the lwp stopped due to the default action of a job control stop
 660  653  signal (see \fBsigaction\fR(2)); \fBpr_what\fR holds the stopping signal
 661  654  number.
 662  655  .RE
 663  656  
 664  657  .sp
 665  658  .ne 2
 666  659  .na
 667  660  \fB\fBPR_SUSPENDED\fR\fR
 668  661  .ad
 669  662  .RS 17n
 670  663  indicates that the lwp stopped due to internal synchronization of lwps within
 671  664  the process. \fBpr_what\fR is unused in this case.
 672  665  .RE
 673  666  
 674  667  .sp
 675  668  .LP
 676  669  \fBpr_cursig\fR names the current signal, that is, the next signal to be
 677  670  delivered to the lwp, if any. \fBpr_info\fR, when the lwp is in a
 678  671  \fBPR_SIGNALLED\fR or \fBPR_FAULTED\fR stop, contains additional information
 679  672  pertinent to the particular signal or fault (see \fB<sys/siginfo.h>\fR).
 680  673  .sp
 681  674  .LP
 682  675  \fBpr_lwppend\fR identifies any synchronous or directed signals pending for the
 683  676  lwp. \fBpr_lwphold\fR identifies those signals whose delivery is being blocked
 684  677  by the lwp (the signal mask).
 685  678  .sp
 686  679  .LP
 687  680  \fBpr_action\fR contains the signal action information pertaining to the
 688  681  current signal (see \fBsigaction\fR(2)); it is undefined if \fBpr_cursig\fR is
 689  682  zero. \fBpr_altstack\fR contains the alternate signal stack information for the
 690  683  lwp (see \fBsigaltstack\fR(2)).
 691  684  .sp
 692  685  .LP
 693  686  \fBpr_oldcontext\fR, if not zero, contains the address on the lwp stack of a
 694  687  \fBucontext\fR structure describing the previous user-level context (see
 695  688  \fBucontext.h\fR(3HEAD)). It is non-zero only if the lwp is executing in the
 696  689  context of a signal handler.
 697  690  .sp
 698  691  .LP
 699  692  \fBpr_syscall\fR is the number of the system call, if any, being executed by
 700  693  the lwp; it is non-zero if and only if the lwp is stopped on \fBPR_SYSENTRY\fR
 701  694  or \fBPR_SYSEXIT\fR, or is asleep within a system call ( \fBPR_ASLEEP\fR is
 702  695  set). If \fBpr_syscall\fR is non-zero, \fBpr_nsysarg\fR is the number of
 703  696  arguments to the system call and \fBpr_sysarg\fR contains the actual arguments.
 704  697  .sp
 705  698  .LP
 706  699  \fBpr_rval1\fR, \fBpr_rval2\fR, and \fBpr_errno\fR are defined only if the lwp
 707  700  is stopped on \fBPR_SYSEXIT\fR or if the \fBPR_VFORKP\fR flag is set. If
 708  701  \fBpr_errno\fR is zero, \fBpr_rval1\fR and \fBpr_rval2\fR contain the return
 709  702  values from the system call. Otherwise, \fBpr_errno\fR contains the error
 710  703  number for the failing system call (see \fB<sys/errno.h>\fR).
 711  704  .sp
 712  705  .LP
 713  706  \fBpr_clname\fR contains the name of the lwp's scheduling class.
 714  707  .sp
 715  708  .LP
 716  709  \fBpr_tstamp\fR, if the lwp is stopped, contains a time stamp marking when the
 717  710  lwp stopped, in real time seconds and nanoseconds since an arbitrary time in
 718  711  the past.
 719  712  .sp
 720  713  .LP
 721  714  \fBpr_utime\fR is the amount of user level CPU time used by this LWP.
 722  715  .sp
 723  716  .LP
 724  717  \fBpr_stime\fR is the amount of system level CPU time used by this LWP.
 725  718  .sp
 726  719  .LP
 727  720  \fBpr_ustack\fR is the virtual address of the \fBstack_t\fR that contains the
 728  721  stack boundaries for this LWP. See \fBgetustack\fR(2) and
 729  722  \fB_stack_grow\fR(3C).
 730  723  .sp
 731  724  .LP
 732  725  \fBpr_instr\fR contains the machine instruction to which the lwp's program
 733  726  counter refers. The amount of data retrieved from the process is
 734  727  machine-dependent. On SPARC based machines, it is a 32-bit word. On x86-based
 735  728  machines, it is a single byte. In general, the size is that of the machine's
 736  729  smallest instruction. If \fBPR_PCINVAL\fR is set, \fBpr_instr\fR is undefined;
 737  730  this occurs whenever the lwp is not stopped or when the program counter refers
 738  731  to an invalid virtual address.
 739  732  .sp
 740  733  .LP
 741  734  \fBpr_reg\fR is an array holding the contents of a stopped lwp's general
 742  735  registers.
 743  736  .sp
 744  737  .ne 2
 745  738  .na
 746  739  \fBSPARC\fR
 747  740  .ad
 748  741  .RS 21n
 749  742  On SPARC-based machines, the predefined constants \fBR_G0\fR ... \fBR_G7\fR,
 750  743  \fBR_O0\fR ... \fBR_O7\fR, \fBR_L0\fR ... \fBR_L7\fR, \fBR_I0\fR ...
 751  744  \fBR_I7\fR, \fBR_PC\fR, \fBR_nPC\fR, and \fBR_Y\fR can be used as indices to
 752  745  refer to the corresponding registers; previous register windows can be read
 753  746  from their overflow locations on the stack (however, see the \fBgwindows\fR
 754  747  file in the \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR subdirectory).
 755  748  .RE
 756  749  
 757  750  .sp
 758  751  .ne 2
 759  752  .na
 760  753  \fBSPARC V8 (32-bit)\fR
 761  754  .ad
 762  755  .RS 21n
 763  756  For SPARC V8 (32-bit) controlling processes, the predefined constants
 764  757  \fBR_PSR\fR, \fBR_WIM\fR, and \fBR_TBR\fR can be used as indices to refer to
 765  758  the corresponding special registers. For SPARC V9 (64-bit) controlling
 766  759  processes, the predefined constants \fBR_CCR\fR, \fBR_ASI\fR, and \fBR_FPRS\fR
 767  760  can be used as indices to refer to the corresponding special registers.
 768  761  .RE
 769  762  
 770  763  .sp
 771  764  .ne 2
 772  765  .na
 773  766  \fBx86 (32-bit)\fR
 774  767  .ad
 775  768  .RS 21n
 776  769  For 32-bit x86 processes, the predefined constants listed belowcan be used as
 777  770  indices to refer to the corresponding registers.
 778  771  .sp
 779  772  .in +2
 780  773  .nf
 781  774  SS
 782  775  UESP
 783  776  EFL
 784  777  CS
 785  778  EIP
 786  779  ERR
 787  780  TRAPNO
 788  781  EAX
 789  782  ECX
 790  783  EDX
 791  784  EBX
 792  785  ESP
 793  786  EBP
 794  787  ESI
 795  788  EDI
 796  789  DS
 797  790  ES
 798  791  GS
 799  792  .fi
 800  793  .in -2
 801  794  
 802  795  The preceding constants are listed in \fB<sys/regset.h>\fR\&.
 803  796  .sp
 804  797  Note that a 32-bit process can run on an x86 64-bit system, using the constants
 805  798  listed above.
 806  799  .RE
 807  800  
 808  801  .sp
 809  802  .ne 2
 810  803  .na
 811  804  \fBx86 (64-bit)\fR
 812  805  .ad
 813  806  .RS 21n
 814  807  To read the registers of a 32- \fBor\fR a 64-bit process, a 64-bit x86 process
 815  808  should use the predefined constants listed below.
 816  809  .sp
 817  810  .in +2
 818  811  .nf
 819  812  REG_GSBASE
 820  813  REG_FSBASE
 821  814  REG_DS
 822  815  REG_ES
 823  816  REG_GS
 824  817  REG_FS
 825  818  REG_SS
 826  819  REG_RSP
 827  820  REG_RFL
 828  821  REG_CS
 829  822  REG_RIP
 830  823  REG_ERR
 831  824  REG_TRAPNO
 832  825  REG_RAX
 833  826  REG_RCX
 834  827  REG_RDX
 835  828  REG_RBX
 836  829  REG_RBP
 837  830  REG_RSI
 838  831  REG_RDI
 839  832  REG_R8
 840  833  REG_R9
 841  834  REG_R10
 842  835  REG_R11
 843  836  REG_R12
 844  837  REG_R13
 845  838  REG_R14
 846  839  REG_R15
 847  840  .fi
 848  841  .in -2
 849  842  
 850  843  The preceding constants are listed in \fB<sys/regset.h>\fR\&.
 851  844  .RE
 852  845  
 853  846  .sp
 854  847  .LP
 855  848  \fBpr_fpreg\fR is a structure holding the contents of the floating-point
 856  849  registers.

 857  850  .sp
 858  851  .LP
 859  852  SPARC registers, both general and floating-point, as seen by a 64-bit
 860  853  controlling process are the V9 versions of the registers, even if the target
 861  854  process is a 32-bit (V8) process. V8 registers are a subset of the V9
 862  855  registers.
 863  856  .sp
 864  857  .LP
 865  858  If the lwp is not stopped, all register values are undefined.
 866  859  .SS "psinfo"
 867      -.sp
 868  860  .LP
 869  861  Contains miscellaneous information about the process and the representative lwp
 870  862  needed by the \fBps\fR(1) command. \fBpsinfo\fR remains accessible after a
 871  863  process becomes a \fIzombie\fR. The file contains a \fBpsinfo\fR structure
 872  864  which contains an embedded \fBlwpsinfo\fR structure for the representative lwp,
 873  865  as follows:
 874  866  .sp
 875  867  .in +2
 876  868  .nf
 877  869  typedef struct psinfo {

 878  870      int pr_flag;             /* process flags (DEPRECATED: see below) */
 879  871      int pr_nlwp;             /* number of active lwps in the process */
 880  872      int pr_nzomb;            /* number of zombie lwps in the process */
 881  873      pid_t pr_pid;            /* process id */
 882  874      pid_t pr_ppid;           /* process id of parent */
 883  875      pid_t pr_pgid;           /* process id of process group leader */
 884  876      pid_t pr_sid;            /* session id */
 885  877      uid_t pr_uid;            /* real user id */
 886  878      uid_t pr_euid;           /* effective user id */
 887  879      gid_t pr_gid;            /* real group id */
 888  880      gid_t pr_egid;           /* effective group id */
 889  881      uintptr_t pr_addr;       /* address of process */
 890  882      size_t pr_size;          /* size of process image in Kbytes */
 891  883      size_t pr_rssize;        /* resident set size in Kbytes */
 892  884      dev_t pr_ttydev;         /* controlling tty device (or PRNODEV) */
 893  885      ushort_t pr_pctcpu;      /* % of recent cpu time used by all lwps */
 894  886      ushort_t pr_pctmem;      /* % of system memory used by process */
 895  887      timestruc_t pr_start;    /* process start time, from the epoch */
 896  888      timestruc_t pr_time;     /* cpu time for this process */
 897  889      timestruc_t pr_ctime;    /* cpu time for reaped children */
 898  890      char pr_fname[PRFNSZ];   /* name of exec'ed file */
 899  891      char pr_psargs[PRARGSZ]; /* initial characters of arg list */
 900  892      int pr_wstat;            /* if zombie, the wait() status */
 901  893      int pr_argc;             /* initial argument count */
 902  894      uintptr_t pr_argv;       /* address of initial argument vector */
 903  895      uintptr_t pr_envp;       /* address of initial environment vector */
 904  896      char pr_dmodel;          /* data model of the process */
 905  897      lwpsinfo_t pr_lwp;       /* information for representative lwp */
 906  898      taskid_t pr_taskid;      /* task id */
 907  899      projid_t pr_projid;      /* project id */
 908  900      poolid_t pr_poolid;      /* pool id */
 909  901      zoneid_t pr_zoneid;      /* zone id */
 910  902      ctid_t pr_contract;      /* process contract id */
 911  903  } psinfo_t;
 912  904  .fi
 913  905  .in -2
 914  906  
 915  907  .sp
 916  908  .LP
 917  909  Some of the entries in \fBpsinfo\fR, such as \fBpr_addr\fR, refer to internal
 918  910  kernel data structures and should not be expected to retain their meanings
 919  911  across different versions of the operating system.
 920  912  .sp
 921  913  .LP
 922  914  \fBpsinfo_t.pr_flag\fR is a deprecated interface that should no longer be used.
 923  915  Applications currently relying on the \fBSSYS\fR bit in \fBpr_flag\fR should
 924  916  migrate to checking \fBPR_ISSYS\fR in the \fBpstatus\fR structure's
 925  917  \fBpr_flags\fR field.
 926  918  .sp
 927  919  .LP
 928  920  \fBpr_pctcpu\fR and \fBpr_pctmem\fR are 16-bit binary fractions in the range
 929  921  0.0 to 1.0 with the binary point to the right of the high-order bit (1.0 ==
 930  922  0x8000). \fBpr_pctcpu\fR is the summation over all lwps in the process.
 931  923  .sp
 932  924  .LP
 933  925  \fBpr_lwp\fR contains the \fBps\fR(1) information for the representative lwp.
 934  926  If the process is a \fIzombie\fR, \fBpr_nlwp\fR, \fBpr_nzomb\fR, and
 935  927  \fBpr_lwp.pr_lwpid\fR are zero and the other fields of \fBpr_lwp\fR are
 936  928  undefined:
 937  929  .sp
 938  930  .in +2
 939  931  .nf
 940  932  typedef struct lwpsinfo {
 941  933      int pr_flag;             /* lwp flags (DEPRECATED: see below) */
 942  934      id_t pr_lwpid;           /* lwp id */
 943  935      uintptr_t pr_addr;       /* internal address of lwp */
 944  936      uintptr_t pr_wchan;      /* wait addr for sleeping lwp */
 945  937      char pr_stype;           /* synchronization event type */
 946  938      char pr_state;           /* numeric lwp state */
 947  939      char pr_sname;           /* printable character for pr_state */
 948  940      char pr_nice;            /* nice for cpu usage */
 949  941      short pr_syscall;        /* system call number (if in syscall) */
 950  942      char pr_oldpri;          /* pre-SVR4, low value is high priority */
 951  943      char pr_cpu;             /* pre-SVR4, cpu usage for scheduling */
 952  944      int pr_pri;              /* priority, high value = high priority */
 953  945      ushort_t pr_pctcpu;      /* % of recent cpu time used by this lwp */
 954  946      timestruc_t pr_start;    /* lwp start time, from the epoch */
 955  947      timestruc_t pr_time;     /* cpu time for this lwp */
 956  948      char pr_clname[PRCLSZ];  /* scheduling class name */
 957  949      char pr_name[PRFNSZ];    /* name of system lwp */
 958  950      processorid_t pr_onpro;  /* processor which last ran this lwp */
 959  951      processorid_t pr_bindpro;/* processor to which lwp is bound */
 960  952      psetid_t pr_bindpset;    /* processor set to which lwp is bound */
 961  953      lgrp_id_t pr_lgrp         /* home lgroup */
 962  954  } lwpsinfo_t;
 963  955  .fi
 964  956  .in -2
 965  957  
 966  958  .sp
 967  959  .LP
 968  960  Some of the entries in \fBlwpsinfo\fR, such as \fBpr_addr\fR, \fBpr_wchan\fR,
 969  961  \fBpr_stype\fR, \fBpr_state\fR, and \fBpr_name\fR, refer to internal kernel
 970  962  data structures and should not be expected to retain their meanings across
 971  963  different versions of the operating system.
 972  964  .sp
 973  965  .LP
 974  966  \fBlwpsinfo_t.pr_flag\fR is a deprecated interface that should no longer be
 975  967  used.

 976  968  .sp
 977  969  .LP
 978  970  \fBpr_pctcpu\fR is a 16-bit binary fraction, as described above. It represents
 979  971  the \fBCPU\fR time used by the specific lwp. On a multi-processor machine, the
 980  972  maximum value is 1/N, where N is the number of \fBCPU\fRs.
 981  973  .sp
 982  974  .LP
 983  975  \fBpr_contract\fR is the id of the process contract of which the process is a
 984  976  member. See \fBcontract\fR(4) and \fBprocess\fR(4).
 985  977  .SS "cred"
 986      -.sp
 987  978  .LP
 988  979  Contains a description of the credentials associated with the process:
 989  980  .sp
 990  981  .in +2
 991  982  .nf
 992  983  typedef struct prcred {
 993  984          uid_t pr_euid;      /* effective user id */
 994  985          uid_t pr_ruid;      /* real user id */
 995  986          uid_t pr_suid;      /* saved user id (from exec) */
 996  987          gid_t pr_egid;      /* effective group id */

 997  988          gid_t pr_rgid;      /* real group id */
 998  989          gid_t pr_sgid;      /* saved group id (from exec) */
 999  990          int pr_ngroups;     /* number of supplementary groups */
1000  991          gid_t pr_groups[1]; /* array of supplementary groups */
1001  992  } prcred_t;
1002  993  .fi

1003  994  .in -2
1004  995  .sp
1005  996  
1006  997  .sp
1007  998  .LP
1008  999  The array of associated supplementary groups in \fBpr_groups\fR is of variable
1009 1000  length; the \fBcred\fR file contains all of the supplementary groups.
1010 1001  \fBpr_ngroups\fR indicates the number of supplementary groups. (See also the
1011 1002  \fBPCSCRED\fR and \fBPCSCREDX\fR control operations.)
1012 1003  .SS "priv"
1013      -.sp
1014 1004  .LP
1015 1005  Contains a description of the privileges associated with the process:
1016 1006  .sp
1017 1007  .in +2
1018 1008  .nf
1019 1009  typedef struct prpriv {
1020 1010       uint32_t        pr_nsets;      /* number of privilege set */
1021 1011       uint32_t        pr_setsize;    /* size of privilege set */
1022 1012       uint32_t        pr_infosize;   /* size of supplementary data */
1023 1013       priv_chunk_t    pr_sets[1];    /* array of sets */

1024 1014  } prpriv_t;
1025 1015  .fi
1026 1016  .in -2
1027 1017  
1028 1018  .sp
1029 1019  .LP
1030 1020  The actual dimension of the \fBpr_sets\fR[] field is
1031 1021  .sp
1032 1022  .in +2
1033 1023  .nf
1034 1024  pr_sets[pr_nsets][pr_setsize]
1035 1025  .fi

1036 1026  .in -2
1037 1027  
1038 1028  .sp
1039 1029  .LP
1040 1030  which is followed by additional information about the process state
1041 1031  \fBpr_infosize\fR bytes in size.
1042 1032  .sp
1043 1033  .LP
1044 1034  The full size of the structure can be computed using
1045 1035  \fBPRIV_PRPRIV_SIZE\fR(\fBprpriv_t *\fR).
1046      -.SS "sigact"
     1036 +.SS "secflags"
     1037 +.LP
     1038 +This file contains the security-flags of the process.  It contains a
     1039 +description of the security flags associated with the process.
1047 1040  .sp
     1041 +.in +2
     1042 +.nf
     1043 +typedef struct prsecflags {
     1044 +        uint32_t pr_version;            /* ABI Versioning of this structure */
     1045 +        secflagset_t pr_effective;      /* Effective flags */
     1046 +        secflagset_t pr_inherit;        /* Inheritable flags */
     1047 +        secflagset_t pr_lower;          /* Lower flags */
     1048 +        secflagset_t pr_upper;          /* Upper flags */
     1049 +} prsecflags_t;
     1050 +.in -2
     1051 +
     1052 +.sp
     1053 +.LP
     1054 +The \fBpr_version\fR field is a version number for the structure, currently
     1055 +\fBPRSECFLAGS_VERSION_1\fR.
     1056 +.SS "sigact"
1048 1057  .LP
1049 1058  Contains an array of \fBsigaction structures\fR describing the current
1050 1059  dispositions of all signals associated with the traced process (see
1051 1060  \fBsigaction\fR(2)). Signal numbers are displaced by 1 from array indices, so
1052 1061  that the action for signal number \fIn\fR appears in position \fIn\fR-1 of the
1053 1062  array.
1054 1063  .SS "auxv"
1055      -.sp
1056 1064  .LP
1057 1065  Contains the initial values of the process's aux vector in an array of
1058 1066  \fBauxv_t\fR structures (see \fB<sys/auxv.h>\fR). The values are those that
1059 1067  were passed by the operating system as startup information to the dynamic
1060 1068  linker.
1061 1069  .SS "ldt"
1062      -.sp
1063 1070  .LP
1064 1071  This file exists only on x86-based machines. It is non-empty only if the
1065 1072  process has established a local descriptor table (\fBLDT\fR). If non-empty, the
1066 1073  file contains the array of currently active \fBLDT\fR entries in an array of
1067 1074  elements of type \fBstruct ssd\fR, defined in \fB<sys/sysi86.h>\fR, one element
1068 1075  for each active \fBLDT\fR entry.
1069 1076  .SS "map, xmap"
1070      -.sp
1071 1077  .LP
1072 1078  Contain information about the virtual address map of the process. The map file
1073 1079  contains an array of \fBprmap\fR structures while the xmap file contains an
1074 1080  array of \fBprxmap\fR structures. Each structure describes a contiguous virtual
1075 1081  address region in the address space of the traced process:
1076 1082  .sp
1077 1083  .in +2
1078 1084  .nf
1079 1085  typedef struct prmap {
1080 1086          uintptr_tpr_vaddr;         /* virtual address of mapping */

1081 1087          size_t pr_size;            /* size of mapping in bytes */
1082 1088          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1083 1089          offset_t pr_offset;        /* offset into mapped object, if any */
1084 1090          int pr_mflags;             /* protection and attribute flags */
1085 1091          int pr_pagesize;           /* pagesize for this mapping in bytes */
1086 1092          int pr_shmid;              /* SysV shared memory identifier */
1087 1093  } prmap_t;
1088 1094  .fi
1089 1095  .in -2
1090 1096  .sp
1091 1097  
1092 1098  .sp
1093 1099  .in +2
1094 1100  .nf
1095 1101  typedef struct prxmap {
1096 1102          uintptr_t pr_vaddr;        /* virtual address of mapping */
1097 1103          size_t pr_size;            /* size of mapping in bytes */
1098 1104          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1099 1105          offset_t pr_offset;        /* offset into mapped object, if any */
1100 1106          int pr_mflags;             /* protection and attribute flags */
1101 1107          int pr_pagesize;           /* pagesize for this mapping in bytes */
1102 1108          int pr_shmid;              /* SysV shared memory identifier */
1103 1109          dev_t pr_dev;              /* device of mapped object, if any */
1104 1110          uint64_t pr_ino;           /* inode of mapped object, if any */
1105 1111          size_t pr_rss;             /* pages of resident memory */
1106 1112          size_t pr_anon;            /* pages of resident anonymous memory */
1107 1113          size_t pr_locked;          /* pages of locked memory */
1108 1114          uint64_t pr_hatpagesize;   /* pagesize of mapping */
1109 1115  } prxmap_t;
1110 1116  .fi
1111 1117  .in -2
1112 1118  .sp
1113 1119  
1114 1120  .sp
1115 1121  .LP
1116 1122  \fBpr_vaddr\fR is the virtual address of the mapping within the traced process
1117 1123  and \fBpr_size\fR is its size in bytes. \fBpr_mapname\fR, if it does not
1118 1124  contain a null string, contains the name of a file in the \fBobject\fR
1119 1125  directory (see below) that can be opened read-only to obtain a file descriptor
1120 1126  for the mapped file associated with the mapping. This enables a debugger to
1121 1127  find object file symbol tables without having to know the real path names of
1122 1128  the executable file and shared libraries of the process. \fBpr_offset\fR is the
1123 1129  64-bit offset within the mapped file (if any) to which the virtual address is
1124 1130  mapped.
1125 1131  .sp
1126 1132  .LP
1127 1133  \fBpr_mflags\fR is a bit-mask of protection and attribute flags:
1128 1134  .sp
1129 1135  .ne 2
1130 1136  .na
1131 1137  \fB\fBMA_READ\fR\fR
1132 1138  .ad
1133 1139  .RS 17n
1134 1140  mapping is readable by the traced process.
1135 1141  .RE
1136 1142  
1137 1143  .sp
1138 1144  .ne 2
1139 1145  .na
1140 1146  \fB\fBMA_WRITE\fR\fR
1141 1147  .ad
1142 1148  .RS 17n
1143 1149  mapping is writable by the traced process.
1144 1150  .RE
1145 1151  
1146 1152  .sp
1147 1153  .ne 2
1148 1154  .na
1149 1155  \fB\fBMA_EXEC\fR\fR
1150 1156  .ad
1151 1157  .RS 17n
1152 1158  mapping is executable by the traced process.
1153 1159  .RE
1154 1160  
1155 1161  .sp
1156 1162  .ne 2
1157 1163  .na
1158 1164  \fB\fBMA_SHARED\fR\fR
1159 1165  .ad
1160 1166  .RS 17n
1161 1167  mapping changes are shared by the mapped object.
1162 1168  .RE
1163 1169  
1164 1170  .sp
1165 1171  .ne 2
1166 1172  .na
1167 1173  \fB\fBMA_ISM\fR\fR
1168 1174  .ad
1169 1175  .RS 17n
1170 1176  mapping is intimate shared memory (shared MMU resources)
1171 1177  .RE
1172 1178  
1173 1179  .sp
1174 1180  .ne 2
1175 1181  .na
1176 1182  \fB\fBMAP_NORESERVE\fR\fR
1177 1183  .ad
1178 1184  .RS 17n
1179 1185  mapping does not have swap space reserved (mapped with MAP_NORESERVE)
1180 1186  .RE
1181 1187  
1182 1188  .sp
1183 1189  .ne 2
1184 1190  .na
1185 1191  \fB\fBMA_SHM\fR\fR
1186 1192  .ad
1187 1193  .RS 17n
1188 1194  mapping System V shared memory
1189 1195  .RE
1190 1196  
1191 1197  .sp
1192 1198  .LP
1193 1199  A contiguous area of the address space having the same underlying mapped object
1194 1200  may appear as multiple mappings due to varying read, write, and execute
1195 1201  attributes. The underlying mapped object does not change over the range of a
1196 1202  single mapping. An \fBI/O\fR operation to a mapping marked \fBMA_SHARED\fR
1197 1203  fails if applied at a virtual address not corresponding to a valid page in the
1198 1204  underlying mapped object. A write to a \fBMA_SHARED\fR mapping that is not
1199 1205  marked \fBMA_WRITE\fR fails. Reads and writes to private mappings always
1200 1206  succeed. Reads and writes to unmapped addresses fail.
1201 1207  .sp
1202 1208  .LP
1203 1209  \fBpr_pagesize\fR is the page size for the mapping, currently always the system
1204 1210  pagesize.
1205 1211  .sp
1206 1212  .LP
1207 1213  \fBpr_shmid\fR is the shared memory identifier, if any, for the mapping. Its
1208 1214  value is \fB\(mi1\fR if the mapping is not System V shared memory. See
1209 1215  \fBshmget\fR(2).
1210 1216  .sp
1211 1217  .LP
1212 1218  \fBpr_dev\fR is the device of the mapped object, if any, for the mapping. Its
1213 1219  value is \fBPRNODEV\fR (-1) if the mapping does not have a device.
1214 1220  .sp
1215 1221  .LP
1216 1222  \fBpr_ino\fR is the inode of the mapped object, if any, for the mapping. Its
1217 1223  contents are only valid if \fBpr_dev\fR is not \fBPRNODEV.\fR
1218 1224  .sp
1219 1225  .LP
1220 1226  \fBpr_rss\fR is the number of resident pages of memory for the mapping. The
1221 1227  number of resident bytes for the mapping may be determined by multiplying
1222 1228  \fBpr_rss\fR by the page size given by \fBpr_pagesize.\fR
1223 1229  .sp
1224 1230  .LP
1225 1231  \fBpr_anon\fR is the number of resident anonymous memory pages (pages which are
1226 1232  private to this process) for the mapping.
1227 1233  .sp

1228 1234  .LP
1229 1235  \fBpr_locked\fR is the number of locked pages for the mapping. Pages which are
1230 1236  locked are always resident in memory.
1231 1237  .sp
1232 1238  .LP
1233 1239  \fBpr_hatpagesize\fR is the size, in bytes, of the \fBHAT\fR (\fBMMU\fR)
1234 1240  translation for the mapping. \fBpr_hatpagesize\fR may be different than
1235 1241  \fBpr_pagesize.\fR The possible values are hardware architecture specific, and
1236 1242  may change over a mapping's lifetime.
1237 1243  .SS "rmap"
1238      -.sp
1239 1244  .LP
1240 1245  Contains information about the reserved address ranges of the process. The file
1241 1246  contains an array of \fBprmap\fR structures, as defined above for the \fBmap\fR
1242 1247  file. Each structure describes a contiguous virtual address region in the
1243 1248  address space of the traced process that is reserved by the system in the sense
1244 1249  that an \fBmmap\fR(2) system call that does not specify \fBMAP_FIXED\fR will
1245 1250  not use any part of it for the new mapping. Examples of such reservations
1246 1251  include the address ranges reserved for the process stack and the individual
1247 1252  thread stacks of a multi-threaded process.
1248 1253  .SS "cwd"
1249      -.sp
1250 1254  .LP
1251 1255  A symbolic link to the process's current working directory. See \fBchdir\fR(2).
1252 1256  A \fBreadlink\fR(2) of \fB/proc/\fIpid\fR/cwd\fR yields a null string. However,
1253 1257  it can be opened, listed, and searched as a directory, and can be the target of
1254 1258  \fBchdir\fR(2).
1255 1259  .SS "root"
1256      -.sp
1257 1260  .LP
1258 1261  A symbolic link to the process's root directory.
1259 1262  \fB/proc/\fR\fIpid\fR\fB/root\fR can differ from the system root directory if
1260 1263  the process or one of its ancestors executed \fBchroot\fR(2) as super user. It
1261 1264  has the same semantics as \fB/proc/\fR\fIpid\fR\fB/cwd\fR.
1262 1265  .SS "fd"
1263      -.sp
1264 1266  .LP
1265 1267  A directory containing references to the open files of the process. Each entry
1266 1268  is a decimal number corresponding to an open file descriptor in the process.
1267 1269  .sp
1268 1270  .LP
1269 1271  If an entry refers to a regular file, it can be opened with normal file system
1270 1272  semantics but, to ensure that the controlling process cannot gain greater
1271 1273  access than the controlled process, with no file access modes other than its
1272 1274  read/write open modes in the controlled process. If an entry refers to a
1273 1275  directory, it can be accessed with the same semantics as
1274 1276  \fB/proc/\fIpid\fR/cwd\fR. An attempt to open any other type of entry fails
1275 1277  with \fBEACCES\fR.
1276 1278  .SS "object"
1277      -.sp
1278 1279  .LP
1279 1280  A directory containing read-only files with names corresponding to the
1280 1281  \fBpr_mapname\fR entries in the \fBmap\fR and \fBpagedata\fR files. Opening
1281 1282  such a file yields a file descriptor for the underlying mapped file associated
1282 1283  with an address-space mapping in the process. The file name \fBa.out\fR appears
1283 1284  in the directory as an alias for the process's executable file.
1284 1285  .sp
1285 1286  .LP
1286 1287  The \fBobject\fR directory makes it possible for a controlling process to gain
1287 1288  access to the object file and any shared libraries (and consequently the symbol
1288 1289  tables) without having to know the actual path names of the executable files.
1289 1290  .SS "path"
1290      -.sp
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      -.sp
1303 1302  .LP
1304 1303  Opening the page data file enables tracking of address space references and
1305 1304  modifications on a per-page basis.
1306 1305  .sp
1307 1306  .LP
1308 1307  A \fBread\fR(2) of the page data file descriptor returns structured page data
1309 1308  and atomically clears the page data maintained for the file by the system. That
1310 1309  is to say, each read returns data collected since the last read; the first read
1311 1310  returns data collected since the file was opened. When the call completes, the
1312 1311  read buffer contains the following structure as its header and thereafter

1313 1312  contains a number of section header structures and associated byte arrays that
1314 1313  must be accessed by walking linearly through the buffer.
1315 1314  .sp
1316 1315  .in +2
1317 1316  .nf
1318 1317  typedef struct prpageheader {
1319 1318      timestruc_t pr_tstamp; /* real time stamp, time of read() */
1320 1319      ulong_t pr_nmap;       /* number of address space mappings */
1321 1320      ulong_t pr_npage;      /* total number of pages */
1322 1321  } prpageheader_t;
1323 1322  .fi
1324 1323  .in -2
1325 1324  
1326 1325  .sp
1327 1326  .LP
1328 1327  The header is followed by \fBpr_nmap prasmap\fR structures and associated data
1329 1328  arrays. The \fBprasmap\fR structure contains the following elements:
1330 1329  .sp
1331 1330  .in +2
1332 1331  .nf
1333 1332  typedef struct prasmap {
1334 1333      uintptr_t pr_vaddr;        /* virtual address of mapping */
1335 1334      ulong_t pr_npage;          /* number of pages in mapping */
1336 1335      char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1337 1336      offset_t pr_offset;        /* offset into mapped object, if any */
1338 1337      int pr_mflags;             /* protection and attribute flags */
1339 1338      int pr_pagesize;           /* pagesize for this mapping in bytes */
1340 1339      int pr_shmid;              /* SysV shared memory identifier */
1341 1340  } prasmap_t;
1342 1341  .fi
1343 1342  .in -2
1344 1343  
1345 1344  .sp
1346 1345  .LP
1347 1346  Each section header is followed by \fBpr_npage\fR bytes, one byte for each page
1348 1347  in the mapping, plus 0-7 null bytes at the end so that the next \fBprasmap\fR
1349 1348  structure begins on an eight-byte aligned boundary. Each data byte may contain
1350 1349  these flags:
1351 1350  .sp
1352 1351  .ne 2
1353 1352  .na
1354 1353  \fB\fBPG_REFERENCED\fR\fR
1355 1354  .ad
1356 1355  .RS 17n
1357 1356  page has been referenced.
1358 1357  .RE
1359 1358  
1360 1359  .sp
1361 1360  .ne 2
1362 1361  .na
1363 1362  \fB\fBPG_MODIFIED\fR\fR
1364 1363  .ad
1365 1364  .RS 17n
1366 1365  page has been modified.
1367 1366  .RE
1368 1367  
1369 1368  .sp
1370 1369  .LP
1371 1370  If the read buffer is not large enough to contain all of the page data, the
1372 1371  read fails with \fBE2BIG\fR and the page data is not cleared. The required size
1373 1372  of the read buffer can be determined through \fBfstat\fR(2). Application of

1374 1373  \fBlseek\fR(2) to the page data file descriptor is ineffective; every read
1375 1374  starts from the beginning of the file. Closing the page data file descriptor
1376 1375  terminates the system overhead associated with collecting the data.
1377 1376  .sp
1378 1377  .LP
1379 1378  More than one page data file descriptor for the same process can be opened, up
1380 1379  to a system-imposed limit per traced process. A read of one does not affect the
1381 1380  data being collected by the system for the others. An open of the page data
1382 1381  file will fail with \fBENOMEM\fR if the system-imposed limit would be exceeded.
1383 1382  .SS "watch"
1384      -.sp
1385 1383  .LP
1386 1384  Contains an array of \fBprwatch\fR structures, one for each watched area
1387 1385  established by the \fBPCWATCH\fR control operation. See \fBPCWATCH\fR for
1388 1386  details.
1389 1387  .SS "usage"
1390      -.sp
1391 1388  .LP
1392 1389  Contains process usage information described by a \fBprusage\fR structure which
1393 1390  contains at least the following fields:
1394 1391  .sp
1395 1392  .in +2
1396 1393  .nf
1397 1394  typedef struct prusage {
1398 1395      id_t pr_lwpid;           /* lwp id.  0: process or defunct */
1399 1396      int pr_count;            /* number of contributing lwps */
1400 1397      timestruc_t pr_tstamp;   /* real time stamp, time of read() */

1401 1398      timestruc_t pr_create;   /* process/lwp creation time stamp */
1402 1399      timestruc_t pr_term;     /* process/lwp termination time stamp */
1403 1400      timestruc_t pr_rtime;    /* total lwp real (elapsed) time */
1404 1401      timestruc_t pr_utime;    /* user level CPU time */
1405 1402      timestruc_t pr_stime;    /* system call CPU time */
1406 1403      timestruc_t pr_ttime;    /* other system trap CPU time */
1407 1404      timestruc_t pr_tftime;   /* text page fault sleep time */
1408 1405      timestruc_t pr_dftime;   /* data page fault sleep time */
1409 1406      timestruc_t pr_kftime;   /* kernel page fault sleep time */
1410 1407      timestruc_t pr_ltime;    /* user lock wait sleep time */
1411 1408      timestruc_t pr_slptime;  /* all other sleep time */
1412 1409      timestruc_t pr_wtime;    /* wait-cpu (latency) time */
1413 1410      timestruc_t pr_stoptime; /* stopped time */
1414 1411      ulong_t pr_minf;         /* minor page faults */
1415 1412      ulong_t pr_majf;         /* major page faults */
1416 1413      ulong_t pr_nswap;        /* swaps */
1417 1414      ulong_t pr_inblk;        /* input blocks */
1418 1415      ulong_t pr_oublk;        /* output blocks */
1419 1416      ulong_t pr_msnd;         /* messages sent */
1420 1417      ulong_t pr_mrcv;         /* messages received */
1421 1418      ulong_t pr_sigs;         /* signals received */
1422 1419      ulong_t pr_vctx;         /* voluntary context switches */
1423 1420      ulong_t pr_ictx;         /* involuntary context switches */
1424 1421      ulong_t pr_sysc;         /* system calls */
1425 1422      ulong_t pr_ioch;         /* chars read and written */
1426 1423  } prusage_t;

1427 1424  .fi
1428 1425  .in -2
1429 1426  
1430 1427  .sp
1431 1428  .LP
1432 1429  Microstate accounting is now continuously enabled. While this information was
1433 1430  previously an estimate, if microstate accounting were not enabled, the current
1434 1431  information is now never an estimate represents time the process has spent in
1435 1432  various states.
1436 1433  .SS "lstatus"
1437      -.sp
1438 1434  .LP
1439 1435  Contains a \fBprheader\fR structure followed by an array of \fBlwpstatus\fR
1440 1436  structures, one for each active lwp in the process (see also
1441 1437  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpstatus\fR, below). The
1442 1438  \fBprheader\fR structure describes the number and size of the array entries
1443 1439  that follow.
1444 1440  .sp
1445 1441  .in +2
1446 1442  .nf
1447 1443  typedef struct prheader {

1448 1444      long pr_nent;        /* number of entries */
1449 1445      size_t pr_entsize;   /* size of each entry, in bytes */
1450 1446  } prheader_t;
1451 1447  .fi

1452 1448  .in -2
1453 1449  
1454 1450  .sp
1455 1451  .LP
1456 1452  The \fBlwpstatus\fR structure may grow by the addition of elements at the end
1457 1453  in future releases of the system. Programs must use \fBpr_entsize\fR in the
1458 1454  file header to index through the array. These comments apply to all \fB/proc\fR
1459 1455  files that include a \fBprheader\fR structure (\fBlpsinfo\fR and \fBlusage\fR,
1460 1456  below).
1461 1457  .SS "lpsinfo"
1462      -.sp
1463 1458  .LP
1464 1459  Contains a \fBprheader\fR structure followed by an array of \fBlwpsinfo\fR
1465 1460  structures, one for eachactive and zombie lwp in the process. See also
1466 1461  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpsinfo\fR, below.
1467 1462  .SS "lusage"
1468      -.sp
1469 1463  .LP
1470 1464  Contains a \fBprheader\fR structure followed by an array of \fBprusage\fR
1471 1465  structures, one for each active lwp in the process, plus an additional element
1472 1466  at the beginning that contains the summation over all defunct lwps (lwps that
1473 1467  once existed but no longer exist in the process). Excluding the \fBpr_lwpid\fR,
1474 1468  \fBpr_tstamp\fR, \fBpr_create\fR, and \fBpr_term\fR entries, the entry-by-entry
1475 1469  summation over all these structures is the definition of the process usage
1476 1470  information obtained from the \fBusage\fR file. (See also
1477 1471  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpusage\fR, below.)
1478 1472  .SS "lwp"
1479      -.sp
1480 1473  .LP
1481 1474  A directory containing entries each of which names an active or zombie lwp
1482 1475  within the process. These entries are themselves directories containing
1483 1476  additional files as described below. Only the \fBlwpsinfo\fR file exists in the
1484 1477  directory of a zombie lwp.
1485 1478  .SH STRUCTURE OF \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR
1486      -.sp
1487 1479  .LP
1488 1480  A given directory \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR contains the
1489 1481  following entries:
1490 1482  .SS "lwpctl"
1491      -.sp
1492 1483  .LP
1493 1484  Write-only control file. The messages written to this file affect the specific
1494 1485  lwp rather than the representative lwp, as is the case for the process's
1495 1486  \fBctl\fR file.
1496 1487  .SS "lwpstatus"
1497      -.sp
1498 1488  .LP
1499 1489  lwp-specific state information. This file contains the \fBlwpstatus\fR
1500 1490  structure for the specific lwp as described above for the representative lwp in
1501 1491  the process's \fBstatus\fR file.
1502 1492  .SS "lwpsinfo"
1503      -.sp
1504 1493  .LP
1505 1494  lwp-specific \fBps\fR(1) information. This file contains the \fBlwpsinfo\fR
1506 1495  structure for the specific lwp as described above for the representative lwp in
1507 1496  the process's \fBpsinfo\fR file. The \fBlwpsinfo\fR file remains accessible
1508 1497  after an lwp becomes a zombie.
1509 1498  .SS "lwpusage"
1510      -.sp
1511 1499  .LP
1512 1500  This file contains the \fBprusage\fR structure for the specific lwp as
1513 1501  described above for the process's \fBusage\fR file.
1514 1502  .SS "gwindows"
1515      -.sp
1516 1503  .LP
1517 1504  This file exists only on SPARC based machines. If it is non-empty, it contains
1518 1505  a \fBgwindows_t\fR structure, defined in \fB<sys/regset.h>\fR, with the values
1519 1506  of those SPARC register windows that could not be stored on the stack when the
1520 1507  lwp stopped. Conditions under which register windows are not stored on the
1521 1508  stack are: the stack pointer refers to nonexistent process memory or the stack
1522 1509  pointer is improperly aligned. If the lwp is not stopped or if there are no
1523 1510  register windows that could not be stored on the stack, the file is empty (the
1524 1511  usual case).
1525 1512  .SS "xregs"
1526      -.sp
1527 1513  .LP
1528 1514  Extra state registers. The extra state register set is architecture dependent;
1529 1515  this file is empty if the system does not support extra state registers. If the
1530 1516  file is non-empty, it contains an architecture dependent structure of type
1531 1517  \fBprxregset_t\fR, defined in \fB<procfs.h>\fR, with the values of the lwp's
1532 1518  extra state registers. If the lwp is not stopped, all register values are
1533 1519  undefined. See also the \fBPCSXREG\fR control operation, below.
1534 1520  .SS "asrs"
1535      -.sp
1536 1521  .LP
1537 1522  This file exists only for 64-bit SPARC V9 processes. It contains an
1538 1523  \fBasrset_t\fR structure, defined in <\fBsys/regset.h\fR>, containing the
1539 1524  values of the lwp's platform-dependent ancillary state registers. If the lwp is
1540 1525  not stopped, all register values are undefined. See also the \fBPCSASRS\fR
1541 1526  control operation, below.
1542 1527  .SS "spymaster"
1543      -.sp
1544 1528  .LP
1545 1529  For an agent lwp (see \fBPCAGENT\fR), this file contains a \fBpsinfo_t\fR
1546 1530  structure that corresponds to the process that created the agent lwp at the
1547 1531  time the agent was created. This structure is identical to that retrieved via
1548 1532  the \fBpsinfo\fR file, with one modification: the \fBpr_time\fR field does not
1549 1533  correspond to the CPU time for the process, but rather to the creation time of
1550 1534  the agent lwp.
1551 1535  .SS "templates"
1552      -.sp
1553 1536  .LP
1554 1537  A directory which contains references to the active templates for the lwp,
1555 1538  named by the contract type. Changes made to an active template descriptor do
1556 1539  not affect the original template which was activated, though they do affect the
1557 1540  active template. It is not possible to activate an active template descriptor.
1558 1541  See \fBcontract\fR(4).
1559 1542  .SH CONTROL MESSAGES
1560      -.sp
1561 1543  .LP
1562 1544  Process state changes are effected through messages written to a process's
1563 1545  \fBctl\fR file or to an individual lwp's \fBlwpctl\fR file. All control
1564 1546  messages consist of a \fBlong\fR that names the specific operation followed by
1565 1547  additional data containing the operand, if any.
1566 1548  .sp
1567 1549  .LP
1568 1550  Multiple control messages may be combined in a single \fBwrite\fR(2) (or
1569 1551  \fBwritev\fR(2)) to a control file, but no partial writes are permitted. That
1570 1552  is, each control message, operation code plus operand, if any, must be
1571 1553  presented in its entirety to the \fBwrite\fR(2) and not in pieces over several
1572 1554  system calls. If a control operation fails, no subsequent operations contained
1573 1555  in the same \fBwrite\fR(2) are attempted.
1574 1556  .sp
1575 1557  .LP
1576 1558  Descriptions of the allowable control messages follow. In all cases, writing a
1577 1559  message to a control file for a process or lwp that has terminated elicits the
1578 1560  error \fBENOENT\fR.
1579 1561  .SS "PCSTOP PCDSTOP PCWSTOP PCTWSTOP"
1580      -.sp
1581 1562  .LP
1582 1563  When applied to the process control file, \fBPCSTOP\fR directs all lwps to stop
1583 1564  and waits for them to stop, \fBPCDSTOP\fR directs all lwps to stop without
1584 1565  waiting for them to stop, and \fBPCWSTOP\fR simply waits for all lwps to stop.
1585 1566  When applied to an lwp control file, \fBPCSTOP\fR directs the specific lwp to
1586 1567  stop and waits until it has stopped, \fBPCDSTOP\fR directs the specific lwp to
1587 1568  stop without waiting for it to stop, and \fBPCWSTOP\fR simply waits for the
1588 1569  specific lwp to stop. When applied to an lwp control file, \fBPCSTOP\fR and
1589 1570  \fBPCWSTOP\fR complete when the lwp stops on an event of interest, immediately
1590 1571  if already so stopped; when applied to the process control file, they complete

1591 1572  when every lwp has stopped either on an event of interest or on a
1592 1573  \fBPR_SUSPENDED\fR stop.
1593 1574  .sp
1594 1575  .LP
1595 1576  \fBPCTWSTOP\fR is identical to \fBPCWSTOP\fR except that it enables the
1596 1577  operation to time out, to avoid waiting forever for a process or lwp that may
1597 1578  never stop on an event of interest. \fBPCTWSTOP\fR takes a \fBlong\fR operand
1598 1579  specifying a number of milliseconds; the wait will terminate successfully after
1599 1580  the specified number of milliseconds even if the process or lwp has not
1600 1581  stopped; a timeout value of zero makes the operation identical to
1601 1582  \fBPCWSTOP\fR.
1602 1583  .sp
1603 1584  .LP
1604 1585  An ``event of interest'' is either a \fBPR_REQUESTED\fR stop or a stop that has
1605 1586  been specified in the process's tracing flags (set by \fBPCSTRACE\fR,
1606 1587  \fBPCSFAULT\fR, \fBPCSENTRY\fR, and \fBPCSEXIT\fR). \fBPR_JOBCONTROL\fR and
1607 1588  \fBPR_SUSPENDED\fR stops are specifically not events of interest. (An lwp may
1608 1589  stop twice due to a stop signal, first showing \fBPR_SIGNALLED\fR if the signal
1609 1590  is traced and again showing \fBPR_JOBCONTROL\fR if the lwp is set running
1610 1591  without clearing the signal.) If \fBPCSTOP\fR or \fBPCDSTOP\fR is applied to an
1611 1592  lwp that is stopped, but not on an event of interest, the stop directive takes
1612 1593  effect when the lwp is restarted by the competing mechanism. At that time, the
1613 1594  lwp enters a \fBPR_REQUESTED\fR stop before executing any user-level code.
1614 1595  .sp
1615 1596  .LP
1616 1597  A write of a control message that blocks is interruptible by a signal so that,
1617 1598  for example, an \fBalarm\fR(2) can be set to avoid waiting forever for a
1618 1599  process or lwp that may never stop on an event of interest. If \fBPCSTOP\fR is

1619 1600  interrupted, the lwp stop directives remain in effect even though the
1620 1601  \fBwrite\fR(2) returns an error. (Use of \fBPCTWSTOP\fR with a non-zero timeout
1621 1602  is recommended over \fBPCWSTOP\fR with an \fBalarm\fR(2).)
1622 1603  .sp
1623 1604  .LP
1624 1605  A system process (indicated by the \fBPR_ISSYS\fR flag) never executes at user
1625 1606  level, has no user-level address space visible through \fB/proc\fR, and cannot
1626 1607  be stopped. Applying one of these operations to a system process or any of its
1627 1608  lwps elicits the error \fBEBUSY\fR.
1628 1609  .SS "PCRUN"
1629      -.sp
1630 1610  .LP
1631 1611  Make an lwp runnable again after a stop. This operation takes a \fBlong\fR
1632 1612  operand containing zero or more of the following flags:
1633 1613  .sp
1634 1614  .ne 2
1635 1615  .na
1636 1616  \fB\fBPRCSIG\fR\fR
1637 1617  .ad
1638 1618  .RS 12n
1639 1619  clears the current signal, if any (see \fBPCCSIG\fR).

1640 1620  .RE
1641 1621  
1642 1622  .sp
1643 1623  .ne 2
1644 1624  .na
1645 1625  \fB\fBPRCFAULT\fR\fR
1646 1626  .ad
1647 1627  .RS 12n
1648 1628  clears the current fault, if any (see \fBPCCFAULT\fR).
1649 1629  .RE
1650 1630  
1651 1631  .sp
1652 1632  .ne 2
1653 1633  .na
1654 1634  \fB\fBPRSTEP\fR\fR
1655 1635  .ad
1656 1636  .RS 12n
1657 1637  directs the lwp to execute a single machine instruction. On completion of the
1658 1638  instruction, a trace trap occurs. If \fBFLTTRACE\fR is being traced, the lwp
1659 1639  stops; otherwise, it is sent \fBSIGTRAP\fR. If \fBSIGTRAP\fR is being traced
1660 1640  and is not blocked, the lwp stops. When the lwp stops on an event of interest,
1661 1641  the single-step directive is cancelled, even if the stop occurs before the
1662 1642  instruction is executed. This operation requires hardware and operating system
1663 1643  support and may not be implemented on all processors. It is implemented on
1664 1644  SPARC and x86-based machines.
1665 1645  .RE
1666 1646  
1667 1647  .sp
1668 1648  .ne 2
1669 1649  .na
1670 1650  \fB\fBPRSABORT\fR\fR
1671 1651  .ad
1672 1652  .RS 12n
1673 1653  is meaningful only if the lwp is in a \fBPR_SYSENTRY\fR stop or is marked
1674 1654  \fBPR_ASLEEP\fR; it instructs the lwp to abort execution of the system call
1675 1655  (see \fBPCSENTRY\fR and \fBPCSEXIT\fR).
1676 1656  .RE
1677 1657  
1678 1658  .sp
1679 1659  .ne 2
1680 1660  .na
1681 1661  \fB\fBPRSTOP\fR\fR
1682 1662  .ad
1683 1663  .RS 12n
1684 1664  directs the lwp to stop again as soon as possible after resuming execution (see
1685 1665  \fBPCDSTOP\fR). In particular, if the lwp is stopped on \fBPR_SIGNALLED\fR or
1686 1666  \fBPR_FAULTED\fR, the next stop will show \fBPR_REQUESTED\fR, no other stop
1687 1667  will have intervened, and the lwp will not have executed any user-level code.
1688 1668  .RE
1689 1669  
1690 1670  .sp
1691 1671  .LP
1692 1672  When applied to an lwp control file, \fBPCRUN\fR clears any outstanding
1693 1673  directed-stop request and makes the specific lwp runnable. The operation fails
1694 1674  with \fBEBUSY\fR if the specific lwp is not stopped on an event of interest or
1695 1675  has not been directed to stop or if the agent lwp exists and this is not the
1696 1676  agent lwp (see \fBPCAGENT\fR).
1697 1677  .sp
1698 1678  .LP
1699 1679  When applied to the process control file, a representative lwp is chosen for

1700 1680  the operation as described for \fB/proc/\fR\fIpid\fR\fB/status\fR. The
1701 1681  operation fails with \fBEBUSY\fR if the representative lwp is not stopped on an
1702 1682  event of interest or has not been directed to stop or if the agent lwp exists.
1703 1683  If \fBPRSTEP\fR or \fBPRSTOP\fR was requested, the representative lwp is made
1704 1684  runnable and its outstanding directed-stop request is cleared; otherwise all
1705 1685  outstanding directed-stop requests are cleared and, if it was stopped on an
1706 1686  event of interest, the representative lwp is marked \fBPR_REQUESTED\fR. If, as
1707 1687  a consequence, all lwps are in the \fBPR_REQUESTED\fR or \fBPR_SUSPENDED\fR
1708 1688  stop state, all lwps showing \fBPR_REQUESTED\fR are made runnable.
1709 1689  .SS "PCSTRACE"
1710      -.sp
1711 1690  .LP
1712 1691  Define a set of signals to be traced in the process. The receipt of one of
1713 1692  these signals by an lwp causes the lwp to stop. The set of signals is defined
1714 1693  using an operand \fBsigset_t\fR contained in the control message. Receipt of
1715 1694  \fBSIGKILL\fR cannot be traced; if specified, it is silently ignored.
1716 1695  .sp
1717 1696  .LP
1718 1697  If a signal that is included in an lwp's held signal set (the signal mask) is
1719 1698  sent to the lwp, the signal is not received and does not cause a stop until it
1720 1699  is removed from the held signal set, either by the lwp itself or by setting the
1721 1700  held signal set with \fBPCSHOLD\fR.
1722 1701  .SS "PCCSIG"
1723      -.sp
1724 1702  .LP
1725 1703  The current signal, if any, is cleared from the specific or representative lwp.
1726 1704  .SS "PCSSIG"
1727      -.sp
1728 1705  .LP
1729 1706  The current signal and its associated signal information for the specific or
1730 1707  representative lwp are set according to the contents of the operand
1731 1708  \fBsiginfo\fR structure (see \fB<sys/siginfo.h>\fR). If the specified signal
1732 1709  number is zero, the current signal is cleared. The semantics of this operation
1733 1710  are different from those of \fBkill\fR(2) in that the signal is delivered to
1734 1711  the lwp immediately after execution is resumed (even if it is being blocked)
1735 1712  and an additional \fBPR_SIGNALLED\fR stop does not intervene even if the signal
1736 1713  is traced. Setting the current signal to \fBSIGKILL\fR terminates the process
1737 1714  immediately.
1738 1715  .SS "PCKILL"
1739      -.sp
1740 1716  .LP
1741 1717  If applied to the process control file, a signal is sent to the process with
1742 1718  semantics identical to those of \fBkill\fR(2). If applied to an lwp control
1743 1719  file, a directed signal is sent to the specific lwp. The signal is named in a
1744 1720  \fBlong\fR operand contained in the message. Sending \fBSIGKILL\fR terminates
1745 1721  the process immediately.
1746 1722  .SS "PCUNKILL"
1747      -.sp
1748 1723  .LP
1749 1724  A signal is deleted, that is, it is removed from the set of pending signals. If
1750 1725  applied to the process control file, the signal is deleted from the process's
1751 1726  pending signals. If applied to an lwp control file, the signal is deleted from
1752 1727  the lwp's pending signals. The current signal (if any) is unaffected. The
1753 1728  signal is named in a \fBlong\fR operand in the control message. It is an error
1754 1729  (\fBEINVAL\fR) to attempt to delete \fBSIGKILL\fR.
1755 1730  .SS "PCSHOLD"
1756      -.sp
1757 1731  .LP
1758 1732  Set the set of held signals for the specific or representative lwp (signals
1759 1733  whose delivery will be blocked if sent to the lwp). The set of signals is
1760 1734  specified with a \fBsigset_t\fR operand. \fBSIGKILL\fR and \fBSIGSTOP\fR cannot
1761 1735  be held; if specified, they are silently ignored.
1762 1736  .SS "PCSFAULT"
1763      -.sp
1764 1737  .LP
1765 1738  Define a set of hardware faults to be traced in the process. On incurring one
1766 1739  of these faults, an lwp stops. The set is defined via the operand
1767 1740  \fBfltset_t\fR structure. Fault names are defined in \fB<sys/fault.h>\fR and
1768 1741  include the following. Some of these may not occur on all processors; there may
1769 1742  be processor-specific faults in addition to these.
1770 1743  .sp
1771 1744  .ne 2
1772 1745  .na
1773 1746  \fB\fBFLTILL\fR\fR

1774 1747  .ad
1775 1748  .RS 13n
1776 1749  illegal instruction
1777 1750  .RE
1778 1751  
1779 1752  .sp
1780 1753  .ne 2
1781 1754  .na
1782 1755  \fB\fBFLTPRIV\fR\fR
1783 1756  .ad
1784 1757  .RS 13n
1785 1758  privileged instruction
1786 1759  .RE
1787 1760  
1788 1761  .sp
1789 1762  .ne 2
1790 1763  .na
1791 1764  \fB\fBFLTBPT\fR\fR
1792 1765  .ad
1793 1766  .RS 13n
1794 1767  breakpoint trap
1795 1768  .RE
1796 1769  
1797 1770  .sp
1798 1771  .ne 2
1799 1772  .na
1800 1773  \fB\fBFLTTRACE\fR\fR
1801 1774  .ad
1802 1775  .RS 13n
1803 1776  trace trap (single-step)
1804 1777  .RE
1805 1778  
1806 1779  .sp
1807 1780  .ne 2
1808 1781  .na
1809 1782  \fB\fBFLTWATCH\fR\fR
1810 1783  .ad
1811 1784  .RS 13n
1812 1785  watchpoint trap
1813 1786  .RE
1814 1787  
1815 1788  .sp
1816 1789  .ne 2
1817 1790  .na
1818 1791  \fB\fBFLTACCESS\fR\fR
1819 1792  .ad
1820 1793  .RS 13n
1821 1794  memory access fault (bus error)
1822 1795  .RE
1823 1796  
1824 1797  .sp
1825 1798  .ne 2
1826 1799  .na
1827 1800  \fB\fBFLTBOUNDS\fR\fR
1828 1801  .ad
1829 1802  .RS 13n
1830 1803  memory bounds violation
1831 1804  .RE
1832 1805  
1833 1806  .sp
1834 1807  .ne 2
1835 1808  .na
1836 1809  \fB\fBFLTIOVF\fR\fR
1837 1810  .ad
1838 1811  .RS 13n
1839 1812  integer overflow
1840 1813  .RE
1841 1814  
1842 1815  .sp
1843 1816  .ne 2
1844 1817  .na
1845 1818  \fB\fBFLTIZDIV\fR\fR
1846 1819  .ad
1847 1820  .RS 13n
1848 1821  integer zero divide
1849 1822  .RE
1850 1823  
1851 1824  .sp
1852 1825  .ne 2
1853 1826  .na
1854 1827  \fB\fBFLTFPE\fR\fR
1855 1828  .ad
1856 1829  .RS 13n
1857 1830  floating-point exception
1858 1831  .RE
1859 1832  
1860 1833  .sp
1861 1834  .ne 2
1862 1835  .na
1863 1836  \fB\fBFLTSTACK\fR\fR
1864 1837  .ad
1865 1838  .RS 13n
1866 1839  unrecoverable stack fault
1867 1840  .RE
1868 1841  
1869 1842  .sp
1870 1843  .ne 2
1871 1844  .na
1872 1845  \fB\fBFLTPAGE\fR\fR
1873 1846  .ad
1874 1847  .RS 13n
1875 1848  recoverable page fault
1876 1849  .RE
1877 1850  

1878 1851  .sp
1879 1852  .LP
1880 1853  When not traced, a fault normally results in the posting of a signal to the lwp
1881 1854  that incurred the fault. If an lwp stops on a fault, the signal is posted to
1882 1855  the lwp when execution is resumed unless the fault is cleared by \fBPCCFAULT\fR
1883 1856  or by the \fBPRCFAULT\fR option of \fBPCRUN\fR. \fBFLTPAGE\fR is an exception;
1884 1857  no signal is posted. The \fBpr_info\fR field in the \fBlwpstatus\fR structure
1885 1858  identifies the signal to be sent and contains machine-specific information
1886 1859  about the fault.
1887 1860  .SS "PCCFAULT"
1888      -.sp
1889 1861  .LP
1890 1862  The current fault, if any, is cleared; the associated signal will not be sent
1891 1863  to the specific or representative lwp.
1892 1864  .SS "PCSENTRY PCSEXIT"
1893      -.sp
1894 1865  .LP
1895 1866  These control operations instruct the process's lwps to stop on entry to or
1896 1867  exit from specified system calls. The set of system calls to be traced is
1897 1868  defined via an operand \fBsysset_t\fR structure.
1898 1869  .sp
1899 1870  .LP
1900 1871  When entry to a system call is being traced, an lwp stops after having begun
1901 1872  the call to the system but before the system call arguments have been fetched
1902 1873  from the lwp. When exit from a system call is being traced, an lwp stops on
1903 1874  completion of the system call just prior to checking for signals and returning
1904 1875  to user level. At this point, all return values have been stored into the lwp's
1905 1876  registers.
1906 1877  .sp
1907 1878  .LP
1908 1879  If an lwp is stopped on entry to a system call (\fBPR_SYSENTRY\fR) or when
1909 1880  sleeping in an interruptible system call (\fBPR_ASLEEP\fR is set), it may be
1910 1881  instructed to go directly to system call exit by specifying the \fBPRSABORT\fR
1911 1882  flag in a \fBPCRUN\fR control message. Unless exit from the system call is
1912 1883  being traced, the lwp returns to user level showing \fBEINTR\fR.
1913 1884  .SS "PCWATCH"
1914      -.sp
1915 1885  .LP
1916 1886  Set or clear a watched area in the controlled process from a \fBprwatch\fR
1917 1887  structure operand:
1918 1888  .sp
1919 1889  .in +2
1920 1890  .nf
1921 1891  typedef struct prwatch {
1922 1892      uintptr_t pr_vaddr;  /* virtual address of watched area */
1923 1893      size_t pr_size;      /* size of watched area in bytes */
1924 1894      int pr_wflags;       /* watch type flags */

1925 1895  } prwatch_t;
1926 1896  .fi
1927 1897  .in -2
1928 1898  
1929 1899  .sp
1930 1900  .LP
1931 1901  \fBpr_vaddr\fR specifies the virtual address of an area of memory to be watched
1932 1902  in the controlled process. \fBpr_size\fR specifies the size of the area, in
1933 1903  bytes. \fBpr_wflags\fR specifies the type of memory access to be monitored as a
1934 1904  bit-mask of the following flags:
1935 1905  .sp
1936 1906  .ne 2
1937 1907  .na
1938 1908  \fB\fBWA_READ\fR\fR
1939 1909  .ad
1940 1910  .RS 16n
1941 1911  read access
1942 1912  .RE
1943 1913  
1944 1914  .sp
1945 1915  .ne 2
1946 1916  .na
1947 1917  \fB\fBWA_WRITE\fR\fR
1948 1918  .ad
1949 1919  .RS 16n
1950 1920  write access
1951 1921  .RE
1952 1922  
1953 1923  .sp
1954 1924  .ne 2
1955 1925  .na
1956 1926  \fB\fBWA_EXEC\fR\fR
1957 1927  .ad
1958 1928  .RS 16n
1959 1929  execution access
1960 1930  .RE
1961 1931  
1962 1932  .sp
1963 1933  .ne 2
1964 1934  .na
1965 1935  \fB\fBWA_TRAPAFTER\fR\fR
1966 1936  .ad
1967 1937  .RS 16n
1968 1938  trap after the instruction completes
1969 1939  .RE
1970 1940  
1971 1941  .sp
1972 1942  .LP
1973 1943  If \fBpr_wflags\fR is non-empty, a watched area is established for the virtual
1974 1944  address range specified by \fBpr_vaddr\fR and \fBpr_size\fR. If \fBpr_wflags\fR
1975 1945  is empty, any previously-established watched area starting at the specified
1976 1946  virtual address is cleared; \fBpr_size\fR is ignored.
1977 1947  .sp
1978 1948  .LP
1979 1949  A watchpoint is triggered when an lwp in the traced process makes a memory
1980 1950  reference that covers at least one byte of a watched area and the memory
1981 1951  reference is as specified in \fBpr_wflags\fR. When an lwp triggers a
1982 1952  watchpoint, it incurs a watchpoint trap. If \fBFLTWATCH\fR is being traced, the
1983 1953  lwp stops; otherwise, it is sent a \fBSIGTRAP\fR signal; if \fBSIGTRAP\fR is
1984 1954  being traced and is not blocked, the lwp stops.
1985 1955  .sp
1986 1956  .LP
1987 1957  The watchpoint trap occurs before the instruction completes unless
1988 1958  \fBWA_TRAPAFTER\fR was specified, in which case it occurs after the instruction
1989 1959  completes. If it occurs before completion, the memory is not modified. If it
1990 1960  occurs after completion, the memory is modified (if the access is a write
1991 1961  access).
1992 1962  .sp
1993 1963  .LP
1994 1964  Physical i/o is an exception for watchpoint traps. In this instance, there is
1995 1965  no guarantee that memory before the watched area has already been modified (or
1996 1966  in the case of \fBWA_TRAPAFTER\fR, that the memory following the watched area
1997 1967  has not been modified) when the watchpoint trap occurs and the lwp stops.
1998 1968  .sp
1999 1969  .LP
2000 1970  \fBpr_info\fR in the \fBlwpstatus\fR structure contains information pertinent
2001 1971  to the watchpoint trap. In particular, the \fBsi_addr\fR field contains the
2002 1972  virtual address of the memory reference that triggered the watchpoint, and the
2003 1973  \fBsi_code\fR field contains one of \fBTRAP_RWATCH\fR, \fBTRAP_WWATCH\fR, or
2004 1974  \fBTRAP_XWATCH\fR, indicating read, write, or execute access, respectively. The
2005 1975  \fBsi_trapafter\fR field is zero unless \fBWA_TRAPAFTER\fR is in effect for
2006 1976  this watched area; non-zero indicates that the current instruction is not the
2007 1977  instruction that incurred the watchpoint trap. The \fBsi_pc\fR field contains
2008 1978  the virtual address of the instruction that incurred the trap.
2009 1979  .sp
2010 1980  .LP
2011 1981  A watchpoint trap may be triggered while executing a system call that makes
2012 1982  reference to the traced process's memory. The lwp that is executing the system
2013 1983  call incurs the watchpoint trap while still in the system call. If it stops as
2014 1984  a result, the \fBlwpstatus\fR structure contains the system call number and its
2015 1985  arguments. If the lwp does not stop, or if it is set running again without
2016 1986  clearing the signal or fault, the system call fails with \fBEFAULT\fR. If
2017 1987  \fBWA_TRAPAFTER\fR was specified, the memory reference will have completed and
2018 1988  the memory will have been modified (if the access was a write access) when the
2019 1989  watchpoint trap occurs.
2020 1990  .sp
2021 1991  .LP
2022 1992  If more than one of \fBWA_READ\fR, \fBWA_WRITE\fR, and \fBWA_EXEC\fR is
2023 1993  specified for a watched area, and a single instruction incurs more than one of
2024 1994  the specified types, only one is reported when the watchpoint trap occurs. The
2025 1995  precedence is \fBWA_EXEC\fR, \fBWA_READ\fR, \fBWA_WRITE\fR (\fBWA_EXEC\fR and
2026 1996  \fBWA_READ\fR take precedence over \fBWA_WRITE\fR), unless \fBWA_TRAPAFTER\fR
2027 1997  was specified, in which case it is \fBWA_WRITE\fR, \fBWA_READ\fR, \fBWA_EXEC\fR
2028 1998  (\fBWA_WRITE\fR takes precedence).
2029 1999  .sp
2030 2000  .LP
2031 2001  \fBPCWATCH\fR fails with \fBEINVAL\fR if an attempt is made to specify
2032 2002  overlapping watched areas or if \fBpr_wflags\fR contains flags other than those
2033 2003  specified above. It fails with \fBENOMEM\fR if an attempt is made to establish
2034 2004  more watched areas than the system can support (the system can support
2035 2005  thousands).
2036 2006  .sp
2037 2007  .LP
2038 2008  The child of a \fBvfork\fR(2) borrows the parent's address space. When a
2039 2009  \fBvfork\fR(2) is executed by a traced process, all watched areas established
2040 2010  for the parent are suspended until the child terminates or performs an
2041 2011  \fBexec\fR(2). Any watched areas established independently in the child are
2042 2012  cancelled when the parent resumes after the child's termination or
2043 2013  \fBexec\fR(2). \fBPCWATCH\fR fails with \fBEBUSY\fR if applied to the parent of
2044 2014  a \fBvfork\fR(2) before the child has terminated or performed an \fBexec\fR(2).
2045 2015  The \fBPR_VFORKP\fR flag is set in the \fBpstatus\fR structure for such a
2046 2016  parent process.
2047 2017  .sp
2048 2018  .LP
2049 2019  Certain accesses of the traced process's address space by the operating system
2050 2020  are immune to watchpoints. The initial construction of a signal stack frame
2051 2021  when a signal is delivered to an lwp will not trigger a watchpoint trap even if
2052 2022  the new frame covers watched areas of the stack. Once the signal handler is

2053 2023  entered, watchpoint traps occur normally. On SPARC based machines, register
2054 2024  window overflow and underflow will not trigger watchpoint traps, even if the
2055 2025  register window save areas cover watched areas of the stack.
2056 2026  .sp
2057 2027  .LP
2058 2028  Watched areas are not inherited by child processes, even if the traced
2059 2029  process's inherit-on-fork mode, \fBPR_FORK\fR, is set (see \fBPCSET\fR, below).
2060 2030  All watched areas are cancelled when the traced process performs a successful
2061 2031  \fBexec\fR(2).
2062 2032  .SS "PCSET PCUNSET"
2063      -.sp
2064 2033  .LP
2065 2034  \fBPCSET\fR sets one or more modes of operation for the traced process.
2066 2035  \fBPCUNSET\fR unsets these modes. The modes to be set or unset are specified by
2067 2036  flags in an operand \fBlong\fR in the control message:
2068 2037  .sp
2069 2038  .ne 2
2070 2039  .na
2071 2040  \fB\fBPR_FORK\fR\fR
2072 2041  .ad
2073 2042  .RS 13n

2074 2043  (inherit-on-fork): When set, the process's tracing flags and its
2075 2044  inherit-on-fork mode are inherited by the child of a \fBfork\fR(2),
2076 2045  \fBfork1\fR(2), or \fBvfork\fR(2). When unset, child processes start with all
2077 2046  tracing flags cleared.
2078 2047  .RE
2079 2048  
2080 2049  .sp
2081 2050  .ne 2
2082 2051  .na
2083 2052  \fB\fBPR_RLC\fR\fR
2084 2053  .ad
2085 2054  .RS 13n
2086 2055  (run-on-last-close): When set and the last writable \fB/proc\fR file descriptor
2087 2056  referring to the traced process or any of its lwps is closed, all of the
2088 2057  process's tracing flags and watched areas are cleared, any outstanding stop
2089 2058  directives are canceled, and if any lwps are stopped on events of interest,
2090 2059  they are set running as though \fBPCRUN\fR had been applied to them. When
2091 2060  unset, the process's tracing flags and watched areas are retained and lwps are
2092 2061  not set running on last close.
2093 2062  .RE
2094 2063  
2095 2064  .sp
2096 2065  .ne 2
2097 2066  .na
2098 2067  \fB\fBPR_KLC\fR\fR
2099 2068  .ad
2100 2069  .RS 13n
2101 2070  (kill-on-last-close): When set and the last writable \fB/proc\fR file
2102 2071  descriptor referring to the traced process or any of its lwps is closed, the
2103 2072  process is terminated with \fBSIGKILL\fR.
2104 2073  .RE
2105 2074  
2106 2075  .sp
2107 2076  .ne 2
2108 2077  .na
2109 2078  \fB\fBPR_ASYNC\fR\fR
2110 2079  .ad
2111 2080  .RS 13n
2112 2081  (asynchronous-stop): When set, a stop on an event of interest by one lwp does
2113 2082  not directly affect any other lwp in the process. When unset and an lwp stops
2114 2083  on an event of interest other than \fBPR_REQUESTED\fR, all other lwps in the
2115 2084  process are directed to stop.
2116 2085  .RE
2117 2086  
2118 2087  .sp
2119 2088  .ne 2
2120 2089  .na
2121 2090  \fB\fBPR_MSACCT\fR\fR
2122 2091  .ad
2123 2092  .RS 13n
2124 2093  (microstate accounting): Microstate accounting is now continuously enabled.
2125 2094  This flag is deprecated and no longer has any effect upon microstate
2126 2095  accounting. Applications may toggle this flag; however, microstate accounting
2127 2096  will remain enabled regardless.
2128 2097  .RE
2129 2098  
2130 2099  .sp
2131 2100  .ne 2
2132 2101  .na
2133 2102  \fB\fBPR_MSFORK\fR\fR
2134 2103  .ad
2135 2104  .RS 13n
2136 2105  (inherit microstate accounting): All processes now inherit microstate
2137 2106  accounting, as it is continuously enabled. This flag has been deprecated and
2138 2107  its use no longer has any effect upon the behavior of microstate accounting.
2139 2108  .RE
2140 2109  
2141 2110  .sp
2142 2111  .ne 2
2143 2112  .na
2144 2113  \fB\fBPR_BPTADJ\fR\fR
2145 2114  .ad
2146 2115  .RS 13n
2147 2116  (breakpoint trap pc adjustment): On x86-based machines, a breakpoint trap
2148 2117  leaves the program counter (the \fBEIP\fR) referring to the breakpointed
2149 2118  instruction plus one byte. When \fBPR_BPTADJ\fR is set, the system will adjust
2150 2119  the program counter back to the location of the breakpointed instruction when
2151 2120  the lwp stops on a breakpoint. This flag has no effect on SPARC based machines,
2152 2121  where breakpoint traps leave the program counter referring to the breakpointed
2153 2122  instruction.
2154 2123  .RE
2155 2124  
2156 2125  .sp
2157 2126  .ne 2
2158 2127  .na
2159 2128  \fB\fBPR_PTRACE\fR\fR
2160 2129  .ad
2161 2130  .RS 13n
2162 2131  (ptrace-compatibility): When set, a stop on an event of interest by the traced
2163 2132  process is reported to the parent of the traced process by \fBwait\fR(3C),
2164 2133  \fBSIGTRAP\fR is sent to the traced process when it executes a successful
2165 2134  \fBexec\fR(2), setuid/setgid flags are not honored for execs performed by the
2166 2135  traced process, any exec of an object file that the traced process cannot read
2167 2136  fails, and the process dies when its parent dies. This mode is deprecated; it
2168 2137  is provided only to allow \fBptrace\fR(3C) to be implemented as a library

2169 2138  function using \fB/proc\fR.
2170 2139  .RE
2171 2140  
2172 2141  .sp
2173 2142  .LP
2174 2143  It is an error (\fBEINVAL\fR) to specify flags other than those described above
2175 2144  or to apply these operations to a system process. The current modes are
2176 2145  reported in the \fBpr_flags\fR field of \fB/proc/\fR\fIpid\fR\fB/status\fR and
2177 2146  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwp\fR\fB/lwpstatus\fR.
2178 2147  .SS "PCSREG"
2179      -.sp
2180 2148  .LP
2181 2149  Set the general registers for the specific or representative lwp according to
2182 2150  the operand \fBprgregset_t\fR structure.
2183 2151  .sp
2184 2152  .LP
2185 2153  On SPARC based systems, only the condition-code bits of the processor-status
2186 2154  register (R_PSR) of SPARC V8 (32-bit) processes can be modified by
2187 2155  \fBPCSREG\fR. Other privileged registers cannot be modified at all.
2188 2156  .sp
2189 2157  .LP
2190 2158  On x86-based systems, only certain bits of the flags register (EFL) can be
2191 2159  modified by \fBPCSREG\fR: these include the condition codes, direction-bit, and
2192 2160  overflow-bit.
2193 2161  .sp
2194 2162  .LP
2195 2163  \fBPCSREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an event of
2196 2164  interest.
2197 2165  .SS "PCSVADDR"
2198      -.sp
2199 2166  .LP
2200 2167  Set the address at which execution will resume for the specific or
2201 2168  representative lwp from the operand \fBlong\fR. On SPARC based systems, both
2202 2169  %pc and %npc are set, with %npc set to the instruction following the virtual
2203 2170  address. On x86-based systems, only %eip is set. \fBPCSVADDR\fR fails with
2204 2171  \fBEBUSY\fR if the lwp is not stopped on an event of interest.
2205 2172  .SS "PCSFPREG"
2206      -.sp
2207 2173  .LP
2208 2174  Set the floating-point registers for the specific or representative lwp
2209 2175  according to the operand \fBprfpregset_t\fR structure. An error (\fBEINVAL\fR)
2210 2176  is returned if the system does not support floating-point operations (no
2211 2177  floating-point hardware and the system does not emulate floating-point machine
2212 2178  instructions). \fBPCSFPREG\fR fails with \fBEBUSY\fR if the lwp is not stopped
2213 2179  on an event of interest.
2214 2180  .SS "PCSXREG"
2215      -.sp
2216 2181  .LP
2217 2182  Set the extra state registers for the specific or representative lwp according
2218 2183  to the architecture-dependent operand \fBprxregset_t\fR structure. An error
2219 2184  (\fBEINVAL\fR) is returned if the system does not support extra state
2220 2185  registers. \fBPCSXREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an
2221 2186  event of interest.
2222 2187  .SS "PCSASRS"
2223      -.sp
2224 2188  .LP
2225 2189  Set the ancillary state registers for the specific or representative lwp
2226 2190  according to the SPARC V9 platform-dependent operand \fBasrset_t\fR structure.
2227 2191  An error (\fBEINVAL\fR) is returned if either the target process or the
2228 2192  controlling process is not a 64-bit SPARC V9 process. Most of the ancillary
2229 2193  state registers are privileged registers that cannot be modified. Only those
2230 2194  that can be modified are set; all others are silently ignored. \fBPCSASRS\fR
2231 2195  fails with \fBEBUSY\fR if the lwp is not stopped on an event of interest.
2232 2196  .SS "PCAGENT"
2233      -.sp
2234 2197  .LP
2235 2198  Create an agent lwp in the controlled process with register values from the
2236 2199  operand \fBprgregset_t\fR structure (see \fBPCSREG\fR, above). The agent lwp is
2237 2200  created in the stopped state showing \fBPR_REQUESTED\fR and with its held
2238 2201  signal set (the signal mask) having all signals except \fBSIGKILL\fR and
2239 2202  \fBSIGSTOP\fR blocked.
2240 2203  .sp
2241 2204  .LP
2242 2205  The \fBPCAGENT\fR operation fails with \fBEBUSY\fR unless the process is fully
2243 2206  stopped via \fB/proc\fR, that is, unless all of the lwps in the process are

2244 2207  stopped either on events of interest or on \fBPR_SUSPENDED\fR, or are stopped
2245 2208  on \fBPR_JOBCONTROL\fR and have been directed to stop via \fBPCDSTOP\fR.  It
2246 2209  fails with \fBEBUSY\fR if an agent lwp already exists. It fails with
2247 2210  \fBENOMEM\fR if system resources for creating new lwps have been exhausted.
2248 2211  .sp
2249 2212  .LP
2250 2213  Any \fBPCRUN\fR operation applied to the process control file or to the control
2251 2214  file of an lwp other than the agent lwp fails with \fBEBUSY\fR as long as the
2252 2215  agent lwp exists. The agent lwp must be caused to terminate by executing the
2253 2216  \fBSYS_lwp_exit\fR system call trap before the process can be restarted.
2254 2217  .sp
2255 2218  .LP
2256 2219  Once the agent lwp is created, its lwp-ID can be found by reading the process
2257 2220  status file. To facilitate opening the agent lwp's control and status files,
2258 2221  the directory name \fB/propc/\fR\fIpid\fR\fB/lwp/agent\fR is accepted for
2259 2222  lookup operations as an invisible alias for
2260 2223  \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid,\fR \fIlwpid\fR being the lwp-ID of
2261 2224  the agent lwp (invisible in the sense that the name ``agent'' does not appear
2262 2225  in a directory listing of \fB/proc/\fR\fIpid\fR\fB/lwp\fR obtained from
2263 2226  \fBls\fR(1), \fBgetdents\fR(2), or \fBreaddir\fR(3C)).
2264 2227  .sp
2265 2228  .LP
2266 2229  The purpose of the agent lwp is to perform operations in the controlled process
2267 2230  on behalf of the controlling process: to gather information not directly
2268 2231  available via \fB/proc\fR files, or in general to make the process change state
2269 2232  in ways not directly available via \fB/proc\fR control operations. To make use
2270 2233  of an agent lwp, the controlling process must be capable of making it execute
2271 2234  system calls (specifically, the \fBSYS_lwp_exit\fR system call trap). The
2272 2235  register values given to the agent lwp on creation are typically the registers
2273 2236  of the representative lwp, so that the agent lwp can use its stack.
2274 2237  .sp
2275 2238  .LP
2276 2239  If the controlling process neglects to force the agent lwp to execute the
2277 2240  \fBSYS_lwp_exit\fR system call (due to either logic error or fatal failure on
2278 2241  the part of the controlling process), the agent lwp will remain in the target
2279 2242  process.  For purposes of being able to debug these otherwise rogue agents,
2280 2243  information as to the creator of the agent lwp is reflected in that lwp's
2281 2244  \fBspymaster\fR file in \fB/proc\fR. Should the target process generate a core
2282 2245  dump with the agent lwp in place, this information will be available via the
2283 2246  \fBNT_SPYMASTER\fR note in the core file (see \fBcore\fR(4)).

2284 2247  .sp
2285 2248  .LP
2286 2249  The agent lwp is not allowed to execute any variation of the \fBSYS_fork\fR or
2287 2250  \fBSYS_exec\fR system call traps. Attempts to do so yield \fBENOTSUP\fR to the
2288 2251  agent lwp.
2289 2252  .sp
2290 2253  .LP
2291 2254  Symbolic constants for system call trap numbers like \fBSYS_lwp_exit\fR and
2292 2255  \fBSYS_lwp_create\fR can be found in the header file <\fBsys/syscall.h\fR>.
2293 2256  .SS "PCREAD PCWRITE"
2294      -.sp
2295 2257  .LP
2296 2258  Read or write the target process's address space via a \fBpriovec\fR structure
2297 2259  operand:
2298 2260  .sp
2299 2261  .in +2
2300 2262  .nf
2301 2263  typedef struct priovec {
2302 2264      void *pio_base;      /* buffer in controlling process */
2303 2265      size_t pio_len;      /* size of read/write request in bytes */
2304 2266      off_t pio_offset;    /* virtual address in target process */

2305 2267  } priovec_t;
2306 2268  .fi
2307 2269  .in -2
2308 2270  
2309 2271  .sp
2310 2272  .LP

2311 2273  These operations have the same effect as \fBpread\fR(2) and \fBpwrite\fR(2),
2312 2274  respectively, of the target process's address space file. The difference is
2313 2275  that more than one \fBPCREAD\fR or \fBPCWRITE\fR control operation can be
2314 2276  written to the control file at once, and they can be interspersed with other
2315 2277  control operations in a single write to the control file. This is useful, for
2316 2278  example, when planting many breakpoint instructions in the process's address
2317 2279  space, or when stepping over a breakpointed instruction. Unlike \fBpread\fR(2)
2318 2280  and \fBpwrite\fR(2), no provision is made for partial reads or writes; if the
2319 2281  operation cannot be performed completely, it fails with \fBEIO\fR.
2320 2282  .SS "PCNICE"
2321      -.sp
2322 2283  .LP
2323 2284  The traced process's \fBnice\fR(2) value is incremented by the amount in the
2324 2285  operand \fBlong\fR. Only a process with the {\fBPRIV_PROC_PRIOCNTL\fR}
2325 2286  privilege asserted in its effective set can better a process's priority in this
2326 2287  way, but any user may lower the priority. This operation is not meaningful for
2327 2288  all scheduling classes.
2328 2289  .SS "PCSCRED"
2329      -.sp
2330 2290  .LP
2331 2291  Set the target process credentials to the values contained in the
2332 2292  \fBprcred_t\fR structure operand (see \fB/proc/\fR\fIpid\fR\fB/cred\fR). The
2333 2293  effective, real, and saved user-IDs and group-IDs of the target process are
2334 2294  set. The target process's supplementary groups are not changed; the
2335 2295  \fBpr_ngroups\fR and \fBpr_groups\fR members of the structure operand are
2336 2296  ignored. Only the privileged processes can perform this operation; for all
2337 2297  others it fails with \fBEPERM\fR.
2338 2298  .SS "PCSCREDX"
2339      -.sp
2340 2299  .LP
2341 2300  Operates like \fBPCSCRED\fR but also sets the supplementary groups; the length
2342 2301  of the data written with this control operation should be "sizeof
2343 2302  (\fBprcred_t\fR) + sizeof (\fBgid_t)\fR * (#groups - 1)".
2344 2303  .SS "PCSPRIV"
2345      -.sp
2346 2304  .LP
2347 2305  Set the target process privilege to the values contained in the \fBprpriv_t\fR
2348 2306  operand (see \fB/proc/pid/priv\fR). The effective, permitted, inheritable, and
2349 2307  limit sets are all changed. Privilege flags can also be set. The process is
2350 2308  made privilege aware unless it can relinquish privilege awareness. See
2351 2309  \fBprivileges\fR(5).
2352 2310  .sp
2353 2311  .LP
2354 2312  The limit set of the target process cannot be grown. The other privilege sets
2355 2313  must be subsets of the intersection of the effective set of the calling process
2356 2314  with the new limit set of the target process or subsets of the original values
2357 2315  of the sets in the target process.
2358 2316  .sp
2359 2317  .LP
2360 2318  If any of the above restrictions are not met, \fBEPERM\fR is returned. If the
2361 2319  structure written is improperly formatted, \fBEINVAL\fR is returned.
2362 2320  .SH PROGRAMMING NOTES
2363      -.sp
2364 2321  .LP
2365 2322  For security reasons, except for the \fBpsinfo\fR, \fBusage\fR, \fBlpsinfo\fR,
2366 2323  \fBlusage\fR, \fBlwpsinfo\fR, and \fBlwpusage\fR files, which are
2367 2324  world-readable, and except for privileged processes, an open of a \fB/proc\fR
2368 2325  file fails unless both the user-ID and group-ID of the caller match those of
2369 2326  the traced process and the process's object file is readable by the caller. The
2370 2327  effective set of the caller is a superset of both the inheritable and the
2371 2328  permitted set of the target process. The limit set of the caller is a superset
2372 2329  of the limit set of the target process. Except for the world-readable files
2373 2330  just mentioned, files corresponding to setuid and setgid processes can be

2374 2331  opened only by the appropriately privileged process.
2375 2332  .sp
2376 2333  .LP
2377 2334  A process that is missing the basic privilege {\fBPRIV_PROC_INFO\fR} cannot see
2378 2335  any processes under \fB/proc\fR that it cannot send a signal to.
2379 2336  .sp
2380 2337  .LP
2381 2338  A process that has {\fBPRIV_PROC_OWNER\fR} asserted in its effective set can
2382 2339  open any file for reading. To manipulate or control a process, the controlling
2383 2340  process must have at least as many privileges in its effective set as the
2384 2341  target process has in its effective, inheritable, and permitted sets. The limit
2385 2342  set of the controlling process must be a superset of the limit set of the
2386 2343  target process. Additional restrictions apply if any of the uids of the target
2387 2344  process are 0. See \fBprivileges\fR(5).
2388 2345  .sp
2389 2346  .LP
2390 2347  Even if held by a privileged process, an open process or lwp file descriptor
2391 2348  (other than file descriptors for the world-readable files) becomes invalid if
2392 2349  the traced process performs an \fBexec\fR(2) of a setuid/setgid object file or
2393 2350  an object file that the traced process cannot read. Any operation performed on
2394 2351  an invalid file descriptor, except \fBclose\fR(2), fails with \fBEAGAIN\fR. In
2395 2352  this situation, if any tracing flags are set and the process or any lwp file
2396 2353  descriptor is open for writing, the process will have been directed to stop and
2397 2354  its run-on-last-close flag will have been set (see \fBPCSET\fR). This enables a
2398 2355  controlling process (if it has permission) to reopen the \fB/proc\fR files to
2399 2356  get new valid file descriptors, close the invalid file descriptors, unset the
2400 2357  run-on-last-close flag (if desired), and proceed. Just closing the invalid file
2401 2358  descriptors causes the traced process to resume execution with all tracing
2402 2359  flags cleared. Any process not currently open for writing via \fB/proc\fR, but
2403 2360  that has left-over tracing flags from a previous open, and that executes a
2404 2361  setuid/setgid or unreadable object file, will not be stopped but will have all
2405 2362  its tracing flags cleared.
2406 2363  .sp
2407 2364  .LP
2408 2365  To wait for one or more of a set of processes or lwps to stop or terminate,
2409 2366  \fB/proc\fR file descriptors (other than those obtained by opening the
2410 2367  \fBcwd\fR or \fBroot\fR directories or by opening files in the \fBfd\fR or
2411 2368  \fBobject\fR directories) can be used in a \fBpoll\fR(2) system call. When

2412 2369  requested and returned, either of the polling events \fBPOLLPRI\fR or
2413 2370  \fBPOLLWRNORM\fR indicates that the process or lwp stopped on an event of
2414 2371  interest. Although they cannot be requested, the polling events \fBPOLLHUP\fR,
2415 2372  \fBPOLLERR\fR, and \fBPOLLNVAL\fR may be returned. \fBPOLLHUP\fR indicates that
2416 2373  the process or lwp has terminated. \fBPOLLERR\fR indicates that the file
2417 2374  descriptor has become invalid. \fBPOLLNVAL\fR is returned immediately if
2418 2375  \fBPOLLPRI\fR or \fBPOLLWRNORM\fR is requested on a file descriptor referring
2419 2376  to a system process (see \fBPCSTOP\fR). The requested events may be empty to
2420 2377  wait simply for termination.
2421 2378  .SH FILES
2422      -.sp
2423 2379  .ne 2
2424 2380  .na
2425 2381  \fB\fB/proc\fR\fR
2426 2382  .ad
2427 2383  .sp .6
2428 2384  .RS 4n
2429 2385  directory (list of processes)
2430 2386  .RE
2431 2387  
2432 2388  .sp

2433 2389  .ne 2
2434 2390  .na
2435 2391  \fB\fB/proc/\fIpid\fR\fR\fR
2436 2392  .ad
2437 2393  .sp .6
2438 2394  .RS 4n
2439 2395  specific process directory
2440 2396  .RE
2441 2397  
2442 2398  .sp
2443 2399  .ne 2
2444 2400  .na
2445 2401  \fB\fB/proc/self\fR\fR
2446 2402  .ad
2447 2403  .sp .6
2448 2404  .RS 4n
2449 2405  alias for a process's own directory
2450 2406  .RE
2451 2407  
2452 2408  .sp
2453 2409  .ne 2
2454 2410  .na
2455 2411  \fB\fB/proc/\fIpid\fR/as\fR\fR
2456 2412  .ad
2457 2413  .sp .6
2458 2414  .RS 4n
2459 2415  address space file
2460 2416  .RE
2461 2417  
2462 2418  .sp
2463 2419  .ne 2
2464 2420  .na
2465 2421  \fB\fB/proc/\fIpid\fR/ctl\fR\fR
2466 2422  .ad
2467 2423  .sp .6
2468 2424  .RS 4n
2469 2425  process control file
2470 2426  .RE
2471 2427  
2472 2428  .sp
2473 2429  .ne 2
2474 2430  .na
2475 2431  \fB\fB/proc/\fIpid\fR/status\fR\fR
2476 2432  .ad
2477 2433  .sp .6
2478 2434  .RS 4n
2479 2435  process status
2480 2436  .RE
2481 2437  
2482 2438  .sp
2483 2439  .ne 2
2484 2440  .na
2485 2441  \fB\fB/proc/\fIpid\fR/lstatus\fR\fR
2486 2442  .ad
2487 2443  .sp .6
2488 2444  .RS 4n
2489 2445  array of lwp status structs
2490 2446  .RE
2491 2447  
2492 2448  .sp
2493 2449  .ne 2
2494 2450  .na
2495 2451  \fB\fB/proc/\fIpid\fR/psinfo\fR\fR
2496 2452  .ad
2497 2453  .sp .6
2498 2454  .RS 4n
2499 2455  process \fBps\fR(1) info
2500 2456  .RE
2501 2457  
2502 2458  .sp
2503 2459  .ne 2
2504 2460  .na
2505 2461  \fB\fB/proc/\fIpid\fR/lpsinfo\fR\fR
2506 2462  .ad
2507 2463  .sp .6
2508 2464  .RS 4n
2509 2465  array of lwp \fBps\fR(1) info structs
2510 2466  .RE
2511 2467  
2512 2468  .sp
2513 2469  .ne 2
2514 2470  .na
2515 2471  \fB\fB/proc/\fIpid\fR/map\fR\fR
2516 2472  .ad
2517 2473  .sp .6
2518 2474  .RS 4n
2519 2475  address space map
2520 2476  .RE
2521 2477  
2522 2478  .sp
2523 2479  .ne 2
2524 2480  .na
2525 2481  \fB\fB/proc/\fIpid\fR/xmap\fR\fR
2526 2482  .ad
2527 2483  .sp .6
2528 2484  .RS 4n
2529 2485  extended address space map
2530 2486  .RE
2531 2487  
2532 2488  .sp
2533 2489  .ne 2
2534 2490  .na
2535 2491  \fB\fB/proc/\fIpid\fR/rmap\fR\fR
2536 2492  .ad
2537 2493  .sp .6
2538 2494  .RS 4n
2539 2495  reserved address map
2540 2496  .RE
2541 2497  
2542 2498  .sp
2543 2499  .ne 2
2544 2500  .na
2545 2501  \fB\fB/proc/\fIpid\fR/cred\fR\fR
2546 2502  .ad
2547 2503  .sp .6
2548 2504  .RS 4n
2549 2505  process credentials
2550 2506  .RE
2551 2507  
2552 2508  .sp
2553 2509  .ne 2
2554 2510  .na
2555 2511  \fB\fB/proc/\fIpid\fR/priv\fR\fR
2556 2512  .ad
2557 2513  .sp .6
2558 2514  .RS 4n
2559 2515  process privileges
2560 2516  .RE
2561 2517  
2562 2518  .sp
2563 2519  .ne 2
2564 2520  .na
2565 2521  \fB\fB/proc/\fIpid\fR/sigact\fR\fR
2566 2522  .ad
2567 2523  .sp .6
2568 2524  .RS 4n
2569 2525  process signal actions
2570 2526  .RE
2571 2527  
2572 2528  .sp
2573 2529  .ne 2
2574 2530  .na
2575 2531  \fB\fB/proc/\fIpid\fR/auxv\fR\fR
2576 2532  .ad
2577 2533  .sp .6
2578 2534  .RS 4n
2579 2535  process aux vector
2580 2536  .RE
2581 2537  
2582 2538  .sp
2583 2539  .ne 2
2584 2540  .na
2585 2541  \fB\fB/proc/\fIpid\fR/ldt\fR\fR
2586 2542  .ad
2587 2543  .sp .6
2588 2544  .RS 4n
2589 2545  process \fBLDT\fR (x86 only)
2590 2546  .RE
2591 2547  
2592 2548  .sp
2593 2549  .ne 2
2594 2550  .na
2595 2551  \fB\fB/proc/\fIpid\fR/usage\fR\fR
2596 2552  .ad
2597 2553  .sp .6
2598 2554  .RS 4n
2599 2555  process usage
2600 2556  .RE
2601 2557  
2602 2558  .sp
2603 2559  .ne 2
2604 2560  .na
2605 2561  \fB\fB/proc/\fIpid\fR/lusage\fR\fR
2606 2562  .ad
2607 2563  .sp .6
2608 2564  .RS 4n
2609 2565  array of lwp usage structs
2610 2566  .RE
2611 2567  
2612 2568  .sp
2613 2569  .ne 2
2614 2570  .na
2615 2571  \fB\fB/proc/\fIpid\fR/path\fR\fR
2616 2572  .ad
2617 2573  .sp .6
2618 2574  .RS 4n
2619 2575  symbolic links to process open files
2620 2576  .RE
2621 2577  
2622 2578  .sp
2623 2579  .ne 2
2624 2580  .na
2625 2581  \fB\fB/proc/\fIpid\fR/pagedata\fR\fR
2626 2582  .ad
2627 2583  .sp .6
2628 2584  .RS 4n
2629 2585  process page data
2630 2586  .RE
2631 2587  
2632 2588  .sp
2633 2589  .ne 2
2634 2590  .na
2635 2591  \fB\fB/proc/\fIpid\fR/watch\fR\fR
2636 2592  .ad
2637 2593  .sp .6
2638 2594  .RS 4n
2639 2595  active watchpoints
2640 2596  .RE
2641 2597  
2642 2598  .sp
2643 2599  .ne 2
2644 2600  .na
2645 2601  \fB\fB/proc/\fIpid\fR/cwd\fR\fR
2646 2602  .ad
2647 2603  .sp .6
2648 2604  .RS 4n
2649 2605  alias for the current working directory
2650 2606  .RE
2651 2607  
2652 2608  .sp
2653 2609  .ne 2
2654 2610  .na
2655 2611  \fB\fB/proc/\fIpid\fR/root\fR\fR
2656 2612  .ad
2657 2613  .sp .6
2658 2614  .RS 4n
2659 2615  alias for the root directory
2660 2616  .RE
2661 2617  
2662 2618  .sp
2663 2619  .ne 2
2664 2620  .na
2665 2621  \fB\fB/proc/\fIpid\fR/fd\fR\fR
2666 2622  .ad
2667 2623  .sp .6
2668 2624  .RS 4n
2669 2625  directory (list of open files)
2670 2626  .RE
2671 2627  
2672 2628  .sp
2673 2629  .ne 2
2674 2630  .na
2675 2631  \fB\fB/proc/\fIpid\fR/fd/*\fR\fR
2676 2632  .ad
2677 2633  .sp .6
2678 2634  .RS 4n
2679 2635  aliases for process's open files
2680 2636  .RE
2681 2637  
2682 2638  .sp
2683 2639  .ne 2
2684 2640  .na
2685 2641  \fB\fB/proc/\fIpid\fR/object\fR\fR
2686 2642  .ad
2687 2643  .sp .6
2688 2644  .RS 4n
2689 2645  directory (list of mapped files)
2690 2646  .RE
2691 2647  
2692 2648  .sp
2693 2649  .ne 2
2694 2650  .na
2695 2651  \fB\fB/proc/\fIpid\fR/object/a.out\fR\fR
2696 2652  .ad
2697 2653  .sp .6
2698 2654  .RS 4n
2699 2655  alias for process's executable file
2700 2656  .RE
2701 2657  
2702 2658  .sp
2703 2659  .ne 2
2704 2660  .na
2705 2661  \fB\fB/proc/\fIpid\fR/object/*\fR\fR
2706 2662  .ad
2707 2663  .sp .6
2708 2664  .RS 4n
2709 2665  aliases for other mapped files
2710 2666  .RE
2711 2667  
2712 2668  .sp
2713 2669  .ne 2
2714 2670  .na
2715 2671  \fB\fB/proc/\fIpid\fR/lwp\fR\fR
2716 2672  .ad
2717 2673  .sp .6
2718 2674  .RS 4n
2719 2675  directory (list of lwps)
2720 2676  .RE
2721 2677  
2722 2678  .sp
2723 2679  .ne 2
2724 2680  .na
2725 2681  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR\fR\fR
2726 2682  .ad
2727 2683  .sp .6
2728 2684  .RS 4n
2729 2685  specific lwp directory
2730 2686  .RE
2731 2687  
2732 2688  .sp
2733 2689  .ne 2
2734 2690  .na
2735 2691  \fB\fB/proc/\fIpid\fR/lwp/agent\fR\fR
2736 2692  .ad
2737 2693  .sp .6
2738 2694  .RS 4n
2739 2695  alias for the agent lwp directory
2740 2696  .RE
2741 2697  
2742 2698  .sp
2743 2699  .ne 2
2744 2700  .na
2745 2701  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpctl\fR\fR
2746 2702  .ad
2747 2703  .sp .6
2748 2704  .RS 4n
2749 2705  lwp control file
2750 2706  .RE
2751 2707  
2752 2708  .sp
2753 2709  .ne 2
2754 2710  .na
2755 2711  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpstatus\fR\fR
2756 2712  .ad
2757 2713  .sp .6
2758 2714  .RS 4n
2759 2715  lwp status
2760 2716  .RE
2761 2717  
2762 2718  .sp
2763 2719  .ne 2
2764 2720  .na
2765 2721  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpsinfo\fR\fR
2766 2722  .ad
2767 2723  .sp .6
2768 2724  .RS 4n
2769 2725  lwp \fBps\fR(1) info
2770 2726  .RE
2771 2727  
2772 2728  .sp
2773 2729  .ne 2
2774 2730  .na
2775 2731  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpusage\fR\fR
2776 2732  .ad
2777 2733  .sp .6
2778 2734  .RS 4n
2779 2735  lwp usage
2780 2736  .RE
2781 2737  
2782 2738  .sp
2783 2739  .ne 2
2784 2740  .na
2785 2741  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/gwindows\fR\fR
2786 2742  .ad
2787 2743  .sp .6
2788 2744  .RS 4n
2789 2745  register windows (SPARC only)
2790 2746  .RE
2791 2747  
2792 2748  .sp
2793 2749  .ne 2
2794 2750  .na
2795 2751  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/xregs\fR\fR
2796 2752  .ad
2797 2753  .sp .6
2798 2754  .RS 4n
2799 2755  extra state registers
2800 2756  .RE
2801 2757  
2802 2758  .sp
2803 2759  .ne 2
2804 2760  .na
2805 2761  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/asrs\fR\fR
2806 2762  .ad
2807 2763  .sp .6
2808 2764  .RS 4n
2809 2765  ancillary state registers (SPARC V9 only)
2810 2766  .RE
2811 2767  
2812 2768  .sp

2813 2769  .ne 2
2814 2770  .na
2815 2771  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/spymaster\fR\fR
2816 2772  .ad
2817 2773  .sp .6
2818 2774  .RS 4n
2819 2775  For an agent LWP, the controlling process
2820 2776  .RE
2821 2777  
2822 2778  .SH SEE ALSO
2823      -.sp
2824 2779  .LP
2825 2780  \fBls\fR(1), \fBps\fR(1), \fBchroot\fR(1M), \fBalarm\fR(2), \fBbrk\fR(2),
2826 2781  \fBchdir\fR(2), \fBchroot\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2),
2827 2782  \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2), \fBfork1\fR(2), \fBfstat\fR(2),
2828 2783  \fBgetdents\fR(2), \fBgetustack\fR(2), \fBkill\fR(2), \fBlseek\fR(2),
2829 2784  \fBmmap\fR(2), \fBnice\fR(2), \fBopen\fR(2), \fBpoll\fR(2), \fBpread\fR(2),
2830 2785  \fBptrace\fR(3C), \fBpwrite\fR(2), \fBread\fR(2), \fBreadlink\fR(2),
2831 2786  \fBreadv\fR(2), \fBshmget\fR(2), \fBsigaction\fR(2), \fBsigaltstack\fR(2),
2832 2787  \fBvfork\fR(2), \fBwrite\fR(2), \fBwritev\fR(2), \fB_stack_grow\fR(3C),
2833 2788  \fBreaddir\fR(3C), \fBpthread_create\fR(3C), \fBpthread_join\fR(3C),
2834 2789  \fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), \fBthr_create\fR(3C),
2835 2790  \fBthr_join\fR(3C), \fBtypes32.h\fR(3HEAD), \fBucontext.h\fR(3HEAD),
2836 2791  \fBwait\fR(3C), \fBcontract\fR(4), \fBcore\fR(4), \fBprocess\fR(4),
2837      -\fBlfcompile\fR(5), \fBprivileges\fR(5)
     2792 +\fBlfcompile\fR(5), \fBprivileges\fR(5), \fBsecurity-flags\fR(5)
2838 2793  .SH DIAGNOSTICS
2839      -.sp
2840 2794  .LP
2841 2795  Errors that can occur in addition to the errors normally associated with file
2842 2796  system access:
2843 2797  .sp
2844 2798  .ne 2
2845 2799  .na
2846 2800  \fB\fBE2BIG\fR\fR
2847 2801  .ad
2848 2802  .RS 13n
2849 2803  Data to be returned in a \fBread\fR(2) of the page data file exceeds the size

2850 2804  of the read buffer provided by the caller.
2851 2805  .RE
2852 2806  
2853 2807  .sp
2854 2808  .ne 2
2855 2809  .na
2856 2810  \fB\fBEACCES\fR\fR
2857 2811  .ad
2858 2812  .RS 13n
2859 2813  An attempt was made to examine a process that ran under a different uid than
2860 2814  the controlling process and {\fBPRIV_PROC_OWNER\fR} was not asserted in the
2861 2815  effective set.
2862 2816  .RE
2863 2817  
2864 2818  .sp
2865 2819  .ne 2
2866 2820  .na
2867 2821  \fB\fBEAGAIN\fR\fR
2868 2822  .ad
2869 2823  .RS 13n
2870 2824  The traced process has performed an \fBexec\fR(2) of a setuid/setgid object
2871 2825  file or of an object file that it cannot read; all further operations on the
2872 2826  process or lwp file descriptor (except \fBclose\fR(2)) elicit this error.
2873 2827  .RE
2874 2828  
2875 2829  .sp
2876 2830  .ne 2
2877 2831  .na
2878 2832  \fB\fBEBUSY\fR\fR
2879 2833  .ad
2880 2834  .RS 13n
2881 2835  \fBPCSTOP\fR, \fBPCDSTOP\fR, \fBPCWSTOP\fR, or \fBPCTWSTOP\fR was applied to a
2882 2836  system process; an exclusive \fBopen\fR(2) was attempted on a \fB/proc\fR file
2883 2837  for a process already open for writing; \fBPCRUN\fR, \fBPCSREG\fR,
2884 2838  \fBPCSVADDR\fR, \fBPCSFPREG\fR, or \fBPCSXREG\fR was applied to a process or
2885 2839  lwp not stopped on an event of interest; an attempt was made to mount
2886 2840  \fB/proc\fR when it was already mounted; \fBPCAGENT\fR was applied to a process
2887 2841  that was not fully stopped or that already had an agent lwp.
2888 2842  .RE
2889 2843  
2890 2844  .sp
2891 2845  .ne 2
2892 2846  .na
2893 2847  \fB\fBEINVAL\fR\fR
2894 2848  .ad
2895 2849  .RS 13n
2896 2850  In general, this means that some invalid argument was supplied to a system
2897 2851  call. A non-exhaustive list of conditions eliciting this error includes: a
2898 2852  control message operation code is undefined; an out-of-range signal number was
2899 2853  specified with \fBPCSSIG\fR, \fBPCKILL\fR, or \fBPCUNKILL\fR; \fBSIGKILL\fR was
2900 2854  specified with \fBPCUNKILL\fR; \fBPCSFPREG\fR was applied on a system that does
2901 2855  not support floating-point operations; \fBPCSXREG\fR was applied on a system
2902 2856  that does not support extra state registers.
2903 2857  .RE
2904 2858  
2905 2859  .sp
2906 2860  .ne 2
2907 2861  .na
2908 2862  \fB\fBEINTR\fR\fR
2909 2863  .ad
2910 2864  .RS 13n
2911 2865  A signal was received by the controlling process while waiting for the traced
2912 2866  process or lwp to stop via \fBPCSTOP\fR, \fBPCWSTOP\fR, or \fBPCTWSTOP\fR.
2913 2867  .RE
2914 2868  
2915 2869  .sp
2916 2870  .ne 2
2917 2871  .na
2918 2872  \fB\fBEIO\fR\fR
2919 2873  .ad
2920 2874  .RS 13n
2921 2875  A \fBwrite\fR(2) was attempted at an illegal address in the traced process.
2922 2876  .RE
2923 2877  
2924 2878  .sp
2925 2879  .ne 2
2926 2880  .na
2927 2881  \fB\fBENOENT\fR\fR
2928 2882  .ad
2929 2883  .RS 13n
2930 2884  The traced process or lwp has terminated after being opened. The basic
2931 2885  privilege {\fBPRIV_PROC_INFO\fR} is not asserted in the effective set of the
2932 2886  calling process and the calling process cannot send a signal to the target
2933 2887  process.
2934 2888  .RE
2935 2889  
2936 2890  .sp
2937 2891  .ne 2
2938 2892  .na
2939 2893  \fB\fBENOMEM\fR\fR
2940 2894  .ad
2941 2895  .RS 13n
2942 2896  The system-imposed limit on the number of page data file descriptors was
2943 2897  reached on an open of \fB/proc/\fR\fIpid\fR\fB/pagedata\fR; an attempt was made
2944 2898  with \fBPCWATCH\fR to establish more watched areas than the system can support;
2945 2899  the \fBPCAGENT\fR operation was issued when the system was out of resources for
2946 2900  creating lwps.
2947 2901  .RE
2948 2902  
2949 2903  .sp
2950 2904  .ne 2
2951 2905  .na
2952 2906  \fB\fBENOSYS\fR\fR
2953 2907  .ad
2954 2908  .RS 13n
2955 2909  An attempt was made to perform an unsupported operation (such as
2956 2910  \fBcreat\fR(2), \fBlink\fR(2), or \fBunlink\fR(2)) on an entry in \fB/proc\fR.
2957 2911  .RE
2958 2912  
2959 2913  .sp
2960 2914  .ne 2
2961 2915  .na
2962 2916  \fB\fBEOVERFLOW\fR\fR
2963 2917  .ad
2964 2918  .RS 13n
2965 2919  A 32-bit controlling process attempted to read or write the \fBas\fR file or
2966 2920  attempted to read the \fBmap\fR, \fBrmap\fR, or \fBpagedata\fR file of a 64-bit
2967 2921  target process. A 32-bit controlling process attempted to apply one of the
2968 2922  control operations \fBPCSREG\fR, \fBPCSXREG\fR, \fBPCSVADDR\fR, \fBPCWATCH\fR,
2969 2923  \fBPCAGENT\fR, \fBPCREAD\fR, \fBPCWRITE\fR to a 64-bit target process.
2970 2924  .RE
2971 2925  
2972 2926  .sp
2973 2927  .ne 2
2974 2928  .na
2975 2929  \fB\fBEPERM\fR\fR
2976 2930  .ad
2977 2931  .RS 13n
2978 2932  The process that issued the \fBPCSCRED\fR or \fBPCSCREDX\fR operation did not
2979 2933  have the {\fBPRIV_PROC_SETID\fR} privilege asserted in its effective set, or
2980 2934  the process that issued the \fBPCNICE\fR operation did not have the
2981 2935  {\fBPRIV_PROC_PRIOCNTL\fR} in its effective set.
2982 2936  .sp
2983 2937  An attempt was made to control a process of which the E, P, and I privilege

2984 2938  sets were not a subset of the effective set of the controlling process or the
2985 2939  limit set of the controlling process is not a superset of limit set of the
2986 2940  controlled process.
2987 2941  .sp
2988 2942  Any of the uids of the target process are 0 or an attempt was made to change
2989 2943  any of the uids to 0 using PCSCRED and the security policy imposed additional
2990 2944  restrictions. See \fBprivileges\fR(5).
2991 2945  .RE
2992 2946  
2993 2947  .SH NOTES
2994      -.sp
2995 2948  .LP
2996 2949  Descriptions of structures in this document include only interesting structure
2997 2950  elements, not filler and padding fields, and may show elements out of order for
2998 2951  descriptive clarity. The actual structure definitions are contained in
2999 2952  \fB<procfs.h>\fR\&.
3000 2953  .SH BUGS
3001      -.sp
3002 2954  .LP
3003 2955  Because the old \fBioctl\fR(2)-based version of \fB/proc\fR is currently
3004 2956  supported for binary compatibility with old applications, the top-level
3005 2957  directory for a process, \fB/proc/\fR\fIpid\fR, is not world-readable, but it
3006 2958  is world-searchable. Thus, anyone can open \fB/proc/\fR\fIpid\fR\fB/psinfo\fR
3007 2959  even though \fBls\fR(1) applied to \fB/proc/\fR\fIpid\fR will fail for anyone
3008 2960  but the owner or an appropriately privileged process. Support for the old
3009 2961  \fBioctl\fR(2)-based version of \fB/proc\fR will be dropped in a future
3010 2962  release, at which time the top-level directory for a process will be made
3011 2963  world-readable.
3012 2964  .sp
3013 2965  .LP
3014 2966  On SPARC based machines, the types \fBgregset_t\fR and \fBfpregset_t\fR defined
3015 2967  in <\fBsys/regset.h\fR> are similar to but not the same as the types
3016 2968  \fBprgregset_t\fR and \fBprfpregset_t\fR defined in <\fBprocfs.h\fR>.
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX