sunos man page for timeout

timeout(9F)						   Kernel Functions for Drivers 					       timeout(9F)

NAME
       timeout - execute a function after a specified length of time

SYNOPSIS
       #include <sys/types.h>
       #include <sys/conf.h>

       timeout_id_t timeout(void (* func)(void *), void *arg, clock_t  ticks);

INTERFACE LEVEL
       Architecture independent level 1 (DDI/DKI).

PARAMETERS
       func	       Kernel function to invoke when the time increment expires.

       arg	       Argument to the function.

       ticks	       Number of clock ticks to wait before the function is called. Use drv_usectohz(9F) to convert microseconds to clock ticks.

DESCRIPTION
       The  timeout()  function  schedules the specified function to be called after a specified time interval. The exact time interval over which
       the timeout takes effect cannot be guaranteed, but the value given is a close approximation.

       The function called by timeout() must adhere to the same restrictions as a driver soft interrupt handler.

       The delay(9F) function calls timeout(). Because timeout() is subject to priority inversion, drivers waiting on  behalf  of  processes  with
       real-time constraints should use cv_timedwait(9F) rather than delay().

RETURN VALUES
       timeout() returns an opaque non-zero timeout identifier that can be passed to untimeout(9F) to cancel the request.

CONTEXT
       timeout() can be called from user or interrupt context.

EXAMPLES
       Example 1: Using timeout()

       In  the	following  example,  the  device  driver has issued an IO request and is waiting for the device to respond. If the device does not
       respond within 5 seconds, the device driver will print out an error message to the console.

       static void
       xxtimeout_handler(void *arg)
       {
	       struct xxstate *xsp = (struct xxstate *)arg;
	       mutex_enter(&xsp->lock);
	       cv_signal(&xsp->cv);
	       xsp->flags |= TIMED_OUT;
	       mutex_exit(&xsp->lock);
	       xsp->timeout_id = 0;
       }
       static uint_t
       xxintr(caddr_t arg)
       {
	       struct xxstate *xsp = (struct xxstate *)arg;
		.
		.
		.
	       mutex_enter(&xsp->lock);
	       /* Service interrupt */
	       cv_signal(&xsp->cv);
	       mutex_exit(&xsp->lock);
	       if (xsp->timeout_id != 0) {
		       (void) untimeout(xsp->timeout_id);
		       xsp->timeout_id = 0;
	       }
	       return(DDI_INTR_CLAIMED);
       }
       static void
       xxcheckcond(struct xxstate *xsp)
       {
		.
		.
		.
	       xsp->timeout_id = timeout(xxtimeout_handler,
		   xsp, (5 * drv_usectohz(1000000)));
	       mutex_enter(&xsp->lock);
	       while (/* Waiting for interrupt	or timeout*/)
		       cv_wait(&xsp->cv, &xsp->lock);
	       if (xsp->flags & TIMED_OUT)
		       cmn_err(CE_WARN, "Device not responding");
		.
		.
		.
	       mutex_exit(&xsp->lock);
		.
		.
		.
       }

SEE ALSO
       bufcall(9F), cv_timedwait(9F), ddi_in_panic(9F), delay(9F), drv_usectohz(9F), untimeout(9F)

       Writing Device Drivers

SunOS 5.10							    15 Oct 2001 						       timeout(9F)