bin/pwait/pwait.1

   1 .\"
   2 .\" Copyright (c) 2004-2009, Jilles Tjoelker
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with
   6 .\" or without modification, are permitted provided that the
   7 .\" following conditions are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above
  10 .\"    copyright notice, this list of conditions and the
  11 .\"    following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the
  13 .\"    above copyright notice, this list of conditions and
  14 .\"    the following disclaimer in the documentation and/or
  15 .\"    other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  18 .\" CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
  19 .\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  20 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  21 .\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  22 .\" COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
  23 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  25 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  26 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  27 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  28 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  29 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
  30 .\" USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
  31 .\" OF SUCH DAMAGE.
  32 .\"
  33 .Dd January 21, 2021
  34 .Dt PWAIT 1
  35 .Os
  36 .Sh NAME
  37 .Nm pwait
  38 .Nd wait for processes to terminate
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl t Ar duration
  42 .Op Fl ov
  43 .Ar pid
  44 \&...
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility will wait until each of the given processes has terminated.
  49 .Pp
  50 The following option is available:
  51 .Bl -tag -width indent
  52 .It Fl o
  53 Exit when any of the given processes has terminated.
  54 .It Fl t Ar duration
  55 If any process is still running after
  56 .Ar duration ,
  57 .Nm
  58 will exit.
  59 The
  60 .Ar duration
  61 value can be integer or decimal numbers.
  62 Values without unit symbols are interpreted as seconds.
  63 .Pp
  64 Supported unit symbols are:
  65 .Bl -tag -width indent -compact
  66 .It s
  67 seconds
  68 .It m
  69 minutes
  70 .It h
  71 hours
  72 .El
  73 .It Fl v
  74 Print the exit status when each process terminates or
  75 .Ql timeout
  76 if the timer goes off earlier.
  77 .El
  78 .Sh EXIT STATUS
  79 The
  80 .Nm
  81 utility exits 0 on success, and >0 if an error occurs.
  82 .Pp
  83 If the
  84 .Fl t
  85 flag is specified and a timeout occurs, the exit status will be 124.
  86 .Pp
  87 Invalid pids elicit a warning message but are otherwise ignored.
  88 .Sh EXAMPLES
  89 Start two
  90 .Xr sleep 1
  91 processes in the background.
  92 The first one will sleep for 30 seconds and the second one for one hour.
  93 Wait for any of them to finish but no more than 5 seconds.
  94 Since a timeout occurs the exit status is 124:
  95 .Bd -literal -offset indent
  96 $ sleep 30 & sleep 3600 &
  97 [1] 1646
  98 [2] 1647
  99 $ pwait -o -t5 1646 1647
 100 $ echo $?
 101 124
 102 .Ed
 103 .Pp
 104 Same as above but try to obtain the exit status of the processes.
 105 In this case
 106 .Ql timeout
 107 is shown and the exit status is 124:
 108 .Bd -literal -offset indent
 109 $ sleep 30 & sleep 3600 &
 110 [1] 1652
 111 [2] 1653
 112 $ pwait -v -t 5 1652 1653
 113 timeout
 114 $ echo $?
 115 124
 116 .Ed
 117 .Pp
 118 Start two
 119 .Xr sleep 1
 120 processes in the background sleeping for 30 and 40 seconds respectively.
 121 Wait 60 seconds for any of them to finish and get their exit codes:
 122 .Bd -literal -offset indent
 123 $ sleep 30 & sleep 40 &
 124 [1] 1674
 125 [2] 1675
 126 $ pwait -v -t 60 1674 1675
 127 1674: exited with status 0.
 128 1675: exited with status 0.
 129 [1]-  Done                    sleep 30
 130 [2]+  Done                    sleep 40
 131 $ echo $?
 132 0
 133 .Ed
 134 .Sh SEE ALSO
 135 .Xr kill 1 ,
 136 .Xr pkill 1 ,
 137 .Xr ps 1 ,
 138 .Xr wait 1 ,
 139 .Xr kqueue 2
 140 .Sh NOTES
 141 .Nm
 142 is not a substitute for the
 143 .Xr wait 1
 144 builtin
 145 as it will not clean up any zombies or state in the parent process.
 146 .Pp
 147 To avoid deadlock,
 148 .Nm
 149 will ignore its own pid, if it is provided as a process id to wait for.
 150 .Sh HISTORY
 151 A
 152 .Nm
 153 command first appeared in SunOS 5.8.