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