1 .TH EXITS 3
2 .SH NAME
3 exits, _exits, atexit, atexitdont, terminate \- terminate process, process cleanup
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .nf
10 .B
11 void	_exits(char *msg)
12 .B
13 void	exits(char *msg)
14 .PP
15 .B
16 int	atexit(void(*)(void))
17 .PP
18 .B
19 void	atexitdont(void(*)(void))
20 .fi
21 .SH DESCRIPTION
22 .I Exits
23 is the conventional way to terminate a process.
24 .I _Exits
25 also terminates a process but does not call the registered
26 .I atexit
27 handlers
28 .RI ( q.v. ).
29 They
30 can never return.
31 .PP
32 .I Msg
33 conventionally includes a brief (maximum length
34 .BR ERRLEN )
35 explanation of the reason for
36 exiting, or a null pointer or empty string to indicate normal termination.
37 The string is passed to the parent process, prefixed by the name and process
38 id of the exiting process, when the parent does a
39 .IR wait (3).
40 .PP
41 Before calling
42 .I _exits
43 with
44 .I msg
45 as an argument,
46 .I exits
47 calls in reverse order all the functions
48 recorded by
49 .IR atexit .
50 .PP
51 .I Atexit
52 records
53 .I fn
54 as a function to be called by
55 .IR exits .
56 It returns zero if it failed,
57 nonzero otherwise.
58 A typical use is to register a cleanup routine for an I/O package.
59 To simplify programs that fork or share memory,
60 .I exits
61 only calls those
62 .IR atexit -registered
63 functions that were registered by the same
64 process as that calling
65 .IR exits .
66 .PP
67 Calling
68 .I atexit
69 twice (or more) with the same function argument causes
70 .I exits
71 to invoke the function twice (or more).
72 .PP
73 There is a limit to the number of exit functions
74 that will be recorded;
75 .I atexit
76 returns 0 if that limit has been reached.
77 .PP
78 .I Atexitdont
79 cancels a previous registration of an exit function.
80 .SH SOURCE
81 .B \*9/src/lib9/atexit.c
82 .br
83 .B \*9/src/lib9/_exits.c
84 .SH "SEE ALSO"
85 .IR fork (2),
86 .IR wait (3)
87 .SH BUGS
88 Because of limitations of Unix, the exit status of a
89 process can only be an 8-bit integer.
90 Exit status 0 is used for empty exit messages, and 1 for
91 non-empty messages.
92 .PP
93 Exit codes 97 through 99 are used by the thread library to signal
94 internal synchronization errors between the main program
95 and a proxy process that implements backgrounding.
96 .PP
97 To avoid name conflicts with the underlying system,
98 .I atexit
99 and
100 .I atexitdont
101 are preprocessor macros defined as
102 .I p9atexit
103 and
104 .IR p9atexitdont ;
105 see
106 .IR intro (3).