1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
|
.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source. A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PFAULT 3PROC
.Os
.Sh NAME
.Nm Pfault
.Nd enable and disable the tracing of faults
.Sh LIBRARY
.Lb libproc
.Sh SYNOPSIS
.In libproc.h
.Ft "int"
.Fo Pfault
.Fa "struct ps_prochandle *P"
.Fa "int which"
.Fa "int stop"
.Fc
.Sh DESCRIPTION
The
.Fn Pfault
function controls what the process
.Fa P
should do on faults.
.Pp
A fault is a hardware event that occurs in the context of a running
process and thread.
A hardware fault may occur because an illegal instruction was executed,
a breakpoint or watchpoint was encountered, or an arithmetic exception occurred,
among others.
The full list of faults is available in both
.Xr proc 5
and
.In sys/fault.h .
.Pp
For each hardware fault, a process may be configured to stop the thread
that encountered it when it occurs.
The value of the
.Fa stop
parameter controls whether or not the listed fault in
.Fa which
will cause the thread to trap.
A value of 1 indicates the thread should stop; a value of 0 indicates it should
not.
.Pp
The value of
.Fa which
indicates which hardware fault the change applies to.
However, if the value of
.Fa which
is zero, then it applies to all faults.
.Pp
The
.Fn Pfault
function only applies to actively running processes.
It does not function on handles that refer to core files, zombie processes, or
ELF objects.
.Sh RETURN VALUES
Upon successful completion, the
.Fn Pfault
function returns the old disposition of the fault --
.Sy 0
if it was not set to stop and
.Sy 1
if it was --
and the fault state is updated.
Otherwise,
.Sy -1
is returned,
.Dv errno
is updated with the error that occurred, and the fault state is not
updated.
.Sh ERRORS
The
.Fn Pfault
function will fail if:
.Bl -tag -width Er
.It Er EINVAL
The value of
.Fa which
is invalid, e.g. it is less than zero or greater than the largest defined
fault.
.It Er ENOENT
The handle
.Fa P
refers to a process that is a zombie, a core file, or a file.
.El
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr libproc 3LIB ,
.Xr proc 5
|
