xref: /illumos-gate/usr/src/man/man1/wait.1 (revision bbf21555)

Sun Microsystems, Inc. gratefully acknowledges The Open Group for
permission to reproduce portions of its copyrighted documentation.
Original documentation from The Open Group can be obtained online at
http://www.opengroup.org/bookstore/.

The Institute of Electrical and Electronics Engineers and The Open
Group, have given us permission to reprint portions of their
documentation.

In the following statement, the phrase ``this text'' refers to portions
of the system documentation.

Portions of this text are reprinted and reproduced in electronic form
in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 6,
Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy
between these versions and the original IEEE and The Open Group
Standard, the original IEEE and The Open Group Standard is the referee
document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html.

This notice shall appear on any product containing this material.

The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.

You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.

When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]


Copyright 1989 AT&T
Copyright 1992 X/Open Company Limited
Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved

WAIT 1 "May 17, 2020"
NAME
wait - await process completion
SYNOPSIS

"/bin/sh"
wait [pid]...
wait [pid]...

wait [% jobid...]
"/bin/csh"
wait
"ksh93"
wait [job...]
DESCRIPTION
The shell itself executes wait, without creating a new process. If you get the error message cannot fork,too many processes, try using the wait command to clean up your background processes. If this doesn't help, the system process table is probably full or you have too many active foreground processes. There is a limit to the number of process IDs associated with your login, and to the number the system can keep track of.

Not all the processes of a pipeline with three or more stages are children of the shell, and thus cannot be waited for.

"/bin/sh, /bin/jsh"
Wait for your background process whose process ID is pid and report its termination status. If pid is omitted, all your shell's currently active background processes are waited for and the return code is 0. The wait utility accepts a job identifier, when Job Control is enabled (jsh), and the argument, jobid, is preceded by a percent sign (%).

If pid is not an active process ID, the wait utility returns immediately and the return code is 0.

"csh"
Wait for your background processes.
"ksh"
When an asynchronous list is started by the shell, the process ID of the last command in each element of the asynchronous list becomes known in the current shell execution environment.

If the wait utility is invoked with no operands, it waits until all process IDs known to the invoking shell have terminated and exit with an exit status of 0.

If one or more pid or jobid operands are specified that represent known process IDs (or jobids), the wait utility waits until all of them have terminated. If one or more pid or jobid operands are specified that represent unknown process IDs (or jobids), wait treats them as if they were known process IDs (or jobids) that exited with exit status 127. The exit status returned by the wait utility is the exit status of the process requested by the last pid or jobid operand.

The known process IDs are applicable only for invocations of wait in the current shell execution environment.

"ksh93"
wait with no operands, waits until all jobs known to the invoking shell have terminated. If one or more job operands are specified, wait waits until all of them have completed. Each job can be specified as one of the following: number

number refers to a process ID.

-number

number refers to a process group ID.

%number

number refers to a job number

%string

Refers to a job whose name begins with string

%?string

Refers to a job whose name contains string

%+

%%

Refers to the current job

%-

Refers to the previous job

If one or more job operands is a process id or process group id not known by the current shell environment, wait treats each of them as if it were a process that exited with status 127.

OPERANDS
The following operands are supported: pid

The unsigned decimal integer process ID of a command, for which the utility is to wait for the termination.

jobid

A job control job ID that identifies a background process group to be waited for. The job control job ID notation is applicable only for invocations of wait in the current shell execution environment, and only on systems supporting the job control option.

USAGE
On most implementations, wait is a shell built-in. If it is called in a subshell or separate utility execution environment, such as one of the following,
(wait)
nohup wait ...
find . -exec wait ... \e;

it returns immediately because there is no known process IDs to wait for in those environments.

EXAMPLES
Example 1 Using A Script To Identify The Termination Signal

Although the exact value used when a process is terminated by a signal is unspecified, if it is known that a signal terminated a process, a script can still reliably figure out which signal is using kill, as shown by the following (/bin/ksh and /usr/xpg4/bin/sh):

sleep 1000&
pid=$!
kill -kill $pid
wait $pid
echo $pid was terminated by a SIG$(kill -l $(($?-128))) signal.

Example 2 Returning The Exit Status Of A Process

If the following sequence of commands is run in less than 31 seconds (/bin/ksh and /usr/xpg4/bin/sh):

sleep 257 | sleep 31 &

jobs -l %%

then either of the following commands returns the exit status of the second sleep in the pipeline:

wait <pid of sleep 31>
wait %%
ENVIRONMENT VARIABLES
See environ(7) for descriptions of the following environment variables that affect the execution of wait: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.
EXIT STATUS
"ksh93"
The following exit values are returned by the wait built-in in ksh93: 0

wait was invoked with no operands. All processes known by the invoking process have terminated.

127

job is a process id or process group id that is unknown to the current shell environment.

ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Committed
Standard See standards(7).
SEE ALSO
csh (1), jobs (1), ksh (1), ksh93 (1), sh (1), attributes (7), environ (7), standards (7)