man3/atexit.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   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 (faith@cs.unc.edu)
  12 .\" Modified 2003-10-25, Walter Harms
  13 .\"
  14 .TH atexit 3 (date) "Linux man-pages (unreleased)"
  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 .PP
  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 .PP
  39 The same function may be registered multiple times:
  40 it is called once for each registration.
  41 .PP
  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 .PP
  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 .ad l
  65 .nh
  66 .TS
  67 allbox;
  68 lbx lb lb
  69 l l l.
  70 Interface       Attribute       Value
  71 T{
  72 .BR atexit ()
  73 T}      Thread safety   MT-Safe
  74 .TE
  75 .hy
  76 .ad
  77 .sp 1
  78 .SH VERSIONS
  79 POSIX.1 says that the result of calling
  80 .\" POSIX.1-2001, POSIX.1-2008
  81 .BR exit (3)
  82 more than once (i.e., calling
  83 .BR exit (3)
  84 within a function registered using
  85 .BR atexit ())
  86 is undefined.
  87 On some systems (but not Linux), this can result in an infinite recursion;
  88 .\" This can happen on OpenBSD 4.2 for example, and is documented
  89 .\" as occurring on FreeBSD as well.
  90 .\" glibc does "the Right Thing" -- invocation of the remaining
  91 .\" exit handlers carries on as normal.
  92 portable programs should not invoke
  93 .BR exit (3)
  94 inside a function registered using
  95 .BR atexit ().
  96 .SH STANDARDS
  97 C11, POSIX.1-2008.
  98 .SH HISTORY
  99 POSIX.1-2001, C89, C99, SVr4, 4.3BSD.
 100 .SH NOTES
 101 Functions registered using
 102 .BR atexit ()
 103 (and
 104 .BR on_exit (3))
 105 are not called if a process terminates abnormally because
 106 of the delivery of a signal.
 107 .PP
 108 If one of the registered functions calls
 109 .BR _exit (2),
 110 then any remaining functions are not invoked,
 111 and the other process termination steps performed by
 112 .BR exit (3)
 113 are not performed.
 114 .PP
 115 The
 116 .BR atexit ()
 117 and
 118 .BR on_exit (3)
 119 functions register functions on the same list:
 120 at normal process termination,
 121 the registered functions are invoked in reverse order
 122 of their registration by these two functions.
 123 .PP
 124 According to POSIX.1, the result is undefined if
 125 .BR longjmp (3)
 126 is used to terminate execution of one of the functions registered using
 127 .BR atexit ().
 128 .\" In glibc, things seem to be handled okay
 129 .SS Linux notes
 130 Since glibc 2.2.3,
 131 .BR atexit ()
 132 (and
 133 .BR on_exit (3))
 134 can be used within a shared library to establish functions
 135 that are called when the shared library is unloaded.
 136 .SH EXAMPLES
 137 .\" SRC BEGIN (atexit.c)
 138 .EX
 139 #include <stdio.h>
 140 #include <stdlib.h>
 141 #include <unistd.h>
 142 \&
 143 void
 144 bye(void)
 145 {
 146     printf("That was all, folks\en");
 147 }
 148 \&
 149 int
 150 main(void)
 151 {
 152     long a;
 153     int i;
 154 \&
 155     a = sysconf(_SC_ATEXIT_MAX);
 156     printf("ATEXIT_MAX = %ld\en", a);
 157 \&
 158     i = atexit(bye);
 159     if (i != 0) {
 160         fprintf(stderr, "cannot set exit function\en");
 161         exit(EXIT_FAILURE);
 162     }
 163 \&
 164     exit(EXIT_SUCCESS);
 165 }
 166 .EE
 167 .\" SRC END
 168 .SH SEE ALSO
 169 .BR _exit (2),
 170 .BR dlopen (3),
 171 .BR exit (3),
 172 .BR on_exit (3)