2013-02-02 20:13:36 +00:00
|
|
|
.\" Copyright (C) 2012 Chandan Apsangi <chandan.jc@gmail.com>
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
2013-02-02 20:34:47 +00:00
|
|
|
.TH PTHREAD_SETNAME_NP 3 2013-02-04 "Linux" "Linux Programmer's Manual"
|
2013-02-02 20:13:36 +00:00
|
|
|
.SH NAME
|
|
|
|
pthread_setname_np, pthread_getname_np \- set/get the name of a thread
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
|
|
|
.B #include <pthread.h>
|
|
|
|
.BI "int pthread_setname_np(pthread_t *" thread ", const char *" name ");
|
2013-02-02 20:34:47 +00:00
|
|
|
.BI "int pthread_getname_np(pthread_t *" thread ,
|
|
|
|
.BI " const char *" name ", size_t " len );
|
2013-02-02 20:13:36 +00:00
|
|
|
.fi
|
|
|
|
.sp
|
|
|
|
Compile and link with \fI\-pthread\fP.
|
|
|
|
.SH DESCRIPTION
|
|
|
|
By default, all the threads created using
|
2013-02-02 20:34:47 +00:00
|
|
|
.BR pthread_create ()
|
2013-02-02 20:13:36 +00:00
|
|
|
inherit the program name.
|
2013-02-02 20:34:47 +00:00
|
|
|
The
|
|
|
|
.BR pthread_setname_np ()
|
|
|
|
fuction can be used to set a unique name for a thread,
|
|
|
|
which can be useful for debugging
|
2013-02-02 20:13:36 +00:00
|
|
|
multi-threaded applications.
|
|
|
|
The thread name is a meaningful C language string, whose length is
|
2013-02-02 20:35:09 +00:00
|
|
|
restricted to 16 characters, including the terminating null byte.
|
2013-02-02 20:13:36 +00:00
|
|
|
|
|
|
|
The
|
2013-02-02 20:34:47 +00:00
|
|
|
.BR pthread_getname_np ()
|
|
|
|
function can be used to retrieve the name of the thread.
|
|
|
|
The buffer specified by
|
|
|
|
.I name
|
|
|
|
must be at least 16 characters in length.
|
2013-02-02 20:13:36 +00:00
|
|
|
The returned thread name in the output buffer will be null terminated.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
On success, these functions return 0;
|
|
|
|
on error, they return a nonzero error number.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B ERANGE
|
2013-02-02 20:34:47 +00:00
|
|
|
.RB ( pthread_setname_np ())
|
|
|
|
The length of the string specified pointed to by
|
|
|
|
.I name
|
|
|
|
exceeds the allowed limit.
|
|
|
|
.PP
|
|
|
|
If either of these functions fails to open
|
|
|
|
.IR /proc/self/task/[tid]/comm ,
|
|
|
|
then the call may fail with one of the errors described in
|
|
|
|
.BR open (2).
|
2013-02-02 20:13:36 +00:00
|
|
|
.SH NOTES
|
2013-02-02 20:34:47 +00:00
|
|
|
.BR pthread_setname_np ()
|
2013-02-02 20:13:36 +00:00
|
|
|
internally writes to the thread specific comm file under
|
|
|
|
.IR /proc
|
|
|
|
filesystem:
|
2013-02-02 20:34:47 +00:00
|
|
|
.IR /proc/self/task/[tid]/comm .
|
|
|
|
.BR pthread_getname_np ()
|
2013-02-02 20:13:36 +00:00
|
|
|
retreives it from the same location.
|
|
|
|
|
|
|
|
.SH EXAMPLE
|
|
|
|
.PP
|
|
|
|
The program below demonstrates the use of
|
2013-02-02 20:34:47 +00:00
|
|
|
.BR pthread_setname_np ()
|
|
|
|
and
|
2013-02-02 20:13:36 +00:00
|
|
|
.BR pthread_getname_np ().
|
|
|
|
|
|
|
|
The following shell session shows a sample run of the program:
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
|
2013-02-02 20:34:47 +00:00
|
|
|
.RB "$" " ./a.out"
|
2013-02-02 20:13:36 +00:00
|
|
|
Created a thread. Default name is: a.out
|
|
|
|
The thread name after setting it is THREADFOO.
|
|
|
|
Done
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
|
|
|
|
.SS Program source
|
|
|
|
\&
|
|
|
|
.nf
|
|
|
|
#define _GNU_SOURCE
|
|
|
|
|
|
|
|
#include <pthread.h>
|
|
|
|
#include <stdio.h>
|
|
|
|
#include <string.h>
|
|
|
|
#include <unistd.h>
|
|
|
|
#include <errno.h>
|
|
|
|
#include <stdlib.h>
|
|
|
|
|
|
|
|
#define NAMELEN 16
|
|
|
|
|
|
|
|
#define errExitEN(en, msg) \\
|
|
|
|
do { if(en) { errno = en; perror(msg); \\
|
|
|
|
exit(EXIT_FAILURE);} \\
|
|
|
|
} while (0)
|
|
|
|
|
|
|
|
static void *threadfunc(void *parm)
|
|
|
|
{
|
|
|
|
sleep(5); // allow main program to set the thread name
|
|
|
|
return NULL;
|
|
|
|
}
|
|
|
|
|
|
|
|
int main(int argc, char **argv)
|
|
|
|
{
|
|
|
|
pthread_t thread;
|
|
|
|
int rc;
|
|
|
|
char thread_name[NAMELEN];
|
|
|
|
|
|
|
|
rc = pthread_create(&thread, NULL, threadfunc, NULL);
|
|
|
|
errExitEN(rc, "pthread_create");
|
2013-02-02 20:34:47 +00:00
|
|
|
|
2013-02-02 20:13:36 +00:00
|
|
|
rc = pthread_getname_np(thread, thread_name, NAMELEN);
|
|
|
|
errExitEN(rc, "pthread_getname_np");
|
|
|
|
printf("Created a thread. Default name is: %s\\n", thread_name);
|
|
|
|
rc = pthread_setname_np(thread, "THREADFOO");
|
|
|
|
errExitEN(rc, "pthread_setname_np");
|
2013-02-02 20:34:47 +00:00
|
|
|
|
2013-02-02 20:13:36 +00:00
|
|
|
sleep(2);
|
2013-02-02 20:34:47 +00:00
|
|
|
|
2013-02-02 20:13:36 +00:00
|
|
|
rc = pthread_getname_np(thread, thread_name, NAMELEN);
|
|
|
|
errExitEN(rc, "pthread_getname_np");
|
|
|
|
printf("The thread name after setting it is %s.\\n", thread_name);
|
2013-02-02 20:34:47 +00:00
|
|
|
|
2013-02-02 20:13:36 +00:00
|
|
|
rc = pthread_join(thread, NULL);
|
|
|
|
errExitEN(rc, "pthread_join");
|
2013-02-02 20:34:47 +00:00
|
|
|
|
2013-02-02 20:13:36 +00:00
|
|
|
printf("Done\\n");
|
|
|
|
exit(EXIT_SUCCESS);
|
|
|
|
}
|
|
|
|
.fi
|
|
|
|
.SH SEE ALSO
|
|
|
|
.ad l
|
|
|
|
.nh
|
|
|
|
.BR prctl (2),
|
|
|
|
.BR pthread_create (3),
|
|
|
|
.BR pthreads (7)
|