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 .\" $FreeBSD$
  34 .\"
  35 .Dd October 5, 2020
  36 .Dt PWAIT 1
  37 .Os
  38 .Sh NAME
  39 .Nm pwait
  40 .Nd wait for processes to terminate
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl t Ar duration
  44 .Op Fl ov
  45 .Ar pid
  46 \&...
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility will wait until each of the given processes has terminated.
  51 .Pp
  52 The following option is available:
  53 .Bl -tag -width indent
  54 .It Fl o
  55 Exit when any of the given processes has terminated.
  56 .It Fl t Ar duration
  57 If any process is still running after
  58 .Ar duration ,
  59 .Nm
  60 will exit.
  61 The
  62 .Ar duration
  63 value can be integer or decimal numbers.
  64 Values without unit symbols are interpreted as seconds.
  65 .Pp
  66 Supported unit symbols are:
  67 .Bl -tag -width indent -compact
  68 .It s
  69 seconds
  70 .It m
  71 minutes
  72 .It h
  73 hours
  74 .El
  75 .It Fl v
  76 Print the exit status when each process terminates or
  77 .Ql timeout
  78 if the timer goes off earlier.
  79 .El
  80 .Sh EXIT STATUS
  81 The
  82 .Nm
  83 utility exits 0 on success, and >0 if an error occurs.
  84 .Pp
  85 If the
  86 .Fl t
  87 flag is specified and a timeout occurs, the exit status will be 124.
  88 .Pp
  89 Invalid pids elicit a warning message but are otherwise ignored.
  90 .Sh EXAMPLES
  91 Start two
  92 .Xr sleep 1
  93 processes in the background.
  94 The first one will sleep for 30 seconds and the second one for one hour.
  95 Wait for any of them to finish but no more than 5 seconds.
  96 Since a timeout occurs the exit status is 124:
  97 .Bd -literal -offset indent
  98 $ sleep 30 & sleep 3600 &
  99 [1] 1646
 100 [2] 1647
 101 $ pwait -o -t5 1646 1647
 102 $?
 103 124
 104 .Ed
 105 .Pp
 106 Same as above but try to obtain the exit status of the processes.
 107 In this case
 108 .Ql timeout
 109 is shown and the exit status is 124:
 110 .Bd -literal -offset indent
 111 $ sleep 30 & sleep 3600 &
 112 [1] 1652
 113 [2] 1653
 114 $ pwait -v -t 5 1652 1653
 115 timeout
 116 $?
 117 124
 118 .Ed
 119 .Pp
 120 Start two
 121 .Xr sleep 1
 122 processes in the background sleeping for 30 and 40 seconds respectively.
 123 Wait 60 seconds for any of them to finish and get their exit codes:
 124 .Bd -literal -offset indent
 125 $ sleep 30 & sleep 40 &
 126 [1] 1674
 127 [2] 1675
 128 $ pwait -v -t 60 1674 1675
 129 1674: exited with status 0.
 130 1675: exited with status 0.
 131 [1]-  Done                    sleep 30
 132 [2]+  Done                    sleep 40
 133 $ echo $?
 134 0
 135 .Ed
 136 .Sh SEE ALSO
 137 .Xr kill 1 ,
 138 .Xr pkill 1 ,
 139 .Xr ps 1 ,
 140 .Xr wait 1 ,
 141 .Xr kqueue 2
 142 .Sh NOTES
 143 .Nm
 144 is not a substitute for the
 145 .Xr wait 1
 146 builtin
 147 as it will not clean up any zombies or state in the parent process.
 148 .Sh HISTORY
 149 A
 150 .Nm
 151 command first appeared in SunOS 5.8.