pthread_cleanup_peek_np()--Copy Cleanup Handler from Cancellation Cleanup Stack

 #include <pthread.h>
 int pthread_cleanup_peek_np(pthread_cleanup_entry_np_t *entry);    

The pthread_cleanup_peek_np() function returns a copy of the cleanup handler entry that the next call to pthread_cleanup_pop() would pop. The handler remains on the cancellation cleanup stack after the call to pthread_cleanup_peek_np().

During this thread cancellation cleanup, the thread calls cancellation cleanup handlers with cancellation disabled until the last cancellation cleanup handler returns. The handlers are called in Last In, First Out (LIFO) order. Automatic storage for the invocation stack frame of the function that registered the handler is still present when the cancellation cleanup handler is executed.

The pthread_cleanup_push() and the matching pthread_cleanup_pop() call should be in the same lexical scope (that is, same level of brackets {}).

The pthread_cleanup_peek_np() function has no scoping rules.

Note: This function is not portable.

Authorities and Locks

None.

Parameters

None.

Return Value

0

pthread_cleanup_peek_np() was successful.

value

pthread_cleanup_peek_np() was not successful. value is set to indicate the error condition.

Error Conditions

If pthread_cleanup_peek_np() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

[ENOENT]

The cancellation cleanup stack is empty.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_cleanup_pop()--Pop Cleanup Handler off of Cancellation Cleanup Stack
  
  
• pthread_cleanup_push()--Push Cleanup Handler onto Cancellation Cleanup Stack
  
  
• pthread_exit()--Terminate Calling Thread

Example

See Code disclaimer information for information pertaining to code examples.

#define _MULTI_THREADED
#include <pthread.h>
#include <stdio.h>
#include "check.h"

void cleanupHandler1(void *arg) { printf("In Handler 1\n"); return; }
void cleanupHandler2(void *arg) { printf("In Handler 2\n"); return; }
void cleanupHandler3(void *arg) { printf("In Handler 3\n"); return; }
int             args[3] = {0,0,0};

int main(int argc, char **argv)
{
  int                           rc=0;
  pthread_cleanup_entry_np_t    entry;

  printf("Enter Testcase - %s\n", argv[0]);

  printf("Check for absence of cleanup handlers\n");
  rc = pthread_cleanup_peek_np(&entry);
  if (rc != ENOENT) {
    printf("pthread_cleanup_peek_np(), expected ENOENT\n");
    exit(1);
  }
 
  printf("Push some cancellation cleanup handlers\n"); 
  pthread_cleanup_push(cleanupHandler1, &args[0]); 
  pthread_cleanup_push(cleanupHandler2, &args[1]);

  printf("Check for cleanupHandler2\n");
  rc = pthread_cleanup_peek_np(&entry);
  checkResults("pthread_cleanup_peek_np(2)\n", rc);
  if (entry.handler != cleanupHandler2 ||
      entry.arg != &args[1]) {
    printf("Did not get expected handler(2) information!\n");
    exit(1);
  }
 
  pthread_cleanup_push(cleanupHandler3, &args[2]);

  printf("Check for cleanupHandler3\n");
  rc = pthread_cleanup_peek_np(&entry);
  checkResults("pthread_cleanup_peek_np(3)\n", rc);
  if (entry.handler != cleanupHandler3 ||
      entry.arg != &args[2]) {
    printf("Did not get expected handler(3) information!\n");
    exit(1);
  }
 
  pthread_cleanup_pop(0);
  pthread_cleanup_pop(0);
  pthread_cleanup_pop(0);
 
  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPCLPP0
Check for absence of cleanup handlers
Push some cancellation cleanup handlers
Check for cleanupHandler2
Check for cleanupHandler3
Main completed