1.\" $NetBSD: _lwp_park.2,v 1.12 2019/07/31 23:53:25 pgoyette Exp $ 2.\" 3.\" Copyright (c) 2003, 2007, 2017 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe of Wasabi Systems, Inc, and by Andrew Doran. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd July 30, 2019 31.Dt _LWP_PARK 2 32.Os 33.Sh NAME 34.Nm _lwp_park 35.Nd wait interruptably in the kernel 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In lwp.h 40.Ft int 41.Fn _lwp_park "clockid_t clock_id" "int flags" "struct timespec *ts" "lwpid_t unpark" "const void *hint" "const void *unparkhint" 42.Sh DESCRIPTION 43.Fn _lwp_park 44can be used to synchronize access to resources among multiple light-weight 45processes. 46It causes the calling LWP to wait interruptably in the kernel, until one 47of the following conditions is met: 48.Bl -bullet 49.It 50The 51.Fa ts 52argument is 53.Pf non- Dv NULL , 54and the time it specifies has passed. 55The 56.Fa ts 57time can be a relative interval to wait if the 58.Ar flags 59argument does not contain 60.Dv TIMER_ABSTIME 61or it can be an absolute time. 62The 63.Fa clock_id 64argument contains the clock to be used; it can be: 65.Dv CLOCK_REALTIME 66or 67.Dv CLOCK_MONOTONIC . 68.It 69The LWP receives a directed signal posted using 70.Fn _lwp_kill , 71or is elected to handle a signal on behalf of its containing process. 72.It 73The LWP is awoken by another LWP in the same process that has made 74a call to 75.Fn _lwp_wakeup . 76.It 77The LWP is awoken by another LWP in the same process that has made 78a call to 79.Fn _lwp_unpark 80or 81.Fn _lwp_unpark_all . 82.El 83.Pp 84If the 85.Fa ts 86argument contains a relative time interval, it will be modified to contain 87the remaining time to sleep when 88.Fn _lwp_park 89returns. 90.Pp 91The preferred method to awaken an LWP sleeping as a result of a call 92to 93.Fn _lwp_park 94is to make a call to 95.Fn _lwp_unpark , 96or 97.Fn _lwp_unpark_all . 98The 99.Fn _lwp_wakeup 100system call is a more general facility, and requires more resources 101to execute. 102.Pp 103The optional 104.Fa hint 105argument specifies the address of an object upon which the LWP is 106synchronizing. 107When the 108.Fa hint 109value is matched between calls to 110.Fn _lwp_park 111and 112.Fn _lwp_unpark 113or 114.Fn _lwp_unpark_all , 115it may reduce the time necessary for the system to resume execution 116of waiting LWPs. 117.Pp 118The 119.Fa unpark 120and 121.Fa unparkhint 122arguments can be used to fold a park operation and unpark operation into a 123single system call. 124If 125.Fa unpark 126is non-zero, the system will behave as if the following call had been made 127before the calling thread begins to wait: 128.Bd -literal 129 _lwp_unpark(unpark, unparkhint); 130.Ed 131.Sh RETURN VALUES 132.Fn _lwp_park 133may return a value of 0. 134Otherwise, \-1 is returned and 135.Va errno 136is set to provide more information. 137.Sh ERRORS 138.Bl -tag -width [EINVAL] 139.It Bq Er EALREADY 140A request was made to wake the LWP before it began to wait in 141the kernel. 142.It Bq Er EINTR 143The LWP has been awoken by a signal or by a call to one of the 144following functions: 145.Fn _lwp_unpark , 146.Fn _lwp_unpark_all , 147.Fn _lwp_wakeup . 148.It Bq Er EINVAL 149The time value specified by 150.Fa ts 151is invalid. 152.It Bq Er ESRCH 153No LWP can be found in the current process corresponding to 154.Fa unpark . 155.It Bq Er ETIMEDOUT 156The UTC time specified by 157.Fa ts 158has passed. 159.El 160.Sh SEE ALSO 161.Xr _lwp_unpark 2 , 162.Xr _lwp_unpark_all 2 , 163.Xr _lwp_wakeup 2 164.Sh HISTORY 165The 166.Fn _lwp_park 167system call first appeared in 168.Nx 5.0 . 169