Manpage of STRQGET

STRQGET

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

NAME

strqget - gets information about a STREAMS message queue

SYNOPSIS

#include <sys/stream.h>

int strqget(queue_t *q, qfields_t what, unsigned char band, long *val);

ARGUMENTS

q: the queue for which to retrieve parameters.
what: which parameter to retrieve.
band: the queue band for which to retrieve parameters.
val: the pointer to where the retrieved value is to be placed.

INTERFACE

STREAMS.

DESCRIPTION

strqget() returns the value or pointer requested by what for the queue pointed to by q and band specified by band into the memory area pointed to by val. The attribute retrieved can be either a scalar or a pointer.

When band is zero, strqget() will retrieve the attribute specified by what for the queue. When band is non-zero (between 1 and 255), strqget() will retrieve the attribute specified by what for the queue band specified by band.

The argument what specifies which queue (or queue band if band is non-zero) attribute is to be retrieved. what can be one of the following values:

QHIWAT: Gets the high water mark associated with the q or queue band.
QLOWAT: Gets the low water mark associated with the q or queue band.
QCOUNT: Gets the count of bytes associated with the q or queue band.
QFIRST: Gets the first message pointer associated with the q or queue band.
QLAST: Gets the last message pointer associated with the q or queue band.
QFLAG: Gets the flags associated with the q or queue band.
: QMAXPSZ Gets the maximum packet size associated with the q. For this operation band must be zero (0).
QMINPSZ: Gets the minimum packet size associated with the q. For this operation band must be zero (0).

strqget() provides a mechanism whereby a STREAMS(4) driver or module can access information about a queue or queue band without directly accessing the queue or qband structures. Values retrieved by strqget() are equivalent to directly accessing the queue or qband structure members described below.

The queue structure contains at least the following members:

ulong q_hiwat - the high water mark for the queue.
ulong q_lowat - the low water mark for the queue.
ulong q_count - the count of the number of bytes in the queue.
struct msgb *q_first - the first message in the queue.
struct msgb *q_last - the last message in the queue.
ulong q_flag - the flags associated with the queue, see ``Queue Flags'',
above.
long q_maxpsz - the maximum message size accepted by the queue.
long q_minpsz - the minimum message size accepted by the queue.

The qband structure contains at least the following members:

ulong qb_hiwat - the high water mark for the band.
ulong qb_lowat - the low water mark for the band.
ulong qb_count; - the count of the number of bytes in the band.
struct msgb *qb_first - the first message in the band.
struct msgb *qb_last - the last message in the band.
ulong qb_flag - the flags associated with the band, see ``Queue Band Flags'',
above.

Queue Flags

When strqget() is called with what set to QFLAG and band is set to zero (0), strqget() returns the queue flags in the area pointed to by val. The queue flags in the area pointed to by val can contain the following flags:

QENAB: set when the queue is enabled.
QWANTR: set when the previous queue wants to read.
QWANTW: set when the previous queue wants to write.
QFULL: set when the queue is full. The queue is full when the count of bytes in the queue was greater than the high water mark for the queue, yet has not subsided to less than or equal to the low water marke for the queue.
QREADR: set when the queue is the reader.
QUSE: set when the queue is not free.
QNOENB: set when the queue is not to be enabled.
QUP: set when the queue uses uni-processor emulation.
QBACK: set when the queue is a back-enabled queue.
QOLD: set when the queue supports the old SVR 3[1] style open/close.
QHLIST: set when the stream head has scan listed the queue.
QTOENAB: set when the stream is to be enabled.
QSYNCH: set when the queue is synchornized.
QSAFE: set when the queue requires safe callbacks (STREAMS driver interrupts disabled).
QWELDED: wet when the queue is welded.
QSVCBUSY: set when the queue qi_srvp(9) procedure is running.
QWCLOSE: set when the queue is in close wait.
QPROCS: set when qprocsoff(9) has been called, or qprocson(9) has yet to be called for the queue.

Queue Band Flags

When strqget() is called with what set to QFLAG and band is set between 1 and 255, strqget() returns the queue band flags associated with band in the area pointed to by val. The queue band flags in the area pointed to by val can contain the following flags:

QB_FULL: set when the queue band is full. The queue band is full when the count of the bytes in the queue band was greater than the high water mark for the queue band, and has not yet dropped to zero or below the low water mark for the queue.
QB_WANTW: set when the previous queue wants to write to this queue band.
QB_BACK: set when the queue band is back-enabled.

USAGE

strqget() is the proper transparent and implementation independent method for accessing members of the queue(9) and qband(9) structures.

strqget() will attempt to allocate a qband(9) structure for bands that are accessed for which a qband(9) structure does not yet exist. This means that strqget() can be used to allocate queue bands so that subsequent calls to appq(9), insq(9), putq(9) and putbq(9) will not fail for the allocated band.

strqget() can be called in a driver or module initialization routine to ensure that appq(9), insq(9), putq(9) and putbq(9) will never fail for the allocated queue band. This is useful if appq(9), insq(9), putq(9) or putbq(9) are called from interrupt service routine context.

RETURN

Upon success, strqget() returns zero (0) and places the appropriate value in the memory area pointed to by val.

Upon failure, strqget() returns a non-zero error number. The memory area pointed to by val remains unchanged.

ERRORS

When strqget() fails, it returns one of the following errors:

[EINVAL]: The value pointer val is NULL; the queue pointer q is NULL; q does not point to a valid queue structure; QMAXPSZ or QMINPSZ was specified for what and band was non-zero; what is not a valid queue or queue band attribute.
[ENOMEM]: the queue band specified in band does not exist and a qband(9) structure could not be immediately allocated.

CONTEXT

strqget() 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

strqget() is MP-safe.

Calling strqget() on a queue and stream previously frozen with freezestr(9) could result in single-party deadlock.

IMPLEMENTATION

strqget() uses recursive read-write locks on the stream head, so calls to strqget() on a stream frozen with freezestr(9) will not result in single-party deadlock. Also, failure to call freezestr(9) on the stream will not cause strqget() to panic because the head lock is still taken.

BUGS

strqget() has no known bugs.

COMPATIBILITY

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

---: strqget() returns some specialized flags, such as the queue flags QUP, QBACK, QOLD, QHLIST, QTOENAB, QSYNCH, QSAFE, QWELDED, QSVCBUSY and QWCLOSE, and the queue band flag QB_BACK. LiS defines a number of queue flags that are not elsewhere defined, yet returns those flags from a call to strqget()[4]. LiS should mask off its private flags when returning flags from a call to strqget().
: Portable STREAMS drivers and modules will mask the queue flags returned by strqget() with ( QENAB | QWANTR | QWANTW | QFULL | QREADR | QUSE | QNOENB ), and queue band flags with ( QB_FULL | QB_WANTW ).
---: SVR 4.2 MP, SUPER-UX® and UnixWare® require that a stream be frozen with freezestr(9) for the duration of the call to strqget()[5..7].
: Portable STREAMS drivers and modules will freeze the stream with freezestr(9) before calling strqget().
---: HP-UX®[8] lists strqget() as a function that can only be passed a queue in the queue pair currently being synchronized within a module procedure. HP-UX®[8] also lists strqget() 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 strqget() from outside of a qinit(9) routine for the queue pair of q.
---: AIX® documents arguments q and band as register arguments[9].
---: strqget() will allocate a queue band structure for the band argument, band, if one does not already exist. HP-UX®, SUPER-UX®, UXP/V® and LiS indicate that strqget() and strqset(9) will cause qband(9) allocation to occur if executed for a queue band, band, that does not currently exist[4, 6, 8, 10].
: Portable STREAMS drivers and modules can assume that a call to strqget() with a band, band, for a queue band structure qband(9), that has not yet been allocated, will cause the allocation of the queue band structure. That is, drivers can assume that a successful call to strqget() for a given queue band, band, will ensure that appq(9), insq(9), putq(9) and putbq(9) will always succeed for the queue band, band.
---: strqget() is not bug for bug compatible with LiS.
: LiS will return [EINVAL] when it cannot allocate a qband(9) structure instead of [ENOMEM].
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility considerations.

CONFORMANCE

SVR 4.2 MP DDI/DKI[2].

HISTORY

strqget() first appeared in SVR 4.0 STREAMS[11].

REFERENCES

[1]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[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]: 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.
[4]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[5]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[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]: 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/>
[9]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[10]: UXP/V® V10L10, UXP/V Programmer's Guide: STREAMS V10, 1997, Fujitsu Limited, Fujitsu.
[11]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.