12745 man page typos
1 .\" Copyright 1989 AT&T 2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. 3 .\" Copyright 2019, Joyent, Inc. 4 .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association. 5 .\" 6 .\" The contents of this file are subject to the terms of the 7 .\" Common Development and Distribution License (the "License"). 8 .\" You may not use this file except in compliance with the License. 9 .\" 10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 11 .\" or http://www.opensolaris.org/os/licensing. 12 .\" See the License for the specific language governing permissions 13 .\" and limitations under the License. 14 .\" 15 .\" When distributing Covered Code, include this CDDL HEADER in each 16 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 17 .\" If applicable, add the following below this CDDL HEADER, with the 18 .\" fields enclosed by brackets "[]" replaced with your own identifying 19 .\" information: Portions Copyright [yyyy] [name of copyright owner] 20 .\" 21 .Dd May 17, 2020 22 .Dt PROC 4 23 .Os 24 .Sh NAME 25 .Nm proc 26 .Nd /proc, the process file system 27 .Sh DESCRIPTION 28 .Pa /proc 29 is a file system that provides access to the state of each process 30 and light-weight process (lwp) in the system. 31 The name of each entry in the 32 .Pa /proc 33 directory is a decimal number corresponding to a process-ID. 34 These entries are themselves subdirectories. 35 Access to process state is provided by additional files contained within each 36 subdirectory; the hierarchy is described more completely below. 37 In this document, 38 .Dq Pa /proc file 39 refers to a non-directory file within the hierarchy rooted at 40 .Pa /proc . 41 The owner of each 42 .Pa /proc 43 file and subdirectory is determined by the user-ID of the process. 44 .Pp 45 .Pa /proc 46 can be mounted on any mount point, in addition to the standard 47 .Pa /proc 48 mount point, and can be mounted several places at once. 49 Such additional mounts are allowed in order to facilitate the confinement of 50 processes to subtrees of the file system via 51 .Xr chroot 2 52 and yet allow such processes access to commands like 53 .Xr ps 1 . 54 .Pp 55 Standard system calls are used to access 56 .Pa /proc 57 files: 58 .Xr open 2 , 59 .Xr close 2 , 60 .Xr read 2 , 61 and 62 .Xr write 2 63 (including 64 .Xr readv 2 , 65 .Xr writev 2 , 66 .Xr pread 2 , 67 and 68 .Xr pwrite 2 ) . 69 Most files describe process state and can only be opened for reading. 70 .Pa ctl 71 and 72 .Pa lwpctl 73 (control) files permit manipulation of process state and can only be opened for 74 writing. 75 .Pa as 76 (address space) files contain the image of the running process and can be 77 opened for both reading and writing. 78 An open for writing allows process control; a read-only open allows inspection 79 but not control. 80 In this document, we refer to the process as open for reading or writing if 81 any of its associated 82 .Pa /proc 83 files is open for reading or writing. 84 .Pp 85 In general, more than one process can open the same 86 .Pa /proc 87 file at the same time. \fIExclusive\fR \fIopen\fR is an advisory mechanism provided to 88 allow controlling processes to avoid collisions with each other. 89 A process can obtain exclusive control of a target process, with respect to 90 other cooperating processes, if it successfully opens any 91 .Pa /proc 92 file in the target process for writing (the 93 .Pa as 94 or 95 .Pa ctl 96 files, or the 97 .Pa lwpctl 98 file of any lwp) while specifying 99 .Sy O_EXCL 100 in the 101 .Xr open 2 . 102 Such an open will fail if the target process is already open for writing (that 103 is, if an 104 .Pa as , 105 .Pa ctl , 106 or 107 .Pa lwpctl 108 file is already open for writing). 109 There can be any number of concurrent read-only opens; 110 .Sy O_EXCL 111 is ignored on opens for reading. 112 It is recommended that the first open for writing by a controlling 113 process use the 114 .Sy O_EXCL 115 flag; multiple controlling processes usually result in chaos. 116 .Pp 117 If a process opens one of its own 118 .Pa /proc 119 files for writing, the open 120 succeeds regardless of 121 .Sy O_EXCL 122 and regardless of whether some other process has the process open for writing. 123 Self-opens do not count when another process attempts an exclusive open. 124 (A process cannot exclude a debugger by opening itself for writing and the 125 application of a debugger cannot prevent a process from opening itself.) 126 All self-opens for writing are forced to be close-on-exec (see the 127 .Sy F_SETFD 128 operation of 129 .Xr fcntl 2 ) . 130 .Pp 131 Data may be transferred from or to any locations in the address space of the 132 traced process by applying 133 .Xr lseek 2 134 to position the 135 .Pa as 136 file at the virtual address of interest followed by 137 .Xr read 2 138 or 139 .Xr write 2 140 (or by using 141 .Xr pread 2 142 or 143 .Xr pwrite 2 144 for the combined operation). 145 The address-map files 146 .Pa /proc/ Ns Em pid Ns Pa /map 147 and 148 .Pa /proc/ Ns Em pid Ns Pa /xmap 149 can be read to determine the accessible areas (mappings) of the address space. 150 .Sy I/O 151 transfers may span contiguous mappings. 152 An 153 .Sy I/O 154 request extending into an unmapped area is truncated at the boundary. 155 A write request beginning at an unmapped virtual address fails with 156 .Er EIO ; 157 a read request beginning at an unmapped virtual address returns zero (an 158 end-of-file indication). 159 .Pp 160 Information and control operations are provided through additional files. 161 .In procfs.h 162 contains definitions of data structures and message formats 163 used with these files. 164 Some of these definitions involve the use of sets of flags. 165 The set types 166 .Sy sigset_t , 167 .Sy fltset_t , 168 and 169 .Sy sysset_t 170 correspond, respectively, to signal, fault, and system call enumerations 171 defined in 172 .In sys/signal.h , 173 .In sys/fault.h , 174 and 175 .In sys/syscall.h . 176 Each set type is large enough to hold flags for its own enumeration. 177 Although they are of different sizes, they have a common 178 structure and can be manipulated by these macros: 179 .Bd -literal -offset indent 180 prfillset(&set); /* turn on all flags in set */ 181 premptyset(&set); /* turn off all flags in set */ 182 praddset(&set, flag); /* turn on the specified flag */ 183 prdelset(&set, flag); /* turn off the specified flag */ 184 r = prismember(&set, flag); /* != 0 iff flag is turned on */ 185 .Ed 186 .Pp 187 One of 188 .Fn prfillset 189 or 190 .Fn premptyset 191 must be used to initialize 192 .Fa set 193 before it is used in any other operation. 194 .Fa flag 195 must be a member of the enumeration corresponding to 196 .Fa set . 197 .Pp 198 Every process contains at least one 199 .Em light-weight process , 200 or 201 .Sy lwp . 202 Each lwp represents a flow of execution that is independently scheduled by the 203 operating system. 204 All lwps in a process share its address space as well as many other attributes. 205 Through the use of 206 .Pa lwpctl 207 and 208 .Pa ctl 209 files as described below, it is possible to affect individual lwps in a 210 process or to affect all of them at once, depending on the operation. 211 .Pp 212 When the process has more than one lwp, a representative lwp is chosen by the 213 system for certain process status files and control operations. 214 The representative lwp is a stopped lwp only if all of the process's lwps are 215 stopped; is stopped on an event of interest only if all of the lwps are so 216 stopped (excluding 217 .Sy PR_SUSPENDED 218 lwps); is in a 219 .Sy PR_REQUESTED 220 stop only if there are no other events of interest to be found; or, failing 221 everything else, is in a 222 .Sy PR_SUSPENDED 223 stop (implying that the process is deadlocked). 224 See the description of the 225 .Pa status 226 file for definitions of stopped states. 227 See the 228 .Sy PCSTOP 229 control operation for the definition of 230 .Dq event of interest . 231 .Pp 232 The representative lwp remains fixed (it will be chosen again on the next 233 operation) as long as all of the lwps are stopped on events of interest or are 234 in a 235 .Sy PR_SUSPENDED 236 stop and the 237 .Sy PCRUN 238 control operation is not applied to any of them. 239 .Pp 240 When applied to the process control file, every 241 .Pa /proc 242 control operation 243 that must act on an lwp uses the same algorithm to choose which lwp to act 244 upon. 245 Together with synchronous stopping (see 246 .Sy PCSET ) , 247 this enables a debugger to control a multiple-lwp process using only the 248 process-level status and control files if it so chooses. 249 More fine-grained control can be achieved using the lwp-specific files. 250 .Pp 251 The system supports two process data models, the traditional 32-bit data model 252 in which ints, longs and pointers are all 32 bits wide (the ILP32 data model), 253 and on some platforms the 64-bit data model in which longs and pointers, but 254 not ints, are 64 bits in width (the LP64 data model). 255 In the LP64 data model some system data types, notably 256 .Sy size_t , 257 .Sy off_t , 258 .Sy time_t 259 and 260 .Sy dev_t , 261 grow from 32 bits to 64 bits as well. 262 .Pp 263 The 264 .Pa /proc 265 interfaces described here are available to both 32-bit and 266 64-bit controlling processes. 267 However, many operations attempted by a 32-bit 268 controlling process on a 64-bit target process will fail with 269 .Er EOVERFLOW 270 because the address space range of a 32-bit process cannot encompass a 64-bit 271 process or because the data in some 64-bit system data type cannot be 272 compressed to fit into the corresponding 32-bit type without loss of 273 information. 274 Operations that fail in this circumstance include reading and 275 writing the address space, reading the address-map files, and setting the 276 target process's registers. 277 There is no restriction on operations applied by a 278 64-bit process to either a 32-bit or a 64-bit target processes. 279 .Pp 280 The format of the contents of any 281 .Pa /proc 282 file depends on the data model of the observer (the controlling process), not 283 on the data model of the target process. 284 A 64-bit debugger does not have to translate the information it reads from a 285 .Pa /proc 286 file for a 32-bit process from 32-bit format to 64-bit format. 287 However, it usually has to be aware of the data model of the target process. 288 The 289 .Sy pr_dmodel 290 field of the 291 .Pa status 292 files indicates the target process's data model. 293 .Pp 294 To help deal with system data structures that are read from 32-bit processes, a 295 64-bit controlling program can be compiled with the C preprocessor symbol 296 .Dv _SYSCALL32 297 defined before system header files are included. 298 This makes explicit 32-bit fixed-width data structures (like 299 .Sy struct stat32 ) 300 visible to the 64-bit program. 301 See 302 .Xr types32.h 3HEAD . 303 .Sh DIRECTORY STRUCTURE 304 At the top level, the directory 305 .Pa /proc 306 contains entries each of which names an existing process in the system. 307 These entries are themselves directories. 308 Except where otherwise noted, the files described below can be 309 opened for reading only. 310 In addition, if a process becomes a 311 .Em zombie 312 (one that has exited but whose parent has not yet performed a 313 .Xr wait 3C 314 upon it), most of its associated 315 .Pa /proc 316 files disappear from the hierarchy; subsequent attempts to open them, or to 317 read or write files opened before the process exited, will elicit the error 318 .Er ENOENT . 319 .Pp 320 Although process state and consequently the contents of 321 .Pa /proc 322 files can change from instant to instant, a single 323 .Xr read 2 324 of a 325 .Pa /proc 326 file is guaranteed to return a sane representation of state; that is, the read 327 will be atomic with respect to the state of the process. 328 No such guarantee applies to successive reads applied to a 329 .Pa /proc 330 file for a running process. 331 In addition, atomicity is not guaranteed for 332 .Sy I/O 333 applied to the 334 .Pa as 335 (address-space) file for a running process or for a process whose address space 336 contains memory shared by another running process. 337 .Pp 338 A number of structure definitions are used to describe the files. 339 These structures may grow by the addition of elements at the end in future 340 releases of the system and it is not legitimate for a program to assume that 341 they will not. 342 .Sh STRUCTURE OF Pa /proc/ Ns Em pid 343 A given directory 344 .Pa /proc/ Ns Em pid 345 contains the following entries. 346 A process can use the invisible alias 347 .Pa /proc/self 348 if it wishes to open one of its own 349 .Pa /proc 350 files (invisible in the sense that the name 351 .Dq self 352 does not appear in a directory listing of 353 .Pa /proc 354 obtained from 355 .Xr ls 1 , 356 .Xr getdents 2 , 357 or 358 .Xr readdir 3C ) . 359 .Ss contracts 360 A directory containing references to the contracts held by the process. 361 Each entry is a symlink to the contract's directory under 362 .Pa /system/contract . 363 See 364 .Xr contract 4 . 365 .Ss as 366 Contains the address-space image of the process; it can be opened for both 367 reading and writing. 368 .Xr lseek 2 369 is used to position the file at the virtual address of interest and then the 370 address space can be examined or changed through 371 .Xr read 2 372 or 373 .Xr write 2 374 (or by using 375 .Xr pread 2 376 or 377 .Xr pwrite 2 378 for the combined operation). 379 .Ss ctl 380 A write-only file to which structured messages are written directing the system 381 to change some aspect of the process's state or control its behavior in some 382 way. 383 The seek offset is not relevant when writing to this file. 384 Individual lwps also have associated 385 .Pa lwpctl 386 files in the lwp subdirectories. 387 A control message may be written either to the process's 388 .Pa ctl 389 file or to a specific 390 .Pa lwpctl 391 file with operation-specific effects. 392 The effect of a control message is immediately reflected in the state of the 393 process visible through appropriate status and information files. 394 The types of control messages are described in detail later. 395 See 396 .Sx CONTROL MESSAGES . 397 .Ss status 398 Contains state information about the process and the representative lwp. 399 The file contains a 400 .Sy pstatus 401 structure which contains an embedded 402 .Sy lwpstatus 403 structure for the representative lwp, as follows: 404 .Bd -literal -offset 2 405 typedef struct pstatus { 406 int pr_flags; /* flags (see below) */ 407 int pr_nlwp; /* number of active lwps in the process */ 408 int pr_nzomb; /* number of zombie lwps in the process */ 409 pid_tpr_pid; /* process id */ 410 pid_tpr_ppid; /* parent process id */ 411 pid_tpr_pgid; /* process group id */ 412 pid_tpr_sid; /* session id */ 413 id_t pr_aslwpid; /* obsolete */ 414 id_t pr_agentid; /* lwp-id of the agent lwp, if any */ 415 sigset_t pr_sigpend; /* set of process pending signals */ 416 uintptr_t pr_brkbase; /* virtual address of the process heap */ 417 size_t pr_brksize; /* size of the process heap, in bytes */ 418 uintptr_t pr_stkbase; /* virtual address of the process stack */ 419 size_tpr_stksize; /* size of the process stack, in bytes */ 420 timestruc_t pr_utime; /* process user cpu time */ 421 timestruc_t pr_stime; /* process system cpu time */ 422 timestruc_t pr_cutime; /* sum of children's user times */ 423 timestruc_t pr_cstime; /* sum of children's system times */ 424 sigset_t pr_sigtrace; /* set of traced signals */ 425 fltset_t pr_flttrace; /* set of traced faults */ 426 sysset_t pr_sysentry; /* set of system calls traced on entry */ 427 sysset_t pr_sysexit; /* set of system calls traced on exit */ 428 char pr_dmodel; /* data model of the process */ 429 taskid_t pr_taskid; /* task id */ 430 projid_t pr_projid; /* project id */ 431 zoneid_t pr_zoneid; /* zone id */ 432 lwpstatus_t pr_lwp; /* status of the representative lwp */ 433 } pstatus_t; 434 .Ed 435 .Pp 436 .Sy pr_flags 437 is a bit-mask holding the following process flags. 438 For convenience, it also contains the lwp flags for the representative lwp, 439 described later. 440 .Bl -tag -width "PR_MSACCT" -offset indent 441 .It Sy PR_ISSYS 442 process is a system process (see 443 .Sx PCSTOP ) . 444 .It Sy PR_VFORKP 445 process is the parent of a vforked child (see 446 .Sx PCWATCH ) . 447 .It Sy PR_FORK 448 process has its inherit-on-fork mode set (see 449 .Sx PCSET ) . 450 .It Sy PR_RLC 451 process has its run-on-last-close mode set (see 452 .Sx PCSET ) . 453 .It Sy PR_KLC 454 process has its kill-on-last-close mode set (see 455 .Sx PCSET ) . 456 .It Sy PR_ASYNC 457 process has its asynchronous-stop mode set (see 458 .Sx PCSET ) . 459 .It Sy PR_MSACCT 460 Set by default in all processes to indicate that microstate accounting is 461 enabled. 462 However, this flag has been deprecated and no longer has any effect. 463 Microstate accounting may not be disabled; however, it is still possible to 464 toggle the flag. 465 .It Sy PR_MSFORK 466 Set by default in all processes to indicate that microstate accounting will be 467 enabled for processes that this parent 468 .Xr fork 2 Ns s . 469 However, this flag has been deprecated and no longer has any effect. 470 It is possible to toggle this flag; however, it is not possible to disable 471 microstate accounting. 472 .It Sy PR_BPTADJ 473 process has its breakpoint adjustment mode set (see 474 .Sx PCSET ) . 475 .It Sy PR_PTRACE 476 process has its ptrace-compatibility mode set (see 477 .Sx PCSET ) . 478 .El 479 .Pp 480 .Sy pr_nlwp 481 is the total number of active lwps in the process. 482 .Sy pr_nzomb 483 is the total number of zombie lwps in the process. 484 A zombie lwp is a non-detached lwp that has terminated but has not been reaped 485 with 486 .Xr thr_join 3C 487 or 488 .Xr pthread_join 3C . 489 .Pp 490 .Sy pr_pid , 491 .Sy pr_ppi , 492 .Sy pr_pgid , 493 and 494 .Sy pr_sid 495 are, respectively, the process ID, the ID of the process's parent, the 496 process's process group ID, and the process's session ID. 497 .Pp 498 .Sy pr_aslwpid 499 is obsolete and is always zero. 500 .Pp 501 .Sy pr_agentid 502 is the lwp-ID for the 503 .Pa /proc 504 agent lwp (see the 505 .Sx PCAGENT 506 control operation). 507 It is zero if there is no agent lwp in the process. 508 .Pp 509 .Sy pr_sigpend 510 identifies asynchronous signals pending for the process. 511 .Pp 512 .Sy pr_brkbase 513 is the virtual address of the process heap and 514 .Sy pr_brksize 515 is its size in bytes. 516 The address formed by the sum of these values is the process 517 .Sy break 518 (see 519 .Xr brk 2 ) . 520 .Sy pr_stkbase 521 and 522 .Sy pr_stksize 523 are, respectively, the virtual address of the process stack and its size in 524 bytes. 525 (Each lwp runs on a separate stack; the distinguishing characteristic of the 526 process stack is that the operating system will grow it when necessary.) 527 .Pp 528 .Sy pr_utime , 529 .Sy pr_stime , 530 .Sy pr_cutime , 531 .Sy and pr_cstime 532 are, respectively, the user 533 .Sy CPU 534 and system 535 .Sy CPU 536 time consumed by the process, and the cumulative user 537 .Sy CPU 538 and system 539 .Sy CPU 540 time consumed by the process's children, in seconds and nanoseconds. 541 .Pp 542 .Sy pr_sigtrace 543 and 544 .Sy pr_flttrace 545 contain, respectively, the set of signals and the set of hardware faults that 546 are being traced (see 547 .Sx PCSTRACE 548 and 549 .Sx PCSFAULT ) . 550 .Pp 551 .Sy pr_sysentry 552 and 553 .Sy pr_sysexit 554 contain, respectively, the sets of system calls being traced on entry and exit 555 (see 556 .Sx PCSENTRY 557 and 558 .Sx PCSEXIT ) . 559 .Pp 560 .Sy pr_dmodel 561 indicates the data model of the process. 562 Possible values are: 563 .Bl -tag -width "PR_MODEL_NATIVE" -offset indent 564 .It Sy PR_MODEL_ILP32 565 process data model is ILP32. 566 .It Sy PR_MODEL_LP64 567 process data model is LP64. 568 .It Sy PR_MODEL_NATIVE 569 process data model is native. 570 .El 571 .Pp 572 The 573 .Sy pr_taskid , 574 .Sy pr_projid , 575 and 576 .Sy pr_zoneid 577 fields contain respectively, the numeric 578 .Sy ID Ns s 579 of the task, project, and zone in which the process was running. 580 .Pp 581 The constant 582 .Sy PR_MODEL_NATIVE 583 reflects the data model of the controlling process, 584 .Em that is , 585 its value is 586 .Sy PR_MODEL_ILP32 587 or 588 .Sy PR_MODEL_LP64 589 according to whether the controlling process has been 590 compiled as a 32-bit program or a 64-bit program, respectively. 591 .Pp 592 .Sy pr_lwp 593 contains the status information for the representative lwp: 594 .Bd -literal -offset 2 595 typedef struct lwpstatus { 596 int pr_flags; /* flags (see below) */ 597 id_t pr_lwpid; /* specific lwp identifier */ 598 short pr_why; /* reason for lwp stop, if stopped */ 599 short pr_what; /* more detailed reason */ 600 short pr_cursig; /* current signal, if any */ 601 siginfo_t pr_info; /* info associated with signal or fault */ 602 sigset_t pr_lwppend; /* set of signals pending to the lwp */ 603 sigset_t pr_lwphold; /* set of signals blocked by the lwp */ 604 struct sigaction pr_action;/* signal action for current signal */ 605 stack_t pr_altstack; /* alternate signal stack info */ 606 uintptr_t pr_oldcontext; /* address of previous ucontext */ 607 short pr_syscall; /* system call number (if in syscall) */ 608 short pr_nsysarg; /* number of arguments to this syscall */ 609 int pr_errno; /* errno for failed syscall */ 610 long pr_sysarg[PRSYSARGS]; /* arguments to this syscall */ 611 long pr_rval1; /* primary syscall return value */ 612 long pr_rval2; /* second syscall return value, if any */ 613 char pr_clname[PRCLSZ]; /* scheduling class name */ 614 timestruc_t pr_tstamp; /* real-time time stamp of stop */ 615 timestruc_t pr_utime; /* lwp user cpu time */ 616 timestruc_t pr_stime; /* lwp system cpu time */ 617 uintptr_t pr_ustack; /* stack boundary data (stack_t) address */ 618 ulong_t pr_instr; /* current instruction */ 619 prgregset_t pr_reg; /* general registers */ 620 prfpregset_t pr_fpreg; /* floating-point registers */ 621 } lwpstatus_t; 622 .Ed 623 .Pp 624 .Sy pr_flags 625 is a bit-mask holding the following lwp flags. 626 For convenience, it also contains the process flags, described previously. 627 .Bl -tag -width "PR_STOPPED" -offset indent 628 .It Sy PR_STOPPED 629 The lwp is stopped. 630 .It Sy PR_ISTOP 631 The lwp is stopped on an event of interest (see 632 .Sx PCSTOP ) . 633 .It Sy PR_DSTOP 634 The lwp has a stop directive in effect (see 635 .Sx PCSTOP ) . 636 .It Sy PR_STEP 637 The lwp has a single-step directive in effect (see 638 .Sx PCRUN ) . 639 .It Sy PR_ASLEEP 640 The lwp is in an interruptible sleep within a system call. 641 .It Sy PR_PCINVAL 642 The lwp's current instruction 643 .Pq Sy pr_instr 644 is undefined. 645 .It Sy PR_DETACH 646 This is a detached lwp (see 647 .Xr pthread_create 3C 648 and 649 .Xr pthread_join 3C ) . 650 .It Sy PR_DAEMON 651 This is a daemon lwp (see 652 .Xr pthread_create 3C ) . 653 .It Sy PR_ASLWP 654 This flag is obsolete and is never set. 655 .It Sy PR_AGENT 656 This is the 657 .Pa /proc 658 agent lwp for the process. 659 .El 660 .Pp 661 .Sy pr_lwpid 662 names the specific lwp. 663 .Pp 664 .Sy pr_why 665 .Sy and 666 pr_what 667 together describe, for a stopped lwp, the reason for the stop. 668 Possible values of 669 .Sy pr_why 670 and the associated 671 .Sy pr_what 672 are: 673 .Bl -tag -width "PR_JOBCONTROL" -offset left 674 .It Sy PR_REQUESTED 675 indicates that the stop occurred in response to a stop directive, normally 676 because 677 .Sy PCSTOP 678 was applied or because another lwp stopped on an event of interest and the 679 asynchronous-stop flag (see 680 .Sx PCSET ) 681 was not set for the process. 682 .Sy pr_what 683 is unused in this case. 684 .It Sy PR_SIGNALLED 685 indicates that the lwp stopped on receipt of a signal (see 686 .Sx PCSTRACE ) ; 687 .Sy pr_what 688 holds the signal number that caused the stop (for a newly-stopped 689 lwp, the same value is in 690 .Sy pr_cursig ) . 691 .It Sy PR_FAULTED 692 indicates that the lwp stopped on incurring a hardware fault (see 693 .Sx PCSFAULT ) ; 694 .Sy pr_what 695 holds the fault number that caused the stop. 696 .It Sy PR_SYSENTRY 697 .It Sy PR_SYSEXIT 698 indicate a stop on entry to or exit from a system call (see 699 .Sx PCSENTRY 700 and 701 .Sx PCSEXIT ) ; 702 .Sy pr_what 703 holds the system call number. 704 .It Sy PR_JOBCONTROL 705 indicates that the lwp stopped due to the default action of a job control stop 706 signal (see 707 .Xr sigaction 2 ) ; 708 .Sy pr_what 709 holds the stopping signal number. 710 .It Sy PR_SUSPENDED 711 indicates that the lwp stopped due to internal synchronization of lwps within 712 the process. 713 .Sy pr_what 714 is unused in this case. 715 .El 716 .Pp 717 .Sy pr_cursig 718 names the current signal, that is, the next signal to be delivered to the lwp, 719 if any. 720 .Sy pr_info , 721 when the lwp is in a 722 .Sy PR_SIGNALLED 723 or 724 .Sy PR_FAULTED 725 stop, contains additional information pertinent to the particular signal or 726 fault (see 727 .In sys/siginfo.h ) . 728 .Pp 729 .Sy pr_lwppend 730 identifies any synchronous or directed signals pending for the lwp. 731 .Sy pr_lwphold 732 identifies those signals whose delivery is being blocked by the lwp (the 733 signal mask). 734 .Pp 735 .Sy pr_action 736 contains the signal action information pertaining to the current signal (see 737 .Xr sigaction 2 ) ; 738 it is undefined if 739 .Sy pr_cursig 740 is zero. 741 .Sy pr_altstack 742 contains the alternate signal stack information for the lwp (see 743 .Xr sigaltstack 2 ) . 744 .Pp 745 .Sy pr_oldcontext , 746 if not zero, contains the address on the lwp stack of a 747 .Sy ucontext 748 structure describing the previous user-level context (see 749 .Xr ucontext.h 3HEAD ) . 750 It is non-zero only if the lwp is executing in the context of a signal handler. 751 .Pp 752 .Sy pr_syscall 753 is the number of the system call, if any, being executed by 754 the lwp; it is non-zero if and only if the lwp is stopped on 755 .Sy PR_SYSENTRY 756 or 757 .Sy PR_SYSEXIT , 758 or is asleep within a system call 759 .Pf ( Sy PR_ASLEEP 760 is set). 761 If 762 .Sy pr_syscall 763 is non-zero, 764 .Sy pr_nsysarg 765 is the number of arguments to the system call and 766 .Sy pr_sysarg 767 contains the actual arguments. 768 .Pp 769 .Sy pr_rval1 , 770 .Sy pr_rval2 , 771 and 772 .Sy pr_errno 773 are defined only if the lwp 774 is stopped on 775 .Sy PR_SYSEXIT 776 or if the 777 .Sy PR_VFORKP 778 flag is set. 779 If 780 .Sy pr_errno 781 is zero, 782 .Sy pr_rval1 783 and 784 .Sy pr_rval2 785 contain the return values from the system call. 786 Otherwise, 787 .Sy pr_errno 788 contains the error number for the failing system call (see 789 .In sys/errno.h ) . 790 .Pp 791 .Sy pr_clname 792 contains the name of the lwp's scheduling class. 793 .Pp 794 .Sy pr_tstamp , 795 if the lwp is stopped, contains a time stamp marking when the 796 lwp stopped, in real time seconds and nanoseconds since an arbitrary time in 797 the past. 798 .Pp 799 .Sy pr_utime 800 is the amount of user level CPU time used by this LWP. 801 .Pp 802 .Sy pr_stime 803 is the amount of system level CPU time used by this LWP. 804 .Pp 805 .Sy pr_ustack 806 is the virtual address of the 807 .Sy stack_t 808 that contains the stack boundaries for this LWP. 809 See 810 .Xr getustack 2 811 and 812 .Xr _stack_grow 3C . 813 .Pp 814 .Sy pr_instr 815 contains the machine instruction to which the lwp's program counter refers. 816 The amount of data retrieved from the process is machine-dependent. 817 On SPARC based machines, it is a 32-bit word. 818 On x86-based machines, it is a single byte. 819 In general, the size is that of the machine's smallest instruction. 820 If 821 .Sy PR_PCINVAL 822 is set, 823 .Sy pr_instr 824 is undefined; this occurs whenever the lwp is not stopped or when the program 825 counter refers to an invalid virtual address. 826 .Pp 827 .Sy pr_reg 828 is an array holding the contents of a stopped lwp's general registers. 829 .Bl -tag -offset left -width "SPARC V8 (32-bit)" 830 .It Sy SPARC 831 On SPARC-based machines, the predefined constants 832 .Sy R_G0 833 \&.\&.\&. 834 .Sy R_G7 , 835 .Sy R_O0 836 \&.\&.\&. 837 .Sy R_O7 , 838 .Sy R_L0 839 \&.\&.\&. 840 .Sy R_L7 , 841 .Sy R_I0 842 \&.\&.\&. 843 .Sy R_I7 , 844 .Sy R_PC , 845 .Sy R_nPC , 846 and 847 .Sy R_Y 848 can be used as indices to refer to the corresponding registers; previous 849 register windows can be read from their overflow locations on the stack 850 (however, see the 851 .Pa gwindows 852 file in the 853 .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid 854 subdirectory). 855 .It Sy SPARC V8 (32-bit) 856 For SPARC V8 (32-bit) controlling processes, the predefined constants 857 .Sy R_PSR , 858 .Sy R_WIM , 859 and 860 .Sy R_TBR 861 can be used as indices to refer to the corresponding special registers. 862 For SPARC V9 (64-bit) controlling processes, the predefined constants 863 .Sy R_CCR , 864 .Sy R_ASI , 865 and 866 .Sy R_FPRS 867 can be used as indices to refer to the corresponding special registers. 868 .It Sy x86 (32-bit) 869 For 32-bit x86 processes, the predefined constants listed belowcan be used as 870 indices to refer to the corresponding registers. 871 .Bl -tag -width "TRAPNO" -offset indent -compact 872 .It SS 873 .It UESP 874 .It EFL 875 .It CS 876 .It EIP 877 .It ERR 878 .It TRAPNO 879 .It EAX 880 .It ECX 881 .It EDX 882 .It EBX 883 .It ESP 884 .It EBP 885 .It ESI 886 .It EDI 887 .It DS 888 .It ES 889 .It GS 890 .El 891 .Pp 892 The preceding constants are listed in 893 .In sys/regset.h . 894 .Pp 895 Note that a 32-bit process can run on an x86 64-bit system, using the constants 896 listed above. 897 .It Sy x86 (64-bit) 898 To read the registers of a 32- 899 .Em or 900 a 64-bit process, a 64-bit x86 process should use the predefined constants 901 listed below. 902 .Bl -tag -width "REG_TRAPNO" -offset indent -compact 903 .It REG_GSBASE 904 .It REG_FSBASE 905 .It REG_DS 906 .It REG_ES 907 .It REG_GS 908 .It REG_FS 909 .It REG_SS 910 .It REG_RSP 911 .It REG_RFL 912 .It REG_CS 913 .It REG_RIP 914 .It REG_ERR 915 .It REG_TRAPNO 916 .It REG_RAX 917 .It REG_RCX 918 .It REG_RDX 919 .It REG_RBX 920 .It REG_RBP 921 .It REG_RSI 922 .It REG_RDI 923 .It REG_R8 924 .It REG_R9 925 .It REG_R10 926 .It REG_R11 927 .It REG_R12 928 .It REG_R13 929 .It REG_R14 930 .It REG_R15 931 .El 932 .Pp 933 The preceding constants are listed in 934 .In sys/regset.h . 935 .El 936 .Pp 937 .Sy pr_fpreg 938 is a structure holding the contents of the floating-point registers. 939 .Pp 940 SPARC registers, both general and floating-point, as seen by a 64-bit 941 controlling process are the V9 versions of the registers, even if the target 942 process is a 32-bit (V8) process. 943 V8 registers are a subset of the V9 registers. 944 .Pp 945 If the lwp is not stopped, all register values are undefined. 946 .Ss psinfo 947 Contains miscellaneous information about the process and the representative lwp 948 needed by the 949 .Xr ps 1 950 command. 951 .Sy psinfo 952 remains accessible after a process becomes a 953 .Em zombie . 954 The file contains a 955 .Sy psinfo 956 structure which contains an embedded 957 .Sy lwpsinfo 958 structure for the representative lwp, as follows: 959 .Bd -literal -offset 2 960 typedef struct psinfo { 961 int pr_flag; /* process flags (DEPRECATED: see below) */ 962 int pr_nlwp; /* number of active lwps in the process */ 963 int pr_nzomb; /* number of zombie lwps in the process */ 964 pid_t pr_pid; /* process id */ 965 pid_t pr_ppid; /* process id of parent */ 966 pid_t pr_pgid; /* process id of process group leader */ 967 pid_t pr_sid; /* session id */ 968 uid_t pr_uid; /* real user id */ 969 uid_t pr_euid; /* effective user id */ 970 gid_t pr_gid; /* real group id */ 971 gid_t pr_egid; /* effective group id */ 972 uintptr_t pr_addr; /* address of process */ 973 size_t pr_size; /* size of process image in Kbytes */ 974 size_t pr_rssize; /* resident set size in Kbytes */ 975 dev_t pr_ttydev; /* controlling tty device (or PRNODEV) */ 976 ushort_t pr_pctcpu; /* % of recent cpu time used by all lwps */ 977 ushort_t pr_pctmem; /* % of system memory used by process */ 978 timestruc_t pr_start; /* process start time, from the epoch */ 979 timestruc_t pr_time; /* cpu time for this process */ 980 timestruc_t pr_ctime; /* cpu time for reaped children */ 981 char pr_fname[PRFNSZ]; /* name of exec'ed file */ 982 char pr_psargs[PRARGSZ]; /* initial characters of arg list */ 983 int pr_wstat; /* if zombie, the wait() status */ 984 int pr_argc; /* initial argument count */ 985 uintptr_t pr_argv; /* address of initial argument vector */ 986 uintptr_t pr_envp; /* address of initial environment vector */ 987 char pr_dmodel; /* data model of the process */ 988 taskid_t pr_taskid; /* task id */ 989 projid_t pr_projid; /* project id */ 990 poolid_t pr_poolid; /* pool id */ 991 zoneid_t pr_zoneid; /* zone id */ 992 ctid_t pr_contract; /* process contract id */ 993 lwpsinfo_t pr_lwp; /* information for representative lwp */ 994 } psinfo_t; 995 .Ed 996 .Pp 997 Some of the entries in 998 .Sy psinfo , 999 such as 1000 .Sy pr_addr , 1001 refer to internal kernel data structures and should not be expected to retain 1002 their meanings across different versions of the operating system. 1003 .Pp 1004 .Sy psinfo_t.pr_flag 1005 is a deprecated interface that should no longer be used. 1006 Applications currently relying on the 1007 .Sy SSYS 1008 bit in 1009 .Sy pr_flag 1010 should migrate to checking 1011 .Sy PR_ISSYS 1012 in the 1013 .Sy pstatus 1014 structure's 1015 .Sy pr_flags 1016 field. 1017 .Pp 1018 .Sy pr_pctcpu 1019 and 1020 .Sy pr_pctmem 1021 are 16-bit binary fractions in the range 0.0 to 1.0 with the binary point to 1022 the right of the high-order bit (1.0 == 0x8000). 1023 .Sy pr_pctcpu 1024 is the summation over all lwps in the process. 1025 .Pp 1026 .Sy pr_lwp 1027 contains the 1028 .Xr ps 1 1029 information for the representative lwp. 1030 If the process is a 1031 .Em zombie , 1032 .Sy pr_nlwp , 1033 .Sy pr_nzomb , 1034 and 1035 .Sy pr_lwp.pr_lwpid 1036 are zero and the other fields of 1037 .Sy pr_lwp 1038 are undefined: 1039 .Bd -literal -offset 2 1040 typedef struct lwpsinfo { 1041 int pr_flag; /* lwp flags (DEPRECATED: see below) */ 1042 id_t pr_lwpid; /* lwp id */ 1043 uintptr_t pr_addr; /* internal address of lwp */ 1044 uintptr_t pr_wchan; /* wait addr for sleeping lwp */ 1045 char pr_stype; /* synchronization event type */ 1046 char pr_state; /* numeric lwp state */ 1047 char pr_sname; /* printable character for pr_state */ 1048 char pr_nice; /* nice for cpu usage */ 1049 short pr_syscall; /* system call number (if in syscall) */ 1050 char pr_oldpri; /* pre-SVR4, low value is high priority */ 1051 char pr_cpu; /* pre-SVR4, cpu usage for scheduling */ 1052 int pr_pri; /* priority, high value = high priority */ 1053 ushort_t pr_pctcpu; /* % of recent cpu time used by this lwp */ 1054 timestruc_t pr_start; /* lwp start time, from the epoch */ 1055 timestruc_t pr_time; /* cpu time for this lwp */ 1056 char pr_clname[PRCLSZ]; /* scheduling class name */ 1057 char pr_name[PRFNSZ]; /* name of system lwp */ 1058 processorid_t pr_onpro; /* processor which last ran this lwp */ 1059 processorid_t pr_bindpro;/* processor to which lwp is bound */ 1060 psetid_t pr_bindpset; /* processor set to which lwp is bound */ 1061 lgrp_id_t pr_lgrp; /* home lgroup */ 1062 } lwpsinfo_t; 1063 .Ed 1064 .Pp 1065 Some of the entries in 1066 .Sy lwpsinfo , 1067 such as 1068 .Sy pr_addr , 1069 .Sy pr_wchan , 1070 .Sy pr_stype , 1071 .Sy pr_state , 1072 and 1073 .Sy pr_name , 1074 refer to internal kernel data structures and should not be expected to retain 1075 their meanings across different versions of the operating system. 1076 .Pp 1077 .Sy lwpsinfo_t.pr_flag 1078 is a deprecated interface that should no longer be used. 1079 .Pp 1080 .Sy pr_pctcpu 1081 is a 16-bit binary fraction, as described above. 1082 It represents the 1083 .Sy CPU 1084 time used by the specific lwp. 1085 On a multi-processor machine, the maximum value is 1/N, where N is the number 1086 of 1087 .Sy CPU Ns s . 1088 .Pp 1089 .Sy pr_contract 1090 is the id of the process contract of which the process is a member. 1091 See 1092 .Xr contract 4 1093 and 1094 .Xr process 4 . 1095 .Ss cred 1096 Contains a description of the credentials associated with the process: 1097 .Bd -literal -offset 2 1098 typedef struct prcred { 1099 uid_t pr_euid; /* effective user id */ 1100 uid_t pr_ruid; /* real user id */ 1101 uid_t pr_suid; /* saved user id (from exec) */ 1102 gid_t pr_egid; /* effective group id */ 1103 gid_t pr_rgid; /* real group id */ 1104 gid_t pr_sgid; /* saved group id (from exec) */ 1105 int pr_ngroups; /* number of supplementary groups */ 1106 gid_t pr_groups[1]; /* array of supplementary groups */ 1107 } prcred_t; 1108 .Ed 1109 .Pp 1110 The array of associated supplementary groups in 1111 .Sy pr_groups 1112 is of variable 1113 length; the 1114 .Sy cred 1115 file contains all of the supplementary groups. 1116 .Sy pr_ngroups 1117 indicates the number of supplementary groups. (See also the 1118 .Sy PCSCRED 1119 and 1120 .Sy PCSCREDX 1121 control operations.) 1122 .Ss priv 1123 Contains a description of the privileges associated with the process: 1124 .Bd -literal -offset 2 1125 typedef struct prpriv { 1126 uint32_t pr_nsets; /* number of privilege set */ 1127 uint32_t pr_setsize; /* size of privilege set */ 1128 uint32_t pr_infosize; /* size of supplementary data */ 1129 priv_chunk_t pr_sets[1]; /* array of sets */ 1130 } prpriv_t; 1131 .Ed 1132 .Pp 1133 The actual dimension of the 1134 .Sy pr_sets Ns [] 1135 field is 1136 .D1 pr_sets[pr_nsets][pr_setsize] 1137 .Pp 1138 which is followed by additional information about the process state 1139 .Sy pr_infosize 1140 bytes in size. 1141 .Pp 1142 The full size of the structure can be computed using 1143 .Fn PRIV_PRPRIV_SIZE "prpriv_t *" . 1144 .Ss secflags 1145 This file contains the security-flags of the process. 1146 It contains a description of the security flags associated with the process. 1147 .Bd -literal -offset 2 1148 typedef struct prsecflags { 1149 uint32_t pr_version; /* ABI Versioning of this structure */ 1150 secflagset_t pr_effective; /* Effective flags */ 1151 secflagset_t pr_inherit; /* Inheritable flags */ 1152 secflagset_t pr_lower; /* Lower flags */ 1153 secflagset_t pr_upper; /* Upper flags */ 1154 } prsecflags_t; 1155 .Ed 1156 .Pp 1157 The 1158 .Sy pr_version 1159 field is a version number for the structure, currently 1160 .Sy PRSECFLAGS_VERSION_1 . 1161 .Ss sigact 1162 Contains an array of 1163 .Sy sigaction structures 1164 describing the current dispositions of all signals associated with the traced 1165 process (see 1166 .Xr sigaction 2 ) . 1167 Signal numbers are displaced by 1 from array indices, so that the action for 1168 signal number 1169 .Va n 1170 appears in position 1171 .Va n Ns -1 1172 of the array. 1173 .Ss auxv 1174 Contains the initial values of the process's aux vector in an array of 1175 .Sy auxv_t 1176 structures (see 1177 .In sys/auxv.h ) . 1178 The values are those that were passed by the operating system as startup 1179 information to the dynamic linker. 1180 .Ss ldt 1181 This file exists only on x86-based machines. 1182 It is non-empty only if the process has established a local descriptor table 1183 .Pq Sy LDT . 1184 If non-empty, the file contains the array of currently active 1185 .Sy LDT 1186 entries in an array of elements of type 1187 .Vt struct ssd , 1188 defined in 1189 .In sys/sysi86.h , 1190 one element for each active 1191 .Sy LDT 1192 entry. 1193 .Ss map, xmap 1194 Contain information about the virtual address map of the process. 1195 The map file contains an array of 1196 .Sy prmap 1197 structures while the xmap file contains an 1198 array of 1199 .Sy prxmap 1200 structures. 1201 Each structure describes a contiguous virtual 1202 address region in the address space of the traced process: 1203 .Bd -literal -offset 2 1204 typedef struct prmap { 1205 uintptr_tpr_vaddr; /* virtual address of mapping */ 1206 size_t pr_size; /* size of mapping in bytes */ 1207 char pr_mapname[PRMAPSZ]; /* name in /proc/pid/object */ 1208 offset_t pr_offset; /* offset into mapped object, if any */ 1209 int pr_mflags; /* protection and attribute flags */ 1210 int pr_pagesize; /* pagesize for this mapping in bytes */ 1211 int pr_shmid; /* SysV shared memory identifier */ 1212 } prmap_t; 1213 .Ed 1214 .Bd -literal -offset 2 1215 typedef struct prxmap { 1216 uintptr_t pr_vaddr; /* virtual address of mapping */ 1217 size_t pr_size; /* size of mapping in bytes */ 1218 char pr_mapname[PRMAPSZ]; /* name in /proc/pid/object */ 1219 offset_t pr_offset; /* offset into mapped object, if any */ 1220 int pr_mflags; /* protection and attribute flags */ 1221 int pr_pagesize; /* pagesize for this mapping in bytes */ 1222 int pr_shmid; /* SysV shared memory identifier */ 1223 dev_t pr_dev; /* device of mapped object, if any */ 1224 uint64_t pr_ino; /* inode of mapped object, if any */ 1225 size_t pr_rss; /* pages of resident memory */ 1226 size_t pr_anon; /* pages of resident anonymous memory */ 1227 size_t pr_locked; /* pages of locked memory */ 1228 uint64_t pr_hatpagesize; /* pagesize of mapping */ 1229 } prxmap_t; 1230 .Ed 1231 .Pp 1232 .Sy pr_vaddr 1233 is the virtual address of the mapping within the traced process and 1234 .Sy pr_size 1235 is its size in bytes. 1236 .Sy pr_mapname , 1237 if it does not contain a null string, contains the name of a file in the 1238 .Sy object 1239 directory (see below) that can be opened read-only to obtain a file descriptor 1240 for the mapped file associated with the mapping. 1241 This enables a debugger to find object file symbol tables without having to 1242 know the real path names of the executable file and shared libraries of 1243 the process. 1244 .Sy pr_offset 1245 is the 64-bit offset within the mapped file (if any) to which the virtual 1246 address is mapped. 1247 .Pp 1248 .Sy pr_mflags 1249 is a bit-mask of protection and attribute flags: 1250 .Bl -tag -width "MA_NORESERVE" -offset left 1251 .It Sy MA_READ 1252 mapping is readable by the traced process. 1253 .It Sy MA_WRITE 1254 mapping is writable by the traced process. 1255 .It Sy MA_EXEC 1256 mapping is executable by the traced process. 1257 .It Sy MA_SHARED 1258 mapping changes are shared by the mapped object. 1259 .It Sy MA_ISM 1260 mapping is intimate shared memory (shared MMU resources) 1261 .It Sy MAP_NORESERVE 1262 mapping does not have swap space reserved (mapped with MAP_NORESERVE) 1263 .It Sy MA_SHM 1264 mapping System V shared memory 1265 .El 1266 .Pp 1267 A contiguous area of the address space having the same underlying mapped object 1268 may appear as multiple mappings due to varying read, write, and execute 1269 attributes. 1270 The underlying mapped object does not change over the range of a 1271 single mapping. 1272 An 1273 .Sy I/O 1274 operation to a mapping marked 1275 .Sy MA_SHARED 1276 fails if applied at a virtual address not corresponding to a valid page in the 1277 underlying mapped object. 1278 A write to a 1279 .Sy MA_SHARED 1280 mapping that is not marked 1281 .Sy MA_WRITE 1282 fails. 1283 Reads and writes to private mappings always succeed. 1284 Reads and writes to unmapped addresses fail. 1285 .Pp 1286 .Sy pr_pagesize 1287 is the page size for the mapping, currently always the system pagesize. 1288 .Pp 1289 .Sy pr_shmid 1290 is the shared memory identifier, if any, for the mapping. 1291 Its value is \-1 1292 if the mapping is not System V shared memory. 1293 See 1294 .Xr shmget 2 . 1295 .Pp 1296 .Sy pr_dev 1297 is the device of the mapped object, if any, for the mapping. 1298 Its value is 1299 .Sy PRNODEV 1300 .Pq \-1 1301 if the mapping does not have a device. 1302 .Pp 1303 .Sy pr_ino 1304 is the inode of the mapped object, if any, for the mapping. 1305 Its contents are only valid if 1306 .Sy pr_dev 1307 is not 1308 .Sy PRNODEV . 1309 .Pp 1310 .Sy pr_rss 1311 is the number of resident pages of memory for the mapping. 1312 The number of resident bytes for the mapping may be determined by multiplying 1313 .Sy pr_rss 1314 by the page size given by 1315 .Sy pr_pagesize . 1316 .Pp 1317 .Sy pr_anon 1318 is the number of resident anonymous memory pages (pages which are 1319 private to this process) for the mapping. 1320 .Pp 1321 .Sy pr_locked 1322 is the number of locked pages for the mapping. 1323 Pages which are locked are always resident in memory. 1324 .Pp 1325 .Sy pr_hatpagesize 1326 is the size, in bytes, of the 1327 .Sy HAT 1328 .Pq Sy MMU 1329 translation for the mapping. 1330 .Sy pr_hatpagesize 1331 may be different than 1332 .Sy pr_pagesize . 1333 The possible values are hardware architecture specific, and 1334 may change over a mapping's lifetime. 1335 .Ss rmap 1336 Contains information about the reserved address ranges of the process. 1337 The file contains an array of 1338 .Sy prmap 1339 structures, as defined above for the 1340 .Sy map 1341 file. 1342 Each structure describes a contiguous virtual address region in the 1343 address space of the traced process that is reserved by the system in the sense 1344 that an 1345 .Xr mmap 2 1346 system call that does not specify 1347 .Sy MAP_FIXED 1348 will not use any part of it for the new mapping. 1349 Examples of such reservations include the address ranges reserved for the 1350 process stack and the individual thread stacks of a multi-threaded process. 1351 .Ss cwd 1352 A symbolic link to the process's current working directory. 1353 See 1354 .Xr chdir 2 . 1355 A 1356 .Xr readlink 2 1357 of 1358 .Pa /proc/ Ns Em pid Ns Pa /cwd 1359 yields a null string. 1360 However, it can be opened, listed, and searched as a directory, and can be the 1361 target of 1362 .Xr chdir 2 . 1363 .Ss root 1364 A symbolic link to the process's root directory. 1365 .Pa /proc/ Ns Em pid Ns Pa /root 1366 can differ from the system root directory if the process or one of its 1367 ancestors executed 1368 .Xr chroot 2 1369 as super user. 1370 It has the same semantics as 1371 .Pa /proc/ Ns Em pid Ns Pa /cwd . 1372 .Ss fd 1373 A directory containing references to the open files of the process. 1374 Each entry is a decimal number corresponding to an open file descriptor in the 1375 process. 1376 .Pp 1377 If an entry refers to a regular file, it can be opened with normal file system 1378 semantics but, to ensure that the controlling process cannot gain greater 1379 access than the controlled process, with no file access modes other than its 1380 read/write open modes in the controlled process. 1381 If an entry refers to a directory, it can be accessed with the same semantics 1382 as 1383 .Pa /proc/ Ns Em pid Ns Pa /cwd . 1384 An attempt to open any other type of entry fails with 1385 .Er EACCES . 1386 .Ss fdinfo 1387 A directory containing information about each of the process's open files. 1388 Each entry is a decimal number corresponding to an open file descriptor in the 1389 process. 1390 Each file contains a 1391 .Sy prfdinfo_t 1392 structure defined as follows: 1393 .Bd -literal -offset 2 1394 typedef struct prfdinfo { 1395 int pr_fd; /* file descriptor number */ 1396 mode_t pr_mode; /* (see st_mode in stat(2)) */ 1397 uint64_t pr_ino; /* inode number */ 1398 uint64_t pr_size; /* file size */ 1399 int64_t pr_offset; /* current offset of file descriptor */ 1400 uid_t pr_uid; /* owner's user id */ 1401 gid_t pr_gid; /* owner's group id */ 1402 major_t pr_major; /* major number of device containing file */ 1403 minor_t pr_minor; /* minor number of device containing file */ 1404 major_t pr_rmajor; /* major number (if special file) */ 1405 minor_t pr_rminor; /* minor number (if special file) */ 1406 int pr_fileflags; /* (see F_GETXFL in fcntl(2)) */ 1407 int pr_fdflags; /* (see F_GETFD in fcntl(2)) */ 1408 short pr_locktype; /* (see F_GETLK in fcntl(2)) */ 1409 pid_t pr_lockpid; /* process holding file lock (see F_GETLK) */ 1410 int pr_locksysid; /* sysid of locking process (see F_GETLK) */ 1411 pid_t pr_peerpid; /* peer process (socket, door) */ 1412 int pr_filler[25]; /* reserved for future use */ 1413 char pr_peername[PRFNSZ]; /* peer process name */ 1414 #if __STDC_VERSION__ >= 199901L 1415 char pr_misc[]; /* self describing structures */ 1416 #else 1417 char pr_misc[1]; 1418 #endif 1419 } prfdinfo_t; 1420 .Ed 1421 .Pp 1422 The 1423 .Sy pr_misc 1424 element points to a list of additional miscellaneous data items, each of which 1425 has a header of type 1426 .Sy pr_misc_header_t 1427 specifying the size and type, and some data which immediately follow 1428 the header. 1429 .Bd -literal -offset 2 1430 typedef struct pr_misc_header { 1431 uint_t pr_misc_size; 1432 uint_t pr_misc_type; 1433 } pr_misc_header_t; 1434 .Ed 1435 .Pp 1436 The 1437 .Sy pr_misc_size 1438 field is the sum of the sizes of the header and the associated data and any 1439 trailing padding bytes which will be set to zero. 1440 The end of the list is indicated by a header with a zero size and a type with 1441 all bits set. 1442 .Pp 1443 The following miscellaneous data types can be present: 1444 .Bl -tag -width "PR_SOCKOPT_TCP_CONGESTION" -offset left 1445 .It Sy PR_PATHNAME 1446 The file descriptor's path in the filesystem. 1447 This is a NUL-terminated sequence of characters. 1448 .It Sy PR_SOCKETNAME 1449 A 1450 .Sy sockaddr 1451 structure representing the local socket name for this file descriptor, as 1452 would be returned by calling 1453 .Fn getsockname 1454 within the process. 1455 .It Sy PR_PEERSOCKNAME 1456 A 1457 .Sy sockaddr 1458 structure representing the peer socket name for this file descriptor, as 1459 would be returned by calling 1460 .Fn getpeername 1461 within the process. 1462 .It Sy PR_SOCKOPTS_BOOL_OPTS 1463 An unsigned integer which has bits set corresponding to options which are 1464 set on the underlying socket. 1465 The following bits may be set: 1466 .Bl -tag -width "PR_SO_PASSIVE_CONNECT" 1467 .It Sy PR_SO_DEBUG 1468 .It Sy PR_SO_REUSEADDR 1469 .It Sy PR_SO_REUSEPORT 1470 .It Sy PR_SO_KEEPALIVE 1471 .It Sy PR_SO_DONTROUTE 1472 .It Sy PR_SO_BROADCAST 1473 .It Sy PR_SO_OOBINLINE 1474 .It Sy PR_SO_DGRAM_ERRIND 1475 .It Sy PR_SO_ALLZONES 1476 .It Sy PR_SO_MAC_EXEMPT 1477 .It Sy PR_SO_EXCLBIND 1478 .It Sy PR_SO_PASSIVE_CONNECT 1479 .It Sy PR_SO_ACCEPTCONN 1480 .It Sy PR_UDP_NAT_T_ENDPOINT 1481 .It Sy PR_SO_VRRP 1482 .It Sy PR_SO_MAC_IMPLICIT 1483 .El 1484 .It Sy PR_SOCKOPT_LINGER 1485 A 1486 .Sy struct linger 1487 as would be returned by calling 1488 .Fn getsockopt SO_LINGER 1489 within the process. 1490 .It Sy PR_SOCKOPT_SNDBUF 1491 The data that would be returned by calling 1492 .Fn getsockopt SO_SNDBUF 1493 within the process. 1494 .It Sy PR_SOCKOPT_RCVBUF 1495 The data that would be returned by calling 1496 .Fn getsockopt SO_RCVBUF 1497 within the process. 1498 .It Sy PR_SOCKOPT_IP_NEXTHOP 1499 The data that would be returned by calling 1500 .Fn getsockopt IPPROTO_IP IP_NEXTHOP 1501 within the process. 1502 .It Sy PR_SOCKOPT_IPV6_NEXTHOP 1503 The data that would be returned by calling 1504 .Fn getsockopt IPPROTO_IPV6 IPV6_NEXTHOP 1505 within the process. 1506 .It Sy PR_SOCKOPT_TYPE 1507 The data that would be returned by calling 1508 .Fn getsockopt SO_TYPE 1509 within the process. 1510 .It Sy PR_SOCKOPT_TCP_CONGESTION 1511 For TCP sockets, the data that would be returned by calling 1512 .Fn getsockopt IPPROTO_TCP TCP_CONGESTION 1513 within the process. 1514 This is a NUL-terminated character array containing the name of the congestion 1515 algorithm in use for the socket. 1516 .It Sy PR_SOCKFILTERS_PRIV 1517 Private data relating to up to the first 32 socket filters pushed on this 1518 descriptor. 1519 .El 1520 .Ss object 1521 A directory containing read-only files with names corresponding to the 1522 .Sy pr_mapname 1523 entries in the 1524 .Sy map 1525 and 1526 .Sy pagedata 1527 files. 1528 Opening such a file yields a file descriptor for the underlying mapped file 1529 associated with an address-space mapping in the process. 1530 The file name 1531 .Pa a.out 1532 appears in the directory as an alias for the process's executable file. 1533 .Pp 1534 The 1535 .Pa object 1536 directory makes it possible for a controlling process to gain 1537 access to the object file and any shared libraries (and consequently the symbol 1538 tables) without having to know the actual path names of the executable files. 1539 .Ss path 1540 A directory containing symbolic links to files opened by the process. 1541 The directory includes one entry for 1542 .Pa cwd 1543 and 1544 .Pa root . 1545 The directory also contains a numerical entry for each file descriptor in the 1546 .Pa fd 1547 directory, and entries matching those in the 1548 .Pa object 1549 directory. 1550 If this information is not available, any attempt to read the contents of the 1551 symbolic link will fail. 1552 This is most common for files that do not exist in the filesystem namespace 1553 (such as 1554 .Sy FIFO Ns s 1555 and sockets), but can also happen for regular files. 1556 For the file descriptor entries, the path may be different from the one 1557 used by the process to open the file. 1558 .Ss pagedata 1559 Opening the page data file enables tracking of address space references and 1560 modifications on a per-page basis. 1561 .Pp 1562 A 1563 .Xr read 2 1564 of the page data file descriptor returns structured page data 1565 and atomically clears the page data maintained for the file by the system. 1566 That is to say, each read returns data collected since the last read; the 1567 first read returns data collected since the file was opened. 1568 When the call completes, the read buffer contains the following structure as 1569 its header and thereafter contains a number of section header structures and 1570 associated byte arrays that must be accessed by walking linearly through the 1571 buffer. 1572 .Bd -literal -offset 2 1573 typedef struct prpageheader { 1574 timestruc_t pr_tstamp; /* real time stamp, time of read() */ 1575 ulong_t pr_nmap; /* number of address space mappings */ 1576 ulong_t pr_npage; /* total number of pages */ 1577 } prpageheader_t; 1578 .Ed 1579 .Pp 1580 The header is followed by 1581 .Sy "pr_nmap prasmap" 1582 structures and associated data arrays. 1583 The 1584 .Sy prasmap 1585 structure contains the following elements: 1586 .Bd -literal -offset 2 1587 typedef struct prasmap { 1588 uintptr_t pr_vaddr; /* virtual address of mapping */ 1589 ulong_t pr_npage; /* number of pages in mapping */ 1590 char pr_mapname[PRMAPSZ]; /* name in /proc/pid/object */ 1591 offset_t pr_offset; /* offset into mapped object, if any */ 1592 int pr_mflags; /* protection and attribute flags */ 1593 int pr_pagesize; /* pagesize for this mapping in bytes */ 1594 int pr_shmid; /* SysV shared memory identifier */ 1595 } prasmap_t; 1596 .Ed 1597 .Pp 1598 Each section header is followed by 1599 .Sy pr_npage 1600 bytes, one byte for each page in the mapping, plus 0-7 null bytes at the end 1601 so that the next 1602 .Sy prasmap 1603 structure begins on an eight-byte aligned boundary. 1604 Each data byte may contain these flags: 1605 .Bl -tag -width "PG_REFERENCED" -offset 2 1606 .It Sy PG_REFERENCED 1607 page has been referenced. 1608 .It Sy PG_MODIFIED 1609 page has been modified. 1610 .El 1611 .Pp 1612 If the read buffer is not large enough to contain all of the page data, the 1613 read fails with 1614 .Er E2BIG 1615 and the page data is not cleared. 1616 The required size of the read buffer can be determined through 1617 .Xr fstat 2 . 1618 Application of 1619 .Xr lseek 2 1620 to the page data file descriptor is ineffective; every read 1621 starts from the beginning of the file. 1622 Closing the page data file descriptor 1623 terminates the system overhead associated with collecting the data. 1624 .Pp 1625 More than one page data file descriptor for the same process can be opened, up 1626 to a system-imposed limit per traced process. 1627 A read of one does not affect the data being collected by the system for the 1628 others. 1629 An open of the page data file will fail with 1630 .Er ENOMEM 1631 if the system-imposed limit would be exceeded. 1632 .Ss watch 1633 Contains an array of 1634 .Vt prwatch 1635 structures, one for each watched area established by the 1636 .Sy PCWATCH 1637 control operation. 1638 See 1639 .Sx PCWATCH 1640 for details. 1641 .Ss usage 1642 Contains process usage information described by a 1643 .Vt prusage 1644 structure which contains at least the following fields: 1645 .Bd -literal -offset 2 1646 typedef struct prusage { 1647 id_t pr_lwpid; /* lwp id. 0: process or defunct */ 1648 int pr_count; /* number of contributing lwps */ 1649 timestruc_t pr_tstamp; /* real time stamp, time of read() */ 1650 timestruc_t pr_create; /* process/lwp creation time stamp */ 1651 timestruc_t pr_term; /* process/lwp termination time stamp */ 1652 timestruc_t pr_rtime; /* total lwp real (elapsed) time */ 1653 timestruc_t pr_utime; /* user level CPU time */ 1654 timestruc_t pr_stime; /* system call CPU time */ 1655 timestruc_t pr_ttime; /* other system trap CPU time */ 1656 timestruc_t pr_tftime; /* text page fault sleep time */ 1657 timestruc_t pr_dftime; /* data page fault sleep time */ 1658 timestruc_t pr_kftime; /* kernel page fault sleep time */ 1659 timestruc_t pr_ltime; /* user lock wait sleep time */ 1660 timestruc_t pr_slptime; /* all other sleep time */ 1661 timestruc_t pr_wtime; /* wait-cpu (latency) time */ 1662 timestruc_t pr_stoptime; /* stopped time */ 1663 ulong_t pr_minf; /* minor page faults */ 1664 ulong_t pr_majf; /* major page faults */ 1665 ulong_t pr_nswap; /* swaps */ 1666 ulong_t pr_inblk; /* input blocks */ 1667 ulong_t pr_oublk; /* output blocks */ 1668 ulong_t pr_msnd; /* messages sent */ 1669 ulong_t pr_mrcv; /* messages received */ 1670 ulong_t pr_sigs; /* signals received */ 1671 ulong_t pr_vctx; /* voluntary context switches */ 1672 ulong_t pr_ictx; /* involuntary context switches */ 1673 ulong_t pr_sysc; /* system calls */ 1674 ulong_t pr_ioch; /* chars read and written */ 1675 } prusage_t; 1676 .Ed 1677 .Pp 1678 Microstate accounting is now continuously enabled. 1679 While this information was 1680 previously an estimate, if microstate accounting were not enabled, the current 1681 information is now never an estimate represents time the process has spent in 1682 various states. 1683 .Ss lstatus 1684 Contains a 1685 .Vt prheader 1686 structure followed by an array of 1687 .Vt lwpstatus 1688 structures, one for each active lwp in the process (see also 1689 .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpstatus , 1690 below). 1691 The 1692 .Vt prheader 1693 structure describes the number and size of the array entries that follow. 1694 .Bd -literal -offset 2 1695 typedef struct prheader { 1696 long pr_nent; /* number of entries */ 1697 size_t pr_entsize; /* size of each entry, in bytes */ 1698 } prheader_t; 1699 .Ed 1700 .Pp 1701 The 1702 .Vt lwpstatus 1703 structure may grow by the addition of elements at the end in future releases 1704 of the system. 1705 Programs must use 1706 .Sy pr_entsize 1707 in the file header to index through the array. 1708 These comments apply to all 1709 .Pa /proc 1710 files that include a 1711 .Vt prheader 1712 structure 1713 .Pf ( Pa lpsinfo 1714 and 1715 .Pa lusage , 1716 below). 1717 .Ss lpsinfo 1718 Contains a 1719 .Vt prheader 1720 structure followed by an array of 1721 .Vt lwpsinfo 1722 structures, one for eachactive and zombie lwp in the process. 1723 See also 1724 .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpsinfo , 1725 below. 1726 .Ss lusage 1727 Contains a 1728 .Vt prheader 1729 structure followed by an array of 1730 .Vt prusage 1731 structures, one for each active lwp in the process, plus an additional element 1732 at the beginning that contains the summation over all defunct lwps (lwps that 1733 once existed but no longer exist in the process). 1734 Excluding the 1735 .Sy pr_lwpid , 1736 .Sy pr_tstamp , 1737 .Sy pr_create , 1738 and 1739 .Sy pr_term 1740 entries, the entry-by-entry summation over all these structures is the 1741 definition of the process usage information obtained from the 1742 .Pa usage 1743 file. (See also 1744 .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpusage , 1745 below.) 1746 .Ss lwp 1747 A directory containing entries each of which names an active or zombie lwp 1748 within the process. 1749 These entries are themselves directories containing additional files as 1750 described below. 1751 Only the 1752 .Pa lwpsinfo 1753 file exists in the directory of a zombie lwp. 1754 .Sh "STRUCTURE OF" Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid 1755 A given directory 1756 .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid 1757 contains the following entries: 1758 .Ss lwpctl 1759 Write-only control file. 1760 The messages written to this file affect the specific 1761 lwp rather than the representative lwp, as is the case for the process's 1762 .Pa ctl 1763 file. 1764 .Ss lwpname 1765 A buffer of 1766 .Dv THREAD_NAME_MAX 1767 bytes representing the LWP name; the buffer is 1768 zero-filled if the thread name is shorter than the buffer. 1769 If no thread name is set, the buffer contains the empty string. 1770 A read with a buffer shorter than 1771 .Dv THREAD_NAME_MAX 1772 bytes is not guaranteed to be NUL-terminated. 1773 Writing to this file will set the LWP name for the specific lwp. 1774 This file may not be present in older operating system versions. 1775 .Dv THREAD_NAME_MAX 1776 may increase in the future; clients should be prepared for this. 1777 .Ss lwpstatus 1778 lwp-specific state information. 1779 This file contains the 1780 .Vt lwpstatus 1781 structure for the specific lwp as described above for the representative lwp in 1782 the process's 1783 .Pa status 1784 file. 1785 .Ss lwpsinfo 1786 lwp-specific 1787 .Xr ps 1 1788 information. 1789 This file contains the 1790 .Vt lwpsinfo 1791 structure for the specific lwp as described above for the representative lwp in 1792 the process's 1793 .Pa psinfo 1794 file. 1795 The 1796 .Pa lwpsinfo 1797 file remains accessible after an lwp becomes a zombie. 1798 .Ss lwpusage 1799 This file contains the 1800 .Vt prusage 1801 structure for the specific lwp as described above for the process's 1802 .Pa usage 1803 file. 1804 .Ss gwindows 1805 This file exists only on SPARC based machines. 1806 If it is non-empty, it contains a 1807 .Vt gwindows_t 1808 structure, defined in 1809 .In sys/regset.h , 1810 with the values of those SPARC register windows that could not be stored on 1811 the stack when the lwp stopped. 1812 Conditions under which register windows are not stored on the 1813 stack are: the stack pointer refers to nonexistent process memory or the stack 1814 pointer is improperly aligned. 1815 If the lwp is not stopped or if there are no 1816 register windows that could not be stored on the stack, the file is empty (the 1817 usual case). 1818 .Ss xregs 1819 Extra state registers. 1820 The extra state register set is architecture dependent; 1821 this file is empty if the system does not support extra state registers. 1822 If the file is non-empty, it contains an architecture dependent structure of 1823 type 1824 .Vt prxregset_t , 1825 defined in 1826 .In procfs.h , 1827 with the values of the lwp's extra state registers. 1828 If the lwp is not stopped, all register values are undefined. 1829 See also the 1830 .Sx PCSXREG 1831 control operation, below. 1832 .Ss asrs 1833 This file exists only for 64-bit SPARC V9 processes. 1834 It contains an 1835 .Vt asrset_t 1836 structure, defined in 1837 .In sys/regset.h , 1838 containing the values of the lwp's platform-dependent ancillary state registers. 1839 If the lwp is not stopped, all register values are undefined. 1840 See also the 1841 .Sx PCSASRS 1842 control operation, below. 1843 .Ss spymaster 1844 For an agent lwp (see 1845 .Sx PCAGENT ) , 1846 this file contains a 1847 .Vt psinfo_t 1848 structure that corresponds to the process that created the agent lwp at the 1849 time the agent was created. 1850 This structure is identical to that retrieved via the 1851 .Pa psinfo 1852 file, with one modification: the 1853 .Sy pr_time 1854 field does not correspond to the CPU time for the process, but rather to the 1855 creation time of the agent lwp. 1856 .Ss templates 1857 A directory which contains references to the active templates for the lwp, 1858 named by the contract type. 1859 Changes made to an active template descriptor do 1860 not affect the original template which was activated, though they do affect the 1861 active template. 1862 It is not possible to activate an active template descriptor. 1863 See 1864 .Xr contract 4 . 1865 .Sh CONTROL MESSAGES 1866 Process state changes are effected through messages written to a process's 1867 .Sy ctl 1868 file or to an individual lwp's 1869 .Sy lwpctl 1870 file. 1871 All control messages consist of a 1872 .Sy long 1873 that names the specific operation followed by 1874 additional data containing the operand, if any. 1875 .Pp 1876 Multiple control messages may be combined in a single 1877 .Xr write 2 1878 (or 1879 .Xr writev 2 ) 1880 to a control file, but no partial writes are permitted. 1881 That is, each control message, operation code plus operand, if any, must be 1882 presented in its entirety to the 1883 .Xr write 2 1884 and not in pieces over several system calls. 1885 If a control operation fails, no subsequent operations contained in the same 1886 .Xr write 2 1887 are attempted. 1888 .Pp 1889 Descriptions of the allowable control messages follow. 1890 In all cases, writing a message to a control file for a process or lwp that 1891 has terminated elicits the error 1892 .Er ENOENT . 1893 .Ss PCSTOP PCDSTOP PCWSTOP PCTWSTOP 1894 When applied to the process control file, 1895 .Sy PCSTOP 1896 directs all lwps to stop and waits for them to stop, 1897 .Sy PCDSTOP 1898 directs all lwps to stop without waiting for them to stop, and 1899 .Sy PCWSTOP 1900 simply waits for all lwps to stop. 1901 When applied to an lwp control file, 1902 .Sy PCSTOP 1903 directs the specific lwp to stop and waits until it has stopped, 1904 .Sy PCDSTOP 1905 directs the specific lwp to stop without waiting for it to stop, and 1906 .Sy PCWSTOP 1907 simply waits for the specific lwp to stop. 1908 When applied to an lwp control file, 1909 .Sy PCSTOP 1910 and 1911 .Sy PCWSTOP 1912 complete when the lwp stops on an event of interest, immediately 1913 if already so stopped; when applied to the process control file, they complete 1914 when every lwp has stopped either on an event of interest or on a 1915 .Sy PR_SUSPENDED 1916 stop. 1917 .Pp 1918 .Sy PCTWSTOP 1919 is identical to 1920 .Sy PCWSTOP 1921 except that it enables the operation to time out, to avoid waiting forever for 1922 a process or lwp that may never stop on an event of interest. 1923 .Sy PCTWSTOP 1924 takes a 1925 .Sy long 1926 operand specifying a number of milliseconds; the wait will terminate 1927 successfully after the specified number of milliseconds even if the process or 1928 lwp has not stopped; a timeout value of zero makes the operation identical to 1929 .Sy PCWSTOP . 1930 .Pp 1931 An 1932 .Dq event of interest 1933 is either a 1934 .Sy PR_REQUESTED 1935 stop or a stop that has been specified in the process's tracing flags (set by 1936 .Sy PCSTRACE , 1937 .Sy PCSFAULT , 1938 .Sy PCSENTRY , 1939 and 1940 .Sy PCSEXIT ) . 1941 .Sy PR_JOBCONTROL 1942 and 1943 .Sy PR_SUSPENDED 1944 stops are specifically not events of interest. 1945 (An lwp may stop twice due to a stop signal, first showing 1946 .Sy PR_SIGNALLED 1947 if the signal is traced and again showing 1948 .Sy PR_JOBCONTROL 1949 if the lwp is set running without clearing the signal.) 1950 If 1951 .Sy PCSTOP 1952 or 1953 .Sy PCDSTOP 1954 is applied to an 1955 lwp that is stopped, but not on an event of interest, the stop directive takes 1956 effect when the lwp is restarted by the competing mechanism. 1957 At that time, the lwp enters a 1958 .Sy PR_REQUESTED 1959 stop before executing any user-level code. 1960 .Pp 1961 A write of a control message that blocks is interruptible by a signal so that, 1962 for example, an 1963 .Xr alarm 2 1964 can be set to avoid waiting forever for a 1965 process or lwp that may never stop on an event of interest. 1966 If 1967 .Sy PCSTOP 1968 is interrupted, the lwp stop directives remain in effect even though the 1969 .Xr write 2 1970 returns an error. 1971 (Use of 1972 .Sy PCTWSTOP 1973 with a non-zero timeout is recommended over 1974 .Sy PCWSTOP 1975 with an 1976 .Xr alarm 2 . ) 1977 .Pp 1978 A system process (indicated by the 1979 .Sy PR_ISSYS 1980 flag) never executes at user level, has no user-level address space visible 1981 through 1982 .Pa /proc , 1983 and cannot be stopped. 1984 Applying one of these operations to a system process or any of its 1985 lwps elicits the error 1986 .Er EBUSY . 1987 .Ss PCRUN 1988 Make an lwp runnable again after a stop. 1989 This operation takes a 1990 .Vt long 1991 operand containing zero or more of the following flags: 1992 .Bl -tag -width "PRSABORT" -offset left 1993 .It Sy PRCSIG 1994 clears the current signal, if any (see 1995 .Sx PCCSIG ) . 1996 .It Sy PRCFAULT 1997 clears the current fault, if any (see 1998 .Sx PCCFAULT ) . 1999 .It Sy PRSTEP 2000 directs the lwp to execute a single machine instruction. 2001 On completion of the instruction, a trace trap occurs. 2002 If 2003 .Sy FLTTRACE 2004 is being traced, the lwp stops; otherwise, it is sent 2005 .Sy SIGTRAP . 2006 If 2007 .Sy SIGTRAP 2008 is being traced and is not blocked, the lwp stops. 2009 When the lwp stops on an event of interest, 2010 the single-step directive is cancelled, even if the stop occurs before the 2011 instruction is executed. 2012 This operation requires hardware and operating system 2013 support and may not be implemented on all processors. 2014 It is implemented on SPARC and x86-based machines. 2015 .It Sy PRSABORT 2016 is meaningful only if the lwp is in a 2017 .Sy PR_SYSENTRY 2018 stop or is marked 2019 .Sy PR_ASLEEP ; 2020 it instructs the lwp to abort execution of the system call (see 2021 .Sx PCSENTRY 2022 and 2023 .Sx PCSEXIT ) . 2024 .It Sy PRSTOP 2025 directs the lwp to stop again as soon as possible after resuming execution (see 2026 .Sx PCDSTOP ) . 2027 In particular, if the lwp is stopped on 2028 .Sy PR_SIGNALLED 2029 or 2030 .Sy PR_FAULTED , 2031 the next stop will show 2032 .Sy PR_REQUESTED , 2033 no other stop 2034 will have intervened, and the lwp will not have executed any user-level code. 2035 .El 2036 .Pp 2037 When applied to an lwp control file, 2038 .Sy PCRUN 2039 clears any outstanding 2040 directed-stop request and makes the specific lwp runnable. 2041 The operation fails with 2042 .Er EBUSY 2043 if the specific lwp is not stopped on an event of interest or 2044 has not been directed to stop or if the agent lwp exists and this is not the 2045 agent lwp (see 2046 .Sx PCAGENT ) . 2047 .Pp 2048 When applied to the process control file, a representative lwp is chosen for 2049 the operation as described for 2050 .Pa /proc/ Ns Em pid Ns Pa /status . 2051 The operation fails with 2052 .Er EBUSY 2053 if the representative lwp is not stopped on an 2054 event of interest or has not been directed to stop or if the agent lwp exists. 2055 If 2056 .Sy PRSTEP 2057 or 2058 .Sy PRSTOP 2059 was requested, the representative lwp is made 2060 runnable and its outstanding directed-stop request is cleared; otherwise all 2061 outstanding directed-stop requests are cleared and, if it was stopped on an 2062 event of interest, the representative lwp is marked 2063 .Sy PR_REQUESTED . 2064 If, as a consequence, all lwps are in the 2065 .Sy PR_REQUESTED 2066 or 2067 .Sy PR_SUSPENDED 2068 stop state, all lwps showing 2069 .Sy PR_REQUESTED 2070 are made runnable. 2071 .Ss PCSTRACE 2072 Define a set of signals to be traced in the process. 2073 The receipt of one of these signals by an lwp causes the lwp to stop. 2074 The set of signals is defined using an operand 2075 .Sy sigset_t 2076 contained in the control message. 2077 Receipt of 2078 .Sy SIGKILL 2079 cannot be traced; if specified, it is silently ignored. 2080 .Pp 2081 If a signal that is included in an lwp's held signal set (the signal mask) is 2082 sent to the lwp, the signal is not received and does not cause a stop until it 2083 is removed from the held signal set, either by the lwp itself or by setting the 2084 held signal set with 2085 .Sy PCSHOLD . 2086 .Ss PCCSIG 2087 The current signal, if any, is cleared from the specific or representative lwp. 2088 .Ss PCSSIG 2089 The current signal and its associated signal information for the specific or 2090 representative lwp are set according to the contents of the operand 2091 .Vt siginfo 2092 structure (see 2093 .In sys/siginfo.h ) . 2094 If the specified signal number is zero, the current signal is cleared. 2095 The semantics of this operation are different from those of 2096 .Xr kill 2 2097 in that the signal is delivered to the lwp immediately after execution is 2098 resumed (even if it is being blocked) and an additional 2099 .Sy PR_SIGNALLED 2100 stop does not intervene even if the signal is traced. 2101 Setting the current signal to 2102 .Sy SIGKILL 2103 terminates the process immediately. 2104 .Ss PCKILL 2105 If applied to the process control file, a signal is sent to the process with 2106 semantics identical to those of 2107 .Xr kill 2 2108 If applied to an lwp control file, a directed signal is sent to the specific 2109 lwp. 2110 The signal is named in a 2111 .Vt long 2112 operand contained in the message. 2113 Sending 2114 .Sy SIGKILL 2115 terminates the process immediately. 2116 .Ss PCUNKILL 2117 A signal is deleted, that is, it is removed from the set of pending signals. 2118 If applied to the process control file, the signal is deleted from the process's 2119 pending signals. 2120 If applied to an lwp control file, the signal is deleted from 2121 the lwp's pending signals. 2122 The current signal (if any) is unaffected. 2123 The signal is named in a 2124 .Sy long 2125 operand in the control message. 2126 It is an error 2127 .Pq Er EINVAL 2128 to attempt to delete 2129 .Sy SIGKILL . 2130 .Ss PCSHOLD 2131 Set the set of held signals for the specific or representative lwp (signals 2132 whose delivery will be blocked if sent to the lwp). 2133 The set of signals is specified with a 2134 .Vt sigset_t 2135 operand. 2136 .Sy SIGKILL 2137 and 2138 .Sy SIGSTOP 2139 cannot be held; if specified, they are silently ignored. 2140 .Ss PCSFAULT 2141 Define a set of hardware faults to be traced in the process. 2142 On incurring one of these faults, an lwp stops. 2143 The set is defined via the operand 2144 .Vt fltset_t 2145 structure. 2146 Fault names are defined in 2147 .In sys/fault.h 2148 and include the following. 2149 Some of these may not occur on all processors; there may 2150 be processor-specific faults in addition to these. 2151 .Bl -tag -width "FLTACCESS" -offset indent 2152 .It Sy FLTILL 2153 illegal instruction 2154 .It Sy FLTPRIV 2155 privileged instruction 2156 .It Sy FLTBPT 2157 breakpoint trap 2158 .It Sy FLTTRACE 2159 trace trap (single-step) 2160 .It Sy FLTWATCH 2161 watchpoint trap 2162 .It Sy FLTACCESS 2163 memory access fault (bus error) 2164 .It Sy FLTBOUNDS 2165 memory bounds violation 2166 .It Sy FLTIOVF 2167 integer overflow 2168 .It Sy FLTIZDIV 2169 integer zero divide 2170 .It Sy FLTFPE 2171 floating-point exception 2172 .It Sy FLTSTACK 2173 unrecoverable stack fault 2174 .It Sy FLTPAGE 2175 recoverable page fault 2176 .El 2177 .Pp 2178 When not traced, a fault normally results in the posting of a signal to the lwp 2179 that incurred the fault. 2180 If an lwp stops on a fault, the signal is posted to 2181 the lwp when execution is resumed unless the fault is cleared by 2182 .Sy PCCFAULT 2183 or by the 2184 .Sy PRCFAULT 2185 option of 2186 .Sy PCRUN . 2187 .Sy FLTPAGE 2188 is an exception; no signal is posted. 2189 The 2190 .Sy pr_info 2191 field in the 2192 .Vt lwpstatus 2193 structure identifies the signal to be sent and contains machine-specific 2194 information about the fault. 2195 .Ss PCCFAULT 2196 The current fault, if any, is cleared; the associated signal will not be sent 2197 to the specific or representative lwp. 2198 .Ss PCSENTRY PCSEXIT 2199 These control operations instruct the process's lwps to stop on entry to or 2200 exit from specified system calls. 2201 The set of system calls to be traced is defined via an operand 2202 .Vt sysset_t 2203 structure. 2204 .Pp 2205 When entry to a system call is being traced, an lwp stops after having begun 2206 the call to the system but before the system call arguments have been fetched 2207 from the lwp. 2208 When exit from a system call is being traced, an lwp stops on completion of 2209 the system call just prior to checking for signals and returning to user level. 2210 At this point, all return values have been stored into the lwp's registers. 2211 .Pp 2212 If an lwp is stopped on entry to a system call 2213 .Pq Sy PR_SYSENTRY 2214 or when sleeping in an interruptible system call 2215 .Pf ( Sy PR_ASLEEP 2216 is set), it may be instructed to go directly to system call exit by specifying 2217 the 2218 .Sy PRSABORT 2219 flag in a 2220 .Sy PCRUN 2221 control message. 2222 Unless exit from the system call is being traced, the lwp returns to user 2223 level showing 2224 .Er EINTR . 2225 .Ss PCWATCH 2226 Set or clear a watched area in the controlled process from a 2227 .Vt prwatch 2228 structure operand: 2229 .Bd -literal -offset 2 2230 typedef struct prwatch { 2231 uintptr_t pr_vaddr; /* virtual address of watched area */ 2232 size_t pr_size; /* size of watched area in bytes */ 2233 int pr_wflags; /* watch type flags */ 2234 } prwatch_t; 2235 .Ed 2236 .Pp 2237 .Sy pr_vaddr 2238 specifies the virtual address of an area of memory to be watched 2239 in the controlled process. 2240 .Sy pr_size 2241 specifies the size of the area, in bytes. 2242 .Sy pr_wflags 2243 specifies the type of memory access to be monitored as a 2244 bit-mask of the following flags: 2245 .Bl -tag -width "WA_TRAPAFTER" -offset indent 2246 .It Sy WA_READ 2247 read access 2248 .It Sy WA_WRITE 2249 write access 2250 .It Sy WA_EXEC 2251 execution access 2252 .It Sy WA_TRAPAFTER 2253 trap after the instruction completes 2254 .El 2255 .Pp 2256 If 2257 .Sy pr_wflags 2258 is non-empty, a watched area is established for the virtual 2259 address range specified by 2260 .Sy pr_vaddr 2261 and 2262 .Sy pr_size . 2263 If 2264 .Sy pr_wflags 2265 is empty, any previously-established watched area starting at the specified 2266 virtual address is cleared; 2267 .Sy pr_size 2268 is ignored. 2269 .Pp 2270 A watchpoint is triggered when an lwp in the traced process makes a memory 2271 reference that covers at least one byte of a watched area and the memory 2272 reference is as specified in 2273 .Sy pr_wflags . 2274 When an lwp triggers a watchpoint, it incurs a watchpoint trap. 2275 If 2276 .Sy FLTWATCH 2277 is being traced, the lwp stops; otherwise, it is sent a 2278 .Sy SIGTRAP 2279 signal; if 2280 .Sy SIGTRAP 2281 is being traced and is not blocked, the lwp stops. 2282 .Pp 2283 The watchpoint trap occurs before the instruction completes unless 2284 .Sy WA_TRAPAFTER 2285 was specified, in which case it occurs after the instruction completes. 2286 If it occurs before completion, the memory is not modified. 2287 If it occurs after completion, the memory is modified (if the access is a write 2288 access). 2289 .Pp 2290 Physical i/o is an exception for watchpoint traps. 2291 In this instance, there is no guarantee that memory before the watched area 2292 has already been modified (or in the case of 2293 .Sy WA_TRAPAFTER , 2294 that the memory following the watched area 2295 has not been modified) when the watchpoint trap occurs and the lwp stops. 2296 .Pp 2297 .Sy pr_info 2298 in the 2299 .Vt lwpstatus 2300 structure contains information pertinent to the watchpoint trap. 2301 In particular, the 2302 .Sy si_addr 2303 field contains the 2304 virtual address of the memory reference that triggered the watchpoint, and the 2305 .Sy si_code 2306 field contains one of 2307 .Sy TRAP_RWATCH , 2308 .Sy TRAP_WWATCH , 2309 or 2310 .Sy TRAP_XWATCH , 2311 indicating read, write, or execute access, respectively. 2312 The 2313 .Sy si_trapafter 2314 field is zero unless 2315 .Sy WA_TRAPAFTER 2316 is in effect for this watched area; non-zero indicates that the current 2317 instruction is not the instruction that incurred the watchpoint trap. 2318 The 2319 .Sy si_pc 2320 field contains the virtual address of the instruction that incurred the trap. 2321 .Pp 2322 A watchpoint trap may be triggered while executing a system call that makes 2323 reference to the traced process's memory. 2324 The lwp that is executing the system call incurs the watchpoint trap while 2325 still in the system call. 2326 If it stops as a result, the 2327 .Vt lwpstatus 2328 structure contains the system call number and its arguments. 2329 If the lwp does not stop, or if it is set running again without 2330 clearing the signal or fault, the system call fails with 2331 .Er EFAULT . 2332 If 2333 .Sy WA_TRAPAFTER 2334 was specified, the memory reference will have completed and 2335 the memory will have been modified (if the access was a write access) when the 2336 watchpoint trap occurs. 2337 .Pp 2338 If more than one of 2339 .Sy WA_READ , 2340 .Sy WA_WRITE , 2341 and 2342 .Sy WA_EXEC 2343 is specified for a watched area, and a single instruction incurs more than one 2344 of the specified types, only one is reported when the watchpoint trap occurs. 2345 The precedence is 2346 .Sy WA_EXEC , 2347 .Sy WA_READ , 2348 .Sy WA_WRITE 2349 .Pf ( Sy WA_EXEC 2350 and 2351 .Sy WA_READ 2352 take precedence over 2353 .Sy WA_WRITE ) , 2354 unless 2355 .Sy WA_TRAPAFTER 2356 was specified, in which case it is 2357 .Sy WA_WRITE , 2358 .Sy WA_READ , 2359 .Sy WA_EXEC 2360 .Pf ( Sy WA_WRITE 2361 takes precedence). 2362 .Pp 2363 .Sy PCWATCH 2364 fails with 2365 .Er EINVAL 2366 if an attempt is made to specify overlapping watched areas or if 2367 .Sy pr_wflags 2368 contains flags other than those specified above. 2369 It fails with 2370 .Er ENOMEM 2371 if an attempt is made to establish more watched areas than the system can 2372 support (the system can support thousands). 2373 .Pp 2374 The child of a 2375 .Xr vfork 2 2376 borrows the parent's address space. 2377 When a 2378 .Xr vfork 2 2379 is executed by a traced process, all watched areas established 2380 for the parent are suspended until the child terminates or performs an 2381 .Xr exec 2 . 2382 Any watched areas established independently in the child are 2383 cancelled when the parent resumes after the child's termination or 2384 .Xr exec 2 . 2385 .Sy PCWATCH 2386 fails with 2387 .Er EBUSY 2388 if applied to the parent of a 2389 .Xr vfork 2 2390 before the child has terminated or performed an 2391 .Xr exec 2 . 2392 The 2393 .Sy PR_VFORKP 2394 flag is set in the 2395 .Sy pstatus 2396 structure for such a parent process. 2397 .Pp 2398 Certain accesses of the traced process's address space by the operating system 2399 are immune to watchpoints. 2400 The initial construction of a signal stack frame when a signal is delivered to 2401 an lwp will not trigger a watchpoint trap even if the new frame covers watched 2402 areas of the stack. 2403 Once the signal handler is entered, watchpoint traps occur normally. 2404 On SPARC based machines, register window overflow and underflow will not 2405 trigger watchpoint traps, even if the register window save areas cover watched 2406 areas of the stack. 2407 .Pp 2408 Watched areas are not inherited by child processes, even if the traced 2409 process's inherit-on-fork mode, 2410 .Sy PR_FORK , 2411 is set (see 2412 .Sy PCSET , 2413 below). 2414 All watched areas are cancelled when the traced process performs a successful 2415 .Xr exec 2 . 2416 .Ss PCSET PCUNSET 2417 .Sy PCSET 2418 sets one or more modes of operation for the traced process. 2419 .Sy PCUNSET 2420 unsets these modes. 2421 The modes to be set or unset are specified by flags in an operand 2422 .Sy long 2423 in the control message: 2424 .Bl -tag -offset left -width "PR_MSFORK" 2425 .It Sy PR_FORK 2426 (inherit-on-fork): When set, the process's tracing flags and its 2427 inherit-on-fork mode are inherited by the child of a 2428 .Xr fork 2 , 2429 .Xr fork1 2 , 2430 or 2431 .Xr vfork 2 . 2432 When unset, child processes start with all tracing flags cleared. 2433 .It Sy PR_RLC 2434 (run-on-last-close): When set and the last writable 2435 .Pa /proc 2436 file descriptor referring to the traced process or any of its lwps is closed, 2437 all of the process's tracing flags and watched areas are cleared, any 2438 outstanding stop directives are canceled, and if any lwps are stopped on 2439 events of interest, they are set running as though 2440 .Sy PCRUN 2441 had been applied to them. 2442 When unset, the process's tracing flags and watched areas are retained and 2443 lwps are not set running on last close. 2444 .It Sy PR_KLC 2445 (kill-on-last-close): When set and the last writable 2446 .Pa /proc 2447 file descriptor referring to the traced process or any of its lwps is closed, 2448 the process is terminated with 2449 .Sy SIGKILL . 2450 .It Sy PR_ASYNC 2451 (asynchronous-stop): When set, a stop on an event of interest by one lwp does 2452 not directly affect any other lwp in the process. 2453 When unset and an lwp stops on an event of interest other than 2454 .Sy PR_REQUESTED , 2455 all other lwps in the process are directed to stop. 2456 .It Sy PR_MSACCT 2457 (microstate accounting): Microstate accounting is now continuously enabled. 2458 This flag is deprecated and no longer has any effect upon microstate 2459 accounting. 2460 Applications may toggle this flag; however, microstate accounting 2461 will remain enabled regardless. 2462 .It Sy PR_MSFORK 2463 (inherit microstate accounting): All processes now inherit microstate 2464 accounting, as it is continuously enabled. 2465 This flag has been deprecated and its use no longer has any effect upon the 2466 behavior of microstate accounting. 2467 .It Sy PR_BPTADJ 2468 (breakpoint trap pc adjustment): On x86-based machines, a breakpoint trap 2469 leaves the program counter (the 2470 .Sy EIP ) 2471 referring to the breakpointed instruction plus one byte. 2472 When 2473 .Sy PR_BPTADJ 2474 is set, the system will adjust the program counter back to the location of the 2475 breakpointed instruction when the lwp stops on a breakpoint. 2476 This flag has no effect on SPARC based machines, where breakpoint traps leave 2477 the program counter referring to the breakpointed instruction. 2478 .It Sy PR_PTRACE 2479 (ptrace-compatibility): When set, a stop on an event of interest by the traced 2480 process is reported to the parent of the traced process by 2481 .Xr wait 3C , 2482 .Sy SIGTRAP 2483 is sent to the traced process when it executes a successful 2484 .Xr exec 2 , 2485 setuid/setgid flags are not honored for execs performed by the 2486 traced process, any exec of an object file that the traced process cannot read 2487 fails, and the process dies when its parent dies. 2488 This mode is deprecated; it is provided only to allow 2489 .Xr ptrace 3C 2490 to be implemented as a library function using 2491 .Pa /proc . 2492 .El 2493 .Pp 2494 It is an error 2495 .Pq Er EINVAL 2496 to specify flags other than those described above 2497 or to apply these operations to a system process. 2498 The current modes are reported in the 2499 .Sy pr_flags 2500 field of 2501 .Pa /proc/ Ns Em pid Ns Pa /status 2502 and 2503 .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwp Ns Pa /lwpstatus . 2504 .Ss PCSREG 2505 Set the general registers for the specific or representative lwp according to 2506 the operand 2507 .Vt prgregset_t 2508 structure. 2509 .Pp 2510 On SPARC based systems, only the condition-code bits of the processor-status 2511 register (R_PSR) of SPARC V8 (32-bit) processes can be modified by 2512 .Sy PCSREG . 2513 Other privileged registers cannot be modified at all. 2514 .Pp 2515 On x86-based systems, only certain bits of the flags register (EFL) can be 2516 modified by 2517 .Sy PCSREG : 2518 these include the condition codes, direction-bit, and overflow-bit. 2519 .Pp 2520 .Sy PCSREG 2521 fails with 2522 .Er EBUSY 2523 if the lwp is not stopped on an event of interest. 2524 .Ss PCSVADDR 2525 Set the address at which execution will resume for the specific or 2526 representative lwp from the operand 2527 .Vt long . 2528 On SPARC based systems, both %pc and %npc are set, with %npc set to the 2529 instruction following the virtual address. 2530 On x86-based systems, only %eip is set. 2531 .Sy PCSVADDR 2532 fails with 2533 .Er EBUSY 2534 if the lwp is not stopped on an event of interest. 2535 .Ss PCSFPREG 2536 Set the floating-point registers for the specific or representative lwp 2537 according to the operand 2538 .Vt prfpregset_t 2539 structure. 2540 An error 2541 .Pq Er EINVAL 2542 is returned if the system does not support floating-point operations (no 2543 floating-point hardware and the system does not emulate floating-point machine 2544 instructions). 2545 .Sy PCSFPREG 2546 fails with 2547 .Er EBUSY 2548 if the lwp is not stopped on an event of interest. 2549 .Ss PCSXREG 2550 Set the extra state registers for the specific or representative lwp according 2551 to the architecture-dependent operand 2552 .Vt prxregset_t 2553 structure. 2554 An error 2555 .Pq Er EINVAL 2556 is returned if the system does not support extra state registers. 2557 .Sy PCSXREG 2558 fails with 2559 .Er EBUSY 2560 if the lwp is not stopped on an event of interest. 2561 .Ss PCSASRS 2562 Set the ancillary state registers for the specific or representative lwp 2563 according to the SPARC V9 platform-dependent operand 2564 .Vt asrset_t 2565 structure. 2566 An error 2567 .Pq Er EINVAL 2568 is returned if either the target process or the 2569 controlling process is not a 64-bit SPARC V9 process. 2570 Most of the ancillary state registers are privileged registers that cannot be 2571 modified. 2572 Only those that can be modified are set; all others are silently ignored. 2573 .Sy PCSASRS 2574 fails with 2575 .Er EBUSY 2576 if the lwp is not stopped on an event of interest. 2577 .Ss PCAGENT 2578 Create an agent lwp in the controlled process with register values from the 2579 operand 2580 .Vt prgregset_t 2581 structure (see 2582 .Sy PCSREG , 2583 above). 2584 The agent lwp is created in the stopped state showing 2585 .Sy PR_REQUESTED 2586 and with its held signal set (the signal mask) having all signals except 2587 .Sy SIGKILL 2588 and 2589 .Sy SIGSTOP 2590 blocked. 2591 .Pp 2592 The 2593 .Sy PCAGENT 2594 operation fails with 2595 .Er EBUSY 2596 unless the process is fully stopped via 2597 .Pa /proc , 2598 that is, unless all of the lwps in the process are 2599 stopped either on events of interest or on 2600 .Sy PR_SUSPENDED , 2601 or are stopped on 2602 .Sy PR_JOBCONTROL 2603 and have been directed to stop via 2604 .Sy PCDSTOP . 2605 It fails with 2606 .Er EBUSY 2607 if an agent lwp already exists. 2608 It fails with 2609 .Er ENOMEM 2610 if system resources for creating new lwps have been exhausted. 2611 .Pp 2612 Any 2613 .Sy PCRUN 2614 operation applied to the process control file or to the control 2615 file of an lwp other than the agent lwp fails with 2616 .Er EBUSY 2617 as long as the agent lwp exists. 2618 The agent lwp must be caused to terminate by executing the 2619 .Sy SYS_lwp_exit 2620 system call trap before the process can be restarted. 2621 .Pp 2622 Once the agent lwp is created, its lwp-ID can be found by reading the process 2623 status file. 2624 To facilitate opening the agent lwp's control and status files, 2625 the directory name 2626 .Pa /proc/ Ns Em pid Ns Pa /lwp/agent 2627 is accepted for lookup operations as an invisible alias for 2628 .Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid , 2629 .Em lwpid 2630 being the lwp-ID of the agent lwp (invisible in the sense that the name 2631 .Dq agent 2632 does not appear in a directory listing of 2633 .Pa /proc/ Ns Em pid Ns Pa /lwp 2634 obtained from 2635 .Xr ls 1 , 2636 .Xr getdents 2 , 2637 or 2638 .Xr readdir 3C . 2639 .Pp 2640 The purpose of the agent lwp is to perform operations in the controlled process 2641 on behalf of the controlling process: to gather information not directly 2642 available via 2643 .Pa /proc 2644 files, or in general to make the process change state 2645 in ways not directly available via 2646 .Pa /proc 2647 control operations. 2648 To make use of an agent lwp, the controlling process must be capable of making 2649 it execute system calls (specifically, the 2650 .Sy SYS_lwp_exit 2651 system call trap). 2652 The register values given to the agent lwp on creation are typically the 2653 registers of the representative lwp, so that the agent lwp can use its stack. 2654 .Pp 2655 If the controlling process neglects to force the agent lwp to execute the 2656 .Sy SYS_lwp_exit 2657 system call (due to either logic error or fatal failure on 2658 the part of the controlling process), the agent lwp will remain in the target 2659 process. 2660 For purposes of being able to debug these otherwise rogue agents, 2661 information as to the creator of the agent lwp is reflected in that lwp's 2662 .Pa spymaster 2663 file in 2664 .Pa /proc . 2665 Should the target process generate a core 2666 dump with the agent lwp in place, this information will be available via the 2667 .Sy NT_SPYMASTER 2668 note in the core file (see 2669 .Xr core 4 ) . 2670 .Pp 2671 The agent lwp is not allowed to execute any variation of the 2672 .Sy SYS_fork 2673 or 2674 .Sy SYS_exec 2675 system call traps. 2676 Attempts to do so yield 2677 .Er ENOTSUP 2678 to the agent lwp. 2679 .Pp 2680 Symbolic constants for system call trap numbers like 2681 .Sy SYS_lwp_exit 2682 and 2683 .Sy SYS_lwp_create 2684 can be found in the header file 2685 .In sys/syscall.h . 2686 .Ss PCREAD PCWRITE 2687 Read or write the target process's address space via a 2688 .Vt priovec 2689 structure operand: 2690 .Bd -literal -offset 2 2691 typedef struct priovec { 2692 void *pio_base; /* buffer in controlling process */ 2693 size_t pio_len; /* size of read/write request in bytes */ 2694 off_t pio_offset; /* virtual address in target process */ 2695 } priovec_t; 2696 .Ed 2697 .Pp 2698 These operations have the same effect as 2699 .Xr pread 2 2700 and 2701 .Xr pwrite 2 , 2702 respectively, of the target process's address space file. 2703 The difference is that more than one 2704 .Sy PCREAD 2705 or 2706 .Sy PCWRITE 2707 control operation can be 2708 written to the control file at once, and they can be interspersed with other 2709 control operations in a single write to the control file. 2710 This is useful, for example, when planting many breakpoint instructions in 2711 the process's address space, or when stepping over a breakpointed instruction. 2712 Unlike 2713 .Xr pread 2 2714 and 2715 .Xr pwrite 2 , 2716 no provision is made for partial reads or writes; if the 2717 operation cannot be performed completely, it fails with 2718 .Er EIO . 2719 .Ss PCNICE 2720 The traced process's 2721 .Xr nice 2 2722 value is incremented by the amount in the 2723 operand 2724 .Vt long . 2725 Only a process with the 2726 .Brq Sy PRIV_PROC_PRIOCNTL 2727 privilege asserted in its effective set can better a process's priority in this 2728 way, but any user may lower the priority. 2729 This operation is not meaningful for all scheduling classes. 2730 .Ss PCSCRED 2731 Set the target process credentials to the values contained in the 2732 .Vt prcred_t 2733 structure operand (see 2734 .Pa /proc/ Ns Em pid Ns Pa /cred ) . 2735 The 2736 effective, real, and saved user-IDs and group-IDs of the target process are 2737 set. 2738 The target process's supplementary groups are not changed; the 2739 .Sy pr_ngroups 2740 and 2741 .Sy pr_groups 2742 members of the structure operand are ignored. 2743 Only the privileged processes can perform this operation; for all 2744 others it fails with 2745 .Er EPERM . 2746 .Ss PCSCREDX 2747 Operates like 2748 .Sy PCSCRED 2749 but also sets the supplementary groups; the length 2750 of the data written with this control operation should be "sizeof 2751 .Pq Vt prcred_t 2752 + sizeof 2753 .Pq Vt gid_t 2754 * (#groups - 1)". 2755 .Ss PCSPRIV 2756 Set the target process privilege to the values contained in the 2757 .Vt prpriv_t 2758 operand (see 2759 .Pa /proc/pid/priv ) . 2760 The effective, permitted, inheritable, and 2761 limit sets are all changed. 2762 Privilege flags can also be set. 2763 The process is made privilege aware unless it can relinquish privilege awareness. 2764 See 2765 .Xr privileges 5 . 2766 .Pp 2767 The limit set of the target process cannot be grown. 2768 The other privilege sets must be subsets of the intersection of the effective set 2769 of the calling process with the new limit set of the target process or subsets of 2770 the original values of the sets in the target process. 2771 .Pp 2772 If any of the above restrictions are not met, 2773 .Er EPERM 2774 is returned. 2775 If the structure written is improperly formatted, 2776 .Er EINVAL 2777 is returned. 2778 .Sh PROGRAMMING NOTES 2779 For security reasons, except for the 2780 .Sy psinfo , 2781 .Sy usage , 2782 .Sy lpsinfo , 2783 .Sy lusage , 2784 .Sy lwpsinfo , 2785 and 2786 .Sy lwpusage 2787 files, which are world-readable, and except for privileged processes, an open 2788 of a 2789 .Pa /proc 2790 file fails unless both the user-ID and group-ID of the caller match those of 2791 the traced process and the process's object file is readable by the caller. 2792 The effective set of the caller is a superset of both the inheritable and the 2793 permitted set of the target process. 2794 The limit set of the caller is a superset of the limit set of the target 2795 process. 2796 Except for the world-readable files just mentioned, files corresponding to 2797 setuid and setgid processes can be opened only by the appropriately privileged 2798 process. 2799 .Pp 2800 A process that is missing the basic privilege 2801 .Brq Sy PRIV_PROC_INFO 2802 cannot see any processes under 2803 .Pa /proc 2804 that it cannot send a signal to. 2805 .Pp 2806 A process that has 2807 .Brq Sy PRIV_PROC_OWNER 2808 asserted in its effective set can open any file for reading. 2809 To manipulate or control a process, the controlling process must have at least 2810 as many privileges in its effective set as the target process has in its 2811 effective, inheritable, and permitted sets. 2812 The limit set of the controlling process must be a superset of the limit set 2813 of the target process. 2814 Additional restrictions apply if any of the uids of the target process are 0. 2815 See 2816 .Xr privileges 5 . 2817 .Pp 2818 Even if held by a privileged process, an open process or lwp file descriptor 2819 (other than file descriptors for the world-readable files) becomes invalid if 2820 the traced process performs an 2821 .Xr exec 2 2822 of a setuid/setgid object file or 2823 an object file that the traced process cannot read. 2824 Any operation performed on an invalid file descriptor, except 2825 .Xr close 2 , 2826 fails with 2827 .Er EAGAIN . 2828 In this situation, if any tracing flags are set and the process or any lwp 2829 file descriptor is open for writing, the process will have been directed to 2830 stop and its run-on-last-close flag will have been set (see 2831 .Sx PCSET ) . 2832 This enables a controlling process (if it has permission) to reopen the 2833 .Pa /proc 2834 files to get new valid file descriptors, close the invalid file descriptors, 2835 unset the run-on-last-close flag (if desired), and proceed. 2836 Just closing the invalid file descriptors causes the traced process to resume 2837 execution with all tracing flags cleared. 2838 Any process not currently open for writing via 2839 .Pa /proc , 2840 but that has left-over tracing flags from a previous open, and that executes 2841 a setuid/setgid or unreadable object file, will not be stopped but will have 2842 all its tracing flags cleared. 2843 .Pp 2844 To wait for one or more of a set of processes or lwps to stop or terminate, 2845 .Pa /proc 2846 file descriptors (other than those obtained by opening the 2847 .Pa cwd 2848 or 2849 .Pa root 2850 directories or by opening files in the 2851 .Pa fd 2852 or 2853 .Pa object 2854 directories) can be used in a 2855 .Xr poll 2 2856 system call. 2857 When requested and returned, either of the polling events 2858 .Sy POLLPRI 2859 or 2860 .Sy POLLWRNORM 2861 indicates that the process or lwp stopped on an event of 2862 interest. 2863 Although they cannot be requested, the polling events 2864 .Sy POLLHUP , 2865 .Sy POLLERR , 2866 and 2867 .Sy POLLNVAL 2868 may be returned. 2869 .Sy POLLHUP 2870 indicates that the process or lwp has terminated. 2871 .Sy POLLERR 2872 indicates that the file descriptor has become invalid. 2873 .Sy POLLNVAL 2874 is returned immediately if 2875 .Sy POLLPRI 2876 or 2877 .Sy POLLWRNORM 2878 is requested on a file descriptor referring to a system process (see 2879 .Sx PCSTOP ) . 2880 The requested events may be empty to wait simply for termination. 2881 .Sh FILES 2882 .Bl -tag -compact -width Ds 2883 .It Pa /proc 2884 directory (list of processes) 2885 .It Pa /proc/ Ns Em pid 2886 specific process directory 2887 .It Pa /proc/self 2888 alias for a process's own directory 2889 .It Pa /proc/ Ns Em pid Ns Pa /as 2890 address space file 2891 .It Pa /proc/ Ns Em pid Ns Pa /ctl 2892 process control file 2893 .It Pa /proc/ Ns Em pid Ns Pa /status 2894 process status 2895 .It Pa /proc/ Ns Em pid Ns Pa /lstatus 2896 array of lwp status structs 2897 .It Pa /proc/ Ns Em pid Ns Pa /psinfo 2898 process 2899 .Xr ps 1 2900 info 2901 .It Pa /proc/ Ns Em pid Ns Pa /lpsinfo 2902 array of lwp 2903 .Xr ps 1 2904 info structs 2905 .It Pa /proc/ Ns Em pid Ns Pa /map 2906 address space map 2907 .It Pa /proc/ Ns Em pid Ns Pa /xmap 2908 extended address space map 2909 .It Pa /proc/ Ns Em pid Ns Pa /rmap 2910 reserved address map 2911 .It Pa /proc/ Ns Em pid Ns Pa /cred 2912 process credentials 2913 .It Pa /proc/ Ns Em pid Ns Pa /priv 2914 process privileges 2915 .It Pa /proc/ Ns Em pid Ns Pa /sigact 2916 process signal actions 2917 .It Pa /proc/ Ns Em pid Ns Pa /auxv 2918 process aux vector 2919 .It Pa /proc/ Ns Em pid Ns Pa /ldt 2920 process 2921 .Sy LDT 2922 (x86 only) 2923 .It Pa /proc/ Ns Em pid Ns Pa /usage 2924 process usage 2925 .It Pa /proc/ Ns Em pid Ns Pa /lusage 2926 array of lwp usage structs 2927 .It Pa /proc/ Ns Em pid Ns Pa /path 2928 symbolic links to process open files 2929 .It Pa /proc/ Ns Em pid Ns Pa /pagedata 2930 process page data 2931 .It Pa /proc/ Ns Em pid Ns Pa /watch 2932 active watchpoints 2933 .It Pa /proc/ Ns Em pid Ns Pa /cwd 2934 alias for the current working directory 2935 .It Pa /proc/ Ns Em pid Ns Pa /root 2936 alias for the root directory 2937 .It Pa /proc/ Ns Em pid Ns Pa /fd 2938 directory (list of open files) 2939 .It Pa /proc/ Ns Em pid Ns Pa /fd/* 2940 aliases for process's open files 2941 .It Pa /proc/ Ns Em pid Ns Pa /object 2942 directory (list of mapped files) 2943 .It Pa /proc/ Ns Em pid Ns Pa /object/a.out 2944 alias for process's executable file 2945 .It Pa /proc/ Ns Em pid Ns Pa /object/* 2946 aliases for other mapped files 2947 .It Pa /proc/ Ns Em pid Ns Pa /lwp 2948 directory (list of lwps) 2949 .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid 2950 specific lwp directory 2951 .It Pa /proc/ Ns Em pid Ns Pa /lwp/agent 2952 alias for the agent lwp directory 2953 .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpctl 2954 lwp control file 2955 .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpstatus 2956 lwp status 2957 .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpsinfo 2958 lwp 2959 .Xr ps 1 2960 info 2961 .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpusage 2962 lwp usage 2963 .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /gwindows 2964 register windows (SPARC only) 2965 .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /xregs 2966 extra state registers 2967 .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /asrs 2968 ancillary state registers (SPARC V9 only) 2969 .It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /spymaster 2970 For an agent LWP, the controlling process 2971 .El 2972 .Sh DIAGNOSTICS 2973 Errors that can occur in addition to the errors normally associated with file 2974 system access: 2975 .Bl -tag -width "EOVERFLOW" -offset left 2976 .It Er E2BIG 2977 Data to be returned in a 2978 .Xr read 2 2979 of the page data file exceeds the size of the read buffer provided by the 2980 caller. 2981 .It Er EACCES 2982 An attempt was made to examine a process that ran under a different uid than 2983 the controlling process and 2984 .Brq Sy PRIV_PROC_OWNER 2985 was not asserted in the effective set. 2986 .It Er EAGAIN 2987 The traced process has performed an 2988 .Xr exec 2 2989 of a setuid/setgid object 2990 file or of an object file that it cannot read; all further operations on the 2991 process or lwp file descriptor (except 2992 .Xr close 2 ) 2993 elicit this error. 2994 .It Er EBUSY 2995 .Sy PCSTOP , 2996 .Sy PCDSTOP , 2997 .Sy PCWSTOP , or 2998 .Sy PCTWSTOP 2999 was applied to a system process; an exclusive 3000 .Xr open 2 3001 was attempted on a 3002 .Pa /proc 3003 file for a process already open for writing; 3004 .Sy PCRUN , 3005 .Sy PCSREG , 3006 .Sy PCSVADDR , 3007 .Sy PCSFPREG , 3008 or 3009 .Sy PCSXREG 3010 was applied to a process or 3011 lwp not stopped on an event of interest; an attempt was made to mount 3012 .Pa /proc 3013 when it was already mounted; 3014 .Sy PCAGENT 3015 was applied to a process 3016 that was not fully stopped or that already had an agent lwp. 3017 .It Er EINVAL 3018 In general, this means that some invalid argument was supplied to a system 3019 call. 3020 A non-exhaustive list of conditions eliciting this error includes: a 3021 control message operation code is undefined; an out-of-range signal number was 3022 specified with 3023 .Sy PCSSIG , 3024 .Sy PCKILL , 3025 or 3026 .Sy PCUNKILL ; 3027 .Sy SIGKILL 3028 was specified with 3029 .Sy PCUNKILL ; 3030 .Sy PCSFPREG 3031 was applied on a system that does not support floating-point operations; 3032 .Sy PCSXREG 3033 was applied on a system that does not support extra state registers. 3034 .It Er EINTR 3035 A signal was received by the controlling process while waiting for the traced 3036 process or lwp to stop via 3037 .Sy PCSTOP , 3038 .Sy PCWSTOP , 3039 or 3040 .Sy PCTWSTOP . 3041 .It Er EIO 3042 A 3043 .Xr write 2 3044 was attempted at an illegal address in the traced process. 3045 .It Er ENOENT 3046 The traced process or lwp has terminated after being opened. 3047 The basic privilege 3048 .Brq Sy PRIV_PROC_INFO 3049 is not asserted in the effective set of the calling process and the calling 3050 process cannot send a signal to the target process. 3051 .It Er ENOMEM 3052 The system-imposed limit on the number of page data file descriptors was 3053 reached on an open of 3054 .Pa /proc/ Ns Em pid Ns Pa /pagedata ; 3055 an attempt was made 3056 with 3057 .Sy PCWATCH 3058 to establish more watched areas than the system can support; 3059 the 3060 .Sy PCAGENT 3061 operation was issued when the system was out of resources for 3062 creating lwps. 3063 .It Er ENOSYS 3064 An attempt was made to perform an unsupported operation (such as 3065 .Xr creat 2 , 3066 .Xr link 2 , 3067 or 3068 .Xr unlink 2 ) 3069 on an entry in 3070 .Pa /proc . 3071 .It Er EOVERFLOW 3072 A 32-bit controlling process attempted to read or write the 3073 .Pa as 3074 file or attempted to read the 3075 .Pa map , 3076 .Pa rmap , 3077 or 3078 .Pa pagedata 3079 file of a 64-bit target process. 3080 A 32-bit controlling process attempted to apply one of the 3081 control operations 3082 .Sy PCSREG , 3083 .Sy PCSXREG , 3084 .Sy PCSVADDR , 3085 .Sy PCWATCH , 3086 .Sy PCAGENT , 3087 .Sy PCREAD , 3088 .Sy PCWRITE 3089 to a 64-bit target process. 3090 .It Er EPERM 3091 The process that issued the 3092 .Sy PCSCRED 3093 or 3094 .Sy PCSCREDX 3095 operation did not have the 3096 .Brq Sy PRIV_PROC_SETID 3097 privilege asserted in its effective set, or 3098 the process that issued the 3099 .Sy PCNICE 3100 operation did not have the 3101 .Brq Sy PRIV_PROC_PRIOCNTL 3102 in its effective set. 3103 .Pp 3104 An attempt was made to control a process of which the E, P, and I privilege 3105 sets were not a subset of the effective set of the controlling process or the 3106 limit set of the controlling process is not a superset of limit set of the 3107 controlled process. 3108 .Pp 3109 Any of the uids of the target process are 3110 .Sy 0 3111 or an attempt was made to change any of the uids to 3112 .Sy 0 3113 using 3114 .Sy PCSCRED 3115 and the security policy imposed additional restrictions. 3116 See 3117 .Xr privileges 5 . 3118 .El 3119 .Sh SEE ALSO 3120 .Xr ls 1 , 3121 .Xr ps 1 , 3122 .Xr chroot 1M , 3123 .Xr alarm 2 , 3124 .Xr brk 2 , 3125 .Xr chdir 2 , 3126 .Xr chroot 2 , 3127 .Xr close 2 , 3128 .Xr creat 2 , 3129 .Xr dup 2 , 3130 .Xr exec 2 , 3131 .Xr fcntl 2 , 3132 .Xr fork 2 , 3133 .Xr fork1 2 , 3134 .Xr fstat 2 , 3135 .Xr getdents 2 , 3136 .Xr getustack 2 , 3137 .Xr kill 2 , 3138 .Xr lseek 2 , 3139 .Xr mmap 2 , 3140 .Xr nice 2 , 3141 .Xr open 2 , 3142 .Xr poll 2 , 3143 .Xr pread 2 , 3144 .Xr pwrite 2 , 3145 .Xr read 2 , 3146 .Xr readlink 2 , 3147 .Xr readv 2 , 3148 .Xr shmget 2 , 3149 .Xr sigaction 2 , 3150 .Xr sigaltstack 2 , 3151 .Xr vfork 2 , 3152 .Xr write 2 , 3153 .Xr writev 2 , 3154 .Xr _stack_grow 3C , 3155 .Xr pthread_create 3C , 3156 .Xr pthread_join 3C , 3157 .Xr ptrace 3C , 3158 .Xr readdir 3C , 3159 .Xr thr_create 3C , 3160 .Xr thr_join 3C , 3161 .Xr wait 3C , 3162 .Xr siginfo.h 3HEAD , 3163 .Xr signal.h 3HEAD , 3164 .Xr types32.h 3HEAD , 3165 .Xr ucontext.h 3HEAD , 3166 .Xr contract 4 , 3167 .Xr core 4 , 3168 .Xr process 4 , 3169 .Xr lfcompile 5 , 3170 .Xr privileges 5 , 3171 .Xr security-flags 5 3172 .Sh NOTES 3173 Descriptions of structures in this document include only interesting structure 3174 elements, not filler and padding fields, and may show elements out of order for 3175 descriptive clarity. 3176 The actual structure definitions are contained in 3177 .In procfs.h . 3178 .Sh BUGS 3179 Because the old 3180 .Xr ioctl 2 Ns -based 3181 version of 3182 .Pa /proc 3183 is currently supported for binary compatibility with old applications, the 3184 top-level directory for a process, 3185 .Pa /proc/ Ns Em pid , 3186 is not world-readable, but it is world-searchable. 3187 Thus, anyone can open 3188 .Pa /proc/ Ns Em pid Ns Pa /psinfo 3189 even though 3190 .Xr ls 1 3191 applied to 3192 .Pa /proc/ Ns Em pid 3193 will fail for anyone but the owner or an appropriately privileged process. 3194 Support for the old 3195 .Xr ioctl 2 Ns -based 3196 version of 3197 .Pa /proc 3198 will be dropped in a future release, at which time the top-level directory for 3199 a process will be made world-readable. 3200 .Pp 3201 On SPARC based machines, the types 3202 .Sy gregset_t 3203 and 3204 .Sy fpregset_t 3205 defined in 3206 .In sys/regset.h 3207 are similar to but not the same as the types 3208 .Sy prgregset_t 3209 and 3210 .Sy prfpregset_t 3211 defined in 3212 .In procfs.h . --- EOF ---