10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
121 lines
2.5 KiB
Groff
121 lines
2.5 KiB
Groff
.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 .
|