| .\" |
| .\" 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 SYNOPSIS |
| .Lb libproc |
| .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 4 |
| 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 4 |