15254 %ymm registers not restored after signal handler
15367 x86 getfpregs() summons corrupting %xmm ghosts
15333 want x86 /proc xregs support (libc_db, libproc, mdb, etc.)
15336 want libc functions for extended ucontext_t
15334 want ps_lwphandle-specific reg routines
15328 FPU_CW_INIT mistreats reserved bit
15335 i86pc fpu_subr.c isn't really platform-specific
15332 setcontext(2) isn't actually noreturn
15331 need <sys/stdalign.h>
Change-Id: I7060aa86042dfb989f77fc3323c065ea2eafa9ad
Conflicts:
    usr/src/uts/common/fs/proc/prcontrol.c
    usr/src/uts/intel/os/archdep.c
    usr/src/uts/intel/sys/ucontext.h
    usr/src/uts/intel/syscall/getcontext.c

          --- old/usr/src/man/man5/proc.5
          +++ new/usr/src/man/man5/proc.5
   1    1  .\" Copyright 1989 AT&T
   2    2  .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
   3    3  .\" Copyright 2019, Joyent, Inc.
   4    4  .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
        5 +.\" Copyright 2023 Oxide computer Company
   5    6  .\"
   6    7  .\" The contents of this file are subject to the terms of the
   7    8  .\" Common Development and Distribution License (the "License").
   8    9  .\" You may not use this file except in compliance with the License.
   9   10  .\"
  10   11  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  11   12  .\" or http://www.opensolaris.org/os/licensing.
  12   13  .\" See the License for the specific language governing permissions
  13   14  .\" and limitations under the License.
  14   15  .\"

  15   16  .\" When distributing Covered Code, include this CDDL HEADER in each
  16   17  .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  17   18  .\" If applicable, add the following below this CDDL HEADER, with the
  18   19  .\" fields enclosed by brackets "[]" replaced with your own identifying
  19   20  .\" information: Portions Copyright [yyyy] [name of copyright owner]
  20   21  .\"
  21   22  .Dd May 17, 2020
  22   23  .Dt PROC 5
  23   24  .Os
  24   25  .Sh NAME
  25   26  .Nm proc
  26   27  .Nd /proc, the process file system
  27   28  .Sh DESCRIPTION
  28   29  .Pa /proc
  29   30  is a file system that provides access to the state of each process
  30   31  and light-weight process (lwp) in the system.
  31   32  The name of each entry in the
  32   33  .Pa /proc
  33   34  directory is a decimal number corresponding to a process-ID.
  34   35  These entries are themselves subdirectories.
  35   36  Access to process state is provided by additional files contained within each
  36   37  subdirectory; the hierarchy is described more completely below.
  37   38  In this document,
  38   39  .Dq Pa /proc file
  39   40  refers to a non-directory file within the hierarchy rooted at
  40   41  .Pa /proc .
  41   42  The owner of each
  42   43  .Pa /proc
  43   44  file and subdirectory is determined by the user-ID of the process.
  44   45  .Pp
  45   46  .Pa /proc
  46   47  can be mounted on any mount point, in addition to the standard
  47   48  .Pa /proc
  48   49  mount point, and can be mounted several places at once.
  49   50  Such additional mounts are allowed in order to facilitate the confinement of
  50   51  processes to subtrees of the file system via
  51   52  .Xr chroot 2
  52   53  and yet allow such processes access to commands like
  53   54  .Xr ps 1 .
  54   55  .Pp
  55   56  Standard system calls are used to access
  56   57  .Pa /proc
  57   58  files:
  58   59  .Xr open 2 ,
  59   60  .Xr close 2 ,
  60   61  .Xr read 2 ,
  61   62  and
  62   63  .Xr write 2
  63   64  (including
  64   65  .Xr readv 2 ,
  65   66  .Xr writev 2 ,
  66   67  .Xr pread 2 ,
  67   68  and
  68   69  .Xr pwrite 2 ) .
  69   70  Most files describe process state and can only be opened for reading.
  70   71  .Pa ctl
  71   72  and
  72   73  .Pa lwpctl
  73   74  (control) files permit manipulation of process state and can only be opened for
  74   75  writing.
  75   76  .Pa as
  76   77  (address space) files contain the image of the running process and can be
  77   78  opened for both reading and writing.
  78   79  An open for writing allows process control; a read-only open allows inspection
  79   80  but not control.
  80   81  In this document, we refer to the process as open for reading or writing if
  81   82  any of its associated
  82   83  .Pa /proc
  83   84  files is open for reading or writing.
  84   85  .Pp
  85   86  In general, more than one process can open the same
  86   87  .Pa /proc
  87   88  file at the same time. \fIExclusive\fR \fIopen\fR is an advisory mechanism provided to
  88   89  allow controlling processes to avoid collisions with each other.
  89   90  A process can obtain exclusive control of a target process, with respect to
  90   91  other cooperating processes, if it successfully opens any
  91   92  .Pa /proc
  92   93  file in the target process for writing (the
  93   94  .Pa as
  94   95  or
  95   96  .Pa ctl
  96   97  files, or the
  97   98  .Pa lwpctl
  98   99  file of any lwp) while specifying
  99  100  .Sy O_EXCL
 100  101  in the
 101  102  .Xr open 2 .
 102  103  Such an open will fail if the target process is already open for writing (that
 103  104  is, if an
 104  105  .Pa as ,
 105  106  .Pa ctl ,
 106  107  or
 107  108  .Pa lwpctl
 108  109  file is already open for writing).
 109  110  There can be any number of concurrent read-only opens;
 110  111  .Sy O_EXCL
 111  112  is ignored on opens for reading.
 112  113  It is recommended that the first open for writing by a controlling
 113  114  process use the
 114  115  .Sy O_EXCL
 115  116  flag; multiple controlling processes usually result in chaos.
 116  117  .Pp
 117  118  If a process opens one of its own
 118  119  .Pa /proc
 119  120  files for writing, the open
 120  121  succeeds regardless of
 121  122  .Sy O_EXCL
 122  123  and regardless of whether some other process has the process open for writing.
 123  124  Self-opens do not count when another process attempts an exclusive open.
 124  125  (A process cannot exclude a debugger by opening itself for writing and the
 125  126  application of a debugger cannot prevent a process from opening itself.)
 126  127  All self-opens for writing are forced to be close-on-exec (see the
 127  128  .Sy F_SETFD
 128  129  operation of
 129  130  .Xr fcntl 2 ) .
 130  131  .Pp
 131  132  Data may be transferred from or to any locations in the address space of the
 132  133  traced process by applying
 133  134  .Xr lseek 2
 134  135  to position the
 135  136  .Pa as
 136  137  file at the virtual address of interest followed by
 137  138  .Xr read 2
 138  139  or
 139  140  .Xr write 2
 140  141  (or by using
 141  142  .Xr pread 2
 142  143  or
 143  144  .Xr pwrite 2
 144  145  for the combined operation).
 145  146  The address-map files
 146  147  .Pa /proc/ Ns Em pid Ns Pa /map
 147  148  and
 148  149  .Pa /proc/ Ns Em pid Ns Pa /xmap
 149  150  can be read to determine the accessible areas (mappings) of the address space.
 150  151  .Sy I/O
 151  152  transfers may span contiguous mappings.
 152  153  An
 153  154  .Sy I/O
 154  155  request extending into an unmapped area is truncated at the boundary.
 155  156  A write request beginning at an unmapped virtual address fails with
 156  157  .Er EIO ;
 157  158  a read request beginning at an unmapped virtual address returns zero (an
 158  159  end-of-file indication).
 159  160  .Pp
 160  161  Information and control operations are provided through additional files.
 161  162  .In procfs.h
 162  163  contains definitions of data structures and message formats
 163  164  used with these files.
 164  165  Some of these definitions involve the use of sets of flags.
 165  166  The set types
 166  167  .Sy sigset_t ,
 167  168  .Sy fltset_t ,
 168  169  and
 169  170  .Sy sysset_t
 170  171  correspond, respectively, to signal, fault, and system call enumerations
 171  172  defined in
 172  173  .In sys/signal.h ,
 173  174  .In sys/fault.h ,
 174  175  and
 175  176  .In sys/syscall.h .
 176  177  Each set type is large enough to hold flags for its own enumeration.
 177  178  Although they are of different sizes, they have a common
 178  179  structure and can be manipulated by these macros:
 179  180  .Bd -literal -offset indent
 180  181  prfillset(&set);             /* turn on all flags in set */
 181  182  premptyset(&set);            /* turn off all flags in set */
 182  183  praddset(&set, flag);        /* turn on the specified flag */
 183  184  prdelset(&set, flag);        /* turn off the specified flag */
 184  185  r = prismember(&set, flag);  /* != 0 iff flag is turned on */
 185  186  .Ed
 186  187  .Pp
 187  188  One of
 188  189  .Fn prfillset
 189  190  or
 190  191  .Fn premptyset
 191  192  must be used to initialize
 192  193  .Fa set
 193  194  before it is used in any other operation.
 194  195  .Fa flag
 195  196  must be a member of the enumeration corresponding to
 196  197  .Fa set .
 197  198  .Pp
 198  199  Every process contains at least one
 199  200  .Em light-weight process ,
 200  201  or
 201  202  .Sy lwp .
 202  203  Each lwp represents a flow of execution that is independently scheduled by the
 203  204  operating system.
 204  205  All lwps in a process share its address space as well as many other attributes.
 205  206  Through the use of
 206  207  .Pa lwpctl
 207  208  and
 208  209  .Pa ctl
 209  210  files as described below, it is possible to affect individual lwps in a
 210  211  process or to affect all of them at once, depending on the operation.
 211  212  .Pp
 212  213  When the process has more than one lwp, a representative lwp is chosen by the
 213  214  system for certain process status files and control operations.
 214  215  The representative lwp is a stopped lwp only if all of the process's lwps are
 215  216  stopped; is stopped on an event of interest only if all of the lwps are so
 216  217  stopped (excluding
 217  218  .Sy PR_SUSPENDED
 218  219  lwps); is in a
 219  220  .Sy PR_REQUESTED
 220  221  stop only if there are no other events of interest to be found; or, failing
 221  222  everything else, is in a
 222  223  .Sy PR_SUSPENDED
 223  224  stop (implying that the process is deadlocked).
 224  225  See the description of the
 225  226  .Pa status
 226  227  file for definitions of stopped states.
 227  228  See the
 228  229  .Sy PCSTOP
 229  230  control operation for the definition of
 230  231  .Dq event of interest .
 231  232  .Pp
 232  233  The representative lwp remains fixed (it will be chosen again on the next
 233  234  operation) as long as all of the lwps are stopped on events of interest or are
 234  235  in a
 235  236  .Sy PR_SUSPENDED
 236  237  stop and the
 237  238  .Sy PCRUN
 238  239  control operation is not applied to any of them.
 239  240  .Pp
 240  241  When applied to the process control file, every
 241  242  .Pa /proc
 242  243  control operation
 243  244  that must act on an lwp uses the same algorithm to choose which lwp to act
 244  245  upon.
 245  246  Together with synchronous stopping (see
 246  247  .Sy PCSET ) ,
 247  248  this enables a debugger to control a multiple-lwp process using only the
 248  249  process-level status and control files if it so chooses.
 249  250  More fine-grained control can be achieved using the lwp-specific files.
 250  251  .Pp
 251  252  The system supports two process data models, the traditional 32-bit data model
 252  253  in which ints, longs and pointers are all 32 bits wide (the ILP32 data model),
 253  254  and on some platforms the 64-bit data model in which longs and pointers, but
 254  255  not ints, are 64 bits in width (the LP64 data model).
 255  256  In the LP64 data model some system data types, notably
 256  257  .Sy size_t ,
 257  258  .Sy off_t ,
 258  259  .Sy time_t
 259  260  and
 260  261  .Sy dev_t ,
 261  262  grow from 32 bits to 64 bits as well.
 262  263  .Pp
 263  264  The
 264  265  .Pa /proc
 265  266  interfaces described here are available to both 32-bit and
 266  267  64-bit controlling processes.
 267  268  However, many operations attempted by a 32-bit
 268  269  controlling process on a 64-bit target process will fail with
 269  270  .Er EOVERFLOW
 270  271  because the address space range of a 32-bit process cannot encompass a 64-bit
 271  272  process or because the data in some 64-bit system data type cannot be
 272  273  compressed to fit into the corresponding 32-bit type without loss of
 273  274  information.
 274  275  Operations that fail in this circumstance include reading and
 275  276  writing the address space, reading the address-map files, and setting the
 276  277  target process's registers.
 277  278  There is no restriction on operations applied by a
 278  279  64-bit process to either a 32-bit or a 64-bit target processes.
 279  280  .Pp
 280  281  The format of the contents of any
 281  282  .Pa /proc
 282  283  file depends on the data model of the observer (the controlling process), not
 283  284  on the data model of the target process.
 284  285  A 64-bit debugger does not have to translate the information it reads from a
 285  286  .Pa /proc
 286  287  file for a 32-bit process from 32-bit format to 64-bit format.
 287  288  However, it usually has to be aware of the data model of the target process.
 288  289  The
 289  290  .Sy pr_dmodel
 290  291  field of the
 291  292  .Pa status
 292  293  files indicates the target process's data model.
 293  294  .Pp
 294  295  To help deal with system data structures that are read from 32-bit processes, a
 295  296  64-bit controlling program can be compiled with the C preprocessor symbol
 296  297  .Dv _SYSCALL32
 297  298  defined before system header files are included.
 298  299  This makes explicit 32-bit fixed-width data structures (like
 299  300  .Sy struct stat32 )
 300  301  visible to the 64-bit program.
 301  302  See
 302  303  .Xr types32.h 3HEAD .
 303  304  .Sh DIRECTORY STRUCTURE
 304  305  At the top level, the directory
 305  306  .Pa /proc
 306  307  contains entries each of which names an existing process in the system.
 307  308  These entries are themselves directories.
 308  309  Except where otherwise noted, the files described below can be
 309  310  opened for reading only.
 310  311  In addition, if a process becomes a
 311  312  .Em zombie
 312  313  (one that has exited but whose parent has not yet performed a
 313  314  .Xr wait 3C
 314  315  upon it), most of its associated
 315  316  .Pa /proc
 316  317  files disappear from the hierarchy; subsequent attempts to open them, or to
 317  318  read or write files opened before the process exited, will elicit the error
 318  319  .Er ENOENT .
 319  320  .Pp
 320  321  Although process state and consequently the contents of
 321  322  .Pa /proc
 322  323  files can change from instant to instant, a single
 323  324  .Xr read 2
 324  325  of a
 325  326  .Pa /proc
 326  327  file is guaranteed to return a sane representation of state; that is, the read
 327  328  will be atomic with respect to the state of the process.
 328  329  No such guarantee applies to successive reads applied to a
 329  330  .Pa /proc
 330  331  file for a running process.
 331  332  In addition, atomicity is not guaranteed for
 332  333  .Sy I/O
 333  334  applied to the
 334  335  .Pa as
 335  336  (address-space) file for a running process or for a process whose address space
 336  337  contains memory shared by another running process.
 337  338  .Pp
 338  339  A number of structure definitions are used to describe the files.
 339  340  These structures may grow by the addition of elements at the end in future
 340  341  releases of the system and it is not legitimate for a program to assume that
 341  342  they will not.
 342  343  .Sh STRUCTURE OF Pa /proc/ Ns Em pid
 343  344  A given directory
 344  345  .Pa /proc/ Ns Em pid
 345  346  contains the following entries.
 346  347  A process can use the invisible alias
 347  348  .Pa /proc/self
 348  349  if it wishes to open one of its own
 349  350  .Pa /proc
 350  351  files (invisible in the sense that the name
 351  352  .Dq self
 352  353  does not appear in a directory listing of
 353  354  .Pa /proc
 354  355  obtained from
 355  356  .Xr ls 1 ,
 356  357  .Xr getdents 2 ,
 357  358  or
 358  359  .Xr readdir 3C ) .
 359  360  .Ss contracts
 360  361  A directory containing references to the contracts held by the process.
 361  362  Each entry is a symlink to the contract's directory under
 362  363  .Pa /system/contract .
 363  364  See
 364  365  .Xr contract 5 .
 365  366  .Ss as
 366  367  Contains the address-space image of the process; it can be opened for both
 367  368  reading and writing.
 368  369  .Xr lseek 2
 369  370  is used to position the file at the virtual address of interest and then the
 370  371  address space can be examined or changed through
 371  372  .Xr read 2
 372  373  or
 373  374  .Xr write 2
 374  375  (or by using
 375  376  .Xr pread 2
 376  377  or
 377  378  .Xr pwrite 2
 378  379  for the combined operation).
 379  380  .Ss ctl
 380  381  A write-only file to which structured messages are written directing the system
 381  382  to change some aspect of the process's state or control its behavior in some
 382  383  way.
 383  384  The seek offset is not relevant when writing to this file.
 384  385  Individual lwps also have associated
 385  386  .Pa lwpctl
 386  387  files in the lwp subdirectories.
 387  388  A control message may be written either to the process's
 388  389  .Pa ctl
 389  390  file or to a specific
 390  391  .Pa lwpctl
 391  392  file with operation-specific effects.
 392  393  The effect of a control message is immediately reflected in the state of the
 393  394  process visible through appropriate status and information files.
 394  395  The types of control messages are described in detail later.
 395  396  See
 396  397  .Sx CONTROL MESSAGES .
 397  398  .Ss status
 398  399  Contains state information about the process and the representative lwp.
 399  400  The file contains a
 400  401  .Sy pstatus
 401  402  structure which contains an embedded
 402  403  .Sy lwpstatus
 403  404  structure for the representative lwp, as follows:
 404  405  .Bd -literal -offset 2
 405  406  typedef struct pstatus {
 406  407       int pr_flags;            /* flags (see below) */
 407  408       int pr_nlwp;             /* number of active lwps in the process */
 408  409       int pr_nzomb;            /* number of zombie lwps in the process */
 409  410       pid_tpr_pid;             /* process id */
 410  411       pid_tpr_ppid;            /* parent process id */
 411  412       pid_tpr_pgid;            /* process group id */
 412  413       pid_tpr_sid;             /* session id */
 413  414       id_t pr_aslwpid;         /* obsolete */
 414  415       id_t pr_agentid;         /* lwp-id of the agent lwp, if any */
 415  416       sigset_t pr_sigpend;     /* set of process pending signals */
 416  417       uintptr_t pr_brkbase;    /* virtual address of the process heap */
 417  418       size_t pr_brksize;       /* size of the process heap, in bytes */
 418  419       uintptr_t pr_stkbase;    /* virtual address of the process stack */
 419  420       size_tpr_stksize;        /* size of the process stack, in bytes */
 420  421       timestruc_t pr_utime;    /* process user cpu time */
 421  422       timestruc_t pr_stime;    /* process system cpu time */
 422  423       timestruc_t pr_cutime;   /* sum of children's user times */
 423  424       timestruc_t pr_cstime;   /* sum of children's system times */
 424  425       sigset_t pr_sigtrace;    /* set of traced signals */
 425  426       fltset_t pr_flttrace;    /* set of traced faults */
 426  427       sysset_t pr_sysentry;    /* set of system calls traced on entry */
 427  428       sysset_t pr_sysexit;     /* set of system calls traced on exit */
 428  429       char pr_dmodel;          /* data model of the process */
 429  430       taskid_t pr_taskid;      /* task id */
 430  431       projid_t pr_projid;      /* project id */
 431  432       zoneid_t pr_zoneid;      /* zone id */
 432  433       lwpstatus_t pr_lwp;      /* status of the representative lwp */
 433  434  } pstatus_t;
 434  435  .Ed
 435  436  .Pp
 436  437  .Sy pr_flags
 437  438  is a bit-mask holding the following process flags.
 438  439  For convenience, it also contains the lwp flags for the representative lwp,
 439  440  described later.
 440  441  .Bl -tag -width "PR_MSACCT" -offset indent
 441  442  .It Sy PR_ISSYS
 442  443  process is a system process (see
 443  444  .Sx PCSTOP ) .
 444  445  .It Sy PR_VFORKP
 445  446  process is the parent of a vforked child (see
 446  447  .Sx PCWATCH ) .
 447  448  .It Sy PR_FORK
 448  449  process has its inherit-on-fork mode set (see
 449  450  .Sx PCSET ) .
 450  451  .It Sy PR_RLC
 451  452  process has its run-on-last-close mode set (see
 452  453  .Sx PCSET ) .
 453  454  .It Sy PR_KLC
 454  455  process has its kill-on-last-close mode set (see
 455  456  .Sx PCSET ) .
 456  457  .It Sy PR_ASYNC
 457  458  process has its asynchronous-stop mode set (see
 458  459  .Sx PCSET ) .
 459  460  .It Sy PR_MSACCT
 460  461  Set by default in all processes to indicate that microstate accounting is
 461  462  enabled.
 462  463  However, this flag has been deprecated and no longer has any effect.
 463  464  Microstate accounting may not be disabled; however, it is still possible to
 464  465  toggle the flag.
 465  466  .It Sy PR_MSFORK
 466  467  Set by default in all processes to indicate that microstate accounting will be
 467  468  enabled for processes that this parent
 468  469  .Xr fork 2 Ns s .
 469  470  However, this flag has been deprecated and no longer has any effect.
 470  471  It is possible to toggle this flag; however, it is not possible to disable
 471  472  microstate accounting.
 472  473  .It Sy PR_BPTADJ
 473  474  process has its breakpoint adjustment mode set (see
 474  475  .Sx PCSET ) .
 475  476  .It Sy PR_PTRACE
 476  477  process has its ptrace-compatibility mode set (see
 477  478  .Sx PCSET ) .
 478  479  .El
 479  480  .Pp
 480  481  .Sy pr_nlwp
 481  482  is the total number of active lwps in the process.
 482  483  .Sy pr_nzomb
 483  484  is the total number of zombie lwps in the process.
 484  485  A zombie lwp is a non-detached lwp that has terminated but has not been reaped
 485  486  with
 486  487  .Xr thr_join 3C
 487  488  or
 488  489  .Xr pthread_join 3C .
 489  490  .Pp
 490  491  .Sy pr_pid ,
 491  492  .Sy pr_ppi ,
 492  493  .Sy pr_pgid ,
 493  494  and
 494  495  .Sy pr_sid
 495  496  are, respectively, the process ID, the ID of the process's parent, the
 496  497  process's process group ID, and the process's session ID.
 497  498  .Pp
 498  499  .Sy pr_aslwpid
 499  500  is obsolete and is always zero.
 500  501  .Pp
 501  502  .Sy pr_agentid
 502  503  is the lwp-ID for the
 503  504  .Pa /proc
 504  505  agent lwp (see the
 505  506  .Sx PCAGENT
 506  507  control operation).
 507  508  It is zero if there is no agent lwp in the process.
 508  509  .Pp
 509  510  .Sy pr_sigpend
 510  511  identifies asynchronous signals pending for the process.
 511  512  .Pp
 512  513  .Sy pr_brkbase
 513  514  is the virtual address of the process heap and
 514  515  .Sy pr_brksize
 515  516  is its size in bytes.
 516  517  The address formed by the sum of these values is the process
 517  518  .Sy break
 518  519  (see
 519  520  .Xr brk 2 ) .
 520  521  .Sy pr_stkbase
 521  522  and
 522  523  .Sy pr_stksize
 523  524  are, respectively, the virtual address of the process stack and its size in
 524  525  bytes.
 525  526  (Each lwp runs on a separate stack; the distinguishing characteristic of the
 526  527  process stack is that the operating system will grow it when necessary.)
 527  528  .Pp
 528  529  .Sy pr_utime ,
 529  530  .Sy pr_stime ,
 530  531  .Sy pr_cutime ,
 531  532  .Sy and pr_cstime
 532  533  are, respectively, the user
 533  534  .Sy CPU
 534  535  and system
 535  536  .Sy CPU
 536  537  time consumed by the process, and the cumulative user
 537  538  .Sy CPU
 538  539  and system
 539  540  .Sy CPU
 540  541  time consumed by the process's children, in seconds and nanoseconds.
 541  542  .Pp
 542  543  .Sy pr_sigtrace
 543  544  and
 544  545  .Sy pr_flttrace
 545  546  contain, respectively, the set of signals and the set of hardware faults that
 546  547  are being traced (see
 547  548  .Sx PCSTRACE
 548  549  and
 549  550  .Sx PCSFAULT ) .
 550  551  .Pp
 551  552  .Sy pr_sysentry
 552  553  and
 553  554  .Sy pr_sysexit
 554  555  contain, respectively, the sets of system calls being traced on entry and exit
 555  556  (see
 556  557  .Sx PCSENTRY
 557  558  and
 558  559  .Sx PCSEXIT ) .
 559  560  .Pp
 560  561  .Sy pr_dmodel
 561  562  indicates the data model of the process.
 562  563  Possible values are:
 563  564  .Bl -tag -width "PR_MODEL_NATIVE" -offset indent
 564  565  .It Sy PR_MODEL_ILP32
 565  566  process data model is ILP32.
 566  567  .It Sy PR_MODEL_LP64
 567  568  process data model is LP64.
 568  569  .It Sy PR_MODEL_NATIVE
 569  570  process data model is native.
 570  571  .El
 571  572  .Pp
 572  573  The
 573  574  .Sy pr_taskid ,
 574  575  .Sy pr_projid ,
 575  576  and
 576  577  .Sy pr_zoneid
 577  578  fields contain respectively, the numeric
 578  579  .Sy ID Ns s
 579  580  of the task, project, and zone in which the process was running.
 580  581  .Pp
 581  582  The constant
 582  583  .Sy PR_MODEL_NATIVE
 583  584  reflects the data model of the controlling process,
 584  585  .Em that is ,
 585  586  its value is
 586  587  .Sy PR_MODEL_ILP32
 587  588  or
 588  589  .Sy PR_MODEL_LP64
 589  590  according to whether the controlling process has been
 590  591  compiled as a 32-bit program or a 64-bit program, respectively.
 591  592  .Pp
 592  593  .Sy pr_lwp
 593  594  contains the status information for the representative lwp:
 594  595  .Bd -literal -offset 2
 595  596  typedef struct lwpstatus {
 596  597    int pr_flags;              /* flags (see below) */
 597  598    id_t pr_lwpid;             /* specific lwp identifier */
 598  599    short pr_why;              /* reason for lwp stop, if stopped */
 599  600    short pr_what;             /* more detailed reason */
 600  601    short pr_cursig;           /* current signal, if any */
 601  602    siginfo_t pr_info;         /* info associated with signal or fault */
 602  603    sigset_t pr_lwppend;       /* set of signals pending to the lwp */
 603  604    sigset_t pr_lwphold;       /* set of signals blocked by the lwp */
 604  605    struct sigaction pr_action;/* signal action for current signal */
 605  606    stack_t pr_altstack;       /* alternate signal stack info */
 606  607    uintptr_t pr_oldcontext;   /* address of previous ucontext */
 607  608    short pr_syscall;          /* system call number (if in syscall) */
 608  609    short pr_nsysarg;          /* number of arguments to this syscall */
 609  610    int pr_errno;              /* errno for failed syscall */
 610  611    long pr_sysarg[PRSYSARGS]; /* arguments to this syscall */
 611  612    long pr_rval1;             /* primary syscall return value */
 612  613    long pr_rval2;             /* second syscall return value, if any */
 613  614    char pr_clname[PRCLSZ];    /* scheduling class name */
 614  615    timestruc_t pr_tstamp;     /* real-time time stamp of stop */
 615  616    timestruc_t pr_utime;      /* lwp user cpu time */
 616  617    timestruc_t pr_stime;      /* lwp system cpu time */
 617  618    uintptr_t pr_ustack;       /* stack boundary data (stack_t) address */
 618  619    ulong_t pr_instr;          /* current instruction */
 619  620    prgregset_t pr_reg;        /* general registers */
 620  621    prfpregset_t pr_fpreg;     /* floating-point registers */
 621  622  } lwpstatus_t;
 622  623  .Ed
 623  624  .Pp
 624  625  .Sy pr_flags
 625  626  is a bit-mask holding the following lwp flags.
 626  627  For convenience, it also contains the process flags, described previously.
 627  628  .Bl -tag -width "PR_STOPPED" -offset indent
 628  629  .It Sy PR_STOPPED
 629  630  The lwp is stopped.
 630  631  .It Sy PR_ISTOP
 631  632  The lwp is stopped on an event of interest (see
 632  633  .Sx PCSTOP ) .
 633  634  .It Sy PR_DSTOP
 634  635  The lwp has a stop directive in effect (see
 635  636  .Sx PCSTOP ) .
 636  637  .It Sy PR_STEP
 637  638  The lwp has a single-step directive in effect (see
 638  639  .Sx PCRUN ) .
 639  640  .It Sy PR_ASLEEP
 640  641  The lwp is in an interruptible sleep within a system call.
 641  642  .It Sy PR_PCINVAL
 642  643  The lwp's current instruction
 643  644  .Pq Sy pr_instr
 644  645  is undefined.
 645  646  .It Sy PR_DETACH
 646  647  This is a detached lwp (see
 647  648  .Xr pthread_create 3C
 648  649  and
 649  650  .Xr pthread_join 3C ) .
 650  651  .It Sy PR_DAEMON
 651  652  This is a daemon lwp (see
 652  653  .Xr pthread_create 3C ) .
 653  654  .It Sy PR_ASLWP
 654  655  This flag is obsolete and is never set.
 655  656  .It Sy PR_AGENT
 656  657  This is the
 657  658  .Pa /proc
 658  659  agent lwp for the process.
 659  660  .El
 660  661  .Pp
 661  662  .Sy pr_lwpid
 662  663  names the specific lwp.
 663  664  .Pp
 664  665  .Sy pr_why
 665  666  .Sy and
 666  667  pr_what
 667  668  together describe, for a stopped lwp, the reason for the stop.
 668  669  Possible values of
 669  670  .Sy pr_why
 670  671  and the associated
 671  672  .Sy pr_what
 672  673  are:
 673  674  .Bl -tag -width "PR_JOBCONTROL" -offset left
 674  675  .It Sy PR_REQUESTED
 675  676  indicates that the stop occurred in response to a stop directive, normally
 676  677  because
 677  678  .Sy PCSTOP
 678  679  was applied or because another lwp stopped on an event of interest and the
 679  680  asynchronous-stop flag (see
 680  681  .Sx PCSET )
 681  682  was not set for the process.
 682  683  .Sy pr_what
 683  684  is unused in this case.
 684  685  .It Sy PR_SIGNALLED
 685  686  indicates that the lwp stopped on receipt of a signal (see
 686  687  .Sx PCSTRACE ) ;
 687  688  .Sy pr_what
 688  689  holds the signal number that caused the stop (for a newly-stopped
 689  690  lwp, the same value is in
 690  691  .Sy pr_cursig ) .
 691  692  .It Sy PR_FAULTED
 692  693  indicates that the lwp stopped on incurring a hardware fault (see
 693  694  .Sx PCSFAULT ) ;
 694  695  .Sy pr_what
 695  696  holds the fault number that caused the stop.
 696  697  .It Sy PR_SYSENTRY
 697  698  .It Sy PR_SYSEXIT
 698  699  indicate a stop on entry to or exit from a system call (see
 699  700  .Sx PCSENTRY
 700  701  and
 701  702  .Sx PCSEXIT ) ;
 702  703  .Sy pr_what
 703  704  holds the system call number.
 704  705  .It Sy PR_JOBCONTROL
 705  706  indicates that the lwp stopped due to the default action of a job control stop
 706  707  signal (see
 707  708  .Xr sigaction 2 ) ;
 708  709  .Sy pr_what
 709  710  holds the stopping signal number.
 710  711  .It Sy PR_SUSPENDED
 711  712  indicates that the lwp stopped due to internal synchronization of lwps within
 712  713  the process.
 713  714  .Sy pr_what
 714  715  is unused in this case.
 715  716  .It Sy PR_BRAND
 716  717  indicates that the lwp stopped for a brand-specific reason.
 717  718  Interpretation of the value of
 718  719  .Sy pr_what
 719  720  depends on which zone brand is in use.
 720  721  It is not generally expected that an lwp stopped in this state will be
 721  722  restarted by native
 722  723  .\" mandoc(1) doesn't like .Xr macros referring to itself, so this is
 723  724  .\" a bit of a hack.
 724  725  .Nm Ns Pq 4
 725  726  consumers.
 726  727  .El
 727  728  .Pp
 728  729  .Sy pr_cursig
 729  730  names the current signal, that is, the next signal to be delivered to the lwp,
 730  731  if any.
 731  732  .Sy pr_info ,
 732  733  when the lwp is in a
 733  734  .Sy PR_SIGNALLED
 734  735  or
 735  736  .Sy PR_FAULTED
 736  737  stop, contains additional information pertinent to the particular signal or
 737  738  fault (see
 738  739  .In sys/siginfo.h ) .
 739  740  .Pp
 740  741  .Sy pr_lwppend
 741  742  identifies any synchronous or directed signals pending for the lwp.
 742  743  .Sy pr_lwphold
 743  744  identifies those signals whose delivery is being blocked by the lwp (the
 744  745  signal mask).
 745  746  .Pp
 746  747  .Sy pr_action
 747  748  contains the signal action information pertaining to the current signal (see
 748  749  .Xr sigaction 2 ) ;
 749  750  it is undefined if
 750  751  .Sy pr_cursig
 751  752  is zero.
 752  753  .Sy pr_altstack
 753  754  contains the alternate signal stack information for the lwp (see
 754  755  .Xr sigaltstack 2 ) .
 755  756  .Pp
 756  757  .Sy pr_oldcontext ,
 757  758  if not zero, contains the address on the lwp stack of a
 758  759  .Sy ucontext
 759  760  structure describing the previous user-level context (see
 760  761  .Xr ucontext.h 3HEAD ) .
 761  762  It is non-zero only if the lwp is executing in the context of a signal handler.
 762  763  .Pp
 763  764  .Sy pr_syscall
 764  765  is the number of the system call, if any, being executed by
 765  766  the lwp; it is non-zero if and only if the lwp is stopped on
 766  767  .Sy PR_SYSENTRY
 767  768  or
 768  769  .Sy PR_SYSEXIT ,
 769  770  or is asleep within a system call
 770  771  .Pf ( Sy PR_ASLEEP
 771  772  is set).
 772  773  If
 773  774  .Sy pr_syscall
 774  775  is non-zero,
 775  776  .Sy pr_nsysarg
 776  777  is the number of arguments to the system call and
 777  778  .Sy pr_sysarg
 778  779  contains the actual arguments.
 779  780  .Pp
 780  781  .Sy pr_rval1 ,
 781  782  .Sy pr_rval2 ,
 782  783  and
 783  784  .Sy pr_errno
 784  785  are defined only if the lwp
 785  786  is stopped on
 786  787  .Sy PR_SYSEXIT
 787  788  or if the
 788  789  .Sy PR_VFORKP
 789  790  flag is set.
 790  791  If
 791  792  .Sy pr_errno
 792  793  is zero,
 793  794  .Sy pr_rval1
 794  795  and
 795  796  .Sy pr_rval2
 796  797  contain the return values from the system call.
 797  798  Otherwise,
 798  799  .Sy pr_errno
 799  800  contains the error number for the failing system call (see
 800  801  .In sys/errno.h ) .
 801  802  .Pp
 802  803  .Sy pr_clname
 803  804  contains the name of the lwp's scheduling class.
 804  805  .Pp
 805  806  .Sy pr_tstamp ,
 806  807  if the lwp is stopped, contains a time stamp marking when the
 807  808  lwp stopped, in real time seconds and nanoseconds since an arbitrary time in
 808  809  the past.
 809  810  .Pp
 810  811  .Sy pr_utime
 811  812  is the amount of user level CPU time used by this LWP.
 812  813  .Pp
 813  814  .Sy pr_stime
 814  815  is the amount of system level CPU time used by this LWP.
 815  816  .Pp
 816  817  .Sy pr_ustack
 817  818  is the virtual address of the
 818  819  .Sy stack_t
 819  820  that contains the stack boundaries for this LWP.
 820  821  See
 821  822  .Xr getustack 2
 822  823  and
 823  824  .Xr _stack_grow 3C .
 824  825  .Pp
 825  826  .Sy pr_instr
 826  827  contains the machine instruction to which the lwp's program counter refers.
 827  828  The amount of data retrieved from the process is machine-dependent.
 828  829  On SPARC based machines, it is a 32-bit word.
 829  830  On x86-based machines, it is a single byte.
 830  831  In general, the size is that of the machine's smallest instruction.
 831  832  If
 832  833  .Sy PR_PCINVAL
 833  834  is set,
 834  835  .Sy pr_instr
 835  836  is undefined; this occurs whenever the lwp is not stopped or when the program
 836  837  counter refers to an invalid virtual address.
 837  838  .Pp
 838  839  .Sy pr_reg
 839  840  is an array holding the contents of a stopped lwp's general registers.
 840  841  .Bl -tag -offset left -width "SPARC V8 (32-bit)"
 841  842  .It Sy SPARC
 842  843  On SPARC-based machines, the predefined constants
 843  844  .Sy R_G0
 844  845  \&.\&.\&.
 845  846  .Sy R_G7 ,
 846  847  .Sy R_O0
 847  848  \&.\&.\&.
 848  849  .Sy R_O7 ,
 849  850  .Sy R_L0
 850  851  \&.\&.\&.
 851  852  .Sy R_L7 ,
 852  853  .Sy R_I0
 853  854  \&.\&.\&.
 854  855  .Sy R_I7 ,
 855  856  .Sy R_PC ,
 856  857  .Sy R_nPC ,
 857  858  and
 858  859  .Sy R_Y
 859  860  can be used as indices to refer to the corresponding registers; previous
 860  861  register windows can be read from their overflow locations on the stack
 861  862  (however, see the
 862  863  .Pa gwindows
 863  864  file in the
 864  865  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid
 865  866  subdirectory).
 866  867  .It Sy SPARC V8 (32-bit)
 867  868  For SPARC V8 (32-bit) controlling processes, the predefined constants
 868  869  .Sy R_PSR ,
 869  870  .Sy R_WIM ,
 870  871  and
 871  872  .Sy R_TBR
 872  873  can be used as indices to refer to the corresponding special registers.
 873  874  For SPARC V9 (64-bit) controlling processes, the predefined constants
 874  875  .Sy R_CCR ,
 875  876  .Sy R_ASI ,
 876  877  and
 877  878  .Sy R_FPRS
 878  879  can be used as indices to refer to the corresponding special registers.
 879  880  .It Sy x86 (32-bit)
 880  881  For 32-bit x86 processes, the predefined constants listed belowcan be used as
 881  882  indices to refer to the corresponding registers.
 882  883  .Bl -tag -width "TRAPNO" -offset indent -compact
 883  884  .It SS
 884  885  .It UESP
 885  886  .It EFL
 886  887  .It CS
 887  888  .It EIP
 888  889  .It ERR
 889  890  .It TRAPNO
 890  891  .It EAX
 891  892  .It ECX
 892  893  .It EDX
 893  894  .It EBX
 894  895  .It ESP
 895  896  .It EBP
 896  897  .It ESI
 897  898  .It EDI
 898  899  .It DS
 899  900  .It ES
 900  901  .It GS
 901  902  .El
 902  903  .Pp
 903  904  The preceding constants are listed in
 904  905  .In sys/regset.h .
 905  906  .Pp
 906  907  Note that a 32-bit process can run on an x86 64-bit system, using the constants
 907  908  listed above.
 908  909  .It Sy x86 (64-bit)
 909  910  To read the registers of a 32-
 910  911  .Em or
 911  912  a 64-bit process, a 64-bit x86 process should use the predefined constants
 912  913  listed below.
 913  914  .Bl -tag -width "REG_TRAPNO" -offset indent -compact
 914  915  .It REG_GSBASE
 915  916  .It REG_FSBASE
 916  917  .It REG_DS
 917  918  .It REG_ES
 918  919  .It REG_GS
 919  920  .It REG_FS
 920  921  .It REG_SS
 921  922  .It REG_RSP
 922  923  .It REG_RFL
 923  924  .It REG_CS
 924  925  .It REG_RIP
 925  926  .It REG_ERR
 926  927  .It REG_TRAPNO
 927  928  .It REG_RAX
 928  929  .It REG_RCX
 929  930  .It REG_RDX
 930  931  .It REG_RBX
 931  932  .It REG_RBP
 932  933  .It REG_RSI
 933  934  .It REG_RDI
 934  935  .It REG_R8
 935  936  .It REG_R9
 936  937  .It REG_R10
 937  938  .It REG_R11
 938  939  .It REG_R12
 939  940  .It REG_R13
 940  941  .It REG_R14
 941  942  .It REG_R15
 942  943  .El
 943  944  .Pp
 944  945  The preceding constants are listed in
 945  946  .In sys/regset.h .
 946  947  .El
 947  948  .Pp
 948  949  .Sy pr_fpreg
 949  950  is a structure holding the contents of the floating-point registers.
 950  951  .Pp
 951  952  SPARC registers, both general and floating-point, as seen by a 64-bit
 952  953  controlling process are the V9 versions of the registers, even if the target
 953  954  process is a 32-bit (V8) process.
 954  955  V8 registers are a subset of the V9 registers.
 955  956  .Pp
 956  957  If the lwp is not stopped, all register values are undefined.
 957  958  .Ss psinfo
 958  959  Contains miscellaneous information about the process and the representative lwp
 959  960  needed by the
 960  961  .Xr ps 1
 961  962  command.
 962  963  .Sy psinfo
 963  964  remains accessible after a process becomes a
 964  965  .Em zombie .
 965  966  The file contains a
 966  967  .Sy psinfo
 967  968  structure which contains an embedded
 968  969  .Sy lwpsinfo
 969  970  structure for the representative lwp, as follows:
 970  971  .Bd -literal -offset 2
 971  972  typedef struct psinfo {
 972  973      int pr_flag;             /* process flags (DEPRECATED: see below) */
 973  974      int pr_nlwp;             /* number of active lwps in the process */
 974  975      int pr_nzomb;            /* number of zombie lwps in the process */
 975  976      pid_t pr_pid;            /* process id */
 976  977      pid_t pr_ppid;           /* process id of parent */
 977  978      pid_t pr_pgid;           /* process id of process group leader */
 978  979      pid_t pr_sid;            /* session id */
 979  980      uid_t pr_uid;            /* real user id */
 980  981      uid_t pr_euid;           /* effective user id */
 981  982      gid_t pr_gid;            /* real group id */
 982  983      gid_t pr_egid;           /* effective group id */
 983  984      uintptr_t pr_addr;       /* address of process */
 984  985      size_t pr_size;          /* size of process image in Kbytes */
 985  986      size_t pr_rssize;        /* resident set size in Kbytes */
 986  987      dev_t pr_ttydev;         /* controlling tty device (or PRNODEV) */
 987  988      ushort_t pr_pctcpu;      /* % of recent cpu time used by all lwps */
 988  989      ushort_t pr_pctmem;      /* % of system memory used by process */
 989  990      timestruc_t pr_start;    /* process start time, from the epoch */
 990  991      timestruc_t pr_time;     /* cpu time for this process */
 991  992      timestruc_t pr_ctime;    /* cpu time for reaped children */
 992  993      char pr_fname[PRFNSZ];   /* name of exec'ed file */
 993  994      char pr_psargs[PRARGSZ]; /* initial characters of arg list */
 994  995      int pr_wstat;            /* if zombie, the wait() status */
 995  996      int pr_argc;             /* initial argument count */
 996  997      uintptr_t pr_argv;       /* address of initial argument vector */
 997  998      uintptr_t pr_envp;       /* address of initial environment vector */
 998  999      char pr_dmodel;          /* data model of the process */
 999 1000      taskid_t pr_taskid;      /* task id */
1000 1001      projid_t pr_projid;      /* project id */
1001 1002      poolid_t pr_poolid;      /* pool id */
1002 1003      zoneid_t pr_zoneid;      /* zone id */
1003 1004      ctid_t pr_contract;      /* process contract id */
1004 1005      lwpsinfo_t pr_lwp;       /* information for representative lwp */
1005 1006  } psinfo_t;
1006 1007  .Ed
1007 1008  .Pp
1008 1009  Some of the entries in
1009 1010  .Sy psinfo ,
1010 1011  such as
1011 1012  .Sy pr_addr ,
1012 1013  refer to internal kernel data structures and should not be expected to retain
1013 1014  their meanings across different versions of the operating system.
1014 1015  .Pp
1015 1016  .Sy psinfo_t.pr_flag
1016 1017  is a deprecated interface that should no longer be used.
1017 1018  Applications currently relying on the
1018 1019  .Sy SSYS
1019 1020  bit in
1020 1021  .Sy pr_flag
1021 1022  should migrate to checking
1022 1023  .Sy PR_ISSYS
1023 1024  in the
1024 1025  .Sy pstatus
1025 1026  structure's
1026 1027  .Sy pr_flags
1027 1028  field.
1028 1029  .Pp
1029 1030  .Sy pr_pctcpu
1030 1031  and
1031 1032  .Sy pr_pctmem
1032 1033  are 16-bit binary fractions in the range 0.0 to 1.0 with the binary point to
1033 1034  the right of the high-order bit (1.0 == 0x8000).
1034 1035  .Sy pr_pctcpu
1035 1036  is the summation over all lwps in the process.
1036 1037  .Pp
1037 1038  The
1038 1039  .Sy pr_fname
1039 1040  and
1040 1041  .Sy pr_psargs
1041 1042  are writable by the owner of the process.
1042 1043  To write to them, the
1043 1044  .Sy psinfo
1044 1045  file should be open for writing and the desired value for the field should be
1045 1046  written at the file offset that corresponds to the member of structure.
1046 1047  No other entry may be written to; if a write is attempted to an offset that
1047 1048  does not represent one of these two memers, or if the size of the write is not
1048 1049  exactly the size of the member being written, no bytes will be written and
1049 1050  zero will be returned.
1050 1051  .Pp
1051 1052  .Sy pr_lwp
1052 1053  contains the
1053 1054  .Xr ps 1
1054 1055  information for the representative lwp.
1055 1056  If the process is a
1056 1057  .Em zombie ,
1057 1058  .Sy pr_nlwp ,
1058 1059  .Sy pr_nzomb ,
1059 1060  and
1060 1061  .Sy pr_lwp.pr_lwpid
1061 1062  are zero and the other fields of
1062 1063  .Sy pr_lwp
1063 1064  are undefined:
1064 1065  .Bd -literal -offset 2
1065 1066  typedef struct lwpsinfo {
1066 1067      int pr_flag;             /* lwp flags (DEPRECATED: see below) */
1067 1068      id_t pr_lwpid;           /* lwp id */
1068 1069      uintptr_t pr_addr;       /* internal address of lwp */
1069 1070      uintptr_t pr_wchan;      /* wait addr for sleeping lwp */
1070 1071      char pr_stype;           /* synchronization event type */
1071 1072      char pr_state;           /* numeric lwp state */
1072 1073      char pr_sname;           /* printable character for pr_state */
1073 1074      char pr_nice;            /* nice for cpu usage */
1074 1075      short pr_syscall;        /* system call number (if in syscall) */
1075 1076      char pr_oldpri;          /* pre-SVR4, low value is high priority */
1076 1077      char pr_cpu;             /* pre-SVR4, cpu usage for scheduling */
1077 1078      int pr_pri;              /* priority, high value = high priority */
1078 1079      ushort_t pr_pctcpu;      /* % of recent cpu time used by this lwp */
1079 1080      timestruc_t pr_start;    /* lwp start time, from the epoch */
1080 1081      timestruc_t pr_time;     /* cpu time for this lwp */
1081 1082      char pr_clname[PRCLSZ];  /* scheduling class name */
1082 1083      char pr_name[PRFNSZ];    /* name of system lwp */
1083 1084      processorid_t pr_onpro;  /* processor which last ran this lwp */
1084 1085      processorid_t pr_bindpro;/* processor to which lwp is bound */
1085 1086      psetid_t pr_bindpset;    /* processor set to which lwp is bound */
1086 1087      lgrp_id_t pr_lgrp;       /* home lgroup */
1087 1088  } lwpsinfo_t;
1088 1089  .Ed
1089 1090  .Pp
1090 1091  Some of the entries in
1091 1092  .Sy lwpsinfo ,
1092 1093  such as
1093 1094  .Sy pr_addr ,
1094 1095  .Sy pr_wchan ,
1095 1096  .Sy pr_stype ,
1096 1097  .Sy pr_state ,
1097 1098  and
1098 1099  .Sy pr_name ,
1099 1100  refer to internal kernel data structures and should not be expected to retain
1100 1101  their meanings across different versions of the operating system.
1101 1102  .Pp
1102 1103  .Sy lwpsinfo_t.pr_flag
1103 1104  is a deprecated interface that should no longer be used.
1104 1105  .Pp
1105 1106  .Sy pr_pctcpu
1106 1107  is a 16-bit binary fraction, as described above.
1107 1108  It represents the
1108 1109  .Sy CPU
1109 1110  time used by the specific lwp.
1110 1111  On a multi-processor machine, the maximum value is 1/N, where N is the number
1111 1112  of
1112 1113  .Sy CPU Ns s .
1113 1114  .Pp
1114 1115  .Sy pr_contract
1115 1116  is the id of the process contract of which the process is a member.
1116 1117  See
1117 1118  .Xr contract 5
1118 1119  and
1119 1120  .Xr process 5 .
1120 1121  .Ss cred
1121 1122  Contains a description of the credentials associated with the process:
1122 1123  .Bd -literal -offset 2
1123 1124  typedef struct prcred {
1124 1125          uid_t pr_euid;      /* effective user id */
1125 1126          uid_t pr_ruid;      /* real user id */
1126 1127          uid_t pr_suid;      /* saved user id (from exec) */
1127 1128          gid_t pr_egid;      /* effective group id */
1128 1129          gid_t pr_rgid;      /* real group id */
1129 1130          gid_t pr_sgid;      /* saved group id (from exec) */
1130 1131          int pr_ngroups;     /* number of supplementary groups */
1131 1132          gid_t pr_groups[1]; /* array of supplementary groups */
1132 1133  } prcred_t;
1133 1134  .Ed
1134 1135  .Pp
1135 1136  The array of associated supplementary groups in
1136 1137  .Sy pr_groups
1137 1138   is of variable
1138 1139  length; the
1139 1140  .Sy cred
1140 1141  file contains all of the supplementary groups.
1141 1142  .Sy pr_ngroups
1142 1143  indicates the number of supplementary groups. (See also the
1143 1144  .Sy PCSCRED
1144 1145  and
1145 1146  .Sy PCSCREDX
1146 1147  control operations.)
1147 1148  .Ss priv
1148 1149  Contains a description of the privileges associated with the process:
1149 1150  .Bd -literal -offset 2
1150 1151  typedef struct prpriv {
1151 1152       uint32_t        pr_nsets;      /* number of privilege set */
1152 1153       uint32_t        pr_setsize;    /* size of privilege set */
1153 1154       uint32_t        pr_infosize;   /* size of supplementary data */
1154 1155       priv_chunk_t    pr_sets[1];    /* array of sets */
1155 1156  } prpriv_t;
1156 1157  .Ed
1157 1158  .Pp
1158 1159  The actual dimension of the
1159 1160  .Sy pr_sets Ns []
1160 1161  field is
1161 1162  .D1 pr_sets[pr_nsets][pr_setsize]
1162 1163  .Pp
1163 1164  which is followed by additional information about the process state
1164 1165  .Sy pr_infosize
1165 1166  bytes in size.
1166 1167  .Pp
1167 1168  The full size of the structure can be computed using
1168 1169  .Fn PRIV_PRPRIV_SIZE "prpriv_t *" .
1169 1170  .Ss secflags
1170 1171  This file contains the security-flags of the process.
1171 1172  It contains a description of the security flags associated with the process.
1172 1173  .Bd -literal -offset 2
1173 1174  typedef struct prsecflags {
1174 1175          uint32_t pr_version;            /* ABI Versioning of this structure */
1175 1176          secflagset_t pr_effective;      /* Effective flags */
1176 1177          secflagset_t pr_inherit;        /* Inheritable flags */
1177 1178          secflagset_t pr_lower;          /* Lower flags */
1178 1179          secflagset_t pr_upper;          /* Upper flags */
1179 1180  } prsecflags_t;
1180 1181  .Ed
1181 1182  .Pp
1182 1183  The
1183 1184  .Sy pr_version
1184 1185  field is a version number for the structure, currently
1185 1186  .Sy PRSECFLAGS_VERSION_1 .
1186 1187  .Ss sigact
1187 1188  Contains an array of
1188 1189  .Sy sigaction structures
1189 1190  describing the current dispositions of all signals associated with the traced
1190 1191  process (see
1191 1192  .Xr sigaction 2 ) .
1192 1193  Signal numbers are displaced by 1 from array indices, so that the action for
1193 1194  signal number
1194 1195  .Va n
1195 1196  appears in position
1196 1197  .Va n Ns -1
1197 1198  of the array.
1198 1199  .Ss auxv
1199 1200  Contains the initial values of the process's aux vector in an array of
1200 1201  .Sy auxv_t
1201 1202  structures (see
1202 1203  .In sys/auxv.h ) .
1203 1204  The values are those that were passed by the operating system as startup
1204 1205  information to the dynamic linker.
1205 1206  .Ss argv
1206 1207  Contains the concatenation of each of the argument strings, including their
1207 1208  .Sy NUL
1208 1209  terminators, in the argument vector
1209 1210  .Pq Va argv
1210 1211  for the process.
1211 1212  If the process has modified either its argument vector, or the contents of
1212 1213  any of the strings referenced by that vector, those changes will be visible
1213 1214  here.
1214 1215  .Ss ldt
1215 1216  This file exists only on x86-based machines.
1216 1217  It is non-empty only if the process has established a local descriptor table
1217 1218  .Pq Sy LDT .
1218 1219  If non-empty, the file contains the array of currently active
1219 1220  .Sy LDT
1220 1221  entries in an array of elements of type
1221 1222  .Vt struct ssd ,
1222 1223  defined in
1223 1224  .In sys/sysi86.h ,
1224 1225  one element for each active
1225 1226  .Sy LDT
1226 1227  entry.
1227 1228  .Ss map, xmap
1228 1229  Contain information about the virtual address map of the process.
1229 1230  The map file contains an array of
1230 1231  .Sy prmap
1231 1232  structures while the xmap file contains an
1232 1233  array of
1233 1234  .Sy prxmap
1234 1235  structures.
1235 1236  Each structure describes a contiguous virtual
1236 1237  address region in the address space of the traced process:
1237 1238  .Bd -literal -offset 2
1238 1239  typedef struct prmap {
1239 1240          uintptr_tpr_vaddr;         /* virtual address of mapping */
1240 1241          size_t pr_size;            /* size of mapping in bytes */
1241 1242          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1242 1243          offset_t pr_offset;        /* offset into mapped object, if any */
1243 1244          int pr_mflags;             /* protection and attribute flags */
1244 1245          int pr_pagesize;           /* pagesize for this mapping in bytes */
1245 1246          int pr_shmid;              /* SysV shared memory identifier */
1246 1247  } prmap_t;
1247 1248  .Ed
1248 1249  .Bd -literal -offset 2
1249 1250  typedef struct prxmap {
1250 1251          uintptr_t pr_vaddr;        /* virtual address of mapping */
1251 1252          size_t pr_size;            /* size of mapping in bytes */
1252 1253          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1253 1254          offset_t pr_offset;        /* offset into mapped object, if any */
1254 1255          int pr_mflags;             /* protection and attribute flags */
1255 1256          int pr_pagesize;           /* pagesize for this mapping in bytes */
1256 1257          int pr_shmid;              /* SysV shared memory identifier */
1257 1258          dev_t pr_dev;              /* device of mapped object, if any */
1258 1259          uint64_t pr_ino;           /* inode of mapped object, if any */
1259 1260          size_t pr_rss;             /* pages of resident memory */
1260 1261          size_t pr_anon;            /* pages of resident anonymous memory */
1261 1262          size_t pr_locked;          /* pages of locked memory */
1262 1263          uint64_t pr_hatpagesize;   /* pagesize of mapping */
1263 1264  } prxmap_t;
1264 1265  .Ed
1265 1266  .Pp
1266 1267  .Sy pr_vaddr
1267 1268  is the virtual address of the mapping within the traced process and
1268 1269  .Sy pr_size
1269 1270  is its size in bytes.
1270 1271  .Sy pr_mapname ,
1271 1272  if it does not contain a null string, contains the name of a file in the
1272 1273  .Sy object
1273 1274  directory (see below) that can be opened read-only to obtain a file descriptor
1274 1275  for the mapped file associated with the mapping.
1275 1276  This enables a debugger to find object file symbol tables without having to
1276 1277  know the real path names of the executable file and shared libraries of
1277 1278  the process.
1278 1279  .Sy pr_offset
1279 1280  is the 64-bit offset within the mapped file (if any) to which the virtual
1280 1281  address is mapped.
1281 1282  .Pp
1282 1283  .Sy pr_mflags
1283 1284  is a bit-mask of protection and attribute flags:
1284 1285  .Bl -tag -width "MA_NORESERVE" -offset left
1285 1286  .It Sy MA_READ
1286 1287  mapping is readable by the traced process.
1287 1288  .It Sy MA_WRITE
1288 1289  mapping is writable by the traced process.
1289 1290  .It Sy MA_EXEC
1290 1291  mapping is executable by the traced process.
1291 1292  .It Sy MA_SHARED
1292 1293  mapping changes are shared by the mapped object.
1293 1294  .It Sy MA_ISM
1294 1295  mapping is intimate shared memory (shared MMU resources)
1295 1296  .It Sy MAP_NORESERVE
1296 1297  mapping does not have swap space reserved (mapped with MAP_NORESERVE)
1297 1298  .It Sy MA_SHM
1298 1299  mapping System V shared memory
1299 1300  .El
1300 1301  .Pp
1301 1302  A contiguous area of the address space having the same underlying mapped object
1302 1303  may appear as multiple mappings due to varying read, write, and execute
1303 1304  attributes.
1304 1305  The underlying mapped object does not change over the range of a
1305 1306  single mapping.
1306 1307  An
1307 1308  .Sy I/O
1308 1309  operation to a mapping marked
1309 1310  .Sy MA_SHARED
1310 1311  fails if applied at a virtual address not corresponding to a valid page in the
1311 1312  underlying mapped object.
1312 1313  A write to a
1313 1314  .Sy MA_SHARED
1314 1315  mapping that is not marked
1315 1316  .Sy MA_WRITE
1316 1317  fails.
1317 1318  Reads and writes to private mappings always succeed.
1318 1319  Reads and writes to unmapped addresses fail.
1319 1320  .Pp
1320 1321  .Sy pr_pagesize
1321 1322  is the page size for the mapping, currently always the system pagesize.
1322 1323  .Pp
1323 1324  .Sy pr_shmid
1324 1325  is the shared memory identifier, if any, for the mapping.
1325 1326  Its value is \-1
1326 1327  if the mapping is not System V shared memory.
1327 1328  See
1328 1329  .Xr shmget 2 .
1329 1330  .Pp
1330 1331  .Sy pr_dev
1331 1332  is the device of the mapped object, if any, for the mapping.
1332 1333  Its value is
1333 1334  .Sy PRNODEV
1334 1335  .Pq \-1
1335 1336  if the mapping does not have a device.
1336 1337  .Pp
1337 1338  .Sy pr_ino
1338 1339  is the inode of the mapped object, if any, for the mapping.
1339 1340  Its contents are only valid if
1340 1341  .Sy pr_dev
1341 1342  is not
1342 1343  .Sy PRNODEV .
1343 1344  .Pp
1344 1345  .Sy pr_rss
1345 1346  is the number of resident pages of memory for the mapping.
1346 1347  The number of resident bytes for the mapping may be determined by multiplying
1347 1348  .Sy pr_rss
1348 1349  by the page size given by
1349 1350  .Sy pr_pagesize .
1350 1351  .Pp
1351 1352  .Sy pr_anon
1352 1353  is the number of resident anonymous memory pages (pages which are
1353 1354  private to this process) for the mapping.
1354 1355  .Pp
1355 1356  .Sy pr_locked
1356 1357  is the number of locked pages for the mapping.
1357 1358  Pages which are locked are always resident in memory.
1358 1359  .Pp
1359 1360  .Sy pr_hatpagesize
1360 1361  is the size, in bytes, of the
1361 1362  .Sy HAT
1362 1363  .Pq Sy MMU
1363 1364  translation for the mapping.
1364 1365  .Sy pr_hatpagesize
1365 1366  may be different than
1366 1367  .Sy pr_pagesize .
1367 1368  The possible values are hardware architecture specific, and
1368 1369  may change over a mapping's lifetime.
1369 1370  .Ss rmap
1370 1371  Contains information about the reserved address ranges of the process.
1371 1372  The file contains an array of
1372 1373  .Sy prmap
1373 1374  structures, as defined above for the
1374 1375  .Sy map
1375 1376  file.
1376 1377  Each structure describes a contiguous virtual address region in the
1377 1378  address space of the traced process that is reserved by the system in the sense
1378 1379  that an
1379 1380  .Xr mmap 2
1380 1381  system call that does not specify
1381 1382  .Sy MAP_FIXED
1382 1383  will not use any part of it for the new mapping.
1383 1384  Examples of such reservations include the address ranges reserved for the
1384 1385  process stack and the individual thread stacks of a multi-threaded process.
1385 1386  .Ss cwd
1386 1387  A symbolic link to the process's current working directory.
1387 1388  See
1388 1389  .Xr chdir 2 .
1389 1390  A
1390 1391  .Xr readlink 2
1391 1392  of
1392 1393  .Pa /proc/ Ns Em pid Ns Pa /cwd
1393 1394  yields a null string.
1394 1395  However, it can be opened, listed, and searched as a directory, and can be the
1395 1396  target of
1396 1397  .Xr chdir 2 .
1397 1398  .Ss root
1398 1399  A symbolic link to the process's root directory.
1399 1400  .Pa /proc/ Ns Em pid Ns Pa /root
1400 1401  can differ from the system root directory if the process or one of its
1401 1402  ancestors executed
1402 1403  .Xr chroot 2
1403 1404  as super user.
1404 1405  It has the same semantics as
1405 1406  .Pa /proc/ Ns Em pid Ns Pa /cwd .
1406 1407  .Ss fd
1407 1408  A directory containing references to the open files of the process.
1408 1409  Each entry is a decimal number corresponding to an open file descriptor in the
1409 1410  process.
1410 1411  .Pp
1411 1412  If an entry refers to a regular file, it can be opened with normal file system
1412 1413  semantics but, to ensure that the controlling process cannot gain greater
1413 1414  access than the controlled process, with no file access modes other than its
1414 1415  read/write open modes in the controlled process.
1415 1416  If an entry refers to a directory, it can be accessed with the same semantics
1416 1417  as
1417 1418  .Pa /proc/ Ns Em pid Ns Pa /cwd .
1418 1419  An attempt to open any other type of entry fails with
1419 1420  .Er EACCES .
1420 1421  .Ss fdinfo
1421 1422  A directory containing information about each of the process's open files.
1422 1423  Each entry is a decimal number corresponding to an open file descriptor in the
1423 1424  process.
1424 1425  Each file contains a
1425 1426  .Sy prfdinfo_t
1426 1427  structure defined as follows:
1427 1428  .Bd -literal -offset 2
1428 1429  typedef struct prfdinfo {
1429 1430      int     pr_fd;          /* file descriptor number */
1430 1431      mode_t  pr_mode;        /* (see st_mode in stat(2)) */
1431 1432      uint64_t pr_ino;        /* inode number */
1432 1433      uint64_t pr_size;       /* file size */
1433 1434      int64_t pr_offset;      /* current offset of file descriptor */
1434 1435      uid_t   pr_uid;         /* owner's user id */
1435 1436      gid_t   pr_gid;         /* owner's group id */
1436 1437      major_t pr_major;       /* major number of device containing file */
1437 1438      minor_t pr_minor;       /* minor number of device containing file */
1438 1439      major_t pr_rmajor;      /* major number (if special file) */
1439 1440      minor_t pr_rminor;      /* minor number (if special file) */
1440 1441      int     pr_fileflags;   /* (see F_GETXFL in fcntl(2)) */
1441 1442      int     pr_fdflags;     /* (see F_GETFD in fcntl(2)) */
1442 1443      short   pr_locktype;    /* (see F_GETLK in fcntl(2)) */
1443 1444      pid_t   pr_lockpid;     /* process holding file lock (see F_GETLK) */
1444 1445      int     pr_locksysid;   /* sysid of locking process (see F_GETLK) */
1445 1446      pid_t   pr_peerpid;     /* peer process (socket, door) */
1446 1447      int     pr_filler[25];  /* reserved for future use */
1447 1448      char    pr_peername[PRFNSZ]; /* peer process name */
1448 1449  #if __STDC_VERSION__ >= 199901L
1449 1450      char    pr_misc[];      /* self describing structures */
1450 1451  #else
1451 1452      char    pr_misc[1];
1452 1453  #endif
1453 1454  } prfdinfo_t;
1454 1455  .Ed
1455 1456  .Pp
1456 1457  The
1457 1458  .Sy pr_misc
1458 1459  element points to a list of additional miscellaneous data items, each of which
1459 1460  has a header of type
1460 1461  .Sy pr_misc_header_t
1461 1462  specifying the size and type, and some data which immediately follow
1462 1463  the header.
1463 1464  .Bd -literal -offset 2
1464 1465  typedef struct pr_misc_header {
1465 1466      uint_t          pr_misc_size;
1466 1467      uint_t          pr_misc_type;
1467 1468  } pr_misc_header_t;
1468 1469  .Ed
1469 1470  .Pp
1470 1471  The
1471 1472  .Sy pr_misc_size
1472 1473  field is the sum of the sizes of the header and the associated data and any
1473 1474  trailing padding bytes which will be set to zero.
1474 1475  The end of the list is indicated by a header with a zero size and a type with
1475 1476  all bits set.
1476 1477  .Pp
1477 1478  The following miscellaneous data types can be present:
1478 1479  .Bl -tag -width "PR_SOCKOPT_TCP_CONGESTION" -offset left
1479 1480  .It Sy PR_PATHNAME
1480 1481  The file descriptor's path in the filesystem.
1481 1482  This is a NUL-terminated sequence of characters.
1482 1483  .It Sy PR_SOCKETNAME
1483 1484  A
1484 1485  .Sy sockaddr
1485 1486  structure representing the local socket name for this file descriptor, as
1486 1487  would be returned by calling
1487 1488  .Fn getsockname
1488 1489  within the process.
1489 1490  .It Sy PR_PEERSOCKNAME
1490 1491  A
1491 1492  .Sy sockaddr
1492 1493  structure representing the peer socket name for this file descriptor, as
1493 1494  would be returned by calling
1494 1495  .Fn getpeername
1495 1496  within the process.
1496 1497  .It Sy PR_SOCKOPTS_BOOL_OPTS
1497 1498  An unsigned integer which has bits set corresponding to options which are
1498 1499  set on the underlying socket.
1499 1500  The following bits may be set:
1500 1501  .Bl -tag -width "PR_SO_PASSIVE_CONNECT"
1501 1502  .It Sy PR_SO_DEBUG
1502 1503  .It Sy PR_SO_REUSEADDR
1503 1504  .It Sy PR_SO_REUSEPORT
1504 1505  .It Sy PR_SO_KEEPALIVE
1505 1506  .It Sy PR_SO_DONTROUTE
1506 1507  .It Sy PR_SO_BROADCAST
1507 1508  .It Sy PR_SO_OOBINLINE
1508 1509  .It Sy PR_SO_DGRAM_ERRIND
1509 1510  .It Sy PR_SO_ALLZONES
1510 1511  .It Sy PR_SO_MAC_EXEMPT
1511 1512  .It Sy PR_SO_EXCLBIND
1512 1513  .It Sy PR_SO_PASSIVE_CONNECT
1513 1514  .It Sy PR_SO_ACCEPTCONN
1514 1515  .It Sy PR_UDP_NAT_T_ENDPOINT
1515 1516  .It Sy PR_SO_VRRP
1516 1517  .It Sy PR_SO_MAC_IMPLICIT
1517 1518  .El
1518 1519  .It Sy PR_SOCKOPT_LINGER
1519 1520  A
1520 1521  .Sy struct linger
1521 1522  as would be returned by calling
1522 1523  .Fn getsockopt SO_LINGER
1523 1524  within the process.
1524 1525  .It Sy PR_SOCKOPT_SNDBUF
1525 1526  The data that would be returned by calling
1526 1527  .Fn getsockopt SO_SNDBUF
1527 1528  within the process.
1528 1529  .It Sy PR_SOCKOPT_RCVBUF
1529 1530  The data that would be returned by calling
1530 1531  .Fn getsockopt SO_RCVBUF
1531 1532  within the process.
1532 1533  .It Sy PR_SOCKOPT_IP_NEXTHOP
1533 1534  The data that would be returned by calling
1534 1535  .Fn getsockopt IPPROTO_IP IP_NEXTHOP
1535 1536  within the process.
1536 1537  .It Sy PR_SOCKOPT_IPV6_NEXTHOP
1537 1538  The data that would be returned by calling
1538 1539  .Fn getsockopt IPPROTO_IPV6 IPV6_NEXTHOP
1539 1540  within the process.
1540 1541  .It Sy PR_SOCKOPT_TYPE
1541 1542  The data that would be returned by calling
1542 1543  .Fn getsockopt SO_TYPE
1543 1544  within the process.
1544 1545  .It Sy PR_SOCKOPT_TCP_CONGESTION
1545 1546  For TCP sockets, the data that would be returned by calling
1546 1547  .Fn getsockopt IPPROTO_TCP TCP_CONGESTION
1547 1548  within the process.
1548 1549  This is a NUL-terminated character array containing the name of the congestion
1549 1550  algorithm in use for the socket.
1550 1551  .It Sy PR_SOCKFILTERS_PRIV
1551 1552  Private data relating to up to the first 32 socket filters pushed on this
1552 1553  descriptor.
1553 1554  .El
1554 1555  .Ss object
1555 1556  A directory containing read-only files with names corresponding to the
1556 1557  .Sy pr_mapname
1557 1558  entries in the
1558 1559  .Sy map
1559 1560  and
1560 1561  .Sy pagedata
1561 1562  files.
1562 1563  Opening such a file yields a file descriptor for the underlying mapped file
1563 1564  associated with an address-space mapping in the process.
1564 1565  The file name
1565 1566  .Pa a.out
1566 1567  appears in the directory as an alias for the process's executable file.
1567 1568  .Pp
1568 1569  The
1569 1570  .Pa object
1570 1571  directory makes it possible for a controlling process to gain
1571 1572  access to the object file and any shared libraries (and consequently the symbol
1572 1573  tables) without having to know the actual path names of the executable files.
1573 1574  .Ss path
1574 1575  A directory containing symbolic links to files opened by the process.
1575 1576  The directory includes one entry for
1576 1577  .Pa cwd
1577 1578  and
1578 1579  .Pa root .
1579 1580  The directory also contains a numerical entry for each file descriptor in the
1580 1581  .Pa fd
1581 1582  directory, and entries matching those in the
1582 1583  .Pa object
1583 1584  directory.
1584 1585  If this information is not available, any attempt to read the contents of the
1585 1586  symbolic link will fail.
1586 1587  This is most common for files that do not exist in the filesystem namespace
1587 1588  (such as
1588 1589  .Sy FIFO Ns s
1589 1590  and sockets), but can also happen for regular files.
1590 1591  For the file descriptor entries, the path may be different from the one
1591 1592  used by the process to open the file.
1592 1593  .Ss pagedata
1593 1594  Opening the page data file enables tracking of address space references and
1594 1595  modifications on a per-page basis.
1595 1596  .Pp
1596 1597  A
1597 1598  .Xr read 2
1598 1599  of the page data file descriptor returns structured page data
1599 1600  and atomically clears the page data maintained for the file by the system.
1600 1601  That is to say, each read returns data collected since the last read; the
1601 1602  first read returns data collected since the file was opened.
1602 1603  When the call completes, the read buffer contains the following structure as
1603 1604  its header and thereafter contains a number of section header structures and
1604 1605  associated byte arrays that must be accessed by walking linearly through the
1605 1606  buffer.
1606 1607  .Bd -literal -offset 2
1607 1608  typedef struct prpageheader {
1608 1609      timestruc_t pr_tstamp; /* real time stamp, time of read() */
1609 1610      ulong_t pr_nmap;       /* number of address space mappings */
1610 1611      ulong_t pr_npage;      /* total number of pages */
1611 1612  } prpageheader_t;
1612 1613  .Ed
1613 1614  .Pp
1614 1615  The header is followed by
1615 1616  .Sy "pr_nmap prasmap"
1616 1617  structures and associated data arrays.
1617 1618  The
1618 1619  .Sy prasmap
1619 1620  structure contains the following elements:
1620 1621  .Bd -literal -offset 2
1621 1622  typedef struct prasmap {
1622 1623      uintptr_t pr_vaddr;        /* virtual address of mapping */
1623 1624      ulong_t pr_npage;          /* number of pages in mapping */
1624 1625      char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1625 1626      offset_t pr_offset;        /* offset into mapped object, if any */
1626 1627      int pr_mflags;             /* protection and attribute flags */
1627 1628      int pr_pagesize;           /* pagesize for this mapping in bytes */
1628 1629      int pr_shmid;              /* SysV shared memory identifier */
1629 1630  } prasmap_t;
1630 1631  .Ed
1631 1632  .Pp
1632 1633  Each section header is followed by
1633 1634  .Sy pr_npage
1634 1635  bytes, one byte for each page in the mapping, plus 0-7 null bytes at the end
1635 1636  so that the next
1636 1637  .Sy prasmap
1637 1638  structure begins on an eight-byte aligned boundary.
1638 1639  Each data byte may contain these flags:
1639 1640  .Bl -tag -width "PG_REFERENCED" -offset 2
1640 1641  .It Sy PG_REFERENCED
1641 1642  page has been referenced.
1642 1643  .It Sy PG_MODIFIED
1643 1644  page has been modified.
1644 1645  .El
1645 1646  .Pp
1646 1647  If the read buffer is not large enough to contain all of the page data, the
1647 1648  read fails with
1648 1649  .Er E2BIG
1649 1650  and the page data is not cleared.
1650 1651  The required size of the read buffer can be determined through
1651 1652  .Xr fstat 2 .
1652 1653  Application of
1653 1654  .Xr lseek 2
1654 1655  to the page data file descriptor is ineffective; every read
1655 1656  starts from the beginning of the file.
1656 1657  Closing the page data file descriptor
1657 1658  terminates the system overhead associated with collecting the data.
1658 1659  .Pp
1659 1660  More than one page data file descriptor for the same process can be opened, up
1660 1661  to a system-imposed limit per traced process.
1661 1662  A read of one does not affect the data being collected by the system for the
1662 1663  others.
1663 1664  An open of the page data file will fail with
1664 1665  .Er ENOMEM
1665 1666  if the system-imposed limit would be exceeded.
1666 1667  .Ss watch
1667 1668  Contains an array of
1668 1669  .Vt prwatch
1669 1670  structures, one for each watched area established by the
1670 1671  .Sy PCWATCH
1671 1672  control operation.
1672 1673  See
1673 1674  .Sx PCWATCH
1674 1675  for details.
1675 1676  .Ss usage
1676 1677  Contains process usage information described by a
1677 1678  .Vt prusage
1678 1679  structure which contains at least the following fields:
1679 1680  .Bd -literal -offset 2
1680 1681  typedef struct prusage {
1681 1682      id_t pr_lwpid;           /* lwp id.  0: process or defunct */
1682 1683      int pr_count;            /* number of contributing lwps */
1683 1684      timestruc_t pr_tstamp;   /* real time stamp, time of read() */
1684 1685      timestruc_t pr_create;   /* process/lwp creation time stamp */
1685 1686      timestruc_t pr_term;     /* process/lwp termination time stamp */
1686 1687      timestruc_t pr_rtime;    /* total lwp real (elapsed) time */
1687 1688      timestruc_t pr_utime;    /* user level CPU time */
1688 1689      timestruc_t pr_stime;    /* system call CPU time */
1689 1690      timestruc_t pr_ttime;    /* other system trap CPU time */
1690 1691      timestruc_t pr_tftime;   /* text page fault sleep time */
1691 1692      timestruc_t pr_dftime;   /* data page fault sleep time */
1692 1693      timestruc_t pr_kftime;   /* kernel page fault sleep time */
1693 1694      timestruc_t pr_ltime;    /* user lock wait sleep time */
1694 1695      timestruc_t pr_slptime;  /* all other sleep time */
1695 1696      timestruc_t pr_wtime;    /* wait-cpu (latency) time */
1696 1697      timestruc_t pr_stoptime; /* stopped time */
1697 1698      ulong_t pr_minf;         /* minor page faults */
1698 1699      ulong_t pr_majf;         /* major page faults */
1699 1700      ulong_t pr_nswap;        /* swaps */
1700 1701      ulong_t pr_inblk;        /* input blocks */
1701 1702      ulong_t pr_oublk;        /* output blocks */
1702 1703      ulong_t pr_msnd;         /* messages sent */
1703 1704      ulong_t pr_mrcv;         /* messages received */
1704 1705      ulong_t pr_sigs;         /* signals received */
1705 1706      ulong_t pr_vctx;         /* voluntary context switches */
1706 1707      ulong_t pr_ictx;         /* involuntary context switches */
1707 1708      ulong_t pr_sysc;         /* system calls */
1708 1709      ulong_t pr_ioch;         /* chars read and written */
1709 1710  } prusage_t;
1710 1711  .Ed
1711 1712  .Pp
1712 1713  Microstate accounting is now continuously enabled.
1713 1714  While this information was
1714 1715  previously an estimate, if microstate accounting were not enabled, the current
1715 1716  information is now never an estimate represents time the process has spent in
1716 1717  various states.
1717 1718  .Ss lstatus
1718 1719  Contains a
1719 1720  .Vt prheader
1720 1721  structure followed by an array of
1721 1722  .Vt lwpstatus
1722 1723  structures, one for each active lwp in the process (see also
1723 1724  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpstatus ,
1724 1725  below).
1725 1726  The
1726 1727  .Vt prheader
1727 1728  structure describes the number and size of the array entries that follow.
1728 1729  .Bd -literal -offset 2
1729 1730  typedef struct prheader {
1730 1731      long pr_nent;        /* number of entries */
1731 1732      size_t pr_entsize;   /* size of each entry, in bytes */
1732 1733  } prheader_t;
1733 1734  .Ed
1734 1735  .Pp
1735 1736  The
1736 1737  .Vt lwpstatus
1737 1738  structure may grow by the addition of elements at the end in future releases
1738 1739  of the system.
1739 1740  Programs must use
1740 1741  .Sy pr_entsize
1741 1742  in the file header to index through the array.
1742 1743  These comments apply to all
1743 1744  .Pa /proc
1744 1745  files that include a
1745 1746  .Vt prheader
1746 1747  structure
1747 1748  .Pf ( Pa lpsinfo
1748 1749  and
1749 1750  .Pa lusage ,
1750 1751  below).
1751 1752  .Ss lpsinfo
1752 1753  Contains a
1753 1754  .Vt prheader
1754 1755  structure followed by an array of
1755 1756  .Vt lwpsinfo
1756 1757  structures, one for eachactive and zombie lwp in the process.
1757 1758  See also
1758 1759  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpsinfo ,
1759 1760  below.
1760 1761  .Ss lusage
1761 1762  Contains a
1762 1763  .Vt prheader
1763 1764  structure followed by an array of
1764 1765  .Vt prusage
1765 1766  structures, one for each active lwp in the process, plus an additional element
1766 1767  at the beginning that contains the summation over all defunct lwps (lwps that
1767 1768  once existed but no longer exist in the process).
1768 1769  Excluding the
1769 1770  .Sy pr_lwpid ,
1770 1771  .Sy pr_tstamp ,
1771 1772  .Sy pr_create ,
1772 1773  and
1773 1774  .Sy pr_term
1774 1775  entries, the entry-by-entry summation over all these structures is the
1775 1776  definition of the process usage information obtained from the
1776 1777  .Pa usage
1777 1778  file. (See also
1778 1779  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpusage ,
1779 1780  below.)
1780 1781  .Ss lwp
1781 1782  A directory containing entries each of which names an active or zombie lwp
1782 1783  within the process.
1783 1784  These entries are themselves directories containing additional files as
1784 1785  described below.
1785 1786  Only the
1786 1787  .Pa lwpsinfo
1787 1788  file exists in the directory of a zombie lwp.
1788 1789  .Sh "STRUCTURE OF" Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid
1789 1790  A given directory
1790 1791  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid
1791 1792  contains the following entries:
1792 1793  .Ss lwpctl
1793 1794  Write-only control file.
1794 1795  The messages written to this file affect the specific
1795 1796  lwp rather than the representative lwp, as is the case for the process's
1796 1797  .Pa ctl
1797 1798  file.
1798 1799  .Ss lwpname
1799 1800  A buffer of
1800 1801  .Dv THREAD_NAME_MAX
1801 1802  bytes representing the LWP name; the buffer is
1802 1803  zero-filled if the thread name is shorter than the buffer.
1803 1804  If no thread name is set, the buffer contains the empty string.
1804 1805  A read with a buffer shorter than
1805 1806  .Dv THREAD_NAME_MAX
1806 1807  bytes is not guaranteed to be NUL-terminated.
1807 1808  Writing to this file will set the LWP name for the specific lwp.
1808 1809  This file may not be present in older operating system versions.
1809 1810  .Dv THREAD_NAME_MAX
1810 1811  may increase in the future; clients should be prepared for this.
1811 1812  .Ss lwpstatus
1812 1813  lwp-specific state information.
1813 1814  This file contains the
1814 1815  .Vt lwpstatus
1815 1816  structure for the specific lwp as described above for the representative lwp in
1816 1817  the process's
1817 1818  .Pa status
1818 1819  file.
1819 1820  .Ss lwpsinfo
1820 1821  lwp-specific
1821 1822  .Xr ps 1
1822 1823  information.
1823 1824  This file contains the
1824 1825  .Vt lwpsinfo
1825 1826  structure for the specific lwp as described above for the representative lwp in
1826 1827  the process's
1827 1828  .Pa psinfo
1828 1829  file.
1829 1830  The
1830 1831  .Pa lwpsinfo
1831 1832  file remains accessible after an lwp becomes a zombie.
1832 1833  .Ss lwpusage
1833 1834  This file contains the
1834 1835  .Vt prusage
1835 1836  structure for the specific lwp as described above for the process's
1836 1837  .Pa usage
1837 1838  file.
1838 1839  .Ss gwindows
1839 1840  This file exists only on SPARC based machines.
1840 1841  If it is non-empty, it contains a
1841 1842  .Vt gwindows_t
1842 1843  structure, defined in
1843 1844  .In sys/regset.h ,
1844 1845  with the values of those SPARC register windows that could not be stored on
1845 1846  the stack when the lwp stopped.
1846 1847  Conditions under which register windows are not stored on the
1847 1848  stack are: the stack pointer refers to nonexistent process memory or the stack
1848 1849  pointer is improperly aligned.
1849 1850  If the lwp is not stopped or if there are no
1850 1851  register windows that could not be stored on the stack, the file is empty (the
1851 1852  usual case).
1852 1853  .Ss xregs
1853 1854  Extra state registers.
1854 1855  The extra state register set is architecture dependent;
1855 1856  this file is empty if the system does not support extra state registers.
1856 1857  If the file is non-empty, it contains an architecture dependent structure of
1857 1858  type
1858 1859  .Vt prxregset_t ,
1859 1860  defined in
1860 1861  .In procfs.h ,
1861 1862  with the values of the lwp's extra state registers.
1862 1863  If the lwp is not stopped, all register values are undefined.
1863 1864  See also the
1864 1865  .Sx PCSXREG
1865 1866  control operation, below.
1866 1867  .Ss asrs
1867 1868  This file exists only for 64-bit SPARC V9 processes.
1868 1869  It contains an
1869 1870  .Vt asrset_t
1870 1871  structure, defined in
1871 1872  .In sys/regset.h ,
1872 1873  containing the values of the lwp's platform-dependent ancillary state registers.
1873 1874  If the lwp is not stopped, all register values are undefined.
1874 1875  See also the
1875 1876  .Sx PCSASRS
1876 1877  control operation, below.
1877 1878  .Ss spymaster
1878 1879  For an agent lwp (see
1879 1880  .Sx PCAGENT ) ,
1880 1881  this file contains a
1881 1882  .Vt psinfo_t
1882 1883  structure that corresponds to the process that created the agent lwp at the
1883 1884  time the agent was created.
1884 1885  This structure is identical to that retrieved via the
1885 1886  .Pa psinfo
1886 1887  file, with one modification: the
1887 1888  .Sy pr_time
1888 1889  field does not correspond to the CPU time for the process, but rather to the

1889 1890  creation time of the agent lwp.
1890 1891  .Ss templates
1891 1892  A directory which contains references to the active templates for the lwp,
1892 1893  named by the contract type.
1893 1894  Changes made to an active template descriptor do
1894 1895  not affect the original template which was activated, though they do affect the
1895 1896  active template.
1896 1897  It is not possible to activate an active template descriptor.
1897 1898  See
1898 1899  .Xr contract 5 .
     1900 +.Sh ARCHITECTURE-SPECIFIC STRUCTURES
     1901 +.Ss x86
     1902 +The x86
     1903 +.Vt prxregset_t
     1904 +structure is opaque and is made up of several different components due
     1905 +to the fact that different x86 processors enumerate different
     1906 +architectural extensions.
     1907 +.Pp
     1908 +The structure begins with a header, the
     1909 +.Vt prxregset_hdr_t ,
     1910 +which is followed by a number of different information sections which
     1911 +describe different possible extended registers.
     1912 +Each of those is covered by a
     1913 +.Vt prxregset_info_t ,
     1914 +and then finally there are different data payloads that represent each
     1915 +extended register.
     1916 +.Pp
     1917 +The number of different informational entries varies from system to
     1918 +system based on the set of architectural features that the system
     1919 +supports and the corresponding OS enablement for them.
     1920 +This structure is built around the idea of the x86
     1921 +.Sy xsave
     1922 +structure.
     1923 +That is, there is a central header which describes a bit-vector of what
     1924 +extended features are present and have valid state.
     1925 +.Pp
     1926 +Each x86 xregs file begins with the
     1927 +.Vt prxregset_hdr_t
     1928 +which looks like:
     1929 +.Bd -literal -offset 2
     1930 +typedef struct prxregset_hdr {
     1931 +        uint32_t        pr_type;
     1932 +        uint32_t        pr_size;
     1933 +        uint32_t        pr_flags;
     1934 +        uint32_t        pr_pad[4];
     1935 +        uint32_t        pr_ninfo;
     1936 +        prxregset_info_t pr_info[];
     1937 +} prxregset_hdr_t;
     1938 +.Ed
     1939 +.Pp
     1940 +The
     1941 +.Fa pr_type
     1942 +member is always set to
     1943 +.Dv PR_TYPE_XSAVE .
     1944 +This is used to indicate the type of file that is present.
     1945 +There may be different file types in the future on x86 so this value
     1946 +should always be checked.
     1947 +If it is not
     1948 +.Dv PR_TYPE_XSAVE
     1949 +then the rest of the structure may look different.
     1950 +The
     1951 +.Fa pr_size
     1952 +member indicates the size in bytes of the overall structure.
     1953 +The
     1954 +.Fa pr_flags
     1955 +and
     1956 +.Fa pr_pad
     1957 +values are currently reserved for future use.
     1958 +They will be set to zero right now when read and must be set to zero when
     1959 +writing the data.
     1960 +The
     1961 +.Fa pr_ninfo
     1962 +member indicates the number of informational items are present in
     1963 +.Fa pr_info.
     1964 +There will be one informational item for each register set that exists.
     1965 +.Pp
     1966 +The
     1967 +.Fa pr_info
     1968 +member points to an array of informational members.
     1969 +These immediately follow the structure, though the
     1970 +.Fa pr_info
     1971 +member may not be available directly if not in an environment compatible with
     1972 +some C99 features.
     1973 +Each
     1974 +.Vt prxregset_info_t
     1975 +structure looks like:
     1976 +.Bd -literal -offset 2
     1977 +typedef struct prxregset_info {
     1978 +        uint32_t pri_type;
     1979 +        uint32_t pri_flags;
     1980 +        uint32_t pri_size;
     1981 +        uint32_t pri_offset;
     1982 +} prxregset_info_t;
     1983 +.Ed
     1984 +.Pp
     1985 +The
     1986 +.Fa pri_type
     1987 +member is used to indicate the type of data and its format that this represents.
     1988 +Types are listed below.
     1989 +The
     1990 +.Fa pri_flags
     1991 +member is used to indicate future extensions or information about these items.
     1992 +Right now, these are all zero.
     1993 +The
     1994 +.Fa pri_size
     1995 +member indicates the size in bytes of the type's data.
     1996 +The
     1997 +.Fa pri_offset
     1998 +member indicates the offset to the start of the data section from the beginning
     1999 +of the xregs file.
     2000 +That is an offset of 0 would be the first byte of the
     2001 +.Vt prxregset_hdr_t .
     2002 +.Pp
     2003 +The following types of structures and their corresponding data structures are
     2004 +currently defined:
     2005 +.Bl -tag -width Ds
     2006 +.It Dv PRX_INFO_XCR - Vt prxregset_xcr_t
     2007 +This structure provides read-only access to understanding the CPU's settings for
     2008 +this thread.
     2009 +In particular, it lets you see what is set in the x86 %xcr0 register which is
     2010 +the extended feature control register and controls what extended features the
     2011 +CPU actually uses.
     2012 +It also contains the x86 extended feature disable MSR which controls features
     2013 +that are ignored.
     2014 +The
     2015 +.Vt prxregset_xcr_t
     2016 +looks like:
     2017 +.Bd -literal -offset -indent
     2018 +typedef struct prxregset_xcr {
     2019 +        uint64_t        prx_xcr_xcr0;
     2020 +        uint64_t        prx_xcr_xfd;
     2021 +        uint64_t        prx_xcr_pad[2];
     2022 +} prxregset_xcr_t;
     2023 +.Ed
     2024 +.Pp
     2025 +When setting the xregs, this entry can be left out.
     2026 +If it is included, it must match the existing entries, otherwise an error will
     2027 +be generated.
     2028 +.It Dv PRX_INFO_XSAVE - Vt prxregset_xsave_t
     2029 +This structure represents the same as the actual Intel xsave structure, which
     2030 +has both the traditional XMM state that comes from the fxsave instruction and
     2031 +then also contains the xsave header itself.
     2032 +The structure varies between 32-bit and 64-bit applications.
     2033 +The structure itself looks like:
     2034 +.Bd -literal
     2035 +typedef struct prxregset_xsave {
     2036 +        uint16_t        prx_fx_fcw;
     2037 +        uint16_t        prx_fx_fsw;
     2038 +        uint16_t        prx_fx_fctw;    /* compressed tag word */
     2039 +        uint16_t        prx_fx_fop;
     2040 +#if defined(__amd64)
     2041 +        uint64_t        prx_fx_rip;
     2042 +        uint64_t        prx_fx_rdp;
     2043 +#else
     2044 +        uint32_t        prx_fx_eip;
     2045 +        uint16_t        prx_fx_cs;
     2046 +        uint16_t        __prx_fx_ign0;
     2047 +        uint32_t        prx_fx_dp;
     2048 +        uint16_t        prx_fx_ds;
     2049 +        uint16_t        __prx_fx_ign1;
     2050 +#endif
     2051 +        uint32_t        prx_fx_mxcsr;
     2052 +        uint32_t        prx_fx_mxcsr_mask;
     2053 +        union {
     2054 +                uint16_t prx_fpr_16[5]; /* 80-bits of x87 state */
     2055 +                u_longlong_t prx_fpr_mmx;       /* 64-bit mmx register */
     2056 +                uint32_t _prx__fpr_pad[4];      /* (pad out to 128-bits) */
     2057 +        } fx_st[8];
     2058 +#if defined(__amd64)
     2059 +        upad128_t       prx_fx_xmm[16]; /* 128-bit registers */
     2060 +        upad128_t       __prx_fx_ign2[6];
     2061 +#else
     2062 +        upad128_t       prx_fx_xmm[8];  /* 128-bit registers */
     2063 +        upad128_t       __prx_fx_ign2[14];
     2064 +#endif
     2065 +        uint64_t        prx_xsh_xstate_bv;
     2066 +        uint64_t        prx_xsh_xcomp_bv;
     2067 +        uint64_t        prx_xsh_reserved[6];
     2068 +} prxregset_xsave_t;
     2069 +.Ed
     2070 +.Pp
     2071 +In the classical fxsave portion of the structure, most of the members follow the
     2072 +same meaning and match their presence in the fpregs file and their use as
     2073 +discussed in the Intel and AMD software developer manuals.
     2074 +The one exception is that when setting the
     2075 +.Fa prx_fx_mxcsr
     2076 +member reserved bits that are set will be masked off and ignored.
     2077 +.Pp
     2078 +The most notable fields to consider here right now are the last few members
     2079 +which are part of the xsave header itself.
     2080 +In particular, the
     2081 +.Fa prx_xsh_xstate_bv
     2082 +component is used to track the actual features whose content are valid.
     2083 +When reading the registers, if a given entry is not valid, the register state
     2084 +will write out the informational entry in its default state.
     2085 +When setting the extended registers, this notes which features will be loaded
     2086 +from their default state
     2087 +.Pq as defined by Intel and AMD's manuals
     2088 +and which will be loaded from the informational entries.
     2089 +If a bit is set in the
     2090 +.Fa prx_xsh_xstate_bv
     2091 +entry, then it must be present as its own informational entry otherwise a write
     2092 +will fail.
     2093 +If an informational entry is present in a write, but not set in the
     2094 +.Fa prx_xsh_xstate_bv
     2095 +then its contents will be ignored.
     2096 +.Pp
     2097 +The xregs format currently does not support any compressed items being specified
     2098 +nor does it specify any, so the
     2099 +.Fa prx_xsh_xcomp_bv
     2100 +member will be always set to zero and it and the reserved members
     2101 +.Fa prx_xsh_reserved
     2102 +must all be left as zero.
     2103 +.It Dv PRX_INFO_YMM - Vt prxregset_ymm_t
     2104 +This structure contains the upper 128-bits of the first 16 %ymm registers
     2105 +.Pq 8 for 32-bit applications .
     2106 +To construct a full vector register, it must be combined with the
     2107 +.Fa prx_fx_xmm
     2108 +member of the
     2109 +.Dv PRX_INFO_XSAVE
     2110 +data.
     2111 +In 32-bit applications, the reserved registers must be written as zero.
     2112 +The structure itself looks like:
     2113 +.Bd -literal -offset 2
     2114 +typedef struct prxregset_ymm {
     2115 +#if defined(__amd64)
     2116 +        upad128_t       prx_ymm[16];
     2117 +#else
     2118 +        upad128_t       prx_ymm[8];
     2119 +        upad128_t       prx_rsvd[8];
     2120 +#endif
     2121 +} prxregset_ymm_t;
     2122 +.Ed
     2123 +.It Dv PRX_INFO_OPMASK - Vt prxregset_opmask_t
     2124 +This structure represents one portion of Intel's AVX-512 state: the 8 64-bit
     2125 +mask registers, %k0 through %k7.
     2126 +The structure looks like:
     2127 +.Bd -literal -offset 2
     2128 +typedef struct prxregset_opmask {
     2129 +        uint64_t        prx_opmask[8];
     2130 +} prxregset_opmask_t;
     2131 +.Ed
     2132 +.It Dv PRX_INFO_ZMM - Vt prxregset_zmm_t
     2133 +This structure represents one portion of Intel's AVX-512 state: the upper
     2134 +256 bits of the 512-bit %zmm0 through %zmm15 registers.
     2135 +Bits 0-127 are found in the
     2136 +.Fa prx_fx_xmm
     2137 +member of the
     2138 +.Dv PRX_INFO_XSAVE
     2139 +data and bits 128-255 are found in the
     2140 +.Fa prx_ymm
     2141 +member of the
     2142 +.Dv PRX_INFO_YMM .
     2143 +32-bit applications only have access to %zmm0 through %zmm7.
     2144 +This structure looks like:
     2145 +.Bd -literal -offset 2
     2146 +typedef struct prxregset_zmm {
     2147 +#if defined(__amd64)
     2148 +        upad256_t       prx_zmm[16];
     2149 +#else
     2150 +        upad256_t       prx_zmm[8];
     2151 +        upad256_t       prx_rsvd[8];
     2152 +#endif
     2153 +} prxregset_zmm_t;
     2154 +.Ed
     2155 +.It Dv PRX_INFO_HI_ZMM - Vt prxregset_hi_zmm_t
     2156 +This structure represents the third portion of Intel's AVX-512 state: the
     2157 +additional 16 512-bit registers that are available to 64-bit applications, but
     2158 +not 32-bit applications.
     2159 +This represents %zmm16 through %zmm31.
     2160 +This structure looks like:
     2161 +.Bd -literal -offset indent
     2162 +typedef struct prxregset_hi_zmm {
     2163 +#if defined(__amd64)
     2164 +        upad512_t       prx_hi_zmm[16];
     2165 +#else
     2166 +        upad512_t       prx_rsvd[16];
     2167 +#endif
     2168 +} prxregset_hi_zmm_t;
     2169 +.Pp
     2170 +Unlike the other lower %zmm registers of %zmm0 through %zmm15, this contains the
     2171 +entire 512-bit register in one spot and there is no need to look at other
     2172 +information items to reconstitute the entire vector.
     2173 +.Ed
     2174 +.Pp
     2175 +When setting the extended registers, at least the
     2176 +.Dv PRX_INFO_XSAVE
     2177 +component must be present.
     2178 +None of the component offsets may overlap with the
     2179 +.Vt prxregset_hdr_t
     2180 +or any of the
     2181 +.Vt prxregset_info_t
     2182 +structures.
     2183 +In the written data file, it is expected that the various structures start with
     2184 +their naturally expected alignment, which is most often 16 bytes
     2185 +.Po
     2186 +that is the value that the C
     2187 +.Fn alignof
     2188 +keyword will return
     2189 +.Pc .
     2190 +The structures that we use are all multiples of 16 bytes to make this easier.
     2191 +The kernel will write out structures with a greater alignment such that the
     2192 +portions of registers are aligned and safely usable with instructions that move
     2193 +aligned integers such as vmovdqu64.
     2194 +.El
1899 2195  .Sh CONTROL MESSAGES
1900 2196  Process state changes are effected through messages written to a process's
1901 2197  .Sy ctl
1902 2198  file or to an individual lwp's
1903 2199  .Sy lwpctl
1904 2200  file.
1905 2201  All control messages consist of a
1906 2202  .Sy long
1907 2203  that names the specific operation followed by
1908 2204  additional data containing the operand, if any.

1909 2205  .Pp
1910 2206  Multiple control messages may be combined in a single
1911 2207  .Xr write 2
1912 2208  (or
1913 2209  .Xr writev 2 )
1914 2210  to a control file, but no partial writes are permitted.
1915 2211  That is, each control message, operation code plus operand, if any, must be
1916 2212  presented in its entirety to the
1917 2213  .Xr write 2
1918 2214  and not in pieces over several system calls.
1919 2215  If a control operation fails, no subsequent operations contained in the same
1920 2216  .Xr write 2
1921 2217  are attempted.
1922 2218  .Pp
1923 2219  Descriptions of the allowable control messages follow.
1924 2220  In all cases, writing a message to a control file for a process or lwp that
1925 2221  has terminated elicits the error
1926 2222  .Er ENOENT .
1927 2223  .Ss PCSTOP PCDSTOP PCWSTOP PCTWSTOP
1928 2224  When applied to the process control file,
1929 2225  .Sy PCSTOP
1930 2226  directs all lwps to stop and waits for them to stop,

1931 2227  .Sy PCDSTOP
1932 2228  directs all lwps to stop without waiting for them to stop, and
1933 2229  .Sy PCWSTOP
1934 2230  simply waits for all lwps to stop.
1935 2231  When applied to an lwp control file,
1936 2232  .Sy PCSTOP
1937 2233  directs the specific lwp to stop and waits until it has stopped,
1938 2234  .Sy PCDSTOP
1939 2235  directs the specific lwp to stop without waiting for it to stop, and
1940 2236  .Sy PCWSTOP
1941      - simply waits for the specific lwp to stop.
     2237 +simply waits for the specific lwp to stop.
1942 2238  When applied to an lwp control file,
1943 2239  .Sy PCSTOP
1944 2240  and
1945 2241  .Sy PCWSTOP
1946 2242  complete when the lwp stops on an event of interest, immediately
1947 2243  if already so stopped; when applied to the process control file, they complete
1948 2244  when every lwp has stopped either on an event of interest or on a
1949 2245  .Sy PR_SUSPENDED
1950 2246  stop.
1951 2247  .Pp

1952 2248  .Sy PCTWSTOP
1953 2249  is identical to
1954 2250  .Sy PCWSTOP
1955 2251  except that it enables the operation to time out, to avoid waiting forever for
1956 2252  a process or lwp that may never stop on an event of interest.
1957 2253  .Sy PCTWSTOP
1958 2254  takes a
1959 2255  .Sy long
1960 2256  operand specifying a number of milliseconds; the wait will terminate
1961 2257  successfully after the specified number of milliseconds even if the process or
1962 2258  lwp has not stopped; a timeout value of zero makes the operation identical to
1963 2259  .Sy PCWSTOP .
1964 2260  .Pp
1965 2261  An

1966 2262  .Dq event of interest
1967 2263  is either a
1968 2264  .Sy PR_REQUESTED
1969 2265  stop or a stop that has been specified in the process's tracing flags (set by
1970 2266  .Sy PCSTRACE ,
1971 2267  .Sy PCSFAULT ,
1972 2268  .Sy PCSENTRY ,
1973 2269  and
1974 2270  .Sy PCSEXIT ) .
1975 2271  .Sy PR_JOBCONTROL
1976      - and
     2272 +and
1977 2273  .Sy PR_SUSPENDED
1978 2274  stops are specifically not events of interest.
1979 2275  (An lwp may stop twice due to a stop signal, first showing
1980 2276  .Sy PR_SIGNALLED
1981 2277  if the signal is traced and again showing
1982 2278  .Sy PR_JOBCONTROL
1983 2279  if the lwp is set running without clearing the signal.)
1984 2280  If
1985 2281  .Sy PCSTOP
1986 2282  or

1987 2283  .Sy PCDSTOP
1988 2284  is applied to an
1989 2285  lwp that is stopped, but not on an event of interest, the stop directive takes
1990 2286  effect when the lwp is restarted by the competing mechanism.
1991 2287  At that time, the lwp enters a
1992 2288  .Sy PR_REQUESTED
1993 2289  stop before executing any user-level code.
1994 2290  .Pp
1995 2291  A write of a control message that blocks is interruptible by a signal so that,
1996 2292  for example, an
1997 2293  .Xr alarm 2
1998 2294  can be set to avoid waiting forever for a
1999 2295  process or lwp that may never stop on an event of interest.
2000 2296  If
2001 2297  .Sy PCSTOP
2002 2298  is interrupted, the lwp stop directives remain in effect even though the
2003 2299  .Xr write 2
2004 2300  returns an error.
2005 2301  (Use of
2006 2302  .Sy PCTWSTOP
2007 2303  with a non-zero timeout is recommended over
2008 2304  .Sy PCWSTOP
2009 2305  with an
2010 2306  .Xr alarm 2 . )
2011 2307  .Pp
2012 2308  A system process (indicated by the
2013 2309  .Sy PR_ISSYS
2014 2310  flag) never executes at user level, has no user-level address space visible
2015 2311  through
2016 2312  .Pa /proc ,
2017 2313  and cannot be stopped.
2018 2314  Applying one of these operations to a system process or any of its
2019 2315  lwps elicits the error
2020 2316  .Er EBUSY .
2021 2317  .Ss PCRUN
2022 2318  Make an lwp runnable again after a stop.
2023 2319  This operation takes a
2024 2320  .Vt long
2025 2321  operand containing zero or more of the following flags:
2026 2322  .Bl -tag -width "PRSABORT" -offset left
2027 2323  .It Sy PRCSIG
2028 2324  clears the current signal, if any (see
2029 2325  .Sx PCCSIG ) .
2030 2326  .It Sy PRCFAULT
2031 2327  clears the current fault, if any (see
2032 2328  .Sx PCCFAULT ) .
2033 2329  .It Sy PRSTEP
2034 2330  directs the lwp to execute a single machine instruction.
2035 2331  On completion of the instruction, a trace trap occurs.
2036 2332  If
2037 2333  .Sy FLTTRACE
2038 2334  is being traced, the lwp stops; otherwise, it is sent
2039 2335  .Sy SIGTRAP .
2040 2336  If
2041 2337  .Sy SIGTRAP
2042 2338  is being traced and is not blocked, the lwp stops.
2043 2339  When the lwp stops on an event of interest,
2044 2340  the single-step directive is cancelled, even if the stop occurs before the
2045 2341  instruction is executed.
2046 2342  This operation requires hardware and operating system
2047 2343  support and may not be implemented on all processors.
2048 2344  It is implemented on SPARC and x86-based machines.
2049 2345  .It Sy PRSABORT
2050 2346  is meaningful only if the lwp is in a
2051 2347  .Sy PR_SYSENTRY
2052 2348  stop or is marked
2053 2349  .Sy PR_ASLEEP ;
2054 2350  it instructs the lwp to abort execution of the system call (see
2055 2351  .Sx PCSENTRY
2056 2352  and
2057 2353  .Sx PCSEXIT ) .
2058 2354  .It Sy PRSTOP
2059 2355  directs the lwp to stop again as soon as possible after resuming execution (see
2060 2356  .Sx PCDSTOP ) .
2061 2357  In particular, if the lwp is stopped on
2062 2358  .Sy PR_SIGNALLED
2063 2359  or
2064 2360  .Sy PR_FAULTED ,
2065 2361  the next stop will show
2066 2362  .Sy PR_REQUESTED ,
2067 2363  no other stop
2068 2364  will have intervened, and the lwp will not have executed any user-level code.
2069 2365  .El
2070 2366  .Pp
2071 2367  When applied to an lwp control file,
2072 2368  .Sy PCRUN
2073 2369  clears any outstanding
2074 2370  directed-stop request and makes the specific lwp runnable.
2075 2371  The operation fails with
2076 2372  .Er EBUSY
2077 2373  if the specific lwp is not stopped on an event of interest or
2078 2374  has not been directed to stop or if the agent lwp exists and this is not the
2079 2375  agent lwp (see
2080 2376  .Sx PCAGENT ) .
2081 2377  .Pp
2082 2378  When applied to the process control file, a representative lwp is chosen for
2083 2379  the operation as described for
2084 2380  .Pa /proc/ Ns Em pid Ns Pa /status .
2085 2381  The operation fails with
2086 2382  .Er EBUSY
2087 2383  if the representative lwp is not stopped on an
2088 2384  event of interest or has not been directed to stop or if the agent lwp exists.
2089 2385  If
2090 2386  .Sy PRSTEP
2091 2387  or
2092 2388  .Sy PRSTOP
2093 2389  was requested, the representative lwp is made
2094 2390  runnable and its outstanding directed-stop request is cleared; otherwise all
2095 2391  outstanding directed-stop requests are cleared and, if it was stopped on an
2096 2392  event of interest, the representative lwp is marked
2097 2393  .Sy PR_REQUESTED .
2098 2394  If, as a consequence, all lwps are in the
2099 2395  .Sy PR_REQUESTED
2100 2396  or
2101 2397  .Sy PR_SUSPENDED
2102 2398  stop state, all lwps showing
2103 2399  .Sy PR_REQUESTED
2104 2400  are made runnable.
2105 2401  .Ss PCSTRACE
2106 2402  Define a set of signals to be traced in the process.
2107 2403  The receipt of one of these signals by an lwp causes the lwp to stop.
2108 2404  The set of signals is defined using an operand
2109 2405  .Sy sigset_t
2110 2406  contained in the control message.
2111 2407  Receipt of
2112 2408  .Sy SIGKILL
2113 2409  cannot be traced; if specified, it is silently ignored.
2114 2410  .Pp
2115 2411  If a signal that is included in an lwp's held signal set (the signal mask) is
2116 2412  sent to the lwp, the signal is not received and does not cause a stop until it
2117 2413  is removed from the held signal set, either by the lwp itself or by setting the
2118 2414  held signal set with
2119 2415  .Sy PCSHOLD .
2120 2416  .Ss PCCSIG
2121 2417  The current signal, if any, is cleared from the specific or representative lwp.
2122 2418  .Ss PCSSIG
2123 2419  The current signal and its associated signal information for the specific or
2124 2420  representative lwp are set according to the contents of the operand
2125 2421  .Vt siginfo
2126 2422  structure (see
2127 2423  .In sys/siginfo.h ) .
2128 2424  If the specified signal number is zero, the current signal is cleared.
2129 2425  The semantics of this operation are different from those of
2130 2426  .Xr kill 2
2131 2427  in that the signal is delivered to the lwp immediately after execution is
2132 2428  resumed (even if it is being blocked) and an additional
2133 2429  .Sy PR_SIGNALLED
2134 2430  stop does not intervene even if the signal is traced.
2135 2431  Setting the current signal to
2136 2432  .Sy SIGKILL
2137 2433  terminates the process immediately.
2138 2434  .Ss PCKILL
2139 2435  If applied to the process control file, a signal is sent to the process with
2140 2436  semantics identical to those of
2141 2437  .Xr kill 2
2142 2438  If applied to an lwp control file, a directed signal is sent to the specific
2143 2439  lwp.
2144 2440  The signal is named in a
2145 2441  .Vt long
2146 2442  operand contained in the message.
2147 2443  Sending
2148 2444  .Sy SIGKILL
2149 2445  terminates the process immediately.
2150 2446  .Ss PCUNKILL
2151 2447  A signal is deleted, that is, it is removed from the set of pending signals.
2152 2448  If applied to the process control file, the signal is deleted from the process's
2153 2449  pending signals.
2154 2450  If applied to an lwp control file, the signal is deleted from
2155 2451  the lwp's pending signals.
2156 2452  The current signal (if any) is unaffected.
2157 2453  The signal is named in a
2158 2454  .Sy long
2159 2455  operand in the control message.
2160 2456  It is an error
2161 2457  .Pq Er EINVAL
2162 2458  to attempt to delete
2163 2459  .Sy SIGKILL .
2164 2460  .Ss PCSHOLD
2165 2461  Set the set of held signals for the specific or representative lwp (signals
2166 2462  whose delivery will be blocked if sent to the lwp).
2167 2463  The set of signals is specified with a
2168 2464  .Vt sigset_t
2169 2465  operand.
2170 2466  .Sy SIGKILL
2171 2467  and
2172 2468  .Sy SIGSTOP
2173 2469  cannot be held; if specified, they are silently ignored.
2174 2470  .Ss PCSFAULT
2175 2471  Define a set of hardware faults to be traced in the process.
2176 2472  On incurring one of these faults, an lwp stops.
2177 2473  The set is defined via the operand
2178 2474  .Vt fltset_t
2179 2475  structure.
2180 2476  Fault names are defined in
2181 2477  .In sys/fault.h
2182 2478  and include the following.
2183 2479  Some of these may not occur on all processors; there may
2184 2480  be processor-specific faults in addition to these.
2185 2481  .Bl -tag -width "FLTACCESS" -offset indent
2186 2482  .It Sy FLTILL
2187 2483  illegal instruction
2188 2484  .It Sy FLTPRIV
2189 2485  privileged instruction
2190 2486  .It Sy FLTBPT
2191 2487  breakpoint trap
2192 2488  .It Sy FLTTRACE
2193 2489  trace trap (single-step)
2194 2490  .It Sy FLTWATCH
2195 2491  watchpoint trap
2196 2492  .It Sy FLTACCESS
2197 2493  memory access fault (bus error)
2198 2494  .It Sy FLTBOUNDS
2199 2495  memory bounds violation
2200 2496  .It Sy FLTIOVF
2201 2497  integer overflow
2202 2498  .It Sy FLTIZDIV
2203 2499  integer zero divide
2204 2500  .It Sy FLTFPE
2205 2501  floating-point exception
2206 2502  .It Sy FLTSTACK
2207 2503  unrecoverable stack fault
2208 2504  .It Sy FLTPAGE
2209 2505  recoverable page fault
2210 2506  .El
2211 2507  .Pp
2212 2508  When not traced, a fault normally results in the posting of a signal to the lwp
2213 2509  that incurred the fault.
2214 2510  If an lwp stops on a fault, the signal is posted to
2215 2511  the lwp when execution is resumed unless the fault is cleared by
2216 2512  .Sy PCCFAULT
2217 2513  or by the
2218 2514  .Sy PRCFAULT
2219 2515  option of
2220 2516  .Sy PCRUN .
2221 2517  .Sy FLTPAGE
2222 2518  is an exception; no signal is posted.
2223 2519  The
2224 2520  .Sy pr_info
2225 2521  field in the
2226 2522  .Vt lwpstatus
2227 2523  structure identifies the signal to be sent and contains machine-specific
2228 2524  information about the fault.
2229 2525  .Ss PCCFAULT
2230 2526  The current fault, if any, is cleared; the associated signal will not be sent
2231 2527  to the specific or representative lwp.
2232 2528  .Ss PCSENTRY PCSEXIT
2233 2529  These control operations instruct the process's lwps to stop on entry to or
2234 2530  exit from specified system calls.
2235 2531  The set of system calls to be traced is defined via an operand
2236 2532  .Vt sysset_t
2237 2533  structure.
2238 2534  .Pp
2239 2535  When entry to a system call is being traced, an lwp stops after having begun
2240 2536  the call to the system but before the system call arguments have been fetched
2241 2537  from the lwp.
2242 2538  When exit from a system call is being traced, an lwp stops on completion of
2243 2539  the system call just prior to checking for signals and returning to user level.
2244 2540  At this point, all return values have been stored into the lwp's registers.
2245 2541  .Pp
2246 2542  If an lwp is stopped on entry to a system call
2247 2543  .Pq Sy PR_SYSENTRY
2248 2544  or when sleeping in an interruptible system call
2249 2545  .Pf ( Sy PR_ASLEEP
2250 2546  is set), it may be instructed to go directly to system call exit by specifying
2251 2547  the
2252 2548  .Sy PRSABORT
2253 2549  flag in a
2254 2550  .Sy PCRUN
2255 2551  control message.
2256 2552  Unless exit from the system call is being traced, the lwp returns to user
2257 2553  level showing
2258 2554  .Er EINTR .
2259 2555  .Ss PCWATCH
2260 2556  Set or clear a watched area in the controlled process from a
2261 2557  .Vt prwatch
2262 2558  structure operand:
2263 2559  .Bd -literal -offset 2
2264 2560  typedef struct prwatch {
2265 2561      uintptr_t pr_vaddr;  /* virtual address of watched area */
2266 2562      size_t pr_size;      /* size of watched area in bytes */
2267 2563      int pr_wflags;       /* watch type flags */
2268 2564  } prwatch_t;
2269 2565  .Ed
2270 2566  .Pp
2271 2567  .Sy pr_vaddr
2272 2568  specifies the virtual address of an area of memory to be watched
2273 2569  in the controlled process.
2274 2570  .Sy pr_size
2275 2571  specifies the size of the area, in bytes.
2276 2572  .Sy pr_wflags
2277 2573  specifies the type of memory access to be monitored as a
2278 2574  bit-mask of the following flags:
2279 2575  .Bl -tag -width "WA_TRAPAFTER" -offset indent
2280 2576  .It Sy WA_READ
2281 2577  read access
2282 2578  .It Sy WA_WRITE
2283 2579  write access
2284 2580  .It Sy WA_EXEC
2285 2581  execution access
2286 2582  .It Sy WA_TRAPAFTER
2287 2583  trap after the instruction completes
2288 2584  .El
2289 2585  .Pp
2290 2586  If
2291 2587  .Sy pr_wflags
2292 2588  is non-empty, a watched area is established for the virtual
2293 2589  address range specified by
2294 2590  .Sy pr_vaddr
2295 2591  and
2296 2592  .Sy pr_size .
2297 2593  If
2298 2594  .Sy pr_wflags
2299 2595  is empty, any previously-established watched area starting at the specified
2300 2596  virtual address is cleared;
2301 2597  .Sy pr_size
2302 2598  is ignored.
2303 2599  .Pp
2304 2600  A watchpoint is triggered when an lwp in the traced process makes a memory
2305 2601  reference that covers at least one byte of a watched area and the memory
2306 2602  reference is as specified in
2307 2603  .Sy pr_wflags .
2308 2604  When an lwp triggers a watchpoint, it incurs a watchpoint trap.
2309 2605  If
2310 2606  .Sy FLTWATCH
2311 2607  is being traced, the lwp stops; otherwise, it is sent a
2312 2608  .Sy SIGTRAP
2313 2609  signal; if
2314 2610  .Sy SIGTRAP
2315 2611  is being traced and is not blocked, the lwp stops.
2316 2612  .Pp
2317 2613  The watchpoint trap occurs before the instruction completes unless
2318 2614  .Sy WA_TRAPAFTER
2319 2615  was specified, in which case it occurs after the instruction completes.
2320 2616  If it occurs before completion, the memory is not modified.
2321 2617  If it occurs after completion, the memory is modified (if the access is a write
2322 2618  access).
2323 2619  .Pp
2324 2620  Physical i/o is an exception for watchpoint traps.
2325 2621  In this instance, there is no guarantee that memory before the watched area
2326 2622  has already been modified (or in the case of
2327 2623  .Sy WA_TRAPAFTER ,
2328 2624  that the memory following the watched area
2329 2625  has not been modified) when the watchpoint trap occurs and the lwp stops.
2330 2626  .Pp
2331 2627  .Sy pr_info
2332 2628  in the
2333 2629  .Vt lwpstatus
2334 2630  structure contains information pertinent to the watchpoint trap.
2335 2631  In particular, the
2336 2632  .Sy si_addr
2337 2633  field contains the
2338 2634  virtual address of the memory reference that triggered the watchpoint, and the
2339 2635  .Sy si_code
2340 2636  field contains one of
2341 2637  .Sy TRAP_RWATCH ,
2342 2638  .Sy TRAP_WWATCH ,
2343 2639  or
2344 2640  .Sy TRAP_XWATCH ,
2345 2641  indicating read, write, or execute access, respectively.
2346 2642  The
2347 2643  .Sy si_trapafter
2348 2644  field is zero unless
2349 2645  .Sy WA_TRAPAFTER
2350 2646  is in effect for this watched area; non-zero indicates that the current
2351 2647  instruction is not the instruction that incurred the watchpoint trap.
2352 2648  The
2353 2649  .Sy si_pc
2354 2650  field contains the virtual address of the instruction that incurred the trap.
2355 2651  .Pp
2356 2652  A watchpoint trap may be triggered while executing a system call that makes
2357 2653  reference to the traced process's memory.
2358 2654  The lwp that is executing the system call incurs the watchpoint trap while
2359 2655  still in the system call.
2360 2656  If it stops as a result, the
2361 2657  .Vt lwpstatus
2362 2658  structure contains the system call number and its arguments.
2363 2659  If the lwp does not stop, or if it is set running again without
2364 2660  clearing the signal or fault, the system call fails with
2365 2661  .Er EFAULT .
2366 2662  If
2367 2663  .Sy WA_TRAPAFTER
2368 2664  was specified, the memory reference will have completed and
2369 2665  the memory will have been modified (if the access was a write access) when the
2370 2666  watchpoint trap occurs.
2371 2667  .Pp
2372 2668  If more than one of
2373 2669  .Sy WA_READ ,
2374 2670  .Sy WA_WRITE ,
2375 2671  and
2376 2672  .Sy WA_EXEC
2377 2673  is specified for a watched area, and a single instruction incurs more than one
2378 2674  of the specified types, only one is reported when the watchpoint trap occurs.
2379 2675  The precedence is
2380 2676  .Sy WA_EXEC ,
2381 2677  .Sy WA_READ ,
2382 2678  .Sy WA_WRITE
2383 2679  .Pf ( Sy WA_EXEC
2384 2680  and
2385 2681  .Sy WA_READ
2386 2682  take precedence over
2387 2683  .Sy WA_WRITE ) ,
2388 2684  unless
2389 2685  .Sy WA_TRAPAFTER
2390 2686  was specified, in which case it is
2391 2687  .Sy WA_WRITE ,
2392 2688  .Sy WA_READ ,
2393 2689  .Sy WA_EXEC
2394 2690  .Pf ( Sy WA_WRITE
2395 2691  takes precedence).
2396 2692  .Pp
2397 2693  .Sy PCWATCH
2398 2694  fails with
2399 2695  .Er EINVAL
2400 2696  if an attempt is made to specify overlapping watched areas or if
2401 2697  .Sy pr_wflags
2402 2698  contains flags other than those specified above.
2403 2699  It fails with
2404 2700  .Er ENOMEM
2405 2701  if an attempt is made to establish more watched areas than the system can
2406 2702  support (the system can support thousands).
2407 2703  .Pp
2408 2704  The child of a
2409 2705  .Xr vfork 2
2410 2706  borrows the parent's address space.
2411 2707  When a
2412 2708  .Xr vfork 2
2413 2709  is executed by a traced process, all watched areas established
2414 2710  for the parent are suspended until the child terminates or performs an
2415 2711  .Xr exec 2 .
2416 2712  Any watched areas established independently in the child are
2417 2713  cancelled when the parent resumes after the child's termination or
2418 2714  .Xr exec 2 .
2419 2715  .Sy PCWATCH
2420 2716  fails with
2421 2717  .Er EBUSY
2422 2718  if applied to the parent of a
2423 2719  .Xr vfork 2
2424 2720  before the child has terminated or performed an
2425 2721  .Xr exec 2 .
2426 2722  The
2427 2723  .Sy PR_VFORKP
2428 2724  flag is set in the
2429 2725  .Sy pstatus
2430 2726  structure for such a parent process.
2431 2727  .Pp
2432 2728  Certain accesses of the traced process's address space by the operating system
2433 2729  are immune to watchpoints.
2434 2730  The initial construction of a signal stack frame when a signal is delivered to
2435 2731  an lwp will not trigger a watchpoint trap even if the new frame covers watched
2436 2732  areas of the stack.
2437 2733  Once the signal handler is entered, watchpoint traps occur normally.
2438 2734  On SPARC based machines, register window overflow and underflow will not
2439 2735  trigger watchpoint traps, even if the register window save areas cover watched
2440 2736  areas of the stack.
2441 2737  .Pp
2442 2738  Watched areas are not inherited by child processes, even if the traced
2443 2739  process's inherit-on-fork mode,
2444 2740  .Sy PR_FORK ,
2445 2741  is set (see
2446 2742  .Sy PCSET ,
2447 2743  below).
2448 2744  All watched areas are cancelled when the traced process performs a successful
2449 2745  .Xr exec 2 .
2450 2746  .Ss PCSET PCUNSET
2451 2747  .Sy PCSET
2452 2748  sets one or more modes of operation for the traced process.
2453 2749  .Sy PCUNSET
2454 2750  unsets these modes.
2455 2751  The modes to be set or unset are specified by flags in an operand
2456 2752  .Sy long
2457 2753  in the control message:
2458 2754  .Bl -tag -offset left -width "PR_MSFORK"
2459 2755  .It Sy PR_FORK
2460 2756  (inherit-on-fork): When set, the process's tracing flags and its
2461 2757  inherit-on-fork mode are inherited by the child of a
2462 2758  .Xr fork 2 ,
2463 2759  .Xr fork1 2 ,
2464 2760  or
2465 2761  .Xr vfork 2 .
2466 2762  When unset, child processes start with all tracing flags cleared.
2467 2763  .It Sy PR_RLC
2468 2764  (run-on-last-close): When set and the last writable
2469 2765  .Pa /proc
2470 2766  file descriptor referring to the traced process or any of its lwps is closed,
2471 2767  all of the process's tracing flags and watched areas are cleared, any
2472 2768  outstanding stop directives are canceled, and if any lwps are stopped on
2473 2769  events of interest, they are set running as though
2474 2770  .Sy PCRUN
2475 2771  had been applied to them.
2476 2772  When unset, the process's tracing flags and watched areas are retained and
2477 2773  lwps are not set running on last close.
2478 2774  .It Sy PR_KLC
2479 2775  (kill-on-last-close): When set and the last writable
2480 2776  .Pa /proc
2481 2777  file descriptor referring to the traced process or any of its lwps is closed,
2482 2778  the process is terminated with
2483 2779  .Sy SIGKILL .
2484 2780  .It Sy PR_ASYNC
2485 2781  (asynchronous-stop): When set, a stop on an event of interest by one lwp does
2486 2782  not directly affect any other lwp in the process.
2487 2783  When unset and an lwp stops on an event of interest other than
2488 2784  .Sy PR_REQUESTED ,
2489 2785  all other lwps in the process are directed to stop.
2490 2786  .It Sy PR_MSACCT
2491 2787  (microstate accounting): Microstate accounting is now continuously enabled.
2492 2788  This flag is deprecated and no longer has any effect upon microstate
2493 2789  accounting.
2494 2790  Applications may toggle this flag; however, microstate accounting
2495 2791  will remain enabled regardless.
2496 2792  .It Sy PR_MSFORK
2497 2793  (inherit microstate accounting): All processes now inherit microstate
2498 2794  accounting, as it is continuously enabled.
2499 2795  This flag has been deprecated and its use no longer has any effect upon the
2500 2796  behavior of microstate accounting.
2501 2797  .It Sy PR_BPTADJ
2502 2798  (breakpoint trap pc adjustment): On x86-based machines, a breakpoint trap
2503 2799  leaves the program counter (the
2504 2800  .Sy EIP )
2505 2801  referring to the breakpointed instruction plus one byte.
2506 2802  When
2507 2803  .Sy PR_BPTADJ
2508 2804  is set, the system will adjust the program counter back to the location of the
2509 2805  breakpointed instruction when the lwp stops on a breakpoint.
2510 2806  This flag has no effect on SPARC based machines, where breakpoint traps leave
2511 2807  the program counter referring to the breakpointed instruction.
2512 2808  .It Sy PR_PTRACE
2513 2809  (ptrace-compatibility): When set, a stop on an event of interest by the traced
2514 2810  process is reported to the parent of the traced process by
2515 2811  .Xr wait 3C ,
2516 2812  .Sy SIGTRAP
2517 2813  is sent to the traced process when it executes a successful
2518 2814  .Xr exec 2 ,
2519 2815  setuid/setgid flags are not honored for execs performed by the
2520 2816  traced process, any exec of an object file that the traced process cannot read
2521 2817  fails, and the process dies when its parent dies.
2522 2818  This mode is deprecated; it is provided only to allow
2523 2819  .Xr ptrace 3C
2524 2820  to be implemented as a library function using
2525 2821  .Pa /proc .
2526 2822  .El
2527 2823  .Pp
2528 2824  It is an error
2529 2825  .Pq Er EINVAL
2530 2826  to specify flags other than those described above
2531 2827  or to apply these operations to a system process.
2532 2828  The current modes are reported in the
2533 2829  .Sy pr_flags
2534 2830  field of
2535 2831  .Pa /proc/ Ns Em pid Ns Pa /status
2536 2832  and
2537 2833  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwp Ns Pa /lwpstatus .
2538 2834  .Ss PCSREG
2539 2835  Set the general registers for the specific or representative lwp according to
2540 2836  the operand
2541 2837  .Vt prgregset_t
2542 2838  structure.
2543 2839  .Pp
2544 2840  On SPARC based systems, only the condition-code bits of the processor-status
2545 2841  register (R_PSR) of SPARC V8 (32-bit) processes can be modified by
2546 2842  .Sy PCSREG .
2547 2843  Other privileged registers cannot be modified at all.
2548 2844  .Pp
2549 2845  On x86-based systems, only certain bits of the flags register (EFL) can be
2550 2846  modified by
2551 2847  .Sy PCSREG :
2552 2848  these include the condition codes, direction-bit, and overflow-bit.
2553 2849  .Pp
2554 2850  .Sy PCSREG
2555 2851  fails with
2556 2852  .Er EBUSY
2557 2853  if the lwp is not stopped on an event of interest.
2558 2854  .Ss PCSVADDR
2559 2855  Set the address at which execution will resume for the specific or
2560 2856  representative lwp from the operand
2561 2857  .Vt long .
2562 2858  On SPARC based systems, both %pc and %npc are set, with %npc set to the
2563 2859  instruction following the virtual address.
2564 2860  On x86-based systems, only %eip is set.
2565 2861  .Sy PCSVADDR
2566 2862  fails with
2567 2863  .Er EBUSY
2568 2864  if the lwp is not stopped on an event of interest.
2569 2865  .Ss PCSFPREG
2570 2866  Set the floating-point registers for the specific or representative lwp
2571 2867  according to the operand
2572 2868  .Vt prfpregset_t
2573 2869  structure.
2574 2870  An error
2575 2871  .Pq Er EINVAL
2576 2872  is returned if the system does not support floating-point operations (no
2577 2873  floating-point hardware and the system does not emulate floating-point machine
2578 2874  instructions).
2579 2875  .Sy PCSFPREG

2580 2876  fails with
2581 2877  .Er EBUSY
2582 2878  if the lwp is not stopped on an event of interest.
2583 2879  .Ss PCSXREG
2584 2880  Set the extra state registers for the specific or representative lwp according
2585 2881  to the architecture-dependent operand
2586 2882  .Vt prxregset_t
2587 2883  structure.
2588 2884  An error
2589 2885  .Pq Er EINVAL
2590      -is returned if the system does not support extra state registers.
     2886 +is returned if the system does not support extra state registers or the register
     2887 +state is invalid.
2591 2888  .Sy PCSXREG
2592 2889  fails with
2593 2890  .Er EBUSY
2594 2891  if the lwp is not stopped on an event of interest.
2595 2892  .Ss PCSASRS
2596 2893  Set the ancillary state registers for the specific or representative lwp
2597 2894  according to the SPARC V9 platform-dependent operand
2598 2895  .Vt asrset_t
2599 2896  structure.
2600 2897  An error

2601 2898  .Pq Er EINVAL
2602 2899  is returned if either the target process or the
2603 2900  controlling process is not a 64-bit SPARC V9 process.
2604 2901  Most of the ancillary state registers are privileged registers that cannot be
2605 2902  modified.
2606 2903  Only those that can be modified are set; all others are silently ignored.
2607 2904  .Sy PCSASRS
2608 2905  fails with
2609 2906  .Er EBUSY
2610 2907  if the lwp is not stopped on an event of interest.
2611 2908  .Ss PCAGENT
2612 2909  Create an agent lwp in the controlled process with register values from the
2613 2910  operand
2614 2911  .Vt prgregset_t
2615 2912  structure (see
2616 2913  .Sy PCSREG ,
2617 2914  above).
2618 2915  The agent lwp is created in the stopped state showing
2619 2916  .Sy PR_REQUESTED
2620 2917  and with its held signal set (the signal mask) having all signals except
2621 2918  .Sy SIGKILL
2622 2919  and
2623 2920  .Sy SIGSTOP
2624 2921  blocked.
2625 2922  .Pp
2626 2923  The
2627 2924  .Sy PCAGENT
2628 2925  operation fails with
2629 2926  .Er EBUSY
2630 2927  unless the process is fully stopped via
2631 2928  .Pa /proc ,
2632 2929  that is, unless all of the lwps in the process are
2633 2930  stopped either on events of interest or on
2634 2931  .Sy PR_SUSPENDED ,
2635 2932  or are stopped on
2636 2933  .Sy PR_JOBCONTROL
2637 2934  and have been directed to stop via
2638 2935  .Sy PCDSTOP .
2639 2936  It fails with
2640 2937  .Er EBUSY
2641 2938  if an agent lwp already exists.
2642 2939  It fails with
2643 2940  .Er ENOMEM
2644 2941  if system resources for creating new lwps have been exhausted.
2645 2942  .Pp
2646 2943  Any
2647 2944  .Sy PCRUN
2648 2945  operation applied to the process control file or to the control
2649 2946  file of an lwp other than the agent lwp fails with
2650 2947  .Er EBUSY
2651 2948  as long as the agent lwp exists.
2652 2949  The agent lwp must be caused to terminate by executing the
2653 2950  .Sy SYS_lwp_exit
2654 2951  system call trap before the process can be restarted.
2655 2952  .Pp
2656 2953  Once the agent lwp is created, its lwp-ID can be found by reading the process
2657 2954  status file.
2658 2955  To facilitate opening the agent lwp's control and status files,
2659 2956  the directory name
2660 2957  .Pa /proc/ Ns Em pid Ns Pa /lwp/agent
2661 2958  is accepted for lookup operations as an invisible alias for
2662 2959  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid ,
2663 2960  .Em lwpid
2664 2961  being the lwp-ID of the agent lwp (invisible in the sense that the name
2665 2962  .Dq agent
2666 2963  does not appear in a directory listing of
2667 2964  .Pa /proc/ Ns Em pid Ns Pa /lwp
2668 2965  obtained from
2669 2966  .Xr ls 1 ,
2670 2967  .Xr getdents 2 ,
2671 2968  or
2672 2969  .Xr readdir 3C .
2673 2970  .Pp
2674 2971  The purpose of the agent lwp is to perform operations in the controlled process
2675 2972  on behalf of the controlling process: to gather information not directly
2676 2973  available via
2677 2974  .Pa /proc
2678 2975  files, or in general to make the process change state
2679 2976  in ways not directly available via
2680 2977  .Pa /proc
2681 2978  control operations.
2682 2979  To make use of an agent lwp, the controlling process must be capable of making
2683 2980  it execute system calls (specifically, the
2684 2981  .Sy SYS_lwp_exit
2685 2982  system call trap).
2686 2983  The register values given to the agent lwp on creation are typically the
2687 2984  registers of the representative lwp, so that the agent lwp can use its stack.
2688 2985  .Pp
2689 2986  If the controlling process neglects to force the agent lwp to execute the
2690 2987  .Sy SYS_lwp_exit
2691 2988  system call (due to either logic error or fatal failure on
2692 2989  the part of the controlling process), the agent lwp will remain in the target
2693 2990  process.
2694 2991  For purposes of being able to debug these otherwise rogue agents,
2695 2992  information as to the creator of the agent lwp is reflected in that lwp's
2696 2993  .Pa spymaster
2697 2994  file in
2698 2995  .Pa /proc .
2699 2996  Should the target process generate a core
2700 2997  dump with the agent lwp in place, this information will be available via the
2701 2998  .Sy NT_SPYMASTER
2702 2999  note in the core file (see
2703 3000  .Xr core 5 ) .
2704 3001  .Pp
2705 3002  The agent lwp is not allowed to execute any variation of the
2706 3003  .Sy SYS_fork
2707 3004  or
2708 3005  .Sy SYS_exec
2709 3006  system call traps.
2710 3007  Attempts to do so yield
2711 3008  .Er ENOTSUP
2712 3009  to the agent lwp.
2713 3010  .Pp
2714 3011  Symbolic constants for system call trap numbers like
2715 3012  .Sy SYS_lwp_exit
2716 3013  and
2717 3014  .Sy SYS_lwp_create
2718 3015  can be found in the header file
2719 3016  .In sys/syscall.h .
2720 3017  .Ss PCREAD PCWRITE
2721 3018  Read or write the target process's address space via a
2722 3019  .Vt priovec
2723 3020  structure operand:
2724 3021  .Bd -literal -offset 2
2725 3022  typedef struct priovec {
2726 3023      void *pio_base;      /* buffer in controlling process */
2727 3024      size_t pio_len;      /* size of read/write request in bytes */
2728 3025      off_t pio_offset;    /* virtual address in target process */
2729 3026  } priovec_t;
2730 3027  .Ed
2731 3028  .Pp
2732 3029  These operations have the same effect as
2733 3030  .Xr pread 2
2734 3031  and
2735 3032  .Xr pwrite 2 ,
2736 3033  respectively, of the target process's address space file.
2737 3034  The difference is that more than one
2738 3035  .Sy PCREAD
2739 3036  or
2740 3037  .Sy PCWRITE
2741 3038  control operation can be
2742 3039  written to the control file at once, and they can be interspersed with other
2743 3040  control operations in a single write to the control file.
2744 3041  This is useful, for example, when planting many breakpoint instructions in
2745 3042  the process's address space, or when stepping over a breakpointed instruction.
2746 3043  Unlike
2747 3044  .Xr pread 2
2748 3045  and
2749 3046  .Xr pwrite 2 ,
2750 3047  no provision is made for partial reads or writes; if the
2751 3048  operation cannot be performed completely, it fails with
2752 3049  .Er EIO .
2753 3050  .Ss PCNICE
2754 3051  The traced process's
2755 3052  .Xr nice 2
2756 3053  value is incremented by the amount in the
2757 3054  operand
2758 3055  .Vt long .
2759 3056  Only a process with the
2760 3057  .Brq Sy PRIV_PROC_PRIOCNTL
2761 3058  privilege asserted in its effective set can better a process's priority in this
2762 3059  way, but any user may lower the priority.
2763 3060  This operation is not meaningful for all scheduling classes.
2764 3061  .Ss PCSCRED
2765 3062  Set the target process credentials to the values contained in the
2766 3063  .Vt prcred_t
2767 3064  structure operand (see
2768 3065  .Pa /proc/ Ns Em pid Ns Pa /cred ) .
2769 3066  The
2770 3067  effective, real, and saved user-IDs and group-IDs of the target process are
2771 3068  set.
2772 3069  The target process's supplementary groups are not changed; the
2773 3070  .Sy pr_ngroups
2774 3071  and
2775 3072  .Sy pr_groups
2776 3073  members of the structure operand are ignored.
2777 3074  Only the privileged processes can perform this operation; for all
2778 3075  others it fails with
2779 3076  .Er EPERM .
2780 3077  .Ss PCSCREDX
2781 3078  Operates like
2782 3079  .Sy PCSCRED
2783 3080  but also sets the supplementary groups; the length
2784 3081  of the data written with this control operation should be "sizeof
2785 3082  .Pq Vt prcred_t
2786 3083  + sizeof
2787 3084  .Pq Vt gid_t
2788 3085  * (#groups - 1)".
2789 3086  .Ss PCSPRIV
2790 3087  Set the target process privilege to the values contained in the
2791 3088  .Vt prpriv_t
2792 3089  operand (see
2793 3090  .Pa /proc/pid/priv ) .
2794 3091  The effective, permitted, inheritable, and
2795 3092  limit sets are all changed.
2796 3093  Privilege flags can also be set.
2797 3094  The process is made privilege aware unless it can relinquish privilege awareness.
2798 3095  See
2799 3096  .Xr privileges 7 .
2800 3097  .Pp
2801 3098  The limit set of the target process cannot be grown.
2802 3099  The other privilege sets must be subsets of the intersection of the effective set
2803 3100  of the calling process with the new limit set of the target process or subsets of
2804 3101  the original values of the sets in the target process.
2805 3102  .Pp
2806 3103  If any of the above restrictions are not met,
2807 3104  .Er EPERM
2808 3105  is returned.
2809 3106  If the structure written is improperly formatted,
2810 3107  .Er EINVAL
2811 3108  is returned.
2812 3109  .Sh PROGRAMMING NOTES
2813 3110  For security reasons, except for the
2814 3111  .Sy psinfo ,
2815 3112  .Sy usage ,
2816 3113  .Sy lpsinfo ,
2817 3114  .Sy lusage ,
2818 3115  .Sy lwpsinfo ,
2819 3116  and
2820 3117  .Sy lwpusage
2821 3118  files, which are world-readable, and except for privileged processes, an open
2822 3119  of a
2823 3120  .Pa /proc
2824 3121  file fails unless both the user-ID and group-ID of the caller match those of
2825 3122  the traced process and the process's object file is readable by the caller.
2826 3123  The effective set of the caller is a superset of both the inheritable and the
2827 3124  permitted set of the target process.
2828 3125  The limit set of the caller is a superset of the limit set of the target
2829 3126  process.
2830 3127  Except for the world-readable files just mentioned, files corresponding to
2831 3128  setuid and setgid processes can be opened only by the appropriately privileged
2832 3129  process.
2833 3130  .Pp
2834 3131  A process that is missing the basic privilege
2835 3132  .Brq Sy PRIV_PROC_INFO
2836 3133  cannot see any processes under
2837 3134  .Pa /proc
2838 3135  that it cannot send a signal to.
2839 3136  .Pp
2840 3137  A process that has
2841 3138  .Brq Sy PRIV_PROC_OWNER
2842 3139  asserted in its effective set can open any file for reading.
2843 3140  To manipulate or control a process, the controlling process must have at least
2844 3141  as many privileges in its effective set as the target process has in its
2845 3142  effective, inheritable, and permitted sets.
2846 3143  The limit set of the controlling process must be a superset of the limit set
2847 3144  of the target process.
2848 3145  Additional restrictions apply if any of the uids of the target process are 0.
2849 3146  See
2850 3147  .Xr privileges 7 .
2851 3148  .Pp
2852 3149  Even if held by a privileged process, an open process or lwp file descriptor
2853 3150  (other than file descriptors for the world-readable files) becomes invalid if
2854 3151  the traced process performs an
2855 3152  .Xr exec 2
2856 3153  of a setuid/setgid object file or
2857 3154  an object file that the traced process cannot read.
2858 3155  Any operation performed on an invalid file descriptor, except
2859 3156  .Xr close 2 ,
2860 3157  fails with
2861 3158  .Er EAGAIN .
2862 3159  In this situation, if any tracing flags are set and the process or any lwp
2863 3160  file descriptor is open for writing, the process will have been directed to
2864 3161  stop and its run-on-last-close flag will have been set (see
2865 3162  .Sx PCSET ) .
2866 3163  This enables a controlling process (if it has permission) to reopen the
2867 3164  .Pa /proc
2868 3165  files to get new valid file descriptors, close the invalid file descriptors,
2869 3166  unset the run-on-last-close flag (if desired), and proceed.
2870 3167  Just closing the invalid file descriptors causes the traced process to resume
2871 3168  execution with all tracing flags cleared.
2872 3169  Any process not currently open for writing via
2873 3170  .Pa /proc ,
2874 3171  but that has left-over tracing flags from a previous open, and that executes
2875 3172  a setuid/setgid or unreadable object file, will not be stopped but will have
2876 3173  all its tracing flags cleared.
2877 3174  .Pp
2878 3175  To wait for one or more of a set of processes or lwps to stop or terminate,
2879 3176  .Pa /proc
2880 3177  file descriptors (other than those obtained by opening the
2881 3178  .Pa cwd
2882 3179  or
2883 3180  .Pa root
2884 3181  directories or by opening files in the
2885 3182  .Pa fd
2886 3183  or
2887 3184  .Pa object
2888 3185  directories) can be used in a
2889 3186  .Xr poll 2
2890 3187  system call.
2891 3188  When requested and returned, either of the polling events
2892 3189  .Sy POLLPRI
2893 3190  or
2894 3191  .Sy POLLWRNORM
2895 3192  indicates that the process or lwp stopped on an event of
2896 3193  interest.
2897 3194  Although they cannot be requested, the polling events
2898 3195  .Sy POLLHUP ,
2899 3196  .Sy POLLERR ,
2900 3197  and
2901 3198  .Sy POLLNVAL
2902 3199  may be returned.
2903 3200  .Sy POLLHUP
2904 3201  indicates that the process or lwp has terminated.
2905 3202  .Sy POLLERR
2906 3203  indicates that the file descriptor has become invalid.
2907 3204  .Sy POLLNVAL
2908 3205  is returned immediately if
2909 3206  .Sy POLLPRI
2910 3207  or
2911 3208  .Sy POLLWRNORM
2912 3209  is requested on a file descriptor referring to a system process (see
2913 3210  .Sx  PCSTOP ) .
2914 3211  The requested events may be empty to wait simply for termination.
2915 3212  .Sh FILES
2916 3213  .Bl -tag -compact -width Ds
2917 3214  .It Pa /proc
2918 3215  directory (list of processes)
2919 3216  .It Pa /proc/ Ns Em pid
2920 3217  specific process directory
2921 3218  .It Pa /proc/self
2922 3219  alias for a process's own directory
2923 3220  .It Pa /proc/ Ns Em pid Ns Pa /as
2924 3221  address space file
2925 3222  .It Pa /proc/ Ns Em pid Ns Pa /ctl
2926 3223  process control file
2927 3224  .It Pa /proc/ Ns Em pid Ns Pa /status
2928 3225  process status
2929 3226  .It Pa /proc/ Ns Em pid Ns Pa /lstatus
2930 3227  array of lwp status structs
2931 3228  .It Pa /proc/ Ns Em pid Ns Pa /psinfo
2932 3229  process
2933 3230  .Xr ps 1
2934 3231  info
2935 3232  .It Pa /proc/ Ns Em pid Ns Pa /lpsinfo
2936 3233  array of lwp
2937 3234  .Xr ps 1
2938 3235  info structs
2939 3236  .It Pa /proc/ Ns Em pid Ns Pa /map
2940 3237  address space map
2941 3238  .It Pa /proc/ Ns Em pid Ns Pa /xmap
2942 3239  extended address space map
2943 3240  .It Pa /proc/ Ns Em pid Ns Pa /rmap
2944 3241  reserved address map
2945 3242  .It Pa /proc/ Ns Em pid Ns Pa /cred
2946 3243  process credentials
2947 3244  .It Pa /proc/ Ns Em pid Ns Pa /priv
2948 3245  process privileges
2949 3246  .It Pa /proc/ Ns Em pid Ns Pa /sigact
2950 3247  process signal actions
2951 3248  .It Pa /proc/ Ns Em pid Ns Pa /auxv
2952 3249  process aux vector
2953 3250  .It Pa /proc/ Ns Em pid Ns Pa /argv
2954 3251  process argument vector
2955 3252  .It Pa /proc/ Ns Em pid Ns Pa /ldt
2956 3253  process
2957 3254  .Sy LDT
2958 3255  (x86 only)
2959 3256  .It Pa /proc/ Ns Em pid Ns Pa /usage
2960 3257  process usage
2961 3258  .It Pa /proc/ Ns Em pid Ns Pa /lusage
2962 3259  array of lwp usage structs
2963 3260  .It Pa /proc/ Ns Em pid Ns Pa /path
2964 3261  symbolic links to process open files
2965 3262  .It Pa /proc/ Ns Em pid Ns Pa /pagedata
2966 3263  process page data
2967 3264  .It Pa /proc/ Ns Em pid Ns Pa /watch
2968 3265  active watchpoints
2969 3266  .It Pa /proc/ Ns Em pid Ns Pa /cwd
2970 3267  alias for the current working directory
2971 3268  .It Pa /proc/ Ns Em pid Ns Pa /root
2972 3269  alias for the root directory
2973 3270  .It Pa /proc/ Ns Em pid Ns Pa /fd
2974 3271  directory (list of open files)
2975 3272  .It Pa /proc/ Ns Em pid Ns Pa /fd/*
2976 3273  aliases for process's open files
2977 3274  .It Pa /proc/ Ns Em pid Ns Pa /object
2978 3275  directory (list of mapped files)
2979 3276  .It Pa /proc/ Ns Em pid Ns Pa /object/a.out
2980 3277  alias for process's executable file
2981 3278  .It Pa /proc/ Ns Em pid Ns Pa /object/*
2982 3279  aliases for other mapped files
2983 3280  .It Pa /proc/ Ns Em pid Ns Pa /lwp
2984 3281  directory (list of lwps)
2985 3282  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid
2986 3283  specific lwp directory
2987 3284  .It Pa /proc/ Ns Em pid Ns Pa /lwp/agent
2988 3285  alias for the agent lwp directory
2989 3286  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpctl
2990 3287  lwp control file
2991 3288  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpstatus
2992 3289  lwp status
2993 3290  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpsinfo
2994 3291  lwp
2995 3292  .Xr ps 1
2996 3293  info
2997 3294  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpusage
2998 3295  lwp usage
2999 3296  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /gwindows
3000 3297  register windows (SPARC only)
3001 3298  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /xregs
3002 3299  extra state registers
3003 3300  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /asrs
3004 3301  ancillary state registers (SPARC V9 only)
3005 3302  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /spymaster
3006 3303  For an agent LWP, the controlling process
3007 3304  .El
3008 3305  .Sh DIAGNOSTICS
3009 3306  Errors that can occur in addition to the errors normally associated with file
3010 3307  system access:
3011 3308  .Bl -tag -width "EOVERFLOW" -offset left
3012 3309  .It Er E2BIG
3013 3310  Data to be returned in a
3014 3311  .Xr read 2
3015 3312  of the page data file exceeds the size of the read buffer provided by the
3016 3313  caller.
3017 3314  .It Er EACCES
3018 3315  An attempt was made to examine a process that ran under a different uid than
3019 3316  the controlling process and
3020 3317  .Brq Sy PRIV_PROC_OWNER
3021 3318  was not asserted in the effective set.
3022 3319  .It Er EAGAIN
3023 3320  The traced process has performed an
3024 3321  .Xr exec 2
3025 3322  of a setuid/setgid object
3026 3323  file or of an object file that it cannot read; all further operations on the
3027 3324  process or lwp file descriptor (except
3028 3325  .Xr close 2 )
3029 3326  elicit this error.
3030 3327  .It Er EBUSY
3031 3328  .Sy PCSTOP ,
3032 3329  .Sy PCDSTOP ,
3033 3330  .Sy PCWSTOP , or
3034 3331  .Sy PCTWSTOP
3035 3332  was applied to a system process; an exclusive
3036 3333  .Xr open 2
3037 3334  was attempted on a
3038 3335  .Pa /proc
3039 3336  file for a process already open for writing;
3040 3337  .Sy PCRUN ,
3041 3338  .Sy PCSREG ,
3042 3339  .Sy PCSVADDR ,
3043 3340  .Sy PCSFPREG ,
3044 3341  or
3045 3342  .Sy PCSXREG
3046 3343  was applied to a process or
3047 3344  lwp not stopped on an event of interest; an attempt was made to mount
3048 3345  .Pa /proc
3049 3346  when it was already mounted;
3050 3347  .Sy PCAGENT
3051 3348  was applied to a process
3052 3349  that was not fully stopped or that already had an agent lwp.
3053 3350  .It Er EINVAL
3054 3351  In general, this means that some invalid argument was supplied to a system
3055 3352  call.
3056 3353  A non-exhaustive list of conditions eliciting this error includes: a
3057 3354  control message operation code is undefined; an out-of-range signal number was
3058 3355  specified with
3059 3356  .Sy PCSSIG ,
3060 3357  .Sy PCKILL ,
3061 3358  or
3062 3359  .Sy PCUNKILL ;
3063 3360  .Sy SIGKILL
3064 3361  was specified with
3065 3362  .Sy PCUNKILL ;
3066 3363  .Sy PCSFPREG
3067 3364  was applied on a system that does not support floating-point operations;
3068 3365  .Sy PCSXREG
3069 3366  was applied on a system that does not support extra state registers.
3070 3367  .It Er EINTR
3071 3368  A signal was received by the controlling process while waiting for the traced
3072 3369  process or lwp to stop via
3073 3370  .Sy PCSTOP ,
3074 3371  .Sy PCWSTOP ,
3075 3372  or
3076 3373  .Sy PCTWSTOP .
3077 3374  .It Er EIO
3078 3375  A
3079 3376  .Xr write 2
3080 3377  was attempted at an illegal address in the traced process.
3081 3378  .It Er ENOENT
3082 3379  The traced process or lwp has terminated after being opened.
3083 3380  The basic privilege
3084 3381  .Brq Sy PRIV_PROC_INFO
3085 3382  is not asserted in the effective set of the calling process and the calling
3086 3383  process cannot send a signal to the target process.
3087 3384  .It Er ENOMEM
3088 3385  The system-imposed limit on the number of page data file descriptors was
3089 3386  reached on an open of
3090 3387  .Pa /proc/ Ns Em pid Ns Pa /pagedata ;
3091 3388  an attempt was made
3092 3389  with
3093 3390  .Sy PCWATCH
3094 3391  to establish more watched areas than the system can support;
3095 3392  the
3096 3393  .Sy PCAGENT
3097 3394  operation was issued when the system was out of resources for
3098 3395  creating lwps.
3099 3396  .It Er ENOSYS
3100 3397  An attempt was made to perform an unsupported operation (such as
3101 3398  .Xr creat 2 ,
3102 3399  .Xr link 2 ,
3103 3400  or
3104 3401  .Xr unlink 2 )
3105 3402  on an entry in
3106 3403  .Pa /proc .
3107 3404  .It Er EOVERFLOW
3108 3405  A 32-bit controlling process attempted to read or write the
3109 3406  .Pa as
3110 3407  file or attempted to read the
3111 3408  .Pa map ,
3112 3409  .Pa rmap ,
3113 3410  or
3114 3411  .Pa pagedata
3115 3412  file of a 64-bit target process.
3116 3413  A 32-bit controlling process attempted to apply one of the
3117 3414  control operations
3118 3415  .Sy PCSREG ,
3119 3416  .Sy PCSXREG ,
3120 3417  .Sy PCSVADDR ,
3121 3418  .Sy PCWATCH ,
3122 3419  .Sy PCAGENT ,
3123 3420  .Sy PCREAD ,
3124 3421  .Sy PCWRITE
3125 3422  to a 64-bit target process.
3126 3423  .It Er EPERM
3127 3424  The process that issued the
3128 3425  .Sy PCSCRED
3129 3426  or
3130 3427  .Sy PCSCREDX
3131 3428  operation did not have the
3132 3429  .Brq Sy PRIV_PROC_SETID
3133 3430  privilege asserted in its effective set, or
3134 3431  the process that issued the
3135 3432  .Sy PCNICE
3136 3433  operation did not have the
3137 3434  .Brq Sy PRIV_PROC_PRIOCNTL
3138 3435  in its effective set.
3139 3436  .Pp
3140 3437  An attempt was made to control a process of which the E, P, and I privilege
3141 3438  sets were not a subset of the effective set of the controlling process or the
3142 3439  limit set of the controlling process is not a superset of limit set of the
3143 3440  controlled process.
3144 3441  .Pp
3145 3442  Any of the uids of the target process are
3146 3443  .Sy 0
3147 3444  or an attempt was made to change any of the uids to
3148 3445  .Sy 0
3149 3446  using
3150 3447  .Sy PCSCRED
3151 3448  and the security policy imposed additional restrictions.
3152 3449  See
3153 3450  .Xr privileges 7 .
3154 3451  .El
3155 3452  .Sh SEE ALSO
3156 3453  .Xr ls 1 ,
3157 3454  .Xr ps 1 ,
3158 3455  .Xr alarm 2 ,
3159 3456  .Xr brk 2 ,
3160 3457  .Xr chdir 2 ,
3161 3458  .Xr chroot 2 ,
3162 3459  .Xr close 2 ,
3163 3460  .Xr creat 2 ,
3164 3461  .Xr dup 2 ,
3165 3462  .Xr exec 2 ,
3166 3463  .Xr fcntl 2 ,
3167 3464  .Xr fork 2 ,
3168 3465  .Xr fork1 2 ,
3169 3466  .Xr fstat 2 ,
3170 3467  .Xr getdents 2 ,
3171 3468  .Xr getustack 2 ,
3172 3469  .Xr kill 2 ,
3173 3470  .Xr lseek 2 ,
3174 3471  .Xr mmap 2 ,
3175 3472  .Xr nice 2 ,
3176 3473  .Xr open 2 ,
3177 3474  .Xr poll 2 ,
3178 3475  .Xr pread 2 ,
3179 3476  .Xr pwrite 2 ,
3180 3477  .Xr read 2 ,
3181 3478  .Xr readlink 2 ,
3182 3479  .Xr readv 2 ,
3183 3480  .Xr shmget 2 ,
3184 3481  .Xr sigaction 2 ,
3185 3482  .Xr sigaltstack 2 ,
3186 3483  .Xr vfork 2 ,
3187 3484  .Xr write 2 ,
3188 3485  .Xr writev 2 ,
3189 3486  .Xr _stack_grow 3C ,
3190 3487  .Xr pthread_create 3C ,
3191 3488  .Xr pthread_join 3C ,
3192 3489  .Xr ptrace 3C ,
3193 3490  .Xr readdir 3C ,
3194 3491  .Xr thr_create 3C ,
3195 3492  .Xr thr_join 3C ,
3196 3493  .Xr wait 3C ,
3197 3494  .Xr siginfo.h 3HEAD ,
3198 3495  .Xr signal.h 3HEAD ,
3199 3496  .Xr types32.h 3HEAD ,
3200 3497  .Xr ucontext.h 3HEAD ,
3201 3498  .Xr contract 5 ,
3202 3499  .Xr core 5 ,
3203 3500  .Xr process 5 ,
3204 3501  .Xr lfcompile 7 ,
3205 3502  .Xr privileges 7 ,
3206 3503  .Xr security-flags 7 ,
3207 3504  .Xr chroot 8
3208 3505  .Sh NOTES
3209 3506  Descriptions of structures in this document include only interesting structure
3210 3507  elements, not filler and padding fields, and may show elements out of order for
3211 3508  descriptive clarity.
3212 3509  The actual structure definitions are contained in
3213 3510  .In procfs.h .
3214 3511  .Sh BUGS
3215 3512  Because the old
3216 3513  .Xr ioctl 2 Ns -based
3217 3514  version of
3218 3515  .Pa /proc
3219 3516  is currently supported for binary compatibility with old applications, the
3220 3517  top-level directory for a process,
3221 3518  .Pa /proc/ Ns Em pid ,
3222 3519  is not world-readable, but it is world-searchable.
3223 3520  Thus, anyone can open
3224 3521  .Pa /proc/ Ns Em pid Ns Pa /psinfo
3225 3522  even though
3226 3523  .Xr ls 1
3227 3524  applied to
3228 3525  .Pa /proc/ Ns Em pid
3229 3526  will fail for anyone but the owner or an appropriately privileged process.
3230 3527  Support for the old
3231 3528  .Xr ioctl 2 Ns -based
3232 3529  version of
3233 3530  .Pa /proc
3234 3531  will be dropped in a future release, at which time the top-level directory for
3235 3532  a process will be made world-readable.
3236 3533  .Pp
3237 3534  On SPARC based machines, the types
3238 3535  .Sy gregset_t
3239 3536  and
3240 3537  .Sy fpregset_t
3241 3538  defined in
3242 3539  .In sys/regset.h
3243 3540  are similar to but not the same as the types
3244 3541  .Sy prgregset_t
3245 3542  and
3246 3543  .Sy prfpregset_t
3247 3544  defined in
3248 3545  .In procfs.h .

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX