pthread_mutex_setname_np()--Set Name in Mutex

 #include <pthread.h>
 int pthread_mutex_setname_np(pthread_mutex_t *mutex,  
                              const char *name);

The pthread_mutex_setname_np() function sets the name of the specified mutex. The buffer specified by name must contain a null terminated string of 15 characters or less in length (not including the NULL). If the length of name is greater than 15 characters, the excess characters are ignored. If name is null, the mutex name is reset to the default.

By default, each pthread_mutex_t has the name "QP0WMTX UNNAMED" associated with it. The name attribute is used by various IBM i system utilities to aid in debug and service. One example is the WRKJOB command, which has a `work with mutexes' menu choice to show which mutexes are currently locked and which mutexes are being waited for.

You should give unique names to all mutexes created to aid in debugging deadlock or performance problems. Use the CL command WRKJOB, option 20, to help debug mutex deadlocks.

Note: This function is not portable.

Parameters

mutex

(Input) The address of the mutex object

name

(Input) Address of a null terminated character buffer containing the name

Authorities and Locks

None.

Return Value

0

pthread_mutex_setname_np() was successful.

value

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

Error Conditions

If pthread_mutex_setname_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.

Usage Notes

• No CCSID conversion is performed when storing or displaying the name.
  
  

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_mutex_getname_np()--Get Name From Mutex
  
  
• pthread_mutex_init()--Initialize Mutex
  
  
• pthread_mutex_destroy()--Destroy Mutex
  
  

Example

The following example will set the mutex name.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

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

pthread_mutex_t    mutex;

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

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

  printf("Create a default mutex attribute\n");
  rc = pthread_mutexattr_init(&mta);
  checkResults("pthread_mutexattr_init\n", rc);

  printf("Create the mutex using a mutex attributes object\n");
  rc = pthread_mutex_init(&mutex, &mta);
  checkResults("pthread_mutex_init(mta)\n", rc);

  memset(mutexName, 0, sizeof(mutexName));
  strcpy(mutexName,"MUTEX1");
  printf("Set the name of the mutex\n");
  rc = pthread_mutex_setname_np(&mutex, mutexName);
  checkResults("pthread_mutex_setname_np\n", rc);

  memset(mutexName, 0, sizeof(mutexName));
  printf("Get the name of the mutex\n");
  rc = pthread_mutex_getname_np(&mutex, mutexName);
  checkResults("pthread_mutex_getname_np\n", rc);
  printf("The mutex name is: %.15s\n", mutexName);

  printf("Destroy the mutex\n");
  pthread_mutex_destroy(&mutex);

  printf("Main completed\n");
  return 0;
}

Enter Testcase - QP0WTEST/TPCRT0
Create a default mutex attribute
Create the mutex using a mutex attributes object
Set the name of the mutex
Get the name of the mutex
The mutex name is: MUTEX1
Destroy the mutex
Main completed

[ Back to top | Pthread APIs | APIs by category ]