share/man/man9f/qtimeout.9f

   1 '\" te
   2 .\"  Copyright (c) 2006, Sun Microsystems, Inc.
   3 .\" All Rights Reserved
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH QTIMEOUT 9F "Jan 16, 2006"
   8 .SH NAME
   9 qtimeout \- execute a function after a specified length of time
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/stream.h>
  14 #include <sys/ddi.h>
  15
  16
  17 \fBtimeout_id_t\fR \fBqtimeout\fR(\fBqueue_t *\fR\fIq\fR, \fBvoid\fR (\fI*func\fR)(\fIvoid *\fR),
  18      \fBvoid\fR \fI*arg\fR, \fBclock_t\fR \fIticks\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI).
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIq\fR\fR
  30 .ad
  31 .RS 9n
  32 Pointer to \fBSTREAMS\fR queue structure.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIfunc\fR\fR
  39 .ad
  40 .RS 9n
  41 Kernel function to invoke when the time increment expires.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIarg\fR\fR
  48 .ad
  49 .RS 9n
  50 Argument to the function.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIticks\fR\fR
  57 .ad
  58 .RS 9n
  59 Number of clock ticks to wait before the function is called. Use
  60 \fBdrv_usectohz\fR(9F) to convert microseconds to clock ticks.
  61 .RE
  62
  63 .SH DESCRIPTION
  64 .sp
  65 .LP
  66 The \fBqtimeout()\fR function schedules the specified function \fIfunc\fR to be
  67 called after a specified time interval. \fIfunc\fR is called with \fIarg\fR as
  68 a parameter. Control is immediately returned to the caller. This is useful when
  69 an event is known to occur within a specific time frame, or when you want to
  70 wait for I/O processes when an interrupt is not available or might cause
  71 problems. The exact time interval over which the timeout takes effect cannot be
  72 guaranteed, but the value given is a close approximation.
  73 .sp
  74 .LP
  75 The \fBqtimeout()\fR function is tailored to be used with the enhanced
  76 \fBSTREAMS \fRframework interface which is based on the concept of perimeters.
  77 (See \fBmt-streams\fR(9F).) \fBqtimeout()\fR schedules the specified function
  78 to execute after entering the perimeters associated with the queue passed in as
  79 the first parameter to \fBqtimeout()\fR. All outstanding timeouts and bufcalls
  80 must be cancelled (using, respectively, \fBquntimeout\fR(9F) and
  81 \fBqunbufcall\fR(9F)) before a driver close routine can block and before the
  82 close  routine calls \fBqprocsoff\fR(9F).
  83 .sp
  84 .LP
  85 The \fBqprocson\fR(9F) function must be called before calling \fBqtimeout()\fR.
  86 .SH RETURN VALUES
  87 .sp
  88 .LP
  89 The \fBqtimeout()\fR function returns an opaque non-zero \fBtimeout\fR
  90 identifier that can be passed to \fBquntimeout\fR(9F) to cancel the request.
  91 Note: No value is returned from the called function.
  92 .SH CONTEXT
  93 .sp
  94 .LP
  95 The \fBqtimeout()\fR function can be called from user, interrupt, or kernel
  96 context.
  97 .SH SEE ALSO
  98 .sp
  99 .LP
 100 \fBdrv_usectohz\fR(9F), \fBmt-streams\fR(9F), \fBqbufcall\fR(9F),
 101 \fBqprocson\fR(9F), \fBqunbufcall\fR(9F), \fBquntimeout\fR(9F)
 102 .sp
 103 .LP
 104 \fIWriting Device Drivers\fR
 105 .sp
 106 .LP
 107 \fISTREAMS Programming Guide\fR