Manpage of STRQSET

STRQSET

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

NAME

strqset - sets attributes of a STREAMS message queue

SYNOPSIS

#include <sys/stream.h>

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

ARGUMENTS

q: the queue for which to set values.
what: what values of the associated queue to set.
band: the band for the specified settings.
val: the value to set.

INTERFACE

STREAMS.

DESCRIPTION

strqset() sets the attribute requested by what for the queue pointed to by q and band specified by band to the value specified by val. The value set can be either a scalar or a pointer.

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

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

QHIWAT: Sets the high water mark associated with the q or queue band.
QLOWAT: Sets the low water mark associated with the q or queue band.
QMAXPSZ: Sets the maximum packet size associated with the q. For this operation band must be zero (0).
QMINPSZ: Sets the minimum packet size associated with the q. For this operation band must be zero (0).

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

The queue structure contains at least the following members:

size_t q_hiwat - the high water mark for the queue.
size_t q_lowat - the low water mark for the queue.
ssize_t q_maxpsz - the maximum message size accepted by the queue.
ssize_t q_minpsz - the minimum message size accepted by the queue.

The qband structure contains at least the following members:

size_t qb_hiwat - the high water mark for the band.
size_t qb_lowat - the low water mark for the band.

RETURN

Upon success, strqset() returns zero (0) and sets the appropriate attribute to the appropriate value; upon failure, a non-zero error number.

ERRORS

When strqset() fails, the requested attribute remains unchanged, and it returns one of the following errors:

[EINVAL]: 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.
[EPERM]: what specified an attribute that is appropriate for strqget(9), but which is invalid for strqset(): QCOUNT, QFIRST, QLAST or QFLAG.

CONTEXT

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

strqset() is MP-safe.

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

BUGS

strqset(9) has no known bugs.

COMPATIBILITY

strqset(9) is source-level compatible with SVR 4.2 MP DDI/DKI[1], and systems based on SVR 4[2], with the following portability considerations:

---: UnixWare®[3] and SUPER-UX®[4] require that a stream be frozen with freezestr(9) for the duration of the call to strqset().
---: HP-UX®[5] lists strqset() as a function that can only be passed a queue in the queue pair currently being synchronized within a module procedure. HP-UX®[5] also lists strqset() 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 strqset() from outside of a qinit(9) routine for the queue pair of q.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[1].

HISTORY

strqset() first appeared in SVR 4.0 STREAMS[2].

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, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[4]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[5]: 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/>

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
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 22:38:30 GMT, May 20, 2013