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 8, 2023 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. 1833Reading this data currently requires that the process be stopped. 1834.Ss asrs 1835This file exists only for 64-bit SPARC V9 processes. 1836It contains an 1837.Vt asrset_t 1838structure, defined in 1839.In sys/regset.h , 1840containing the values of the lwp's platform-dependent ancillary state registers. 1841If the lwp is not stopped, all register values are undefined. 1842See also the 1843.Sx PCSASRS 1844control operation, below. 1845.Ss spymaster 1846For an agent lwp (see 1847.Sx PCAGENT ) , 1848this file contains a 1849.Vt psinfo_t 1850structure that corresponds to the process that created the agent lwp at the 1851time the agent was created. 1852This structure is identical to that retrieved via the 1853.Pa psinfo 1854file, with one modification: the 1855.Sy pr_time 1856field does not correspond to the CPU time for the process, but rather to the 1857creation time of the agent lwp. 1858.Ss templates 1859A directory which contains references to the active templates for the lwp, 1860named by the contract type. 1861Changes made to an active template descriptor do 1862not affect the original template which was activated, though they do affect the 1863active template. 1864It is not possible to activate an active template descriptor. 1865See 1866.Xr contract 5 . 1867.Sh ARCHITECTURE-SPECIFIC STRUCTURES 1868.Ss x86 1869While the x86 1870.Vt prxregset_t 1871structure is opaque to consumers, it is made up of several different 1872components due to the fact that different x86 processors enumerate 1873different architectural extensions. 1874.Pp 1875The structure begins with a header, the 1876.Vt prxregset_hdr_t , 1877which is followed by a number of different information sections which 1878describe different possible extended registers. 1879Each of those is covered by a 1880.Vt prxregset_info_t , 1881and then finally there are different data payloads that represent each 1882extended register. 1883.Pp 1884The number of different informational entries varies from system to 1885system based on the set of architectural features that the system 1886supports and the corresponding OS enablement for them. 1887This structure is built around the idea of the x86 1888.Sy xsave 1889structure. 1890That is, there is a central header which describes a bit-vector of what 1891extended features are present and have valid state. 1892.Pp 1893Each x86 xregs file begins with the 1894.Vt prxregset_hdr_t 1895which looks like: 1896.Bd -literal -offset 2 1897typedef struct prxregset_hdr { 1898 uint32_t pr_type; 1899 uint32_t pr_size; 1900 uint32_t pr_flags; 1901 uint32_t pr_pad[4]; 1902 uint32_t pr_ninfo; 1903 prxregset_info_t pr_info[]; 1904} prxregset_hdr_t; 1905.Ed 1906.Pp 1907The 1908.Fa pr_type 1909member is always set to 1910.Dv PR_TYPE_XSAVE . 1911This is used to indicate the type of file that is present. 1912There may be different file types in the future on x86 so this value 1913should always be checked. 1914If it is not 1915.Dv PR_TYPE_XSAVE 1916then the rest of the structure may look different. 1917The 1918.Fa pr_size 1919member indicates the size in bytes of the overall structure. 1920The 1921.Fa pr_flags 1922and 1923.Fa pr_pad 1924values are currently reserved for future use. 1925They will be set to zero right now when read and must be set to zero when 1926writing the data. 1927The 1928.Fa pr_ninfo 1929member indicates the number of informational items are present in 1930.Fa pr_info. 1931There will be one informational item for each register set that exists. 1932.Pp 1933The 1934.Fa pr_info 1935member points to an array of informational members. 1936These immediately follow the structure, though the 1937.Fa pr_info 1938member may not be available directly if not in an environment compatible with 1939some C99 features. 1940Each 1941.Vt prxregset_info_t 1942structure looks like: 1943.Bd -literal -offset 2 1944typedef struct prxregset_info { 1945 uint32_t pri_type; 1946 uint32_t pri_flags; 1947 uint32_t pri_size; 1948 uint32_t pri_offset; 1949} prxregset_info_t; 1950.Ed 1951.Pp 1952The 1953.Fa pri_type 1954member is used to indicate the type of data and its format that this represents. 1955Types are listed below. 1956The 1957.Fa pri_flags 1958member is used to indicate future extensions or information about these items. 1959Right now, these are all zero. 1960The 1961.Fa pri_size 1962member indicates the size in bytes of the type's data. 1963The 1964.Fa pri_offset 1965member indicates the offset to the start of the data section from the beginning 1966of the xregs file. 1967That is an offset of 0 would be the first byte of the 1968.Vt prxregset_hdr_t . 1969.Pp 1970The following types of structures and their corresponding data structures are 1971currently defined: 1972.Bl -tag -width Ds 1973.It Dv PRX_INFO_XCR - Vt prxregset_xcr_t 1974This structure provides read-only access to understanding the CPU's settings for 1975this thread. 1976In particular, it lets you see what is set in the x86 %xcr0 register which is 1977the extended feature control register and controls what extended features the 1978CPU actually uses. 1979It also contains the x86 extended feature disable MSR which controls features 1980that are ignored. 1981The 1982.Vt prxregset_xcr_t 1983looks like: 1984.Bd -literal -offset -indent 1985typedef struct prxregset_xcr { 1986 uint64_t prx_xcr_xcr0; 1987 uint64_t prx_xcr_xfd; 1988 uint64_t prx_xcr_pad[2]; 1989} prxregset_xcr_t; 1990.Ed 1991.Pp 1992When setting the xregs, this entry can be left out. 1993If it is included, it must match the existing entries, otherwise an error will 1994be generated. 1995.It Dv PRX_INFO_XSAVE - Vt prxregset_xsave_t 1996This structure represents the same as the actual Intel xsave structure, which 1997has both the traditional XMM state that comes from the fxsave instruction and 1998then also contains the xsave header itself. 1999The structure varies between 32-bit and 64-bit applications. 2000The structure itself looks like: 2001.Bd -literal 2002typedef struct prxregset_xsave { 2003 uint16_t prx_fx_fcw; 2004 uint16_t prx_fx_fsw; 2005 uint16_t prx_fx_fctw; /* compressed tag word */ 2006 uint16_t prx_fx_fop; 2007#if defined(__amd64) 2008 uint64_t prx_fx_rip; 2009 uint64_t prx_fx_rdp; 2010#else 2011 uint32_t prx_fx_eip; 2012 uint16_t prx_fx_cs; 2013 uint16_t __prx_fx_ign0; 2014 uint32_t prx_fx_dp; 2015 uint16_t prx_fx_ds; 2016 uint16_t __prx_fx_ign1; 2017#endif 2018 uint32_t prx_fx_mxcsr; 2019 uint32_t prx_fx_mxcsr_mask; 2020 union { 2021 uint16_t prx_fpr_16[5]; /* 80-bits of x87 state */ 2022 u_longlong_t prx_fpr_mmx; /* 64-bit mmx register */ 2023 uint32_t _prx__fpr_pad[4]; /* (pad out to 128-bits) */ 2024 } fx_st[8]; 2025#if defined(__amd64) 2026 upad128_t prx_fx_xmm[16]; /* 128-bit registers */ 2027 upad128_t __prx_fx_ign2[6]; 2028#else 2029 upad128_t prx_fx_xmm[8]; /* 128-bit registers */ 2030 upad128_t __prx_fx_ign2[14]; 2031#endif 2032 uint64_t prx_xsh_xstate_bv; 2033 uint64_t prx_xsh_xcomp_bv; 2034 uint64_t prx_xsh_reserved[6]; 2035} prxregset_xsave_t; 2036.Ed 2037.Pp 2038In the classical fxsave portion of the structure, most of the members follow the 2039same meaning and match their presence in the fpregs file and their use as 2040discussed in the Intel and AMD software developer manuals. 2041The one exception is that when setting the 2042.Fa prx_fx_mxcsr 2043member reserved bits that are set will be masked off and ignored. 2044.Pp 2045The most notable fields to consider here right now are the last few members 2046which are part of the xsave header itself. 2047In particular, the 2048.Fa prx_xsh_xstate_bv 2049component is used to track the actual features whose content are valid. 2050When reading the registers, if a given entry is not valid, the register state 2051will write out the informational entry in its default state. 2052When setting the extended registers, this notes which features will be loaded 2053from their default state 2054.Pq as defined by Intel and AMD's manuals 2055and which will be loaded from the informational entries. 2056If a bit is set in the 2057.Fa prx_xsh_xstate_bv 2058entry, then it must be present as its own informational entry otherwise a write 2059will fail. 2060If an informational entry is present in a write, but not set in the 2061.Fa prx_xsh_xstate_bv 2062then its contents will be ignored. 2063.Pp 2064The xregs format currently does not support any compressed items being specified 2065nor does it specify any, so the 2066.Fa prx_xsh_xcomp_bv 2067member will be always set to zero and it and the reserved members 2068.Fa prx_xsh_reserved 2069must all be left as zero. 2070.It Dv PRX_INFO_YMM - Vt prxregset_ymm_t 2071This structure contains the upper 128-bits of the first 16 %ymm registers 2072.Pq 8 for 32-bit applications . 2073To construct a full vector register, it must be combined with the 2074.Fa prx_fx_xmm 2075member of the 2076.Dv PRX_INFO_XSAVE 2077data. 2078In 32-bit applications, the reserved registers must be written as zero. 2079The structure itself looks like: 2080.Bd -literal -offset 2 2081typedef struct prxregset_ymm { 2082#if defined(__amd64) 2083 upad128_t prx_ymm[16]; 2084#else 2085 upad128_t prx_ymm[8]; 2086 upad128_t prx_rsvd[8]; 2087#endif 2088} prxregset_ymm_t; 2089.Ed 2090.It Dv PRX_INFO_OPMASK - Vt prxregset_opmask_t 2091This structure represents one portion of Intel's AVX-512 state: the 8 64-bit 2092mask registers, %k0 through %k7. 2093The structure looks like: 2094.Bd -literal -offset 2 2095typedef struct prxregset_opmask { 2096 uint64_t prx_opmask[8]; 2097} prxregset_opmask_t; 2098.Ed 2099.It Dv PRX_INFO_ZMM - Vt prxregset_zmm_t 2100This structure represents one portion of Intel's AVX-512 state: the upper 2101256 bits of the 512-bit %zmm0 through %zmm15 registers. 2102Bits 0-127 are found in the 2103.Fa prx_fx_xmm 2104member of the 2105.Dv PRX_INFO_XSAVE 2106data and bits 128-255 are found in the 2107.Fa prx_ymm 2108member of the 2109.Dv PRX_INFO_YMM . 211032-bit applications only have access to %zmm0 through %zmm7. 2111This structure looks like: 2112.Bd -literal -offset 2 2113typedef struct prxregset_zmm { 2114#if defined(__amd64) 2115 upad256_t prx_zmm[16]; 2116#else 2117 upad256_t prx_zmm[8]; 2118 upad256_t prx_rsvd[8]; 2119#endif 2120} prxregset_zmm_t; 2121.Ed 2122.It Dv PRX_INFO_HI_ZMM - Vt prxregset_hi_zmm_t 2123This structure represents the third portion of Intel's AVX-512 state: the 2124additional 16 512-bit registers that are available to 64-bit applications, but 2125not 32-bit applications. 2126This represents %zmm16 through %zmm31. 2127This structure looks like: 2128.Bd -literal -offset indent 2129typedef struct prxregset_hi_zmm { 2130#if defined(__amd64) 2131 upad512_t prx_hi_zmm[16]; 2132#else 2133 upad512_t prx_rsvd[16]; 2134#endif 2135} prxregset_hi_zmm_t; 2136.Pp 2137Unlike the other lower %zmm registers of %zmm0 through %zmm15, this contains the 2138entire 512-bit register in one spot and there is no need to look at other 2139information items to reconstitute the entire vector. 2140.Ed 2141.Pp 2142When setting the extended registers, at least the 2143.Dv PRX_INFO_XSAVE 2144component must be present. 2145None of the component offsets may overlap with the 2146.Vt prxregset_hdr_t 2147or any of the 2148.Vt prxregset_info_t 2149structures. 2150When constructing the overall payload, it is expected that the various 2151structures start with their naturally expected alignment, which is most 2152often 16 bytes 2153.Po 2154that is the value that the C 2155.Fn alignof 2156keyword will return 2157.Pc . 2158The structures that we use are all multiples of 16 bytes to make this easier. 2159Note, when reading the x86 xregs file, the kernel will write out these 2160structures with increased alignment beyond the natural alignment of the 2161structure. 2162The kernel does this so that the structure's data may be more easily used 2163directly by x86 instructions that require alignment such as vmovdqu64. 2164.El 2165.Sh CONTROL MESSAGES 2166Process state changes are effected through messages written to a process's 2167.Sy ctl 2168file or to an individual lwp's 2169.Sy lwpctl 2170file. 2171All control messages consist of a 2172.Sy long 2173that names the specific operation followed by 2174additional data containing the operand, if any. 2175.Pp 2176Multiple control messages may be combined in a single 2177.Xr write 2 2178(or 2179.Xr writev 2 ) 2180to a control file, but no partial writes are permitted. 2181That is, each control message, operation code plus operand, if any, must be 2182presented in its entirety to the 2183.Xr write 2 2184and not in pieces over several system calls. 2185If a control operation fails, no subsequent operations contained in the same 2186.Xr write 2 2187are attempted. 2188.Pp 2189Descriptions of the allowable control messages follow. 2190In all cases, writing a message to a control file for a process or lwp that 2191has terminated elicits the error 2192.Er ENOENT . 2193.Ss PCSTOP PCDSTOP PCWSTOP PCTWSTOP 2194When applied to the process control file, 2195.Sy PCSTOP 2196directs all lwps to stop and waits for them to stop, 2197.Sy PCDSTOP 2198directs all lwps to stop without waiting for them to stop, and 2199.Sy PCWSTOP 2200simply waits for all lwps to stop. 2201When applied to an lwp control file, 2202.Sy PCSTOP 2203directs the specific lwp to stop and waits until it has stopped, 2204.Sy PCDSTOP 2205directs the specific lwp to stop without waiting for it to stop, and 2206.Sy PCWSTOP 2207simply waits for the specific lwp to stop. 2208When applied to an lwp control file, 2209.Sy PCSTOP 2210and 2211.Sy PCWSTOP 2212complete when the lwp stops on an event of interest, immediately 2213if already so stopped; when applied to the process control file, they complete 2214when every lwp has stopped either on an event of interest or on a 2215.Sy PR_SUSPENDED 2216stop. 2217.Pp 2218.Sy PCTWSTOP 2219is identical to 2220.Sy PCWSTOP 2221except that it enables the operation to time out, to avoid waiting forever for 2222a process or lwp that may never stop on an event of interest. 2223.Sy PCTWSTOP 2224takes a 2225.Sy long 2226operand specifying a number of milliseconds; the wait will terminate 2227successfully after the specified number of milliseconds even if the process or 2228lwp has not stopped; a timeout value of zero makes the operation identical to 2229.Sy PCWSTOP . 2230.Pp 2231An 2232.Dq event of interest 2233is either a 2234.Sy PR_REQUESTED 2235stop or a stop that has been specified in the process's tracing flags (set by 2236.Sy PCSTRACE , 2237.Sy PCSFAULT , 2238.Sy PCSENTRY , 2239and 2240.Sy PCSEXIT ) . 2241.Sy PR_JOBCONTROL 2242and 2243.Sy PR_SUSPENDED 2244stops are specifically not events of interest. 2245(An lwp may stop twice due to a stop signal, first showing 2246.Sy PR_SIGNALLED 2247if the signal is traced and again showing 2248.Sy PR_JOBCONTROL 2249if the lwp is set running without clearing the signal.) 2250If 2251.Sy PCSTOP 2252or 2253.Sy PCDSTOP 2254is applied to an 2255lwp that is stopped, but not on an event of interest, the stop directive takes 2256effect when the lwp is restarted by the competing mechanism. 2257At that time, the lwp enters a 2258.Sy PR_REQUESTED 2259stop before executing any user-level code. 2260.Pp 2261A write of a control message that blocks is interruptible by a signal so that, 2262for example, an 2263.Xr alarm 2 2264can be set to avoid waiting forever for a 2265process or lwp that may never stop on an event of interest. 2266If 2267.Sy PCSTOP 2268is interrupted, the lwp stop directives remain in effect even though the 2269.Xr write 2 2270returns an error. 2271(Use of 2272.Sy PCTWSTOP 2273with a non-zero timeout is recommended over 2274.Sy PCWSTOP 2275with an 2276.Xr alarm 2 . ) 2277.Pp 2278A system process (indicated by the 2279.Sy PR_ISSYS 2280flag) never executes at user level, has no user-level address space visible 2281through 2282.Pa /proc , 2283and cannot be stopped. 2284Applying one of these operations to a system process or any of its 2285lwps elicits the error 2286.Er EBUSY . 2287.Ss PCRUN 2288Make an lwp runnable again after a stop. 2289This operation takes a 2290.Vt long 2291operand containing zero or more of the following flags: 2292.Bl -tag -width "PRSABORT" -offset left 2293.It Sy PRCSIG 2294clears the current signal, if any (see 2295.Sx PCCSIG ) . 2296.It Sy PRCFAULT 2297clears the current fault, if any (see 2298.Sx PCCFAULT ) . 2299.It Sy PRSTEP 2300directs the lwp to execute a single machine instruction. 2301On completion of the instruction, a trace trap occurs. 2302If 2303.Sy FLTTRACE 2304is being traced, the lwp stops; otherwise, it is sent 2305.Sy SIGTRAP . 2306If 2307.Sy SIGTRAP 2308is being traced and is not blocked, the lwp stops. 2309When the lwp stops on an event of interest, 2310the single-step directive is cancelled, even if the stop occurs before the 2311instruction is executed. 2312This operation requires hardware and operating system 2313support and may not be implemented on all processors. 2314It is implemented on SPARC and x86-based machines. 2315.It Sy PRSABORT 2316is meaningful only if the lwp is in a 2317.Sy PR_SYSENTRY 2318stop or is marked 2319.Sy PR_ASLEEP ; 2320it instructs the lwp to abort execution of the system call (see 2321.Sx PCSENTRY 2322and 2323.Sx PCSEXIT ) . 2324.It Sy PRSTOP 2325directs the lwp to stop again as soon as possible after resuming execution (see 2326.Sx PCDSTOP ) . 2327In particular, if the lwp is stopped on 2328.Sy PR_SIGNALLED 2329or 2330.Sy PR_FAULTED , 2331the next stop will show 2332.Sy PR_REQUESTED , 2333no other stop 2334will have intervened, and the lwp will not have executed any user-level code. 2335.El 2336.Pp 2337When applied to an lwp control file, 2338.Sy PCRUN 2339clears any outstanding 2340directed-stop request and makes the specific lwp runnable. 2341The operation fails with 2342.Er EBUSY 2343if the specific lwp is not stopped on an event of interest or 2344has not been directed to stop or if the agent lwp exists and this is not the 2345agent lwp (see 2346.Sx PCAGENT ) . 2347.Pp 2348When applied to the process control file, a representative lwp is chosen for 2349the operation as described for 2350.Pa /proc/ Ns Em pid Ns Pa /status . 2351The operation fails with 2352.Er EBUSY 2353if the representative lwp is not stopped on an 2354event of interest or has not been directed to stop or if the agent lwp exists. 2355If 2356.Sy PRSTEP 2357or 2358.Sy PRSTOP 2359was requested, the representative lwp is made 2360runnable and its outstanding directed-stop request is cleared; otherwise all 2361outstanding directed-stop requests are cleared and, if it was stopped on an 2362event of interest, the representative lwp is marked 2363.Sy PR_REQUESTED . 2364If, as a consequence, all lwps are in the 2365.Sy PR_REQUESTED 2366or 2367.Sy PR_SUSPENDED 2368stop state, all lwps showing 2369.Sy PR_REQUESTED 2370are made runnable. 2371.Ss PCSTRACE 2372Define a set of signals to be traced in the process. 2373The receipt of one of these signals by an lwp causes the lwp to stop. 2374The set of signals is defined using an operand 2375.Sy sigset_t 2376contained in the control message. 2377Receipt of 2378.Sy SIGKILL 2379cannot be traced; if specified, it is silently ignored. 2380.Pp 2381If a signal that is included in an lwp's held signal set (the signal mask) is 2382sent to the lwp, the signal is not received and does not cause a stop until it 2383is removed from the held signal set, either by the lwp itself or by setting the 2384held signal set with 2385.Sy PCSHOLD . 2386.Ss PCCSIG 2387The current signal, if any, is cleared from the specific or representative lwp. 2388.Ss PCSSIG 2389The current signal and its associated signal information for the specific or 2390representative lwp are set according to the contents of the operand 2391.Vt siginfo 2392structure (see 2393.In sys/siginfo.h ) . 2394If the specified signal number is zero, the current signal is cleared. 2395The semantics of this operation are different from those of 2396.Xr kill 2 2397in that the signal is delivered to the lwp immediately after execution is 2398resumed (even if it is being blocked) and an additional 2399.Sy PR_SIGNALLED 2400stop does not intervene even if the signal is traced. 2401Setting the current signal to 2402.Sy SIGKILL 2403terminates the process immediately. 2404.Ss PCKILL 2405If applied to the process control file, a signal is sent to the process with 2406semantics identical to those of 2407.Xr kill 2 2408If applied to an lwp control file, a directed signal is sent to the specific 2409lwp. 2410The signal is named in a 2411.Vt long 2412operand contained in the message. 2413Sending 2414.Sy SIGKILL 2415terminates the process immediately. 2416.Ss PCUNKILL 2417A signal is deleted, that is, it is removed from the set of pending signals. 2418If applied to the process control file, the signal is deleted from the process's 2419pending signals. 2420If applied to an lwp control file, the signal is deleted from 2421the lwp's pending signals. 2422The current signal (if any) is unaffected. 2423The signal is named in a 2424.Sy long 2425operand in the control message. 2426It is an error 2427.Pq Er EINVAL 2428to attempt to delete 2429.Sy SIGKILL . 2430.Ss PCSHOLD 2431Set the set of held signals for the specific or representative lwp (signals 2432whose delivery will be blocked if sent to the lwp). 2433The set of signals is specified with a 2434.Vt sigset_t 2435operand. 2436.Sy SIGKILL 2437and 2438.Sy SIGSTOP 2439cannot be held; if specified, they are silently ignored. 2440.Ss PCSFAULT 2441Define a set of hardware faults to be traced in the process. 2442On incurring one of these faults, an lwp stops. 2443The set is defined via the operand 2444.Vt fltset_t 2445structure. 2446Fault names are defined in 2447.In sys/fault.h 2448and include the following. 2449Some of these may not occur on all processors; there may 2450be processor-specific faults in addition to these. 2451.Bl -tag -width "FLTACCESS" -offset indent 2452.It Sy FLTILL 2453illegal instruction 2454.It Sy FLTPRIV 2455privileged instruction 2456.It Sy FLTBPT 2457breakpoint trap 2458.It Sy FLTTRACE 2459trace trap (single-step) 2460.It Sy FLTWATCH 2461watchpoint trap 2462.It Sy FLTACCESS 2463memory access fault (bus error) 2464.It Sy FLTBOUNDS 2465memory bounds violation 2466.It Sy FLTIOVF 2467integer overflow 2468.It Sy FLTIZDIV 2469integer zero divide 2470.It Sy FLTFPE 2471floating-point exception 2472.It Sy FLTSTACK 2473unrecoverable stack fault 2474.It Sy FLTPAGE 2475recoverable page fault 2476.El 2477.Pp 2478When not traced, a fault normally results in the posting of a signal to the lwp 2479that incurred the fault. 2480If an lwp stops on a fault, the signal is posted to 2481the lwp when execution is resumed unless the fault is cleared by 2482.Sy PCCFAULT 2483or by the 2484.Sy PRCFAULT 2485option of 2486.Sy PCRUN . 2487.Sy FLTPAGE 2488is an exception; no signal is posted. 2489The 2490.Sy pr_info 2491field in the 2492.Vt lwpstatus 2493structure identifies the signal to be sent and contains machine-specific 2494information about the fault. 2495.Ss PCCFAULT 2496The current fault, if any, is cleared; the associated signal will not be sent 2497to the specific or representative lwp. 2498.Ss PCSENTRY PCSEXIT 2499These control operations instruct the process's lwps to stop on entry to or 2500exit from specified system calls. 2501The set of system calls to be traced is defined via an operand 2502.Vt sysset_t 2503structure. 2504.Pp 2505When entry to a system call is being traced, an lwp stops after having begun 2506the call to the system but before the system call arguments have been fetched 2507from the lwp. 2508When exit from a system call is being traced, an lwp stops on completion of 2509the system call just prior to checking for signals and returning to user level. 2510At this point, all return values have been stored into the lwp's registers. 2511.Pp 2512If an lwp is stopped on entry to a system call 2513.Pq Sy PR_SYSENTRY 2514or when sleeping in an interruptible system call 2515.Pf ( Sy PR_ASLEEP 2516is set), it may be instructed to go directly to system call exit by specifying 2517the 2518.Sy PRSABORT 2519flag in a 2520.Sy PCRUN 2521control message. 2522Unless exit from the system call is being traced, the lwp returns to user 2523level showing 2524.Er EINTR . 2525.Ss PCWATCH 2526Set or clear a watched area in the controlled process from a 2527.Vt prwatch 2528structure operand: 2529.Bd -literal -offset 2 2530typedef struct prwatch { 2531 uintptr_t pr_vaddr; /* virtual address of watched area */ 2532 size_t pr_size; /* size of watched area in bytes */ 2533 int pr_wflags; /* watch type flags */ 2534} prwatch_t; 2535.Ed 2536.Pp 2537.Sy pr_vaddr 2538specifies the virtual address of an area of memory to be watched 2539in the controlled process. 2540.Sy pr_size 2541specifies the size of the area, in bytes. 2542.Sy pr_wflags 2543specifies the type of memory access to be monitored as a 2544bit-mask of the following flags: 2545.Bl -tag -width "WA_TRAPAFTER" -offset indent 2546.It Sy WA_READ 2547read access 2548.It Sy WA_WRITE 2549write access 2550.It Sy WA_EXEC 2551execution access 2552.It Sy WA_TRAPAFTER 2553trap after the instruction completes 2554.El 2555.Pp 2556If 2557.Sy pr_wflags 2558is non-empty, a watched area is established for the virtual 2559address range specified by 2560.Sy pr_vaddr 2561and 2562.Sy pr_size . 2563If 2564.Sy pr_wflags 2565is empty, any previously-established watched area starting at the specified 2566virtual address is cleared; 2567.Sy pr_size 2568is ignored. 2569.Pp 2570A watchpoint is triggered when an lwp in the traced process makes a memory 2571reference that covers at least one byte of a watched area and the memory 2572reference is as specified in 2573.Sy pr_wflags . 2574When an lwp triggers a watchpoint, it incurs a watchpoint trap. 2575If 2576.Sy FLTWATCH 2577is being traced, the lwp stops; otherwise, it is sent a 2578.Sy SIGTRAP 2579signal; if 2580.Sy SIGTRAP 2581is being traced and is not blocked, the lwp stops. 2582.Pp 2583The watchpoint trap occurs before the instruction completes unless 2584.Sy WA_TRAPAFTER 2585was specified, in which case it occurs after the instruction completes. 2586If it occurs before completion, the memory is not modified. 2587If it occurs after completion, the memory is modified (if the access is a write 2588access). 2589.Pp 2590Physical i/o is an exception for watchpoint traps. 2591In this instance, there is no guarantee that memory before the watched area 2592has already been modified (or in the case of 2593.Sy WA_TRAPAFTER , 2594that the memory following the watched area 2595has not been modified) when the watchpoint trap occurs and the lwp stops. 2596.Pp 2597.Sy pr_info 2598in the 2599.Vt lwpstatus 2600structure contains information pertinent to the watchpoint trap. 2601In particular, the 2602.Sy si_addr 2603field contains the 2604virtual address of the memory reference that triggered the watchpoint, and the 2605.Sy si_code 2606field contains one of 2607.Sy TRAP_RWATCH , 2608.Sy TRAP_WWATCH , 2609or 2610.Sy TRAP_XWATCH , 2611indicating read, write, or execute access, respectively. 2612The 2613.Sy si_trapafter 2614field is zero unless 2615.Sy WA_TRAPAFTER 2616is in effect for this watched area; non-zero indicates that the current 2617instruction is not the instruction that incurred the watchpoint trap. 2618The 2619.Sy si_pc 2620field contains the virtual address of the instruction that incurred the trap. 2621.Pp 2622A watchpoint trap may be triggered while executing a system call that makes 2623reference to the traced process's memory. 2624The lwp that is executing the system call incurs the watchpoint trap while 2625still in the system call. 2626If it stops as a result, the 2627.Vt lwpstatus 2628structure contains the system call number and its arguments. 2629If the lwp does not stop, or if it is set running again without 2630clearing the signal or fault, the system call fails with 2631.Er EFAULT . 2632If 2633.Sy WA_TRAPAFTER 2634was specified, the memory reference will have completed and 2635the memory will have been modified (if the access was a write access) when the 2636watchpoint trap occurs. 2637.Pp 2638If more than one of 2639.Sy WA_READ , 2640.Sy WA_WRITE , 2641and 2642.Sy WA_EXEC 2643is specified for a watched area, and a single instruction incurs more than one 2644of the specified types, only one is reported when the watchpoint trap occurs. 2645The precedence is 2646.Sy WA_EXEC , 2647.Sy WA_READ , 2648.Sy WA_WRITE 2649.Pf ( Sy WA_EXEC 2650and 2651.Sy WA_READ 2652take precedence over 2653.Sy WA_WRITE ) , 2654unless 2655.Sy WA_TRAPAFTER 2656was specified, in which case it is 2657.Sy WA_WRITE , 2658.Sy WA_READ , 2659.Sy WA_EXEC 2660.Pf ( Sy WA_WRITE 2661takes precedence). 2662.Pp 2663.Sy PCWATCH 2664fails with 2665.Er EINVAL 2666if an attempt is made to specify overlapping watched areas or if 2667.Sy pr_wflags 2668contains flags other than those specified above. 2669It fails with 2670.Er ENOMEM 2671if an attempt is made to establish more watched areas than the system can 2672support (the system can support thousands). 2673.Pp 2674The child of a 2675.Xr vfork 2 2676borrows the parent's address space. 2677When a 2678.Xr vfork 2 2679is executed by a traced process, all watched areas established 2680for the parent are suspended until the child terminates or performs an 2681.Xr exec 2 . 2682Any watched areas established independently in the child are 2683cancelled when the parent resumes after the child's termination or 2684.Xr exec 2 . 2685.Sy PCWATCH 2686fails with 2687.Er EBUSY 2688if applied to the parent of a 2689.Xr vfork 2 2690before the child has terminated or performed an 2691.Xr exec 2 . 2692The 2693.Sy PR_VFORKP 2694flag is set in the 2695.Sy pstatus 2696structure for such a parent process. 2697.Pp 2698Certain accesses of the traced process's address space by the operating system 2699are immune to watchpoints. 2700The initial construction of a signal stack frame when a signal is delivered to 2701an lwp will not trigger a watchpoint trap even if the new frame covers watched 2702areas of the stack. 2703Once the signal handler is entered, watchpoint traps occur normally. 2704On SPARC based machines, register window overflow and underflow will not 2705trigger watchpoint traps, even if the register window save areas cover watched 2706areas of the stack. 2707.Pp 2708Watched areas are not inherited by child processes, even if the traced 2709process's inherit-on-fork mode, 2710.Sy PR_FORK , 2711is set (see 2712.Sy PCSET , 2713below). 2714All watched areas are cancelled when the traced process performs a successful 2715.Xr exec 2 . 2716.Ss PCSET PCUNSET 2717.Sy PCSET 2718sets one or more modes of operation for the traced process. 2719.Sy PCUNSET 2720unsets these modes. 2721The modes to be set or unset are specified by flags in an operand 2722.Sy long 2723in the control message: 2724.Bl -tag -offset left -width "PR_MSFORK" 2725.It Sy PR_FORK 2726(inherit-on-fork): When set, the process's tracing flags and its 2727inherit-on-fork mode are inherited by the child of a 2728.Xr fork 2 , 2729.Xr fork1 2 , 2730or 2731.Xr vfork 2 . 2732When unset, child processes start with all tracing flags cleared. 2733.It Sy PR_RLC 2734(run-on-last-close): When set and the last writable 2735.Pa /proc 2736file descriptor referring to the traced process or any of its lwps is closed, 2737all of the process's tracing flags and watched areas are cleared, any 2738outstanding stop directives are canceled, and if any lwps are stopped on 2739events of interest, they are set running as though 2740.Sy PCRUN 2741had been applied to them. 2742When unset, the process's tracing flags and watched areas are retained and 2743lwps are not set running on last close. 2744.It Sy PR_KLC 2745(kill-on-last-close): When set and the last writable 2746.Pa /proc 2747file descriptor referring to the traced process or any of its lwps is closed, 2748the process is terminated with 2749.Sy SIGKILL . 2750.It Sy PR_ASYNC 2751(asynchronous-stop): When set, a stop on an event of interest by one lwp does 2752not directly affect any other lwp in the process. 2753When unset and an lwp stops on an event of interest other than 2754.Sy PR_REQUESTED , 2755all other lwps in the process are directed to stop. 2756.It Sy PR_MSACCT 2757(microstate accounting): Microstate accounting is now continuously enabled. 2758This flag is deprecated and no longer has any effect upon microstate 2759accounting. 2760Applications may toggle this flag; however, microstate accounting 2761will remain enabled regardless. 2762.It Sy PR_MSFORK 2763(inherit microstate accounting): All processes now inherit microstate 2764accounting, as it is continuously enabled. 2765This flag has been deprecated and its use no longer has any effect upon the 2766behavior of microstate accounting. 2767.It Sy PR_BPTADJ 2768(breakpoint trap pc adjustment): On x86-based machines, a breakpoint trap 2769leaves the program counter (the 2770.Sy EIP ) 2771referring to the breakpointed instruction plus one byte. 2772When 2773.Sy PR_BPTADJ 2774is set, the system will adjust the program counter back to the location of the 2775breakpointed instruction when the lwp stops on a breakpoint. 2776This flag has no effect on SPARC based machines, where breakpoint traps leave 2777the program counter referring to the breakpointed instruction. 2778.It Sy PR_PTRACE 2779(ptrace-compatibility): When set, a stop on an event of interest by the traced 2780process is reported to the parent of the traced process by 2781.Xr wait 3C , 2782.Sy SIGTRAP 2783is sent to the traced process when it executes a successful 2784.Xr exec 2 , 2785setuid/setgid flags are not honored for execs performed by the 2786traced process, any exec of an object file that the traced process cannot read 2787fails, and the process dies when its parent dies. 2788This mode is deprecated; it is provided only to allow 2789.Xr ptrace 3C 2790to be implemented as a library function using 2791.Pa /proc . 2792.El 2793.Pp 2794It is an error 2795.Pq Er EINVAL 2796to specify flags other than those described above 2797or to apply these operations to a system process. 2798The current modes are reported in the 2799.Sy pr_flags 2800field of 2801.Pa /proc/ Ns Em pid Ns Pa /status 2802and 2803.Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwp Ns Pa /lwpstatus . 2804.Ss PCSREG 2805Set the general registers for the specific or representative lwp according to 2806the operand 2807.Vt prgregset_t 2808structure. 2809.Pp 2810On SPARC based systems, only the condition-code bits of the processor-status 2811register (R_PSR) of SPARC V8 (32-bit) processes can be modified by 2812.Sy PCSREG . 2813Other privileged registers cannot be modified at all. 2814.Pp 2815On x86-based systems, only certain bits of the flags register (EFL) can be 2816modified by 2817.Sy PCSREG : 2818these include the condition codes, direction-bit, and overflow-bit. 2819.Pp 2820.Sy PCSREG 2821fails with 2822.Er EBUSY 2823if the lwp is not stopped on an event of interest. 2824.Ss PCSVADDR 2825Set the address at which execution will resume for the specific or 2826representative lwp from the operand 2827.Vt long . 2828On SPARC based systems, both %pc and %npc are set, with %npc set to the 2829instruction following the virtual address. 2830On x86-based systems, only %eip is set. 2831.Sy PCSVADDR 2832fails with 2833.Er EBUSY 2834if the lwp is not stopped on an event of interest. 2835.Ss PCSFPREG 2836Set the floating-point registers for the specific or representative lwp 2837according to the operand 2838.Vt prfpregset_t 2839structure. 2840An error 2841.Pq Er EINVAL 2842is returned if the system does not support floating-point operations (no 2843floating-point hardware and the system does not emulate floating-point machine 2844instructions). 2845.Sy PCSFPREG 2846fails with 2847.Er EBUSY 2848if the lwp is not stopped on an event of interest. 2849.Ss PCSXREG 2850Set the extra state registers for the specific or representative lwp according 2851to the architecture-dependent operand 2852.Vt prxregset_t 2853structure. 2854An error 2855.Pq Er EINVAL 2856is returned if the system does not support extra state registers or the register 2857state is invalid. 2858.Sy PCSXREG 2859fails with 2860.Er EBUSY 2861if the lwp is not stopped on an event of interest. 2862.Ss PCSASRS 2863Set the ancillary state registers for the specific or representative lwp 2864according to the SPARC V9 platform-dependent operand 2865.Vt asrset_t 2866structure. 2867An error 2868.Pq Er EINVAL 2869is returned if either the target process or the 2870controlling process is not a 64-bit SPARC V9 process. 2871Most of the ancillary state registers are privileged registers that cannot be 2872modified. 2873Only those that can be modified are set; all others are silently ignored. 2874.Sy PCSASRS 2875fails with 2876.Er EBUSY 2877if the lwp is not stopped on an event of interest. 2878.Ss PCAGENT 2879Create an agent lwp in the controlled process with register values from the 2880operand 2881.Vt prgregset_t 2882structure (see 2883.Sy PCSREG , 2884above). 2885The agent lwp is created in the stopped state showing 2886.Sy PR_REQUESTED 2887and with its held signal set (the signal mask) having all signals except 2888.Sy SIGKILL 2889and 2890.Sy SIGSTOP 2891blocked. 2892.Pp 2893The 2894.Sy PCAGENT 2895operation fails with 2896.Er EBUSY 2897unless the process is fully stopped via 2898.Pa /proc , 2899that is, unless all of the lwps in the process are 2900stopped either on events of interest or on 2901.Sy PR_SUSPENDED , 2902or are stopped on 2903.Sy PR_JOBCONTROL 2904and have been directed to stop via 2905.Sy PCDSTOP . 2906It fails with 2907.Er EBUSY 2908if an agent lwp already exists. 2909It fails with 2910.Er ENOMEM 2911if system resources for creating new lwps have been exhausted. 2912.Pp 2913Any 2914.Sy PCRUN 2915operation applied to the process control file or to the control 2916file of an lwp other than the agent lwp fails with 2917.Er EBUSY 2918as long as the agent lwp exists. 2919The agent lwp must be caused to terminate by executing the 2920.Sy SYS_lwp_exit 2921system call trap before the process can be restarted. 2922.Pp 2923Once the agent lwp is created, its lwp-ID can be found by reading the process 2924status file. 2925To facilitate opening the agent lwp's control and status files, 2926the directory name 2927.Pa /proc/ Ns Em pid Ns Pa /lwp/agent 2928is accepted for lookup operations as an invisible alias for 2929.Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid , 2930.Em lwpid 2931being the lwp-ID of the agent lwp (invisible in the sense that the name 2932.Dq agent 2933does not appear in a directory listing of 2934.Pa /proc/ Ns Em pid Ns Pa /lwp 2935obtained from 2936.Xr ls 1 , 2937.Xr getdents 2 , 2938or 2939.Xr readdir 3C . 2940.Pp 2941The purpose of the agent lwp is to perform operations in the controlled process 2942on behalf of the controlling process: to gather information not directly 2943available via 2944.Pa /proc 2945files, or in general to make the process change state 2946in ways not directly available via 2947.Pa /proc 2948control operations. 2949To make use of an agent lwp, the controlling process must be capable of making 2950it execute system calls (specifically, the 2951.Sy SYS_lwp_exit 2952system call trap). 2953The register values given to the agent lwp on creation are typically the 2954registers of the representative lwp, so that the agent lwp can use its stack. 2955.Pp 2956If the controlling process neglects to force the agent lwp to execute the 2957.Sy SYS_lwp_exit 2958system call (due to either logic error or fatal failure on 2959the part of the controlling process), the agent lwp will remain in the target 2960process. 2961For purposes of being able to debug these otherwise rogue agents, 2962information as to the creator of the agent lwp is reflected in that lwp's 2963.Pa spymaster 2964file in 2965.Pa /proc . 2966Should the target process generate a core 2967dump with the agent lwp in place, this information will be available via the 2968.Sy NT_SPYMASTER 2969note in the core file (see 2970.Xr core 5 ) . 2971.Pp 2972The agent lwp is not allowed to execute any variation of the 2973.Sy SYS_fork 2974or 2975.Sy SYS_exec 2976system call traps. 2977Attempts to do so yield 2978.Er ENOTSUP 2979to the agent lwp. 2980.Pp 2981Symbolic constants for system call trap numbers like 2982.Sy SYS_lwp_exit 2983and 2984.Sy SYS_lwp_create 2985can be found in the header file 2986.In sys/syscall.h . 2987.Ss PCREAD PCWRITE 2988Read or write the target process's address space via a 2989.Vt priovec 2990structure operand: 2991.Bd -literal -offset 2 2992typedef struct priovec { 2993 void *pio_base; /* buffer in controlling process */ 2994 size_t pio_len; /* size of read/write request in bytes */ 2995 off_t pio_offset; /* virtual address in target process */ 2996} priovec_t; 2997.Ed 2998.Pp 2999These operations have the same effect as 3000.Xr pread 2 3001and 3002.Xr pwrite 2 , 3003respectively, of the target process's address space file. 3004The difference is that more than one 3005.Sy PCREAD 3006or 3007.Sy PCWRITE 3008control operation can be 3009written to the control file at once, and they can be interspersed with other 3010control operations in a single write to the control file. 3011This is useful, for example, when planting many breakpoint instructions in 3012the process's address space, or when stepping over a breakpointed instruction. 3013Unlike 3014.Xr pread 2 3015and 3016.Xr pwrite 2 , 3017no provision is made for partial reads or writes; if the 3018operation cannot be performed completely, it fails with 3019.Er EIO . 3020.Ss PCNICE 3021The traced process's 3022.Xr nice 2 3023value is incremented by the amount in the 3024operand 3025.Vt long . 3026Only a process with the 3027.Brq Sy PRIV_PROC_PRIOCNTL 3028privilege asserted in its effective set can better a process's priority in this 3029way, but any user may lower the priority. 3030This operation is not meaningful for all scheduling classes. 3031.Ss PCSCRED 3032Set the target process credentials to the values contained in the 3033.Vt prcred_t 3034structure operand (see 3035.Pa /proc/ Ns Em pid Ns Pa /cred ) . 3036The 3037effective, real, and saved user-IDs and group-IDs of the target process are 3038set. 3039The target process's supplementary groups are not changed; the 3040.Sy pr_ngroups 3041and 3042.Sy pr_groups 3043members of the structure operand are ignored. 3044Only the privileged processes can perform this operation; for all 3045others it fails with 3046.Er EPERM . 3047.Ss PCSCREDX 3048Operates like 3049.Sy PCSCRED 3050but also sets the supplementary groups; the length 3051of the data written with this control operation should be "sizeof 3052.Pq Vt prcred_t 3053+ sizeof 3054.Pq Vt gid_t 3055* (#groups - 1)". 3056.Ss PCSPRIV 3057Set the target process privilege to the values contained in the 3058.Vt prpriv_t 3059operand (see 3060.Pa /proc/pid/priv ) . 3061The effective, permitted, inheritable, and 3062limit sets are all changed. 3063Privilege flags can also be set. 3064The process is made privilege aware unless it can relinquish privilege awareness. 3065See 3066.Xr privileges 7 . 3067.Pp 3068The limit set of the target process cannot be grown. 3069The other privilege sets must be subsets of the intersection of the effective set 3070of the calling process with the new limit set of the target process or subsets of 3071the original values of the sets in the target process. 3072.Pp 3073If any of the above restrictions are not met, 3074.Er EPERM 3075is returned. 3076If the structure written is improperly formatted, 3077.Er EINVAL 3078is returned. 3079.Sh PROGRAMMING NOTES 3080For security reasons, except for the 3081.Sy psinfo , 3082.Sy usage , 3083.Sy lpsinfo , 3084.Sy lusage , 3085.Sy lwpsinfo , 3086and 3087.Sy lwpusage 3088files, which are world-readable, and except for privileged processes, an open 3089of a 3090.Pa /proc 3091file fails unless both the user-ID and group-ID of the caller match those of 3092the traced process and the process's object file is readable by the caller. 3093The effective set of the caller is a superset of both the inheritable and the 3094permitted set of the target process. 3095The limit set of the caller is a superset of the limit set of the target 3096process. 3097Except for the world-readable files just mentioned, files corresponding to 3098setuid and setgid processes can be opened only by the appropriately privileged 3099process. 3100.Pp 3101A process that is missing the basic privilege 3102.Brq Sy PRIV_PROC_INFO 3103cannot see any processes under 3104.Pa /proc 3105that it cannot send a signal to. 3106.Pp 3107A process that has 3108.Brq Sy PRIV_PROC_OWNER 3109asserted in its effective set can open any file for reading. 3110To manipulate or control a process, the controlling process must have at least 3111as many privileges in its effective set as the target process has in its 3112effective, inheritable, and permitted sets. 3113The limit set of the controlling process must be a superset of the limit set 3114of the target process. 3115Additional restrictions apply if any of the uids of the target process are 0. 3116See 3117.Xr privileges 7 . 3118.Pp 3119Even if held by a privileged process, an open process or lwp file descriptor 3120(other than file descriptors for the world-readable files) becomes invalid if 3121the traced process performs an 3122.Xr exec 2 3123of a setuid/setgid object file or 3124an object file that the traced process cannot read. 3125Any operation performed on an invalid file descriptor, except 3126.Xr close 2 , 3127fails with 3128.Er EAGAIN . 3129In this situation, if any tracing flags are set and the process or any lwp 3130file descriptor is open for writing, the process will have been directed to 3131stop and its run-on-last-close flag will have been set (see 3132.Sx PCSET ) . 3133This enables a controlling process (if it has permission) to reopen the 3134.Pa /proc 3135files to get new valid file descriptors, close the invalid file descriptors, 3136unset the run-on-last-close flag (if desired), and proceed. 3137Just closing the invalid file descriptors causes the traced process to resume 3138execution with all tracing flags cleared. 3139Any process not currently open for writing via 3140.Pa /proc , 3141but that has left-over tracing flags from a previous open, and that executes 3142a setuid/setgid or unreadable object file, will not be stopped but will have 3143all its tracing flags cleared. 3144.Pp 3145To wait for one or more of a set of processes or lwps to stop or terminate, 3146.Pa /proc 3147file descriptors (other than those obtained by opening the 3148.Pa cwd 3149or 3150.Pa root 3151directories or by opening files in the 3152.Pa fd 3153or 3154.Pa object 3155directories) can be used in a 3156.Xr poll 2 3157system call. 3158When requested and returned, either of the polling events 3159.Sy POLLPRI 3160or 3161.Sy POLLWRNORM 3162indicates that the process or lwp stopped on an event of 3163interest. 3164Although they cannot be requested, the polling events 3165.Sy POLLHUP , 3166.Sy POLLERR , 3167and 3168.Sy POLLNVAL 3169may be returned. 3170.Sy POLLHUP 3171indicates that the process or lwp has terminated. 3172.Sy POLLERR 3173indicates that the file descriptor has become invalid. 3174.Sy POLLNVAL 3175is returned immediately if 3176.Sy POLLPRI 3177or 3178.Sy POLLWRNORM 3179is requested on a file descriptor referring to a system process (see 3180.Sx PCSTOP ) . 3181The requested events may be empty to wait simply for termination. 3182.Sh FILES 3183.Bl -tag -compact -width Ds 3184.It Pa /proc 3185directory (list of processes) 3186.It Pa /proc/ Ns Em pid 3187specific process directory 3188.It Pa /proc/self 3189alias for a process's own directory 3190.It Pa /proc/ Ns Em pid Ns Pa /as 3191address space file 3192.It Pa /proc/ Ns Em pid Ns Pa /ctl 3193process control file 3194.It Pa /proc/ Ns Em pid Ns Pa /status 3195process status 3196.It Pa /proc/ Ns Em pid Ns Pa /lstatus 3197array of lwp status structs 3198.It Pa /proc/ Ns Em pid Ns Pa /psinfo 3199process 3200.Xr ps 1 3201info 3202.It Pa /proc/ Ns Em pid Ns Pa /lpsinfo 3203array of lwp 3204.Xr ps 1 3205info structs 3206.It Pa /proc/ Ns Em pid Ns Pa /map 3207address space map 3208.It Pa /proc/ Ns Em pid Ns Pa /xmap 3209extended address space map 3210.It Pa /proc/ Ns Em pid Ns Pa /rmap 3211reserved address map 3212.It Pa /proc/ Ns Em pid Ns Pa /cred 3213process credentials 3214.It Pa /proc/ Ns Em pid Ns Pa /priv 3215process privileges 3216.It Pa /proc/ Ns Em pid Ns Pa /sigact 3217process signal actions 3218.It Pa /proc/ Ns Em pid Ns Pa /auxv 3219process aux vector 3220.It Pa /proc/ Ns Em pid Ns Pa /ldt 3221process 3222.Sy LDT 3223(x86 only) 3224.It Pa /proc/ Ns Em pid Ns Pa /usage 3225process usage 3226.It Pa /proc/ Ns Em pid Ns Pa /lusage 3227array of lwp usage structs 3228.It Pa /proc/ Ns Em pid Ns Pa /path 3229symbolic links to process open files 3230.It Pa /proc/ Ns Em pid Ns Pa /pagedata 3231process page data 3232.It Pa /proc/ Ns Em pid Ns Pa /watch 3233active watchpoints 3234.It Pa /proc/ Ns Em pid Ns Pa /cwd 3235alias for the current working directory 3236.It Pa /proc/ Ns Em pid Ns Pa /root 3237alias for the root directory 3238.It Pa /proc/ Ns Em pid Ns Pa /fd 3239directory (list of open files) 3240.It Pa /proc/ Ns Em pid Ns Pa /fd/* 3241aliases for process's open files 3242.It Pa /proc/ Ns Em pid Ns Pa /object 3243directory (list of mapped files) 3244.It Pa /proc/ Ns Em pid Ns Pa /object/a.out 3245alias for process's executable file 3246.It Pa /proc/ Ns Em pid Ns Pa /object/* 3247aliases for other mapped files 3248.It Pa /proc/ Ns Em pid Ns Pa /lwp 3249directory (list of lwps) 3250.It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid 3251specific lwp directory 3252.It Pa /proc/ Ns Em pid Ns Pa /lwp/agent 3253alias for the agent lwp directory 3254.It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpctl 3255lwp control file 3256.It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpstatus 3257lwp status 3258.It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpsinfo 3259lwp 3260.Xr ps 1 3261info 3262.It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /lwpusage 3263lwp usage 3264.It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /gwindows 3265register windows (SPARC only) 3266.It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /xregs 3267extra state registers 3268.It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /asrs 3269ancillary state registers (SPARC V9 only) 3270.It Pa /proc/ Ns Em pid Ns Pa /lwp/ Ns Em lwpid Ns Pa /spymaster 3271For an agent LWP, the controlling process 3272.El 3273.Sh DIAGNOSTICS 3274Errors that can occur in addition to the errors normally associated with file 3275system access: 3276.Bl -tag -width "EOVERFLOW" -offset left 3277.It Er E2BIG 3278Data to be returned in a 3279.Xr read 2 3280of the page data file exceeds the size of the read buffer provided by the 3281caller. 3282.It Er EACCES 3283An attempt was made to examine a process that ran under a different uid than 3284the controlling process and 3285.Brq Sy PRIV_PROC_OWNER 3286was not asserted in the effective set. 3287.It Er EAGAIN 3288The traced process has performed an 3289.Xr exec 2 3290of a setuid/setgid object 3291file or of an object file that it cannot read; all further operations on the 3292process or lwp file descriptor (except 3293.Xr close 2 ) 3294elicit this error. 3295.It Er EBUSY 3296.Sy PCSTOP , 3297.Sy PCDSTOP , 3298.Sy PCWSTOP , or 3299.Sy PCTWSTOP 3300was applied to a system process; an exclusive 3301.Xr open 2 3302was attempted on a 3303.Pa /proc 3304file for a process already open for writing; 3305.Sy PCRUN , 3306.Sy PCSREG , 3307.Sy PCSVADDR , 3308.Sy PCSFPREG , 3309or 3310.Sy PCSXREG 3311was applied to a process or 3312lwp not stopped on an event of interest; an attempt was made to mount 3313.Pa /proc 3314when it was already mounted; 3315.Sy PCAGENT 3316was applied to a process 3317that was not fully stopped or that already had an agent lwp. 3318.It Er EINVAL 3319In general, this means that some invalid argument was supplied to a system 3320call. 3321A non-exhaustive list of conditions eliciting this error includes: a 3322control message operation code is undefined; an out-of-range signal number was 3323specified with 3324.Sy PCSSIG , 3325.Sy PCKILL , 3326or 3327.Sy PCUNKILL ; 3328.Sy SIGKILL 3329was specified with 3330.Sy PCUNKILL ; 3331.Sy PCSFPREG 3332was applied on a system that does not support floating-point operations; 3333.Sy PCSXREG 3334was applied on a system that does not support extra state registers. 3335.It Er EINTR 3336A signal was received by the controlling process while waiting for the traced 3337process or lwp to stop via 3338.Sy PCSTOP , 3339.Sy PCWSTOP , 3340or 3341.Sy PCTWSTOP . 3342.It Er EIO 3343A 3344.Xr write 2 3345was attempted at an illegal address in the traced process. 3346.It Er ENOENT 3347The traced process or lwp has terminated after being opened. 3348The basic privilege 3349.Brq Sy PRIV_PROC_INFO 3350is not asserted in the effective set of the calling process and the calling 3351process cannot send a signal to the target process. 3352.It Er ENOMEM 3353The system-imposed limit on the number of page data file descriptors was 3354reached on an open of 3355.Pa /proc/ Ns Em pid Ns Pa /pagedata ; 3356an attempt was made 3357with 3358.Sy PCWATCH 3359to establish more watched areas than the system can support; 3360the 3361.Sy PCAGENT 3362operation was issued when the system was out of resources for 3363creating lwps. 3364.It Er ENOSYS 3365An attempt was made to perform an unsupported operation (such as 3366.Xr creat 2 , 3367.Xr link 2 , 3368or 3369.Xr unlink 2 ) 3370on an entry in 3371.Pa /proc . 3372.It Er EOVERFLOW 3373A 32-bit controlling process attempted to read or write the 3374.Pa as 3375file or attempted to read the 3376.Pa map , 3377.Pa rmap , 3378or 3379.Pa pagedata 3380file of a 64-bit target process. 3381A 32-bit controlling process attempted to apply one of the 3382control operations 3383.Sy PCSREG , 3384.Sy PCSXREG , 3385.Sy PCSVADDR , 3386.Sy PCWATCH , 3387.Sy PCAGENT , 3388.Sy PCREAD , 3389.Sy PCWRITE 3390to a 64-bit target process. 3391.It Er EPERM 3392The process that issued the 3393.Sy PCSCRED 3394or 3395.Sy PCSCREDX 3396operation did not have the 3397.Brq Sy PRIV_PROC_SETID 3398privilege asserted in its effective set, or 3399the process that issued the 3400.Sy PCNICE 3401operation did not have the 3402.Brq Sy PRIV_PROC_PRIOCNTL 3403in its effective set. 3404.Pp 3405An attempt was made to control a process of which the E, P, and I privilege 3406sets were not a subset of the effective set of the controlling process or the 3407limit set of the controlling process is not a superset of limit set of the 3408controlled process. 3409.Pp 3410Any of the uids of the target process are 3411.Sy 0 3412or an attempt was made to change any of the uids to 3413.Sy 0 3414using 3415.Sy PCSCRED 3416and the security policy imposed additional restrictions. 3417See 3418.Xr privileges 7 . 3419.El 3420.Sh SEE ALSO 3421.Xr ls 1 , 3422.Xr ps 1 , 3423.Xr alarm 2 , 3424.Xr brk 2 , 3425.Xr chdir 2 , 3426.Xr chroot 2 , 3427.Xr close 2 , 3428.Xr creat 2 , 3429.Xr dup 2 , 3430.Xr exec 2 , 3431.Xr fcntl 2 , 3432.Xr fork 2 , 3433.Xr fork1 2 , 3434.Xr fstat 2 , 3435.Xr getdents 2 , 3436.Xr getustack 2 , 3437.Xr kill 2 , 3438.Xr lseek 2 , 3439.Xr mmap 2 , 3440.Xr nice 2 , 3441.Xr open 2 , 3442.Xr poll 2 , 3443.Xr pread 2 , 3444.Xr pwrite 2 , 3445.Xr read 2 , 3446.Xr readlink 2 , 3447.Xr readv 2 , 3448.Xr shmget 2 , 3449.Xr sigaction 2 , 3450.Xr sigaltstack 2 , 3451.Xr vfork 2 , 3452.Xr write 2 , 3453.Xr writev 2 , 3454.Xr _stack_grow 3C , 3455.Xr pthread_create 3C , 3456.Xr pthread_join 3C , 3457.Xr ptrace 3C , 3458.Xr readdir 3C , 3459.Xr thr_create 3C , 3460.Xr thr_join 3C , 3461.Xr wait 3C , 3462.Xr siginfo.h 3HEAD , 3463.Xr signal.h 3HEAD , 3464.Xr types32.h 3HEAD , 3465.Xr ucontext.h 3HEAD , 3466.Xr contract 5 , 3467.Xr core 5 , 3468.Xr process 5 , 3469.Xr lfcompile 7 , 3470.Xr privileges 7 , 3471.Xr security-flags 7 , 3472.Xr chroot 8 3473.Sh NOTES 3474Descriptions of structures in this document include only interesting structure 3475elements, not filler and padding fields, and may show elements out of order for 3476descriptive clarity. 3477The actual structure definitions are contained in 3478.In procfs.h . 3479.Sh BUGS 3480Because the old 3481.Xr ioctl 2 Ns -based 3482version of 3483.Pa /proc 3484is currently supported for binary compatibility with old applications, the 3485top-level directory for a process, 3486.Pa /proc/ Ns Em pid , 3487is not world-readable, but it is world-searchable. 3488Thus, anyone can open 3489.Pa /proc/ Ns Em pid Ns Pa /psinfo 3490even though 3491.Xr ls 1 3492applied to 3493.Pa /proc/ Ns Em pid 3494will fail for anyone but the owner or an appropriately privileged process. 3495Support for the old 3496.Xr ioctl 2 Ns -based 3497version of 3498.Pa /proc 3499will be dropped in a future release, at which time the top-level directory for 3500a process will be made world-readable. 3501.Pp 3502On SPARC based machines, the types 3503.Sy gregset_t 3504and 3505.Sy fpregset_t 3506defined in 3507.In sys/regset.h 3508are similar to but not the same as the types 3509.Sy prgregset_t 3510and 3511.Sy prfpregset_t 3512defined in 3513.In procfs.h . 3514