SAS/C Library Reference, Vol. 1

atexit -- Register Program Cleanup Function

SYNOPSIS

 #include <stdlib.h>

 int atexit(void (*func)());

DESCRIPTION

atexit defines a function to be called during program termination, either as the result of a call to exit or a return from the main function. The func argument should be a function with no arguments returning void. Usually, atexit routines are used to free resources allocated by the program that are not freed automatically by the library, such as memory allocated by direct use of GETMAIN or DMSFREE. You can call atexit any number of times, and you can register the same routine more than once, in which case it is called once for each registration.

atexit cleanup routines are called in the opposite order of their registration. They are called before any coprocesses are terminated or open files are closed, but after termination of any active functions. (Thus, a cleanup routine cannot cause execution to resume by issuing longjmp.) A cleanup routine can call exit, which has no effect other than possibly to change the exit code returned to the operating system. In this case, no cleanup routine that was previously called is called again.

It is not possible to deregister a function after it is registered. However, when a load module containing a registered cleanup routine is unloaded using unloadm, the cleanup routine is deregistered automatically.

It is not possible to define additional cleanup routines after program termination starts.

RETURN VALUE

atexit returns 0 if it is successful, or a non-zero value if it is unsuccessful.

The ISO/ANSI Standard for C permits an implementation to enforce an upper limit of 32 registered functions and leaves the results undefined if a registered function calls exit.

USAGE NOTES

Both atexit and blkjmp enable you to intercept calls to the exit function. You should consider the following when deciding which function to use:

atexit is portable and blkjmp is not.
blkjmp cannot intercept return from the main function.
atexit cannot prevent completion of exit but blkjmp can.
blkjmp is used mainly for intercepting termination of an active function, either by exit or by longjmp to a calling routine. atexit has no effect on longjmp calls but can be used without concern for active functions.

EXAMPLE

This example allocates a buffer using the CMS DMSFREE facility and defines an atexit routine to release it because CMS leaves it allocated forever.

  #include <stdlib.h>
  #include <stdio.h>
  #include <dmsfree.h>

  static void cleanup();
  extern char *buffer;
  static unsigned bufsize;

  void getbuf(unsigned int size)
  {
        /* Allocate buffer; check for error.                  */
     if (DMSFREE((size+7)/8, &buffer, FREE_DEF, ERR_RET)){
        puts("Unable to allocate buffer.");
        exit(16);
     }

        /* Save buffer size.                                  */
     bufsize = (size+7)/8;

        /* If exit not defined, cleanup without it and quit.  */
     if (atexit(&cleanup) != 0) {
        cleanup();
        exit(16);
     }
  }

  static void cleanup()
  {
        /* Return buffer at end of execution.                 */
     DMSFRET(bufsize, buffer, MSG_YES, ERR_ABN);
  }

RELATED FUNCTIONS

atcoexit, blkjmp, exit