Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SLEEP(9)		 BSD Kernel Developer's	Manual		      SLEEP(9)

     msleep, msleep_spin, pause, tsleep, wakeup	-- wait	for events

     #include <sys/param.h>
     #include <sys/systm.h>
     #include <sys/proc.h>

     msleep(void *chan,	struct mtx *mtx, int priority, const char *wmesg,
	 int timo);

     msleep_spin(void *chan, struct mtx	*mtx, const char *wmesg, int timo);

     pause(const char *wmesg, int timo);

     tsleep(void *chan,	int priority, const char *wmesg, int timo);

     wakeup(void *chan);

     wakeup_one(void *chan);

     The functions tsleep(), msleep(), msleep_spin(), pause(), wakeup(), and
     wakeup_one() handle event-based thread blocking.  If a thread must	wait
     for an external event, it is put to sleep by tsleep(), msleep(),
     msleep_spin(), or pause().	 Threads may also wait using one of the	lock-
     ing primitive sleep routines mtx_sleep(9),	rw_sleep(9), or	sx_sleep(9).

     The parameter chan	is an arbitrary	address	that uniquely identifies the
     event on which the	thread is being	put to sleep.  All threads sleeping on
     a single chan are woken up	later by wakeup(), often called	from inside an
     interrupt routine,	to indicate that the resource the thread was blocking
     on	is available now.

     The parameter priority specifies a	new priority for the thread as well as
     some optional flags.  If the new priority is not 0, then the thread will
     be	made runnable with the specified priority when it resumes.  PZERO
     should never be used, as it is for	compatibility only.  A new priority of
     0 means to	use the	thread's current priority when it is made runnable

     If	priority includes the PCATCH flag, signals are checked before and af-
     ter sleeping, otherwise signals are not checked.  If PCATCH is set	and a
     signal needs to be	delivered, ERESTART is returned	if the current system
     call should be restarted if possible, and EINTR is	returned if the	system
     call should be interrupted	by the signal (return EINTR).  If PBDRY	flag
     is	specified in addition to PCATCH, then the sleeping thread is not
     stopped while sleeping upon delivery of SIGSTOP or	other stop action.
     Instead, it is waken up, assuming that stop occurs	on reaching a stop
     point when	returning to usermode.	The flag should	be used	when sleeping
     thread owns resources, for	instance vnode locks, that should be freed

     The parameter wmesg is a string describing	the sleep condition for	tools
     like ps(1).  Due to the limited space of those programs to	display	arbi-
     trary strings, this message should	not be longer than 6 characters.

     The parameter timo	specifies a timeout for	the sleep.  If timo is not 0,
     then the thread will sleep	for at most timo / hz seconds.	If the timeout
     expires, then the sleep function will return EWOULDBLOCK.

     Several of	the sleep functions including msleep(),	msleep_spin(), and the
     locking primitive sleep routines specify an additional lock parameter.
     The lock will be released before sleeping and reacquired before the sleep
     routine returns.  If priority includes the	PDROP flag, then the lock will
     not be reacquired before returning.  The lock is used to ensure that a
     condition can be checked atomically, and that the current thread can be
     suspended without missing a change	to the condition, or an	associated
     wakeup.  In addition, all of the sleep routines will fully	drop the Giant
     mutex (even if recursed) while the	thread is suspended and	will reacquire
     the Giant mutex before the	function returns.  Note	that the Giant mutex
     may be specified as the lock to drop.  In that case, however, the PDROP
     flag is not allowed.

     To	avoid lost wakeups, either a lock should be used to protect against
     races, or a timeout should	be specified to	place an upper bound on	the
     delay due to a lost wakeup.  As a result, the tsleep() function should
     only be invoked with a timeout of 0 when the Giant	mutex is held.

     The msleep() function requires that mtx reference a default, i.e. non-
     spin, mutex.  Its use is deprecated in favor of mtx_sleep(9) which	pro-
     vides identical behavior.

     The msleep_spin() function	requires that mtx reference a spin mutex.  The
     msleep_spin() function does not accept a priority parameter and thus does
     not support changing the current thread's priority, the PDROP flag, or
     catching signals via the PCATCH flag.

     The pause() function is a wrapper around tsleep() that suspends execution
     of	the current thread for the indicated timeout.  The thread can not be
     awakened early by signals or calls	to wakeup() or wakeup_one().

     The wakeup_one() function makes the first thread in the queue that	is
     sleeping on the parameter chan runnable.  This reduces the	load when a
     large number of threads are sleeping on the same address, but only	one of
     them can actually do any useful work when made runnable.

     Due to the	way it works, the wakeup_one() function	requires that only re-
     lated threads sleep on a specific chan address.  It is the	programmer's
     responsibility to choose a	unique chan value.  The	older wakeup() func-
     tion did not require this,	though it was never good practice for threads
     to	share a	chan value.  When converting from wakeup() to wakeup_one(),
     pay particular attention to ensure	that no	other threads wait on the same

     If	the thread is awakened by a call to wakeup() or	wakeup_one(), the
     msleep(), msleep_spin(), tsleep(),	and locking primitive sleep functions
     return 0.	Otherwise, a non-zero error code is returned.

     msleep(), msleep_spin(), tsleep(),	and the	locking	primitive sleep	func-
     tions will	fail if:

     [EINTR]		The PCATCH flag	was specified, a signal	was caught,
			and the	system call should be interrupted.

     [ERESTART]		The PCATCH flag	was specified, a signal	was caught,
			and the	system call should be restarted.

     [EWOULDBLOCK]	A non-zero timeout was specified and the timeout ex-

     ps(1), locking(9),	malloc(9), mi_switch(9), mtx_sleep(9), rw_sleep(9),

     The functions sleep() and wakeup()	were present in	Version	1 AT&T UNIX.
     They were probably	also present in	the preceding PDP-7 version of UNIX.
     They were the basic process synchronization model.

     The tsleep() function appeared in 4.4BSD and added	the parameters wmesg
     and timo.	The sleep() function was removed in FreeBSD 2.2.  The
     wakeup_one() function appeared in FreeBSD 2.2.  The msleep() function ap-
     peared in FreeBSD 5.0, and	the msleep_spin() function appeared in
     FreeBSD 6.2.  The pause() function	appeared in FreeBSD 7.0.

     This manual page was written by Jorg Wunsch <>.

BSD			       December	12, 2009			   BSD


Want to link to this manual page? Use this URL:

home | help