PROC_INITSTDIO(3PROC) Process Control Library Functions

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

Uncommitted

MT-LEVEL
Unsafe

SEE ALSO

libproc(3LIB), Pgrab(3PROC), Prelease(3PROC)

illumos November 27, 2023 illumos