.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2018 Joyent, Inc.
.\"
.Dd "August 22, 2018"
.Dt PTHREAD_GETNAME_NP 3C
.Os
.Sh NAME
.Nm pthread_getname_np ,
.Nm pthread_setname_np
.Nd get or set the name of a thread
.Sh SYNOPSIS
.In pthread.h
.
.Ft int
.Fo pthread_getname_np
.Fa "pthread_t tid"
.Fa "char *name"
.Fa "size_t len"
.Fc
.
.Ft int
.Fo pthread_setname_np
.Fa "pthread_t tid"
.Fa "const char *name"
.Fc
.
.Sh DESCRIPTION
The
.Fn pthread_getname_np
and
.Fn pthread_setname_np
functions, respectively, get and set the names of the thread whose id is given
by the
.Fa tid
parameter.
For
.Fn pthread_getname_np ,
.Fa len
indicates the size of
.Fa name .
.Pp
Thread names are limited to
.Dv PTHREAD_MAX_NAMELEN_NP
including the terminating NUL.
They may only contain printable ASCII characters.
.Pp
To clear a thread name, call
.Fn pthread_setname_np
with
.Sy NULL .
.Pp
Unlike some other systems, threads do not inherit the process name by default.
.Sh RETURN VALUES
Upon successful completion, the
.Fn pthread_getname_np
and
.Fn pthread_setname_np
functions return
.Sy 0 .
Otherwise, an error number is returned to indicate the error.
If the thread identified by
.Fa tid
does not have a name set,
.Fa pthread_getname_np
will be set to an empty string (length = 0).
.Sh ERRORS
On failure, the contents of the buffer are undefined.
Errors from
.Xr open 2 ,
.Xr read 2 ,
or
.Xr write 2
are possible.
In addition, the
.Fn pthread_getname_np
function will fail with:
.Bl -tag -width Er
.It Er EINVAL
The
.Fa name
argument is
.Sy NULL .
.It Er ERANGE
The size of
.Fa name
as given by
.Fa len
was not large enough to contain the name of the thread.
.It Er ESRCH
The thread
.Fa tid
was not found.
.El
.Pp
The
.Fn pthread_setname_np
function will fail with:
.Bl -tag -width Er
.It Er ERANGE
The length of
.Fa name
exceeds the maximum allowed size.
.It Er ESRCH
The thread
.Fa tid
was not found.
.El
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr pthread_attr_getname_np 3c ,
.Xr pthread_create 3c