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