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 May 11, 2016 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 SYNOPSIS 23.Lb libproc 24.In libproc.h 25.Ft int 26.Fo proc_initstdio 27.Fa void 28.Fc 29.Ft int 30.Fo proc_flushstdio 31.Fa void 32.Fc 33.Ft int 34.Fo proc_finistdio 35.Fa void 36.Fc 37.Sh DESCRIPTION 38The 39.Fn proc_initstdio , 40.Fn proc_flushstdio , 41and 42.Fn proc_finistdio 43functions are utilities provided to aid with the possibility of deadlock 44while doing I/O operations. If a process is trying to do I/O, but 45holding the process handle that would consume that I/O, then eventually 46the program holding the process handle will block as none of its I/O has 47been drained. However, because it is holding a process handle to that 48process, it will never be drained. 49.Pp 50Consider, for example, the following invocation: 51.Li pfiles `pgrep xterm` 52where the command was launched from a shell on an xterm. Because the 53xterm is stopped, it will not be able to write out any of the standard 54out that gets passed to it, leading to a deadlock. The 55.Li pfiles 56program cannot release the 57.Li xterm 58process because it still has pending I/O, but the I/O cannot be drained 59due to the same hold. 60.Pp 61To address this, these functions duplicate the standard output and 62standard error of the process to temporary files and then flushes it out 63to the original file descriptors and streams later. When finished, the 64original file descriptors are restored as standard out and standard 65error. 66.Pp 67The 68.Fn proc_initstdio 69function initializes a new standard out and standard error file 70descriptors and retains the originals. 71.Pp 72The 73.Fn proc_flushstdio 74functions flushes all of the cached data from the temporary standard out 75and standard error back to the underlying ones. This function should 76only be called after all process handles have been released. For 77example, if iterating on multiple processes, calling this after handling 78each one is safe. 79.Pp 80The 81.Fn proc_finistdio 82flushes any outstanding I/O and restores the original standard output 83and standard error. 84.Pp 85Once called, the 86.Fn proc_initstdio 87function must not be called again until a successful call to 88.Fn proc_finistdio . 89.Sh RETURN VALUES 90Upon successful completion, the 91.Fn proc_initstdio , 92.Fn proc_flushstdio , 93and 94.Fn proc_finistdio 95functions all return 96.Sy 0 . 97Otherwise, 98.Sy -1 99is returned to indicate failure. 100.Sh INTERFACE STABILITY 101.Sy Uncommitted 102.Sh MT-LEVEL 103.Sy Unsafe 104.Sh SEE ALSO 105.Xr libproc 3LIB , 106.Xr Pgrab 3PROC , 107.Xr Prelease 3PROC 108