d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ac39a5d5ea
freebsd-dev/lib/libc/sys/thr_set_name.2

95 lines
2.8 KiB
Groff
Raw Normal View History

Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
.\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This documentation was written by
.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
.\" from the FreeBSD Foundation.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
thr_set_name(): silently truncate the given name as needed Instead of failing with ENAMETOOLONG, which is swallowed by pthread_set_name_np() anyway, truncate the given name to MAXCOMLEN+1 bytes. This is more likely what the user wants, and saves the caller from truncating it before the call (which was the only recourse). Polish pthread_set_name_np(3) and add a .Xr to thr_set_name(2) so the user might find the documentation for this behavior. Reviewed by: jilles MFC after: 3 days Sponsored by: Dell EMC
2016-12-03 01:14:21 +00:00
.Dd December 2, 2016
Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
.Dt THR_SET_NAME 2
.Os
.Sh NAME
.Nm thr_set_name
.Nd set user-visible thread name
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/thr.h
.Ft int
.Fn thr_set_name "long id" "const char *name"
.Sh DESCRIPTION
The
.Fn thr_set_name
thr_set_name(): silently truncate the given name as needed Instead of failing with ENAMETOOLONG, which is swallowed by pthread_set_name_np() anyway, truncate the given name to MAXCOMLEN+1 bytes. This is more likely what the user wants, and saves the caller from truncating it before the call (which was the only recourse). Polish pthread_set_name_np(3) and add a .Xr to thr_set_name(2) so the user might find the documentation for this behavior. Reviewed by: jilles MFC after: 3 days Sponsored by: Dell EMC
2016-12-03 01:14:21 +00:00
system call sets the user-visible name for the thread with the identifier
Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
.Va id
thr_set_name(): silently truncate the given name as needed Instead of failing with ENAMETOOLONG, which is swallowed by pthread_set_name_np() anyway, truncate the given name to MAXCOMLEN+1 bytes. This is more likely what the user wants, and saves the caller from truncating it before the call (which was the only recourse). Polish pthread_set_name_np(3) and add a .Xr to thr_set_name(2) so the user might find the documentation for this behavior. Reviewed by: jilles MFC after: 3 days Sponsored by: Dell EMC
2016-12-03 01:14:21 +00:00
in the current process to the NUL-terminated string
Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
.Va name .
thr_set_name(): silently truncate the given name as needed Instead of failing with ENAMETOOLONG, which is swallowed by pthread_set_name_np() anyway, truncate the given name to MAXCOMLEN+1 bytes. This is more likely what the user wants, and saves the caller from truncating it before the call (which was the only recourse). Polish pthread_set_name_np(3) and add a .Xr to thr_set_name(2) so the user might find the documentation for this behavior. Reviewed by: jilles MFC after: 3 days Sponsored by: Dell EMC
2016-12-03 01:14:21 +00:00
The name will be silently truncated to fit into a buffer of
.Dv MAXCOMLEN + 1
bytes.
Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
The thread name can be seen in the output of the
.Xr ps 1
and
.Xr top 1
commands, in the kernel debuggers and kernel tracing facility outputs,
thr_set_name(): silently truncate the given name as needed Instead of failing with ENAMETOOLONG, which is swallowed by pthread_set_name_np() anyway, truncate the given name to MAXCOMLEN+1 bytes. This is more likely what the user wants, and saves the caller from truncating it before the call (which was the only recourse). Polish pthread_set_name_np(3) and add a .Xr to thr_set_name(2) so the user might find the documentation for this behavior. Reviewed by: jilles MFC after: 3 days Sponsored by: Dell EMC
2016-12-03 01:14:21 +00:00
and in userland debuggers and program core files, as notes.
Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
.Sh RETURN VALUES
If successful,
.Fn thr_set_name
thr_set_name(): silently truncate the given name as needed Instead of failing with ENAMETOOLONG, which is swallowed by pthread_set_name_np() anyway, truncate the given name to MAXCOMLEN+1 bytes. This is more likely what the user wants, and saves the caller from truncating it before the call (which was the only recourse). Polish pthread_set_name_np(3) and add a .Xr to thr_set_name(2) so the user might find the documentation for this behavior. Reviewed by: jilles MFC after: 3 days Sponsored by: Dell EMC
2016-12-03 01:14:21 +00:00
returns zero; otherwise, \-1 is returned, and
Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn thr_set_name
thr_set_name(): silently truncate the given name as needed Instead of failing with ENAMETOOLONG, which is swallowed by pthread_set_name_np() anyway, truncate the given name to MAXCOMLEN+1 bytes. This is more likely what the user wants, and saves the caller from truncating it before the call (which was the only recourse). Polish pthread_set_name_np(3) and add a .Xr to thr_set_name(2) so the user might find the documentation for this behavior. Reviewed by: jilles MFC after: 3 days Sponsored by: Dell EMC
2016-12-03 01:14:21 +00:00
system call may return the following errors:
Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
.Bl -tag -width Er
.It Bq Er EFAULT
The memory pointed to by the
.Fa name
argument is not valid.
.It Bq Er ESRCH
The thread with the identifier
.Fa id
does not exist in the current process.
.El
.Sh SEE ALSO
.Xr ps 1 ,
.Xr thr_exit 2 ,
.Xr thr_kill 2 ,
.Xr thr_kill2 2 ,
.Xr thr_new 2 ,
.Xr thr_self 2 ,
.Xr _umtx_op 2 ,
thr_*(2): Add xrefs to what libthr implements using each syscall. Add text to thr_exit(2) and thr_new(2) discouraging their use in applications since calling these in a process with libthr loaded will confuse libthr and is likely to cause hangs or crashes. The thr_kill2(2) call is not used by libthr and may be useful in special applications. The other calls can be used in applications but it should not be necessary.
2016-06-01 21:58:13 +00:00
.Xr pthread_set_name_np 3 ,
Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
.Xr ddb 4 ,
.Xr ktr 9
.Sh STANDARDS
The
thr_set_name(): silently truncate the given name as needed Instead of failing with ENAMETOOLONG, which is swallowed by pthread_set_name_np() anyway, truncate the given name to MAXCOMLEN+1 bytes. This is more likely what the user wants, and saves the caller from truncating it before the call (which was the only recourse). Polish pthread_set_name_np(3) and add a .Xr to thr_set_name(2) so the user might find the documentation for this behavior. Reviewed by: jilles MFC after: 3 days Sponsored by: Dell EMC
2016-12-03 01:14:21 +00:00
.Fn thr_set_name
system call is non-standard and is used by the
Document the non-obsoleted kernel interfaces used by libthr. Reviewed by: emaste Sponsored by: The FreeBSD Foundation Differential revision: https://reviews.freebsd.org/D6335
2016-05-14 08:36:37 +00:00
.Lb libthr .
Reference in New Issue Copy Permalink