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