1.\" $NetBSD: _lwp_park.2,v 1.6 2007/09/25 09:42:51 tnn Exp $ 2.\" 3.\" Copyright (c) 2003, 2007 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 25, 2007 38.Dt _LWP_PARK 2 39.Os 40.Sh NAME 41.Nm _lwp_park 42.Nd wait interruptably in the kernel 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In lwp.h 47.Ft int 48.Fn _lwp_park "const struct timespec *abstime" "lwpid_t unpark" "const void *hint" "const void *unparkhint" 49.Sh DESCRIPTION 50.Fn _lwp_park 51can be used to synchronize access to resources among multiple light-weight 52processes. 53It causes the calling LWP to wait interruptably in the kernel, until one 54of the following conditions is met: 55.Bl -bullet 56.It 57The 58.Fa abstime 59argument is non-NULL, and the absolute UTC time it specifies has passed. 60.It 61The LWP receives a directed signal posted using 62.Fn _lwp_kill , 63or is elected to handle a signal on behalf of its containing process. 64.It 65The LWP is awoken by another LWP in the same process that has made 66a call to 67.Fn _lwp_wakeup . 68.It 69The LWP is awoken by another LWP in the same process that has made 70a call to 71.Fn _lwp_unpark 72or 73.Fn _lwp_unpark_all . 74.El 75.Pp 76The preferred method to awaken an LWP sleeping as a result of a call 77to 78.Fn _lwp_park 79is to make a call to 80.Fn _lwp_unpark , 81or 82.Fn _lwp_unpark_all . 83The 84.Fn _lwp_wakeup 85system call is a more general facility, and requires more resources 86to execute. 87.Pp 88The optional 89.Fa hint 90argument specifies the address of object upon which the LWP is 91synchronizing. 92When the 93.Fa hint 94value is matched between calls to 95.Fn _lwp_park 96and 97.Fn _lwp_unpark 98or 99.Fn _lwp_unpark_all , 100it may reduce the time necessary for the system to resume execution 101of waiting LWPs. 102.Pp 103The 104.Fa unpark 105and 106.Fa unparkhint 107arguments can be used to fold a park operation and unpark operation into a 108single system call. 109If 110.Fa unpark 111is non-zero, the system will behave as if the following call had been made 112before the calling thread begins to wait: 113.Bd -literal 114 _lwp_unpark(unpark, unparkhint); 115.Ed 116.Sh RETURN VALUES 117.Fn _lwp_park 118may return a value of 0. 119Otherwise, \-1 is returned and 120.Va errno 121is set to provide more information. 122.Sh ERRORS 123.Bl -tag -width [EINVAL] 124.It Bq Er EALREADY 125A request was made to wake the LWP before it began to wait in 126the kernel. 127.It Bq Er EINTR 128The LWP has been awoken by a signal or by a call to one of the 129following functions: 130.Fn _lwp_unpark , 131.Fn _lwp_unpark_all , 132.Fn _lwp_wakeup . 133.It Bq Er EINVAL 134The time value specified by 135.Fa abstime 136is invalid. 137.It Bq Er ESRCH 138No LWP can be found in the current process corresponding to 139.Fa unpark . 140.It Bq Er ETIMEDOUT 141The UTC time specified by 142.Fa abstime 143has passed. 144.El 145.Sh SEE ALSO 146.Xr _lwp_unpark 2 , 147.Xr _lwp_unpark_all 2 , 148.Xr _lwp_wakeup 2 149.Sh HISTORY 150The 151.Fn _lwp_park 152system call first appeared in 153.Nx 5.0 . 154