QENABLE

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

NAME

qenable - schedules a STREAMS message queue service procedure

SYNOPSIS

#include <sys/stream.h>

void qenable(queue_t *q);

ARGUMENTS

q: the queue to enable.

INTERFACE

STREAMS.

DESCRIPTION

qenable() schedules the qi_srvp(9) procedure of the queue pointed to by q to be run by runqueues(9). If the queue pointed to by q has been disabled with a call to noenable(9), then qenable() will still succeed in enabling the queue.

qenable() is normally called to invoke the execution of q's qi_srvp(9) procedure.

RETURN

qenable() returns void.

ERRORS

When qenable() fails, it fails silently. qenable() fails to enable the queue when the queue does not have a qi_srvp(9) procedure. Otherwise, qenable() is always successful.

CONTEXT

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

MP-STREAMS

qenable() is MP-safe.

If the queue was not already enabled (qi_srvp(9) procedure already scheduled to run) on a different CPU, qenable() schedules the qi_srvp(9) procedure of the queue, q, using scheduleq(9) on the current CPU. In this case, the queue qi_srvp(9) procedure for the queue, q, will not execute until after qenable() returns and the function that called qenable() returns or encounters a preemption point. However, if the queue is already scheduled by another processor and qenable() was not called from a context synchronous with the qi_srvp(9) procedure, another processor may run the qi_srvp(9) procedure before qenable() returns.

Therefore, qenable() should be called with STREAMS synchronization in effect, or hold the necessary private locks across the call to qenable(), if it is ncessary to synchronize the call to qenable() with execution of the qi_srvp(9) procedure.

NOTICES

qenable() has no effect if the queue has already been enabled due to internal STREAMS scheduler actions, or a previous call to qenable() that has not yet completed service.

Enabling a queue from within its own qi_srvp(9) procedure will not reschedule the qi_srvp(9) procedure.

BUGS

qenable() has no known bugs.

COMPATIBILITY

qenable() is compatible with SVR 4.2 MP DDI/DKI[1], and implementations based on SVR 4, with the following portability considerations:

---: qenable() only schedules the queue for later service. qenable() schedules a queue regardless of whether the QNOENB flag is set, or whether noenable(9) has been called for the queue, For a version of this function that considers the QNOENB flag, see enableq(9). Even as far back as SVR 3.1[2], the noenable(9), enableok(9) and canenable(9) functions affecting the QNOENB flag have only affected putq(9) scheduling the queue, q.
: Portable STREAMS drivers and modules will expect that qenable() will enable a queue regardless of the state of the QNOENB flag and the calling of noenable(9).
---: qenable() is not bug for bug compatible with LiS.
: Under older versions of LiS, qenable() will not enable a queue previously disabled with enableok() or qprocsoff(). This is an LiS bug. Under current versions of LiS, this is not the case, but current versions of LiS have their own bugs: for example, qenable() will not enable a queue that is closing (i.e. had the QCLOSING flag set), which is before driver and module qi_qclose(9) procedures get called[3].
: Portable STREAMS drivers and modules will not use LiS, but will use Linux Fast-STREAMS[4] in its place.
---: qenable() may be called on a stream frozen with freezestr(9). SVR 4.2 MP DDI/DKI[1], Solaris®[5], SUPER-UX®[6] and UnixWare®[7] do not permit qenable() to be called on a stream frozen with freezestr(9).
: Portable STREAMS drivers and modules should not call qenable() on a stream frozen with freezestr(9).
---: qenable() enables the queue regardless of the settings of other flags. IRIX®, Solaris®, SUPER-UX® and UnixWare® documentation explicitly state that qenable() schedules the queue regardless of whether noenable(9) was invoked on the queue previously[8..11]. AIX®, HP-UX®, OSF/1® and UXP/V® documentation does not say that noenable(9) defeats qenable() either[12..15]. Older versions of LiS source code, on the other hand, shows that no queue will be enabled while the QNOENB, QPROCSOFF or QCLOSING flags are set. This is an LiS bug.
: Portable STREAMS drivers and modules will not rely on qenable() to enable a stream that is disabled previously with noenable(9); instead, it will reenable the stream with enableok(9) before calling qenable(). See ``EXAMPLES'' under enableok(9) for an example.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility considerations.

CONFORMANCES

SVR 4.2 MP DDI/DKI[1]

HISTORY

qenable() appears as part of SVR 4.0 STREAMS[16].

qenable() first appeared in SVR 3[2]. The original versions of qenable() returned int instead of void.

REFERENCES

[1]: 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.
[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]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[4]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[5]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[6]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[7]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[8]: IRIX® 6.5.17, IRIX 6.5 Manual Pages, 2003, (Mountainview, California), Silicon Graphics, Inc., SGI Technical Publications. <http://techpubs.sgi.com/>
[9]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[10]: SUPER-UX® Release 9.2, SUPER-UX Release 9.2 Documentation, 1999, NEC Corporation, NEC.
[11]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[12]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[13]: HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>
[14]: Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[15]: UXP/V® V10L10, UXP/V V10L10 Documentation, 1997, Fujitsu Limited, Fujitsu.
[16]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

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
RETURN
ERRORS
CONTEXT
MP-STREAMS
NOTICES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCES
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 16:49:16 GMT, May 23, 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