plan9port/man/man3/exits.3

.TH EXITS 3
.SH NAME
exits, _exits, exitcode, atexit, atexitdont \- terminate process, process cleanup
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.nf
.B
void	_exits(char *msg)
.B
void	exits(char *msg)
.PP
.B
int	exitcode(char *msg)
.PP
.B
int	atexit(void(*)(void))
.PP
.B
void	atexitdont(void(*)(void))
.fi
.SH DESCRIPTION
.I Exits
is the conventional way to terminate a process.
.I _Exits
also terminates a process but does not call the registered
.I atexit
handlers
.RI ( q.v. ).
They
can never return.
.PP
.I Msg
conventionally includes a brief (maximum length
.BR ERRLEN )
explanation of the reason for
exiting, or a null pointer or empty string to indicate normal termination.
The string is passed to the parent process, prefixed by the name and process
id of the exiting process, when the parent does a
.MR wait (3) .
.PP
Before calling
.I _exits
with
.I msg
as an argument,
.I exits
calls in reverse order all the functions
recorded by
.IR atexit .
.PP
.I Atexit
records
.I fn
as a function to be called by
.IR exits .
It returns zero if it failed,
nonzero otherwise.
A typical use is to register a cleanup routine for an I/O package.
To simplify programs that fork or share memory,
.I exits
only calls those
.IR atexit -registered
functions that were registered by the same
process as that calling
.IR exits .
.PP
Calling
.I atexit
twice (or more) with the same function argument causes
.I exits
to invoke the function twice (or more).
.PP
There is a limit to the number of exit functions
that will be recorded;
.I atexit
returns 0 if that limit has been reached.
.PP
.I Atexitdont
cancels a previous registration of an exit function.
.SH SOURCE
.B \*9/src/lib9/atexit.c
.br
.B \*9/src/lib9/_exits.c
.SH "SEE ALSO"
.MR fork (2) ,
.MR wait (3)
.SH BUGS
Because of limitations of Unix, the exit status of a
process can only be an 8-bit integer.
.I Exits
and
.I _exits
treat null or empty exit status as exit code 0
and call 
.I exitcode
to translate any other string into an exit code.
By default, the library provides an
.I exitcode
that maps all messages to 1.
Applications may find it useful to provide their own 
implementations of
.I exitcode .
.PP
Exit codes 97 through 99 are used by the thread library to signal
internal synchronization errors between the main program
and a proxy process that implements backgrounding.
.PP
To avoid name conflicts with the underlying system,
.I atexit
and
.I atexitdont
are preprocessor macros defined as
.I p9atexit
and
.IR p9atexitdont ;
see
.MR intro (3) .