Debian Codegraph @

upstream/debian-unstable/man3/pthread_setname_np.3

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