man3/on_exit.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-04-02, David Metcalfe
  11 .\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu)
  12 .TH on_exit 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 on_exit \- register a function to be called at normal process termination
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <stdlib.h>
  21 .P
  22 .BI "int on_exit(void (*" function ")(int, void *), void *" arg );
  23 .fi
  24 .P
  25 .RS -4
  26 Feature Test Macro Requirements for glibc (see
  27 .BR feature_test_macros (7)):
  28 .RE
  29 .P
  30 .BR on_exit ():
  31 .nf
  32     Since glibc 2.19:
  33         _DEFAULT_SOURCE
  34     glibc 2.19 and earlier:
  35         _BSD_SOURCE || _SVID_SOURCE
  36 .fi
  37 .SH DESCRIPTION
  38 The
  39 .BR on_exit ()
  40 function registers the given
  41 .I function
  42 to be
  43 called at normal process termination, whether via
  44 .BR exit (3)
  45 or via return from the program's
  46 .IR main ().
  47 The
  48 .I function
  49 is passed the status argument given to the last call to
  50 .BR exit (3)
  51 and the
  52 .I arg
  53 argument from
  54 .BR on_exit ().
  55 .P
  56 The same function may be registered multiple times:
  57 it is called once for each registration.
  58 .P
  59 When a child process is created via
  60 .BR fork (2),
  61 it inherits copies of its parent's registrations.
  62 Upon a successful call to one of the
  63 .BR exec (3)
  64 functions, all registrations are removed.
  65 .SH RETURN VALUE
  66 The
  67 .BR on_exit ()
  68 function returns the value 0 if successful; otherwise
  69 it returns a nonzero value.
  70 .SH ATTRIBUTES
  71 For an explanation of the terms used in this section, see
  72 .BR attributes (7).
  73 .TS
  74 allbox;
  75 lbx lb lb
  76 l l l.
  77 Interface       Attribute       Value
  78 T{
  79 .na
  80 .nh
  81 .BR on_exit ()
  82 T}      Thread safety   MT-Safe
  83 .TE
  84 .SH STANDARDS
  85 None.
  86 .SH HISTORY
  87 SunOS 4, glibc.
  88 Removed in Solaris (SunOS 5).
  89 Use the standard
  90 .BR atexit (3)
  91 instead.
  92 .SH CAVEATS
  93 By the time
  94 .I function
  95 is executed, stack
  96 .RI ( auto )
  97 variables may already have gone out of scope.
  98 Therefore,
  99 .I arg
 100 should not be a pointer to a stack variable;
 101 it may however be a pointer to a heap variable or a global variable.
 102 .SH SEE ALSO
 103 .BR _exit (2),
 104 .BR atexit (3),
 105 .BR exit (3)