--- 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    5  .\" Copyright 2023 Oxide computer Company
   6    6  .\"
   7    7  .\" The contents of this file are subject to the terms of the
   8    8  .\" Common Development and Distribution License (the "License").
   9    9  .\" You may not use this file except in compliance with the License.
  10   10  .\"
  11   11  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  12   12  .\" or http://www.opensolaris.org/os/licensing.
  13   13  .\" See the License for the specific language governing permissions
  14   14  .\" and limitations under the License.
  15   15  .\"
  16   16  .\" When distributing Covered Code, include this CDDL HEADER in each
  17   17  .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  18   18  .\" If applicable, add the following below this CDDL HEADER, with the
  19   19  .\" fields enclosed by brackets "[]" replaced with your own identifying
  20   20  .\" information: Portions Copyright [yyyy] [name of copyright owner]
  21   21  .\"
  22   22  .Dd May 17, 2020
  23   23  .Dt PROC 5
  24   24  .Os
  25   25  .Sh NAME
  26   26  .Nm proc
  27   27  .Nd /proc, the process file system
  28   28  .Sh DESCRIPTION
  29   29  .Pa /proc
  30   30  is a file system that provides access to the state of each process
  31   31  and light-weight process (lwp) in the system.
  32   32  The name of each entry in the
  33   33  .Pa /proc
  34   34  directory is a decimal number corresponding to a process-ID.
  35   35  These entries are themselves subdirectories.
  36   36  Access to process state is provided by additional files contained within each
  37   37  subdirectory; the hierarchy is described more completely below.
  38   38  In this document,
  39   39  .Dq Pa /proc file
  40   40  refers to a non-directory file within the hierarchy rooted at
  41   41  .Pa /proc .
  42   42  The owner of each
  43   43  .Pa /proc
  44   44  file and subdirectory is determined by the user-ID of the process.
  45   45  .Pp
  46   46  .Pa /proc
  47   47  can be mounted on any mount point, in addition to the standard
  48   48  .Pa /proc
  49   49  mount point, and can be mounted several places at once.
  50   50  Such additional mounts are allowed in order to facilitate the confinement of
  51   51  processes to subtrees of the file system via
  52   52  .Xr chroot 2
  53   53  and yet allow such processes access to commands like
  54   54  .Xr ps 1 .
  55   55  .Pp
  56   56  Standard system calls are used to access
  57   57  .Pa /proc
  58   58  files:
  59   59  .Xr open 2 ,
  60   60  .Xr close 2 ,
  61   61  .Xr read 2 ,
  62   62  and
  63   63  .Xr write 2
  64   64  (including
  65   65  .Xr readv 2 ,
  66   66  .Xr writev 2 ,
  67   67  .Xr pread 2 ,
  68   68  and
  69   69  .Xr pwrite 2 ) .
  70   70  Most files describe process state and can only be opened for reading.
  71   71  .Pa ctl
  72   72  and
  73   73  .Pa lwpctl
  74   74  (control) files permit manipulation of process state and can only be opened for
  75   75  writing.
  76   76  .Pa as
  77   77  (address space) files contain the image of the running process and can be
  78   78  opened for both reading and writing.
  79   79  An open for writing allows process control; a read-only open allows inspection
  80   80  but not control.
  81   81  In this document, we refer to the process as open for reading or writing if
  82   82  any of its associated
  83   83  .Pa /proc
  84   84  files is open for reading or writing.
  85   85  .Pp
  86   86  In general, more than one process can open the same
  87   87  .Pa /proc
  88   88  file at the same time. \fIExclusive\fR \fIopen\fR is an advisory mechanism provided to
  89   89  allow controlling processes to avoid collisions with each other.
  90   90  A process can obtain exclusive control of a target process, with respect to
  91   91  other cooperating processes, if it successfully opens any
  92   92  .Pa /proc
  93   93  file in the target process for writing (the
  94   94  .Pa as
  95   95  or
  96   96  .Pa ctl
  97   97  files, or the
  98   98  .Pa lwpctl
  99   99  file of any lwp) while specifying
 100  100  .Sy O_EXCL
 101  101  in the
 102  102  .Xr open 2 .
 103  103  Such an open will fail if the target process is already open for writing (that
 104  104  is, if an
 105  105  .Pa as ,
 106  106  .Pa ctl ,
 107  107  or
 108  108  .Pa lwpctl
 109  109  file is already open for writing).
 110  110  There can be any number of concurrent read-only opens;
 111  111  .Sy O_EXCL
 112  112  is ignored on opens for reading.
 113  113  It is recommended that the first open for writing by a controlling
 114  114  process use the
 115  115  .Sy O_EXCL
 116  116  flag; multiple controlling processes usually result in chaos.
 117  117  .Pp
 118  118  If a process opens one of its own
 119  119  .Pa /proc
 120  120  files for writing, the open
 121  121  succeeds regardless of
 122  122  .Sy O_EXCL
 123  123  and regardless of whether some other process has the process open for writing.
 124  124  Self-opens do not count when another process attempts an exclusive open.
 125  125  (A process cannot exclude a debugger by opening itself for writing and the
 126  126  application of a debugger cannot prevent a process from opening itself.)
 127  127  All self-opens for writing are forced to be close-on-exec (see the
 128  128  .Sy F_SETFD
 129  129  operation of
 130  130  .Xr fcntl 2 ) .
 131  131  .Pp
 132  132  Data may be transferred from or to any locations in the address space of the
 133  133  traced process by applying
 134  134  .Xr lseek 2
 135  135  to position the
 136  136  .Pa as
 137  137  file at the virtual address of interest followed by
 138  138  .Xr read 2
 139  139  or
 140  140  .Xr write 2
 141  141  (or by using
 142  142  .Xr pread 2
 143  143  or
 144  144  .Xr pwrite 2
 145  145  for the combined operation).
 146  146  The address-map files
 147  147  .Pa /proc/ Ns Em pid Ns Pa /map
 148  148  and
 149  149  .Pa /proc/ Ns Em pid Ns Pa /xmap
 150  150  can be read to determine the accessible areas (mappings) of the address space.
 151  151  .Sy I/O
 152  152  transfers may span contiguous mappings.
 153  153  An
 154  154  .Sy I/O
 155  155  request extending into an unmapped area is truncated at the boundary.
 156  156  A write request beginning at an unmapped virtual address fails with
 157  157  .Er EIO ;
 158  158  a read request beginning at an unmapped virtual address returns zero (an
 159  159  end-of-file indication).
 160  160  .Pp
 161  161  Information and control operations are provided through additional files.
 162  162  .In procfs.h
 163  163  contains definitions of data structures and message formats
 164  164  used with these files.
 165  165  Some of these definitions involve the use of sets of flags.
 166  166  The set types
 167  167  .Sy sigset_t ,
 168  168  .Sy fltset_t ,
 169  169  and
 170  170  .Sy sysset_t
 171  171  correspond, respectively, to signal, fault, and system call enumerations
 172  172  defined in
 173  173  .In sys/signal.h ,
 174  174  .In sys/fault.h ,
 175  175  and
 176  176  .In sys/syscall.h .
 177  177  Each set type is large enough to hold flags for its own enumeration.
 178  178  Although they are of different sizes, they have a common
 179  179  structure and can be manipulated by these macros:
 180  180  .Bd -literal -offset indent
 181  181  prfillset(&set);             /* turn on all flags in set */
 182  182  premptyset(&set);            /* turn off all flags in set */
 183  183  praddset(&set, flag);        /* turn on the specified flag */
 184  184  prdelset(&set, flag);        /* turn off the specified flag */
 185  185  r = prismember(&set, flag);  /* != 0 iff flag is turned on */
 186  186  .Ed
 187  187  .Pp
 188  188  One of
 189  189  .Fn prfillset
 190  190  or
 191  191  .Fn premptyset
 192  192  must be used to initialize
 193  193  .Fa set
 194  194  before it is used in any other operation.
 195  195  .Fa flag
 196  196  must be a member of the enumeration corresponding to
 197  197  .Fa set .
 198  198  .Pp
 199  199  Every process contains at least one
 200  200  .Em light-weight process ,
 201  201  or
 202  202  .Sy lwp .
 203  203  Each lwp represents a flow of execution that is independently scheduled by the
 204  204  operating system.
 205  205  All lwps in a process share its address space as well as many other attributes.
 206  206  Through the use of
 207  207  .Pa lwpctl
 208  208  and
 209  209  .Pa ctl
 210  210  files as described below, it is possible to affect individual lwps in a
 211  211  process or to affect all of them at once, depending on the operation.
 212  212  .Pp
 213  213  When the process has more than one lwp, a representative lwp is chosen by the
 214  214  system for certain process status files and control operations.
 215  215  The representative lwp is a stopped lwp only if all of the process's lwps are
 216  216  stopped; is stopped on an event of interest only if all of the lwps are so
 217  217  stopped (excluding
 218  218  .Sy PR_SUSPENDED
 219  219  lwps); is in a
 220  220  .Sy PR_REQUESTED
 221  221  stop only if there are no other events of interest to be found; or, failing
 222  222  everything else, is in a
 223  223  .Sy PR_SUSPENDED
 224  224  stop (implying that the process is deadlocked).
 225  225  See the description of the
 226  226  .Pa status
 227  227  file for definitions of stopped states.
 228  228  See the
 229  229  .Sy PCSTOP
 230  230  control operation for the definition of
 231  231  .Dq event of interest .
 232  232  .Pp
 233  233  The representative lwp remains fixed (it will be chosen again on the next
 234  234  operation) as long as all of the lwps are stopped on events of interest or are
 235  235  in a
 236  236  .Sy PR_SUSPENDED
 237  237  stop and the
 238  238  .Sy PCRUN
 239  239  control operation is not applied to any of them.
 240  240  .Pp
 241  241  When applied to the process control file, every
 242  242  .Pa /proc
 243  243  control operation
 244  244  that must act on an lwp uses the same algorithm to choose which lwp to act
 245  245  upon.
 246  246  Together with synchronous stopping (see
 247  247  .Sy PCSET ) ,
 248  248  this enables a debugger to control a multiple-lwp process using only the
 249  249  process-level status and control files if it so chooses.
 250  250  More fine-grained control can be achieved using the lwp-specific files.
 251  251  .Pp
 252  252  The system supports two process data models, the traditional 32-bit data model
 253  253  in which ints, longs and pointers are all 32 bits wide (the ILP32 data model),
 254  254  and on some platforms the 64-bit data model in which longs and pointers, but
 255  255  not ints, are 64 bits in width (the LP64 data model).
 256  256  In the LP64 data model some system data types, notably
 257  257  .Sy size_t ,
 258  258  .Sy off_t ,
 259  259  .Sy time_t
 260  260  and
 261  261  .Sy dev_t ,
 262  262  grow from 32 bits to 64 bits as well.
 263  263  .Pp
 264  264  The
 265  265  .Pa /proc
 266  266  interfaces described here are available to both 32-bit and
 267  267  64-bit controlling processes.
 268  268  However, many operations attempted by a 32-bit
 269  269  controlling process on a 64-bit target process will fail with
 270  270  .Er EOVERFLOW
 271  271  because the address space range of a 32-bit process cannot encompass a 64-bit
 272  272  process or because the data in some 64-bit system data type cannot be
 273  273  compressed to fit into the corresponding 32-bit type without loss of
 274  274  information.
 275  275  Operations that fail in this circumstance include reading and
 276  276  writing the address space, reading the address-map files, and setting the
 277  277  target process's registers.
 278  278  There is no restriction on operations applied by a
 279  279  64-bit process to either a 32-bit or a 64-bit target processes.
 280  280  .Pp
 281  281  The format of the contents of any
 282  282  .Pa /proc
 283  283  file depends on the data model of the observer (the controlling process), not
 284  284  on the data model of the target process.
 285  285  A 64-bit debugger does not have to translate the information it reads from a
 286  286  .Pa /proc
 287  287  file for a 32-bit process from 32-bit format to 64-bit format.
 288  288  However, it usually has to be aware of the data model of the target process.
 289  289  The
 290  290  .Sy pr_dmodel
 291  291  field of the
 292  292  .Pa status
 293  293  files indicates the target process's data model.
 294  294  .Pp
 295  295  To help deal with system data structures that are read from 32-bit processes, a
 296  296  64-bit controlling program can be compiled with the C preprocessor symbol
 297  297  .Dv _SYSCALL32
 298  298  defined before system header files are included.
 299  299  This makes explicit 32-bit fixed-width data structures (like
 300  300  .Sy struct stat32 )
 301  301  visible to the 64-bit program.
 302  302  See
 303  303  .Xr types32.h 3HEAD .
 304  304  .Sh DIRECTORY STRUCTURE
 305  305  At the top level, the directory
 306  306  .Pa /proc
 307  307  contains entries each of which names an existing process in the system.
 308  308  These entries are themselves directories.
 309  309  Except where otherwise noted, the files described below can be
 310  310  opened for reading only.
 311  311  In addition, if a process becomes a
 312  312  .Em zombie
 313  313  (one that has exited but whose parent has not yet performed a
 314  314  .Xr wait 3C
 315  315  upon it), most of its associated
 316  316  .Pa /proc
 317  317  files disappear from the hierarchy; subsequent attempts to open them, or to
 318  318  read or write files opened before the process exited, will elicit the error
 319  319  .Er ENOENT .
 320  320  .Pp
 321  321  Although process state and consequently the contents of
 322  322  .Pa /proc
 323  323  files can change from instant to instant, a single
 324  324  .Xr read 2
 325  325  of a
 326  326  .Pa /proc
 327  327  file is guaranteed to return a sane representation of state; that is, the read
 328  328  will be atomic with respect to the state of the process.
 329  329  No such guarantee applies to successive reads applied to a
 330  330  .Pa /proc
 331  331  file for a running process.
 332  332  In addition, atomicity is not guaranteed for
 333  333  .Sy I/O
 334  334  applied to the
 335  335  .Pa as
 336  336  (address-space) file for a running process or for a process whose address space
 337  337  contains memory shared by another running process.
 338  338  .Pp
 339  339  A number of structure definitions are used to describe the files.
 340  340  These structures may grow by the addition of elements at the end in future
 341  341  releases of the system and it is not legitimate for a program to assume that
 342  342  they will not.
 343  343  .Sh STRUCTURE OF Pa /proc/ Ns Em pid
 344  344  A given directory
 345  345  .Pa /proc/ Ns Em pid
 346  346  contains the following entries.
 347  347  A process can use the invisible alias
 348  348  .Pa /proc/self
 349  349  if it wishes to open one of its own
 350  350  .Pa /proc
 351  351  files (invisible in the sense that the name
 352  352  .Dq self
 353  353  does not appear in a directory listing of
 354  354  .Pa /proc
 355  355  obtained from
 356  356  .Xr ls 1 ,
 357  357  .Xr getdents 2 ,
 358  358  or
 359  359  .Xr readdir 3C ) .
 360  360  .Ss contracts
 361  361  A directory containing references to the contracts held by the process.
 362  362  Each entry is a symlink to the contract's directory under
 363  363  .Pa /system/contract .
 364  364  See
 365  365  .Xr contract 5 .
 366  366  .Ss as
 367  367  Contains the address-space image of the process; it can be opened for both
 368  368  reading and writing.
 369  369  .Xr lseek 2
 370  370  is used to position the file at the virtual address of interest and then the
 371  371  address space can be examined or changed through
 372  372  .Xr read 2
 373  373  or
 374  374  .Xr write 2
 375  375  (or by using
 376  376  .Xr pread 2
 377  377  or
 378  378  .Xr pwrite 2
 379  379  for the combined operation).
 380  380  .Ss ctl
 381  381  A write-only file to which structured messages are written directing the system
 382  382  to change some aspect of the process's state or control its behavior in some
 383  383  way.
 384  384  The seek offset is not relevant when writing to this file.
 385  385  Individual lwps also have associated
 386  386  .Pa lwpctl
 387  387  files in the lwp subdirectories.
 388  388  A control message may be written either to the process's
 389  389  .Pa ctl
 390  390  file or to a specific
 391  391  .Pa lwpctl
 392  392  file with operation-specific effects.
 393  393  The effect of a control message is immediately reflected in the state of the
 394  394  process visible through appropriate status and information files.
 395  395  The types of control messages are described in detail later.
 396  396  See
 397  397  .Sx CONTROL MESSAGES .
 398  398  .Ss status
 399  399  Contains state information about the process and the representative lwp.
 400  400  The file contains a
 401  401  .Sy pstatus
 402  402  structure which contains an embedded
 403  403  .Sy lwpstatus
 404  404  structure for the representative lwp, as follows:
 405  405  .Bd -literal -offset 2
 406  406  typedef struct pstatus {
 407  407       int pr_flags;            /* flags (see below) */
 408  408       int pr_nlwp;             /* number of active lwps in the process */
 409  409       int pr_nzomb;            /* number of zombie lwps in the process */
 410  410       pid_tpr_pid;             /* process id */
 411  411       pid_tpr_ppid;            /* parent process id */
 412  412       pid_tpr_pgid;            /* process group id */
 413  413       pid_tpr_sid;             /* session id */
 414  414       id_t pr_aslwpid;         /* obsolete */
 415  415       id_t pr_agentid;         /* lwp-id of the agent lwp, if any */
 416  416       sigset_t pr_sigpend;     /* set of process pending signals */
 417  417       uintptr_t pr_brkbase;    /* virtual address of the process heap */
 418  418       size_t pr_brksize;       /* size of the process heap, in bytes */
 419  419       uintptr_t pr_stkbase;    /* virtual address of the process stack */
 420  420       size_tpr_stksize;        /* size of the process stack, in bytes */
 421  421       timestruc_t pr_utime;    /* process user cpu time */
 422  422       timestruc_t pr_stime;    /* process system cpu time */
 423  423       timestruc_t pr_cutime;   /* sum of children's user times */
 424  424       timestruc_t pr_cstime;   /* sum of children's system times */
 425  425       sigset_t pr_sigtrace;    /* set of traced signals */
 426  426       fltset_t pr_flttrace;    /* set of traced faults */
 427  427       sysset_t pr_sysentry;    /* set of system calls traced on entry */
 428  428       sysset_t pr_sysexit;     /* set of system calls traced on exit */
 429  429       char pr_dmodel;          /* data model of the process */
 430  430       taskid_t pr_taskid;      /* task id */
 431  431       projid_t pr_projid;      /* project id */
 432  432       zoneid_t pr_zoneid;      /* zone id */
 433  433       lwpstatus_t pr_lwp;      /* status of the representative lwp */
 434  434  } pstatus_t;
 435  435  .Ed
 436  436  .Pp
 437  437  .Sy pr_flags
 438  438  is a bit-mask holding the following process flags.
 439  439  For convenience, it also contains the lwp flags for the representative lwp,
 440  440  described later.
 441  441  .Bl -tag -width "PR_MSACCT" -offset indent
 442  442  .It Sy PR_ISSYS
 443  443  process is a system process (see
 444  444  .Sx PCSTOP ) .
 445  445  .It Sy PR_VFORKP
 446  446  process is the parent of a vforked child (see
 447  447  .Sx PCWATCH ) .
 448  448  .It Sy PR_FORK
 449  449  process has its inherit-on-fork mode set (see
 450  450  .Sx PCSET ) .
 451  451  .It Sy PR_RLC
 452  452  process has its run-on-last-close mode set (see
 453  453  .Sx PCSET ) .
 454  454  .It Sy PR_KLC
 455  455  process has its kill-on-last-close mode set (see
 456  456  .Sx PCSET ) .
 457  457  .It Sy PR_ASYNC
 458  458  process has its asynchronous-stop mode set (see
 459  459  .Sx PCSET ) .
 460  460  .It Sy PR_MSACCT
 461  461  Set by default in all processes to indicate that microstate accounting is
 462  462  enabled.
 463  463  However, this flag has been deprecated and no longer has any effect.
 464  464  Microstate accounting may not be disabled; however, it is still possible to
 465  465  toggle the flag.
 466  466  .It Sy PR_MSFORK
 467  467  Set by default in all processes to indicate that microstate accounting will be
 468  468  enabled for processes that this parent
 469  469  .Xr fork 2 Ns s .
 470  470  However, this flag has been deprecated and no longer has any effect.
 471  471  It is possible to toggle this flag; however, it is not possible to disable
 472  472  microstate accounting.
 473  473  .It Sy PR_BPTADJ
 474  474  process has its breakpoint adjustment mode set (see
 475  475  .Sx PCSET ) .
 476  476  .It Sy PR_PTRACE
 477  477  process has its ptrace-compatibility mode set (see
 478  478  .Sx PCSET ) .
 479  479  .El
 480  480  .Pp
 481  481  .Sy pr_nlwp
 482  482  is the total number of active lwps in the process.
 483  483  .Sy pr_nzomb
 484  484  is the total number of zombie lwps in the process.
 485  485  A zombie lwp is a non-detached lwp that has terminated but has not been reaped
 486  486  with
 487  487  .Xr thr_join 3C
 488  488  or
 489  489  .Xr pthread_join 3C .
 490  490  .Pp
 491  491  .Sy pr_pid ,
 492  492  .Sy pr_ppi ,
 493  493  .Sy pr_pgid ,
 494  494  and
 495  495  .Sy pr_sid
 496  496  are, respectively, the process ID, the ID of the process's parent, the
 497  497  process's process group ID, and the process's session ID.
 498  498  .Pp
 499  499  .Sy pr_aslwpid
 500  500  is obsolete and is always zero.
 501  501  .Pp
 502  502  .Sy pr_agentid
 503  503  is the lwp-ID for the
 504  504  .Pa /proc
 505  505  agent lwp (see the
 506  506  .Sx PCAGENT
 507  507  control operation).
 508  508  It is zero if there is no agent lwp in the process.
 509  509  .Pp
 510  510  .Sy pr_sigpend
 511  511  identifies asynchronous signals pending for the process.
 512  512  .Pp
 513  513  .Sy pr_brkbase
 514  514  is the virtual address of the process heap and
 515  515  .Sy pr_brksize
 516  516  is its size in bytes.
 517  517  The address formed by the sum of these values is the process
 518  518  .Sy break
 519  519  (see
 520  520  .Xr brk 2 ) .
 521  521  .Sy pr_stkbase
 522  522  and
 523  523  .Sy pr_stksize
 524  524  are, respectively, the virtual address of the process stack and its size in
 525  525  bytes.
 526  526  (Each lwp runs on a separate stack; the distinguishing characteristic of the
 527  527  process stack is that the operating system will grow it when necessary.)
 528  528  .Pp
 529  529  .Sy pr_utime ,
 530  530  .Sy pr_stime ,
 531  531  .Sy pr_cutime ,
 532  532  .Sy and pr_cstime
 533  533  are, respectively, the user
 534  534  .Sy CPU
 535  535  and system
 536  536  .Sy CPU
 537  537  time consumed by the process, and the cumulative user
 538  538  .Sy CPU
 539  539  and system
 540  540  .Sy CPU
 541  541  time consumed by the process's children, in seconds and nanoseconds.
 542  542  .Pp
 543  543  .Sy pr_sigtrace
 544  544  and
 545  545  .Sy pr_flttrace
 546  546  contain, respectively, the set of signals and the set of hardware faults that
 547  547  are being traced (see
 548  548  .Sx PCSTRACE
 549  549  and
 550  550  .Sx PCSFAULT ) .
 551  551  .Pp
 552  552  .Sy pr_sysentry
 553  553  and
 554  554  .Sy pr_sysexit
 555  555  contain, respectively, the sets of system calls being traced on entry and exit
 556  556  (see
 557  557  .Sx PCSENTRY
 558  558  and
 559  559  .Sx PCSEXIT ) .
 560  560  .Pp
 561  561  .Sy pr_dmodel
 562  562  indicates the data model of the process.
 563  563  Possible values are:
 564  564  .Bl -tag -width "PR_MODEL_NATIVE" -offset indent
 565  565  .It Sy PR_MODEL_ILP32
 566  566  process data model is ILP32.
 567  567  .It Sy PR_MODEL_LP64
 568  568  process data model is LP64.
 569  569  .It Sy PR_MODEL_NATIVE
 570  570  process data model is native.
 571  571  .El
 572  572  .Pp
 573  573  The
 574  574  .Sy pr_taskid ,
 575  575  .Sy pr_projid ,
 576  576  and
 577  577  .Sy pr_zoneid
 578  578  fields contain respectively, the numeric
 579  579  .Sy ID Ns s
 580  580  of the task, project, and zone in which the process was running.
 581  581  .Pp
 582  582  The constant
 583  583  .Sy PR_MODEL_NATIVE
 584  584  reflects the data model of the controlling process,
 585  585  .Em that is ,
 586  586  its value is
 587  587  .Sy PR_MODEL_ILP32
 588  588  or
 589  589  .Sy PR_MODEL_LP64
 590  590  according to whether the controlling process has been
 591  591  compiled as a 32-bit program or a 64-bit program, respectively.
 592  592  .Pp
 593  593  .Sy pr_lwp
 594  594  contains the status information for the representative lwp:
 595  595  .Bd -literal -offset 2
 596  596  typedef struct lwpstatus {
 597  597    int pr_flags;              /* flags (see below) */
 598  598    id_t pr_lwpid;             /* specific lwp identifier */
 599  599    short pr_why;              /* reason for lwp stop, if stopped */
 600  600    short pr_what;             /* more detailed reason */
 601  601    short pr_cursig;           /* current signal, if any */
 602  602    siginfo_t pr_info;         /* info associated with signal or fault */
 603  603    sigset_t pr_lwppend;       /* set of signals pending to the lwp */
 604  604    sigset_t pr_lwphold;       /* set of signals blocked by the lwp */
 605  605    struct sigaction pr_action;/* signal action for current signal */
 606  606    stack_t pr_altstack;       /* alternate signal stack info */
 607  607    uintptr_t pr_oldcontext;   /* address of previous ucontext */
 608  608    short pr_syscall;          /* system call number (if in syscall) */
 609  609    short pr_nsysarg;          /* number of arguments to this syscall */
 610  610    int pr_errno;              /* errno for failed syscall */
 611  611    long pr_sysarg[PRSYSARGS]; /* arguments to this syscall */
 612  612    long pr_rval1;             /* primary syscall return value */
 613  613    long pr_rval2;             /* second syscall return value, if any */
 614  614    char pr_clname[PRCLSZ];    /* scheduling class name */
 615  615    timestruc_t pr_tstamp;     /* real-time time stamp of stop */
 616  616    timestruc_t pr_utime;      /* lwp user cpu time */
 617  617    timestruc_t pr_stime;      /* lwp system cpu time */
 618  618    uintptr_t pr_ustack;       /* stack boundary data (stack_t) address */
 619  619    ulong_t pr_instr;          /* current instruction */
 620  620    prgregset_t pr_reg;        /* general registers */
 621  621    prfpregset_t pr_fpreg;     /* floating-point registers */
 622  622  } lwpstatus_t;
 623  623  .Ed
 624  624  .Pp
 625  625  .Sy pr_flags
 626  626  is a bit-mask holding the following lwp flags.
 627  627  For convenience, it also contains the process flags, described previously.
 628  628  .Bl -tag -width "PR_STOPPED" -offset indent
 629  629  .It Sy PR_STOPPED
 630  630  The lwp is stopped.
 631  631  .It Sy PR_ISTOP
 632  632  The lwp is stopped on an event of interest (see
 633  633  .Sx PCSTOP ) .
 634  634  .It Sy PR_DSTOP
 635  635  The lwp has a stop directive in effect (see
 636  636  .Sx PCSTOP ) .
 637  637  .It Sy PR_STEP
 638  638  The lwp has a single-step directive in effect (see
 639  639  .Sx PCRUN ) .
 640  640  .It Sy PR_ASLEEP
 641  641  The lwp is in an interruptible sleep within a system call.
 642  642  .It Sy PR_PCINVAL
 643  643  The lwp's current instruction
 644  644  .Pq Sy pr_instr
 645  645  is undefined.
 646  646  .It Sy PR_DETACH
 647  647  This is a detached lwp (see
 648  648  .Xr pthread_create 3C
 649  649  and
 650  650  .Xr pthread_join 3C ) .
 651  651  .It Sy PR_DAEMON
 652  652  This is a daemon lwp (see
 653  653  .Xr pthread_create 3C ) .
 654  654  .It Sy PR_ASLWP
 655  655  This flag is obsolete and is never set.
 656  656  .It Sy PR_AGENT
 657  657  This is the
 658  658  .Pa /proc
 659  659  agent lwp for the process.
 660  660  .El
 661  661  .Pp
 662  662  .Sy pr_lwpid
 663  663  names the specific lwp.
 664  664  .Pp
 665  665  .Sy pr_why
 666  666  .Sy and
 667  667  pr_what
 668  668  together describe, for a stopped lwp, the reason for the stop.
 669  669  Possible values of
 670  670  .Sy pr_why
 671  671  and the associated
 672  672  .Sy pr_what
 673  673  are:
 674  674  .Bl -tag -width "PR_JOBCONTROL" -offset left
 675  675  .It Sy PR_REQUESTED
 676  676  indicates that the stop occurred in response to a stop directive, normally
 677  677  because
 678  678  .Sy PCSTOP
 679  679  was applied or because another lwp stopped on an event of interest and the
 680  680  asynchronous-stop flag (see
 681  681  .Sx PCSET )
 682  682  was not set for the process.
 683  683  .Sy pr_what
 684  684  is unused in this case.
 685  685  .It Sy PR_SIGNALLED
 686  686  indicates that the lwp stopped on receipt of a signal (see
 687  687  .Sx PCSTRACE ) ;
 688  688  .Sy pr_what
 689  689  holds the signal number that caused the stop (for a newly-stopped
 690  690  lwp, the same value is in
 691  691  .Sy pr_cursig ) .
 692  692  .It Sy PR_FAULTED
 693  693  indicates that the lwp stopped on incurring a hardware fault (see
 694  694  .Sx PCSFAULT ) ;
 695  695  .Sy pr_what
 696  696  holds the fault number that caused the stop.
 697  697  .It Sy PR_SYSENTRY
 698  698  .It Sy PR_SYSEXIT
 699  699  indicate a stop on entry to or exit from a system call (see
 700  700  .Sx PCSENTRY
 701  701  and
 702  702  .Sx PCSEXIT ) ;
 703  703  .Sy pr_what
 704  704  holds the system call number.
 705  705  .It Sy PR_JOBCONTROL

 706  706  indicates that the lwp stopped due to the default action of a job control stop
 707  707  signal (see
 708  708  .Xr sigaction 2 ) ;
 709  709  .Sy pr_what
 710  710  holds the stopping signal number.
 711  711  .It Sy PR_SUSPENDED
 712  712  indicates that the lwp stopped due to internal synchronization of lwps within
 713  713  the process.
 714  714  .Sy pr_what
 715  715  is unused in this case.
      716 +.It Sy PR_BRAND
      717 +indicates that the lwp stopped for a brand-specific reason.
      718 +Interpretation of the value of
      719 +.Sy pr_what
      720 +depends on which zone brand is in use.
      721 +It is not generally expected that an lwp stopped in this state will be
      722 +restarted by native
      723 +.\" mandoc(1) doesn't like .Xr macros referring to itself, so this is
      724 +.\" a bit of a hack.
      725 +.Nm Ns Pq 4
      726 +consumers.
 716  727  .El
 717  728  .Pp
 718  729  .Sy pr_cursig
 719  730  names the current signal, that is, the next signal to be delivered to the lwp,
 720  731  if any.
 721  732  .Sy pr_info ,
 722  733  when the lwp is in a
 723  734  .Sy PR_SIGNALLED
 724  735  or
 725  736  .Sy PR_FAULTED

 726  737  stop, contains additional information pertinent to the particular signal or
 727  738  fault (see
 728  739  .In sys/siginfo.h ) .
 729  740  .Pp
 730  741  .Sy pr_lwppend
 731  742  identifies any synchronous or directed signals pending for the lwp.
 732  743  .Sy pr_lwphold
 733  744  identifies those signals whose delivery is being blocked by the lwp (the
 734  745  signal mask).
 735  746  .Pp
 736  747  .Sy pr_action
 737  748  contains the signal action information pertaining to the current signal (see
 738  749  .Xr sigaction 2 ) ;
 739  750  it is undefined if
 740  751  .Sy pr_cursig
 741  752  is zero.
 742  753  .Sy pr_altstack
 743  754  contains the alternate signal stack information for the lwp (see
 744  755  .Xr sigaltstack 2 ) .
 745  756  .Pp
 746  757  .Sy pr_oldcontext ,
 747  758  if not zero, contains the address on the lwp stack of a
 748  759  .Sy ucontext
 749  760  structure describing the previous user-level context (see
 750  761  .Xr ucontext.h 3HEAD ) .
 751  762  It is non-zero only if the lwp is executing in the context of a signal handler.
 752  763  .Pp
 753  764  .Sy pr_syscall
 754  765  is the number of the system call, if any, being executed by
 755  766  the lwp; it is non-zero if and only if the lwp is stopped on
 756  767  .Sy PR_SYSENTRY
 757  768  or
 758  769  .Sy PR_SYSEXIT ,
 759  770  or is asleep within a system call
 760  771  .Pf ( Sy PR_ASLEEP
 761  772  is set).
 762  773  If
 763  774  .Sy pr_syscall
 764  775  is non-zero,
 765  776  .Sy pr_nsysarg
 766  777  is the number of arguments to the system call and
 767  778  .Sy pr_sysarg
 768  779  contains the actual arguments.
 769  780  .Pp
 770  781  .Sy pr_rval1 ,
 771  782  .Sy pr_rval2 ,
 772  783  and
 773  784  .Sy pr_errno
 774  785  are defined only if the lwp
 775  786  is stopped on
 776  787  .Sy PR_SYSEXIT
 777  788  or if the
 778  789  .Sy PR_VFORKP
 779  790  flag is set.
 780  791  If
 781  792  .Sy pr_errno
 782  793  is zero,
 783  794  .Sy pr_rval1
 784  795  and
 785  796  .Sy pr_rval2
 786  797  contain the return values from the system call.
 787  798  Otherwise,
 788  799  .Sy pr_errno
 789  800  contains the error number for the failing system call (see
 790  801  .In sys/errno.h ) .
 791  802  .Pp
 792  803  .Sy pr_clname
 793  804  contains the name of the lwp's scheduling class.
 794  805  .Pp
 795  806  .Sy pr_tstamp ,
 796  807  if the lwp is stopped, contains a time stamp marking when the
 797  808  lwp stopped, in real time seconds and nanoseconds since an arbitrary time in
 798  809  the past.
 799  810  .Pp
 800  811  .Sy pr_utime
 801  812  is the amount of user level CPU time used by this LWP.
 802  813  .Pp
 803  814  .Sy pr_stime
 804  815  is the amount of system level CPU time used by this LWP.
 805  816  .Pp
 806  817  .Sy pr_ustack
 807  818  is the virtual address of the
 808  819  .Sy stack_t
 809  820  that contains the stack boundaries for this LWP.
 810  821  See
 811  822  .Xr getustack 2
 812  823  and
 813  824  .Xr _stack_grow 3C .
 814  825  .Pp
 815  826  .Sy pr_instr
 816  827  contains the machine instruction to which the lwp's program counter refers.
 817  828  The amount of data retrieved from the process is machine-dependent.
 818  829  On SPARC based machines, it is a 32-bit word.
 819  830  On x86-based machines, it is a single byte.
 820  831  In general, the size is that of the machine's smallest instruction.
 821  832  If
 822  833  .Sy PR_PCINVAL
 823  834  is set,
 824  835  .Sy pr_instr
 825  836  is undefined; this occurs whenever the lwp is not stopped or when the program
 826  837  counter refers to an invalid virtual address.
 827  838  .Pp
 828  839  .Sy pr_reg
 829  840  is an array holding the contents of a stopped lwp's general registers.
 830  841  .Bl -tag -offset left -width "SPARC V8 (32-bit)"
 831  842  .It Sy SPARC
 832  843  On SPARC-based machines, the predefined constants
 833  844  .Sy R_G0
 834  845  \&.\&.\&.
 835  846  .Sy R_G7 ,
 836  847  .Sy R_O0
 837  848  \&.\&.\&.
 838  849  .Sy R_O7 ,
 839  850  .Sy R_L0
 840  851  \&.\&.\&.
 841  852  .Sy R_L7 ,
 842  853  .Sy R_I0
 843  854  \&.\&.\&.
 844  855  .Sy R_I7 ,
 845  856  .Sy R_PC ,
 846  857  .Sy R_nPC ,
 847  858  and
 848  859  .Sy R_Y
 849  860  can be used as indices to refer to the corresponding registers; previous
 850  861  register windows can be read from their overflow locations on the stack
 851  862  (however, see the
 852  863  .Pa gwindows
 853  864  file in the
 854  865  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid
 855  866  subdirectory).
 856  867  .It Sy SPARC V8 (32-bit)
 857  868  For SPARC V8 (32-bit) controlling processes, the predefined constants
 858  869  .Sy R_PSR ,
 859  870  .Sy R_WIM ,
 860  871  and
 861  872  .Sy R_TBR
 862  873  can be used as indices to refer to the corresponding special registers.
 863  874  For SPARC V9 (64-bit) controlling processes, the predefined constants
 864  875  .Sy R_CCR ,
 865  876  .Sy R_ASI ,
 866  877  and
 867  878  .Sy R_FPRS
 868  879  can be used as indices to refer to the corresponding special registers.
 869  880  .It Sy x86 (32-bit)
 870  881  For 32-bit x86 processes, the predefined constants listed belowcan be used as
 871  882  indices to refer to the corresponding registers.
 872  883  .Bl -tag -width "TRAPNO" -offset indent -compact
 873  884  .It SS
 874  885  .It UESP
 875  886  .It EFL
 876  887  .It CS
 877  888  .It EIP
 878  889  .It ERR
 879  890  .It TRAPNO
 880  891  .It EAX
 881  892  .It ECX
 882  893  .It EDX
 883  894  .It EBX
 884  895  .It ESP
 885  896  .It EBP
 886  897  .It ESI
 887  898  .It EDI
 888  899  .It DS
 889  900  .It ES
 890  901  .It GS
 891  902  .El
 892  903  .Pp
 893  904  The preceding constants are listed in
 894  905  .In sys/regset.h .
 895  906  .Pp
 896  907  Note that a 32-bit process can run on an x86 64-bit system, using the constants
 897  908  listed above.
 898  909  .It Sy x86 (64-bit)
 899  910  To read the registers of a 32-
 900  911  .Em or
 901  912  a 64-bit process, a 64-bit x86 process should use the predefined constants
 902  913  listed below.
 903  914  .Bl -tag -width "REG_TRAPNO" -offset indent -compact
 904  915  .It REG_GSBASE
 905  916  .It REG_FSBASE
 906  917  .It REG_DS
 907  918  .It REG_ES
 908  919  .It REG_GS
 909  920  .It REG_FS
 910  921  .It REG_SS
 911  922  .It REG_RSP
 912  923  .It REG_RFL
 913  924  .It REG_CS
 914  925  .It REG_RIP
 915  926  .It REG_ERR
 916  927  .It REG_TRAPNO
 917  928  .It REG_RAX
 918  929  .It REG_RCX
 919  930  .It REG_RDX
 920  931  .It REG_RBX
 921  932  .It REG_RBP
 922  933  .It REG_RSI
 923  934  .It REG_RDI
 924  935  .It REG_R8
 925  936  .It REG_R9
 926  937  .It REG_R10
 927  938  .It REG_R11
 928  939  .It REG_R12
 929  940  .It REG_R13
 930  941  .It REG_R14
 931  942  .It REG_R15
 932  943  .El
 933  944  .Pp
 934  945  The preceding constants are listed in
 935  946  .In sys/regset.h .
 936  947  .El
 937  948  .Pp
 938  949  .Sy pr_fpreg
 939  950  is a structure holding the contents of the floating-point registers.
 940  951  .Pp
 941  952  SPARC registers, both general and floating-point, as seen by a 64-bit
 942  953  controlling process are the V9 versions of the registers, even if the target
 943  954  process is a 32-bit (V8) process.
 944  955  V8 registers are a subset of the V9 registers.
 945  956  .Pp
 946  957  If the lwp is not stopped, all register values are undefined.
 947  958  .Ss psinfo
 948  959  Contains miscellaneous information about the process and the representative lwp
 949  960  needed by the
 950  961  .Xr ps 1
 951  962  command.
 952  963  .Sy psinfo
 953  964  remains accessible after a process becomes a
 954  965  .Em zombie .
 955  966  The file contains a
 956  967  .Sy psinfo
 957  968  structure which contains an embedded
 958  969  .Sy lwpsinfo
 959  970  structure for the representative lwp, as follows:
 960  971  .Bd -literal -offset 2
 961  972  typedef struct psinfo {
 962  973      int pr_flag;             /* process flags (DEPRECATED: see below) */
 963  974      int pr_nlwp;             /* number of active lwps in the process */
 964  975      int pr_nzomb;            /* number of zombie lwps in the process */
 965  976      pid_t pr_pid;            /* process id */
 966  977      pid_t pr_ppid;           /* process id of parent */
 967  978      pid_t pr_pgid;           /* process id of process group leader */
 968  979      pid_t pr_sid;            /* session id */
 969  980      uid_t pr_uid;            /* real user id */
 970  981      uid_t pr_euid;           /* effective user id */
 971  982      gid_t pr_gid;            /* real group id */
 972  983      gid_t pr_egid;           /* effective group id */
 973  984      uintptr_t pr_addr;       /* address of process */
 974  985      size_t pr_size;          /* size of process image in Kbytes */
 975  986      size_t pr_rssize;        /* resident set size in Kbytes */
 976  987      dev_t pr_ttydev;         /* controlling tty device (or PRNODEV) */
 977  988      ushort_t pr_pctcpu;      /* % of recent cpu time used by all lwps */
 978  989      ushort_t pr_pctmem;      /* % of system memory used by process */
 979  990      timestruc_t pr_start;    /* process start time, from the epoch */
 980  991      timestruc_t pr_time;     /* cpu time for this process */
 981  992      timestruc_t pr_ctime;    /* cpu time for reaped children */
 982  993      char pr_fname[PRFNSZ];   /* name of exec'ed file */
 983  994      char pr_psargs[PRARGSZ]; /* initial characters of arg list */
 984  995      int pr_wstat;            /* if zombie, the wait() status */
 985  996      int pr_argc;             /* initial argument count */
 986  997      uintptr_t pr_argv;       /* address of initial argument vector */
 987  998      uintptr_t pr_envp;       /* address of initial environment vector */
 988  999      char pr_dmodel;          /* data model of the process */
 989 1000      taskid_t pr_taskid;      /* task id */
 990 1001      projid_t pr_projid;      /* project id */
 991 1002      poolid_t pr_poolid;      /* pool id */
 992 1003      zoneid_t pr_zoneid;      /* zone id */
 993 1004      ctid_t pr_contract;      /* process contract id */
 994 1005      lwpsinfo_t pr_lwp;       /* information for representative lwp */
 995 1006  } psinfo_t;
 996 1007  .Ed
 997 1008  .Pp
 998 1009  Some of the entries in
 999 1010  .Sy psinfo ,
1000 1011  such as
1001 1012  .Sy pr_addr ,
1002 1013  refer to internal kernel data structures and should not be expected to retain
1003 1014  their meanings across different versions of the operating system.
1004 1015  .Pp
1005 1016  .Sy psinfo_t.pr_flag
1006 1017  is a deprecated interface that should no longer be used.
1007 1018  Applications currently relying on the
1008 1019  .Sy SSYS
1009 1020  bit in
1010 1021  .Sy pr_flag
1011 1022  should migrate to checking
1012 1023  .Sy PR_ISSYS
1013 1024  in the
1014 1025  .Sy pstatus
1015 1026  structure's
1016 1027  .Sy pr_flags

1017 1028  field.
1018 1029  .Pp
1019 1030  .Sy pr_pctcpu
1020 1031  and
1021 1032  .Sy pr_pctmem
1022 1033  are 16-bit binary fractions in the range 0.0 to 1.0 with the binary point to
1023 1034  the right of the high-order bit (1.0 == 0x8000).
1024 1035  .Sy pr_pctcpu
1025 1036  is the summation over all lwps in the process.
1026 1037  .Pp
     1038 +The
     1039 +.Sy pr_fname
     1040 +and
     1041 +.Sy pr_psargs
     1042 +are writable by the owner of the process.
     1043 +To write to them, the
     1044 +.Sy psinfo
     1045 +file should be open for writing and the desired value for the field should be
     1046 +written at the file offset that corresponds to the member of structure.
     1047 +No other entry may be written to; if a write is attempted to an offset that
     1048 +does not represent one of these two memers, or if the size of the write is not
     1049 +exactly the size of the member being written, no bytes will be written and
     1050 +zero will be returned.
     1051 +.Pp
1027 1052  .Sy pr_lwp
1028 1053  contains the
1029 1054  .Xr ps 1
1030 1055  information for the representative lwp.
1031 1056  If the process is a
1032 1057  .Em zombie ,
1033 1058  .Sy pr_nlwp ,
1034 1059  .Sy pr_nzomb ,
1035 1060  and
1036 1061  .Sy pr_lwp.pr_lwpid

1037 1062  are zero and the other fields of
1038 1063  .Sy pr_lwp
1039 1064  are undefined:
1040 1065  .Bd -literal -offset 2
1041 1066  typedef struct lwpsinfo {
1042 1067      int pr_flag;             /* lwp flags (DEPRECATED: see below) */
1043 1068      id_t pr_lwpid;           /* lwp id */
1044 1069      uintptr_t pr_addr;       /* internal address of lwp */
1045 1070      uintptr_t pr_wchan;      /* wait addr for sleeping lwp */
1046 1071      char pr_stype;           /* synchronization event type */
1047 1072      char pr_state;           /* numeric lwp state */
1048 1073      char pr_sname;           /* printable character for pr_state */
1049 1074      char pr_nice;            /* nice for cpu usage */
1050 1075      short pr_syscall;        /* system call number (if in syscall) */
1051 1076      char pr_oldpri;          /* pre-SVR4, low value is high priority */
1052 1077      char pr_cpu;             /* pre-SVR4, cpu usage for scheduling */
1053 1078      int pr_pri;              /* priority, high value = high priority */
1054 1079      ushort_t pr_pctcpu;      /* % of recent cpu time used by this lwp */
1055 1080      timestruc_t pr_start;    /* lwp start time, from the epoch */
1056 1081      timestruc_t pr_time;     /* cpu time for this lwp */
1057 1082      char pr_clname[PRCLSZ];  /* scheduling class name */
1058 1083      char pr_name[PRFNSZ];    /* name of system lwp */
1059 1084      processorid_t pr_onpro;  /* processor which last ran this lwp */
1060 1085      processorid_t pr_bindpro;/* processor to which lwp is bound */
1061 1086      psetid_t pr_bindpset;    /* processor set to which lwp is bound */
1062 1087      lgrp_id_t pr_lgrp;       /* home lgroup */
1063 1088  } lwpsinfo_t;
1064 1089  .Ed
1065 1090  .Pp
1066 1091  Some of the entries in
1067 1092  .Sy lwpsinfo ,
1068 1093  such as
1069 1094  .Sy pr_addr ,
1070 1095  .Sy pr_wchan ,
1071 1096  .Sy pr_stype ,
1072 1097  .Sy pr_state ,
1073 1098  and
1074 1099  .Sy pr_name ,
1075 1100  refer to internal kernel data structures and should not be expected to retain
1076 1101  their meanings across different versions of the operating system.
1077 1102  .Pp
1078 1103  .Sy lwpsinfo_t.pr_flag
1079 1104  is a deprecated interface that should no longer be used.
1080 1105  .Pp
1081 1106  .Sy pr_pctcpu
1082 1107  is a 16-bit binary fraction, as described above.
1083 1108  It represents the
1084 1109  .Sy CPU
1085 1110  time used by the specific lwp.
1086 1111  On a multi-processor machine, the maximum value is 1/N, where N is the number
1087 1112  of
1088 1113  .Sy CPU Ns s .
1089 1114  .Pp
1090 1115  .Sy pr_contract
1091 1116  is the id of the process contract of which the process is a member.
1092 1117  See
1093 1118  .Xr contract 5
1094 1119  and
1095 1120  .Xr process 5 .
1096 1121  .Ss cred
1097 1122  Contains a description of the credentials associated with the process:
1098 1123  .Bd -literal -offset 2
1099 1124  typedef struct prcred {
1100 1125          uid_t pr_euid;      /* effective user id */
1101 1126          uid_t pr_ruid;      /* real user id */
1102 1127          uid_t pr_suid;      /* saved user id (from exec) */
1103 1128          gid_t pr_egid;      /* effective group id */
1104 1129          gid_t pr_rgid;      /* real group id */
1105 1130          gid_t pr_sgid;      /* saved group id (from exec) */
1106 1131          int pr_ngroups;     /* number of supplementary groups */
1107 1132          gid_t pr_groups[1]; /* array of supplementary groups */
1108 1133  } prcred_t;
1109 1134  .Ed
1110 1135  .Pp
1111 1136  The array of associated supplementary groups in
1112 1137  .Sy pr_groups
1113 1138   is of variable
1114 1139  length; the
1115 1140  .Sy cred
1116 1141  file contains all of the supplementary groups.
1117 1142  .Sy pr_ngroups
1118 1143  indicates the number of supplementary groups. (See also the
1119 1144  .Sy PCSCRED
1120 1145  and
1121 1146  .Sy PCSCREDX
1122 1147  control operations.)
1123 1148  .Ss priv
1124 1149  Contains a description of the privileges associated with the process:
1125 1150  .Bd -literal -offset 2
1126 1151  typedef struct prpriv {
1127 1152       uint32_t        pr_nsets;      /* number of privilege set */
1128 1153       uint32_t        pr_setsize;    /* size of privilege set */
1129 1154       uint32_t        pr_infosize;   /* size of supplementary data */
1130 1155       priv_chunk_t    pr_sets[1];    /* array of sets */
1131 1156  } prpriv_t;
1132 1157  .Ed
1133 1158  .Pp
1134 1159  The actual dimension of the
1135 1160  .Sy pr_sets Ns []
1136 1161  field is
1137 1162  .D1 pr_sets[pr_nsets][pr_setsize]
1138 1163  .Pp
1139 1164  which is followed by additional information about the process state
1140 1165  .Sy pr_infosize
1141 1166  bytes in size.
1142 1167  .Pp
1143 1168  The full size of the structure can be computed using
1144 1169  .Fn PRIV_PRPRIV_SIZE "prpriv_t *" .
1145 1170  .Ss secflags
1146 1171  This file contains the security-flags of the process.
1147 1172  It contains a description of the security flags associated with the process.
1148 1173  .Bd -literal -offset 2
1149 1174  typedef struct prsecflags {
1150 1175          uint32_t pr_version;            /* ABI Versioning of this structure */
1151 1176          secflagset_t pr_effective;      /* Effective flags */
1152 1177          secflagset_t pr_inherit;        /* Inheritable flags */
1153 1178          secflagset_t pr_lower;          /* Lower flags */
1154 1179          secflagset_t pr_upper;          /* Upper flags */
1155 1180  } prsecflags_t;
1156 1181  .Ed
1157 1182  .Pp
1158 1183  The
1159 1184  .Sy pr_version
1160 1185  field is a version number for the structure, currently
1161 1186  .Sy PRSECFLAGS_VERSION_1 .
1162 1187  .Ss sigact
1163 1188  Contains an array of
1164 1189  .Sy sigaction structures
1165 1190  describing the current dispositions of all signals associated with the traced
1166 1191  process (see
1167 1192  .Xr sigaction 2 ) .
1168 1193  Signal numbers are displaced by 1 from array indices, so that the action for
1169 1194  signal number
1170 1195  .Va n

1171 1196  appears in position
1172 1197  .Va n Ns -1
1173 1198  of the array.
1174 1199  .Ss auxv
1175 1200  Contains the initial values of the process's aux vector in an array of
1176 1201  .Sy auxv_t
1177 1202  structures (see
1178 1203  .In sys/auxv.h ) .
1179 1204  The values are those that were passed by the operating system as startup
1180 1205  information to the dynamic linker.
     1206 +.Ss argv
     1207 +Contains the concatenation of each of the argument strings, including their
     1208 +.Sy NUL
     1209 +terminators, in the argument vector
     1210 +.Pq Va argv
     1211 +for the process.
     1212 +If the process has modified either its argument vector, or the contents of
     1213 +any of the strings referenced by that vector, those changes will be visible
     1214 +here.
1181 1215  .Ss ldt
1182 1216  This file exists only on x86-based machines.
1183 1217  It is non-empty only if the process has established a local descriptor table
1184 1218  .Pq Sy LDT .
1185 1219  If non-empty, the file contains the array of currently active
1186 1220  .Sy LDT
1187 1221  entries in an array of elements of type
1188 1222  .Vt struct ssd ,
1189 1223  defined in
1190 1224  .In sys/sysi86.h ,

1191 1225  one element for each active
1192 1226  .Sy LDT
1193 1227  entry.
1194 1228  .Ss map, xmap
1195 1229  Contain information about the virtual address map of the process.
1196 1230  The map file contains an array of
1197 1231  .Sy prmap
1198 1232  structures while the xmap file contains an
1199 1233  array of
1200 1234  .Sy prxmap
1201 1235  structures.
1202 1236  Each structure describes a contiguous virtual
1203 1237  address region in the address space of the traced process:
1204 1238  .Bd -literal -offset 2
1205 1239  typedef struct prmap {
1206 1240          uintptr_tpr_vaddr;         /* virtual address of mapping */
1207 1241          size_t pr_size;            /* size of mapping in bytes */
1208 1242          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1209 1243          offset_t pr_offset;        /* offset into mapped object, if any */
1210 1244          int pr_mflags;             /* protection and attribute flags */
1211 1245          int pr_pagesize;           /* pagesize for this mapping in bytes */
1212 1246          int pr_shmid;              /* SysV shared memory identifier */
1213 1247  } prmap_t;
1214 1248  .Ed
1215 1249  .Bd -literal -offset 2
1216 1250  typedef struct prxmap {
1217 1251          uintptr_t pr_vaddr;        /* virtual address of mapping */
1218 1252          size_t pr_size;            /* size of mapping in bytes */
1219 1253          char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1220 1254          offset_t pr_offset;        /* offset into mapped object, if any */
1221 1255          int pr_mflags;             /* protection and attribute flags */
1222 1256          int pr_pagesize;           /* pagesize for this mapping in bytes */
1223 1257          int pr_shmid;              /* SysV shared memory identifier */
1224 1258          dev_t pr_dev;              /* device of mapped object, if any */
1225 1259          uint64_t pr_ino;           /* inode of mapped object, if any */
1226 1260          size_t pr_rss;             /* pages of resident memory */
1227 1261          size_t pr_anon;            /* pages of resident anonymous memory */
1228 1262          size_t pr_locked;          /* pages of locked memory */
1229 1263          uint64_t pr_hatpagesize;   /* pagesize of mapping */
1230 1264  } prxmap_t;
1231 1265  .Ed
1232 1266  .Pp
1233 1267  .Sy pr_vaddr
1234 1268  is the virtual address of the mapping within the traced process and
1235 1269  .Sy pr_size
1236 1270  is its size in bytes.
1237 1271  .Sy pr_mapname ,
1238 1272  if it does not contain a null string, contains the name of a file in the
1239 1273  .Sy object
1240 1274  directory (see below) that can be opened read-only to obtain a file descriptor
1241 1275  for the mapped file associated with the mapping.
1242 1276  This enables a debugger to find object file symbol tables without having to
1243 1277  know the real path names of the executable file and shared libraries of
1244 1278  the process.
1245 1279  .Sy pr_offset
1246 1280  is the 64-bit offset within the mapped file (if any) to which the virtual
1247 1281  address is mapped.
1248 1282  .Pp
1249 1283  .Sy pr_mflags
1250 1284  is a bit-mask of protection and attribute flags:
1251 1285  .Bl -tag -width "MA_NORESERVE" -offset left
1252 1286  .It Sy MA_READ
1253 1287  mapping is readable by the traced process.
1254 1288  .It Sy MA_WRITE
1255 1289  mapping is writable by the traced process.
1256 1290  .It Sy MA_EXEC
1257 1291  mapping is executable by the traced process.
1258 1292  .It Sy MA_SHARED
1259 1293  mapping changes are shared by the mapped object.
1260 1294  .It Sy MA_ISM
1261 1295  mapping is intimate shared memory (shared MMU resources)
1262 1296  .It Sy MAP_NORESERVE
1263 1297  mapping does not have swap space reserved (mapped with MAP_NORESERVE)
1264 1298  .It Sy MA_SHM
1265 1299  mapping System V shared memory
1266 1300  .El
1267 1301  .Pp
1268 1302  A contiguous area of the address space having the same underlying mapped object
1269 1303  may appear as multiple mappings due to varying read, write, and execute
1270 1304  attributes.
1271 1305  The underlying mapped object does not change over the range of a
1272 1306  single mapping.
1273 1307  An
1274 1308  .Sy I/O
1275 1309  operation to a mapping marked
1276 1310  .Sy MA_SHARED
1277 1311  fails if applied at a virtual address not corresponding to a valid page in the
1278 1312  underlying mapped object.
1279 1313  A write to a
1280 1314  .Sy MA_SHARED
1281 1315  mapping that is not marked
1282 1316  .Sy MA_WRITE
1283 1317  fails.
1284 1318  Reads and writes to private mappings always succeed.
1285 1319  Reads and writes to unmapped addresses fail.
1286 1320  .Pp
1287 1321  .Sy pr_pagesize
1288 1322  is the page size for the mapping, currently always the system pagesize.
1289 1323  .Pp
1290 1324  .Sy pr_shmid
1291 1325  is the shared memory identifier, if any, for the mapping.
1292 1326  Its value is \-1
1293 1327  if the mapping is not System V shared memory.
1294 1328  See
1295 1329  .Xr shmget 2 .
1296 1330  .Pp
1297 1331  .Sy pr_dev
1298 1332  is the device of the mapped object, if any, for the mapping.
1299 1333  Its value is
1300 1334  .Sy PRNODEV
1301 1335  .Pq \-1
1302 1336  if the mapping does not have a device.
1303 1337  .Pp
1304 1338  .Sy pr_ino
1305 1339  is the inode of the mapped object, if any, for the mapping.
1306 1340  Its contents are only valid if
1307 1341  .Sy pr_dev
1308 1342  is not
1309 1343  .Sy PRNODEV .
1310 1344  .Pp
1311 1345  .Sy pr_rss
1312 1346  is the number of resident pages of memory for the mapping.
1313 1347  The number of resident bytes for the mapping may be determined by multiplying
1314 1348  .Sy pr_rss
1315 1349  by the page size given by
1316 1350  .Sy pr_pagesize .
1317 1351  .Pp
1318 1352  .Sy pr_anon
1319 1353  is the number of resident anonymous memory pages (pages which are
1320 1354  private to this process) for the mapping.
1321 1355  .Pp
1322 1356  .Sy pr_locked
1323 1357  is the number of locked pages for the mapping.
1324 1358  Pages which are locked are always resident in memory.
1325 1359  .Pp
1326 1360  .Sy pr_hatpagesize
1327 1361  is the size, in bytes, of the
1328 1362  .Sy HAT
1329 1363  .Pq Sy MMU
1330 1364  translation for the mapping.
1331 1365  .Sy pr_hatpagesize
1332 1366  may be different than
1333 1367  .Sy pr_pagesize .
1334 1368  The possible values are hardware architecture specific, and
1335 1369  may change over a mapping's lifetime.
1336 1370  .Ss rmap
1337 1371  Contains information about the reserved address ranges of the process.
1338 1372  The file contains an array of
1339 1373  .Sy prmap
1340 1374  structures, as defined above for the
1341 1375  .Sy map
1342 1376  file.
1343 1377  Each structure describes a contiguous virtual address region in the
1344 1378  address space of the traced process that is reserved by the system in the sense
1345 1379  that an
1346 1380  .Xr mmap 2
1347 1381  system call that does not specify
1348 1382  .Sy MAP_FIXED
1349 1383  will not use any part of it for the new mapping.
1350 1384  Examples of such reservations include the address ranges reserved for the
1351 1385  process stack and the individual thread stacks of a multi-threaded process.
1352 1386  .Ss cwd
1353 1387  A symbolic link to the process's current working directory.
1354 1388  See
1355 1389  .Xr chdir 2 .
1356 1390  A
1357 1391  .Xr readlink 2
1358 1392  of
1359 1393  .Pa /proc/ Ns Em pid Ns Pa /cwd
1360 1394  yields a null string.
1361 1395  However, it can be opened, listed, and searched as a directory, and can be the
1362 1396  target of
1363 1397  .Xr chdir 2 .
1364 1398  .Ss root
1365 1399  A symbolic link to the process's root directory.
1366 1400  .Pa /proc/ Ns Em pid Ns Pa /root
1367 1401  can differ from the system root directory if the process or one of its
1368 1402  ancestors executed
1369 1403  .Xr chroot 2
1370 1404  as super user.
1371 1405  It has the same semantics as
1372 1406  .Pa /proc/ Ns Em pid Ns Pa /cwd .
1373 1407  .Ss fd
1374 1408  A directory containing references to the open files of the process.
1375 1409  Each entry is a decimal number corresponding to an open file descriptor in the
1376 1410  process.
1377 1411  .Pp
1378 1412  If an entry refers to a regular file, it can be opened with normal file system
1379 1413  semantics but, to ensure that the controlling process cannot gain greater
1380 1414  access than the controlled process, with no file access modes other than its
1381 1415  read/write open modes in the controlled process.
1382 1416  If an entry refers to a directory, it can be accessed with the same semantics
1383 1417  as
1384 1418  .Pa /proc/ Ns Em pid Ns Pa /cwd .
1385 1419  An attempt to open any other type of entry fails with
1386 1420  .Er EACCES .
1387 1421  .Ss fdinfo
1388 1422  A directory containing information about each of the process's open files.
1389 1423  Each entry is a decimal number corresponding to an open file descriptor in the
1390 1424  process.
1391 1425  Each file contains a
1392 1426  .Sy prfdinfo_t
1393 1427  structure defined as follows:
1394 1428  .Bd -literal -offset 2
1395 1429  typedef struct prfdinfo {
1396 1430      int     pr_fd;          /* file descriptor number */
1397 1431      mode_t  pr_mode;        /* (see st_mode in stat(2)) */
1398 1432      uint64_t pr_ino;        /* inode number */
1399 1433      uint64_t pr_size;       /* file size */
1400 1434      int64_t pr_offset;      /* current offset of file descriptor */
1401 1435      uid_t   pr_uid;         /* owner's user id */
1402 1436      gid_t   pr_gid;         /* owner's group id */
1403 1437      major_t pr_major;       /* major number of device containing file */
1404 1438      minor_t pr_minor;       /* minor number of device containing file */
1405 1439      major_t pr_rmajor;      /* major number (if special file) */
1406 1440      minor_t pr_rminor;      /* minor number (if special file) */
1407 1441      int     pr_fileflags;   /* (see F_GETXFL in fcntl(2)) */
1408 1442      int     pr_fdflags;     /* (see F_GETFD in fcntl(2)) */
1409 1443      short   pr_locktype;    /* (see F_GETLK in fcntl(2)) */
1410 1444      pid_t   pr_lockpid;     /* process holding file lock (see F_GETLK) */
1411 1445      int     pr_locksysid;   /* sysid of locking process (see F_GETLK) */
1412 1446      pid_t   pr_peerpid;     /* peer process (socket, door) */
1413 1447      int     pr_filler[25];  /* reserved for future use */
1414 1448      char    pr_peername[PRFNSZ]; /* peer process name */
1415 1449  #if __STDC_VERSION__ >= 199901L
1416 1450      char    pr_misc[];      /* self describing structures */
1417 1451  #else
1418 1452      char    pr_misc[1];
1419 1453  #endif
1420 1454  } prfdinfo_t;
1421 1455  .Ed
1422 1456  .Pp
1423 1457  The
1424 1458  .Sy pr_misc
1425 1459  element points to a list of additional miscellaneous data items, each of which
1426 1460  has a header of type
1427 1461  .Sy pr_misc_header_t
1428 1462  specifying the size and type, and some data which immediately follow
1429 1463  the header.
1430 1464  .Bd -literal -offset 2
1431 1465  typedef struct pr_misc_header {
1432 1466      uint_t          pr_misc_size;
1433 1467      uint_t          pr_misc_type;
1434 1468  } pr_misc_header_t;
1435 1469  .Ed
1436 1470  .Pp
1437 1471  The
1438 1472  .Sy pr_misc_size
1439 1473  field is the sum of the sizes of the header and the associated data and any
1440 1474  trailing padding bytes which will be set to zero.
1441 1475  The end of the list is indicated by a header with a zero size and a type with
1442 1476  all bits set.
1443 1477  .Pp
1444 1478  The following miscellaneous data types can be present:
1445 1479  .Bl -tag -width "PR_SOCKOPT_TCP_CONGESTION" -offset left
1446 1480  .It Sy PR_PATHNAME
1447 1481  The file descriptor's path in the filesystem.
1448 1482  This is a NUL-terminated sequence of characters.
1449 1483  .It Sy PR_SOCKETNAME
1450 1484  A
1451 1485  .Sy sockaddr
1452 1486  structure representing the local socket name for this file descriptor, as
1453 1487  would be returned by calling
1454 1488  .Fn getsockname
1455 1489  within the process.
1456 1490  .It Sy PR_PEERSOCKNAME
1457 1491  A
1458 1492  .Sy sockaddr
1459 1493  structure representing the peer socket name for this file descriptor, as
1460 1494  would be returned by calling
1461 1495  .Fn getpeername
1462 1496  within the process.
1463 1497  .It Sy PR_SOCKOPTS_BOOL_OPTS
1464 1498  An unsigned integer which has bits set corresponding to options which are
1465 1499  set on the underlying socket.
1466 1500  The following bits may be set:
1467 1501  .Bl -tag -width "PR_SO_PASSIVE_CONNECT"
1468 1502  .It Sy PR_SO_DEBUG
1469 1503  .It Sy PR_SO_REUSEADDR
1470 1504  .It Sy PR_SO_REUSEPORT
1471 1505  .It Sy PR_SO_KEEPALIVE
1472 1506  .It Sy PR_SO_DONTROUTE
1473 1507  .It Sy PR_SO_BROADCAST
1474 1508  .It Sy PR_SO_OOBINLINE
1475 1509  .It Sy PR_SO_DGRAM_ERRIND
1476 1510  .It Sy PR_SO_ALLZONES
1477 1511  .It Sy PR_SO_MAC_EXEMPT
1478 1512  .It Sy PR_SO_EXCLBIND
1479 1513  .It Sy PR_SO_PASSIVE_CONNECT
1480 1514  .It Sy PR_SO_ACCEPTCONN
1481 1515  .It Sy PR_UDP_NAT_T_ENDPOINT
1482 1516  .It Sy PR_SO_VRRP
1483 1517  .It Sy PR_SO_MAC_IMPLICIT
1484 1518  .El
1485 1519  .It Sy PR_SOCKOPT_LINGER
1486 1520  A
1487 1521  .Sy struct linger
1488 1522  as would be returned by calling
1489 1523  .Fn getsockopt SO_LINGER
1490 1524  within the process.
1491 1525  .It Sy PR_SOCKOPT_SNDBUF
1492 1526  The data that would be returned by calling
1493 1527  .Fn getsockopt SO_SNDBUF
1494 1528  within the process.
1495 1529  .It Sy PR_SOCKOPT_RCVBUF
1496 1530  The data that would be returned by calling
1497 1531  .Fn getsockopt SO_RCVBUF
1498 1532  within the process.
1499 1533  .It Sy PR_SOCKOPT_IP_NEXTHOP
1500 1534  The data that would be returned by calling
1501 1535  .Fn getsockopt IPPROTO_IP IP_NEXTHOP
1502 1536  within the process.
1503 1537  .It Sy PR_SOCKOPT_IPV6_NEXTHOP
1504 1538  The data that would be returned by calling
1505 1539  .Fn getsockopt IPPROTO_IPV6 IPV6_NEXTHOP
1506 1540  within the process.
1507 1541  .It Sy PR_SOCKOPT_TYPE
1508 1542  The data that would be returned by calling
1509 1543  .Fn getsockopt SO_TYPE
1510 1544  within the process.
1511 1545  .It Sy PR_SOCKOPT_TCP_CONGESTION
1512 1546  For TCP sockets, the data that would be returned by calling
1513 1547  .Fn getsockopt IPPROTO_TCP TCP_CONGESTION
1514 1548  within the process.
1515 1549  This is a NUL-terminated character array containing the name of the congestion
1516 1550  algorithm in use for the socket.
1517 1551  .It Sy PR_SOCKFILTERS_PRIV
1518 1552  Private data relating to up to the first 32 socket filters pushed on this
1519 1553  descriptor.
1520 1554  .El
1521 1555  .Ss object
1522 1556  A directory containing read-only files with names corresponding to the
1523 1557  .Sy pr_mapname
1524 1558  entries in the
1525 1559  .Sy map
1526 1560  and
1527 1561  .Sy pagedata
1528 1562  files.
1529 1563  Opening such a file yields a file descriptor for the underlying mapped file
1530 1564  associated with an address-space mapping in the process.
1531 1565  The file name
1532 1566  .Pa a.out
1533 1567  appears in the directory as an alias for the process's executable file.
1534 1568  .Pp
1535 1569  The
1536 1570  .Pa object
1537 1571  directory makes it possible for a controlling process to gain
1538 1572  access to the object file and any shared libraries (and consequently the symbol
1539 1573  tables) without having to know the actual path names of the executable files.
1540 1574  .Ss path
1541 1575  A directory containing symbolic links to files opened by the process.
1542 1576  The directory includes one entry for
1543 1577  .Pa cwd
1544 1578  and
1545 1579  .Pa root .
1546 1580  The directory also contains a numerical entry for each file descriptor in the
1547 1581  .Pa fd
1548 1582  directory, and entries matching those in the
1549 1583  .Pa object
1550 1584  directory.
1551 1585  If this information is not available, any attempt to read the contents of the
1552 1586  symbolic link will fail.
1553 1587  This is most common for files that do not exist in the filesystem namespace
1554 1588  (such as
1555 1589  .Sy FIFO Ns s
1556 1590  and sockets), but can also happen for regular files.
1557 1591  For the file descriptor entries, the path may be different from the one
1558 1592  used by the process to open the file.
1559 1593  .Ss pagedata
1560 1594  Opening the page data file enables tracking of address space references and
1561 1595  modifications on a per-page basis.
1562 1596  .Pp
1563 1597  A
1564 1598  .Xr read 2
1565 1599  of the page data file descriptor returns structured page data
1566 1600  and atomically clears the page data maintained for the file by the system.
1567 1601  That is to say, each read returns data collected since the last read; the
1568 1602  first read returns data collected since the file was opened.
1569 1603  When the call completes, the read buffer contains the following structure as
1570 1604  its header and thereafter contains a number of section header structures and
1571 1605  associated byte arrays that must be accessed by walking linearly through the
1572 1606  buffer.
1573 1607  .Bd -literal -offset 2
1574 1608  typedef struct prpageheader {
1575 1609      timestruc_t pr_tstamp; /* real time stamp, time of read() */
1576 1610      ulong_t pr_nmap;       /* number of address space mappings */
1577 1611      ulong_t pr_npage;      /* total number of pages */
1578 1612  } prpageheader_t;
1579 1613  .Ed
1580 1614  .Pp
1581 1615  The header is followed by
1582 1616  .Sy "pr_nmap prasmap"
1583 1617  structures and associated data arrays.
1584 1618  The
1585 1619  .Sy prasmap
1586 1620  structure contains the following elements:
1587 1621  .Bd -literal -offset 2
1588 1622  typedef struct prasmap {
1589 1623      uintptr_t pr_vaddr;        /* virtual address of mapping */
1590 1624      ulong_t pr_npage;          /* number of pages in mapping */
1591 1625      char pr_mapname[PRMAPSZ];  /* name in /proc/pid/object */
1592 1626      offset_t pr_offset;        /* offset into mapped object, if any */
1593 1627      int pr_mflags;             /* protection and attribute flags */
1594 1628      int pr_pagesize;           /* pagesize for this mapping in bytes */
1595 1629      int pr_shmid;              /* SysV shared memory identifier */
1596 1630  } prasmap_t;
1597 1631  .Ed
1598 1632  .Pp
1599 1633  Each section header is followed by
1600 1634  .Sy pr_npage
1601 1635  bytes, one byte for each page in the mapping, plus 0-7 null bytes at the end
1602 1636  so that the next
1603 1637  .Sy prasmap
1604 1638  structure begins on an eight-byte aligned boundary.
1605 1639  Each data byte may contain these flags:
1606 1640  .Bl -tag -width "PG_REFERENCED" -offset 2
1607 1641  .It Sy PG_REFERENCED
1608 1642  page has been referenced.
1609 1643  .It Sy PG_MODIFIED
1610 1644  page has been modified.
1611 1645  .El
1612 1646  .Pp
1613 1647  If the read buffer is not large enough to contain all of the page data, the
1614 1648  read fails with
1615 1649  .Er E2BIG
1616 1650  and the page data is not cleared.
1617 1651  The required size of the read buffer can be determined through
1618 1652  .Xr fstat 2 .
1619 1653  Application of
1620 1654  .Xr lseek 2
1621 1655  to the page data file descriptor is ineffective; every read
1622 1656  starts from the beginning of the file.
1623 1657  Closing the page data file descriptor
1624 1658  terminates the system overhead associated with collecting the data.
1625 1659  .Pp
1626 1660  More than one page data file descriptor for the same process can be opened, up
1627 1661  to a system-imposed limit per traced process.
1628 1662  A read of one does not affect the data being collected by the system for the
1629 1663  others.
1630 1664  An open of the page data file will fail with
1631 1665  .Er ENOMEM
1632 1666  if the system-imposed limit would be exceeded.
1633 1667  .Ss watch
1634 1668  Contains an array of
1635 1669  .Vt prwatch
1636 1670  structures, one for each watched area established by the
1637 1671  .Sy PCWATCH
1638 1672  control operation.
1639 1673  See
1640 1674  .Sx PCWATCH
1641 1675  for details.
1642 1676  .Ss usage
1643 1677  Contains process usage information described by a
1644 1678  .Vt prusage
1645 1679  structure which contains at least the following fields:
1646 1680  .Bd -literal -offset 2
1647 1681  typedef struct prusage {
1648 1682      id_t pr_lwpid;           /* lwp id.  0: process or defunct */
1649 1683      int pr_count;            /* number of contributing lwps */
1650 1684      timestruc_t pr_tstamp;   /* real time stamp, time of read() */
1651 1685      timestruc_t pr_create;   /* process/lwp creation time stamp */
1652 1686      timestruc_t pr_term;     /* process/lwp termination time stamp */
1653 1687      timestruc_t pr_rtime;    /* total lwp real (elapsed) time */
1654 1688      timestruc_t pr_utime;    /* user level CPU time */
1655 1689      timestruc_t pr_stime;    /* system call CPU time */
1656 1690      timestruc_t pr_ttime;    /* other system trap CPU time */
1657 1691      timestruc_t pr_tftime;   /* text page fault sleep time */
1658 1692      timestruc_t pr_dftime;   /* data page fault sleep time */
1659 1693      timestruc_t pr_kftime;   /* kernel page fault sleep time */
1660 1694      timestruc_t pr_ltime;    /* user lock wait sleep time */
1661 1695      timestruc_t pr_slptime;  /* all other sleep time */
1662 1696      timestruc_t pr_wtime;    /* wait-cpu (latency) time */
1663 1697      timestruc_t pr_stoptime; /* stopped time */
1664 1698      ulong_t pr_minf;         /* minor page faults */
1665 1699      ulong_t pr_majf;         /* major page faults */
1666 1700      ulong_t pr_nswap;        /* swaps */
1667 1701      ulong_t pr_inblk;        /* input blocks */
1668 1702      ulong_t pr_oublk;        /* output blocks */
1669 1703      ulong_t pr_msnd;         /* messages sent */
1670 1704      ulong_t pr_mrcv;         /* messages received */
1671 1705      ulong_t pr_sigs;         /* signals received */
1672 1706      ulong_t pr_vctx;         /* voluntary context switches */
1673 1707      ulong_t pr_ictx;         /* involuntary context switches */
1674 1708      ulong_t pr_sysc;         /* system calls */
1675 1709      ulong_t pr_ioch;         /* chars read and written */
1676 1710  } prusage_t;
1677 1711  .Ed
1678 1712  .Pp
1679 1713  Microstate accounting is now continuously enabled.
1680 1714  While this information was
1681 1715  previously an estimate, if microstate accounting were not enabled, the current
1682 1716  information is now never an estimate represents time the process has spent in
1683 1717  various states.
1684 1718  .Ss lstatus
1685 1719  Contains a
1686 1720  .Vt prheader
1687 1721  structure followed by an array of
1688 1722  .Vt lwpstatus
1689 1723  structures, one for each active lwp in the process (see also
1690 1724  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpstatus ,
1691 1725  below).
1692 1726  The
1693 1727  .Vt prheader
1694 1728  structure describes the number and size of the array entries that follow.
1695 1729  .Bd -literal -offset 2
1696 1730  typedef struct prheader {
1697 1731      long pr_nent;        /* number of entries */
1698 1732      size_t pr_entsize;   /* size of each entry, in bytes */
1699 1733  } prheader_t;
1700 1734  .Ed
1701 1735  .Pp
1702 1736  The
1703 1737  .Vt lwpstatus
1704 1738  structure may grow by the addition of elements at the end in future releases
1705 1739  of the system.
1706 1740  Programs must use
1707 1741  .Sy pr_entsize
1708 1742  in the file header to index through the array.
1709 1743  These comments apply to all
1710 1744  .Pa /proc
1711 1745  files that include a
1712 1746  .Vt prheader
1713 1747  structure
1714 1748  .Pf ( Pa lpsinfo
1715 1749  and
1716 1750  .Pa lusage ,
1717 1751  below).
1718 1752  .Ss lpsinfo
1719 1753  Contains a
1720 1754  .Vt prheader
1721 1755  structure followed by an array of
1722 1756  .Vt lwpsinfo
1723 1757  structures, one for eachactive and zombie lwp in the process.
1724 1758  See also
1725 1759  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpsinfo ,
1726 1760  below.
1727 1761  .Ss lusage
1728 1762  Contains a
1729 1763  .Vt prheader
1730 1764  structure followed by an array of
1731 1765  .Vt prusage
1732 1766  structures, one for each active lwp in the process, plus an additional element
1733 1767  at the beginning that contains the summation over all defunct lwps (lwps that
1734 1768  once existed but no longer exist in the process).
1735 1769  Excluding the
1736 1770  .Sy pr_lwpid ,
1737 1771  .Sy pr_tstamp ,
1738 1772  .Sy pr_create ,
1739 1773  and
1740 1774  .Sy pr_term
1741 1775  entries, the entry-by-entry summation over all these structures is the
1742 1776  definition of the process usage information obtained from the
1743 1777  .Pa usage
1744 1778  file. (See also
1745 1779  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpusage ,
1746 1780  below.)
1747 1781  .Ss lwp
1748 1782  A directory containing entries each of which names an active or zombie lwp
1749 1783  within the process.
1750 1784  These entries are themselves directories containing additional files as
1751 1785  described below.
1752 1786  Only the
1753 1787  .Pa lwpsinfo
1754 1788  file exists in the directory of a zombie lwp.
1755 1789  .Sh "STRUCTURE OF" Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid
1756 1790  A given directory
1757 1791  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid
1758 1792  contains the following entries:
1759 1793  .Ss lwpctl
1760 1794  Write-only control file.
1761 1795  The messages written to this file affect the specific
1762 1796  lwp rather than the representative lwp, as is the case for the process's
1763 1797  .Pa ctl
1764 1798  file.
1765 1799  .Ss lwpname
1766 1800  A buffer of
1767 1801  .Dv THREAD_NAME_MAX
1768 1802  bytes representing the LWP name; the buffer is
1769 1803  zero-filled if the thread name is shorter than the buffer.
1770 1804  If no thread name is set, the buffer contains the empty string.
1771 1805  A read with a buffer shorter than
1772 1806  .Dv THREAD_NAME_MAX
1773 1807  bytes is not guaranteed to be NUL-terminated.
1774 1808  Writing to this file will set the LWP name for the specific lwp.
1775 1809  This file may not be present in older operating system versions.
1776 1810  .Dv THREAD_NAME_MAX
1777 1811  may increase in the future; clients should be prepared for this.
1778 1812  .Ss lwpstatus
1779 1813  lwp-specific state information.
1780 1814  This file contains the
1781 1815  .Vt lwpstatus
1782 1816  structure for the specific lwp as described above for the representative lwp in
1783 1817  the process's
1784 1818  .Pa status
1785 1819  file.
1786 1820  .Ss lwpsinfo
1787 1821  lwp-specific
1788 1822  .Xr ps 1
1789 1823  information.
1790 1824  This file contains the
1791 1825  .Vt lwpsinfo
1792 1826  structure for the specific lwp as described above for the representative lwp in
1793 1827  the process's
1794 1828  .Pa psinfo
1795 1829  file.
1796 1830  The
1797 1831  .Pa lwpsinfo
1798 1832  file remains accessible after an lwp becomes a zombie.
1799 1833  .Ss lwpusage
1800 1834  This file contains the
1801 1835  .Vt prusage
1802 1836  structure for the specific lwp as described above for the process's
1803 1837  .Pa usage
1804 1838  file.
1805 1839  .Ss gwindows
1806 1840  This file exists only on SPARC based machines.
1807 1841  If it is non-empty, it contains a
1808 1842  .Vt gwindows_t
1809 1843  structure, defined in
1810 1844  .In sys/regset.h ,
1811 1845  with the values of those SPARC register windows that could not be stored on
1812 1846  the stack when the lwp stopped.
1813 1847  Conditions under which register windows are not stored on the
1814 1848  stack are: the stack pointer refers to nonexistent process memory or the stack
1815 1849  pointer is improperly aligned.
1816 1850  If the lwp is not stopped or if there are no
1817 1851  register windows that could not be stored on the stack, the file is empty (the
1818 1852  usual case).
1819 1853  .Ss xregs
1820 1854  Extra state registers.
1821 1855  The extra state register set is architecture dependent;
1822 1856  this file is empty if the system does not support extra state registers.
1823 1857  If the file is non-empty, it contains an architecture dependent structure of
1824 1858  type
1825 1859  .Vt prxregset_t ,
1826 1860  defined in
1827 1861  .In procfs.h ,
1828 1862  with the values of the lwp's extra state registers.
1829 1863  If the lwp is not stopped, all register values are undefined.
1830 1864  See also the
1831 1865  .Sx PCSXREG
1832 1866  control operation, below.
1833 1867  .Ss asrs
1834 1868  This file exists only for 64-bit SPARC V9 processes.
1835 1869  It contains an
1836 1870  .Vt asrset_t
1837 1871  structure, defined in
1838 1872  .In sys/regset.h ,
1839 1873  containing the values of the lwp's platform-dependent ancillary state registers.
1840 1874  If the lwp is not stopped, all register values are undefined.
1841 1875  See also the
1842 1876  .Sx PCSASRS
1843 1877  control operation, below.
1844 1878  .Ss spymaster
1845 1879  For an agent lwp (see
1846 1880  .Sx PCAGENT ) ,
1847 1881  this file contains a
1848 1882  .Vt psinfo_t
1849 1883  structure that corresponds to the process that created the agent lwp at the
1850 1884  time the agent was created.
1851 1885  This structure is identical to that retrieved via the
1852 1886  .Pa psinfo
1853 1887  file, with one modification: the
1854 1888  .Sy pr_time
1855 1889  field does not correspond to the CPU time for the process, but rather to the
1856 1890  creation time of the agent lwp.
1857 1891  .Ss templates
1858 1892  A directory which contains references to the active templates for the lwp,
1859 1893  named by the contract type.
1860 1894  Changes made to an active template descriptor do
1861 1895  not affect the original template which was activated, though they do affect the
1862 1896  active template.
1863 1897  It is not possible to activate an active template descriptor.
1864 1898  See
1865 1899  .Xr contract 5 .
1866 1900  .Sh ARCHITECTURE-SPECIFIC STRUCTURES
1867 1901  .Ss x86
1868 1902  The x86
1869 1903  .Vt prxregset_t
1870 1904  structure is opaque and is made up of several different components due
1871 1905  to the fact that different x86 processors enumerate different
1872 1906  architectural extensions.
1873 1907  .Pp
1874 1908  The structure begins with a header, the
1875 1909  .Vt prxregset_hdr_t ,
1876 1910  which is followed by a number of different information sections which
1877 1911  describe different possible extended registers.
1878 1912  Each of those is covered by a
1879 1913  .Vt prxregset_info_t ,
1880 1914  and then finally there are different data payloads that represent each
1881 1915  extended register.
1882 1916  .Pp
1883 1917  The number of different informational entries varies from system to
1884 1918  system based on the set of architectural features that the system
1885 1919  supports and the corresponding OS enablement for them.
1886 1920  This structure is built around the idea of the x86
1887 1921  .Sy xsave
1888 1922  structure.
1889 1923  That is, there is a central header which describes a bit-vector of what
1890 1924  extended features are present and have valid state.
1891 1925  .Pp
1892 1926  Each x86 xregs file begins with the
1893 1927  .Vt prxregset_hdr_t
1894 1928  which looks like:
1895 1929  .Bd -literal -offset 2
1896 1930  typedef struct prxregset_hdr {
1897 1931          uint32_t        pr_type;
1898 1932          uint32_t        pr_size;
1899 1933          uint32_t        pr_flags;
1900 1934          uint32_t        pr_pad[4];
1901 1935          uint32_t        pr_ninfo;
1902 1936          prxregset_info_t pr_info[];
1903 1937  } prxregset_hdr_t;
1904 1938  .Ed
1905 1939  .Pp
1906 1940  The
1907 1941  .Fa pr_type
1908 1942  member is always set to
1909 1943  .Dv PR_TYPE_XSAVE .
1910 1944  This is used to indicate the type of file that is present.
1911 1945  There may be different file types in the future on x86 so this value
1912 1946  should always be checked.
1913 1947  If it is not
1914 1948  .Dv PR_TYPE_XSAVE
1915 1949  then the rest of the structure may look different.
1916 1950  The
1917 1951  .Fa pr_size
1918 1952  member indicates the size in bytes of the overall structure.
1919 1953  The
1920 1954  .Fa pr_flags
1921 1955  and
1922 1956  .Fa pr_pad
1923 1957  values are currently reserved for future use.
1924 1958  They will be set to zero right now when read and must be set to zero when
1925 1959  writing the data.
1926 1960  The
1927 1961  .Fa pr_ninfo
1928 1962  member indicates the number of informational items are present in
1929 1963  .Fa pr_info.
1930 1964  There will be one informational item for each register set that exists.
1931 1965  .Pp
1932 1966  The
1933 1967  .Fa pr_info
1934 1968  member points to an array of informational members.
1935 1969  These immediately follow the structure, though the
1936 1970  .Fa pr_info
1937 1971  member may not be available directly if not in an environment compatible with
1938 1972  some C99 features.
1939 1973  Each
1940 1974  .Vt prxregset_info_t
1941 1975  structure looks like:
1942 1976  .Bd -literal -offset 2
1943 1977  typedef struct prxregset_info {
1944 1978          uint32_t pri_type;
1945 1979          uint32_t pri_flags;
1946 1980          uint32_t pri_size;
1947 1981          uint32_t pri_offset;
1948 1982  } prxregset_info_t;
1949 1983  .Ed
1950 1984  .Pp
1951 1985  The
1952 1986  .Fa pri_type
1953 1987  member is used to indicate the type of data and its format that this represents.
1954 1988  Types are listed below.
1955 1989  The
1956 1990  .Fa pri_flags
1957 1991  member is used to indicate future extensions or information about these items.
1958 1992  Right now, these are all zero.
1959 1993  The
1960 1994  .Fa pri_size
1961 1995  member indicates the size in bytes of the type's data.
1962 1996  The
1963 1997  .Fa pri_offset
1964 1998  member indicates the offset to the start of the data section from the beginning
1965 1999  of the xregs file.
1966 2000  That is an offset of 0 would be the first byte of the
1967 2001  .Vt prxregset_hdr_t .
1968 2002  .Pp
1969 2003  The following types of structures and their corresponding data structures are
1970 2004  currently defined:
1971 2005  .Bl -tag -width Ds
1972 2006  .It Dv PRX_INFO_XCR - Vt prxregset_xcr_t
1973 2007  This structure provides read-only access to understanding the CPU's settings for
1974 2008  this thread.
1975 2009  In particular, it lets you see what is set in the x86 %xcr0 register which is
1976 2010  the extended feature control register and controls what extended features the
1977 2011  CPU actually uses.
1978 2012  It also contains the x86 extended feature disable MSR which controls features
1979 2013  that are ignored.
1980 2014  The
1981 2015  .Vt prxregset_xcr_t
1982 2016  looks like:
1983 2017  .Bd -literal -offset -indent
1984 2018  typedef struct prxregset_xcr {
1985 2019          uint64_t        prx_xcr_xcr0;
1986 2020          uint64_t        prx_xcr_xfd;
1987 2021          uint64_t        prx_xcr_pad[2];
1988 2022  } prxregset_xcr_t;
1989 2023  .Ed
1990 2024  .Pp
1991 2025  When setting the xregs, this entry can be left out.
1992 2026  If it is included, it must match the existing entries, otherwise an error will
1993 2027  be generated.
1994 2028  .It Dv PRX_INFO_XSAVE - Vt prxregset_xsave_t
1995 2029  This structure represents the same as the actual Intel xsave structure, which
1996 2030  has both the traditional XMM state that comes from the fxsave instruction and
1997 2031  then also contains the xsave header itself.
1998 2032  The structure varies between 32-bit and 64-bit applications.
1999 2033  The structure itself looks like:
2000 2034  .Bd -literal
2001 2035  typedef struct prxregset_xsave {
2002 2036          uint16_t        prx_fx_fcw;
2003 2037          uint16_t        prx_fx_fsw;
2004 2038          uint16_t        prx_fx_fctw;    /* compressed tag word */
2005 2039          uint16_t        prx_fx_fop;
2006 2040  #if defined(__amd64)
2007 2041          uint64_t        prx_fx_rip;
2008 2042          uint64_t        prx_fx_rdp;
2009 2043  #else
2010 2044          uint32_t        prx_fx_eip;
2011 2045          uint16_t        prx_fx_cs;
2012 2046          uint16_t        __prx_fx_ign0;
2013 2047          uint32_t        prx_fx_dp;
2014 2048          uint16_t        prx_fx_ds;
2015 2049          uint16_t        __prx_fx_ign1;
2016 2050  #endif
2017 2051          uint32_t        prx_fx_mxcsr;
2018 2052          uint32_t        prx_fx_mxcsr_mask;
2019 2053          union {
2020 2054                  uint16_t prx_fpr_16[5]; /* 80-bits of x87 state */
2021 2055                  u_longlong_t prx_fpr_mmx;       /* 64-bit mmx register */
2022 2056                  uint32_t _prx__fpr_pad[4];      /* (pad out to 128-bits) */
2023 2057          } fx_st[8];
2024 2058  #if defined(__amd64)
2025 2059          upad128_t       prx_fx_xmm[16]; /* 128-bit registers */
2026 2060          upad128_t       __prx_fx_ign2[6];
2027 2061  #else
2028 2062          upad128_t       prx_fx_xmm[8];  /* 128-bit registers */
2029 2063          upad128_t       __prx_fx_ign2[14];
2030 2064  #endif
2031 2065          uint64_t        prx_xsh_xstate_bv;
2032 2066          uint64_t        prx_xsh_xcomp_bv;
2033 2067          uint64_t        prx_xsh_reserved[6];
2034 2068  } prxregset_xsave_t;
2035 2069  .Ed
2036 2070  .Pp
2037 2071  In the classical fxsave portion of the structure, most of the members follow the
2038 2072  same meaning and match their presence in the fpregs file and their use as
2039 2073  discussed in the Intel and AMD software developer manuals.
2040 2074  The one exception is that when setting the
2041 2075  .Fa prx_fx_mxcsr
2042 2076  member reserved bits that are set will be masked off and ignored.
2043 2077  .Pp
2044 2078  The most notable fields to consider here right now are the last few members
2045 2079  which are part of the xsave header itself.
2046 2080  In particular, the
2047 2081  .Fa prx_xsh_xstate_bv
2048 2082  component is used to track the actual features whose content are valid.
2049 2083  When reading the registers, if a given entry is not valid, the register state
2050 2084  will write out the informational entry in its default state.
2051 2085  When setting the extended registers, this notes which features will be loaded
2052 2086  from their default state
2053 2087  .Pq as defined by Intel and AMD's manuals
2054 2088  and which will be loaded from the informational entries.
2055 2089  If a bit is set in the
2056 2090  .Fa prx_xsh_xstate_bv
2057 2091  entry, then it must be present as its own informational entry otherwise a write
2058 2092  will fail.
2059 2093  If an informational entry is present in a write, but not set in the
2060 2094  .Fa prx_xsh_xstate_bv
2061 2095  then its contents will be ignored.
2062 2096  .Pp
2063 2097  The xregs format currently does not support any compressed items being specified
2064 2098  nor does it specify any, so the
2065 2099  .Fa prx_xsh_xcomp_bv
2066 2100  member will be always set to zero and it and the reserved members
2067 2101  .Fa prx_xsh_reserved
2068 2102  must all be left as zero.
2069 2103  .It Dv PRX_INFO_YMM - Vt prxregset_ymm_t
2070 2104  This structure contains the upper 128-bits of the first 16 %ymm registers
2071 2105  .Pq 8 for 32-bit applications .
2072 2106  To construct a full vector register, it must be combined with the
2073 2107  .Fa prx_fx_xmm
2074 2108  member of the
2075 2109  .Dv PRX_INFO_XSAVE
2076 2110  data.
2077 2111  In 32-bit applications, the reserved registers must be written as zero.
2078 2112  The structure itself looks like:
2079 2113  .Bd -literal -offset 2
2080 2114  typedef struct prxregset_ymm {
2081 2115  #if defined(__amd64)
2082 2116          upad128_t       prx_ymm[16];
2083 2117  #else
2084 2118          upad128_t       prx_ymm[8];
2085 2119          upad128_t       prx_rsvd[8];
2086 2120  #endif
2087 2121  } prxregset_ymm_t;
2088 2122  .Ed
2089 2123  .It Dv PRX_INFO_OPMASK - Vt prxregset_opmask_t
2090 2124  This structure represents one portion of Intel's AVX-512 state: the 8 64-bit
2091 2125  mask registers, %k0 through %k7.
2092 2126  The structure looks like:
2093 2127  .Bd -literal -offset 2
2094 2128  typedef struct prxregset_opmask {
2095 2129          uint64_t        prx_opmask[8];
2096 2130  } prxregset_opmask_t;
2097 2131  .Ed
2098 2132  .It Dv PRX_INFO_ZMM - Vt prxregset_zmm_t
2099 2133  This structure represents one portion of Intel's AVX-512 state: the upper
2100 2134  256 bits of the 512-bit %zmm0 through %zmm15 registers.
2101 2135  Bits 0-127 are found in the
2102 2136  .Fa prx_fx_xmm
2103 2137  member of the
2104 2138  .Dv PRX_INFO_XSAVE
2105 2139  data and bits 128-255 are found in the
2106 2140  .Fa prx_ymm
2107 2141  member of the
2108 2142  .Dv PRX_INFO_YMM .
2109 2143  32-bit applications only have access to %zmm0 through %zmm7.
2110 2144  This structure looks like:
2111 2145  .Bd -literal -offset 2
2112 2146  typedef struct prxregset_zmm {
2113 2147  #if defined(__amd64)
2114 2148          upad256_t       prx_zmm[16];
2115 2149  #else
2116 2150          upad256_t       prx_zmm[8];
2117 2151          upad256_t       prx_rsvd[8];
2118 2152  #endif
2119 2153  } prxregset_zmm_t;
2120 2154  .Ed
2121 2155  .It Dv PRX_INFO_HI_ZMM - Vt prxregset_hi_zmm_t
2122 2156  This structure represents the third portion of Intel's AVX-512 state: the
2123 2157  additional 16 512-bit registers that are available to 64-bit applications, but
2124 2158  not 32-bit applications.
2125 2159  This represents %zmm16 through %zmm31.
2126 2160  This structure looks like:
2127 2161  .Bd -literal -offset indent
2128 2162  typedef struct prxregset_hi_zmm {
2129 2163  #if defined(__amd64)
2130 2164          upad512_t       prx_hi_zmm[16];
2131 2165  #else
2132 2166          upad512_t       prx_rsvd[16];
2133 2167  #endif
2134 2168  } prxregset_hi_zmm_t;
2135 2169  .Pp
2136 2170  Unlike the other lower %zmm registers of %zmm0 through %zmm15, this contains the
2137 2171  entire 512-bit register in one spot and there is no need to look at other
2138 2172  information items to reconstitute the entire vector.
2139 2173  .Ed
2140 2174  .Pp
2141 2175  When setting the extended registers, at least the
2142 2176  .Dv PRX_INFO_XSAVE
2143 2177  component must be present.
2144 2178  None of the component offsets may overlap with the
2145 2179  .Vt prxregset_hdr_t
2146 2180  or any of the
2147 2181  .Vt prxregset_info_t
2148 2182  structures.
2149 2183  In the written data file, it is expected that the various structures start with
2150 2184  their naturally expected alignment, which is most often 16 bytes
2151 2185  .Po
2152 2186  that is the value that the C
2153 2187  .Fn alignof
2154 2188  keyword will return
2155 2189  .Pc .
2156 2190  The structures that we use are all multiples of 16 bytes to make this easier.
2157 2191  The kernel will write out structures with a greater alignment such that the
2158 2192  portions of registers are aligned and safely usable with instructions that move
2159 2193  aligned integers such as vmovdqu64.
2160 2194  .El
2161 2195  .Sh CONTROL MESSAGES
2162 2196  Process state changes are effected through messages written to a process's
2163 2197  .Sy ctl
2164 2198  file or to an individual lwp's
2165 2199  .Sy lwpctl
2166 2200  file.
2167 2201  All control messages consist of a
2168 2202  .Sy long
2169 2203  that names the specific operation followed by
2170 2204  additional data containing the operand, if any.
2171 2205  .Pp
2172 2206  Multiple control messages may be combined in a single
2173 2207  .Xr write 2
2174 2208  (or
2175 2209  .Xr writev 2 )
2176 2210  to a control file, but no partial writes are permitted.
2177 2211  That is, each control message, operation code plus operand, if any, must be
2178 2212  presented in its entirety to the
2179 2213  .Xr write 2
2180 2214  and not in pieces over several system calls.
2181 2215  If a control operation fails, no subsequent operations contained in the same
2182 2216  .Xr write 2
2183 2217  are attempted.
2184 2218  .Pp
2185 2219  Descriptions of the allowable control messages follow.
2186 2220  In all cases, writing a message to a control file for a process or lwp that
2187 2221  has terminated elicits the error
2188 2222  .Er ENOENT .
2189 2223  .Ss PCSTOP PCDSTOP PCWSTOP PCTWSTOP
2190 2224  When applied to the process control file,
2191 2225  .Sy PCSTOP
2192 2226  directs all lwps to stop and waits for them to stop,
2193 2227  .Sy PCDSTOP
2194 2228  directs all lwps to stop without waiting for them to stop, and
2195 2229  .Sy PCWSTOP
2196 2230  simply waits for all lwps to stop.
2197 2231  When applied to an lwp control file,
2198 2232  .Sy PCSTOP
2199 2233  directs the specific lwp to stop and waits until it has stopped,
2200 2234  .Sy PCDSTOP
2201 2235  directs the specific lwp to stop without waiting for it to stop, and
2202 2236  .Sy PCWSTOP
2203 2237  simply waits for the specific lwp to stop.
2204 2238  When applied to an lwp control file,
2205 2239  .Sy PCSTOP
2206 2240  and
2207 2241  .Sy PCWSTOP
2208 2242  complete when the lwp stops on an event of interest, immediately
2209 2243  if already so stopped; when applied to the process control file, they complete
2210 2244  when every lwp has stopped either on an event of interest or on a
2211 2245  .Sy PR_SUSPENDED
2212 2246  stop.
2213 2247  .Pp
2214 2248  .Sy PCTWSTOP
2215 2249  is identical to
2216 2250  .Sy PCWSTOP
2217 2251  except that it enables the operation to time out, to avoid waiting forever for
2218 2252  a process or lwp that may never stop on an event of interest.
2219 2253  .Sy PCTWSTOP
2220 2254  takes a
2221 2255  .Sy long
2222 2256  operand specifying a number of milliseconds; the wait will terminate
2223 2257  successfully after the specified number of milliseconds even if the process or
2224 2258  lwp has not stopped; a timeout value of zero makes the operation identical to
2225 2259  .Sy PCWSTOP .
2226 2260  .Pp
2227 2261  An
2228 2262  .Dq event of interest
2229 2263  is either a
2230 2264  .Sy PR_REQUESTED
2231 2265  stop or a stop that has been specified in the process's tracing flags (set by
2232 2266  .Sy PCSTRACE ,
2233 2267  .Sy PCSFAULT ,
2234 2268  .Sy PCSENTRY ,
2235 2269  and
2236 2270  .Sy PCSEXIT ) .
2237 2271  .Sy PR_JOBCONTROL
2238 2272  and
2239 2273  .Sy PR_SUSPENDED
2240 2274  stops are specifically not events of interest.
2241 2275  (An lwp may stop twice due to a stop signal, first showing
2242 2276  .Sy PR_SIGNALLED
2243 2277  if the signal is traced and again showing
2244 2278  .Sy PR_JOBCONTROL
2245 2279  if the lwp is set running without clearing the signal.)
2246 2280  If
2247 2281  .Sy PCSTOP
2248 2282  or
2249 2283  .Sy PCDSTOP
2250 2284  is applied to an
2251 2285  lwp that is stopped, but not on an event of interest, the stop directive takes
2252 2286  effect when the lwp is restarted by the competing mechanism.
2253 2287  At that time, the lwp enters a
2254 2288  .Sy PR_REQUESTED
2255 2289  stop before executing any user-level code.
2256 2290  .Pp
2257 2291  A write of a control message that blocks is interruptible by a signal so that,
2258 2292  for example, an
2259 2293  .Xr alarm 2
2260 2294  can be set to avoid waiting forever for a
2261 2295  process or lwp that may never stop on an event of interest.
2262 2296  If
2263 2297  .Sy PCSTOP
2264 2298  is interrupted, the lwp stop directives remain in effect even though the
2265 2299  .Xr write 2
2266 2300  returns an error.
2267 2301  (Use of
2268 2302  .Sy PCTWSTOP
2269 2303  with a non-zero timeout is recommended over
2270 2304  .Sy PCWSTOP
2271 2305  with an
2272 2306  .Xr alarm 2 . )
2273 2307  .Pp
2274 2308  A system process (indicated by the
2275 2309  .Sy PR_ISSYS
2276 2310  flag) never executes at user level, has no user-level address space visible
2277 2311  through
2278 2312  .Pa /proc ,
2279 2313  and cannot be stopped.
2280 2314  Applying one of these operations to a system process or any of its
2281 2315  lwps elicits the error
2282 2316  .Er EBUSY .
2283 2317  .Ss PCRUN
2284 2318  Make an lwp runnable again after a stop.
2285 2319  This operation takes a
2286 2320  .Vt long
2287 2321  operand containing zero or more of the following flags:
2288 2322  .Bl -tag -width "PRSABORT" -offset left
2289 2323  .It Sy PRCSIG
2290 2324  clears the current signal, if any (see
2291 2325  .Sx PCCSIG ) .
2292 2326  .It Sy PRCFAULT
2293 2327  clears the current fault, if any (see
2294 2328  .Sx PCCFAULT ) .
2295 2329  .It Sy PRSTEP
2296 2330  directs the lwp to execute a single machine instruction.
2297 2331  On completion of the instruction, a trace trap occurs.
2298 2332  If
2299 2333  .Sy FLTTRACE
2300 2334  is being traced, the lwp stops; otherwise, it is sent
2301 2335  .Sy SIGTRAP .
2302 2336  If
2303 2337  .Sy SIGTRAP
2304 2338  is being traced and is not blocked, the lwp stops.
2305 2339  When the lwp stops on an event of interest,
2306 2340  the single-step directive is cancelled, even if the stop occurs before the
2307 2341  instruction is executed.
2308 2342  This operation requires hardware and operating system
2309 2343  support and may not be implemented on all processors.
2310 2344  It is implemented on SPARC and x86-based machines.
2311 2345  .It Sy PRSABORT
2312 2346  is meaningful only if the lwp is in a
2313 2347  .Sy PR_SYSENTRY
2314 2348  stop or is marked
2315 2349  .Sy PR_ASLEEP ;
2316 2350  it instructs the lwp to abort execution of the system call (see
2317 2351  .Sx PCSENTRY
2318 2352  and
2319 2353  .Sx PCSEXIT ) .
2320 2354  .It Sy PRSTOP
2321 2355  directs the lwp to stop again as soon as possible after resuming execution (see
2322 2356  .Sx PCDSTOP ) .
2323 2357  In particular, if the lwp is stopped on
2324 2358  .Sy PR_SIGNALLED
2325 2359  or
2326 2360  .Sy PR_FAULTED ,
2327 2361  the next stop will show
2328 2362  .Sy PR_REQUESTED ,
2329 2363  no other stop
2330 2364  will have intervened, and the lwp will not have executed any user-level code.
2331 2365  .El
2332 2366  .Pp
2333 2367  When applied to an lwp control file,
2334 2368  .Sy PCRUN
2335 2369  clears any outstanding
2336 2370  directed-stop request and makes the specific lwp runnable.
2337 2371  The operation fails with
2338 2372  .Er EBUSY
2339 2373  if the specific lwp is not stopped on an event of interest or
2340 2374  has not been directed to stop or if the agent lwp exists and this is not the
2341 2375  agent lwp (see
2342 2376  .Sx PCAGENT ) .
2343 2377  .Pp
2344 2378  When applied to the process control file, a representative lwp is chosen for
2345 2379  the operation as described for
2346 2380  .Pa /proc/ Ns Em pid Ns Pa /status .
2347 2381  The operation fails with
2348 2382  .Er EBUSY
2349 2383  if the representative lwp is not stopped on an
2350 2384  event of interest or has not been directed to stop or if the agent lwp exists.
2351 2385  If
2352 2386  .Sy PRSTEP
2353 2387  or
2354 2388  .Sy PRSTOP
2355 2389  was requested, the representative lwp is made
2356 2390  runnable and its outstanding directed-stop request is cleared; otherwise all
2357 2391  outstanding directed-stop requests are cleared and, if it was stopped on an
2358 2392  event of interest, the representative lwp is marked
2359 2393  .Sy PR_REQUESTED .
2360 2394  If, as a consequence, all lwps are in the
2361 2395  .Sy PR_REQUESTED
2362 2396  or
2363 2397  .Sy PR_SUSPENDED
2364 2398  stop state, all lwps showing
2365 2399  .Sy PR_REQUESTED
2366 2400  are made runnable.
2367 2401  .Ss PCSTRACE
2368 2402  Define a set of signals to be traced in the process.
2369 2403  The receipt of one of these signals by an lwp causes the lwp to stop.
2370 2404  The set of signals is defined using an operand
2371 2405  .Sy sigset_t
2372 2406  contained in the control message.
2373 2407  Receipt of
2374 2408  .Sy SIGKILL
2375 2409  cannot be traced; if specified, it is silently ignored.
2376 2410  .Pp
2377 2411  If a signal that is included in an lwp's held signal set (the signal mask) is
2378 2412  sent to the lwp, the signal is not received and does not cause a stop until it
2379 2413  is removed from the held signal set, either by the lwp itself or by setting the
2380 2414  held signal set with
2381 2415  .Sy PCSHOLD .
2382 2416  .Ss PCCSIG
2383 2417  The current signal, if any, is cleared from the specific or representative lwp.
2384 2418  .Ss PCSSIG
2385 2419  The current signal and its associated signal information for the specific or
2386 2420  representative lwp are set according to the contents of the operand
2387 2421  .Vt siginfo
2388 2422  structure (see
2389 2423  .In sys/siginfo.h ) .
2390 2424  If the specified signal number is zero, the current signal is cleared.
2391 2425  The semantics of this operation are different from those of
2392 2426  .Xr kill 2
2393 2427  in that the signal is delivered to the lwp immediately after execution is
2394 2428  resumed (even if it is being blocked) and an additional
2395 2429  .Sy PR_SIGNALLED
2396 2430  stop does not intervene even if the signal is traced.
2397 2431  Setting the current signal to
2398 2432  .Sy SIGKILL
2399 2433  terminates the process immediately.
2400 2434  .Ss PCKILL
2401 2435  If applied to the process control file, a signal is sent to the process with
2402 2436  semantics identical to those of
2403 2437  .Xr kill 2
2404 2438  If applied to an lwp control file, a directed signal is sent to the specific
2405 2439  lwp.
2406 2440  The signal is named in a
2407 2441  .Vt long
2408 2442  operand contained in the message.
2409 2443  Sending
2410 2444  .Sy SIGKILL
2411 2445  terminates the process immediately.
2412 2446  .Ss PCUNKILL
2413 2447  A signal is deleted, that is, it is removed from the set of pending signals.
2414 2448  If applied to the process control file, the signal is deleted from the process's
2415 2449  pending signals.
2416 2450  If applied to an lwp control file, the signal is deleted from
2417 2451  the lwp's pending signals.
2418 2452  The current signal (if any) is unaffected.
2419 2453  The signal is named in a
2420 2454  .Sy long
2421 2455  operand in the control message.
2422 2456  It is an error
2423 2457  .Pq Er EINVAL
2424 2458  to attempt to delete
2425 2459  .Sy SIGKILL .
2426 2460  .Ss PCSHOLD
2427 2461  Set the set of held signals for the specific or representative lwp (signals
2428 2462  whose delivery will be blocked if sent to the lwp).
2429 2463  The set of signals is specified with a
2430 2464  .Vt sigset_t
2431 2465  operand.
2432 2466  .Sy SIGKILL
2433 2467  and
2434 2468  .Sy SIGSTOP
2435 2469  cannot be held; if specified, they are silently ignored.
2436 2470  .Ss PCSFAULT
2437 2471  Define a set of hardware faults to be traced in the process.
2438 2472  On incurring one of these faults, an lwp stops.
2439 2473  The set is defined via the operand
2440 2474  .Vt fltset_t
2441 2475  structure.
2442 2476  Fault names are defined in
2443 2477  .In sys/fault.h
2444 2478  and include the following.
2445 2479  Some of these may not occur on all processors; there may
2446 2480  be processor-specific faults in addition to these.
2447 2481  .Bl -tag -width "FLTACCESS" -offset indent
2448 2482  .It Sy FLTILL
2449 2483  illegal instruction
2450 2484  .It Sy FLTPRIV
2451 2485  privileged instruction
2452 2486  .It Sy FLTBPT
2453 2487  breakpoint trap
2454 2488  .It Sy FLTTRACE
2455 2489  trace trap (single-step)
2456 2490  .It Sy FLTWATCH
2457 2491  watchpoint trap
2458 2492  .It Sy FLTACCESS
2459 2493  memory access fault (bus error)
2460 2494  .It Sy FLTBOUNDS
2461 2495  memory bounds violation
2462 2496  .It Sy FLTIOVF
2463 2497  integer overflow
2464 2498  .It Sy FLTIZDIV
2465 2499  integer zero divide
2466 2500  .It Sy FLTFPE
2467 2501  floating-point exception
2468 2502  .It Sy FLTSTACK
2469 2503  unrecoverable stack fault
2470 2504  .It Sy FLTPAGE
2471 2505  recoverable page fault
2472 2506  .El
2473 2507  .Pp
2474 2508  When not traced, a fault normally results in the posting of a signal to the lwp
2475 2509  that incurred the fault.
2476 2510  If an lwp stops on a fault, the signal is posted to
2477 2511  the lwp when execution is resumed unless the fault is cleared by
2478 2512  .Sy PCCFAULT
2479 2513  or by the
2480 2514  .Sy PRCFAULT
2481 2515  option of
2482 2516  .Sy PCRUN .
2483 2517  .Sy FLTPAGE
2484 2518  is an exception; no signal is posted.
2485 2519  The
2486 2520  .Sy pr_info
2487 2521  field in the
2488 2522  .Vt lwpstatus
2489 2523  structure identifies the signal to be sent and contains machine-specific
2490 2524  information about the fault.
2491 2525  .Ss PCCFAULT
2492 2526  The current fault, if any, is cleared; the associated signal will not be sent
2493 2527  to the specific or representative lwp.
2494 2528  .Ss PCSENTRY PCSEXIT
2495 2529  These control operations instruct the process's lwps to stop on entry to or
2496 2530  exit from specified system calls.
2497 2531  The set of system calls to be traced is defined via an operand
2498 2532  .Vt sysset_t
2499 2533  structure.
2500 2534  .Pp
2501 2535  When entry to a system call is being traced, an lwp stops after having begun
2502 2536  the call to the system but before the system call arguments have been fetched
2503 2537  from the lwp.
2504 2538  When exit from a system call is being traced, an lwp stops on completion of
2505 2539  the system call just prior to checking for signals and returning to user level.
2506 2540  At this point, all return values have been stored into the lwp's registers.
2507 2541  .Pp
2508 2542  If an lwp is stopped on entry to a system call
2509 2543  .Pq Sy PR_SYSENTRY
2510 2544  or when sleeping in an interruptible system call
2511 2545  .Pf ( Sy PR_ASLEEP
2512 2546  is set), it may be instructed to go directly to system call exit by specifying
2513 2547  the
2514 2548  .Sy PRSABORT
2515 2549  flag in a
2516 2550  .Sy PCRUN
2517 2551  control message.
2518 2552  Unless exit from the system call is being traced, the lwp returns to user
2519 2553  level showing
2520 2554  .Er EINTR .
2521 2555  .Ss PCWATCH
2522 2556  Set or clear a watched area in the controlled process from a
2523 2557  .Vt prwatch
2524 2558  structure operand:
2525 2559  .Bd -literal -offset 2
2526 2560  typedef struct prwatch {
2527 2561      uintptr_t pr_vaddr;  /* virtual address of watched area */
2528 2562      size_t pr_size;      /* size of watched area in bytes */
2529 2563      int pr_wflags;       /* watch type flags */
2530 2564  } prwatch_t;
2531 2565  .Ed
2532 2566  .Pp
2533 2567  .Sy pr_vaddr
2534 2568  specifies the virtual address of an area of memory to be watched
2535 2569  in the controlled process.
2536 2570  .Sy pr_size
2537 2571  specifies the size of the area, in bytes.
2538 2572  .Sy pr_wflags
2539 2573  specifies the type of memory access to be monitored as a
2540 2574  bit-mask of the following flags:
2541 2575  .Bl -tag -width "WA_TRAPAFTER" -offset indent
2542 2576  .It Sy WA_READ
2543 2577  read access
2544 2578  .It Sy WA_WRITE
2545 2579  write access
2546 2580  .It Sy WA_EXEC
2547 2581  execution access
2548 2582  .It Sy WA_TRAPAFTER
2549 2583  trap after the instruction completes
2550 2584  .El
2551 2585  .Pp
2552 2586  If
2553 2587  .Sy pr_wflags
2554 2588  is non-empty, a watched area is established for the virtual
2555 2589  address range specified by
2556 2590  .Sy pr_vaddr
2557 2591  and
2558 2592  .Sy pr_size .
2559 2593  If
2560 2594  .Sy pr_wflags
2561 2595  is empty, any previously-established watched area starting at the specified
2562 2596  virtual address is cleared;
2563 2597  .Sy pr_size
2564 2598  is ignored.
2565 2599  .Pp
2566 2600  A watchpoint is triggered when an lwp in the traced process makes a memory
2567 2601  reference that covers at least one byte of a watched area and the memory
2568 2602  reference is as specified in
2569 2603  .Sy pr_wflags .
2570 2604  When an lwp triggers a watchpoint, it incurs a watchpoint trap.
2571 2605  If
2572 2606  .Sy FLTWATCH
2573 2607  is being traced, the lwp stops; otherwise, it is sent a
2574 2608  .Sy SIGTRAP
2575 2609  signal; if
2576 2610  .Sy SIGTRAP
2577 2611  is being traced and is not blocked, the lwp stops.
2578 2612  .Pp
2579 2613  The watchpoint trap occurs before the instruction completes unless
2580 2614  .Sy WA_TRAPAFTER
2581 2615  was specified, in which case it occurs after the instruction completes.
2582 2616  If it occurs before completion, the memory is not modified.
2583 2617  If it occurs after completion, the memory is modified (if the access is a write
2584 2618  access).
2585 2619  .Pp
2586 2620  Physical i/o is an exception for watchpoint traps.
2587 2621  In this instance, there is no guarantee that memory before the watched area
2588 2622  has already been modified (or in the case of
2589 2623  .Sy WA_TRAPAFTER ,
2590 2624  that the memory following the watched area
2591 2625  has not been modified) when the watchpoint trap occurs and the lwp stops.
2592 2626  .Pp
2593 2627  .Sy pr_info
2594 2628  in the
2595 2629  .Vt lwpstatus
2596 2630  structure contains information pertinent to the watchpoint trap.
2597 2631  In particular, the
2598 2632  .Sy si_addr
2599 2633  field contains the
2600 2634  virtual address of the memory reference that triggered the watchpoint, and the
2601 2635  .Sy si_code
2602 2636  field contains one of
2603 2637  .Sy TRAP_RWATCH ,
2604 2638  .Sy TRAP_WWATCH ,
2605 2639  or
2606 2640  .Sy TRAP_XWATCH ,
2607 2641  indicating read, write, or execute access, respectively.
2608 2642  The
2609 2643  .Sy si_trapafter
2610 2644  field is zero unless
2611 2645  .Sy WA_TRAPAFTER
2612 2646  is in effect for this watched area; non-zero indicates that the current
2613 2647  instruction is not the instruction that incurred the watchpoint trap.
2614 2648  The
2615 2649  .Sy si_pc
2616 2650  field contains the virtual address of the instruction that incurred the trap.
2617 2651  .Pp
2618 2652  A watchpoint trap may be triggered while executing a system call that makes
2619 2653  reference to the traced process's memory.
2620 2654  The lwp that is executing the system call incurs the watchpoint trap while
2621 2655  still in the system call.
2622 2656  If it stops as a result, the
2623 2657  .Vt lwpstatus
2624 2658  structure contains the system call number and its arguments.
2625 2659  If the lwp does not stop, or if it is set running again without
2626 2660  clearing the signal or fault, the system call fails with
2627 2661  .Er EFAULT .
2628 2662  If
2629 2663  .Sy WA_TRAPAFTER
2630 2664  was specified, the memory reference will have completed and
2631 2665  the memory will have been modified (if the access was a write access) when the
2632 2666  watchpoint trap occurs.
2633 2667  .Pp
2634 2668  If more than one of
2635 2669  .Sy WA_READ ,
2636 2670  .Sy WA_WRITE ,
2637 2671  and
2638 2672  .Sy WA_EXEC
2639 2673  is specified for a watched area, and a single instruction incurs more than one
2640 2674  of the specified types, only one is reported when the watchpoint trap occurs.
2641 2675  The precedence is
2642 2676  .Sy WA_EXEC ,
2643 2677  .Sy WA_READ ,
2644 2678  .Sy WA_WRITE
2645 2679  .Pf ( Sy WA_EXEC
2646 2680  and
2647 2681  .Sy WA_READ
2648 2682  take precedence over
2649 2683  .Sy WA_WRITE ) ,
2650 2684  unless
2651 2685  .Sy WA_TRAPAFTER
2652 2686  was specified, in which case it is
2653 2687  .Sy WA_WRITE ,
2654 2688  .Sy WA_READ ,
2655 2689  .Sy WA_EXEC
2656 2690  .Pf ( Sy WA_WRITE
2657 2691  takes precedence).
2658 2692  .Pp
2659 2693  .Sy PCWATCH
2660 2694  fails with
2661 2695  .Er EINVAL
2662 2696  if an attempt is made to specify overlapping watched areas or if
2663 2697  .Sy pr_wflags
2664 2698  contains flags other than those specified above.
2665 2699  It fails with
2666 2700  .Er ENOMEM
2667 2701  if an attempt is made to establish more watched areas than the system can
2668 2702  support (the system can support thousands).
2669 2703  .Pp
2670 2704  The child of a
2671 2705  .Xr vfork 2
2672 2706  borrows the parent's address space.
2673 2707  When a
2674 2708  .Xr vfork 2
2675 2709  is executed by a traced process, all watched areas established
2676 2710  for the parent are suspended until the child terminates or performs an
2677 2711  .Xr exec 2 .
2678 2712  Any watched areas established independently in the child are
2679 2713  cancelled when the parent resumes after the child's termination or
2680 2714  .Xr exec 2 .
2681 2715  .Sy PCWATCH
2682 2716  fails with
2683 2717  .Er EBUSY
2684 2718  if applied to the parent of a
2685 2719  .Xr vfork 2
2686 2720  before the child has terminated or performed an
2687 2721  .Xr exec 2 .
2688 2722  The
2689 2723  .Sy PR_VFORKP
2690 2724  flag is set in the
2691 2725  .Sy pstatus
2692 2726  structure for such a parent process.
2693 2727  .Pp
2694 2728  Certain accesses of the traced process's address space by the operating system
2695 2729  are immune to watchpoints.
2696 2730  The initial construction of a signal stack frame when a signal is delivered to
2697 2731  an lwp will not trigger a watchpoint trap even if the new frame covers watched
2698 2732  areas of the stack.
2699 2733  Once the signal handler is entered, watchpoint traps occur normally.
2700 2734  On SPARC based machines, register window overflow and underflow will not
2701 2735  trigger watchpoint traps, even if the register window save areas cover watched
2702 2736  areas of the stack.
2703 2737  .Pp
2704 2738  Watched areas are not inherited by child processes, even if the traced
2705 2739  process's inherit-on-fork mode,
2706 2740  .Sy PR_FORK ,
2707 2741  is set (see
2708 2742  .Sy PCSET ,
2709 2743  below).
2710 2744  All watched areas are cancelled when the traced process performs a successful
2711 2745  .Xr exec 2 .
2712 2746  .Ss PCSET PCUNSET
2713 2747  .Sy PCSET
2714 2748  sets one or more modes of operation for the traced process.
2715 2749  .Sy PCUNSET
2716 2750  unsets these modes.
2717 2751  The modes to be set or unset are specified by flags in an operand
2718 2752  .Sy long
2719 2753  in the control message:
2720 2754  .Bl -tag -offset left -width "PR_MSFORK"
2721 2755  .It Sy PR_FORK
2722 2756  (inherit-on-fork): When set, the process's tracing flags and its
2723 2757  inherit-on-fork mode are inherited by the child of a
2724 2758  .Xr fork 2 ,
2725 2759  .Xr fork1 2 ,
2726 2760  or
2727 2761  .Xr vfork 2 .
2728 2762  When unset, child processes start with all tracing flags cleared.
2729 2763  .It Sy PR_RLC
2730 2764  (run-on-last-close): When set and the last writable
2731 2765  .Pa /proc
2732 2766  file descriptor referring to the traced process or any of its lwps is closed,
2733 2767  all of the process's tracing flags and watched areas are cleared, any
2734 2768  outstanding stop directives are canceled, and if any lwps are stopped on
2735 2769  events of interest, they are set running as though
2736 2770  .Sy PCRUN
2737 2771  had been applied to them.
2738 2772  When unset, the process's tracing flags and watched areas are retained and
2739 2773  lwps are not set running on last close.
2740 2774  .It Sy PR_KLC
2741 2775  (kill-on-last-close): When set and the last writable
2742 2776  .Pa /proc
2743 2777  file descriptor referring to the traced process or any of its lwps is closed,
2744 2778  the process is terminated with
2745 2779  .Sy SIGKILL .
2746 2780  .It Sy PR_ASYNC
2747 2781  (asynchronous-stop): When set, a stop on an event of interest by one lwp does
2748 2782  not directly affect any other lwp in the process.
2749 2783  When unset and an lwp stops on an event of interest other than
2750 2784  .Sy PR_REQUESTED ,
2751 2785  all other lwps in the process are directed to stop.
2752 2786  .It Sy PR_MSACCT
2753 2787  (microstate accounting): Microstate accounting is now continuously enabled.
2754 2788  This flag is deprecated and no longer has any effect upon microstate
2755 2789  accounting.
2756 2790  Applications may toggle this flag; however, microstate accounting
2757 2791  will remain enabled regardless.
2758 2792  .It Sy PR_MSFORK
2759 2793  (inherit microstate accounting): All processes now inherit microstate
2760 2794  accounting, as it is continuously enabled.
2761 2795  This flag has been deprecated and its use no longer has any effect upon the
2762 2796  behavior of microstate accounting.
2763 2797  .It Sy PR_BPTADJ
2764 2798  (breakpoint trap pc adjustment): On x86-based machines, a breakpoint trap
2765 2799  leaves the program counter (the
2766 2800  .Sy EIP )
2767 2801  referring to the breakpointed instruction plus one byte.
2768 2802  When
2769 2803  .Sy PR_BPTADJ
2770 2804  is set, the system will adjust the program counter back to the location of the
2771 2805  breakpointed instruction when the lwp stops on a breakpoint.
2772 2806  This flag has no effect on SPARC based machines, where breakpoint traps leave
2773 2807  the program counter referring to the breakpointed instruction.
2774 2808  .It Sy PR_PTRACE
2775 2809  (ptrace-compatibility): When set, a stop on an event of interest by the traced
2776 2810  process is reported to the parent of the traced process by
2777 2811  .Xr wait 3C ,
2778 2812  .Sy SIGTRAP
2779 2813  is sent to the traced process when it executes a successful
2780 2814  .Xr exec 2 ,
2781 2815  setuid/setgid flags are not honored for execs performed by the
2782 2816  traced process, any exec of an object file that the traced process cannot read
2783 2817  fails, and the process dies when its parent dies.
2784 2818  This mode is deprecated; it is provided only to allow
2785 2819  .Xr ptrace 3C
2786 2820  to be implemented as a library function using
2787 2821  .Pa /proc .
2788 2822  .El
2789 2823  .Pp
2790 2824  It is an error
2791 2825  .Pq Er EINVAL
2792 2826  to specify flags other than those described above
2793 2827  or to apply these operations to a system process.
2794 2828  The current modes are reported in the
2795 2829  .Sy pr_flags
2796 2830  field of
2797 2831  .Pa /proc/ Ns Em pid Ns Pa /status
2798 2832  and
2799 2833  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwp Ns Pa /lwpstatus .
2800 2834  .Ss PCSREG
2801 2835  Set the general registers for the specific or representative lwp according to
2802 2836  the operand
2803 2837  .Vt prgregset_t
2804 2838  structure.
2805 2839  .Pp
2806 2840  On SPARC based systems, only the condition-code bits of the processor-status
2807 2841  register (R_PSR) of SPARC V8 (32-bit) processes can be modified by
2808 2842  .Sy PCSREG .
2809 2843  Other privileged registers cannot be modified at all.
2810 2844  .Pp
2811 2845  On x86-based systems, only certain bits of the flags register (EFL) can be
2812 2846  modified by
2813 2847  .Sy PCSREG :
2814 2848  these include the condition codes, direction-bit, and overflow-bit.
2815 2849  .Pp
2816 2850  .Sy PCSREG
2817 2851  fails with
2818 2852  .Er EBUSY
2819 2853  if the lwp is not stopped on an event of interest.
2820 2854  .Ss PCSVADDR
2821 2855  Set the address at which execution will resume for the specific or
2822 2856  representative lwp from the operand
2823 2857  .Vt long .
2824 2858  On SPARC based systems, both %pc and %npc are set, with %npc set to the
2825 2859  instruction following the virtual address.
2826 2860  On x86-based systems, only %eip is set.
2827 2861  .Sy PCSVADDR
2828 2862  fails with
2829 2863  .Er EBUSY
2830 2864  if the lwp is not stopped on an event of interest.
2831 2865  .Ss PCSFPREG
2832 2866  Set the floating-point registers for the specific or representative lwp
2833 2867  according to the operand
2834 2868  .Vt prfpregset_t
2835 2869  structure.
2836 2870  An error
2837 2871  .Pq Er EINVAL
2838 2872  is returned if the system does not support floating-point operations (no
2839 2873  floating-point hardware and the system does not emulate floating-point machine
2840 2874  instructions).
2841 2875  .Sy PCSFPREG
2842 2876  fails with
2843 2877  .Er EBUSY
2844 2878  if the lwp is not stopped on an event of interest.
2845 2879  .Ss PCSXREG
2846 2880  Set the extra state registers for the specific or representative lwp according
2847 2881  to the architecture-dependent operand
2848 2882  .Vt prxregset_t
2849 2883  structure.
2850 2884  An error
2851 2885  .Pq Er EINVAL
2852 2886  is returned if the system does not support extra state registers or the register
2853 2887  state is invalid.
2854 2888  .Sy PCSXREG
2855 2889  fails with
2856 2890  .Er EBUSY
2857 2891  if the lwp is not stopped on an event of interest.
2858 2892  .Ss PCSASRS
2859 2893  Set the ancillary state registers for the specific or representative lwp
2860 2894  according to the SPARC V9 platform-dependent operand
2861 2895  .Vt asrset_t
2862 2896  structure.
2863 2897  An error
2864 2898  .Pq Er EINVAL
2865 2899  is returned if either the target process or the
2866 2900  controlling process is not a 64-bit SPARC V9 process.
2867 2901  Most of the ancillary state registers are privileged registers that cannot be
2868 2902  modified.
2869 2903  Only those that can be modified are set; all others are silently ignored.
2870 2904  .Sy PCSASRS
2871 2905  fails with
2872 2906  .Er EBUSY
2873 2907  if the lwp is not stopped on an event of interest.
2874 2908  .Ss PCAGENT
2875 2909  Create an agent lwp in the controlled process with register values from the
2876 2910  operand
2877 2911  .Vt prgregset_t
2878 2912  structure (see
2879 2913  .Sy PCSREG ,
2880 2914  above).
2881 2915  The agent lwp is created in the stopped state showing
2882 2916  .Sy PR_REQUESTED
2883 2917  and with its held signal set (the signal mask) having all signals except
2884 2918  .Sy SIGKILL
2885 2919  and
2886 2920  .Sy SIGSTOP
2887 2921  blocked.
2888 2922  .Pp
2889 2923  The
2890 2924  .Sy PCAGENT
2891 2925  operation fails with
2892 2926  .Er EBUSY
2893 2927  unless the process is fully stopped via
2894 2928  .Pa /proc ,
2895 2929  that is, unless all of the lwps in the process are
2896 2930  stopped either on events of interest or on
2897 2931  .Sy PR_SUSPENDED ,
2898 2932  or are stopped on
2899 2933  .Sy PR_JOBCONTROL
2900 2934  and have been directed to stop via
2901 2935  .Sy PCDSTOP .
2902 2936  It fails with
2903 2937  .Er EBUSY
2904 2938  if an agent lwp already exists.
2905 2939  It fails with
2906 2940  .Er ENOMEM
2907 2941  if system resources for creating new lwps have been exhausted.
2908 2942  .Pp
2909 2943  Any
2910 2944  .Sy PCRUN
2911 2945  operation applied to the process control file or to the control
2912 2946  file of an lwp other than the agent lwp fails with
2913 2947  .Er EBUSY
2914 2948  as long as the agent lwp exists.
2915 2949  The agent lwp must be caused to terminate by executing the
2916 2950  .Sy SYS_lwp_exit
2917 2951  system call trap before the process can be restarted.
2918 2952  .Pp
2919 2953  Once the agent lwp is created, its lwp-ID can be found by reading the process
2920 2954  status file.
2921 2955  To facilitate opening the agent lwp's control and status files,
2922 2956  the directory name
2923 2957  .Pa /proc/ Ns Em pid Ns Pa /lwp/agent
2924 2958  is accepted for lookup operations as an invisible alias for
2925 2959  .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid ,
2926 2960  .Em lwpid
2927 2961  being the lwp-ID of the agent lwp (invisible in the sense that the name
2928 2962  .Dq agent
2929 2963  does not appear in a directory listing of
2930 2964  .Pa /proc/ Ns Em pid Ns Pa /lwp
2931 2965  obtained from
2932 2966  .Xr ls 1 ,
2933 2967  .Xr getdents 2 ,
2934 2968  or
2935 2969  .Xr readdir 3C .
2936 2970  .Pp
2937 2971  The purpose of the agent lwp is to perform operations in the controlled process
2938 2972  on behalf of the controlling process: to gather information not directly
2939 2973  available via
2940 2974  .Pa /proc
2941 2975  files, or in general to make the process change state
2942 2976  in ways not directly available via
2943 2977  .Pa /proc
2944 2978  control operations.
2945 2979  To make use of an agent lwp, the controlling process must be capable of making
2946 2980  it execute system calls (specifically, the
2947 2981  .Sy SYS_lwp_exit
2948 2982  system call trap).
2949 2983  The register values given to the agent lwp on creation are typically the
2950 2984  registers of the representative lwp, so that the agent lwp can use its stack.
2951 2985  .Pp
2952 2986  If the controlling process neglects to force the agent lwp to execute the
2953 2987  .Sy SYS_lwp_exit
2954 2988  system call (due to either logic error or fatal failure on
2955 2989  the part of the controlling process), the agent lwp will remain in the target
2956 2990  process.
2957 2991  For purposes of being able to debug these otherwise rogue agents,
2958 2992  information as to the creator of the agent lwp is reflected in that lwp's
2959 2993  .Pa spymaster
2960 2994  file in
2961 2995  .Pa /proc .
2962 2996  Should the target process generate a core
2963 2997  dump with the agent lwp in place, this information will be available via the
2964 2998  .Sy NT_SPYMASTER
2965 2999  note in the core file (see
2966 3000  .Xr core 5 ) .
2967 3001  .Pp
2968 3002  The agent lwp is not allowed to execute any variation of the
2969 3003  .Sy SYS_fork
2970 3004  or
2971 3005  .Sy SYS_exec
2972 3006  system call traps.
2973 3007  Attempts to do so yield
2974 3008  .Er ENOTSUP
2975 3009  to the agent lwp.
2976 3010  .Pp
2977 3011  Symbolic constants for system call trap numbers like
2978 3012  .Sy SYS_lwp_exit
2979 3013  and
2980 3014  .Sy SYS_lwp_create
2981 3015  can be found in the header file
2982 3016  .In sys/syscall.h .
2983 3017  .Ss PCREAD PCWRITE
2984 3018  Read or write the target process's address space via a
2985 3019  .Vt priovec
2986 3020  structure operand:
2987 3021  .Bd -literal -offset 2
2988 3022  typedef struct priovec {
2989 3023      void *pio_base;      /* buffer in controlling process */
2990 3024      size_t pio_len;      /* size of read/write request in bytes */
2991 3025      off_t pio_offset;    /* virtual address in target process */
2992 3026  } priovec_t;
2993 3027  .Ed
2994 3028  .Pp
2995 3029  These operations have the same effect as
2996 3030  .Xr pread 2
2997 3031  and
2998 3032  .Xr pwrite 2 ,
2999 3033  respectively, of the target process's address space file.
3000 3034  The difference is that more than one
3001 3035  .Sy PCREAD
3002 3036  or
3003 3037  .Sy PCWRITE
3004 3038  control operation can be
3005 3039  written to the control file at once, and they can be interspersed with other
3006 3040  control operations in a single write to the control file.
3007 3041  This is useful, for example, when planting many breakpoint instructions in
3008 3042  the process's address space, or when stepping over a breakpointed instruction.
3009 3043  Unlike
3010 3044  .Xr pread 2
3011 3045  and
3012 3046  .Xr pwrite 2 ,
3013 3047  no provision is made for partial reads or writes; if the
3014 3048  operation cannot be performed completely, it fails with
3015 3049  .Er EIO .
3016 3050  .Ss PCNICE
3017 3051  The traced process's
3018 3052  .Xr nice 2
3019 3053  value is incremented by the amount in the
3020 3054  operand
3021 3055  .Vt long .
3022 3056  Only a process with the
3023 3057  .Brq Sy PRIV_PROC_PRIOCNTL
3024 3058  privilege asserted in its effective set can better a process's priority in this
3025 3059  way, but any user may lower the priority.
3026 3060  This operation is not meaningful for all scheduling classes.
3027 3061  .Ss PCSCRED
3028 3062  Set the target process credentials to the values contained in the
3029 3063  .Vt prcred_t
3030 3064  structure operand (see
3031 3065  .Pa /proc/ Ns Em pid Ns Pa /cred ) .
3032 3066  The
3033 3067  effective, real, and saved user-IDs and group-IDs of the target process are
3034 3068  set.
3035 3069  The target process's supplementary groups are not changed; the
3036 3070  .Sy pr_ngroups
3037 3071  and
3038 3072  .Sy pr_groups
3039 3073  members of the structure operand are ignored.
3040 3074  Only the privileged processes can perform this operation; for all
3041 3075  others it fails with
3042 3076  .Er EPERM .
3043 3077  .Ss PCSCREDX
3044 3078  Operates like
3045 3079  .Sy PCSCRED
3046 3080  but also sets the supplementary groups; the length
3047 3081  of the data written with this control operation should be "sizeof
3048 3082  .Pq Vt prcred_t
3049 3083  + sizeof
3050 3084  .Pq Vt gid_t
3051 3085  * (#groups - 1)".
3052 3086  .Ss PCSPRIV
3053 3087  Set the target process privilege to the values contained in the
3054 3088  .Vt prpriv_t
3055 3089  operand (see
3056 3090  .Pa /proc/pid/priv ) .
3057 3091  The effective, permitted, inheritable, and
3058 3092  limit sets are all changed.
3059 3093  Privilege flags can also be set.
3060 3094  The process is made privilege aware unless it can relinquish privilege awareness.
3061 3095  See
3062 3096  .Xr privileges 7 .
3063 3097  .Pp
3064 3098  The limit set of the target process cannot be grown.
3065 3099  The other privilege sets must be subsets of the intersection of the effective set
3066 3100  of the calling process with the new limit set of the target process or subsets of
3067 3101  the original values of the sets in the target process.
3068 3102  .Pp
3069 3103  If any of the above restrictions are not met,
3070 3104  .Er EPERM
3071 3105  is returned.
3072 3106  If the structure written is improperly formatted,
3073 3107  .Er EINVAL
3074 3108  is returned.
3075 3109  .Sh PROGRAMMING NOTES
3076 3110  For security reasons, except for the
3077 3111  .Sy psinfo ,
3078 3112  .Sy usage ,
3079 3113  .Sy lpsinfo ,
3080 3114  .Sy lusage ,
3081 3115  .Sy lwpsinfo ,
3082 3116  and
3083 3117  .Sy lwpusage
3084 3118  files, which are world-readable, and except for privileged processes, an open
3085 3119  of a
3086 3120  .Pa /proc
3087 3121  file fails unless both the user-ID and group-ID of the caller match those of
3088 3122  the traced process and the process's object file is readable by the caller.
3089 3123  The effective set of the caller is a superset of both the inheritable and the
3090 3124  permitted set of the target process.
3091 3125  The limit set of the caller is a superset of the limit set of the target
3092 3126  process.
3093 3127  Except for the world-readable files just mentioned, files corresponding to
3094 3128  setuid and setgid processes can be opened only by the appropriately privileged
3095 3129  process.
3096 3130  .Pp
3097 3131  A process that is missing the basic privilege
3098 3132  .Brq Sy PRIV_PROC_INFO
3099 3133  cannot see any processes under
3100 3134  .Pa /proc
3101 3135  that it cannot send a signal to.
3102 3136  .Pp
3103 3137  A process that has
3104 3138  .Brq Sy PRIV_PROC_OWNER
3105 3139  asserted in its effective set can open any file for reading.
3106 3140  To manipulate or control a process, the controlling process must have at least
3107 3141  as many privileges in its effective set as the target process has in its
3108 3142  effective, inheritable, and permitted sets.
3109 3143  The limit set of the controlling process must be a superset of the limit set
3110 3144  of the target process.
3111 3145  Additional restrictions apply if any of the uids of the target process are 0.
3112 3146  See
3113 3147  .Xr privileges 7 .
3114 3148  .Pp
3115 3149  Even if held by a privileged process, an open process or lwp file descriptor
3116 3150  (other than file descriptors for the world-readable files) becomes invalid if
3117 3151  the traced process performs an
3118 3152  .Xr exec 2
3119 3153  of a setuid/setgid object file or
3120 3154  an object file that the traced process cannot read.
3121 3155  Any operation performed on an invalid file descriptor, except
3122 3156  .Xr close 2 ,
3123 3157  fails with
3124 3158  .Er EAGAIN .
3125 3159  In this situation, if any tracing flags are set and the process or any lwp
3126 3160  file descriptor is open for writing, the process will have been directed to
3127 3161  stop and its run-on-last-close flag will have been set (see
3128 3162  .Sx PCSET ) .
3129 3163  This enables a controlling process (if it has permission) to reopen the
3130 3164  .Pa /proc
3131 3165  files to get new valid file descriptors, close the invalid file descriptors,
3132 3166  unset the run-on-last-close flag (if desired), and proceed.
3133 3167  Just closing the invalid file descriptors causes the traced process to resume
3134 3168  execution with all tracing flags cleared.
3135 3169  Any process not currently open for writing via
3136 3170  .Pa /proc ,
3137 3171  but that has left-over tracing flags from a previous open, and that executes
3138 3172  a setuid/setgid or unreadable object file, will not be stopped but will have
3139 3173  all its tracing flags cleared.
3140 3174  .Pp
3141 3175  To wait for one or more of a set of processes or lwps to stop or terminate,
3142 3176  .Pa /proc
3143 3177  file descriptors (other than those obtained by opening the
3144 3178  .Pa cwd
3145 3179  or
3146 3180  .Pa root
3147 3181  directories or by opening files in the
3148 3182  .Pa fd
3149 3183  or
3150 3184  .Pa object
3151 3185  directories) can be used in a
3152 3186  .Xr poll 2
3153 3187  system call.
3154 3188  When requested and returned, either of the polling events
3155 3189  .Sy POLLPRI
3156 3190  or
3157 3191  .Sy POLLWRNORM
3158 3192  indicates that the process or lwp stopped on an event of
3159 3193  interest.
3160 3194  Although they cannot be requested, the polling events
3161 3195  .Sy POLLHUP ,
3162 3196  .Sy POLLERR ,
3163 3197  and
3164 3198  .Sy POLLNVAL
3165 3199  may be returned.
3166 3200  .Sy POLLHUP
3167 3201  indicates that the process or lwp has terminated.
3168 3202  .Sy POLLERR
3169 3203  indicates that the file descriptor has become invalid.
3170 3204  .Sy POLLNVAL
3171 3205  is returned immediately if
3172 3206  .Sy POLLPRI
3173 3207  or
3174 3208  .Sy POLLWRNORM
3175 3209  is requested on a file descriptor referring to a system process (see
3176 3210  .Sx  PCSTOP ) .
3177 3211  The requested events may be empty to wait simply for termination.
3178 3212  .Sh FILES
3179 3213  .Bl -tag -compact -width Ds
3180 3214  .It Pa /proc
3181 3215  directory (list of processes)
3182 3216  .It Pa /proc/ Ns Em pid
3183 3217  specific process directory
3184 3218  .It Pa /proc/self
3185 3219  alias for a process's own directory
3186 3220  .It Pa /proc/ Ns Em pid Ns Pa /as
3187 3221  address space file
3188 3222  .It Pa /proc/ Ns Em pid Ns Pa /ctl
3189 3223  process control file
3190 3224  .It Pa /proc/ Ns Em pid Ns Pa /status
3191 3225  process status
3192 3226  .It Pa /proc/ Ns Em pid Ns Pa /lstatus
3193 3227  array of lwp status structs
3194 3228  .It Pa /proc/ Ns Em pid Ns Pa /psinfo
3195 3229  process
3196 3230  .Xr ps 1
3197 3231  info
3198 3232  .It Pa /proc/ Ns Em pid Ns Pa /lpsinfo
3199 3233  array of lwp
3200 3234  .Xr ps 1
3201 3235  info structs
3202 3236  .It Pa /proc/ Ns Em pid Ns Pa /map
3203 3237  address space map
3204 3238  .It Pa /proc/ Ns Em pid Ns Pa /xmap
3205 3239  extended address space map

3206 3240  .It Pa /proc/ Ns Em pid Ns Pa /rmap
3207 3241  reserved address map
3208 3242  .It Pa /proc/ Ns Em pid Ns Pa /cred
3209 3243  process credentials
3210 3244  .It Pa /proc/ Ns Em pid Ns Pa /priv
3211 3245  process privileges
3212 3246  .It Pa /proc/ Ns Em pid Ns Pa /sigact
3213 3247  process signal actions
3214 3248  .It Pa /proc/ Ns Em pid Ns Pa /auxv
3215 3249  process aux vector
     3250 +.It Pa /proc/ Ns Em pid Ns Pa /argv
     3251 +process argument vector
3216 3252  .It Pa /proc/ Ns Em pid Ns Pa /ldt
3217 3253  process
3218 3254  .Sy LDT
3219 3255  (x86 only)
3220 3256  .It Pa /proc/ Ns Em pid Ns Pa /usage
3221 3257  process usage
3222 3258  .It Pa /proc/ Ns Em pid Ns Pa /lusage
3223 3259  array of lwp usage structs
3224 3260  .It Pa /proc/ Ns Em pid Ns Pa /path
3225 3261  symbolic links to process open files

3226 3262  .It Pa /proc/ Ns Em pid Ns Pa /pagedata
3227 3263  process page data
3228 3264  .It Pa /proc/ Ns Em pid Ns Pa /watch
3229 3265  active watchpoints
3230 3266  .It Pa /proc/ Ns Em pid Ns Pa /cwd
3231 3267  alias for the current working directory
3232 3268  .It Pa /proc/ Ns Em pid Ns Pa /root
3233 3269  alias for the root directory
3234 3270  .It Pa /proc/ Ns Em pid Ns Pa /fd
3235 3271  directory (list of open files)
3236 3272  .It Pa /proc/ Ns Em pid Ns Pa /fd/*
3237 3273  aliases for process's open files
3238 3274  .It Pa /proc/ Ns Em pid Ns Pa /object
3239 3275  directory (list of mapped files)
3240 3276  .It Pa /proc/ Ns Em pid Ns Pa /object/a.out
3241 3277  alias for process's executable file
3242 3278  .It Pa /proc/ Ns Em pid Ns Pa /object/*
3243 3279  aliases for other mapped files
3244 3280  .It Pa /proc/ Ns Em pid Ns Pa /lwp
3245 3281  directory (list of lwps)
3246 3282  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid
3247 3283  specific lwp directory
3248 3284  .It Pa /proc/ Ns Em pid Ns Pa /lwp/agent
3249 3285  alias for the agent lwp directory
3250 3286  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpctl
3251 3287  lwp control file
3252 3288  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpstatus
3253 3289  lwp status
3254 3290  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpsinfo
3255 3291  lwp
3256 3292  .Xr ps 1
3257 3293  info
3258 3294  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpusage
3259 3295  lwp usage
3260 3296  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /gwindows
3261 3297  register windows (SPARC only)
3262 3298  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /xregs
3263 3299  extra state registers
3264 3300  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /asrs
3265 3301  ancillary state registers (SPARC V9 only)
3266 3302  .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /spymaster
3267 3303  For an agent LWP, the controlling process
3268 3304  .El
3269 3305  .Sh DIAGNOSTICS
3270 3306  Errors that can occur in addition to the errors normally associated with file
3271 3307  system access:
3272 3308  .Bl -tag -width "EOVERFLOW" -offset left
3273 3309  .It Er E2BIG
3274 3310  Data to be returned in a
3275 3311  .Xr read 2
3276 3312  of the page data file exceeds the size of the read buffer provided by the
3277 3313  caller.
3278 3314  .It Er EACCES
3279 3315  An attempt was made to examine a process that ran under a different uid than
3280 3316  the controlling process and
3281 3317  .Brq Sy PRIV_PROC_OWNER
3282 3318  was not asserted in the effective set.
3283 3319  .It Er EAGAIN
3284 3320  The traced process has performed an
3285 3321  .Xr exec 2
3286 3322  of a setuid/setgid object
3287 3323  file or of an object file that it cannot read; all further operations on the
3288 3324  process or lwp file descriptor (except
3289 3325  .Xr close 2 )
3290 3326  elicit this error.
3291 3327  .It Er EBUSY
3292 3328  .Sy PCSTOP ,
3293 3329  .Sy PCDSTOP ,
3294 3330  .Sy PCWSTOP , or
3295 3331  .Sy PCTWSTOP
3296 3332  was applied to a system process; an exclusive
3297 3333  .Xr open 2
3298 3334  was attempted on a
3299 3335  .Pa /proc
3300 3336  file for a process already open for writing;
3301 3337  .Sy PCRUN ,
3302 3338  .Sy PCSREG ,
3303 3339  .Sy PCSVADDR ,
3304 3340  .Sy PCSFPREG ,
3305 3341  or
3306 3342  .Sy PCSXREG
3307 3343  was applied to a process or
3308 3344  lwp not stopped on an event of interest; an attempt was made to mount
3309 3345  .Pa /proc
3310 3346  when it was already mounted;
3311 3347  .Sy PCAGENT
3312 3348  was applied to a process
3313 3349  that was not fully stopped or that already had an agent lwp.
3314 3350  .It Er EINVAL
3315 3351  In general, this means that some invalid argument was supplied to a system
3316 3352  call.
3317 3353  A non-exhaustive list of conditions eliciting this error includes: a
3318 3354  control message operation code is undefined; an out-of-range signal number was
3319 3355  specified with
3320 3356  .Sy PCSSIG ,
3321 3357  .Sy PCKILL ,
3322 3358  or
3323 3359  .Sy PCUNKILL ;
3324 3360  .Sy SIGKILL
3325 3361  was specified with
3326 3362  .Sy PCUNKILL ;
3327 3363  .Sy PCSFPREG
3328 3364  was applied on a system that does not support floating-point operations;
3329 3365  .Sy PCSXREG
3330 3366  was applied on a system that does not support extra state registers.
3331 3367  .It Er EINTR
3332 3368  A signal was received by the controlling process while waiting for the traced
3333 3369  process or lwp to stop via
3334 3370  .Sy PCSTOP ,
3335 3371  .Sy PCWSTOP ,
3336 3372  or
3337 3373  .Sy PCTWSTOP .
3338 3374  .It Er EIO
3339 3375  A
3340 3376  .Xr write 2
3341 3377  was attempted at an illegal address in the traced process.
3342 3378  .It Er ENOENT
3343 3379  The traced process or lwp has terminated after being opened.
3344 3380  The basic privilege
3345 3381  .Brq Sy PRIV_PROC_INFO
3346 3382  is not asserted in the effective set of the calling process and the calling
3347 3383  process cannot send a signal to the target process.
3348 3384  .It Er ENOMEM
3349 3385  The system-imposed limit on the number of page data file descriptors was
3350 3386  reached on an open of
3351 3387  .Pa /proc/ Ns Em pid Ns Pa /pagedata ;
3352 3388  an attempt was made
3353 3389  with
3354 3390  .Sy PCWATCH
3355 3391  to establish more watched areas than the system can support;
3356 3392  the
3357 3393  .Sy PCAGENT
3358 3394  operation was issued when the system was out of resources for
3359 3395  creating lwps.
3360 3396  .It Er ENOSYS
3361 3397  An attempt was made to perform an unsupported operation (such as
3362 3398  .Xr creat 2 ,
3363 3399  .Xr link 2 ,
3364 3400  or
3365 3401  .Xr unlink 2 )
3366 3402  on an entry in
3367 3403  .Pa /proc .
3368 3404  .It Er EOVERFLOW
3369 3405  A 32-bit controlling process attempted to read or write the
3370 3406  .Pa as
3371 3407  file or attempted to read the
3372 3408  .Pa map ,
3373 3409  .Pa rmap ,
3374 3410  or
3375 3411  .Pa pagedata
3376 3412  file of a 64-bit target process.
3377 3413  A 32-bit controlling process attempted to apply one of the
3378 3414  control operations
3379 3415  .Sy PCSREG ,
3380 3416  .Sy PCSXREG ,
3381 3417  .Sy PCSVADDR ,
3382 3418  .Sy PCWATCH ,
3383 3419  .Sy PCAGENT ,
3384 3420  .Sy PCREAD ,
3385 3421  .Sy PCWRITE
3386 3422  to a 64-bit target process.
3387 3423  .It Er EPERM
3388 3424  The process that issued the
3389 3425  .Sy PCSCRED
3390 3426  or
3391 3427  .Sy PCSCREDX
3392 3428  operation did not have the
3393 3429  .Brq Sy PRIV_PROC_SETID
3394 3430  privilege asserted in its effective set, or
3395 3431  the process that issued the
3396 3432  .Sy PCNICE
3397 3433  operation did not have the
3398 3434  .Brq Sy PRIV_PROC_PRIOCNTL
3399 3435  in its effective set.
3400 3436  .Pp
3401 3437  An attempt was made to control a process of which the E, P, and I privilege
3402 3438  sets were not a subset of the effective set of the controlling process or the
3403 3439  limit set of the controlling process is not a superset of limit set of the
3404 3440  controlled process.
3405 3441  .Pp
3406 3442  Any of the uids of the target process are
3407 3443  .Sy 0
3408 3444  or an attempt was made to change any of the uids to
3409 3445  .Sy 0
3410 3446  using
3411 3447  .Sy PCSCRED
3412 3448  and the security policy imposed additional restrictions.
3413 3449  See
3414 3450  .Xr privileges 7 .
3415 3451  .El
3416 3452  .Sh SEE ALSO
3417 3453  .Xr ls 1 ,
3418 3454  .Xr ps 1 ,
3419 3455  .Xr alarm 2 ,
3420 3456  .Xr brk 2 ,
3421 3457  .Xr chdir 2 ,
3422 3458  .Xr chroot 2 ,
3423 3459  .Xr close 2 ,
3424 3460  .Xr creat 2 ,
3425 3461  .Xr dup 2 ,
3426 3462  .Xr exec 2 ,
3427 3463  .Xr fcntl 2 ,
3428 3464  .Xr fork 2 ,
3429 3465  .Xr fork1 2 ,
3430 3466  .Xr fstat 2 ,
3431 3467  .Xr getdents 2 ,
3432 3468  .Xr getustack 2 ,
3433 3469  .Xr kill 2 ,
3434 3470  .Xr lseek 2 ,
3435 3471  .Xr mmap 2 ,
3436 3472  .Xr nice 2 ,
3437 3473  .Xr open 2 ,
3438 3474  .Xr poll 2 ,
3439 3475  .Xr pread 2 ,
3440 3476  .Xr pwrite 2 ,
3441 3477  .Xr read 2 ,
3442 3478  .Xr readlink 2 ,
3443 3479  .Xr readv 2 ,
3444 3480  .Xr shmget 2 ,
3445 3481  .Xr sigaction 2 ,
3446 3482  .Xr sigaltstack 2 ,
3447 3483  .Xr vfork 2 ,
3448 3484  .Xr write 2 ,
3449 3485  .Xr writev 2 ,
3450 3486  .Xr _stack_grow 3C ,
3451 3487  .Xr pthread_create 3C ,
3452 3488  .Xr pthread_join 3C ,
3453 3489  .Xr ptrace 3C ,
3454 3490  .Xr readdir 3C ,
3455 3491  .Xr thr_create 3C ,
3456 3492  .Xr thr_join 3C ,
3457 3493  .Xr wait 3C ,
3458 3494  .Xr siginfo.h 3HEAD ,
3459 3495  .Xr signal.h 3HEAD ,
3460 3496  .Xr types32.h 3HEAD ,
3461 3497  .Xr ucontext.h 3HEAD ,
3462 3498  .Xr contract 5 ,
3463 3499  .Xr core 5 ,
3464 3500  .Xr process 5 ,
3465 3501  .Xr lfcompile 7 ,
3466 3502  .Xr privileges 7 ,
3467 3503  .Xr security-flags 7 ,
3468 3504  .Xr chroot 8
3469 3505  .Sh NOTES
3470 3506  Descriptions of structures in this document include only interesting structure
3471 3507  elements, not filler and padding fields, and may show elements out of order for
3472 3508  descriptive clarity.
3473 3509  The actual structure definitions are contained in
3474 3510  .In procfs.h .
3475 3511  .Sh BUGS
3476 3512  Because the old
3477 3513  .Xr ioctl 2 Ns -based
3478 3514  version of
3479 3515  .Pa /proc
3480 3516  is currently supported for binary compatibility with old applications, the
3481 3517  top-level directory for a process,
3482 3518  .Pa /proc/ Ns Em pid ,
3483 3519  is not world-readable, but it is world-searchable.
3484 3520  Thus, anyone can open
3485 3521  .Pa /proc/ Ns Em pid Ns Pa /psinfo
3486 3522  even though
3487 3523  .Xr ls 1
3488 3524  applied to
3489 3525  .Pa /proc/ Ns Em pid
3490 3526  will fail for anyone but the owner or an appropriately privileged process.
3491 3527  Support for the old
3492 3528  .Xr ioctl 2 Ns -based
3493 3529  version of
3494 3530  .Pa /proc
3495 3531  will be dropped in a future release, at which time the top-level directory for
3496 3532  a process will be made world-readable.
3497 3533  .Pp
3498 3534  On SPARC based machines, the types
3499 3535  .Sy gregset_t
3500 3536  and
3501 3537  .Sy fpregset_t
3502 3538  defined in
3503 3539  .In sys/regset.h
3504 3540  are similar to but not the same as the types
3505 3541  .Sy prgregset_t
3506 3542  and
3507 3543  .Sy prfpregset_t
3508 3544  defined in
3509 3545  .In procfs.h .

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX