1 files changed, 107 insertions, 0 deletions
diff --git a/usr/src/man/man3proc/proc_initstdio.3proc b/usr/src/man/man3proc/proc_initstdio.3proc
new file mode 100644
index 0000000000..315f717f81
--- /dev/null
+++ b/usr/src/man/man3proc/proc_initstdio.3proc
@@ -0,0 +1,107 @@
+.\"
+.\" 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 PROC_INITSTDIO 3PROC
+.Os
+.Sh NAME
+.Nm proc_initstdio ,
+.Nm proc_flushstdio ,
+.Nm proc_finistdio
+.Nd stdio buffering functions
+.Sh SYNOPSIS
+.Lb libproc
+.In libproc.h
+.Ft int
+.Fo proc_initstdio
+.Fa void
+.Fc
+.Ft int
+.Fo proc_flushstdio
+.Fa void
+.Fc
+.Ft int
+.Fo proc_finistdio
+.Fa void
+.Fc
+.Sh DESCRIPTION
+The
+.Fn proc_initstdio ,
+.Fn proc_flushstdio ,
+and
+.Fn proc_finistdio
+functions are utilities provided to aid with the possibility of deadlock
+while doing I/O operations. If a process is trying to do I/O, but
+holding the process handle that would consume that I/O, then eventually
+the program holding the process handle will block as none of its I/O has
+been drained. However, because it is holding a process handle to that
+process, it will never be drained.
+.Pp
+Consider, for example, the following invocation:
+.Li pfiles `pgrep xterm`
+where the command was launched from a shell on an xterm. Because the
+xterm is stopped, it will not be able to write out any of the standard
+out that gets passed to it, leading to a deadlock. The
+.Li pfiles
+program cannot release the
+.Li xterm
+process because it still has pending I/O, but the I/O cannot be drained
+due to the same hold.
+.Pp
+To address this, these functions duplicate the standard output and
+standard error of the process to temporary files and then flushes it out
+to the original file descriptors and streams later. When finished, the
+original file descriptors are restored as standard out and standard
+error.
+.Pp
+The
+.Fn proc_initstdio
+function initializes a new standard out and standard error file
+descriptors and retains the originals.
+.Pp
+The
+.Fn proc_flushstdio
+functions flushes all of the cached data from the temporary standard out
+and standard error back to the underlying ones. This function should
+only be called after all process handles have been released. For
+example, if iterating on multiple processes, calling this after handling
+each one is safe.
+.Pp
+The
+.Fn proc_finistdio
+flushes any outstanding I/O and restores the original standard output
+and standard error.
+.Pp
+Once called, the
+.Fn proc_initstdio
+function must not be called again until a successful call to
+.Fn proc_finistdio .
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn proc_initstdio ,
+.Fn proc_flushstdio ,
+and
+.Fn proc_finistdio
+functions all return
+.Sy 0 .
+Otherwise,
+.Sy -1
+is returned to indicate failure.
+.Sh INTERFACE STABILITY
+.Sy Uncommitted
+.Sh MT-LEVEL
+.Sy Unsafe
+.Sh SEE ALSO
+.Xr libproc 3LIB ,
+.Xr Pgrab 3PROC ,
+.Xr Prelease 3PROC