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