1.\" $NetBSD: _lwp_park.2,v 1.9 2014/01/31 21:11:05 wiz 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.\" 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 March 28, 2013 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" "const 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 an relative interval to wait if the 58.Ar flags 59argument does not contain 60.Dv TIMER_ABSTIME 61or it can be an absolute time compared to 62.Dv CLOCK_REALTIME 63or 64.Dv CLOCK_MONOTONIC 65depending on the value 66of the 67.Ar clock_id 68argument. 69.It 70The LWP receives a directed signal posted using 71.Fn _lwp_kill , 72or is elected to handle a signal on behalf of its containing process. 73.It 74The LWP is awoken by another LWP in the same process that has made 75a call to 76.Fn _lwp_wakeup . 77.It 78The LWP is awoken by another LWP in the same process that has made 79a call to 80.Fn _lwp_unpark 81or 82.Fn _lwp_unpark_all . 83.El 84.Pp 85The preferred method to awaken an LWP sleeping as a result of a call 86to 87.Fn _lwp_park 88is to make a call to 89.Fn _lwp_unpark , 90or 91.Fn _lwp_unpark_all . 92The 93.Fn _lwp_wakeup 94system call is a more general facility, and requires more resources 95to execute. 96.Pp 97The optional 98.Fa hint 99argument specifies the address of object upon which the LWP is 100synchronizing. 101When the 102.Fa hint 103value is matched between calls to 104.Fn _lwp_park 105and 106.Fn _lwp_unpark 107or 108.Fn _lwp_unpark_all , 109it may reduce the time necessary for the system to resume execution 110of waiting LWPs. 111.Pp 112The 113.Fa unpark 114and 115.Fa unparkhint 116arguments can be used to fold a park operation and unpark operation into a 117single system call. 118If 119.Fa unpark 120is non-zero, the system will behave as if the following call had been made 121before the calling thread begins to wait: 122.Bd -literal 123 _lwp_unpark(unpark, unparkhint); 124.Ed 125.Sh RETURN VALUES 126.Fn _lwp_park 127may return a value of 0. 128Otherwise, \-1 is returned and 129.Va errno 130is set to provide more information. 131.Sh ERRORS 132.Bl -tag -width [EINVAL] 133.It Bq Er EALREADY 134A request was made to wake the LWP before it began to wait in 135the kernel. 136.It Bq Er EINTR 137The LWP has been awoken by a signal or by a call to one of the 138following functions: 139.Fn _lwp_unpark , 140.Fn _lwp_unpark_all , 141.Fn _lwp_wakeup . 142.It Bq Er EINVAL 143The time value specified by 144.Fa ts 145is invalid. 146.It Bq Er ESRCH 147No LWP can be found in the current process corresponding to 148.Fa unpark . 149.It Bq Er ETIMEDOUT 150The UTC time specified by 151.Fa ts 152has passed. 153.El 154.Sh SEE ALSO 155.Xr _lwp_unpark 2 , 156.Xr _lwp_unpark_all 2 , 157.Xr _lwp_wakeup 2 158.Sh HISTORY 159The 160.Fn _lwp_park 161system call first appeared in 162.Nx 5.0 . 163