Manpage of PUTNEXTCTL

PUTNEXTCTL

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

NAME

putnextctl - put a control message on the downstream STREAMS message queue

SYNOPSIS

#include <sys/stream.h>

int putnextctl(queue_t *q, int type);

ARGUMENTS

q: the queue from which to put the control message.
type: the type of the control message.

INTERFACE

STREAMS.

DESCRIPTION

putnextctl() creates a zero-length control message of type type and calls putnext(9) for the queue pointed to by q to place the message on the subsequent queue. If type is a data message type (M_DATA(9), M_PROTO(9) or M_PCPROTO(9)) and not a control message type, putnextctl() will fail. Note that putnextctl() can succeed for message type M_DELAY(9), which is normally a data message type according to datamsg(9).

putnextctl() allocates the message block for the message with priority BPRI_HI, [see allocb(9)]. putnextctl() fails if message block allocation fails.

USAGE

putnextctl() is used by STREAMS drivers and modules to pass simple messages that contain a zero-length data buffer [e.g., M_HANGUP(9)] along a Stream. However, putnextctl() is not normally used by the Stream head because it will not block awaiting the availability of a message block. For passing messages to a Stream end, putctl(9) should be used instead.

RETURN

Upon success, putnextctl() returns true (1). Upon failure, putnextctl() returns false (0).

ERRORS

putnextctl() fails and returns false (0) if the specified type is not a control message type, or if the allocation of the necessary message blocks fails.

CONTEXT

putnextctl() can be called from any context, including user context, module procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines; however, see the considerations listed under putnext(9).

putnextctl() must be called from a STREAMS synchronous context for the Stream containing q.

MP-STREAMS

putnextctl() is MP-safe when called from the proper context. However, the caller is responsible for ensuring the validity of the passed in queue pointer, q. See also the considerations listed under putnext(9), and mp-streams(9).

NOTICES

putnextctl() can succeed with a type argument of M_DELAY(9).

IMPLEMENTATION

Message blocks allocated by putnextctl() are allocated with priority BPRI_HI, and passed along the Stream with putnext(9).

BUGS

putnextctl() has no known bugs.

COMPATIBILITY

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

---: AIX®, UXP/V® and LiS state that putnextctl() will fail if the type argument is M_DATA(9), M_PROTO(9), M_PCPROTO(9) or M_DELAY(9)[3..5]. IRIX®, Solaris®, SUPER-UX® and UnixWare® state that putnextctl() will fail if the type argument is M_DATA(9), M_PROTO(9) or M_PCPROTO(9), but not M_DELAY(9)[6..9]. IRIX®, Solaris® and UnixWare® even show an example using M_DELAY(9)[6,7,9]. OSF/1® states that putnextctl() will fail if the type argument is M_DELAY(9), M_PROTO(9) or M_PCPROTO(9), but not M_DATA(9), which is quite peculiar, and then goes on to give an example for M_DELAY(9)[10]. M_DELAY(9) should probably be M_DATA(9) in the failure list. This means that AIX®, UXP/V® and LiS are the oddballs in the documented behaviour. Otherwise, putnextctl() is fairly consistent on permitting M_DELAY(9) messages. Linux Fast-STREAMS putnextctl() allows a type of M_DELAY(9) to be specified.
: Portable STREAMS drivers and modules will not pass a type of M_DELAY(9) to putnextctl().
---: HP-UX®[11] lists putnextctl() as a function that can only be passed a queue in the queue pair currently being synchronized within a module procedure. HP-UX®[11] also lists putnextctl() 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 putnextctl() from outside of a qinit(9) routine for the queue pair of q.
---: putnextctl() is not bug for bug compatible with LiS.
: putnextctl() returns failure when the operation fails. Under LiS, putnextctl() will return success even if the operation fails because of the following conditions: q and q->q_next are not NULL, but q->q_next points to something other than a queue structure; the queue pointed to by q->q_next has a q_info pointer of NULL; the queue pointed to by q->q_next has no qi_putp(9) procedure; or the queue pointed to by q->q_next is closing, or the queue has had qi_putp(9) and qi_srvp(9) procedure processing turned off (e.g. with qprocsoff(9)). LiS should return failure when the operation fails.
---: putnextctl() allocates a message block and calls putnext(9). For differences from LiS, see putnext(9).
---: putnextctl() protects dereferencing of the q->q_next pointer with the stream head read lock. LiS implements putnextctl() with a call to putctl(9) using the q->q_next pointer for the queue.
---: putnextctl() may be called on a stream frozen with freezestr(9). SVR 4.2 MP DDI/DKI[1], Solaris®[12], SUPER-UX®[13] and UnixWare®[14] do not permit putnextctl() to be called on a stream frozen with freezestr(9).
: Portable STREAMS drivers and modules will not call putnextctl() on a stream frozen by the caller with freezestr(9).
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[1,15].

HISTORY

putnextctl() first appeared in SVR 4.0 MP and SVR 4.2 MP[1,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 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]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[4]: UXP/V® V10L10, UXP/V V10L10 Documentation, 1997, Fujitsu Limited, Fujitsu.
[5]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[6]: IRIX® 6.5.17, IRIX 6.5 Manual Pages, 2003, (Mountainview, California), Silicon Graphics, Inc., SGI Technical Publications. <http://techpubs.sgi.com/>
[7]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[8]: SUPER-UX® Release 9.2, SUPER-UX Release 9.2 Documentation, 1999, NEC Corporation, NEC.
[9]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[10]: 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/>
[11]: 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/>
[12]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[13]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[14]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[15]: SVR 4.2, STREAMS Programmer's Guide, 1992, (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
IMPLEMENTATION
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 14:52:24 GMT, May 20, 2013