| John Levon | ab61854 | 2018-10-08 15:34:11 +0100 | [diff] [blame^] | 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 THR_GETNAME 3C |
| 16 | .Os |
| 17 | .Sh NAME |
| 18 | .Nm thr_getname , |
| 19 | .Nm thr_setname |
| 20 | .Nd get or set the name of a thread |
| 21 | .Sh SYNOPSIS |
| 22 | .In thread.h |
| 23 | . |
| 24 | .Ft int |
| 25 | .Fo thr_getname |
| 26 | .Fa "thread_t tid" |
| 27 | .Fa "char *name" |
| 28 | .Fa "size_t len" |
| 29 | .Fc |
| 30 | . |
| 31 | .Ft int |
| 32 | .Fo thr_setname |
| 33 | .Fa "thread_t tid" |
| 34 | .Fa "const char *name" |
| 35 | .Fc |
| 36 | . |
| 37 | .Sh DESCRIPTION |
| 38 | The |
| 39 | .Fn thr_getname |
| 40 | and |
| 41 | .Fn thr_setname |
| 42 | functions, respectively, get and set the names of the thread whose id is given |
| 43 | by the |
| 44 | .Fa tid |
| 45 | parameter. |
| 46 | For |
| 47 | .Fn thr_getname , |
| 48 | .Fa len |
| 49 | indicates the size of |
| 50 | .Fa name . |
| 51 | .Pp |
| 52 | Thread names are limited to |
| 53 | .Dv THREAD_NAME_MAX |
| 54 | including the terminating NUL. |
| 55 | They may only contain printable ASCII characters. |
| 56 | .Pp |
| 57 | To clear a thread name, call |
| 58 | .Fn thr_setname |
| 59 | with |
| 60 | .Sy NULL . |
| 61 | .Pp |
| 62 | Unlike some other systems, threads do not inherit the process name by default. |
| 63 | .Sh RETURN VALUES |
| 64 | Upon successful completion, the |
| 65 | .Fn thr_getname |
| 66 | and |
| 67 | .Fn thr_setname |
| 68 | functions return |
| 69 | .Sy 0 . |
| 70 | Otherwise, an error number is returned to indicate the error. |
| 71 | If the thread identified by |
| 72 | .Fa tid |
| 73 | does not have a name set, |
| 74 | .Fa thr_getname |
| 75 | will be set to an empty string (length = 0). |
| 76 | .Sh ERRORS |
| 77 | On failure, the contents of the buffer are undefined. |
| 78 | Errors from |
| 79 | .Xr open 2 , |
| 80 | .Xr read 2 , |
| 81 | or |
| 82 | .Xr write 2 |
| 83 | are possible. |
| 84 | In addition, the |
| 85 | .Fn thr_getname |
| 86 | function will fail with: |
| 87 | .Bl -tag -width Er |
| 88 | .It Er EINVAL |
| 89 | The |
| 90 | .Fa name |
| 91 | argument is |
| 92 | .Sy NULL . |
| 93 | .It Er ERANGE |
| 94 | The size of |
| 95 | .Fa name |
| 96 | as given by |
| 97 | .Fa len |
| 98 | was not large enough to contain the name of the thread. |
| 99 | .It Er ESRCH |
| 100 | The thread |
| 101 | .Fa tid |
| 102 | was not found. |
| 103 | .El |
| 104 | .Pp |
| 105 | The |
| 106 | .Fn thr_setname |
| 107 | function will fail with: |
| 108 | .Bl -tag -width Er |
| 109 | .It Er ERANGE |
| 110 | The length of |
| 111 | .Fa name |
| 112 | exceeds the maximum allowed size. |
| 113 | .It Er ESRCH |
| 114 | The thread |
| 115 | .Fa tid |
| 116 | was 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_setname_np 3c , |
| 124 | .Xr thr_create 3c |