RMVQ

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

NAME

rmvq - remove a message from a STREAMS message queue

SYNOPSIS

#include <sys/stream.h>

void rmvq(queue_t *q, mblk_t *mp);

ARGUMENTS

q: the queue from which to remove the message.
mp: the message to remove from the queue.

INTERFACE

STREAMS.

DESCRIPTION

rmvq() removes the message pointed to by mp from the queue pointed to by q. The message can be removed from the middle of the queue and does not need to be at the head or tail of the queue.

USAGE

The following rules govern the usage of the rmvq(9) utility:

*: rmvq(9), must not be passed a queue pointer that was not frozen by the caller with a previous call to freezstr(9).
*: rmvq(9), can be passed any queue pointer previously frozen by the caller with a call to freezestr(9), regardless of the context of the call.

The above rules allow rmvq(9) to be called on any queue properly frozen by the caller with freezestr(9).

RETURN

rmvq() returns void.

ERRORS

rmvq() is always successful.

CONTEXT

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

The Stream containing q should be frozen by the caller with freezestr(9). If the Strem is not frozen, rmgq() must be called from a STREAMS synchronous context (i.e., qi_putp(9), qi_srvp(9), qi_qopen(9), qi_qclose(9)), for an intermediate module, however, it may be called from an asynchronous context for a Stream end (i.e., no q->q_next pointer). See qbackenable(9).

MP-STREAMS

rmvq() is MP-safe; however, the caller is responsible for ensuring exclusive access to the passed in message pointer, mp.

One way to ensure exclusive access to the message pointer prior to the call is to freeze the state of the queue before the reference to mp is acquired. This can be accomplished by using freezestr(9) for the queue, priori to acquiring mp.

Another way to ensure exclusive access to the message pointer prior to the call is to create a situation whereby the queue's qi_srvp(9) procedure cannot run. This is the state of affairs when the calling process has frozen the entire stream with a function such as qwriter(9), or simply the queue with a function such as MPSTR_QLOCK(9).

NOTICES

rmvq() uses a queue(9) structure pointer in the msgb(9) structure to determine to which queue (if any) mp belongs. This increases the performance of the rmvq() function dramatically.

BUGS

rmvq() has no known bugs.

COMPATIBILITY

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

---: rmvq() is always successful.
: Under LiS, rmvq() silently fails if the message pointer mp is NULL; the queue pointer q is NULL; the queue pointer q does not point to a valid queue structure; q is closing; q has qi_putp(9) and qi_srvp(9) procedures turned off (e.g. with qprocsoff(9)); the message pointed to by mp does not exist on the queue q.
: Portable STREAMS drivers and modules will not pass NULL or invalid pointers to rmvq().
---: Linux Fast-STREAMS maintains a queue pointer within the msgb(9) structure. This permits immediate determination of whether the passed in message pointer, mp, is a member of the queue, q. It even permits ignoring the passed in q pointer.
: LiS does not maintain a pointer in the msgb(9) structure to the queue to which a given message currently belongs. This means that LiS must search the queue pointed to by q for the message pointed to by mp using a linear search. This is inefficient if rmvq() is called often by a STREAMS(4) driver or module (which it is by the Stream head).
---: rmvq() does not panic if the message pointer, mp, points to a message not on queue, q.
: IRIX® documents that if the message pointer, mp, does not point to an existing message on queue, q, that the system could panic[3].
: Portable STREAMS drivers and modules will not pass a message, mp, to rmvq() that is not on the passed in queue, q.
---: UnixWare® and SUPER-UX® require that a stream be frozen with freezestr(9) for the duration of the call to rmvq()[4,5].
: Portable STREAMS drivers and modules will freeze the stream with freezestr(9) before calling rmvq().
---: HP-UX®[6] lists rmvq() as a function that can only be passed a queue in the queue pair currently being synchronized within a module procedure. HP-UX®[6] also lists rmvq() as a utility that cannot be called from user functions or non-STREAMS code; that is, contexts asynchronous to the Stream containing q.
: HP-UX® compatible drivers and modules will not call rmvq() from outside of a qinit(9) routine for the queue pair of q.
---: rmvq() cannot be called from an interrupt service routine.
: Linux Fast-STREAMS does not permit rmvq() to be called from an interrupt service routine context to remove the need for suppressing local interrupts throughout the STREAMS executive. The only queue procedure that Linux Fast-STREAMS permits to be called from an interrupt service routine context is put(9), and that function defers until the next runqueues(9) pass.
: Portable STREAMS drivers and modules will not call rmvq() from any context outside a STREAMS queue procedure or callback function. At the Stream end (Stream head or driver), from a context other than a STREAMS coroutine, only put(9) will be used by a portable STREAMS driver or module.
---: All versions of LiS contain the bug that they keep track of message queue counts, q_count, qb_count, in terms of the sum of the absolute sizes of the data buffers referenced by message blocks, (db_lim - db_base), and not the sizes of the message blocks themselves, (b_wptr - b_rptr), which does not conform to SVR 4.2 STREAMS[7]. See msgsize(9). No other implementation has this bug.
: Portable STREAMS applications programs, drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility considerations.

CONFORMANCE

SVR 4.2 MP DDI/DKI[1].

HISTORY

rmvq() appears as part of SVR 4.0 STREAMS[8].

rmvq() first appeared in SVR 3[9].

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 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.
[3]: IRIX® 6.5.17, IRIX 6.5 Manual Pages, 2003, (Mountainview, California), Silicon Graphics, Inc., SGI Technical Publications. <http://techpubs.sgi.com/>
[4]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[5]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[6]: HP-UX STREAMS, STREAMS Programmer's Guide -- HP 9000 and Integrity Server Computer Systems, October 2005, (Palo Alto, California), Hewlett-Packard Development Company L.P., HP. <http://docs.hp.com/>
[7]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[8]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[9]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (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
USAGE
RETURN
ERRORS
CONTEXT
MP-STREAMS
NOTICES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 13:00:38 GMT, May 19, 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