share/man/man9f/qbufcall.9f

   1 '\" te
   2 .\"  Copyright (c) 2006, Sun Microsystems, Inc.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH QBUFCALL 9F "Jan 16, 2006"
   7 .SH NAME
   8 qbufcall \- call a function when a buffer becomes available
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/stream.h>
  13 #include <sys/ddi.h>
  14
  15
  16
  17 \fBbufcall_id_t\fR \fBqbufcall\fR(\fBqueue_t *\fR\fIq\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR,
  18      \fBvoid\fR(\fI*func\fR)(\fBvoid\fR \fI*arg\fR), \fBvoid\fR \fI*arg\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 8n
  32 Pointer to \fBSTREAMS \fRqueue structure.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIsize\fR\fR
  39 .ad
  40 .RS 8n
  41 Number of bytes required for the buffer.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIpri\fR\fR
  48 .ad
  49 .RS 8n
  50 Priority of the \fBallocb\fR(9F) allocation request (not used).
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIfunc\fR\fR
  57 .ad
  58 .RS 8n
  59 Function or driver routine to be called when a buffer becomes available.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIarg\fR\fR
  66 .ad
  67 .RS 8n
  68 Argument to the function to be called when a buffer becomes available.
  69 .RE
  70
  71 .SH DESCRIPTION
  72 .sp
  73 .LP
  74 The \fBqbufcall()\fR function serves as a \fBqtimeout\fR(9F) call of
  75 indeterminate length. When a buffer allocation request fails, \fBqbufcall()\fR
  76 can be used to schedule the routine \fIfunc\fR to be called with the argument
  77 \fIarg\fR when a buffer becomes available. \fIfunc\fR may call \fBallocb()\fR
  78 or it may do something else.
  79 .sp
  80 .LP
  81 The \fBqbufcall()\fR function is tailored to be used with the enhanced
  82 \fBSTREAMS \fRframework interface, which is based on the concept of perimeters.
  83 (See \fBmt-streams\fR(9F).) \fBqbufcall()\fR schedules the specified function
  84 to execute after entering the perimeters associated with the queue passed in as
  85 the first parameter to \fBqbufcall()\fR. All outstanding timeouts and bufcalls
  86 must be cancelled (using, respectively, \fBquntimeout\fR(9F) and
  87 \fBqunbufcall\fR(9F)) before a driver close routine can block and before the
  88 close  routine calls \fBqprocsoff\fR(9F).
  89 .sp
  90 .LP
  91 \fBqprocson\fR(9F) must be called before calling either \fBqbufcall()\fR or
  92 \fBqtimeout\fR(9F).
  93 .SH RETURN VALUES
  94 .sp
  95 .LP
  96 If successful, the \fBqbufcall()\fR function returns a \fBqbufcall\fR \fBID\fR
  97 that can be used in a call to \fBqunbufcall\fR(9F) to cancel the request. If
  98 the \fBqbufcall()\fR scheduling fails, \fIfunc\fR is never called and \fB0\fR
  99 is returned.
 100 .SH CONTEXT
 101 .sp
 102 .LP
 103 The \fBqbufcall()\fR function can be called from user, interrupt, or kernel
 104 context.
 105 .SH SEE ALSO
 106 .sp
 107 .LP
 108 \fBallocb\fR(9F), \fBmt-streams\fR(9F), \fBqprocson\fR(9F), \fBqtimeout\fR(9F),
 109 \fBqunbufcall\fR(9F), \fBquntimeout\fR(9F)
 110 .sp
 111 .LP
 112 \fIWriting Device Drivers\fR
 113 .sp
 114 .LP
 115 \fISTREAMS Programming Guide\fR
 116 .SH WARNINGS
 117 .sp
 118 .LP
 119 Even when \fIfunc\fR is called by \fBqbufcall()\fR, \fBallocb\fR(9F) can fail
 120 if another module or driver had allocated the memory before \fIfunc\fR was able
 121 to call \fBallocb\fR(9F).