man/man9f/qtimeout.9f

         te
 Copyright (c) 2006, Sun Microsystems, Inc.
 All Rights Reserved
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
 When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 QTIMEOUT 9F "Jan 16, 2006"
 NAME
qtimeout - execute a function after a specified length of time
 SYNOPSIS
#include <sys/stream.h>
#include <sys/ddi.h>


timeout_id_t qtimeout(queue_t *q, void (*func)(void *),
 void *arg, clock_t ticks);


 INTERFACE LEVEL
illumos DDI specific (illumos DDI).
 PARAMETERS
q

Pointer to STREAMS queue structure.


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 qtimeout() function schedules the specified function func to be
called after a specified time interval. func is called with arg as
a parameter. 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. The exact time interval over which the timeout takes effect cannot be
guaranteed, but the value given is a close approximation.

The qtimeout() function is tailored to be used with the enhanced
STREAMS framework interface which is based on the concept of perimeters.
(See mt-streams(9F).) qtimeout() schedules the specified function
to execute after entering the perimeters associated with the queue passed in as
the first parameter to qtimeout(). All outstanding timeouts and bufcalls
must be cancelled (using, respectively, quntimeout(9F) and
qunbufcall(9F)) before a driver close routine can block and before the
close routine calls qprocsoff(9F).

The qprocson(9F) function must be called before calling qtimeout().
 RETURN VALUES
The qtimeout() function returns an opaque non-zero timeout
identifier that can be passed to quntimeout(9F) to cancel the request.
Note: No value is returned from the called function.
 CONTEXT
The qtimeout() function can be called from user, interrupt, or kernel
context.
 SEE ALSO
drv_usectohz(9F), mt-streams(9F), qbufcall(9F),
qprocson(9F), qunbufcall(9F), quntimeout(9F)

Writing Device Drivers

STREAMS Programming Guide