Format
#include <process.h> int _cwait(int *stat_loc, int process_id, int action_code);
Language Level: Extension
_cwait delays the completion of a parent process
until the child process specified by process_id ends.
The process_id is the value returned by the _spawn function that started the child process. If the specified child process ends before _cwait is called, _cwait returns to the calling process immediately with a value of -1. If the value of process_id is 0, the parent process waits until all of its child processes end.
If the variable pointed to by stat_loc is NULL, _cwait does not use it. If it is not NULL,_cwait places information about the return status and the return code of the child process in the location pointed to by stat_loc.
If the child process on OS/2 ended normally with a
call to the OS/2 DosExit API, the lowest-order byte of the
variable pointed to by stat_loc is 0. The next highest-order byte
comtains the lowest-order byte of the argument passed to DosExit.
The value of this byte depends on how the child process caused
the system to call DosExit. If the child called exit, _exit, or
return from main, or used a DosExit coded into the program, the
byte contains the lowest-order byte of the argument the child
passed to exit, _exit, or return. The value of the byte is undefined if the
child caused a DosExit call simply by reaching the end of main.
For OS/2, if the child process ended abnormally (without a call to DosExit), the lowest-order byte of the variable pointed to by stat_loc contains the return code from the OS/2 DosWaitChild API, and the next highest-order byte is 0.
On Windows, if the child process ended normally with
a call to the Win32 ExitProcess API, the lowest-order byte of the
variable pointed to by stat_loc
is 0. The next highest-order byte contains the lowest-order byte
of the argument passed to ExitProcess by the child process. The
value of this byte depends on how the child process caused the
system to call ExitProcess. If the child called exit,
_exit, or return from main, or used a ExitProcess coded into the
program, the byte contains the lowest-order byte of the argument
the child passed to exit, _exit, or return. The value of the byte
is undefined if the child caused a ExitProcess call simply by
reaching the end of main.
If the child process on Windows ended abnormally (without a call to ExitProcess), the lowest-order byte of the variable pointed to by stat_loc contains the return code from the Win32 GetExitCodeProcess API, and the next higher-order byte is 0.
The action_code specifies when the parent process is to start running again. Values for action_code include:
| Action Code | Meaning |
| WAIT_CHILD | The parent process waits until the specified child process ends. |
| WAIT_GRANDCHILD | The parent process waits until the child process and all of the child processes of that process end. |
The action code values are defined in <process.h>.
On OS/2, because the size of an int is only 2 bytes
in 16-bit compilers, if you are migrating a 16-bit program, some
parts of your program may have to be rewritten if they use this
function.
An alternative to this function on OS/2 is the DosWaitChild API call.
An alternative to this function on Windows is the
WaitForSingleObject API call.
Return Value
At the normal end of the child process,
_cwait returns the process identifier of the child to the parent
process. If a child process ends abnormally, _cwait returns -1 to
the parent process and sets errno to EINTR. In the case of an
error, _cwait returns immediately with a value of -1 and sets
errno to one of the following values:
| Value | Meaning |
| EINVAL | Incorrect action code. |
| ECHILD | No child process exists, or the process identifier is incorrect. |
![]()
exit -- End Program
_exit -- End
Process
_spawnl -
_spawnvpe -- Start and Run Child Processes
<process.h>