6955 libproc should be documented and shipped

6956 libproc cannot leave free() to callers
Reviewed by: Ryan Zezeski <ryan@zinascii.com>
Reviewed by: Cody Mello <cody.mello@joyent.com>
Reviewed by: Joshua M. Clulow <josh@sysmgr.org>
Approved by: Richard Lowe <richlowe@richlowe.net>

1 files changed, 103 insertions, 0 deletions

diff --git a/usr/src/man/man3proc/Pfault.3proc b/usr/src/man/man3proc/Pfault.3proc
new file mode 100644
index 0000000000..61c6454f02
--- /dev/null
+++ b/usr/src/man/man3proc/Pfault.3proc
@@ -0,0 +1,103 @@
+.\"
+.\" 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