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