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 LIBRARY 21.Lb libproc 22.Sh SYNOPSIS 23.In libproc.h 24.Ft "int" 25.Fo Pfault 26.Fa "struct ps_prochandle *P" 27.Fa "int which" 28.Fa "int stop" 29.Fc 30.Sh DESCRIPTION 31The 32.Fn Pfault 33function controls what the process 34.Fa P 35should do on faults. 36.Pp 37A fault is a hardware event that occurs in the context of a running 38process and thread. 39A hardware fault may occur because an illegal instruction was executed, 40a breakpoint or watchpoint was encountered, or an arithmetic exception occurred, 41among others. 42The full list of faults is available in both 43.Xr proc 4 44and 45.In sys/fault.h . 46.Pp 47For each hardware fault, a process may be configured to stop the thread 48that encountered it when it occurs. 49The value of the 50.Fa stop 51parameter controls whether or not the listed fault in 52.Fa which 53will cause the thread to trap. 54A value of 1 indicates the thread should stop; a value of 0 indicates it should 55not. 56.Pp 57The value of 58.Fa which 59indicates which hardware fault the change applies to. 60However, if the value of 61.Fa which 62is zero, then it applies to all faults. 63.Pp 64The 65.Fn Pfault 66function only applies to actively running processes. 67It does not function on handles that refer to core files, zombie processes, or 68ELF objects. 69.Sh RETURN VALUES 70Upon successful completion, the 71.Fn Pfault 72function returns the old disposition of the fault -- 73.Sy 0 74if it was not set to stop and 75.Sy 1 76if it was -- 77and the fault state is updated. 78Otherwise, 79.Sy -1 80is returned, 81.Dv errno 82is updated with the error that occurred, and the fault state is not 83updated. 84.Sh ERRORS 85The 86.Fn Pfault 87function will fail if: 88.Bl -tag -width Er 89.It Er EINVAL 90The value of 91.Fa which 92is invalid, e.g. it is less than zero or greater than the largest defined 93fault. 94.It Er ENOENT 95The handle 96.Fa P 97refers to a process that is a zombie, a core file, or a file. 98.El 99.Sh INTERFACE STABILITY 100.Sy Uncommitted 101.Sh MT-LEVEL 102See 103.Sy LOCKING 104in 105.Xr libproc 3LIB . 106.Sh SEE ALSO 107.Xr libproc 3LIB , 108.Xr proc 4 109