Debian Codegraph @

upstream/debian-trixie/man3/atexit.3

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