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

     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

     qbufcall() 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, qbufcall() 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

     qbufcall() can be called from user or interrupt 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).