Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <process.h>
    int cwait( int *status, int process_id, int action );

Description:
    The cwait function suspends the calling process until the specified
    process terminates.

    If status is not NULL, it points to a word that will be filled in with
    the termination status word and return code of the terminated child
    process.

    If the child process terminated normally, then the low order byte of the
    status word will be set to 0, and the high order byte will contain the
    low order byte of the return code that the child process passed to the
     DOSEXIT function.  The  DOSEXIT function is called whenever  main
    returns, or  exit or  _exit are explicity called.

    If the child process did not terminate normally, then the high order
    byte of the status word will be set to 0, and the low order byte will
    contain one of the following values:

    Value     Meaning

1
    Hard-error abort

2
    Trap operation

3
    SIGTERM signal not intercepted

    Note:
        This implementation of the status value follows the OS/2 model and
        differs from the Microsoft implementation.  Under Microsoft, the
        return code is returned in the low order byte and it is not possible
        to determine whether a return code of 1, 2, or 3 imply that the
        process terminated normally.  For portability to Microsoft
        compilers, you should ensure that the application that is waited on
        does not return one of these values.  The following shows how to
        handle the status value in a portable manner.


             cwait( &status, process_id, WAIT_CHILD );

             #if defined(__WATCOMC__)
             switch( status & 0xff ) {
             case 0:
                 printf( "Normal termination exit code = %d\n", status >> 8
        );
                 break;
             case 1:
                 printf( "Hard-error abort\n" );
                 break;
             case 2:
                 printf( "Trap operation\n" );
                 break;
             case 3:
                 printf( "SIGTERM signal not intercepted\n" );
                 break;
             default:
                 printf( "Bogus return status\n" );
             }

             #else if defined(_MSC_VER)
             switch( status & 0xff ) {
             case 1:
                 printf( "Possible Hard-error abort\n" );
                 break;
             case 2:
                 printf( "Possible Trap operation\n" );
                 break;
             case 3:
                 printf( "Possible SIGTERM signal not intercepted\n" );
                 break;
             default:
                 printf( "Normal termination exit code = %d\n", status );
             }

             #endif


    The process_id argument specifies which process to wait for.  Under
    Windows NT, any process can wait for any other process for which the
    process id is known.  Under OS/2, a process can wait for any of its
    child processes.  For example, a process id is returned by certain forms
    of the  spawn function that is used to start a child process.

    The action argument specifies when the parent process resumes execution.
     This argument is ignored in Windows NT, but is accepted for
    compatibility with OS/2 (although Microsoft handles the status value
    differently from OS/2!).  The possible values are:

    Value     Meaning

WAIT_CHILD
    Wait until the specified child process has ended.

WAIT_GRANDCHILD
    Wait until the specified child process and all of the child processes of
    that child process have ended.

    Under Windows NT, there is no parent-child relationship.

Returns:
    The cwait function returns the (child's) process id if the (child)
    process terminated normally.  Otherwise, cwait returns -1 and sets
     errno to one of the following values:

    Constant     Meaning

EINVAL
    Invalid action code

ECHILD
    Invalid process id, or the child does not exist.

EINTR
    The child process terminated abnormally.


Example:
    #include <stdio.h>
    #include <process.h>

    void main()
      {
         int   process_id;
         int   status;

         process_id = spawnl( P_NOWAIT, "child.exe",
                    "child", "parm", NULL );
         cwait( &status, process_id, WAIT_CHILD );
      }

Classification:
    WATCOM

Systems:
    Win32, OS/2 1.x(all), OS/2-32

See Also:
    exit, _exit, spawn Functions, wait