pthread_mutexattr_getname_np()--Get Name from Mutex Attributes Object

 #include <pthread.h>
 int pthread_mutexattr_getname_np(const pthread_mutexattr_t *attr, char *name);  

The pthread_mutexattr_getname_np() function retrieves the name attribute associated with the mutex attribute specified by attr. The buffer specified by name must be at least 16 characters in length. If the length of the mutex name is less than or equal to 15 characters, it is null terminated in the output buffer.

By default, each pthread_mutex_t has the name "QP0WMTX UNNAMED" associated with it. The name attribute is used by various i5/OS system utilities to aid in debugging 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.

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

Authorities and Locks

None.

Parameters

attr

(Input) Address of the mutex attributes object

name

(Output) Address of a 16-byte character buffer to receive the name

Return Value

0

pthread_mutexattr_getname_np() was successful.

value

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

Error Conditions

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

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_mutexattr_init()--Initialize Mutex Attributes Object
  
  
• pthread_mutexattr_setname_np()--Set Name in Mutex Attributes Object
  
  
• pthread_mutex_init()--Initialize Mutex

Example

See Code disclaimer information for information pertaining to code examples.

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

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

  printf("Entering testcase\n");

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

  memset(mutexname, 0, sizeof(mutexname));
  printf("Find out what the default name of the mutex is\n");
  rc = pthread_mutexattr_getname_np(&mta, mutexname);
  checkResults("pthread_mutexattr_getname_np()\n", rc);

  printf("The default mutex name will be: %.15s\n", mutexname);
  printf("- At this point, mutexes created with this attribute\n");
  printf("- will show up by name on many i5/OS debug and service screens\n");
  printf("- The default attribute contains a special automatically\n");
  printf("- incrementing name that changes for each mutex created in \n");
  printf("- the process\n");

  printf("Destroy mutex attribute\n");
  rc = pthread_mutexattr_destroy(&mta);
  checkResults("pthread_mutexattr_destroy()\n", rc);
 
  printf("Main completed\n");
  return 0;
}

Output:

Entering testcase
Create a default mutex attribute
Find out what the default name of the mutex is
The default mutex name is: QP0WMTX UNNAMED
- At this point, mutexes created with this attribute
- will show up by name on many i5/OS debug and service screens
- The default attribute contains a special automatically
- incrementing name that changes for each mutex created in 
- the process
Destroy mutex attribute
Main completed