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