1PTHREAD_SETNAME_NP(3)      Linux Programmer's Manual     PTHREAD_SETNAME_NP(3)
2
3
4

NAME

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

SYNOPSIS

9       #define _GNU_SOURCE             /* See feature_test_macros(7) */
10       #include <pthread.h>
11       int pthread_setname_np(pthread_t thread, const char *name);
12       int pthread_getname_np(pthread_t thread,
13                              char *name, size_t len);
14
15       Compile and link with -pthread.
16

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

VERSIONS

52       These functions first appeared in glibc in version 2.12.
53

ATTRIBUTES

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

CONFORMING TO

66       These functions are nonstandard GNU extensions; hence the suffix  "_np"
67       (nonportable) in the names.
68

NOTES

70       pthread_setname_np() internally writes to the thread-specific comm file
71       under the /proc filesystem:  /proc/self/task/[tid]/comm.   pthread_get‐
72       name_np() retrieves it from the same location.
73

EXAMPLES

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

SEE ALSO

154       prctl(2), pthread_create(3), pthreads(7)
155

COLOPHON

157       This page is part of release 5.07 of the Linux man-pages project.  A
158       description of the project, information about reporting bugs, and the
159       latest version of this page, can be found at
160       https://www.kernel.org/doc/man-pages/.
161
162
163
164Linux                             2020-06-09             PTHREAD_SETNAME_NP(3)
Impressum