PROC_INITSTDIO(3PROC) Process Control Library Functions PROC_INITSTDIO(3PROC)
NAME
proc_initstdio,
proc_flushstdio,
proc_finistdio - stdio buffering functions
LIBRARY
Process Control Library (libproc, -lproc)
SYNOPSIS
#include <libproc.h> int proc_initstdio(
void);
int proc_flushstdio(
void);
int proc_finistdio(
void);
DESCRIPTION
The
proc_initstdio(),
proc_flushstdio(), and
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.
Consider, for example, the following invocation: 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 pfiles program cannot release the
xterm process because it still has pending I/O, but the I/O cannot be
drained due to the same hold.
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.
The
proc_initstdio() function initializes a new standard out and standard
error file descriptors and retains the originals.
The
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.
The
proc_finistdio() flushes any outstanding I/O and restores the original
standard output and standard error.
Once called, the
proc_initstdio() function must not be called again until a
successful call to
proc_finistdio().
RETURN VALUES
Upon successful completion, the
proc_initstdio(),
proc_flushstdio(), and
proc_finistdio() functions all return
0. Otherwise,
-1 is returned to
indicate failure.
INTERFACE STABILITY
UncommittedMT-LEVEL UnsafeSEE ALSO
libproc(3LIB),
Pgrab(3PROC),
Prelease(3PROC)illumos November 27, 2023 illumos