]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
c13182ef | 11 | .\" |
fea681da MK |
12 | .\" Since the Linux kernel and libraries are constantly changing, this |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" References consulted: | |
24 | .\" Linux libc source code | |
25 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
26 | .\" 386BSD man pages | |
27 | .\" Modified 1993-03-29, David Metcalfe | |
28 | .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) | |
29 | .\" Modified 2003-10-25, Walter Harms | |
30 | .\" | |
db217984 | 31 | .TH ATEXIT 3 2008-12-05 "Linux" "Linux Programmer's Manual" |
fea681da | 32 | .SH NAME |
5af3e8ee | 33 | atexit \- register a function to be called at normal process termination |
fea681da MK |
34 | .SH SYNOPSIS |
35 | .nf | |
36 | .B #include <stdlib.h> | |
37 | .sp | |
38 | .BI "int atexit(void (*" function )(void)); | |
39 | .fi | |
40 | .SH DESCRIPTION | |
60a90ecd MK |
41 | The |
42 | .BR atexit () | |
43 | function registers the given \fIfunction\fP to be | |
5af3e8ee | 44 | called at normal process termination, either via |
fea681da | 45 | .BR exit (3) |
1b825ab4 | 46 | or via return from the program's \fImain\fP(). |
fea681da MK |
47 | Functions so registered are called in |
48 | the reverse order of their registration; no arguments are passed. | |
ee394477 MK |
49 | |
50 | The same function may be registered multiple times: | |
51 | it is called once for each registration. | |
fea681da | 52 | .LP |
0f2111e3 MK |
53 | POSIX.1-2001 requires that an implementation allow at least |
54 | .B ATEXIT_MAX | |
55 | (32) such functions to be registered. | |
5af3e8ee | 56 | The actual limit supported by an implementation can be obtained using |
fea681da MK |
57 | .BR sysconf (3). |
58 | .LP | |
c13182ef | 59 | When a child process is created via |
fb186734 | 60 | .BR fork (2), |
0b0bb11a | 61 | it inherits copies of its parent's registrations. |
c13182ef | 62 | Upon a successful call to one of the |
363a3cc9 | 63 | .BR exec (3) |
1e321034 | 64 | functions, |
18f2ce40 | 65 | all registrations are removed. |
fea681da | 66 | .SH "RETURN VALUE" |
60a90ecd MK |
67 | The |
68 | .BR atexit () | |
69 | function returns the value 0 if successful; otherwise | |
c7094399 | 70 | it returns a nonzero value. |
2b2581ee MK |
71 | .SH "CONFORMING TO" |
72 | SVr4, 4.3BSD, C89, C99, POSIX.1-2001. | |
73 | .SH NOTES | |
2b2581ee MK |
74 | Functions registered using |
75 | .BR atexit () | |
76 | (and | |
77 | .BR on_exit (3)) | |
78 | are not called if a process terminates abnormally because | |
79 | of the delivery of a signal. | |
7c298e46 | 80 | |
41bf770c MK |
81 | If one of the functions registered functions calls |
82 | .BR _exit (2), | |
83 | then any remaining functions are not invoked, | |
84 | and the other process termination steps performed by | |
85 | .BR exit (3) | |
86 | are not performed. | |
87 | ||
2656acee MK |
88 | POSIX.1-2001 says that the result of calling |
89 | .BR exit (3) | |
90 | more than once (i.e., calling | |
91 | .BR exit (3) | |
92 | within a function registered using | |
27d47e71 | 93 | .BR atexit ()) |
2656acee MK |
94 | is undefined. |
95 | On some systems (but not Linux), this can result in an infinite recursion; | |
96 | .\" This can happen on OpenBSD 4.2 for example, and is documented | |
97 | .\" as occurring on FreeBSD as well. | |
98 | .\" Glibc does "the Right Thing" -- invocation of the remaining | |
99 | .\" exit handlers carries on as normal. | |
100 | portable programs should not invoke | |
101 | .BR exit (3) | |
102 | inside a function registered using | |
27d47e71 | 103 | .BR atexit (). |
2656acee | 104 | |
374b9a8f MK |
105 | The |
106 | .BR atexit () | |
107 | and | |
108 | .BR on_exit (3) | |
109 | functions register functions on the same list: | |
110 | at normal process termination, | |
111 | the registered functions are invoked in reverse order | |
112 | of their registration by these two functions. | |
113 | ||
7c298e46 MK |
114 | POSIX.1-2001 says that the result is undefined if |
115 | .BR longjmp (3) | |
116 | is used to terminate execution of one of the functions registered | |
117 | .BR atexit (). | |
84fc5566 | 118 | .\" In glibc, things seem to be handled okay |
206ed587 MK |
119 | .SS "Linux Notes" |
120 | Since glibc 2.2.3, | |
121 | .BR atexit () | |
122 | (and | |
123 | .BR on_exit (3)) | |
124 | can be used within a shared library to establish functions | |
125 | that are called when the shared library is unloaded. | |
fea681da MK |
126 | .SH EXAMPLE |
127 | .nf | |
128 | #include <stdio.h> | |
129 | #include <stdlib.h> | |
130 | #include <unistd.h> | |
131 | ||
c13182ef MK |
132 | void |
133 | bye(void) | |
cf0a9ace | 134 | { |
9f8e673e | 135 | printf("That was all, folks\\n"); |
fea681da MK |
136 | } |
137 | ||
c13182ef | 138 | int |
cf0a9ace MK |
139 | main(void) |
140 | { | |
141 | long a; | |
142 | int i; | |
fea681da | 143 | |
cf0a9ace | 144 | a = sysconf(_SC_ATEXIT_MAX); |
9f8e673e | 145 | printf("ATEXIT_MAX = %ld\\n", a); |
fea681da | 146 | |
cf0a9ace MK |
147 | i = atexit(bye); |
148 | if (i != 0) { | |
9f8e673e | 149 | fprintf(stderr, "cannot set exit function\\n"); |
cf634cef | 150 | exit(EXIT_FAILURE); |
cf0a9ace | 151 | } |
cf634cef MK |
152 | |
153 | exit(EXIT_SUCCESS); | |
fea681da MK |
154 | } |
155 | .fi | |
fea681da | 156 | .SH "SEE ALSO" |
aa3a009e | 157 | .BR _exit (2), |
fea681da MK |
158 | .BR exit (3), |
159 | .BR on_exit (3) |