HELPLIB.HLB  —  CRTL  wait4
    Waits for a child process to stop or terminate.

    Format

      #include  <wait.h>

      pid_t wait4   (pid_t process_id, union wait *status_location,
                    int options, struct rusage *resource_usage);

1  –  Arguments

 status_location

    A pointer to a location that contains the termination status of
    the child process as defined in the <wait.h> header file.

    Beginning with OpenVMS Version 7.2, when compiled with the _
    VMS_WAIT macro defined, the wait4 function puts the OpenVMS
    completion code of the child process at the address specified
    in the status_location argument.

 process_id

    The child process or set of child processes.

 options

    Flags that modify the behavior of the function. These flags are
    defined in the Description section.

 resource_usage

    The location of a structure that contains the resource
    utilization information for terminated child processes.

2  –  Description

    The wait4 function suspends the calling process until the request
    is completed.

    The process_id argument allows the calling process to gather
    status from a specific set of child processes, according to the
    following rules:

    If the
    process_
    id is          Then status is requested

    Equal to -1    For any child process. In this respect, the
                   waitpid function is equivalent to the wait
                   function.
    Greater than   For a single child process and specifies the
    0              process ID.

    The wait4 function only returns the status of a child process
    from this set.

    The options argument to the wait4 function modifies the behavior
    of the function. You can combine the flags for the options
    argument by specifying their bitwise-inclusive OR. The flags
    are:

    WNOWAIT        Specifies that the process whose status is
                   returned in status_location is kept in a waitable
                   state. You can wait for the process again with the
                   same results.
    WNOHANG        Prevents the suspension of the calling process.
                   If there are child processes that stopped or
                   terminated, one is chosen and the waitpid function
                   returns its process ID, as when you do not specify
                   the WNOHANG flag. If there are no terminated
                   processes (that is, if waitpid suspends the
                   calling process without the WNOHANG flag), 0 is
                   returned. Because you can never wait for process
                   0, there is no confusion arising from this return.
    WUNTRACED      Specifies that the call return additional
                   information when the child processes of the
                   current process stop because the child process
                   received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP
                   signal.

    If the wait4 function returns because the status of a child
    process is available, the process ID of the child process is
    returned. Information is stored in the location pointed to by
    status_location, if this pointer is not null.

    The value stored in the location pointed to by status_location is
    0 only if the status is returned from a terminated child process
    that did one of the following:

    o  Returned 0 from the main function.

    o  Passed 0 as the status argument to the _exit or exit function.

    Regardless of the status_location value, you can define this
    information using the macros defined in the <wait.h> header file,
    which evaluate to integral expressions. In the following macro
    descriptions, status_value is equal to the integer value pointed
    to by status_location:

    WIFEXITED(status_  Evaluates to a nonzero value if status was
    value)             returned for a child process that terminated
                       normally.
    WEXITSTATUS(status_If the value of WIFEXITED(status_value) is
    value)             nonzero, this macro evaluates to the low-order
                       8 bits of the status argument that the child
                       process passed to the _exit or exit function,
                       or to the value the child process returned
                       from the main function.
    WIFSIGNALED(status_Evaluates to a nonzero value if status was
    value)             returned for a child process that terminated
                       due to the receipt of a signal that was not
                       intercepted.
    WTERMSIG(status_   If the value of WIFSIGNALED(status_value) is
    value)             nonzero, this macro evaluates to the number of
                       the signal that caused the termination of the
                       child process.
    WIFSTOPPED(status_ Evaluates to a nonzero value if status was
    value)             returned for a child process that is currently
                       stopped.
    WSTOPSIG(status_   If the value of WIFSTOPPED(status_value) is
    value)             nonzero, this macro evaluates to the number
                       of the signal that caused the child process to
                       stop.
    WIFCONTINUED(status_valuates to a nonzero value if status
    value)             was returned for a child process that has
                       continued.

    If the information stored at the location pointed to by status_
    location was stored there by a call to wait4 that specified
    the WUNTRACED flag, one of the following macros evaluates to a
    nonzero value:

    o  WIFEXITED(*status_value)

    o  WIFSIGNALED(*status_value)

    o  WIFSTOPPED(*status_value)

    o  WIFCONTINUED(*status_value)

    If the information stored in the location pointed to by status_
    location resulted from a call to wait4 without the WUNTRACED flag
    specified, one of the following macros evaluates to a nonzero
    value:

    o  WIFEXITED(*status_value)

    o  WIFSIGNALED(*status_value)

    The wait4 function is similar to the wait3 function. However,
    the wait4 function waits for a specific child as indicated by
    the process_id argument. The resource_usage argument points to a
    location that contains resource usage information for the child
    processes as defined in the <resource.h> header file.

    See also exit and _exit.

3  –  Return Values

    0                  Indicates success. There are no stopped or
                       exited child processes, the WNOHANG option is
                       specified.
    x                  The process_id of the child process. The
                       status of a child process is available.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  ECHILD - There are no child processes to
                          wait for.

                       o  EINTR - Terminated by receipt of a signal
                          intercepted by the calling process.

                       o  EFAULT - The status_location or resource_
                          usage argument points to a location outside
                          of the address space of the process.

                       o  EINVAL- The value of the options argument
                          is not valid.
Close Help