waitpid()

wait for process termination 

Function


SYNOPSIS

#include <sys/types.h>

#include <sys/wait.h>

pid_t waitpid(pid_t pid, int *stat_loc, int options);


DESCRIPTION

The waitpid() function lets the calling process obtain status information about one of its child processes. If status information is available for two or more child processes, the order in which their status is reported is unspecified. If more than one thread is suspended in waitpid() awaiting termination of the same process, exactly one thread returns the process status at the time of the target child process termination. The other threads return -1, with errno set to ECHILD.

If the calling process sets SIGCHLD to SIG_IGN, and the process has no unwaited for children that were transformed into zombie processes, the calling thread blocks until all of the children of the process terminate, at which time waitpid() returns -1 with errno set to ECHILD.

If the parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned a new parent process ID corresponding to a system-level process.


PARAMETERS

pid 

Specifies a set of child processes for which the status is requested:

  • If pid is equal to -1, status is requested for any child process. In this respect, waitpid() is equivalent to wait().
  • If pid is greater than 0, it specifies the process ID of a single child process for which status is requested.
  • If pid is 0, status is requested for any child process whose process group ID is equal to that of the calling process. This setting is not currently supported.
  • If pid is less than -1, status is requested for any child process whose process group ID is equal to the absolute value of pid. This setting is not currently supported.
stat_loc 

Specifies the location to which the child process' exit status is stored. If NULL is passed, no exit status is returned. Otherwise, the following macros defined in <sys/wait.h> can be used to evaluate the returned status:

WIFEXITED(s) 

Evaluates to a non-zero value if status was returned for a child process that exited normally.

WEXITSTATUS(s) 

If the value of WIFEXITED(s) is non-zero, this macro evaluates to the low-order 8 bits of the status argument that the child process passed to exit() or _exit(), or to the value that the child process returned from main().

WIFSIGNALED(s) 

Evaluates to a non-zero value if status was returned for a child process that terminated due to receipt of a signal that was not caught.

WTERMSIG(s) 

If the value of WIFSIGNALED(s) is non-zero, this macro evaluates to the number of the signal that caused the termination of the child process.

WIFCORED(s) 

Evaluates to a non-zero value if status was returned for a child process that terminated due to receipt of a signal that was not caught, and whose default action is to dump core.

WCOREDUMP(s) 

Evaluates to a non-zero value if status was returned for a child process that terminated due to receipt of a signal that was not caught, and whose default action is to dump core.

WCORESIG(s) 

If the value of WIFCORED(s) is non-zero, this macro evaluates to the number of the signal that caused the termination of the child process.

WIFSTOPPED(s) 

Evaluates to a non-zero value if status was returned for a child process that is currently stopped.

WSTOPSIG(s) 

If the value of WIFSTOPPED(s) is non-zero, this macro evaluates to the number of the signal that caused the child process to stop.

options 

Is the bitwise inclusive-OR of zero or more of the following flags, defined in <sys/wait.h>:

WNOHANG 

The waitpid() function does not suspend execution of the calling thread if status is not immediately available for one of the child processes specified by pid.

WUNTRACED 

The status of any child processes specified by pid that are stopped, and whose status has not yet been reported since they stopped, is also reported to the requesting thread. This value is currently not supported, and is ignored.


RETURN VALUES

If waitpid() was invoked with WNOHANG set in options, and there are children specified by pid for which status is not available, waitpid() returns 0. If WNOHANG was not set, waitpid() returns the process ID of a child when the status of that child is available. Otherwise, it returns -1 and sets errno to one of the following values:

ECHILD 

The process or process group specified by pid does not exist or is not a child of the calling process.

EFAULT 

stat_loc is not a writable address.

EINTR 

The function was interrupted by a signal. The value of the location pointed to by stat_loc is undefined.

EINVAL 

The options argument is not valid.

ENOSYS 

pid specifies a process group (0 or less than -1), which is not currently supported.


CONFORMANCE

POSIX.1 (1996).


MULTITHREAD SAFETY LEVEL

Async-signals-safe.


PORTING ISSUES

The NuTCRACKER Platform converts the exit status of native Windows applications to UNIX format, which allows waitpid() to work correctly with either NuTCRACKER Platform or non-NuTCRACKER Platform processes.

The process ID passed to waitpid() should be one returned by a function in the PTC MKS Toolkit UNIX APIs. Refer to Process Identification in the Windows Concepts chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
_exit(), _NutForkExecl(), _NutForkExecle(), _NutForkExeclp(), _NutForkExeclpe(), _NutForkExecv(), _NutForkExecvp(), _NutForkExecvpe(), execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), exit(), fork(), vfork(), wait()


PTC MKS Toolkit 9.6 Documentation Build 9.