1.\" $NetBSD: kpause.9,v 1.5 2008/08/06 07:08:31 skrll Exp $ 2.\" 3.\" Copyright (c) 2006, 2007 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" 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.\" ------------------------------------------------------------ 31.Dd January 2, 2008 32.Dt KPAUSE 9 33.Os 34.\" ------------------------------------------------------------ 35.Sh NAME 36.Nm kpause 37.Nd make the calling LWP sleep 38.\" ------------------------------------------------------------ 39.Sh SYNOPSIS 40.In sys/proc.h 41.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 42.Ft int 43.Fn kpause \ 44"const char *wmesg" "bool intr" "int timeo" "kmutex_t *mtx" 45.\" ------------------------------------------------------------ 46.Sh DESCRIPTION 47.Fn kpause 48makes the calling LWP sleep. 49It's similar to 50.Xr cv_timedwait_sig 9 51without the corresponding 52.Xr cv_signal 9 . 53.Pp 54.Fn kpause 55can wake up spontaneously. 56Callers should prepare to handle it. 57.Pp 58.Bl -tag -width wmesg 59.It Fa wmesg 60Specifies a string of no more than 8 characters that describes 61the resource or condition associated with the call of 62.Fn kpause . 63The kernel does not use this argument directly but makes it available for 64utilities such as 65.Xr ps 1 66to display. 67.It Fa intr 68If true, sleep interruptably. 69If the LWP receives a signal, or is interrupted by another condition such 70as its containing process exiting, the wait is ended early and an error 71code returned. 72.It Fa timeo 73Specify a timeout. 74It is an architecture and system dependent value related to the number of 75clock interrupts per second. 76See 77.Xr hz 9 78for details. 79The 80.Xr mstohz 9 81macro can be used to convert a timeout expressed in milliseconds to 82one suitable for 83.Fn kpause . 84.Pp 85Zero means no timeout. 86.It Fa mtx 87Convenience and symmetry with other synchronization operations. 88If not 89.Dv NULL , 90.Fa mtx 91will be released once the LWP has prepared to sleep, and will be reacquired 92before 93.Fn kpause 94returns. 95.El 96.\" ------------------------------------------------------------ 97.Sh RETURN VALUES 98.Fn kpause 99returns 0 when waking up spontaneously. 100Otherwise, 101It returns an error number. 102.\" ------------------------------------------------------------ 103.Sh ERRORS 104.Bl -tag -width Er 105.It Bq Er EWOULDBLOCK 106The timeout expired. 107.It Bq Er ERESTART 108.Fn kpause 109returned as a result of a signal with 110.Dv SA_RESTART 111property. 112.It Bq Er EINTR 113.Fn kpause 114returned due to other reasons. 115Typically as a result of a signal without 116.Dv SA_RESTART 117property. 118.El 119.\" ------------------------------------------------------------ 120.Sh SEE ALSO 121.Xr sigaction 2 , 122.Xr errno 9 , 123.Xr condvar 9 , 124.Xr mstohz 9 , 125.Xr hz 9 126