QBUFCALL(9F) Kernel Functions for Drivers QBUFCALL(9F)

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

illumos DDI specific (illumos 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).

January 16, 2006 QBUFCALL(9F)