]>
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 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
5df98ea9 | 5 | .\" |
45186a5d | 6 | .TH PTHREAD_SETNAME_NP 3 2021-08-27 "Linux man-pages (unreleased)" |
5df98ea9 MK |
7 | .SH NAME |
8 | pthread_setname_np, pthread_getname_np \- set/get the name of a thread | |
1cefd9b1 AC |
9 | .SH LIBRARY |
10 | POSIX threads library | |
8fc3b2cf | 11 | .RI ( libpthread ", " \-lpthread ) |
5df98ea9 MK |
12 | .SH SYNOPSIS |
13 | .nf | |
14 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" | |
15 | .B #include <pthread.h> | |
15d65653 | 16 | .PP |
9bfc9cb1 | 17 | .BI "int pthread_setname_np(pthread_t " thread ", const char *" name ); |
15d65653 | 18 | .BI "int pthread_getname_np(pthread_t " thread ", char *" name ", size_t " len ); |
5df98ea9 | 19 | .fi |
5df98ea9 MK |
20 | .SH DESCRIPTION |
21 | By default, all the threads created using | |
e4a83b01 | 22 | .BR pthread_create () |
5df98ea9 | 23 | inherit the program name. |
e4a83b01 MK |
24 | The |
25 | .BR pthread_setname_np () | |
f1a5fff8 | 26 | function can be used to set a unique name for a thread, |
e4a83b01 | 27 | which can be useful for debugging |
ce0234ff | 28 | multithreaded applications. |
5df98ea9 | 29 | The thread name is a meaningful C language string, whose length is |
d1a71985 | 30 | restricted to 16 characters, including the terminating null byte (\(aq\e0\(aq). |
6350e974 MK |
31 | The |
32 | .I thread | |
33 | argument specifies the thread whose name is to be changed; | |
34 | .I name | |
35 | specifies the new name. | |
847e0d88 | 36 | .PP |
5df98ea9 | 37 | The |
e4a83b01 MK |
38 | .BR pthread_getname_np () |
39 | function can be used to retrieve the name of the thread. | |
6350e974 MK |
40 | The |
41 | .I thread | |
3fd9346e | 42 | argument specifies the thread whose name is to be retrieved. |
6350e974 MK |
43 | The buffer |
44 | .I name | |
45 | is used to return the thread name; | |
46 | .I len | |
47 | specifies the number of bytes available in | |
48 | .IR name . | |
e4a83b01 MK |
49 | The buffer specified by |
50 | .I name | |
6350e974 | 51 | should be at least 16 characters in length. |
5df98ea9 MK |
52 | The returned thread name in the output buffer will be null terminated. |
53 | .SH RETURN VALUE | |
54 | On success, these functions return 0; | |
55 | on error, they return a nonzero error number. | |
56 | .SH ERRORS | |
eb6c2cc6 MK |
57 | The |
58 | .BR pthread_setname_np () | |
4a2403ed | 59 | function can fail with the following error: |
5df98ea9 MK |
60 | .TP |
61 | .B ERANGE | |
e4a83b01 MK |
62 | The length of the string specified pointed to by |
63 | .I name | |
64 | exceeds the allowed limit. | |
65 | .PP | |
4a2403ed MK |
66 | The |
67 | .BR pthread_getname_np () | |
68 | function can fail with the following error: | |
69 | .TP | |
70 | .B ERANGE | |
71 | The buffer specified by | |
72 | .I name | |
73 | and | |
74 | .I len | |
75 | is too small to hold the thread name. | |
76 | .PP | |
e4a83b01 MK |
77 | If either of these functions fails to open |
78 | .IR /proc/self/task/[tid]/comm , | |
79 | then the call may fail with one of the errors described in | |
80 | .BR open (2). | |
fbc7552a MK |
81 | .SH VERSIONS |
82 | These functions first appeared in glibc in version 2.12. | |
412793f9 ZL |
83 | .SH ATTRIBUTES |
84 | For an explanation of the terms used in this section, see | |
85 | .BR attributes (7). | |
c466875e MK |
86 | .ad l |
87 | .nh | |
412793f9 ZL |
88 | .TS |
89 | allbox; | |
c466875e | 90 | lbx lb lb |
412793f9 ZL |
91 | l l l. |
92 | Interface Attribute Value | |
93 | T{ | |
94 | .BR pthread_setname_np (), | |
95 | .BR pthread_getname_np () | |
96 | T} Thread safety MT-Safe | |
97 | .TE | |
c466875e MK |
98 | .hy |
99 | .ad | |
847e0d88 | 100 | .sp 1 |
3113c7f3 | 101 | .SH STANDARDS |
3ceb0d18 JW |
102 | These functions are nonstandard GNU extensions; |
103 | hence the suffix "_np" (nonportable) in the names. | |
5df98ea9 | 104 | .SH NOTES |
e4a83b01 | 105 | .BR pthread_setname_np () |
f2cc5c88 | 106 | internally writes to the thread-specific |
7d4d1f8a | 107 | .I comm |
f2cc5c88 | 108 | file under the |
1ae6b2c7 | 109 | .I /proc |
5df98ea9 | 110 | filesystem: |
e4a83b01 MK |
111 | .IR /proc/self/task/[tid]/comm . |
112 | .BR pthread_getname_np () | |
3fd9346e | 113 | retrieves it from the same location. |
a14af333 | 114 | .SH EXAMPLES |
5df98ea9 | 115 | The program below demonstrates the use of |
e4a83b01 MK |
116 | .BR pthread_setname_np () |
117 | and | |
5df98ea9 | 118 | .BR pthread_getname_np (). |
847e0d88 | 119 | .PP |
5df98ea9 | 120 | The following shell session shows a sample run of the program: |
e646a1ba | 121 | .PP |
5df98ea9 | 122 | .in +4n |
e646a1ba | 123 | .EX |
e4a83b01 | 124 | .RB "$" " ./a.out" |
5df98ea9 MK |
125 | Created a thread. Default name is: a.out |
126 | The thread name after setting it is THREADFOO. | |
9ca13180 | 127 | \fB\(haZ\fP # Suspend the program |
6cfa298b | 128 | [1]+ Stopped ./a.out |
861d36ba | 129 | .RB "$ " "ps H \-C a.out \-o \(aqpid tid cmd comm\(aq" |
6cfa298b MK |
130 | PID TID CMD COMMAND |
131 | 5990 5990 ./a.out a.out | |
132 | 5990 5991 ./a.out THREADFOO | |
133 | .RB "$ " "cat /proc/5990/task/5990/comm" | |
134 | a.out | |
135 | .RB "$ " "cat /proc/5990/task/5991/comm" | |
136 | THREADFOO | |
b8302363 | 137 | .EE |
5df98ea9 | 138 | .in |
5df98ea9 MK |
139 | .SS Program source |
140 | \& | |
e7d0bb47 | 141 | .EX |
5df98ea9 | 142 | #define _GNU_SOURCE |
5df98ea9 MK |
143 | #include <pthread.h> |
144 | #include <stdio.h> | |
145 | #include <string.h> | |
146 | #include <unistd.h> | |
147 | #include <errno.h> | |
148 | #include <stdlib.h> | |
149 | ||
150 | #define NAMELEN 16 | |
151 | ||
d1a71985 | 152 | #define errExitEN(en, msg) \e |
49f06c00 MK |
153 | do { errno = en; perror(msg); \e |
154 | exit(EXIT_FAILURE); } while (0) | |
5df98ea9 | 155 | |
30a87638 MK |
156 | static void * |
157 | threadfunc(void *parm) | |
5df98ea9 | 158 | { |
b615a97e | 159 | sleep(5); // allow main program to set the thread name |
5df98ea9 MK |
160 | return NULL; |
161 | } | |
162 | ||
30a87638 | 163 | int |
aa1f53cc | 164 | main(int argc, char *argv[]) |
5df98ea9 MK |
165 | { |
166 | pthread_t thread; | |
167 | int rc; | |
168 | char thread_name[NAMELEN]; | |
169 | ||
170 | rc = pthread_create(&thread, NULL, threadfunc, NULL); | |
b615a97e MK |
171 | if (rc != 0) |
172 | errExitEN(rc, "pthread_create"); | |
e4a83b01 | 173 | |
5df98ea9 | 174 | rc = pthread_getname_np(thread, thread_name, NAMELEN); |
b615a97e MK |
175 | if (rc != 0) |
176 | errExitEN(rc, "pthread_getname_np"); | |
91e38d87 | 177 | |
d1a71985 | 178 | printf("Created a thread. Default name is: %s\en", thread_name); |
e49d4430 | 179 | rc = pthread_setname_np(thread, (argc > 1) ? argv[1] : "THREADFOO"); |
b615a97e MK |
180 | if (rc != 0) |
181 | errExitEN(rc, "pthread_setname_np"); | |
e4a83b01 | 182 | |
5df98ea9 | 183 | sleep(2); |
36127c0e | 184 | |
44a16bcb | 185 | rc = pthread_getname_np(thread, thread_name, NAMELEN); |
b615a97e MK |
186 | if (rc != 0) |
187 | errExitEN(rc, "pthread_getname_np"); | |
d1a71985 | 188 | printf("The thread name after setting it is %s.\en", thread_name); |
36127c0e | 189 | |
5df98ea9 | 190 | rc = pthread_join(thread, NULL); |
b615a97e MK |
191 | if (rc != 0) |
192 | errExitEN(rc, "pthread_join"); | |
36127c0e | 193 | |
d1a71985 | 194 | printf("Done\en"); |
5df98ea9 MK |
195 | exit(EXIT_SUCCESS); |
196 | } | |
e7d0bb47 | 197 | .EE |
5df98ea9 MK |
198 | .SH SEE ALSO |
199 | .ad l | |
200 | .nh | |
201 | .BR prctl (2), | |
202 | .BR pthread_create (3), | |
203 | .BR pthreads (7) |