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