atexit: Call a function at normal program termination

The atexit function records a function, pointed to by func that the z/TPF system calls at normal program termination. Normal program termination is the result of calling the exit function, returning from the main function, or calling the Basic Assembler Language (BAL) EXITC macro.

You can use the atexit function to register as many as 32 functions. The registered functions are called in reverse order. The registered functions must return to ensure that all registered functions are called.

Format

#include <stdlib.h>         
int atexit(void (*func)(void));

func: A pointer to a function to be called at normal program termination.

Normal return

A zero value indicates that the function has completed successfully.

Error return

A nonzero value indicates that the function has not completed successfully.

Programming considerations

The atexit function does not support registering function pointers returned from other C load modules. The z/TPF system does not support the use of a function pointer returned from another C load module. You can use atexit to register a library function, C shared object (CSO), or function that is contained in the same C load module as the call to atexit.
The atexit function handles writable static for functions that are registered in C load modules other than the one that causes the entry control block (ECB) to exit.
If the atexit function is called in a C load module other than the one that causes the ECB to exit, ensure that the C load module containing the registered function is still in main storage when the ECB exits.
If the ECB runs on more than one I-stream or in more than one subsystem, functions registered by atexit may run on an I-stream or subsystem different from the one where they were registered. The registered function must ensure that it can run correctly when the process ends normally.
For example, if a process that runs on more than one I-stream calls atexit to register a function that accesses I-stream unique globals, the registered function must determine if it is running on the required I-stream and, if it is not, either switch itself to the correct I-stream or return without accessing the I-stream unique globals.
It is not possible to unregister a function that has previously been registered by calling atexit.
A registered function must take into account any conditions at normal program termination that can affect its ability to run.
If multiple atexit functions are registered and one does not exit normally, the remaining atexit functions will not be called.

Examples

The following example uses the atexit function to call the goodbye() function at normal program termination.

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

void goodbye(void);

int main(void)
{
   int rc;

   rc = atexit(goodbye);
   if (rc != 0)
      puts("Error in atexit.");

   return 0;
}

void goodbye(void)
{   /* This function is called at normal program termination. */
   puts("The goodbye() function was called at program termination.");
}

Output

The goodbye() function was called at program termination.

Related information

exit: Exit an ECB.

See Programming support for z/TPF file system support for more information about z/TPF file system C functions.

See z/TPF C functions overview for more information about z/TPF C/C++ language support.