mirror of https://github.com/mkerrisk/man-pages
147 lines
4.3 KiB
Groff
147 lines
4.3 KiB
Groff
|
.\" 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.
|
||
|
.\"
|
||
|
.TH PTHREAD_SETNAME_NP 3 2012-10-24 "Linux" "Linux Programmer's Manual"
|
||
|
.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 ");
|
||
|
.BI "int pthread_getname_np(pthread_t *" thread ", const char *" name
|
||
|
", size_t" len);
|
||
|
.fi
|
||
|
.sp
|
||
|
Compile and link with \fI\-pthread\fP.
|
||
|
.SH DESCRIPTION
|
||
|
By default, all the threads created using
|
||
|
.BR pthread_create (3)
|
||
|
inherit the program name.
|
||
|
Using
|
||
|
.BR pthread_setname_np (3),
|
||
|
users can specify a unique name for a thread,
|
||
|
which can be particularly useful for debugging complicated
|
||
|
multi-threaded applications.
|
||
|
The thread name is a meaningful C language string, whose length is
|
||
|
restricted to 16 characters.
|
||
|
Anything greater than this would lead to an error.
|
||
|
|
||
|
The
|
||
|
.BR pthread_getname_np (3)
|
||
|
can be used to retrieve the name of the thread.
|
||
|
The buffer specified by name must be at least 16 characters in length.
|
||
|
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
|
||
|
If the functions fail to open /proc/self/task/<TID>/comm, then the
|
||
|
call may fail with one of
|
||
|
the errors described in
|
||
|
.BR open (2).
|
||
|
.TP
|
||
|
.B ERANGE
|
||
|
The length of the string specified as second argument exceeds the allowed limit.
|
||
|
|
||
|
.SH NOTES
|
||
|
.BR pthread_setname_np (3)
|
||
|
internally writes to the thread specific comm file under
|
||
|
.IR /proc
|
||
|
filesystem:
|
||
|
.IR /proc/self/task/<tid>/comm.
|
||
|
.BR pthread_getname_np (3)
|
||
|
retreives it from the same location.
|
||
|
|
||
|
.SH EXAMPLE
|
||
|
.PP
|
||
|
The program below demonstrates the use of
|
||
|
.BR pthread_setname_np (),
|
||
|
as well as
|
||
|
.BR pthread_getname_np ().
|
||
|
|
||
|
The following shell session shows a sample run of the program:
|
||
|
.in +4n
|
||
|
.nf
|
||
|
|
||
|
.RB "$" " ./a.out 1 2 4 7 14"
|
||
|
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");
|
||
|
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");
|
||
|
sleep(2);
|
||
|
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);
|
||
|
rc = pthread_join(thread, NULL);
|
||
|
errExitEN(rc, "pthread_join");
|
||
|
printf("Done\\n");
|
||
|
exit(EXIT_SUCCESS);
|
||
|
}
|
||
|
.fi
|
||
|
.SH SEE ALSO
|
||
|
.ad l
|
||
|
.nh
|
||
|
.BR prctl (2),
|
||
|
.BR pthread_create (3),
|
||
|
.BR pthreads (7)
|