1.\" $OpenBSD: getthrname.2,v 1.2 2023/02/22 06:31:51 guenther Exp $ 2.\" 3.\" Copyright (c) 2023 Philip Guenther <guenther@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: February 22 2023 $ 18.Dt GETTHRNAME 2 19.Os 20.Sh NAME 21.Nm getthrname , 22.Nm setthrname 23.Nd get or set thread name 24.Sh SYNOPSIS 25.In unistd.h 26.Ft int 27.Fo getthrname 28.Fa "pid_t tid" 29.Fa "char *name" 30.Fa "size_t namelen" 31.Fc 32.Ft int 33.Fo setthrname 34.Fa "pid_t tid" 35.Fa "const char *name" 36.Fc 37.Sh DESCRIPTION 38The 39.Fn getthrname 40system call stores the name of 41.Fa tid , 42a thread in the current process, 43into the buffer 44.Fa name , 45which must be of at least 46.Fa namelen 47bytes long. 48The buffer should be large enough to store the thread name and a 49trailing NUL 50(typically 51.Dv MAXCOMLEN+1 52bytes). 53The 54.Fn setthrname 55system call sets the name of 56.Fa tid 57to the supplied 58.Fa name . 59For both functions, if 60.Fa tid 61is zero then the current thread is operated on. 62.Pp 63Thread names have no inherent meaning in the system and are 64intended for display and debugging only. 65They are not secret but rather are visible to other processes using 66.Xr sysctl 2 67or 68.Xr kvm_getprocs 3 69and in 70.Ic ps Fl H 71output. 72.Pp 73After 74.Xr execve 2 , 75the name of the process's only thread is reset to the empty string. 76Similarly, additional threads created with 77.Xr __tfork 3 78start with the empty name. 79After 80.Xr fork 2 , 81the new process's only thread has the same name as the thread that 82invoked 83.Xr fork 2 . 84.Sh RETURN VALUES 85Upon successful completion, the value 0 is returned; 86otherwise the error number is returned. 87.Sh ERRORS 88.Fn getthrname 89and 90.Fn setthrname 91will succeed unless: 92.Bl -tag -width Er 93.It Bq Er EFAULT 94The 95.Fa name 96argument points to an 97invalid address. 98.El 99.Pp 100In addition, 101.Fn getthrname 102may return the following error: 103.Bl -tag -width Er 104.It Bq Er ERANGE 105The value of 106.Fa namelen 107is not large enough to store the thread name and a trailing NUL. 108.El 109.Pp 110.Fn setthrname 111may return the following errors: 112.Bl -tag -width Er 113.It Bq Er EINVAL 114The 115.Fa name 116argument 117pointed to a string that was too long. 118Thread names are limited to 119.Dv MAXCOMLEN 120characters, currently 23. 121.El 122.Sh SEE ALSO 123.Xr execve 2 , 124.Xr fork 2 , 125.Xr sysctl 2 , 126.Xr __tfork 3 , 127.Xr kvm_getprocs 3 , 128.Xr pthread_set_name_np 3 129.Sh STANDARDS 130The 131.Fn getthrname 132and 133.Fn setthrname 134system calls are specific to 135.Ox ; 136.Xr pthread_get_name_np 3 137and 138.Xr pthread_set_name_np 3 139operate on the same thread name in a more portable way. 140.Sh HISTORY 141The 142.Fn getthrname 143and 144.Fn setthrname 145system calls first appeared in 146.Ox 7.3 . 147