NAME
pthread_cleanup_pop(), pthread_cleanup_push() — remove or register a cancellation cleanup handler
SYNOPSIS
#include <pthread.h>
void pthread_cleanup_push(
void (*routine)(void *),
void *arg
);
void pthread_cleanup_pop(
int execute
);
PARAMETERS
- routine
Routine registered as a cancellation cleanup handler.
- arg
Parameter to be passed to the cancellation cleanup handler
routine().
- execute
Indicates if the popped cancellation cleanup handler is to be executed.
DESCRIPTION
pthread_cleanup_push()
installs the cancellation cleanup handler
routine
onto the calling thread's cancellation cleanup stack.
This handler will be popped from the calling thread's cancellation
cleanup stack and called with the
arg
parameter when any of the following occur:
- (a)
the thread calls
pthread_exit()
or returns from its start routine.
- (b)
the thread acts upon a cancellation request.
- (c)
the thread calls
pthread_cleanup_pop()
with a non-zero
execute
argument.
When a thread terminates, it will execute each of the cancellation
cleanup handlers on its cancellation cleanup stack. These handlers will
be popped and executed in the reverse order that they were installed
(Last-In, First-Out).
pthread_cleanup_pop()
removes the cancellation cleanup handler at the top of the calling
thread's cancellation stack.
If
execute
is non-zero, the cancellation cleanup handler is called after it is
removed from the cancellation stack.
If
execute
is zero, the cancellation cleanup handler is simply removed
and will not be called.
pthread_cleanup_push()
and
pthread_cleanup_pop()
must appear as statements and in pairs within the same lexical scope.
These functions may be macros which contain the opening '{' in the push
function and the closing '}' in the pop function.
Calling
longjmp()
or
siglongjmp()
is undefined if there have been any calls to
pthread_cleanup_push()
or
pthread_cleanup_pop()
made without the matching call since the jump buffer was filled.
Calling
longjmp()
or
siglongjmp()
from inside a cancellation cleanup handler results in undefined behavior
unless the corresponding
setjmp()
or
sigsetjmp()
was also done inside the cancellation cleanup handler.
RETURN VALUE
The
pthread_cleanup_push()
and
pthread_cleanup_pop()
functions must be used as statements.
They do not have return values or errors.
WARNINGS
The functions
pthread_cleanup_push()
and
pthread_cleanup_pop()
must be called in the same lexical scope or the result is undefined behavior.
AUTHOR
pthread_cleanup_push()
and
pthread_cleanup_pop()
were derived from the IEEE POSIX P1003.1c standard.
STANDARDS CONFORMANCE
pthread_cleanup_push(): POSIX 1003.1c.
pthread_cleanup_pop(): POSIX 1003.1c.
Printable version
