Index: head/lib/libc/sys/thr_exit.2 =================================================================== --- head/lib/libc/sys/thr_exit.2 (revision 360669) +++ head/lib/libc/sys/thr_exit.2 (revision 360670) @@ -1,90 +1,95 @@ .\" Copyright (c) 2016 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" This documentation was written by .\" Konstantin Belousov 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$ .\" -.Dd June 1, 2016 +.Dd May 5, 2020 .Dt THR_EXIT 2 .Os .Sh NAME .Nm thr_exit .Nd terminate current thread .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/thr.h .Ft void .Fn thr_exit "long *state" .Sh DESCRIPTION .Bf -symbolic This function is intended for implementing threading. Normal applications should call .Xr pthread_exit 3 instead. .Ef .Pp The .Fn thr_exit system call terminates the current kernel-scheduled thread. .Pp If the .Fa state argument is not .Dv NULL , the location pointed to by the argument is updated with an arbitrary non-zero value, and an .Xr _umtx_op 2 .Dv UMTX_OP_WAKE operation is consequently performed on the location. .Pp Attempts to terminate the last thread in the process are silently ignored. Use .Xr _exit 2 syscall to terminate the process. .Sh RETURN VALUES The function does not return a value. A return from the function indicates that the calling thread was the last one in the process. .Sh SEE ALSO .Xr _exit 2 , .Xr thr_kill 2 , .Xr thr_kill2 2 , .Xr thr_new 2 , .Xr thr_self 2 , .Xr thr_set_name 2 , .Xr _umtx_op 2 , .Xr pthread_exit 3 .Sh STANDARDS The .Fn thr_exit system call is non-standard and is used by .Lb libthr to implement .St -p1003.1-2001 .Xr pthread 3 functionality. +.Sh HISTORY +The +.Fn thr_exit +system call first appeared in +.Fx 5.2 . Index: head/lib/libc/sys/thr_kill.2 =================================================================== --- head/lib/libc/sys/thr_kill.2 (revision 360669) +++ head/lib/libc/sys/thr_kill.2 (revision 360670) @@ -1,133 +1,140 @@ .\" Copyright (c) 2016 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" This documentation was written by .\" Konstantin Belousov 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$ .\" -.Dd June 1, 2016 +.Dd May 5, 2020 .Dt THR_kill 2 .Os .Sh NAME .Nm thr_kill .Nd send signal to thread .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/thr.h .Ft int .Fn thr_kill "long id" "int sig" .Ft int .Fn thr_kill2 "pid_t pid" "long id" "int sig" .Sh DESCRIPTION The .Fn thr_kill and .Fn thr_kill2 system calls allow sending a signal, specified by the .Fa sig argument, to some threads in a process. For the .Fn thr_kill function, signalled threads are always limited to the current process. For the .Fn thr_kill2 function, the .Fa pid argument specifies the process with threads to be signalled. .Pp The .Fa id argument specifies which threads get the signal. If .Fa id is equal to \-1, all threads in the specified process are signalled. Otherwise, only the thread with the thread identifier equal to the argument is signalled. .Pp The .Fa sig argument defines the delivered signal. It must be a valid signal number or zero. In the latter case no signal is actually sent, and the call is used to verify the liveness of the thread. .Pp The signal is delivered with .Dv siginfo .Dv si_code set to .Dv SI_LWP . .Sh RETURN VALUES If successful, .Fn thr_kill and .Fn thr_kill2 will return zero, otherwise \-1 is returned, and .Va errno is set to indicate the error. .Sh ERRORS The .Fn thr_kill and .Fn thr_kill2 operations return the following errors: .Bl -tag -width Er .It Bq Er EINVAL The .Fa sig argument is not zero and does not specify valid signal. .It Bq Er ESRCH The specified process or thread was not found. .El .Pp Additionally, the .Fn thr_kill2 may return the following errors: .Bl -tag -width Er .It Bq Er EPERM The current process does not have sufficient privilege to check existence or send a signal to the specified process. .El .Sh SEE ALSO .Xr kill 2 , .Xr thr_exit 2 , .Xr thr_new 2 , .Xr thr_self 2 , .Xr thr_set_name 2 , .Xr _umtx_op 2 , .Xr pthread_kill 3 , .Xr signal 3 .Sh STANDARDS The .Fn thr_kill and .Fn thr_kill2 system calls are non-standard and are used by the .Lb libthr to implement .St -p1003.1-2001 .Xr pthread 3 functionality. +.Sh HISTORY +The +.Fn thr_kill +and +.Fn thr_kill2 +system calls first appeared in +.Fx 5.2 . Index: head/lib/libc/sys/thr_new.2 =================================================================== --- head/lib/libc/sys/thr_new.2 (revision 360669) +++ head/lib/libc/sys/thr_new.2 (revision 360670) @@ -1,245 +1,250 @@ .\" Copyright (c) 2016 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" This documentation was written by .\" Konstantin Belousov 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$ .\" -.Dd June 2, 2016 +.Dd May 5, 2020 .Dt THR_NEW 2 .Os .Sh NAME .Nm thr_new .Nd create new thread of execution .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/thr.h .Ft int .Fn thr_new "struct thr_param *param" "int param_size" .Sh DESCRIPTION .Bf -symbolic This function is intended for implementing threading. Normal applications should call .Xr pthread_create 3 instead. .Ef .Pp The .Fn thr_new system call creates a new kernel-scheduled thread of execution in the context of the current process. The newly created thread shares all attributes of the process with the existing kernel-scheduled threads in the process, but has private processor execution state. The machine context for the new thread is copied from the creating thread's context, including coprocessor state. FPU state and specific machine registers are excluded from the copy. These are set according to ABI requirements and syscall parameters. The FPU state for the new thread is reinitialized to clean. .Pp The .Fa param structure supplies parameters affecting the thread creation. The structure is defined in the .In sys/thr.h header as follows .Bd -literal struct thr_param { void (*start_func)(void *); void *arg; char *stack_base; size_t stack_size; char *tls_base; size_t tls_size; long *child_tid; long *parent_tid; int flags; struct rtprio *rtp; }; .Ed and contains the following fields: .Bl -tag -width ".Va parent_tid" .It Va start_func Pointer to the thread entry function. The kernel arranges for the new thread to start executing the function upon the first return to userspace. .It Va arg Opaque argument supplied to the entry function. .It Va stack_base Stack base address. The stack must be allocated by the caller. On some architectures, the ABI might require that the system put information on the stack to ensure the execution environment for .Va start_func . .It Va stack_size Stack size. .It Va tls_base TLS base address. The value of TLS base is loaded into the ABI-defined machine register in the new thread context. .It Va tls_size TLS size. .It Va child_tid Address to store the new thread identifier, for the child's use. .It Va parent_tid Address to store the new thread identifier, for the parent's use. .Pp Both .Va child_tid and .Va parent_tid are provided, with the intent that .Va child_tid is used by the new thread to get its thread identifier without issuing the .Xr thr_self 2 syscall, while .Va parent_tid is used by the thread creator. The latter is separate from .Va child_tid because the new thread might exit and free its thread data before the parent has a chance to execute far enough to access it. .It Va flags Thread creation flags. The .Va flags member may specify the following flags: .Bl -tag -width ".Dv THR_SYSTEM_SCOPE" .It Dv THR_SUSPENDED Create the new thread in the suspended state. The flag is not currently implemented. .It Dv THR_SYSTEM_SCOPE Create the system scope thread. The flag is not currently implemented. .El .It Va rtp Real-time scheduling priority for the new thread. May be .Dv NULL to inherit the priority from the creating thread. .El .Pp The .Fa param_size argument should be set to the size of the .Fa param structure. .Pp After the first successful creation of an additional thread, the process is marked by the kernel as multi-threaded. In particular, the .Dv P_HADTHREADS flag is set in the process' .Dv p_flag (visible in the .Xr ps 1 output), and several operations are executed in multi-threaded mode. For instance, the .Xr execve 2 system call terminates all threads but the calling one on successful execution. .Sh RETURN VALUES If successful, .Fn thr_new will return zero, otherwise \-1 is returned, and .Va errno is set to indicate the error. .Sh ERRORS The .Fn thr_new operation returns the following errors: .Bl -tag -width Er .\" When changing this list, consider updating share/man/man3/pthread_create.3, .\" since that function can return any of these errors. .It Bq Er EFAULT The memory pointed to by the .Fa param argument is not valid. .It Bq Er EFAULT The memory pointed to by the .Fa param structure .Fa child_tid , parent_tid or .Fa rtp arguments is not valid. .It Bq Er EFAULT The specified stack base is invalid, or the kernel was unable to put required initial data on the stack. .It Bq Er EINVAL The .Fa param_size argument specifies a negative value, or the value is greater than the largest .Fa struct param size the kernel can interpret. .It Bq Er EINVAL The .Fa rtp member is not .Dv NULL and specifies invalid scheduling parameters. .It Bq Er EINVAL The specified TLS base is invalid. .It Bq Er EPERM The caller does not have permission to set the scheduling parameters or scheduling policy. .It Bq Er EPROCLIM Creation of the new thread would exceed the .Dv RACCT_NTHR limit, see .Xr racct 2 . .It Bq Er EPROCLIM Creation of the new thread would exceed the .Dv kern.threads.max_threads_per_proc .Xr sysctl 2 limit. .It Bq Er ENOMEM There was not enough kernel memory to allocate the new thread structures. .El .Sh SEE ALSO .Xr ps 1 , .Xr execve 2 , .Xr racct 2 , .Xr thr_exit 2 , .Xr thr_kill 2 , .Xr thr_kill2 2 , .Xr thr_self 2 , .Xr thr_set_name 2 , .Xr _umtx_op 2 , .Xr pthread_create 3 .Sh STANDARDS The .Fn thr_new system call is non-standard and is used by the .Lb libthr to implement .St -p1003.1-2001 .Xr pthread 3 functionality. +.Sh HISTORY +The +.Fn thr_new +system call first appeared in +.Fx 5.2 . Index: head/lib/libc/sys/thr_self.2 =================================================================== --- head/lib/libc/sys/thr_self.2 (revision 360669) +++ head/lib/libc/sys/thr_self.2 (revision 360670) @@ -1,90 +1,95 @@ .\" Copyright (c) 2016 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" This documentation was written by .\" Konstantin Belousov 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$ .\" -.Dd March 3, 2020 +.Dd May 5, 2020 .Dt THR_SELF 2 .Os .Sh NAME .Nm thr_self .Nd return thread identifier for the calling thread .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/thr.h .Ft int .Fn thr_self "long *id" .Sh DESCRIPTION The .Fn thr_self system call stores the system-wide thread identifier for the current kernel-scheduled thread in the variable pointed by the argument .Va id . .Pp The thread identifier is an integer in the range from .Dv PID_MAX + 2 (100001) to .Dv INT_MAX . The thread identifier is guaranteed to be unique at any given time, for each running thread in the system. After the thread exits, the identifier may be reused. .Sh RETURN VALUES If successful, .Fn thr_self will return zero, otherwise \-1 is returned, and .Va errno is set to indicate the error. .Sh ERRORS The .Fn thr_self operation may return the following errors: .Bl -tag -width Er .It Bq Er EFAULT The memory pointed to by the .Fa id argument is not valid. .El .Sh SEE ALSO .Xr thr_exit 2 , .Xr thr_kill 2 , .Xr thr_kill2 2 , .Xr thr_new 2 , .Xr thr_set_name 2 , .Xr _umtx_op 2 , .Xr pthread_getthreadid_np 3 , .Xr pthread_self 3 .Sh STANDARDS The .Fn thr_self system call is non-standard and is used by .Lb libthr to implement .St -p1003.1-2001 .Xr pthread 3 functionality. +.Sh HISTORY +The +.Fn thr_self +system call first appeared in +.Fx 5.2 . Index: head/lib/libc/sys/thr_set_name.2 =================================================================== --- head/lib/libc/sys/thr_set_name.2 (revision 360669) +++ head/lib/libc/sys/thr_set_name.2 (revision 360670) @@ -1,94 +1,99 @@ .\" Copyright (c) 2016 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" This documentation was written by .\" Konstantin Belousov 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$ .\" -.Dd December 2, 2016 +.Dd May 5, 2020 .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 system call sets the user-visible name for the thread with the identifier .Va id in the current process to the NUL-terminated string .Va name . The name will be silently truncated to fit into a buffer of .Dv MAXCOMLEN + 1 bytes. 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, and in userland debuggers and program core files, as notes. .Sh RETURN VALUES If successful, .Fn thr_set_name returns zero; otherwise, \-1 is returned, and .Va errno is set to indicate the error. .Sh ERRORS The .Fn thr_set_name system call may return the following errors: .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 , .Xr pthread_set_name_np 3 , .Xr ddb 4 , .Xr ktr 9 .Sh STANDARDS The .Fn thr_set_name system call is non-standard and is used by the .Lb libthr . +.Sh HISTORY +The +.Fn thr_set_name +system call first appeared in +.Fx 5.2 . Index: head/lib/libc/sys/thr_suspend.2 =================================================================== --- head/lib/libc/sys/thr_suspend.2 (revision 360669) +++ head/lib/libc/sys/thr_suspend.2 (revision 360670) @@ -1,130 +1,135 @@ .\" Copyright (c) 2016 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" This documentation was written by .\" Konstantin Belousov 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$ .\" -.Dd September 23, 2016 +.Dd May 5, 2020 .Dt THR_SUSPEND 2 .Os .Sh NAME .Nm thr_suspend .Nd suspend the calling thread .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/thr.h .Ft int .Fn thr_suspend "struct timespec *timeout" .Sh DESCRIPTION .Bf -symbolic This function is intended for implementing threading. Normal applications should use .Xr pthread_cond_timedwait 3 together with .Xr pthread_cond_broadcast 3 for typical safe suspension with cooperation of the thread being suspended, or .Xr pthread_suspend_np 3 and .Xr pthread_resume_np 3 in some specific situations, instead. .Ef .Pp The .Fn thr_suspend system call puts the calling thread in a suspended state, where it is not eligible for CPU time. This state is exited by another thread calling .Xr thr_wake 2 , when the time interval specified by .Fa timeout has elapsed, or by the delivery of a signal to the suspended thread. .Pp If the .Fa timeout argument is .Dv NULL , the suspended state can be only terminated by explicit .Fn thr_wake or signal. .Pp If a wake from .Xr thr_wake 2 was delivered before the .Nm call, the thread is not put into a suspended state. Instead, the call returns immediately without an error. .Pp If a thread previously called .Xr thr_wake 2 with its own thread identifier, which resulted in setting the internal kernel flag to immediately abort interruptible sleeps with an .Er EINTR error .Po see .Xr thr_wake 2 .Pc , the flag is cleared. As with .Xr thr_wake 2 called from another thread, the next .Nm call does not result in suspension. .Pp .Sh RETURN VALUES .Rv -std thr_suspend .Sh ERRORS The .Fn thr_suspend operation returns the following errors: .Bl -tag -width Er .It Bq Er EFAULT The memory pointed to by the .Fa timeout argument is not valid. .It Bq Er ETIMEDOUT The specified timeout expired. .It Bq Er ETIMEDOUT The .Fa timeout argument specified a zero time interval. .It Bq Er EINTR The sleep was interrupted by a signal. .El .Sh SEE ALSO .Xr ps 1 , .Xr thr_wake 2 , .Xr pthread_resume_np 3 , .Xr pthread_suspend_np 3 .Sh STANDARDS The .Fn thr_suspend system call is non-standard. +.Sh HISTORY +The +.Fn thr_suspend +system call first appeared in +.Fx 5.2 . Index: head/lib/libc/sys/thr_wake.2 =================================================================== --- head/lib/libc/sys/thr_wake.2 (revision 360669) +++ head/lib/libc/sys/thr_wake.2 (revision 360670) @@ -1,112 +1,117 @@ .\" Copyright (c) 2016 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" This documentation was written by .\" Konstantin Belousov 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$ .\" -.Dd September 23, 2016 +.Dd May 5, 2020 .Dt THR_WAKE 2 .Os .Sh NAME .Nm thr_wake .Nd wake up the suspended thread .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/thr.h .Ft int .Fn thr_wake "long id" .Sh DESCRIPTION .Bf -symbolic This function is intended for implementing threading. Normal applications should use .Xr pthread_cond_timedwait 3 together with .Xr pthread_cond_broadcast 3 for typical safe suspension with cooperation of the thread being suspended, or .Xr pthread_suspend_np 3 and .Xr pthread_resume_np 3 in some specific situations, instead. .Ef .Pp Passing the thread identifier of the calling thread .Po see .Xr thr_self 2 .Pc to .Fn thr_wake sets a thread's flag to cause the next signal-interruptible sleep of that thread in the kernel to fail immediately with the .Er EINTR error. The flag is cleared by an interruptible sleep attempt or by a call to .Xr thr_suspend 2 . This is used by the system threading library to implement cancellation. .Pp If .Fa id is not equal to the current thread identifier, the specified thread is woken up if suspended by the .Xr thr_suspend system call. If the thread is not suspended at the time of the .Nm call, the wake is remembered and the next attempt of the thread to suspend itself with the .Xr thr_suspend 2 results in immediate return with success. Only one wake is remembered. .Sh RETURN VALUES .Rv -std thr_wake .Sh ERRORS The .Fn thr_wake operation returns these errors: .Bl -tag -width Er .It Bq Er ESRCH The specified thread was not found or does not belong to the process of the calling thread. .El .Sh SEE ALSO .Xr ps 1 , .Xr thr_self 2 , .Xr thr_suspend 2 , .Xr pthread_cancel 3 , .Xr pthread_resume_np 3 , .Xr pthread_suspend_np 3 .Sh STANDARDS The .Fn thr_suspend system call is non-standard and is used by .Lb libthr to implement .St -p1003.1-2001 .Xr pthread 3 functionality. +.Sh HISTORY +The +.Fn thr_suspend +system call first appeared in +.Fx 5.2 . Index: head/lib/libthr/libthr.3 =================================================================== --- head/lib/libthr/libthr.3 (revision 360669) +++ head/lib/libthr/libthr.3 (revision 360670) @@ -1,294 +1,299 @@ .\" Copyright (c) 2005 Robert N. M. Watson .\" Copyright (c) 2014,2015 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" Part of this documentation was written by .\" Konstantin Belousov 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$ .\" -.Dd May 17, 2016 +.Dd May 5, 2020 .Dt LIBTHR 3 .Os .Sh NAME .Nm libthr .Nd "1:1 POSIX threads library" .Sh LIBRARY .Lb libthr .Sh SYNOPSIS .In pthread.h .Sh DESCRIPTION The .Nm library provides a 1:1 implementation of the .Xr pthread 3 library interfaces for application threading. It has been optimized for use by applications expecting system scope thread semantics. .Pp The library is tightly integrated with the run-time link editor .Xr ld-elf.so.1 1 and .Lb libc ; all three components must be built from the same source tree. Mixing .Li libc and .Nm libraries from different versions of .Fx is not supported. The run-time linker .Xr ld-elf.so.1 1 has some code to ensure backward-compatibility with older versions of .Nm . .Pp The man page documents the quirks and tunables of the .Nm . When linking with .Li -lpthread , the run-time dependency .Li libthr.so.3 is recorded in the produced object. .Sh MUTEX ACQUISITION A locked mutex (see .Xr pthread_mutex_lock 3 ) is represented by a volatile variable of type .Dv lwpid_t , which records the global system identifier of the thread owning the lock. .Nm performs a contested mutex acquisition in three stages, each of which is more resource-consuming than the previous. The first two stages are only applied for a mutex of .Dv PTHREAD_MUTEX_ADAPTIVE_NP type and .Dv PTHREAD_PRIO_NONE protocol (see .Xr pthread_mutexattr 3 ) . .Pp First, on SMP systems, a spin loop is performed, where the library attempts to acquire the lock by .Xr atomic 9 operations. The loop count is controlled by the .Ev LIBPTHREAD_SPINLOOPS environment variable, with a default value of 2000. .Pp If the spin loop was unable to acquire the mutex, a yield loop is executed, performing the same .Xr atomic 9 acquisition attempts as the spin loop, but each attempt is followed by a yield of the CPU time of the thread using the .Xr sched_yield 2 syscall. By default, the yield loop is not executed. This is controlled by the .Ev LIBPTHREAD_YIELDLOOPS environment variable. .Pp If both the spin and yield loops failed to acquire the lock, the thread is taken off the CPU and put to sleep in the kernel with the .Xr _umtx_op 2 syscall. The kernel wakes up a thread and hands the ownership of the lock to the woken thread when the lock becomes available. .Sh THREAD STACKS Each thread is provided with a private user-mode stack area used by the C runtime. The size of the main (initial) thread stack is set by the kernel, and is controlled by the .Dv RLIMIT_STACK process resource limit (see .Xr getrlimit 2 ) . .Pp By default, the main thread's stack size is equal to the value of .Dv RLIMIT_STACK for the process. If the .Ev LIBPTHREAD_SPLITSTACK_MAIN environment variable is present in the process environment (its value does not matter), the main thread's stack is reduced to 4MB on 64bit architectures, and to 2MB on 32bit architectures, when the threading library is initialized. The rest of the address space area which has been reserved by the kernel for the initial process stack is used for non-initial thread stacks in this case. The presence of the .Ev LIBPTHREAD_BIGSTACK_MAIN environment variable overrides .Ev LIBPTHREAD_SPLITSTACK_MAIN ; it is kept for backward-compatibility. .Pp The size of stacks for threads created by the process at run-time with the .Xr pthread_create 3 call is controlled by thread attributes: see .Xr pthread_attr 3 , in particular, the .Xr pthread_attr_setstacksize 3 , .Xr pthread_attr_setguardsize 3 and .Xr pthread_attr_setstackaddr 3 functions. If no attributes for the thread stack size are specified, the default non-initial thread stack size is 2MB for 64bit architectures, and 1MB for 32bit architectures. .Sh RUN-TIME SETTINGS The following environment variables are recognized by .Nm and adjust the operation of the library at run-time: .Bl -tag -width "Ev LIBPTHREAD_SPLITSTACK_MAIN" .It Ev LIBPTHREAD_BIGSTACK_MAIN Disables the reduction of the initial thread stack enabled by .Ev LIBPTHREAD_SPLITSTACK_MAIN . .It Ev LIBPTHREAD_SPLITSTACK_MAIN Causes a reduction of the initial thread stack, as described in the section .Sx THREAD STACKS . This was the default behaviour of .Nm before .Fx 11.0 . .It Ev LIBPTHREAD_SPINLOOPS The integer value of the variable overrides the default count of iterations in the .Li spin loop of the mutex acquisition. The default count is 2000, set by the .Dv MUTEX_ADAPTIVE_SPINS constant in the .Nm sources. .It Ev LIBPTHREAD_YIELDLOOPS A non-zero integer value enables the yield loop in the process of the mutex acquisition. The value is the count of loop operations. .It Ev LIBPTHREAD_QUEUE_FIFO The integer value of the variable specifies how often blocked threads are inserted at the head of the sleep queue, instead of its tail. Bigger values reduce the frequency of the FIFO discipline. The value must be between 0 and 255. .Pp .El The following .Dv sysctl MIBs affect the operation of the library: .Bl -tag -width "Dv debug.umtx.robust_faults_verbose" .It Dv kern.ipc.umtx_vnode_persistent By default, a shared lock backed by a mapped file in memory is automatically destroyed on the last unmap of the corresponding file's page, which is allowed by POSIX. Setting the sysctl to 1 makes such a shared lock object persist until the vnode is recycled by the Virtual File System. Note that in case file is not opened and not mapped, the kernel might recycle it at any moment, making this sysctl less useful than it sounds. .It Dv kern.ipc.umtx_max_robust The maximal number of robust mutexes allowed for one thread. The kernel will not unlock more mutexes than specified, see .Xr _umtx_op for more details. The default value is large enough for most useful applications. .It Dv debug.umtx.robust_faults_verbose A non zero value makes kernel emit some diagnostic when the robust mutexes unlock was prematurely aborted after detecting some inconsistency, as a measure to prevent memory corruption. .El .Pp The .Dv RLIMIT_UMTXP limit (see .Xr getrlimit 2 ) defines how many shared locks a given user may create simultaneously. .Sh INTERACTION WITH RUN-TIME LINKER On load, .Nm installs interposing handlers into the hooks exported by .Li libc . The interposers provide real locking implementation instead of the stubs for single-threaded processes in .Li libc , cancellation support and some modifications to the signal operations. .Pp .Nm cannot be unloaded; the .Xr dlclose 3 function does not perform any action when called with a handle for .Nm . One of the reasons is that the internal interposing of .Li libc functions cannot be undone. .Sh SIGNALS The implementation interposes the user-installed .Xr signal 3 handlers. This interposing is done to postpone signal delivery to threads which entered (libthr-internal) critical sections, where the calling of the user-provided signal handler is unsafe. An example of such a situation is owning the internal library lock. When a signal is delivered while the signal handler cannot be safely called, the call is postponed and performed until after the exit from the critical section. This should be taken into account when interpreting .Xr ktrace 1 logs. .Sh SEE ALSO .Xr ktrace 1 , .Xr ld-elf.so.1 1 , .Xr getrlimit 2 , .Xr errno 2 , .Xr thr_exit 2 , .Xr thr_kill 2 , .Xr thr_kill2 2 , .Xr thr_new 2 , .Xr thr_self 2 , .Xr thr_set_name 2 , .Xr _umtx_op 2 , .Xr dlclose 3 , .Xr dlopen 3 , .Xr getenv 3 , .Xr pthread_attr 3 , .Xr pthread_attr_setstacksize 3 , .Xr pthread_create 3 , .Xr signal 3 , .Xr atomic 9 +.Sh HISTORY +The +.Nm +library first appeared in +.Fx 5.2 . .Sh AUTHORS .An -nosplit The .Nm library was originally created by .An Jeff Roberson Aq Mt jeff@FreeBSD.org , and enhanced by .An Jonathan Mini Aq Mt mini@FreeBSD.org and .An Mike Makonnen Aq Mt mtm@FreeBSD.org . It has been substantially rewritten and optimized by .An David Xu Aq Mt davidxu@FreeBSD.org .