man3/pthread_setname_np.3

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