1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2015 Joyent, Inc.
13.\"
14.Dd November 27, 2023
15.Dt PROC_INITSTDIO 3PROC
16.Os
17.Sh NAME
18.Nm proc_initstdio ,
19.Nm proc_flushstdio ,
20.Nm proc_finistdio
21.Nd stdio buffering functions
22.Sh LIBRARY
23.Lb libproc
24.Sh SYNOPSIS
25.In libproc.h
26.Ft int
27.Fo proc_initstdio
28.Fa void
29.Fc
30.Ft int
31.Fo proc_flushstdio
32.Fa void
33.Fc
34.Ft int
35.Fo proc_finistdio
36.Fa void
37.Fc
38.Sh DESCRIPTION
39The
40.Fn proc_initstdio ,
41.Fn proc_flushstdio ,
42and
43.Fn proc_finistdio
44functions are utilities provided to aid with the possibility of deadlock
45while doing I/O operations.
46If a process is trying to do I/O, but holding the process handle that would
47consume that I/O, then eventually the program holding the process handle will
48block as none of its I/O has been drained.
49However, because it is holding a process handle to that process, it will never
50be drained.
51.Pp
52Consider, for example, the following invocation:
53.Li pfiles `pgrep xterm`
54where the command was launched from a shell on an xterm.
55Because the xterm is stopped, it will not be able to write out any of the
56standard out that gets passed to it, leading to a deadlock.
57The
58.Li pfiles
59program cannot release the
60.Li xterm
61process because it still has pending I/O, but the I/O cannot be drained
62due to the same hold.
63.Pp
64To address this, these functions duplicate the standard output and
65standard error of the process to temporary files and then flushes it out
66to the original file descriptors and streams later.
67When finished, the original file descriptors are restored as standard out and
68standard error.
69.Pp
70The
71.Fn proc_initstdio
72function initializes a new standard out and standard error file
73descriptors and retains the originals.
74.Pp
75The
76.Fn proc_flushstdio
77functions flushes all of the cached data from the temporary standard out
78and standard error back to the underlying ones.
79This function should only be called after all process handles have been
80released.
81For example, if iterating on multiple processes, calling this after handling
82each one is safe.
83.Pp
84The
85.Fn proc_finistdio
86flushes any outstanding I/O and restores the original standard output
87and standard error.
88.Pp
89Once called, the
90.Fn proc_initstdio
91function must not be called again until a successful call to
92.Fn proc_finistdio .
93.Sh RETURN VALUES
94Upon successful completion, the
95.Fn proc_initstdio ,
96.Fn proc_flushstdio ,
97and
98.Fn proc_finistdio
99functions all return
100.Sy 0 .
101Otherwise,
102.Sy -1
103is returned to indicate failure.
104.Sh INTERFACE STABILITY
105.Sy Uncommitted
106.Sh MT-LEVEL
107.Sy Unsafe
108.Sh SEE ALSO
109.Xr libproc 3LIB ,
110.Xr Pgrab 3PROC ,
111.Xr Prelease 3PROC
112