_cwait -- Wait for Child Process

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.

Example



exit -- End Program
_exit -- End Process
_spawnl - _spawnvpe -- Start and Run Child Processes
<process.h>