Subversion Repositories planix.SVN

.TH WAIT 2

.SH NAME

await, wait, waitpid \- wait for a process to exit

.SH SYNOPSIS

.B #include <u.h>

.br

.B #include <libc.h>

.PP

.B

Waitmsg*	wait(void)

.PP

.B

int 		waitpid(void)

.PP

.B

int 		await(char *s, int n)

.SH DESCRIPTION

.I Wait

causes a process to wait for any child process (see

.IR fork (2))

to exit.

It returns a

.B Waitmsg

holding

information about the exited child.

A

.B Waitmsg

has this structure:

.IP

.EX

.ta 6n +\w'long 'u +\w'msg[ERRLEN];     'u

typedef

struct Waitmsg

{

	int pid;	/* of loved one */

	ulong time[3];	/* of loved one & descendants */

	char	*msg;

} Waitmsg;

.EE

.PP

.B Pid

is the child's

process id.

The

.B time

array contains the time the child and its descendants spent in user code,

the time spent in system calls, and the child's elapsed real time,

all in units of milliseconds.

.B Msg

contains the message that the child specified in

.IR exits (2).

For a normal exit,

.B msg[0]

is zero,

otherwise

.B msg

is the exit string

prefixed by the process name, a blank, the process id, and a colon.

.PP

If there are no more children to wait for,

.I wait

returns immediately, with return value nil.

.PP

The

.B Waitmsg

structure is allocated by

.IR malloc (2)

and should be freed after use.

For programs that only need the pid of the exiting program,

.I waitpid

returns just the pid and discards the rest of the information.

.PP

The underlying system call is

.IR await ,

which fills in the n-byte buffer

.I s

with a textual representation of the pid, times, and exit string.

There is no terminal NUL.

The return value is the length, in bytes, of the data.

.PP

The buffer filled in by

.I await

may be parsed (after appending a NUL) using

.IR tokenize

(see

.IR getfields (2));

the resulting fields are, in order, pid, the three times, and the exit string,

which will be

.B ''

for normal exit.

If the representation is longer than

.I n

bytes, it is truncated but, if possible, properly formatted.

The information that does not fit in the buffer is discarded, so

a subsequent call to

.I await

will return the information about the next exiting child, not the remainder

of the truncated message.

In other words, each call to

.I await

returns the information about one child, blocking if necessary if no child has exited.

.PP

If the calling process has no living children,

.I await

and

.I waitpid

return

.BR -1 .

.SH SOURCE

.B /sys/src/libc/9syscall

.br

.B /sys/src/libc/9sys

.SH "SEE ALSO"

.IR fork (2),

.IR exits (2),

the

.B wait

file in

.IR proc (3)

.SH DIAGNOSTICS

These routines set

.IR errstr .