#include <pthread.h>
int pthread_mutex_destroy(pthread_mutex_t *mutex);
Threadsafe: Yes
Signal Safe: Yes

The pthread_mutex_destroy() function destroys the named mutex. The destroyed mutex can no longer be used.

If pthread_mutex_destroy() is called on a mutex that is locked by another thread, the request will fail with an EBUSY error. If the calling thread has the mutex locked, any other threads waiting for the mutex via a call to pthread_mutex_lock() at the time of the call to pthread_mutex_destroy() will fail with the EDESTROYED error.

Note that mutex initialization using the PTHREAD_MUTEX_INITIALIZER does not immediately initialize the mutex. Instead, on first use, pthread_mutex_lock() or pthread_mutex_trylock() branches into a slow path and causes the initialization of the mutex. Because a mutex isn't just a simple memory object, and requires that some resources be allocated by the system, an attempt to call pthread_mutex_destroy() or pthread_mutex_unlock() on a mutex that has was statically initialized using PTHREAD_MUTEX_INITIALER and was not yet locked will result in an EINVAL error.

Every mutex must eventually be destroyed with pthread_mutex_destroy(). The machine will eventually detect the error if a mutex is not destroyed, but the storage is de-allocated or corrupted. The machine will then create LIC log synchronization entries indicating the failure to help you debug the problem. Its possible that large numbers of these entries can effect system performance and hinder debug capabilities for other system problems. Always use pthread_mutex_destroy() before freeing mutex storage to prevent these debug LIC log entries.

Once a mutex is created, it cannot be validly copied or moved to a new location.

Parameters

mutex

(Input) Address of the mutex that will be destroyed

None.

Return Value

0

pthread_mutex_destroy() was successful.

value

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

If pthread_mutex_destroy() 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.

[EBUSY]

The mutex is currently owned by another thread.

[EINVAL]

The value specified for the argument is not correct.

• The <pthread.h> header file. See Header files for Pthread functions
• pthread_mutex_init()--Initialize Mutex
• pthread_mutex_lock()--Lock Mutex
• pthread_mutex_trylock()--Lock Mutex with No Wait
• pthread_mutex_unlock()--Unlock Mutex

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

pthread_mutex_t    mutex;

int main(int argc, char **argv)
{
  int                   rc=0;
  pthread_mutexattr_t   mta;

  printf("Entering testcase\n");

  printf("Create the mutex using the NULL attributes (default)\n");
  rc = pthread_mutex_init(&mutex, NULL);
  checkResults("pthread_mutex_init(NULL)\n", rc);
  
  printf("Destroy all mutexes\n");

  pthread_mutex_destroy(&mutex);
  checkResults("pthread_mutex_destroy()\n", rc);
  
  printf("Main completed\n");
  return 0;
}

Entering testcase
Create the mutex using the NULL attributes (default)
Destroy all mutexes
Main completed