| .\" |
| .\" 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 THR_GETNAME 3C |
| .Os |
| .Sh NAME |
| .Nm thr_getname , |
| .Nm thr_setname |
| .Nd get or set the name of a thread |
| .Sh SYNOPSIS |
| .In thread.h |
| . |
| .Ft int |
| .Fo thr_getname |
| .Fa "thread_t tid" |
| .Fa "char *name" |
| .Fa "size_t len" |
| .Fc |
| . |
| .Ft int |
| .Fo thr_setname |
| .Fa "thread_t tid" |
| .Fa "const char *name" |
| .Fc |
| . |
| .Sh DESCRIPTION |
| The |
| .Fn thr_getname |
| and |
| .Fn thr_setname |
| functions, respectively, get and set the names of the thread whose id is given |
| by the |
| .Fa tid |
| parameter. |
| For |
| .Fn thr_getname , |
| .Fa len |
| indicates the size of |
| .Fa name . |
| .Pp |
| Thread names are limited to |
| .Dv THREAD_NAME_MAX |
| including the terminating NUL. |
| They may only contain printable ASCII characters. |
| .Pp |
| To clear a thread name, call |
| .Fn thr_setname |
| 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 thr_getname |
| and |
| .Fn thr_setname |
| 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 thr_getname |
| 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 thr_getname |
| 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 thr_setname |
| 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_setname_np 3c , |
| .Xr thr_create 3c |