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