texits.3 - plan9port - [fork] Plan 9 from user space
 (HTM) git clone git://src.adamsgaard.dk/plan9port
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) README
 (DIR) LICENSE
       ---
       texits.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) .