exits.3 (2525B)
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) .