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