man/man9f/qbufcall.9f

         te
 Copyright (c) 2006, Sun Microsystems, Inc.
 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]
 QBUFCALL 9F "Jan 16, 2006"
 NAME
qbufcall - call a function when a buffer becomes available
 SYNOPSIS

#include <sys/stream.h>
#include <sys/ddi.h>


bufcall_id_t qbufcall(queue_t *q, size_t size, uint_t pri,
 void(*func)(void *arg), void *arg);


 INTERFACE LEVEL

Solaris DDI specific (Solaris DDI).
 PARAMETERS
q

Pointer to STREAMS queue structure.


size

Number of bytes required for the buffer.


pri

Priority of the allocb(9F) allocation request (not used).


func

Function or driver routine to be called when a buffer becomes available.


arg

Argument to the function to be called when a buffer becomes available.


 DESCRIPTION

The qbufcall() function serves as a qtimeout(9F) call of
indeterminate length. When a buffer allocation request fails, qbufcall()
can be used to schedule the routine func to be called with the argument
arg when a buffer becomes available. func may call allocb()
or it may do something else.

The qbufcall() function is tailored to be used with the enhanced
STREAMS framework interface, which is based on the concept of perimeters.
(See mt-streams(9F).) qbufcall() schedules the specified function
to execute after entering the perimeters associated with the queue passed in as
the first parameter to qbufcall(). 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).

qprocson(9F) must be called before calling either qbufcall() or
qtimeout(9F).
 RETURN VALUES

If successful, the qbufcall() function returns a qbufcall ID
that can be used in a call to qunbufcall(9F) to cancel the request. If
the qbufcall() scheduling fails, func is never called and 0
is returned.
 CONTEXT

The qbufcall() function can be called from user, interrupt, or kernel
context.
 SEE ALSO

allocb(9F), mt-streams(9F), qprocson(9F), qtimeout(9F),
qunbufcall(9F), quntimeout(9F)

Writing Device Drivers

STREAMS Programming Guide
 WARNINGS

Even when func is called by qbufcall(), allocb(9F) can fail
if another module or driver had allocated the memory before func was able
to call allocb(9F).