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