CANENABLE

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

NAME

canenable - test whether a STREAMS message queue can be scheduled.

SYNOPSIS

#include <sys/stream.h>

int canenable(queue_t *q);

ARGUMENTS

q: the queue to test whether placing a (normal) message on the queue can result in scheduling of the queue.

INTERFACE

STREAMS.

DESCRIPTION

canenable() tests whether the queue pointed to by q can be enabled (qi_srvp(9) procedure scheduled for execution by runqueues(9)) by placing a (normal) message on the queue.

If the queue, q, has been disabled with noenable(9), setting the the QNOENB flag in the q_flag member of the queue(9) strucuture, then this utility will return false (0). If the queue, q, has been enabled with enableok(9), clearing the QNOENB flag in the q_flag member of the queue(9) structure, then this utility will return true (1).

USAGE

This function is typically called before a call to appq(9), putq(9), or insq(9) when the caller wishes to determine whether appq(9), putq(9), or insq(9) can result in the scheduling of the queue's qi_srvp(9) procedure.

RETURN

canenable() returns true (1) if the queue pointed to by q can be enabled with appq(9), putq(9), or insq(9), or back-enabled by the previous queue. canenable() returns false (0) if the queue pointed to by q cannot be enabled with appq(9), putq(9), or insq(9), or back-enabled by the previous queue.

ERRORS

canenable() is always successful.

CONTEXT

canenable() can be called from any context, including user context, module procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines. It is normally called from a STREAMS synchronous context [see mp-streams(9)], that is, within q's qi_putp(9) put procedure.

MP-STREAMS

canenable() is not MP-safe. Consideration should be given that the condition tested may change before the return value is used if noenable(9), enableok(9), qprocson(9) or qprocsoff(9) are allowed to execute concurrent with canenable().

NOTICES

It is questionable whether canenable() is usable in a Symmetric Multi-Processor (SMP) environment. canenable() tests atomic flags in the queue(9) structure flags word that can be altered by other processors immediately prior to, or subsequent to, the call to canenable(). Therefore, there is always a race condition possible between canenable() and noenable(9), enableok(9), qprocson(9), qprocsoff(9), (or other utilities affecting the QNOENB flag in the queue(9) flags word) on SMP systems.

canenable() might have some limited use on UP systems where interrupts can be locked out across the call, or on SMP systems where the Stream is frozen by freezestr(9).

Portable STREAMS drivers and modules will not call canenable().

IMPLEMENTATION

canenable() simply returns the result of testing the QNOENB bit.

EXAMPLES

None.

BUGS

canenable() has no known bugs, but see the limitations under MP-STREAMS , above.

COMPATIBILITY

canenable() is compatible with SVR 4.0[1] and implementations compatible with SVR 3.2[2] with the following portability considerations:

---: canenable() is an SVR 3 STREAMS[2] macro that never made it to the DDI/DKI[3] and has little use on an Symmetric Multi-Processor (SMP) system. This function is deprecated and is only maintained for backwards compatibility to SVR 3 for single threaded drivers (e.g. ones with synchronization level SQLVL_ELSEWHERE or SQLVL_GLOBAL).
: Portable STREAMS drivers and modules will not call canenable().
---: None of AIX®, HP-UX®, IRIX®, OSF/1®, MacOT®, Solaris®, SUPER-UX® UnixWare® or UXP/V® document canenable().
: Portable STREAMS drivers and modules will not call canenable().
---: canenable() is an extern inline function call. SVR 3.2 implements canenable() as a macro.
: Portable STREAMS drivers and modules will not try to take a function pointer to canenable().
---: A call to canenable() with a NULL q or with a non-NULL q that points to other than a valid queue_t structure is invalid and the result is undefined. When LiS canenable() encounters such an error, it will return false (0).
: Portable STREAMS drivers and modules will not call canenable() with invalid queue pointers.
---: canenable() is provided for source level compatibility with SVR 3 for the purpose of porting SVR 3 drivers to Linux . Because internal structures and definitions for Linux Fast-STREAMS[4] differ from that of SVR 3, binaries are incompatible.
---: canenable() only provides functionality comparable to SVR 3 for use by STREAMS drivers and modules. Any and all functionality provided by canenable() in support of non-STREAMS devices are not supported.
---: Binary compatibility is not guaranteed.

Additional compatibility is available using the STREAMS Compatibility Modules strcompat(5) package for LiS and Linux Fast-STREAMS. See svr3compat(9), liscompat(9), and STREAMS(9) for additional compatibility considerations.

CONFORMANCE

SVR 4.2 MP DDI/DKI [3].

HISTORY

canenable() first appeared in SVR 3[2].

REFERENCES

[1]: SVR 4 DDI/DKI, UNIX® System V Release 4 Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: 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.
[4]: streams-0.9.2, Linux Fast-STREAMS (LfS) 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

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

Index

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

This document was created by man2html, using the manual pages.
Time: 13:50:05 GMT, June 18, 2013

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci