man3/atexit.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified 1993-03-29, David Metcalfe
  10 .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu)
  11 .\" Modified 2003-10-25, Walter Harms
  12 .\"
  13 .TH atexit 3 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 atexit \- register a function to be called at normal process termination
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <stdlib.h>
  22 .PP
  23 .BI "int atexit(void (*" function )(void));
  24 .fi
  25 .SH DESCRIPTION
  26 The
  27 .BR atexit ()
  28 function registers the given
  29 .I function
  30 to be
  31 called at normal process termination, either via
  32 .BR exit (3)
  33 or via return from the program's
  34 .IR main ().
  35 Functions so registered are called in
  36 the reverse order of their registration; no arguments are passed.
  37 .PP
  38 The same function may be registered multiple times:
  39 it is called once for each registration.
  40 .PP
  41 POSIX.1 requires that an implementation allow at least
  42 .\" POSIX.1-2001, POSIX.1-2008
  43 .B ATEXIT_MAX
  44 (32) such functions to be registered.
  45 The actual limit supported by an implementation can be obtained using
  46 .BR sysconf (3).
  47 .PP
  48 When a child process is created via
  49 .BR fork (2),
  50 it inherits copies of its parent's registrations.
  51 Upon a successful call to one of the
  52 .BR exec (3)
  53 functions,
  54 all registrations are removed.
  55 .SH RETURN VALUE
  56 The
  57 .BR atexit ()
  58 function returns the value 0 if successful; otherwise
  59 it returns a nonzero value.
  60 .SH ATTRIBUTES
  61 For an explanation of the terms used in this section, see
  62 .BR attributes (7).
  63 .ad l
  64 .nh
  65 .TS
  66 allbox;
  67 lbx lb lb
  68 l l l.
  69 Interface       Attribute       Value
  70 T{
  71 .BR atexit ()
  72 T}      Thread safety   MT-Safe
  73 .TE
  74 .hy
  75 .ad
  76 .sp 1
  77 .SH STANDARDS
  78 POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
  79 .SH NOTES
  80 Functions registered using
  81 .BR atexit ()
  82 (and
  83 .BR on_exit (3))
  84 are not called if a process terminates abnormally because
  85 of the delivery of a signal.
  86 .PP
  87 If one of the registered functions calls
  88 .BR _exit (2),
  89 then any remaining functions are not invoked,
  90 and the other process termination steps performed by
  91 .BR exit (3)
  92 are not performed.
  93 .PP
  94 POSIX.1 says that the result of calling
  95 .\" POSIX.1-2001, POSIX.1-2008
  96 .BR exit (3)
  97 more than once (i.e., calling
  98 .BR exit (3)
  99 within a function registered using
 100 .BR atexit ())
 101 is undefined.
 102 On some systems (but not Linux), this can result in an infinite recursion;
 103 .\" This can happen on OpenBSD 4.2 for example, and is documented
 104 .\" as occurring on FreeBSD as well.
 105 .\" Glibc does "the Right Thing" -- invocation of the remaining
 106 .\" exit handlers carries on as normal.
 107 portable programs should not invoke
 108 .BR exit (3)
 109 inside a function registered using
 110 .BR atexit ().
 111 .PP
 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 .PP
 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\en");
 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\en", a);
 154
 155     i = atexit(bye);
 156     if (i != 0) {
 157         fprintf(stderr, "cannot set exit function\en");
 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)