Manpage of QBUFCALL

QBUFCALL

Section: OpenSS7 STREAMS Compatibility DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

qbufcall - install a buffer callback

SYNOPSIS

#define _SUN_SOURCE
#include <sys/stream.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>

bufcall_id_t qbufcall(queue_t *q, unsigned size_t size, int priority, void (*function)(void *), void *arg);

ARGUMENTS

q

the queue with which to associate the timeout callback

size

the size of the requested data buffer.

priority

the priority of the requested message. The priority can be one of the following values:

BPRI_LO	the buffer requested is a low priority buffer.
BPRI_MED	the buffer requested is a medium priority buffer.
BPRI_HI	the buffer requested is a high priority buffer.
BPRI_HI	the buffer requested is a low priority buffer and can block.

function

the callback function to call when a buffer of the requested size and message of the requested priority becomes available. This is normally the qi_srvp(9) procedure which failed a call to allocb(9) or it is a function pointer to qenable(9).

arg

the argument to pass the callback function. This is normally a pointer to the queue whose qi_srvp(9) procedure failed an allocb(9).

DESCRIPTION

When allocation of a buffer fails as a result of a failed call to allocb(9) or esballoc(9) the qi_srvp(9) routine should place the message that invoked the allocb(9) or esballoc(9) call back on the queue with putbq(9) and call the qbufcall() function with qenable(9) as the function argument and a pointer to the queue as the arg argument to the call. The size and priority arguments should be the same as the size and priority arguments that were issued to allocb(9). If esballoc(9) failed, the size argument to qbufcall() should be zero (0).

In this way, the queue qi_srvp(9) routine will be recalled once there is sufficient memory to allocate the necessary buffer and message block.

Buffer calls initiated with qbufcall() can be cancelled by calling qunbufcall(9) with the returned bufcall id.

RETURN

qbufcall() returns a bufcall_id_t as follows:


typedef int bcid_t;
typedef int bufcall_id_t;

Upon success, qbufcall() returns a non-zero bufcall id and the specified function will be called with the specified arg at a later time when buffers of the necessary size become available.

Upon failure, qbufcall() returns zero (0) and no call will be generated to the specified function.

ERRORS

When qbufcall() encounters and error, it returns zero (0).

qbufcall() fails and returns zero (0) when the function pointer to the callback function, function, is NULL, or qbufcall() cannot allocate the necessary internal structures for the callback.

CONTEXT

qbufcall() can be called from any context including user context, queue procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines.

MP-STREAMS

qbufcall() is MP-safe.

Considerations should be given when writing the callback function that a qbufcall() callback function can execute at the same time as any non-exclusive qi_qopen(9), qi_qclose(9), qi_putp(9) or qi_srvp(9) procedure, non-exclusive qbufcall(), or qtimeout(9) callback or interrupt service routine.

However, the qbufcall() callback function will be serviced by the same CPU as the CPU from which the qbufcall() was issued. Therfore, the callback function will not execute until after qbufcall() returns. Because the servicing thread and the current thread are the same, the qbufcall() callback will not be invoked until after the function that called qbufcall() returns. This means that it is safe to store the returned bufcall id in global variables accessed by the callback function. It is also safe to hold private locks taken by the callback function across a call to qbufcall(9). This is the same situation as that of the qtimeout(9), bufcall(9) and timeout(9) functions.

NOTICES

qbufcall() is a Solaris®-specific function: _SUN_SOURCE must be defined before including DDI/DKI include files to expose this symbol. OpenSS7 STREAMS Compatibility must also have been compiled with CONFIG_STREAMS_COMPAT_SUN or CONFIG_STREAMS_COMPAT_SUN_MODULE set.

The primary difference between qbufcall() and bufcall(9) is that the STREAMS scheduler will take the same locks as a queue procedure on the associated queue, q, before invoking the qbufcall() callback function. No locks are taken whatsoever when scheduling a bufcall(9) callback.

For a driver or module that has no synchronization (no perimeters or SQLVL_NONE), calling qbufcall() has the same effect as calling bufcall(9).

bufcall_id_t should be treated as an opaque type that can be tested for equality to zero. The value should not otherwise be manipulated. Although bufcall_id_t has traditionally been implemented as an integer index, qbufcall() implements bufcall id values internally as out-dating pointer into a strevent structure.

EXAMPLES

See bufcall(9).

BUGS

qbufcall() has no known bugs.

COMPATIBILITY

qbufcall() is compatible with Solaris®[1] with the following portability considerations:

---: SVR 4.2 MP DDI/DKI[2], AIX®, UnixWare®, OSF/1®, HP-UX®, SUPER-UX®, UXP/V®, and LiS, do not provide this function.
---: qbufcall() passed a NULL q pointer has the same effect as bufcall(9).
---: qbufcall() is a Solaris®-specific function that should not be used by portable STREAMS drivers and modules. The more common bufcall(9) function should be used in its stead.
---: qbufcall() is provided for source level compatibility with Solaris® for the purpose of porting Solaris® drivers to Linux. Because internal structures and definitions for OpenSS7 STREAMS Compatibility[3] differ from that of Solaris®, binaries are incompatible.
---: qbufcall() only provides functionality comparable to Solaris® for use by STREAMS drivers and modules. Any and all functionality provided by qbufcall() in support of non-STREAMS devices are not supported.

See suncompat(9) and STREAMS(9) for additional compatibility considerations.

CONFORMANCE

Solaris®[1] documentation.

HISTORY

qbufcall() is a Solaris® specific function that first appeared in Solaris® 2.

REFERENCES

[1]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[2]: USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: strcompat-0.9.2, STREAMS Compatibility Modules (strcompat) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

OpenSS7 STREAMS Compatibility: Package strcompat version 0.9.2.7 released 2008-10-31.

Index

NAME
SYNOPSIS
ARGUMENTS
DESCRIPTION
RETURN
ERRORS
CONTEXT
MP-STREAMS
NOTICES
EXAMPLES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 04:19:32 GMT, May 23, 2013