]>
Commit | Line | Data |
---|---|---|
5df98ea9 | 1 | .\" Copyright (C) 2012 Chandan Apsangi <chandan.jc@gmail.com> |
7d928e0d | 2 | .\" and Copyright (C) 2013 Michael Kerrisk <mtk.manpages@gmail.com> |
5df98ea9 | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
5df98ea9 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
5df98ea9 | 25 | .\" |
9ba01802 | 26 | .TH PTHREAD_SETNAME_NP 3 2019-03-06 "Linux" "Linux Programmer's Manual" |
5df98ea9 MK |
27 | .SH NAME |
28 | pthread_setname_np, pthread_getname_np \- set/get the name of a thread | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" | |
32 | .B #include <pthread.h> | |
1ba74ca2 AC |
33 | .BI "int pthread_setname_np(pthread_t " thread ", const char *" name "); |
34 | .BI "int pthread_getname_np(pthread_t " thread , | |
3ea70557 | 35 | .BI " char *" name ", size_t " len ); |
5df98ea9 | 36 | .fi |
68e4db0a | 37 | .PP |
5df98ea9 MK |
38 | Compile and link with \fI\-pthread\fP. |
39 | .SH DESCRIPTION | |
40 | By default, all the threads created using | |
e4a83b01 | 41 | .BR pthread_create () |
5df98ea9 | 42 | inherit the program name. |
e4a83b01 MK |
43 | The |
44 | .BR pthread_setname_np () | |
f1a5fff8 | 45 | function can be used to set a unique name for a thread, |
e4a83b01 | 46 | which can be useful for debugging |
ce0234ff | 47 | multithreaded applications. |
5df98ea9 | 48 | The thread name is a meaningful C language string, whose length is |
d1a71985 | 49 | restricted to 16 characters, including the terminating null byte (\(aq\e0\(aq). |
6350e974 MK |
50 | The |
51 | .I thread | |
52 | argument specifies the thread whose name is to be changed; | |
53 | .I name | |
54 | specifies the new name. | |
847e0d88 | 55 | .PP |
5df98ea9 | 56 | The |
e4a83b01 MK |
57 | .BR pthread_getname_np () |
58 | function can be used to retrieve the name of the thread. | |
6350e974 MK |
59 | The |
60 | .I thread | |
3fd9346e | 61 | argument specifies the thread whose name is to be retrieved. |
6350e974 MK |
62 | The buffer |
63 | .I name | |
64 | is used to return the thread name; | |
65 | .I len | |
66 | specifies the number of bytes available in | |
67 | .IR name . | |
e4a83b01 MK |
68 | The buffer specified by |
69 | .I name | |
6350e974 | 70 | should be at least 16 characters in length. |
5df98ea9 MK |
71 | The returned thread name in the output buffer will be null terminated. |
72 | .SH RETURN VALUE | |
73 | On success, these functions return 0; | |
74 | on error, they return a nonzero error number. | |
75 | .SH ERRORS | |
eb6c2cc6 MK |
76 | The |
77 | .BR pthread_setname_np () | |
4a2403ed | 78 | function can fail with the following error: |
5df98ea9 MK |
79 | .TP |
80 | .B ERANGE | |
e4a83b01 MK |
81 | The length of the string specified pointed to by |
82 | .I name | |
83 | exceeds the allowed limit. | |
84 | .PP | |
4a2403ed MK |
85 | The |
86 | .BR pthread_getname_np () | |
87 | function can fail with the following error: | |
88 | .TP | |
89 | .B ERANGE | |
90 | The buffer specified by | |
91 | .I name | |
92 | and | |
93 | .I len | |
94 | is too small to hold the thread name. | |
95 | .PP | |
e4a83b01 MK |
96 | If either of these functions fails to open |
97 | .IR /proc/self/task/[tid]/comm , | |
98 | then the call may fail with one of the errors described in | |
99 | .BR open (2). | |
fbc7552a MK |
100 | .SH VERSIONS |
101 | These functions first appeared in glibc in version 2.12. | |
412793f9 ZL |
102 | .SH ATTRIBUTES |
103 | For an explanation of the terms used in this section, see | |
104 | .BR attributes (7). | |
105 | .TS | |
106 | allbox; | |
107 | lbw21 lb lb | |
108 | l l l. | |
109 | Interface Attribute Value | |
110 | T{ | |
111 | .BR pthread_setname_np (), | |
112 | .BR pthread_getname_np () | |
113 | T} Thread safety MT-Safe | |
114 | .TE | |
847e0d88 | 115 | .sp 1 |
c2ba212d | 116 | .SH CONFORMING TO |
3ceb0d18 JW |
117 | These functions are nonstandard GNU extensions; |
118 | hence the suffix "_np" (nonportable) in the names. | |
5df98ea9 | 119 | .SH NOTES |
e4a83b01 | 120 | .BR pthread_setname_np () |
f2cc5c88 | 121 | internally writes to the thread-specific |
7d4d1f8a | 122 | .I comm |
f2cc5c88 | 123 | file under the |
5df98ea9 MK |
124 | .IR /proc |
125 | filesystem: | |
e4a83b01 MK |
126 | .IR /proc/self/task/[tid]/comm . |
127 | .BR pthread_getname_np () | |
3fd9346e | 128 | retrieves it from the same location. |
5df98ea9 MK |
129 | .SH EXAMPLE |
130 | .PP | |
131 | The program below demonstrates the use of | |
e4a83b01 MK |
132 | .BR pthread_setname_np () |
133 | and | |
5df98ea9 | 134 | .BR pthread_getname_np (). |
847e0d88 | 135 | .PP |
5df98ea9 | 136 | The following shell session shows a sample run of the program: |
e646a1ba | 137 | .PP |
5df98ea9 | 138 | .in +4n |
e646a1ba | 139 | .EX |
e4a83b01 | 140 | .RB "$" " ./a.out" |
5df98ea9 MK |
141 | Created a thread. Default name is: a.out |
142 | The thread name after setting it is THREADFOO. | |
6cfa298b MK |
143 | \fB^Z\fP # Suspend the program |
144 | [1]+ Stopped ./a.out | |
145 | .RB "$ " "ps H -C a.out -o 'pid tid cmd comm'" | |
146 | PID TID CMD COMMAND | |
147 | 5990 5990 ./a.out a.out | |
148 | 5990 5991 ./a.out THREADFOO | |
149 | .RB "$ " "cat /proc/5990/task/5990/comm" | |
150 | a.out | |
151 | .RB "$ " "cat /proc/5990/task/5991/comm" | |
152 | THREADFOO | |
b8302363 | 153 | .EE |
5df98ea9 | 154 | .in |
5df98ea9 MK |
155 | .SS Program source |
156 | \& | |
e7d0bb47 | 157 | .EX |
5df98ea9 | 158 | #define _GNU_SOURCE |
5df98ea9 MK |
159 | #include <pthread.h> |
160 | #include <stdio.h> | |
161 | #include <string.h> | |
162 | #include <unistd.h> | |
163 | #include <errno.h> | |
164 | #include <stdlib.h> | |
165 | ||
166 | #define NAMELEN 16 | |
167 | ||
d1a71985 MK |
168 | #define errExitEN(en, msg) \e |
169 | do { errno = en; perror(msg); exit(EXIT_FAILURE); \e | |
5df98ea9 MK |
170 | } while (0) |
171 | ||
30a87638 MK |
172 | static void * |
173 | threadfunc(void *parm) | |
5df98ea9 | 174 | { |
b615a97e | 175 | sleep(5); // allow main program to set the thread name |
5df98ea9 MK |
176 | return NULL; |
177 | } | |
178 | ||
30a87638 MK |
179 | int |
180 | main(int argc, char **argv) | |
5df98ea9 MK |
181 | { |
182 | pthread_t thread; | |
183 | int rc; | |
184 | char thread_name[NAMELEN]; | |
185 | ||
186 | rc = pthread_create(&thread, NULL, threadfunc, NULL); | |
b615a97e MK |
187 | if (rc != 0) |
188 | errExitEN(rc, "pthread_create"); | |
e4a83b01 | 189 | |
5df98ea9 | 190 | rc = pthread_getname_np(thread, thread_name, NAMELEN); |
b615a97e MK |
191 | if (rc != 0) |
192 | errExitEN(rc, "pthread_getname_np"); | |
91e38d87 | 193 | |
d1a71985 | 194 | printf("Created a thread. Default name is: %s\en", thread_name); |
e49d4430 | 195 | rc = pthread_setname_np(thread, (argc > 1) ? argv[1] : "THREADFOO"); |
b615a97e MK |
196 | if (rc != 0) |
197 | errExitEN(rc, "pthread_setname_np"); | |
e4a83b01 | 198 | |
5df98ea9 | 199 | sleep(2); |
36127c0e | 200 | |
101d0a57 MK |
201 | rc = pthread_getname_np(thread, thread_name, |
202 | (argc > 2) ? atoi(argv[1]) : NAMELEN); | |
b615a97e MK |
203 | if (rc != 0) |
204 | errExitEN(rc, "pthread_getname_np"); | |
d1a71985 | 205 | printf("The thread name after setting it is %s.\en", thread_name); |
36127c0e | 206 | |
5df98ea9 | 207 | rc = pthread_join(thread, NULL); |
b615a97e MK |
208 | if (rc != 0) |
209 | errExitEN(rc, "pthread_join"); | |
36127c0e | 210 | |
d1a71985 | 211 | printf("Done\en"); |
5df98ea9 MK |
212 | exit(EXIT_SUCCESS); |
213 | } | |
e7d0bb47 | 214 | .EE |
5df98ea9 MK |
215 | .SH SEE ALSO |
216 | .ad l | |
217 | .nh | |
218 | .BR prctl (2), | |
219 | .BR pthread_create (3), | |
220 | .BR pthreads (7) |