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