pthread_setname_np(3)

1pthread_setname_np(3)      Library Functions Manual      pthread_setname_np(3)
2
3
4

NAME

6       pthread_setname_np, pthread_getname_np - set/get the name of a thread
7

LIBRARY

9       POSIX threads library (libpthread, -lpthread)
10

SYNOPSIS

12       #define _GNU_SOURCE             /* See feature_test_macros(7) */
13       #include <pthread.h>
14
15       int pthread_setname_np(pthread_t thread, const char *name);
16       int pthread_getname_np(pthread_t thread, char name[.size], size_t size);
17

DESCRIPTION

19       By  default, all the threads created using pthread_create() inherit the
20       program name.  The pthread_setname_np() function can be used to  set  a
21       unique  name  for  a  thread,  which can be useful for debugging multi‐
22       threaded applications.  The thread name  is  a  meaningful  C  language
23       string, whose length is restricted to 16 characters, including the ter‐
24       minating null byte ('\0').  The thread argument  specifies  the  thread
25       whose name is to be changed; name specifies the new name.
26
27       The  pthread_getname_np()  function can be used to retrieve the name of
28       the thread.  The thread argument specifies the thread whose name is  to
29       be  retrieved.  The buffer name is used to return the thread name; size
30       specifies the number of bytes available in name.  The buffer  specified
31       by  name  should  be  at  least  16 characters in length.  The returned
32       thread name in the output buffer will be null terminated.
33

RETURN VALUE

35       On success, these functions return 0; on error, they return  a  nonzero
36       error number.
37

ERRORS

39       The pthread_setname_np() function can fail with the following error:
40
41       ERANGE The  length  of  the string specified pointed to by name exceeds
42              the allowed limit.
43
44       The pthread_getname_np() function can fail with the following error:
45
46       ERANGE The buffer specified by name and size is too small to  hold  the
47              thread name.
48
49       If  either  of  these functions fails to open /proc/self/task/tid/comm,
50       then the call may fail with one of the errors described in open(2).
51

ATTRIBUTES

53       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
54       tributes(7).
55
56       ┌────────────────────────────────────────────┬───────────────┬─────────┐
57       │Interface                                   │ Attribute     │ Value   │
58       ├────────────────────────────────────────────┼───────────────┼─────────┤
59       │pthread_setname_np(), pthread_getname_np()  │ Thread safety │ MT-Safe │
60       └────────────────────────────────────────────┴───────────────┴─────────┘
61

STANDARDS

63       GNU; hence the suffix "_np" (nonportable) in the names.
64

HISTORY

66       glibc 2.12.
67

NOTES

69       pthread_setname_np() internally writes to the thread-specific comm file
70       under     the     /proc      filesystem:      /proc/self/task/tid/comm.
71       pthread_getname_np() retrieves it from the same location.
72

EXAMPLES

74       The  program  below  demonstrates  the  use of pthread_setname_np() and
75       pthread_getname_np().
76
77       The following shell session shows a sample run of the program:
78
79           $ ./a.out
80           Created a thread. Default name is: a.out
81           The thread name after setting it is THREADFOO.
82           ^Z                           # Suspend the program
83           [1]+  Stopped           ./a.out
84           $ ps H -C a.out -o 'pid tid cmd comm'
85             PID   TID CMD                         COMMAND
86            5990  5990 ./a.out                     a.out
87            5990  5991 ./a.out                     THREADFOO
88           $ cat /proc/5990/task/5990/comm
89           a.out
90           $ cat /proc/5990/task/5991/comm
91           THREADFOO
92
93   Program source
94
95       #define _GNU_SOURCE
96       #include <err.h>
97       #include <errno.h>
98       #include <pthread.h>
99       #include <stdio.h>
100       #include <stdlib.h>
101       #include <string.h>
102       #include <unistd.h>
103
104       #define NAMELEN 16
105
106       static void *
107       threadfunc(void *parm)
108       {
109           sleep(5);          // allow main program to set the thread name
110           return NULL;
111       }
112
113       int
114       main(int argc, char *argv[])
115       {
116           pthread_t thread;
117           int rc;
118           char thread_name[NAMELEN];
119
120           rc = pthread_create(&thread, NULL, threadfunc, NULL);
121           if (rc != 0)
122               errc(EXIT_FAILURE, rc, "pthread_create");
123
124           rc = pthread_getname_np(thread, thread_name, NAMELEN);
125           if (rc != 0)
126               errc(EXIT_FAILURE, rc, "pthread_getname_np");
127
128           printf("Created a thread. Default name is: %s\n", thread_name);
129           rc = pthread_setname_np(thread, (argc > 1) ? argv[1] : "THREADFOO");
130           if (rc != 0)
131               errc(EXIT_FAILURE, rc, "pthread_setname_np");
132
133           sleep(2);
134
135           rc = pthread_getname_np(thread, thread_name, NAMELEN);
136           if (rc != 0)
137               errc(EXIT_FAILURE, rc, "pthread_getname_np");
138           printf("The thread name after setting it is %s.\n", thread_name);
139
140           rc = pthread_join(thread, NULL);
141           if (rc != 0)
142               errc(EXIT_FAILURE, rc, "pthread_join");
143
144           printf("Done\n");
145           exit(EXIT_SUCCESS);
146       }
147