io-lx-public Wdiff usr/src/man/man4/proc.4

Print this page

OS-3820 lxbrand ptrace(2): the next generation
OS-3685 lxbrand PTRACE_O_TRACEFORK race condition
OS-3834 lxbrand 64-bit strace(1) reports 64-bit process as using x32 ABI
OS-3794 lxbrand panic on init signal death
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Jerry Jelinek <jerry.jelinek@joyent.com>
Reviewed by: Bryan Cantrill <bryan@joyent.com>
OS-3463 expose process argv through procfs
OS-3207 in lx zone, 'ps auxww' does not show full cmdline for processes
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Patrick Mooney <patrick.mooney@joyent.com>
OS-3383 lx brand: node.js test test-setproctitle.js fails
OS-15 add procfs equivalent to prctl(PR_SET_NAME)

Split	Close
Expand all
Collapse all

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

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

↓ open down ↓

144 lines elided

↑ open up ↑

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

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

↓ open down ↓

6 lines elided

↑ open up ↑

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

 249  242       int pr_nzomb;            /* number of zombie lwps in the process */
 250  243       pid_tpr_pid;             /* process id */
 251  244       pid_tpr_ppid;            /* parent process id */
 252  245       pid_tpr_pgid;            /* process group id */
 253  246       pid_tpr_sid;             /* session id */
 254  247       id_t pr_aslwpid;         /* obsolete */
 255  248       id_t pr_agentid;         /* lwp-id of the agent lwp, if any */
 256  249       sigset_t pr_sigpend;     /* set of process pending signals */
 257  250       uintptr_t pr_brkbase;    /* virtual address of the process heap */
 258  251       size_t pr_brksize;       /* size of the process heap, in bytes */
 259  252       uintptr_t pr_stkbase;    /* virtual address of the process stack */
 260  253       size_tpr_stksize;        /* size of the process stack, in bytes */
 261  254       timestruc_t pr_utime;    /* process user cpu time */
 262  255       timestruc_t pr_stime;    /* process system cpu time */
 263  256       timestruc_t pr_cutime;   /* sum of children's user times */
 264  257       timestruc_t pr_cstime;   /* sum of children's system times */
 265  258       sigset_t pr_sigtrace;    /* set of traced signals */
 266  259       fltset_t pr_flttrace;    /* set of traced faults */
 267  260       sysset_t pr_sysentry;    /* set of system calls traced on entry */
 268  261       sysset_t pr_sysexit;     /* set of system calls traced on exit */
 269  262       char pr_dmodel;          /* data model of the process */
 270  263       taskid_t pr_taskid;      /* task id */
 271  264       projid_t pr_projid;      /* project id */
 272  265       zoneid_t pr_zoneid;      /* zone id */
 273  266       lwpstatus_t pr_lwp;      /* status of the representative lwp */
 274  267  } pstatus_t;
 275  268  .fi
 276  269  .in -2
 277  270  
 278  271  .sp
 279  272  .LP
 280  273  \fBpr_flags\fR is a bit-mask holding the following process flags. For
 281  274  convenience, it also contains the lwp flags for the representative lwp,
 282  275  described later.
 283  276  .sp
 284  277  .ne 2
 285  278  .na
 286  279  \fB\fBPR_ISSYS\fR\fR
 287  280  .ad
 288  281  .RS 13n
 289  282  process is a system process (see \fBPCSTOP\fR).
 290  283  .RE
 291  284  
 292  285  .sp
 293  286  .ne 2
 294  287  .na
 295  288  \fB\fBPR_VFORKP\fR\fR
 296  289  .ad
 297  290  .RS 13n
 298  291  process is the parent of a vforked child (see \fBPCWATCH\fR).
 299  292  .RE
 300  293  
 301  294  .sp
 302  295  .ne 2
 303  296  .na
 304  297  \fB\fBPR_FORK\fR\fR
 305  298  .ad
 306  299  .RS 13n
 307  300  process has its inherit-on-fork mode set (see \fBPCSET\fR).
 308  301  .RE
 309  302  
 310  303  .sp
 311  304  .ne 2
 312  305  .na
 313  306  \fB\fBPR_RLC\fR\fR
 314  307  .ad
 315  308  .RS 13n
 316  309  process has its run-on-last-close mode set (see \fBPCSET\fR).
 317  310  .RE
 318  311  
 319  312  .sp
 320  313  .ne 2
 321  314  .na
 322  315  \fB\fBPR_KLC\fR\fR
 323  316  .ad
 324  317  .RS 13n
 325  318  process has its kill-on-last-close mode set (see \fBPCSET\fR).
 326  319  .RE
 327  320  
 328  321  .sp
 329  322  .ne 2
 330  323  .na
 331  324  \fB\fBPR_ASYNC\fR\fR
 332  325  .ad
 333  326  .RS 13n
 334  327  process has its asynchronous-stop mode set (see \fBPCSET\fR).
 335  328  .RE
 336  329  
 337  330  .sp
 338  331  .ne 2
 339  332  .na
 340  333  \fB\fBPR_MSACCT\fR\fR
 341  334  .ad
 342  335  .RS 13n
 343  336  Set by default in all processes to indicate that microstate accounting is
 344  337  enabled. However, this flag has been deprecated and no longer has any effect.
 345  338  Microstate accounting may not be disabled; however, it is still possible to
 346  339  toggle the flag.
 347  340  .RE
 348  341  
 349  342  .sp
 350  343  .ne 2
 351  344  .na
 352  345  \fB\fBPR_MSFORK\fR\fR
 353  346  .ad
 354  347  .RS 13n
 355  348  Set by default in all processes to indicate that microstate accounting will be
 356  349  enabled for processes that this parent forks(). However, this flag has been
 357  350  deprecated and no longer has any effect. It is possible to toggle this flag;
 358  351  however, it is not possible to disable microstate accounting.
 359  352  .RE
 360  353  
 361  354  .sp
 362  355  .ne 2
 363  356  .na
 364  357  \fB\fBPR_BPTADJ\fR\fR
 365  358  .ad
 366  359  .RS 13n
 367  360  process has its breakpoint adjustment mode set (see \fBPCSET\fR).
 368  361  .RE
 369  362  
 370  363  .sp
 371  364  .ne 2
 372  365  .na
 373  366  \fB\fBPR_PTRACE\fR\fR
 374  367  .ad
 375  368  .RS 13n
 376  369  process has its ptrace-compatibility mode set (see \fBPCSET\fR).
 377  370  .RE
 378  371  
 379  372  .sp
 380  373  .LP
 381  374  \fBpr_nlwp\fR is the total number of active lwps in the process. pr_nzomb is
 382  375  the total number of zombie lwps in the process. A zombie lwp is a non-detached
 383  376  lwp that has terminated but has not been reaped with \fBthr_join\fR(3C) or
 384  377  \fBpthread_join\fR(3C).
 385  378  .sp
 386  379  .LP
 387  380  \fBpr_pid\fR, \fBpr_ppid\fR, \fBpr_pgid\fR, and \fBpr_sid\fR are, respectively,
 388  381  the process ID, the ID of the process's parent, the process's process group ID,
 389  382  and the process's session ID.
 390  383  .sp
 391  384  .LP
 392  385  \fBpr_aslwpid\fR is obsolete and is always zero.
 393  386  .sp
 394  387  .LP
 395  388  \fBpr_agentid\fR is the lwp-ID for the \fB/proc\fR agent lwp (see the
 396  389  \fBPCAGENT\fR control operation). It is zero if there is no agent lwp in the
 397  390  process.
 398  391  .sp
 399  392  .LP
 400  393  \fBpr_sigpend\fR identifies asynchronous signals pending for the process.
 401  394  .sp
 402  395  .LP
 403  396  \fBpr_brkbase\fR is the virtual address of the process heap and
 404  397  \fBpr_brksize\fR is its size in bytes. The address formed by the sum of these
 405  398  values is the process \fBbreak\fR (see \fBbrk\fR(2)). \fBpr_stkbase\fR and
 406  399  \fBpr_stksize\fR are, respectively, the virtual address of the process stack
 407  400  and its size in bytes. (Each lwp runs on a separate stack; the distinguishing
 408  401  characteristic of the process stack is that the operating system will grow it
 409  402  when necessary.)
 410  403  .sp
 411  404  .LP
 412  405  \fBpr_utime\fR, \fBpr_stime\fR, \fBpr_cutime\fR, and \fBpr_cstime\fR are,
 413  406  respectively, the user \fBCPU\fR and system \fBCPU\fR time consumed by the
 414  407  process, and the cumulative user \fBCPU\fR and system \fBCPU\fR time consumed
 415  408  by the process's children, in seconds and nanoseconds.
 416  409  .sp
 417  410  .LP
 418  411  \fBpr_sigtrace\fR and \fBpr_flttrace\fR contain, respectively, the set of
 419  412  signals and the set of hardware faults that are being traced (see
 420  413  \fBPCSTRACE\fR and \fBPCSFAULT\fR).
 421  414  .sp
 422  415  .LP
 423  416  \fBpr_sysentry\fR and \fBpr_sysexit\fR contain, respectively, the sets of
 424  417  system calls being traced on entry and exit (see \fBPCSENTRY\fR and
 425  418  \fBPCSEXIT\fR).
 426  419  .sp
 427  420  .LP
 428  421  \fBpr_dmodel\fR indicates the data model of the process. Possible values are:
 429  422  .sp
 430  423  .ne 2
 431  424  .na
 432  425  \fB\fBPR_MODEL_ILP32\fR\fR
 433  426  .ad
 434  427  .RS 19n
 435  428  process data model is ILP32.
 436  429  .RE
 437  430  
 438  431  .sp
 439  432  .ne 2
 440  433  .na
 441  434  \fB\fBPR_MODEL_LP64\fR\fR
 442  435  .ad
 443  436  .RS 19n
 444  437  process data model is LP64.
 445  438  .RE
 446  439  
 447  440  .sp
 448  441  .ne 2
 449  442  .na
 450  443  \fB\fBPR_MODEL_NATIVE\fR\fR
 451  444  .ad
 452  445  .RS 19n
 453  446  process data model is native.
 454  447  .RE
 455  448  
 456  449  .sp
 457  450  .LP
 458  451  The \fBpr_taskid\fR, \fBpr_projid\fR, and \fBpr_zoneid\fR fields contain
 459  452  respectively, the numeric \fBID\fRs of the task, project, and zone in which the
 460  453  process was running.
 461  454  .sp
 462  455  .LP
 463  456  The constant \fBPR_MODEL_NATIVE\fR reflects the data model of the controlling
 464  457  process, \fIthat is\fR, its value is \fBPR_MODEL_ILP32\fR or
 465  458  \fBPR_MODEL_LP64\fR according to whether the controlling process has been
 466  459  compiled as a 32-bit program or a 64-bit program, respectively.
 467  460  .sp
 468  461  .LP
 469  462  \fBpr_lwp\fR contains the status information for the representative lwp:
 470  463  .sp
 471  464  .in +2
 472  465  .nf
 473  466  typedef struct lwpstatus {
 474  467    int pr_flags;              /* flags (see below) */
 475  468    id_t pr_lwpid;             /* specific lwp identifier */
 476  469    short pr_why;              /* reason for lwp stop, if stopped */
 477  470    short pr_what;             /* more detailed reason */
 478  471    short pr_cursig;           /* current signal, if any */
 479  472    siginfo_t pr_info;         /* info associated with signal or fault */
 480  473    sigset_t pr_lwppend;       /* set of signals pending to the lwp */
 481  474    sigset_t pr_lwphold;       /* set of signals blocked by the lwp */
 482  475    struct sigaction pr_action;/* signal action for current signal */
 483  476    stack_t pr_altstack;       /* alternate signal stack info */
 484  477    uintptr_t pr_oldcontext;   /* address of previous ucontext */
 485  478    short pr_syscall;          /* system call number (if in syscall) */
 486  479    short pr_nsysarg;          /* number of arguments to this syscall */
 487  480    int pr_errno;              /* errno for failed syscall */
 488  481    long pr_sysarg[PRSYSARGS]; /* arguments to this syscall */
 489  482    long pr_rval1;             /* primary syscall return value */
 490  483    long pr_rval2;             /* second syscall return value, if any */
 491  484    char pr_clname[PRCLSZ];    /* scheduling class name */
 492  485    timestruc_t pr_tstamp;     /* real-time time stamp of stop */
 493  486    timestruc_t pr_utime;      /* lwp user cpu time */
 494  487    timestruc_t pr_stime;      /* lwp system cpu time */
 495  488    uintptr_t pr_ustack;       /* stack boundary data (stack_t) address */
 496  489    ulong_t pr_instr;          /* current instruction */
 497  490    prgregset_t pr_reg;        /* general registers */
 498  491    prfpregset_t pr_fpreg;     /* floating-point registers */
 499  492  } lwpstatus_t;
 500  493  .fi
 501  494  .in -2
 502  495  
 503  496  .sp
 504  497  .LP
 505  498  \fBpr_flags\fR is a bit-mask holding the following lwp flags. For convenience,
 506  499  it also contains the process flags, described previously.
 507  500  .sp
 508  501  .ne 2
 509  502  .na
 510  503  \fB\fBPR_STOPPED\fR\fR
 511  504  .ad
 512  505  .RS 14n
 513  506  The lwp is stopped.
 514  507  .RE
 515  508  
 516  509  .sp
 517  510  .ne 2
 518  511  .na
 519  512  \fB\fBPR_ISTOP\fR\fR
 520  513  .ad
 521  514  .RS 14n
 522  515  The lwp is stopped on an event of interest (see \fBPCSTOP\fR).
 523  516  .RE
 524  517  
 525  518  .sp
 526  519  .ne 2
 527  520  .na
 528  521  \fB\fBPR_DSTOP\fR\fR
 529  522  .ad
 530  523  .RS 14n
 531  524  The lwp has a stop directive in effect (see \fBPCSTOP\fR).
 532  525  .RE
 533  526  
 534  527  .sp
 535  528  .ne 2
 536  529  .na
 537  530  \fB\fBPR_STEP\fR\fR
 538  531  .ad
 539  532  .RS 14n
 540  533  The lwp has a single-step directive in effect (see \fBPCRUN\fR).
 541  534  .RE
 542  535  
 543  536  .sp
 544  537  .ne 2
 545  538  .na
 546  539  \fB\fBPR_ASLEEP\fR\fR
 547  540  .ad
 548  541  .RS 14n
 549  542  The lwp is in an interruptible sleep within a system call.
 550  543  .RE
 551  544  
 552  545  .sp
 553  546  .ne 2
 554  547  .na
 555  548  \fB\fBPR_PCINVAL\fR\fR
 556  549  .ad
 557  550  .RS 14n
 558  551  The lwp's current instruction (\fBpr_instr\fR) is undefined.
 559  552  .RE
 560  553  
 561  554  .sp
 562  555  .ne 2
 563  556  .na
 564  557  \fB\fBPR_DETACH\fR\fR
 565  558  .ad
 566  559  .RS 14n
 567  560  This is a detached lwp (see \fBpthread_create\fR(3C) and
 568  561  \fBpthread_join\fR(3C)).
 569  562  .RE
 570  563  
 571  564  .sp
 572  565  .ne 2
 573  566  .na
 574  567  \fB\fBPR_DAEMON\fR\fR
 575  568  .ad
 576  569  .RS 14n
 577  570  This is a daemon lwp (see \fBpthread_create\fR(3C)).
 578  571  .RE
 579  572  
 580  573  .sp
 581  574  .ne 2
 582  575  .na
 583  576  \fB\fBPR_ASLWP\fR\fR
 584  577  .ad
 585  578  .RS 14n
 586  579  This flag is obsolete and is never set.
 587  580  .RE
 588  581  
 589  582  .sp
 590  583  .ne 2
 591  584  .na
 592  585  \fB\fBPR_AGENT\fR\fR
 593  586  .ad
 594  587  .RS 14n
 595  588  This is the \fB/proc\fR agent lwp for the process.
 596  589  .RE
 597  590  
 598  591  .sp
 599  592  .LP
 600  593  \fBpr_lwpid\fR names the specific lwp.
 601  594  .sp
 602  595  .LP
 603  596  \fBpr_why\fR and \fBpr_what\fR together describe, for a stopped lwp, the reason
 604  597  for the stop. Possible values of \fBpr_why\fR and the associated \fBpr_what\fR
 605  598  are:
 606  599  .sp
 607  600  .ne 2
 608  601  .na
 609  602  \fB\fBPR_REQUESTED\fR\fR
 610  603  .ad
 611  604  .RS 17n
 612  605  indicates that the stop occurred in response to a stop directive, normally
 613  606  because \fBPCSTOP\fR was applied or because another lwp stopped on an event of
 614  607  interest and the asynchronous-stop flag (see \fBPCSET\fR) was not set for the
 615  608  process. \fBpr_what\fR is unused in this case.
 616  609  .RE
 617  610  
 618  611  .sp
 619  612  .ne 2
 620  613  .na
 621  614  \fB\fBPR_SIGNALLED\fR\fR
 622  615  .ad
 623  616  .RS 17n
 624  617  indicates that the lwp stopped on receipt of a signal (see \fBPCSTRACE\fR);
 625  618  \fBpr_what\fR holds the signal number that caused the stop (for a newly-stopped
 626  619  lwp, the same value is in \fBpr_cursig\fR).
 627  620  .RE
 628  621  
 629  622  .sp
 630  623  .ne 2
 631  624  .na
 632  625  \fB\fBPR_FAULTED\fR\fR
 633  626  .ad
 634  627  .RS 17n
 635  628  indicates that the lwp stopped on incurring a hardware fault (see
 636  629  \fBPCSFAULT\fR); \fBpr_what\fR holds the fault number that caused the stop.
 637  630  .RE
 638  631  
 639  632  .sp
 640  633  .ne 2
 641  634  .na
 642  635  \fB\fBPR_SYSENTRY\fR\fR
 643  636  .ad
 644  637  .br
 645  638  .na
 646  639  \fB\fBPR_SYSEXIT\fR\fR
 647  640  .ad
 648  641  .RS 17n
 649  642  indicate a stop on entry to or exit from a system call (see \fBPCSENTRY\fR and
 650  643  \fBPCSEXIT\fR); \fBpr_what\fR holds the system call number.
 651  644  .RE
 652  645  
 653  646  .sp
 654  647  .ne 2
 655  648  .na
 656  649  \fB\fBPR_JOBCONTROL\fR\fR
 657  650  .ad
 658  651  .RS 17n
 659  652  indicates that the lwp stopped due to the default action of a job control stop
 660  653  signal (see \fBsigaction\fR(2)); \fBpr_what\fR holds the stopping signal
 661  654  number.
 662  655  .RE
 663  656  
 664  657  .sp

↓ open down ↓

416 lines elided

↑ open up ↑

 665  658  .ne 2
 666  659  .na
 667  660  \fB\fBPR_SUSPENDED\fR\fR
 668  661  .ad
 669  662  .RS 17n
 670  663  indicates that the lwp stopped due to internal synchronization of lwps within
 671  664  the process. \fBpr_what\fR is unused in this case.
 672  665  .RE
 673  666  
 674  667  .sp
      668 +.ne 2
      669 +.na
      670 +\fB\fBPR_BRAND\fR\fR
      671 +.ad
      672 +.RS 17n
      673 +indicates that the lwp stopped for a brand-specific reason.  Interpretation
      674 +of the value of \fBpr_what\fR depends on which zone brand is in use.  It is
      675 +not generally expected that an lwp stopped in this state will be restarted
      676 +by native \fBproc\fR(4) consumers.
      677 +.RE
      678 +
      679 +.sp
 675  680  .LP
 676  681  \fBpr_cursig\fR names the current signal, that is, the next signal to be
 677  682  delivered to the lwp, if any. \fBpr_info\fR, when the lwp is in a
 678  683  \fBPR_SIGNALLED\fR or \fBPR_FAULTED\fR stop, contains additional information
 679  684  pertinent to the particular signal or fault (see \fB<sys/siginfo.h>\fR).
 680  685  .sp
 681  686  .LP
 682  687  \fBpr_lwppend\fR identifies any synchronous or directed signals pending for the
 683  688  lwp. \fBpr_lwphold\fR identifies those signals whose delivery is being blocked
 684  689  by the lwp (the signal mask).

 685  690  .sp
 686  691  .LP
 687  692  \fBpr_action\fR contains the signal action information pertaining to the
 688  693  current signal (see \fBsigaction\fR(2)); it is undefined if \fBpr_cursig\fR is
 689  694  zero. \fBpr_altstack\fR contains the alternate signal stack information for the
 690  695  lwp (see \fBsigaltstack\fR(2)).
 691  696  .sp
 692  697  .LP
 693  698  \fBpr_oldcontext\fR, if not zero, contains the address on the lwp stack of a
 694  699  \fBucontext\fR structure describing the previous user-level context (see
 695  700  \fBucontext.h\fR(3HEAD)). It is non-zero only if the lwp is executing in the
 696  701  context of a signal handler.
 697  702  .sp
 698  703  .LP
 699  704  \fBpr_syscall\fR is the number of the system call, if any, being executed by
 700  705  the lwp; it is non-zero if and only if the lwp is stopped on \fBPR_SYSENTRY\fR
 701  706  or \fBPR_SYSEXIT\fR, or is asleep within a system call ( \fBPR_ASLEEP\fR is
 702  707  set). If \fBpr_syscall\fR is non-zero, \fBpr_nsysarg\fR is the number of
 703  708  arguments to the system call and \fBpr_sysarg\fR contains the actual arguments.
 704  709  .sp
 705  710  .LP
 706  711  \fBpr_rval1\fR, \fBpr_rval2\fR, and \fBpr_errno\fR are defined only if the lwp
 707  712  is stopped on \fBPR_SYSEXIT\fR or if the \fBPR_VFORKP\fR flag is set. If
 708  713  \fBpr_errno\fR is zero, \fBpr_rval1\fR and \fBpr_rval2\fR contain the return
 709  714  values from the system call. Otherwise, \fBpr_errno\fR contains the error
 710  715  number for the failing system call (see \fB<sys/errno.h>\fR).
 711  716  .sp
 712  717  .LP
 713  718  \fBpr_clname\fR contains the name of the lwp's scheduling class.
 714  719  .sp
 715  720  .LP
 716  721  \fBpr_tstamp\fR, if the lwp is stopped, contains a time stamp marking when the
 717  722  lwp stopped, in real time seconds and nanoseconds since an arbitrary time in
 718  723  the past.
 719  724  .sp
 720  725  .LP
 721  726  \fBpr_utime\fR is the amount of user level CPU time used by this LWP.
 722  727  .sp
 723  728  .LP
 724  729  \fBpr_stime\fR is the amount of system level CPU time used by this LWP.
 725  730  .sp
 726  731  .LP
 727  732  \fBpr_ustack\fR is the virtual address of the \fBstack_t\fR that contains the
 728  733  stack boundaries for this LWP. See \fBgetustack\fR(2) and
 729  734  \fB_stack_grow\fR(3C).
 730  735  .sp
 731  736  .LP
 732  737  \fBpr_instr\fR contains the machine instruction to which the lwp's program
 733  738  counter refers. The amount of data retrieved from the process is
 734  739  machine-dependent. On SPARC based machines, it is a 32-bit word. On x86-based
 735  740  machines, it is a single byte. In general, the size is that of the machine's
 736  741  smallest instruction. If \fBPR_PCINVAL\fR is set, \fBpr_instr\fR is undefined;
 737  742  this occurs whenever the lwp is not stopped or when the program counter refers
 738  743  to an invalid virtual address.
 739  744  .sp
 740  745  .LP
 741  746  \fBpr_reg\fR is an array holding the contents of a stopped lwp's general
 742  747  registers.
 743  748  .sp
 744  749  .ne 2
 745  750  .na
 746  751  \fBSPARC\fR
 747  752  .ad
 748  753  .RS 21n
 749  754  On SPARC-based machines, the predefined constants \fBR_G0\fR ... \fBR_G7\fR,
 750  755  \fBR_O0\fR ... \fBR_O7\fR, \fBR_L0\fR ... \fBR_L7\fR, \fBR_I0\fR ...
 751  756  \fBR_I7\fR, \fBR_PC\fR, \fBR_nPC\fR, and \fBR_Y\fR can be used as indices to
 752  757  refer to the corresponding registers; previous register windows can be read
 753  758  from their overflow locations on the stack (however, see the \fBgwindows\fR
 754  759  file in the \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR subdirectory).
 755  760  .RE
 756  761  
 757  762  .sp
 758  763  .ne 2
 759  764  .na
 760  765  \fBSPARC V8 (32-bit)\fR
 761  766  .ad
 762  767  .RS 21n
 763  768  For SPARC V8 (32-bit) controlling processes, the predefined constants
 764  769  \fBR_PSR\fR, \fBR_WIM\fR, and \fBR_TBR\fR can be used as indices to refer to
 765  770  the corresponding special registers. For SPARC V9 (64-bit) controlling
 766  771  processes, the predefined constants \fBR_CCR\fR, \fBR_ASI\fR, and \fBR_FPRS\fR
 767  772  can be used as indices to refer to the corresponding special registers.
 768  773  .RE
 769  774  
 770  775  .sp
 771  776  .ne 2
 772  777  .na
 773  778  \fBx86 (32-bit)\fR
 774  779  .ad
 775  780  .RS 21n
 776  781  For 32-bit x86 processes, the predefined constants listed belowcan be used as
 777  782  indices to refer to the corresponding registers.
 778  783  .sp
 779  784  .in +2
 780  785  .nf
 781  786  SS
 782  787  UESP
 783  788  EFL
 784  789  CS
 785  790  EIP
 786  791  ERR
 787  792  TRAPNO
 788  793  EAX
 789  794  ECX
 790  795  EDX
 791  796  EBX
 792  797  ESP
 793  798  EBP
 794  799  ESI
 795  800  EDI
 796  801  DS
 797  802  ES
 798  803  GS
 799  804  .fi
 800  805  .in -2
 801  806  
 802  807  The preceding constants are listed in \fB<sys/regset.h>\fR\&.
 803  808  .sp
 804  809  Note that a 32-bit process can run on an x86 64-bit system, using the constants
 805  810  listed above.
 806  811  .RE
 807  812  
 808  813  .sp
 809  814  .ne 2
 810  815  .na
 811  816  \fBx86 (64-bit)\fR
 812  817  .ad
 813  818  .RS 21n
 814  819  To read the registers of a 32- \fBor\fR a 64-bit process, a 64-bit x86 process
 815  820  should use the predefined constants listed below.
 816  821  .sp
 817  822  .in +2
 818  823  .nf
 819  824  REG_GSBASE
 820  825  REG_FSBASE
 821  826  REG_DS
 822  827  REG_ES
 823  828  REG_GS
 824  829  REG_FS
 825  830  REG_SS
 826  831  REG_RSP
 827  832  REG_RFL
 828  833  REG_CS
 829  834  REG_RIP
 830  835  REG_ERR
 831  836  REG_TRAPNO
 832  837  REG_RAX
 833  838  REG_RCX
 834  839  REG_RDX
 835  840  REG_RBX
 836  841  REG_RBP
 837  842  REG_RSI
 838  843  REG_RDI
 839  844  REG_R8
 840  845  REG_R9
 841  846  REG_R10
 842  847  REG_R11
 843  848  REG_R12
 844  849  REG_R13
 845  850  REG_R14
 846  851  REG_R15
 847  852  .fi
 848  853  .in -2
 849  854  
 850  855  The preceding constants are listed in \fB<sys/regset.h>\fR\&.
 851  856  .RE
 852  857  
 853  858  .sp
 854  859  .LP
 855  860  \fBpr_fpreg\fR is a structure holding the contents of the floating-point
 856  861  registers.

↓ open down ↓

172 lines elided

↑ open up ↑

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

 878  882      int pr_flag;             /* process flags (DEPRECATED: see below) */
 879  883      int pr_nlwp;             /* number of active lwps in the process */
 880  884      int pr_nzomb;            /* number of zombie lwps in the process */
 881  885      pid_t pr_pid;            /* process id */
 882  886      pid_t pr_ppid;           /* process id of parent */
 883  887      pid_t pr_pgid;           /* process id of process group leader */
 884  888      pid_t pr_sid;            /* session id */
 885  889      uid_t pr_uid;            /* real user id */
 886  890      uid_t pr_euid;           /* effective user id */
 887  891      gid_t pr_gid;            /* real group id */
 888  892      gid_t pr_egid;           /* effective group id */
 889  893      uintptr_t pr_addr;       /* address of process */
 890  894      size_t pr_size;          /* size of process image in Kbytes */
 891  895      size_t pr_rssize;        /* resident set size in Kbytes */
 892  896      dev_t pr_ttydev;         /* controlling tty device (or PRNODEV) */
 893  897      ushort_t pr_pctcpu;      /* % of recent cpu time used by all lwps */
 894  898      ushort_t pr_pctmem;      /* % of system memory used by process */
 895  899      timestruc_t pr_start;    /* process start time, from the epoch */
 896  900      timestruc_t pr_time;     /* cpu time for this process */
 897  901      timestruc_t pr_ctime;    /* cpu time for reaped children */
 898  902      char pr_fname[PRFNSZ];   /* name of exec'ed file */
 899  903      char pr_psargs[PRARGSZ]; /* initial characters of arg list */
 900  904      int pr_wstat;            /* if zombie, the wait() status */
 901  905      int pr_argc;             /* initial argument count */
 902  906      uintptr_t pr_argv;       /* address of initial argument vector */
 903  907      uintptr_t pr_envp;       /* address of initial environment vector */
 904  908      char pr_dmodel;          /* data model of the process */
 905  909      lwpsinfo_t pr_lwp;       /* information for representative lwp */
 906  910      taskid_t pr_taskid;      /* task id */
 907  911      projid_t pr_projid;      /* project id */
 908  912      poolid_t pr_poolid;      /* pool id */
 909  913      zoneid_t pr_zoneid;      /* zone id */
 910  914      ctid_t pr_contract;      /* process contract id */
 911  915  } psinfo_t;
 912  916  .fi
 913  917  .in -2
 914  918  
 915  919  .sp
 916  920  .LP
 917  921  Some of the entries in \fBpsinfo\fR, such as \fBpr_addr\fR, refer to internal
 918  922  kernel data structures and should not be expected to retain their meanings
 919  923  across different versions of the operating system.
 920  924  .sp
 921  925  .LP
 922  926  \fBpsinfo_t.pr_flag\fR is a deprecated interface that should no longer be used.

↓ open down ↓

45 lines elided

↑ open up ↑

 923  927  Applications currently relying on the \fBSSYS\fR bit in \fBpr_flag\fR should
 924  928  migrate to checking \fBPR_ISSYS\fR in the \fBpstatus\fR structure's
 925  929  \fBpr_flags\fR field.
 926  930  .sp
 927  931  .LP
 928  932  \fBpr_pctcpu\fR and \fBpr_pctmem\fR are 16-bit binary fractions in the range
 929  933  0.0 to 1.0 with the binary point to the right of the high-order bit (1.0 ==
 930  934  0x8000). \fBpr_pctcpu\fR is the summation over all lwps in the process.
 931  935  .sp
 932  936  .LP
      937 +The \fBpr_fname\fR and \fBpr_psargs\fR are writable by the owner of the
      938 +process. To write to them, the \fBpsinfo\fR file should be open for writing
      939 +and the desired value for the field should be written at the file offset
      940 +that corresponds to the member of structure.  No other entry may be written
      941 +to; if a write is attempted to an offset that does not represent one of
      942 +these two memers, or if the size of the write is not exactly the size of
      943 +the member being written, no bytes will be written and zero will be returned.
      944 +.sp
      945 +.LP
 933  946  \fBpr_lwp\fR contains the \fBps\fR(1) information for the representative lwp.
 934  947  If the process is a \fIzombie\fR, \fBpr_nlwp\fR, \fBpr_nzomb\fR, and
 935  948  \fBpr_lwp.pr_lwpid\fR are zero and the other fields of \fBpr_lwp\fR are
 936  949  undefined:
 937  950  .sp
 938  951  .in +2
 939  952  .nf
 940  953  typedef struct lwpsinfo {
 941  954      int pr_flag;             /* lwp flags (DEPRECATED: see below) */
 942  955      id_t pr_lwpid;           /* lwp id */

 943  956      uintptr_t pr_addr;       /* internal address of lwp */
 944  957      uintptr_t pr_wchan;      /* wait addr for sleeping lwp */
 945  958      char pr_stype;           /* synchronization event type */
 946  959      char pr_state;           /* numeric lwp state */
 947  960      char pr_sname;           /* printable character for pr_state */
 948  961      char pr_nice;            /* nice for cpu usage */
 949  962      short pr_syscall;        /* system call number (if in syscall) */
 950  963      char pr_oldpri;          /* pre-SVR4, low value is high priority */
 951  964      char pr_cpu;             /* pre-SVR4, cpu usage for scheduling */
 952  965      int pr_pri;              /* priority, high value = high priority */
 953  966      ushort_t pr_pctcpu;      /* % of recent cpu time used by this lwp */
 954  967      timestruc_t pr_start;    /* lwp start time, from the epoch */
 955  968      timestruc_t pr_time;     /* cpu time for this lwp */
 956  969      char pr_clname[PRCLSZ];  /* scheduling class name */
 957  970      char pr_name[PRFNSZ];    /* name of system lwp */
 958  971      processorid_t pr_onpro;  /* processor which last ran this lwp */
 959  972      processorid_t pr_bindpro;/* processor to which lwp is bound */
 960  973      psetid_t pr_bindpset;    /* processor set to which lwp is bound */
 961  974      lgrp_id_t pr_lgrp         /* home lgroup */
 962  975  } lwpsinfo_t;
 963  976  .fi
 964  977  .in -2
 965  978  
 966  979  .sp
 967  980  .LP
 968  981  Some of the entries in \fBlwpsinfo\fR, such as \fBpr_addr\fR, \fBpr_wchan\fR,
 969  982  \fBpr_stype\fR, \fBpr_state\fR, and \fBpr_name\fR, refer to internal kernel
 970  983  data structures and should not be expected to retain their meanings across
 971  984  different versions of the operating system.
 972  985  .sp
 973  986  .LP
 974  987  \fBlwpsinfo_t.pr_flag\fR is a deprecated interface that should no longer be
 975  988  used.

↓ open down ↓

33 lines elided

↑ open up ↑

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

 997 1009          gid_t pr_rgid;      /* real group id */
 998 1010          gid_t pr_sgid;      /* saved group id (from exec) */
 999 1011          int pr_ngroups;     /* number of supplementary groups */
1000 1012          gid_t pr_groups[1]; /* array of supplementary groups */
1001 1013  } prcred_t;
1002 1014  .fi

↓ open down ↓

6 lines elided

↑ open up ↑

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

1024 1035  } prpriv_t;
1025 1036  .fi
1026 1037  .in -2
1027 1038  
1028 1039  .sp
1029 1040  .LP
1030 1041  The actual dimension of the \fBpr_sets\fR[] field is
1031 1042  .sp
1032 1043  .in +2
1033 1044  .nf
1034 1045  pr_sets[pr_nsets][pr_setsize]
1035 1046  .fi
1036 1047  .in -2

↓ open down ↓

13 lines elided

↑ open up ↑

1037 1048  
1038 1049  .sp
1039 1050  .LP
1040 1051  which is followed by additional information about the process state
1041 1052  \fBpr_infosize\fR bytes in size.
1042 1053  .sp
1043 1054  .LP
1044 1055  The full size of the structure can be computed using
1045 1056  \fBPRIV_PRPRIV_SIZE\fR(\fBprpriv_t *\fR).
1046 1057  .SS "sigact"
1047      -.sp
1048 1058  .LP
1049 1059  Contains an array of \fBsigaction structures\fR describing the current
1050 1060  dispositions of all signals associated with the traced process (see
1051 1061  \fBsigaction\fR(2)). Signal numbers are displaced by 1 from array indices, so
1052 1062  that the action for signal number \fIn\fR appears in position \fIn\fR-1 of the
1053 1063  array.
1054 1064  .SS "auxv"
1055      -.sp
1056 1065  .LP
1057 1066  Contains the initial values of the process's aux vector in an array of
1058 1067  \fBauxv_t\fR structures (see \fB<sys/auxv.h>\fR). The values are those that
1059 1068  were passed by the operating system as startup information to the dynamic
1060 1069  linker.
     1070 +.SS "argv"
     1071 +.LP
     1072 +Contains the concatenation of each of the argument strings, including their
     1073 +\fBNUL\fR terminators, in the argument vector (\fBargv\fR) for the process. If
     1074 +the process has modified either its argument vector, or the contents of any of
     1075 +the strings referenced by that vector, those changes will be visible here.
1061 1076  .SS "ldt"
1062      -.sp
1063 1077  .LP
1064 1078  This file exists only on x86-based machines. It is non-empty only if the
1065 1079  process has established a local descriptor table (\fBLDT\fR). If non-empty, the
1066 1080  file contains the array of currently active \fBLDT\fR entries in an array of
1067 1081  elements of type \fBstruct ssd\fR, defined in \fB<sys/sysi86.h>\fR, one element
1068 1082  for each active \fBLDT\fR entry.
1069 1083  .SS "map, xmap"
1070      -.sp
1071 1084  .LP
1072 1085  Contain information about the virtual address map of the process. The map file
1073 1086  contains an array of \fBprmap\fR structures while the xmap file contains an
1074 1087  array of \fBprxmap\fR structures. Each structure describes a contiguous virtual
1075 1088  address region in the address space of the traced process:
1076 1089  .sp
1077 1090  .in +2
1078 1091  .nf
1079 1092  typedef struct prmap {
1080 1093          uintptr_tpr_vaddr;         /* virtual address of mapping */

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

↓ open down ↓

147 lines elided

↑ open up ↑

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

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

↓ open down ↓

61 lines elided

↑ open up ↑

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

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

↓ open down ↓

26 lines elided

↑ open up ↑

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

1448 1451      long pr_nent;        /* number of entries */
1449 1452      size_t pr_entsize;   /* size of each entry, in bytes */
1450 1453  } prheader_t;
1451 1454  .fi

↓ open down ↓

4 lines elided

↑ open up ↑

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

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

↓ open down ↓

28 lines elided

↑ open up ↑

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

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

↓ open down ↓

60 lines elided

↑ open up ↑

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

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

↓ open down ↓

104 lines elided

↑ open up ↑

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

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

↓ open down ↓

128 lines elided

↑ open up ↑

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

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

↓ open down ↓

95 lines elided

↑ open up ↑

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

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

↓ open down ↓

40 lines elided

↑ open up ↑

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

2305 2274  } priovec_t;
2306 2275  .fi
2307 2276  .in -2
2308 2277  
2309 2278  .sp
2310 2279  .LP

↓ open down ↓

6 lines elided

↑ open up ↑

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

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

↓ open down ↓

38 lines elided

↑ open up ↑

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

2433 2396  .ne 2
2434 2397  .na
2435 2398  \fB\fB/proc/\fIpid\fR\fR\fR
2436 2399  .ad
2437 2400  .sp .6
2438 2401  .RS 4n
2439 2402  specific process directory
2440 2403  .RE
2441 2404  
2442 2405  .sp
2443 2406  .ne 2
2444 2407  .na
2445 2408  \fB\fB/proc/self\fR\fR
2446 2409  .ad
2447 2410  .sp .6
2448 2411  .RS 4n
2449 2412  alias for a process's own directory
2450 2413  .RE
2451 2414  
2452 2415  .sp
2453 2416  .ne 2
2454 2417  .na
2455 2418  \fB\fB/proc/\fIpid\fR/as\fR\fR
2456 2419  .ad
2457 2420  .sp .6
2458 2421  .RS 4n
2459 2422  address space file
2460 2423  .RE
2461 2424  
2462 2425  .sp
2463 2426  .ne 2
2464 2427  .na
2465 2428  \fB\fB/proc/\fIpid\fR/ctl\fR\fR
2466 2429  .ad
2467 2430  .sp .6
2468 2431  .RS 4n
2469 2432  process control file
2470 2433  .RE
2471 2434  
2472 2435  .sp
2473 2436  .ne 2
2474 2437  .na
2475 2438  \fB\fB/proc/\fIpid\fR/status\fR\fR
2476 2439  .ad
2477 2440  .sp .6
2478 2441  .RS 4n
2479 2442  process status
2480 2443  .RE
2481 2444  
2482 2445  .sp
2483 2446  .ne 2
2484 2447  .na
2485 2448  \fB\fB/proc/\fIpid\fR/lstatus\fR\fR
2486 2449  .ad
2487 2450  .sp .6
2488 2451  .RS 4n
2489 2452  array of lwp status structs
2490 2453  .RE
2491 2454  
2492 2455  .sp
2493 2456  .ne 2
2494 2457  .na
2495 2458  \fB\fB/proc/\fIpid\fR/psinfo\fR\fR
2496 2459  .ad
2497 2460  .sp .6
2498 2461  .RS 4n
2499 2462  process \fBps\fR(1) info
2500 2463  .RE
2501 2464  
2502 2465  .sp
2503 2466  .ne 2
2504 2467  .na
2505 2468  \fB\fB/proc/\fIpid\fR/lpsinfo\fR\fR
2506 2469  .ad
2507 2470  .sp .6
2508 2471  .RS 4n
2509 2472  array of lwp \fBps\fR(1) info structs
2510 2473  .RE
2511 2474  
2512 2475  .sp
2513 2476  .ne 2
2514 2477  .na
2515 2478  \fB\fB/proc/\fIpid\fR/map\fR\fR
2516 2479  .ad
2517 2480  .sp .6
2518 2481  .RS 4n
2519 2482  address space map
2520 2483  .RE
2521 2484  
2522 2485  .sp
2523 2486  .ne 2
2524 2487  .na
2525 2488  \fB\fB/proc/\fIpid\fR/xmap\fR\fR
2526 2489  .ad
2527 2490  .sp .6
2528 2491  .RS 4n
2529 2492  extended address space map
2530 2493  .RE
2531 2494  
2532 2495  .sp
2533 2496  .ne 2
2534 2497  .na
2535 2498  \fB\fB/proc/\fIpid\fR/rmap\fR\fR
2536 2499  .ad
2537 2500  .sp .6
2538 2501  .RS 4n
2539 2502  reserved address map
2540 2503  .RE
2541 2504  
2542 2505  .sp
2543 2506  .ne 2
2544 2507  .na
2545 2508  \fB\fB/proc/\fIpid\fR/cred\fR\fR
2546 2509  .ad
2547 2510  .sp .6
2548 2511  .RS 4n
2549 2512  process credentials
2550 2513  .RE
2551 2514  
2552 2515  .sp
2553 2516  .ne 2
2554 2517  .na
2555 2518  \fB\fB/proc/\fIpid\fR/priv\fR\fR
2556 2519  .ad
2557 2520  .sp .6
2558 2521  .RS 4n
2559 2522  process privileges
2560 2523  .RE
2561 2524  
2562 2525  .sp
2563 2526  .ne 2
2564 2527  .na
2565 2528  \fB\fB/proc/\fIpid\fR/sigact\fR\fR
2566 2529  .ad
2567 2530  .sp .6
2568 2531  .RS 4n
2569 2532  process signal actions
2570 2533  .RE
2571 2534  
2572 2535  .sp
2573 2536  .ne 2
2574 2537  .na

↓ open down ↓

142 lines elided

↑ open up ↑

2575 2538  \fB\fB/proc/\fIpid\fR/auxv\fR\fR
2576 2539  .ad
2577 2540  .sp .6
2578 2541  .RS 4n
2579 2542  process aux vector
2580 2543  .RE
2581 2544  
2582 2545  .sp
2583 2546  .ne 2
2584 2547  .na
     2548 +\fB\fB/proc/\fIpid\fR/argv\fR\fR
     2549 +.ad
     2550 +.sp .6
     2551 +.RS 4n
     2552 +process argument vector
     2553 +.RE
     2554 +
     2555 +.sp
     2556 +.ne 2
     2557 +.na
2585 2558  \fB\fB/proc/\fIpid\fR/ldt\fR\fR
2586 2559  .ad
2587 2560  .sp .6
2588 2561  .RS 4n
2589 2562  process \fBLDT\fR (x86 only)
2590 2563  .RE
2591 2564  
2592 2565  .sp
2593 2566  .ne 2
2594 2567  .na

2595 2568  \fB\fB/proc/\fIpid\fR/usage\fR\fR
2596 2569  .ad
2597 2570  .sp .6
2598 2571  .RS 4n
2599 2572  process usage
2600 2573  .RE
2601 2574  
2602 2575  .sp
2603 2576  .ne 2
2604 2577  .na
2605 2578  \fB\fB/proc/\fIpid\fR/lusage\fR\fR
2606 2579  .ad
2607 2580  .sp .6
2608 2581  .RS 4n
2609 2582  array of lwp usage structs
2610 2583  .RE
2611 2584  
2612 2585  .sp
2613 2586  .ne 2
2614 2587  .na
2615 2588  \fB\fB/proc/\fIpid\fR/path\fR\fR
2616 2589  .ad
2617 2590  .sp .6
2618 2591  .RS 4n
2619 2592  symbolic links to process open files
2620 2593  .RE
2621 2594  
2622 2595  .sp
2623 2596  .ne 2
2624 2597  .na
2625 2598  \fB\fB/proc/\fIpid\fR/pagedata\fR\fR
2626 2599  .ad
2627 2600  .sp .6
2628 2601  .RS 4n
2629 2602  process page data
2630 2603  .RE
2631 2604  
2632 2605  .sp
2633 2606  .ne 2
2634 2607  .na
2635 2608  \fB\fB/proc/\fIpid\fR/watch\fR\fR
2636 2609  .ad
2637 2610  .sp .6
2638 2611  .RS 4n
2639 2612  active watchpoints
2640 2613  .RE
2641 2614  
2642 2615  .sp
2643 2616  .ne 2
2644 2617  .na
2645 2618  \fB\fB/proc/\fIpid\fR/cwd\fR\fR
2646 2619  .ad
2647 2620  .sp .6
2648 2621  .RS 4n
2649 2622  alias for the current working directory
2650 2623  .RE
2651 2624  
2652 2625  .sp
2653 2626  .ne 2
2654 2627  .na
2655 2628  \fB\fB/proc/\fIpid\fR/root\fR\fR
2656 2629  .ad
2657 2630  .sp .6
2658 2631  .RS 4n
2659 2632  alias for the root directory
2660 2633  .RE
2661 2634  
2662 2635  .sp
2663 2636  .ne 2
2664 2637  .na
2665 2638  \fB\fB/proc/\fIpid\fR/fd\fR\fR
2666 2639  .ad
2667 2640  .sp .6
2668 2641  .RS 4n
2669 2642  directory (list of open files)
2670 2643  .RE
2671 2644  
2672 2645  .sp
2673 2646  .ne 2
2674 2647  .na
2675 2648  \fB\fB/proc/\fIpid\fR/fd/*\fR\fR
2676 2649  .ad
2677 2650  .sp .6
2678 2651  .RS 4n
2679 2652  aliases for process's open files
2680 2653  .RE
2681 2654  
2682 2655  .sp
2683 2656  .ne 2
2684 2657  .na
2685 2658  \fB\fB/proc/\fIpid\fR/object\fR\fR
2686 2659  .ad
2687 2660  .sp .6
2688 2661  .RS 4n
2689 2662  directory (list of mapped files)
2690 2663  .RE
2691 2664  
2692 2665  .sp
2693 2666  .ne 2
2694 2667  .na
2695 2668  \fB\fB/proc/\fIpid\fR/object/a.out\fR\fR
2696 2669  .ad
2697 2670  .sp .6
2698 2671  .RS 4n
2699 2672  alias for process's executable file
2700 2673  .RE
2701 2674  
2702 2675  .sp
2703 2676  .ne 2
2704 2677  .na
2705 2678  \fB\fB/proc/\fIpid\fR/object/*\fR\fR
2706 2679  .ad
2707 2680  .sp .6
2708 2681  .RS 4n
2709 2682  aliases for other mapped files
2710 2683  .RE
2711 2684  
2712 2685  .sp
2713 2686  .ne 2
2714 2687  .na
2715 2688  \fB\fB/proc/\fIpid\fR/lwp\fR\fR
2716 2689  .ad
2717 2690  .sp .6
2718 2691  .RS 4n
2719 2692  directory (list of lwps)
2720 2693  .RE
2721 2694  
2722 2695  .sp
2723 2696  .ne 2
2724 2697  .na
2725 2698  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR\fR\fR
2726 2699  .ad
2727 2700  .sp .6
2728 2701  .RS 4n
2729 2702  specific lwp directory
2730 2703  .RE
2731 2704  
2732 2705  .sp
2733 2706  .ne 2
2734 2707  .na
2735 2708  \fB\fB/proc/\fIpid\fR/lwp/agent\fR\fR
2736 2709  .ad
2737 2710  .sp .6
2738 2711  .RS 4n
2739 2712  alias for the agent lwp directory
2740 2713  .RE
2741 2714  
2742 2715  .sp
2743 2716  .ne 2
2744 2717  .na
2745 2718  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpctl\fR\fR
2746 2719  .ad
2747 2720  .sp .6
2748 2721  .RS 4n
2749 2722  lwp control file
2750 2723  .RE
2751 2724  
2752 2725  .sp
2753 2726  .ne 2
2754 2727  .na
2755 2728  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpstatus\fR\fR
2756 2729  .ad
2757 2730  .sp .6
2758 2731  .RS 4n
2759 2732  lwp status
2760 2733  .RE
2761 2734  
2762 2735  .sp
2763 2736  .ne 2
2764 2737  .na
2765 2738  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpsinfo\fR\fR
2766 2739  .ad
2767 2740  .sp .6
2768 2741  .RS 4n
2769 2742  lwp \fBps\fR(1) info
2770 2743  .RE
2771 2744  
2772 2745  .sp
2773 2746  .ne 2
2774 2747  .na
2775 2748  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/lwpusage\fR\fR
2776 2749  .ad
2777 2750  .sp .6
2778 2751  .RS 4n
2779 2752  lwp usage
2780 2753  .RE
2781 2754  
2782 2755  .sp
2783 2756  .ne 2
2784 2757  .na
2785 2758  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/gwindows\fR\fR
2786 2759  .ad
2787 2760  .sp .6
2788 2761  .RS 4n
2789 2762  register windows (SPARC only)
2790 2763  .RE
2791 2764  
2792 2765  .sp
2793 2766  .ne 2
2794 2767  .na
2795 2768  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/xregs\fR\fR
2796 2769  .ad
2797 2770  .sp .6
2798 2771  .RS 4n
2799 2772  extra state registers
2800 2773  .RE
2801 2774  
2802 2775  .sp
2803 2776  .ne 2
2804 2777  .na
2805 2778  \fB\fB/proc/\fIpid\fR/lwp/\fIlwpid\fR/asrs\fR\fR
2806 2779  .ad
2807 2780  .sp .6
2808 2781  .RS 4n
2809 2782  ancillary state registers (SPARC V9 only)
2810 2783  .RE
2811 2784  
2812 2785  .sp

↓ open down ↓

218 lines elided

↑ open up ↑

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

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

↓ open down ↓

134 lines elided

↑ open up ↑

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

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX