usr/src/man/man3proc/Pfault.3proc

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