'\"macro stdmacro
.if n .pH ddi_dki.timeout @(#)timeout	40.7 of 10/10/89
.\" Copyright 1989 AT&T
.de IX
.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.nr X
.if \nX=0 .ds x} timeout D3DK "" "DDI/DKI" "\&"
.if \nX=1 .ds x} timeout D3DK "" "DDI/DKI"
.if \nX=2 .ds x} timeout D3DK "" "\&"
.if \nX=3 .ds x} timeout "" "" "\&"
.TH \*(x}
.IX "\f4timeout\fP(D3DK)"
.SH NAME
\f4timeout\f1 \- execute a function after a specified length of time
.SH SYNOPSIS
.nf
.na
\f4#include <sys/types.h>
.sp 0.5
int timeout(int (*\f2ftn\f4)(), caddr_t \f2arg, \f4long \f2ticks\f4);\f1
.ad
.fi
.SH ARGUMENTS
.RS 0n 10
.IP "\f2ftn\f1" 10n
Kernel function to invoke when the time increment expires.
.IP "\f2arg\f1" 10n
Argument to the function.
.IP "\f2ticks\f1" 10n
Number of clock ticks to wait before the function is called.
.RE
.SH DESCRIPTION
The \f4timeout\f1 function  schedules the specified function to be
called after a specified time interval.  Control is immediately returned
to the caller. This is useful when an event is known to occur within a
specific time frame, or when you want to wait for I/O processes when an
interrupt is not available or might cause problems.  For example, some
robotics applications do not provide a status flag for determining when
to pump information to the robot's controller.  By using
\f4timeout\f1, the driver can wait a predetermined interval and then
begin transferring data to the robot.
.P
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 \f4timeout\f1 must adhere to the same restrictions as a
driver interrupt handler.  It can neither sleep
nor use previously set local variables.
.SH RETURN VALUE
Under normal conditions,
an integer timeout identifier
is returned (which may,
in unusual circumstances,
be set to 0).
Otherwise,
if
the \f4timeout\f1 table is full,
the following panic message results:
.P
.RS
\f4PANIC:  Timeout table overflow\f1
.RE
.P
The \f4timeout\f1 function returns an identifier that may be passed to
the \f4untimeout\f1(D3DK) function to cancel a pending request.
\f3NOTE:\f1
No value is returned from the called function.
.SH LEVEL
Base or Interrupt
.SH SEE ALSO
\f2BCI Driver Development Guide\f1, Chapter 10, ``Synchronizing Hardware and Software Events''
.P
.na
\f4delay\f1(D3DKK),
\f4biodone\f1(D3DK),
\f4biowait\f1(D3DK),
\f4sleep\f1(D3DK),
\f4untimeout\f1(D3DK),
\f4wakeup\f1(D3DK)
.ad
.SH EXAMPLE
See the \f4bufcall\f1(D3DK) function page for an example of \f4timeout\f1.
