Manpage of PUTCTL1

PUTCTL1

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

NAME

putctl1 - put a 1 byte control message on a STREAMS message queue

SYNOPSIS

#include <sys/stream.h>

int putctl1(queue_t *q, int type, int param);

ARGUMENTS

q: the queue to which to put the control message.
type: the type of the control message.
param: a one-byte parameter to place in the message.

INTERFACE

STREAMS.

DESCRIPTION

putctl1() creates a one-byte control message of type type with the one-byte data containing the data param and calls put(9) for the queue pointed to by q to place the message on the queue. If type is a data message type (M_DATA(9), M_PROTO(9) or M_PCPROTO(9)) and not a control message type, putctl1() will fail. Note that putctl1() can succeed for message type M_DELAY(9), which is normally a data message type according to datamsg(9).

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

USAGE

putctl1() is used by STREAMS drivers and modules, or associated interrupt service routines, to pass simple messages that contain a one-byte data buffer [e.g., M_ERROR(9)] to a Stream end. However, putctl1() is not normally used by the Stream head because it will not block awaiting the availability of a message block. For passing messages between queues along a Stream, putnextctl1(9) should be used instead.

RETURN

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

ERRORS

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

CONTEXT

putctl1() 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 put(9).

Because putctl1() uses put(9), it may be called from contexts asynchronous to STREAMS, such as interrupt service routines.

MP-STREAMS

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

NOTICES

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

IMPLEMENTATION

Message blocks allocated by putctl1() are allocated with priority BPRI_HI, and placed on the Stream with put(9).

BUGS

putctl1() has no known bugs.

COMPATIBILITY

putctl1() 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 putctl1() 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 putctl1() 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 putctl1() 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, putctl1() is fairly consistent on permitting M_DELAY(9) messages. Linux Fast-STREAMS putctl1() 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 putctl1().
---: putctl1() is not bug for bug compatible with LiS.
: putctl1() returns failure when the operations fails. Under LiS, putctl1() will return success even if the operation fails because of the following conditions: q is not NULL, but q points to something other than a queue structure; the queue pointed to by q has a q_info pointer of NULL; the queue pointed to by q has no qi_putp(9) procedure; or the queue pointed to by q 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.
---: putctl1() allocates a message block and calls put(9). For differences from LiS, see put(9).
---: putctl1() may be called on a stream frozen with freezestr(9). SVR 4.2 MP DDI/DKI[1], Solaris®[11], SUPER-UX®[12] and UnixWare®[13] do not permit putctl1() to be called on a stream frozen with freezestr(9).
: Portable STREAMS drivers and modules will not call putctl1() 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].

HISTORY

putctl1() appears as part of SVR 4.0 STREAMS[14].

putctl1() first appeared in SVR 3[15].

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]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[12]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[13]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[14]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[15]: 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
IMPLEMENTATION
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 09:27:11 GMT, May 18, 2013