Manual pages: renmae man->man3 to follow existing conventions. Add files _Exit.3...

[pdclib.old] / man3 / atexit.3

diff --git a/man3/atexit.3 b/man3/atexit.3
new file mode 100644 (file)
index 0000000..a210266
--- /dev/null
+++ b/man3/atexit.3
@@ -0,0 +1,100 @@
+.\" This file is part of the Public Domain C Library (PDCLib).\r
+.\" Permission is granted to use, modify, and / or redistribute at will.\r
+.\"\r
+.Dd\r
+.Dt atexit 3\r
+.Os\r
+\r
+.Sh NAME\r
+.Nm atexit\r
+.Nd registration of functions to be invoked before process termination\r
+\r
+.Sh SYNOPSIS\r
+.In stdlib.h\r
+.Fn "int atexit" "void (*handler)(void)"\r
+.Fn "int at_quick_exit" "void (*handler)(void)" \r
+(C11, C++11)\r
+\r
+.Sh DESCRIPTION\r
+These functions register a function to be called when the corresponding process\r
+exit function is invoked. For\r
+.Fn atexit \r
+the function will be invoked when the process is terminated by calling\r
+.Fn exit ;\r
+for\r
+.Fn at_quick_exit\r
+the function will be invoked when the process is terminated by calling\r
+.Fn quick_exit .\r
+\r
+.Pp\r
+These functions are used in order to permit a program to perform actions before\r
+a process is terminated; for example, releasing an interprocess semaphore. \r
+Special care should be taken when writing \r
+.Fn at_quick_exit\r
+handlers; the purpose of \r
+.Fn quick_exit\r
+is to support the abandonning of a process when normal process termination might\r
+not be possible; at_quick_exit handlers should therefore be used sparingly and\r
+only when their use is essential.\r
+\r
+.Pp\r
+The standard guarantees that \r
+.Fn atexit\r
+and\r
+.Fn at_quick_exit\r
+may each be called at least 32 times successfully.\r
+\r
+.Pp\r
+.Fn atexit \r
+and\r
+.Fn at_quick_exit\r
+handlers are called in reverse order of the order they were registered in. For\r
+precise details of their ordering, see\r
+.Xr exit 3 .\r
+\r
+.Pp\r
+The result of exiting from a handler registered with\r
+.Fn atexit\r
+or\r
+.Fn at_quick_exit\r
+by use of \r
+.Fn longjmp\r
+is undefined. If any function or destructor invoked by\r
+.Fn exit\r
+or\r
+.Fn quick_exit\r
+should throw, \r
+.Fn std::terminate\r
+is invoked.\r
+\r
+.Pp\r
+Undefined behaviour results if an \r
+.Fn atexit\r
+or\r
+.Fn at_quick_exit\r
+handler calls\r
+.Fn exit\r
+or\r
+.Fn quick_exit . \r
+\r
+.Sh RETURN VALUES\r
+Returns 0 to indicate success; nonzero returns indicate failure.\r
+\r
+.Sh ERRORS\r
+No errors are defined\r
+\r
+.Sh SEE ALSO\r
+.Xr abort 3\r
+.Xr exit 3\r
+.Xr quick_exit 3\r
+.Xr _Exit 3\r
+\r
+.Sh STANDARDS\r
+.Fn atexit\r
+is first defined in\r
+.St -isoC-90 ;\r
+.Fn at_quick_exit\r
+was introduced in\r
+.St -isoC-2011 \r
+and\r
+ISO/IEC 14882:2011 "C++ 2011" .
\ No newline at end of file