usr/src/man/man3proc/proc_initstdio.3proc

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