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