GETTHRNAME(2) | System Calls Manual | GETTHRNAME(2)

# NAME

`getthrname`, `setthrname` — get or set thread name

# SYNOPSIS

`#include <unistd.h>`

int
`getthrname`(pid_t tid, char *name, size_t namelen);

int
`setthrname`(pid_t tid, const char *name);

# DESCRIPTION

The `getthrname`() system call stores the name of tid, a thread in the current process, into the buffer name, which must be of at least namelen bytes long. The buffer should be large enough to store the thread name and a trailing NUL (typically `MAXCOMLEN+1` bytes). The `setthrname`() system call sets the name of tid to the supplied name. For both functions, if tid is zero then the current thread is operated on.

Thread names have no inherent meaning in the system and are intended for display and debugging only. They are not secret but rather are visible to other processes using sysctl(2) or kvm_getprocs(3) and in `ps` `-H` output.

After execve(2), the name of the process's only thread is reset to the empty string. Similarly, additional threads created with __tfork(3) start with the empty name. After fork(2), the new process's only thread has the same name as the thread that invoked fork(2).

# RETURN VALUES

Upon successful completion, the value 0 is returned; otherwise the error number is returned.

# ERRORS

`getthrname`() and `setthrname`() will succeed unless:

[`EFAULT`]
  The name argument points to an invalid address.

In addition, `getthrname`() may return the following error:

[`ERANGE`]
  The value of namelen is not large enough to store the thread name and a trailing NUL.

`setthrname`() may return the following errors:

[`EINVAL`]
  The name argument pointed to a string that was too long. Thread names are limited to `MAXCOMLEN` characters, currently 23.

# SEE ALSO

execve(2), fork(2), sysctl(2), __tfork(3), kvm_getprocs(3), pthread_set_name_np(3)

# STANDARDS

The `getthrname`() and `setthrname`() system calls are specific to OpenBSD; pthread_get_name_np(3) and pthread_set_name_np(3) operate on the same thread name in a more portable way.

# HISTORY

The `getthrname`() and `setthrname`() system calls first appeared in OpenBSD 7.3.

February 22, 2023 | Debian