pthread_setname_np()--Set Thread Name

       #include <pthread.h>
       int pthread_setname_np(pthread_t thread, const char *name);

The pthread_setname_np() function sets the name of the target thread. 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 thread becomes unnamed.

By default, each thread is unnamed. A thread name can be used by various system utilities to aid in debug and service. One example is the WRKJOB command, which has a `Work with threads' menu choice. On the 'Work with Threads' display, unnamed threads are identified only by a system-assigned number. It can be a difficult and time-consuming process to determine which thread is performing a specific function, or creating a particular problem. Naming the threads created by an application can greatly simplify problem analysis.

Note: This function is not portable.

Parameters

thread

(Input) Pthread handle to the target thread

name

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

Authorities and Locks

None.

Return Value

0

pthread_setname_np() was successful.

value

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

Error Conditions

If pthread_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. It is most likely that the thread parameter is not a valid thread handle.

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_getname_np()--Get Thread Name
  
  

Example

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 <string.h>
#include <unistd.h>

void *threadfunc(void *parm)
{
  printf("In the thread.\n");
  sleep(45);  // allow main program to set the thread name
  return NULL;
}

int main(int argc, char **argv)
{
  pthread_t             thread;
  int                   rc=0;
  char                  theName[16];

  memset(theName, 0x00, sizeof(theName));
  printf("Create thread using the default attributes\n");
  rc = pthread_create(&thread, NULL, threadfunc, NULL);
  if(0 == rc)
  {
    rc = pthread_setname_np(thread, "THREADNAMEISTOOLONG");
    sleep(10);
    if(0 == rc)
    {
      rc = pthread_getname_np(thread, theName);
      if(0 == rc)
      {
        printf("The thread name is %s.\n", theName);
      }
    }
    rc = pthread_join(thread, NULL);
  }
  if(0 != rc)
  {
    printf("An error occurred - %d\n", rc);
  }
  printf("Main completed\n");
  return(rc);
}

Create thread using the default attributes
The thread name is THREADNAMEISTOO.
In the thread.
Main completed

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