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