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