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