pthread_mutexattr_setname_np()--Set Name in Mutex Attributes Object

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

The pthread_mutexattr_setname_np() function changes the name attribute associated with the mutex attribute specified by attr. 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 attribute 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 i5/OS 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.

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.

Note: This function is not portable.

Authorities and Locks

None.

Parameters

attr

(Input) Address of the mutex attributes object

name

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

Return Value

0

pthread_mutexattr_setname_np() was successful.

value

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

Error Conditions

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

[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_getname_np()--Get Name from Mutex Attributes Object
  
  
• pthread_mutex_initdone()--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 will be: QP0WMTX UNNAMED
The new mutex name will be: <My Mutex>
Destroy mutex attribute
Main completed