1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2018 Joyent, Inc.
13.\"
14.Dd "August 22, 2018"
15.Dt PTHREAD_GETNAME_NP 3C
16.Os
17.Sh NAME
18.Nm pthread_getname_np ,
19.Nm pthread_setname_np
20.Nd get or set the name of a thread
21.Sh SYNOPSIS
22.In pthread.h
23.
24.Ft int
25.Fo pthread_getname_np
26.Fa "pthread_t tid"
27.Fa "char *name"
28.Fa "size_t len"
29.Fc
30.
31.Ft int
32.Fo pthread_setname_np
33.Fa "pthread_t tid"
34.Fa "const char *name"
35.Fc
36.
37.Sh DESCRIPTION
38The
39.Fn pthread_getname_np
40and
41.Fn pthread_setname_np
42functions, respectively, get and set the names of the thread whose id is given
43by the
44.Fa tid
45parameter.
46For
47.Fn pthread_getname_np ,
48.Fa len
49indicates the size of
50.Fa name .
51.Pp
52Thread names are limited to
53.Dv PTHREAD_MAX_NAMELEN_NP
54including the terminating NUL.
55They may only contain printable ASCII characters.
56.Pp
57To clear a thread name, call
58.Fn pthread_setname_np
59with
60.Sy NULL .
61.Pp
62Unlike some other systems, threads do not inherit the process name by default.
63.Sh RETURN VALUES
64Upon successful completion, the
65.Fn pthread_getname_np
66and
67.Fn pthread_setname_np
68functions return
69.Sy 0 .
70Otherwise, an error number is returned to indicate the error.
71If the thread identified by
72.Fa tid
73does not have a name set,
74.Fa pthread_getname_np
75will be set to an empty string (length = 0).
76.Sh ERRORS
77On failure, the contents of the buffer are undefined.
78Errors from
79.Xr open 2 ,
80.Xr read 2 ,
81or
82.Xr write 2
83are possible.
84In addition, the
85.Fn pthread_getname_np
86function will fail with:
87.Bl -tag -width Er
88.It Er EINVAL
89The
90.Fa name
91argument is
92.Sy NULL .
93.It Er ERANGE
94The size of
95.Fa name
96as given by
97.Fa len
98was not large enough to contain the name of the thread.
99.It Er ESRCH
100The thread
101.Fa tid
102was not found.
103.El
104.Pp
105The
106.Fn pthread_setname_np
107function will fail with:
108.Bl -tag -width Er
109.It Er ERANGE
110The length of
111.Fa name
112exceeds the maximum allowed size.
113.It Er ESRCH
114The thread
115.Fa tid
116was not found.
117.El
118.Sh INTERFACE STABILITY
119.Sy Uncommitted
120.Sh MT-LEVEL
121.Sy MT-Safe
122.Sh SEE ALSO
123.Xr pthread_attr_getname_np 3c ,
124.Xr pthread_create 3c
125