]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
5 | .\" |
6 | .\" References consulted: | |
7 | .\" Linux libc source code | |
8 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
9 | .\" 386BSD man pages | |
10 | .\" Modified 1993-03-29, David Metcalfe | |
11 | .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) | |
12 | .\" Modified 2003-10-25, Walter Harms | |
13 | .\" | |
4c1c5274 | 14 | .TH atexit 3 (date) "Linux man-pages (unreleased)" |
fea681da | 15 | .SH NAME |
5af3e8ee | 16 | atexit \- register a function to be called at normal process termination |
b813014f AC |
17 | .SH LIBRARY |
18 | Standard C library | |
19 | .RI ( libc ", " \-lc ) | |
fea681da MK |
20 | .SH SYNOPSIS |
21 | .nf | |
22 | .B #include <stdlib.h> | |
68e4db0a | 23 | .PP |
fea681da MK |
24 | .BI "int atexit(void (*" function )(void)); |
25 | .fi | |
26 | .SH DESCRIPTION | |
60a90ecd MK |
27 | The |
28 | .BR atexit () | |
c6fa0841 MK |
29 | function registers the given |
30 | .I function | |
31 | to be | |
5af3e8ee | 32 | called at normal process termination, either via |
fea681da | 33 | .BR exit (3) |
c6fa0841 MK |
34 | or via return from the program's |
35 | .IR main (). | |
fea681da MK |
36 | Functions so registered are called in |
37 | the reverse order of their registration; no arguments are passed. | |
847e0d88 | 38 | .PP |
ee394477 MK |
39 | The same function may be registered multiple times: |
40 | it is called once for each registration. | |
dd3568a1 | 41 | .PP |
46913bec MK |
42 | POSIX.1 requires that an implementation allow at least |
43 | .\" POSIX.1-2001, POSIX.1-2008 | |
0f2111e3 MK |
44 | .B ATEXIT_MAX |
45 | (32) such functions to be registered. | |
5af3e8ee | 46 | The actual limit supported by an implementation can be obtained using |
fea681da | 47 | .BR sysconf (3). |
dd3568a1 | 48 | .PP |
c13182ef | 49 | When a child process is created via |
fb186734 | 50 | .BR fork (2), |
0b0bb11a | 51 | it inherits copies of its parent's registrations. |
c13182ef | 52 | Upon a successful call to one of the |
363a3cc9 | 53 | .BR exec (3) |
1e321034 | 54 | functions, |
18f2ce40 | 55 | all registrations are removed. |
47297adb | 56 | .SH RETURN VALUE |
60a90ecd MK |
57 | The |
58 | .BR atexit () | |
59 | function returns the value 0 if successful; otherwise | |
c7094399 | 60 | it returns a nonzero value. |
e4a2e237 ZL |
61 | .SH ATTRIBUTES |
62 | For an explanation of the terms used in this section, see | |
63 | .BR attributes (7). | |
64 | .TS | |
65 | allbox; | |
c466875e | 66 | lbx lb lb |
e4a2e237 ZL |
67 | l l l. |
68 | Interface Attribute Value | |
69 | T{ | |
9e54434e BR |
70 | .na |
71 | .nh | |
e4a2e237 ZL |
72 | .BR atexit () |
73 | T} Thread safety MT-Safe | |
74 | .TE | |
847e0d88 | 75 | .sp 1 |
4131356c | 76 | .SH VERSIONS |
46913bec MK |
77 | POSIX.1 says that the result of calling |
78 | .\" POSIX.1-2001, POSIX.1-2008 | |
2656acee MK |
79 | .BR exit (3) |
80 | more than once (i.e., calling | |
81 | .BR exit (3) | |
82 | within a function registered using | |
27d47e71 | 83 | .BR atexit ()) |
2656acee MK |
84 | is undefined. |
85 | On some systems (but not Linux), this can result in an infinite recursion; | |
86 | .\" This can happen on OpenBSD 4.2 for example, and is documented | |
87 | .\" as occurring on FreeBSD as well. | |
75c018a1 | 88 | .\" glibc does "the Right Thing" -- invocation of the remaining |
2656acee MK |
89 | .\" exit handlers carries on as normal. |
90 | portable programs should not invoke | |
91 | .BR exit (3) | |
92 | inside a function registered using | |
27d47e71 | 93 | .BR atexit (). |
4131356c AC |
94 | .SH STANDARDS |
95 | C11, POSIX.1-2008. | |
96 | .SH HISTORY | |
97 | POSIX.1-2001, C89, C99, SVr4, 4.3BSD. | |
98 | .SH NOTES | |
99 | Functions registered using | |
100 | .BR atexit () | |
101 | (and | |
102 | .BR on_exit (3)) | |
103 | are not called if a process terminates abnormally because | |
104 | of the delivery of a signal. | |
105 | .PP | |
106 | If one of the registered functions calls | |
107 | .BR _exit (2), | |
108 | then any remaining functions are not invoked, | |
109 | and the other process termination steps performed by | |
110 | .BR exit (3) | |
111 | are not performed. | |
847e0d88 | 112 | .PP |
374b9a8f MK |
113 | The |
114 | .BR atexit () | |
115 | and | |
116 | .BR on_exit (3) | |
117 | functions register functions on the same list: | |
118 | at normal process termination, | |
119 | the registered functions are invoked in reverse order | |
120 | of their registration by these two functions. | |
847e0d88 | 121 | .PP |
46913bec | 122 | According to POSIX.1, the result is undefined if |
7c298e46 | 123 | .BR longjmp (3) |
be4c9c66 | 124 | is used to terminate execution of one of the functions registered using |
7c298e46 | 125 | .BR atexit (). |
84fc5566 | 126 | .\" In glibc, things seem to be handled okay |
c634028a | 127 | .SS Linux notes |
206ed587 MK |
128 | Since glibc 2.2.3, |
129 | .BR atexit () | |
130 | (and | |
131 | .BR on_exit (3)) | |
132 | can be used within a shared library to establish functions | |
133 | that are called when the shared library is unloaded. | |
a14af333 | 134 | .SH EXAMPLES |
b0b6ab4e | 135 | .\" SRC BEGIN (atexit.c) |
207050fa | 136 | .EX |
fea681da MK |
137 | #include <stdio.h> |
138 | #include <stdlib.h> | |
139 | #include <unistd.h> | |
fe5dba13 | 140 | \& |
c13182ef MK |
141 | void |
142 | bye(void) | |
cf0a9ace | 143 | { |
31a6818e | 144 | printf("That was all, folks\en"); |
fea681da | 145 | } |
fe5dba13 | 146 | \& |
c13182ef | 147 | int |
cf0a9ace MK |
148 | main(void) |
149 | { | |
150 | long a; | |
151 | int i; | |
fe5dba13 | 152 | \& |
cf0a9ace | 153 | a = sysconf(_SC_ATEXIT_MAX); |
31a6818e | 154 | printf("ATEXIT_MAX = %ld\en", a); |
fe5dba13 | 155 | \& |
cf0a9ace MK |
156 | i = atexit(bye); |
157 | if (i != 0) { | |
31a6818e | 158 | fprintf(stderr, "cannot set exit function\en"); |
cf634cef | 159 | exit(EXIT_FAILURE); |
cf0a9ace | 160 | } |
fe5dba13 | 161 | \& |
cf634cef | 162 | exit(EXIT_SUCCESS); |
fea681da | 163 | } |
207050fa | 164 | .EE |
b0b6ab4e | 165 | .\" SRC END |
47297adb | 166 | .SH SEE ALSO |
aa3a009e | 167 | .BR _exit (2), |
92bade29 | 168 | .BR dlopen (3), |
fea681da MK |
169 | .BR exit (3), |
170 | .BR on_exit (3) |