1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
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
|
