Manpage of PUTMSG

PUTMSG

Section: Linux Fast-STREAMS System Calls (2)
Updated: 2008-10-31
Index Return to Main Contents

NAME

putmsg - put a message to a STREAMS character device

SYNOPSIS

#include <stropts.h>

int putmsg(int fd, const struct strbuf *ctlptr, const struct strbuf *dataptr, int flags);

ARGUMENTS

fd: the file descriptor to which to put a message.
ctlptr: a pointer to a strbuf structure holding the control part of the message.
dataptr: structure holding the data part of the message.
flags: putmsg flags.

DESCRIPTION

putmsg() generates a STREAMS message from the buffer supplied in the specified ctlptr and datapr and with options specified by flags and delivers the message to the stream head associated with the STREAMS character special file fd.

The resulting STREAMS message can contain a control part as specified by ctlptr, a data part as specified by datptr, or both. The control part, when present, will generate M_PROTO or M_PCPROTO message blocks. The data part, when present, will generate M_DATTA message blocks. When both control and data parts are present, an M_PROTO or M_PCPROTO message block followed by one or more M_DATA message blocks will be generated.

fd is an open file descriptor for the STREAMS character special file to which the STREAMS message is to be written.

ctlptr and datptr point to a strbuf structure, which contains the following members:

struct strbuf {
    int maxlen;         /* Maximum buffer length.  */
    int len;            /* Length of data.  */
    char *buf;          /* Pointer to buffer.  */
};

maxlen: Not used by putmsg().
len: The length of the information pointed to by buf.
buf: A pointer to the buffer that contains len bytes of information.

ctlptr points to a strbuf structure describing the control part to be included in the message, or NULL if there is no control part. The buf member of the strbuf structure pointed to by ctlptr indicates the start of the information to sent in the control part, and the len member indicates the length of the information for the control part.

datptr points to a strbuf structure describing the data part to be included in the message, or NULL is there is no data part. The buf member of the strbuf structure pointed to by ctlptr indicates the start of the information to sent in the data part, and the len member indicates the length of the information for the data part. len can be zero (0) to send zero-length data.

flags specifies whether to send a high priority message or a normal priority message. flags can be one of the following values:

RS_HIPRI: Specifies that a high priority message is to be sent and the request must contain a control part (ctlptr not NULL). This results in an M_PCPROTO message being placed on the stream head.
0: Specifies that a normal priority message is to be sent. This results in an M_PROTO message being placed on the stream head when there is a control part. When there is only a data part, an M_DATA message is placed on the stream head.

When the O_NONBLOCK(or O_NDELAY) file flag is clear, putmsg() blocks for normal priority messages (ones for which flags is set to zero (0)) when the stream cannot accept data (the stream write queue is full due to internal flow conditions). For normal priority messages (ones for which flags is set to zero (0)), when the O_NONBLOCK(or O_NDELAY) file flag is set, and the stream cannot accept data (the stream write queue is full due to internal flow conditions), putmsg() will fail, return minus one (-1) and set the global error number, errno(3) to [EAGAIN] (or [EWOULDBLOCK]).

When the stream head is set for old TTY semantics for O_NDELAY, and the O_NDELAY(or O_NONBLOCK) file flag is clear, putmsg() blocks for normal priority messages (ones for which flags is set to zero (0)) when the stream cannot accept data (the stream write queue is full due to internal flow conditions). For normal priority messages (ones for which flags is set to zero (0)), when the O_NDELAY(or O_NONBLOCK) file flag is set, and the stream cannot accept data (the stream write queue is full due to internal flow conditions), putmsg() will terminate and return zero (0).

For high priority messages (ones for which flags is set to RS_HIPRI), putmsg() will neither block nor fail on flow control conditions, regardless of the stream head O_NDELAY semantics, or the setting of O_NDELAY or O_NONBLOCK.

Unlike write(2s) or writev(2s), putmsg(), unless prevented by the lack of internal STREAMS resources, blocks awaiting the availability of message blocks to service the request, regardless of the stream head O_NDELAY semantics or the settings of the O_NDELAY or O_NONBLOCK file flags. This is necessary because no partial messages will be written by putmsg(). When prevented by the lack of internal STREAMS resources, putmsg() will fail, return minus one (-1) and set the global error number, errno(3), to [ENOSR].

STREAMS Semantics for O_NDELAY

When O_NDELAY (or O_NONBLOCK) is set, putmsg() will fail, return minus one (-1) and set the global error number, errno(3), to [EAGAIN] if flow control is in effect when the call is received. It will block, unless prevented by lack of internal STREAMS resources, awaiting the availability of message buffers.

When O_NDELAY (or O_NONBLOCK) is clear, putmsg() will block on flow control and, unless prevented by the lack of internal STREAMS resources, will block if buffers are not available.

Old TTY Semantics for O_NDELAY

Regardless of the setting of O_NDELAY (or O_NONBLOCK), putmsg() will block on flow control and, unless prevented by lack of internal STREAMS resources, will also block on the availability of message buffers.

STREAMS-base Pipes and FIFOs

RETURN VALUE

Upon success, putmsg() returns zero (0). Upon failure, putmsg() returns minus one (-1) and sets the global error number, errno(3) to an appropriate error number.

ERRORS

When putmsg() fails, it returns minus one (-1) and sets the global error number, errno(3), to one of the following:

[EISDIR]: fd refers to a directory.
[EBADF]: fd is not a valid open file descriptor or is not open for reading.
[ENOSTR]: fd refers to a device that has no stream associated with it.
[ENODEV]: fd refers to a device that does not support the putmsg() system call.
[EINVAL]: fd refers to a stream that is linked (directly or indirectly) downstream from a STREAMS multiplexing driver.
[EIO]: fd refers to a stream that has closed or is in the process of closing.
[ENXIO]: fd refers to a stream that has received an M_HANGUP(9) message.
[EPIPE]: fd refers to a STREAMS-based pipe or FIFO that has received an M_HANGUP(9) message.
[EPIPE]: fd refers to a STREAMS-based pipe whose other end has closed or is closing. A SIGPIPE signal will also be sent to the calling process.
[ESTRPIPE]: fd refers to a STREAMS-based pipe or FIFO that has no readers.
[ETIME]: The stream head is set for blocking operation and putmsg() has blocked for an excessively long period of time.
[EAGAIN]: The stream head is set for non-blocking operation using STREAMS O_NDELAY semantics and putmsg() would otherwise block: that is, the message is being sent with flags set to zero (0) and the stream write queue is full due to internal flow control conditions.
[EWOULDBLOCK]: Same as [EAGAIN].
[EINTR]: A signal arrived before the operation could complete.
[ERESTARTSYS]: A signal arrived before the operation could begin. That is, the operation has neither blocked nor written any data.
[EFAULT]: ctlptr, datptr, ctlptr->buf or datptr->buf point outside the caller's address space.
[EINVAL]: The value of flags or the combination of ctlptr, datptr, and the value of flags were invalid, such as when flags is specified as RS_HIPRI and there is no control part.
[ENOSR]: STREAMS resources were insufficient to complete the operation.
[ERANGE]: The len of the data part of the message is outside the range q_minpsz to q_maxpsz inclusive for the topmost STREAMS module or driver under the stream head, or, the len of the control or data part is larger than the maximum sized control or data message for the STREAMS subsystem.

Other errors may be returned by putmsg(). If the protocol module sends an M_ERROR message to the stream head, the error returned on all subsequent write operations, including putsmg(), is specified in the M_ERROR message by the protocol module. Which errors are returned under what conditions form part of the necessary documentation of the protocol module.

NOTICES

Multi-Threading

putmsg() is thread-safe. Because putmsg() does not allow partial writes (unlike write(2s)), POSIX mandatory locks (see lockf(3)) are not necessary to make write operations atomic.

Asynchronous I/O

If the file is set for blocking operation (see fcntl(2)), or old TTY semantics for O_NDELAY are set for the stream head, putmsg() will block waiting for the stream to permit sending messages under flow control.

When the file is set for non-blocking operation, and the stream is set for STREAMS semantics for O_NDELAY, putmsg() will not block, but will fail, return minus one (-1), and populate the global error number, errno(3) with [EAGAIN].

Regardless of the stream head semantics for O_NDELAY, or the setting of the O_NDELAY and O_NONBLOCK file flags, for high priority messages (for which flags is set to RS_HIPRI), putmsg() will not block on flow control, because STREAMS flow control conditions do not apply to high priority messages.

Regardless of the stream head semantics for O_NDELAY, or the setting of the O_NDELAY and O_NONBLOCK file flags, putmsg() will block, unless prevented by lack of internal STREAMS resources, awaiting the availability of message blocks to complete the operation. When prevented from blocking due to a lack of internal STREAMS resources, putmsg() wil fail, return minus one (-1), and set the global error number, errno(3) to [ENOSR].

IMPLEMENTATION

When an implementation returns [ENOSR] is not clear.

An implementation that uses bufcall(9) to implement waiting for the availability of message blocks might fail allocate a bufcall(9) callback due to the unavailability of STREAMS resources. That is, a call to bufcall(9) to create a buffer callback fails and returns zero (0), leaving the implementation little option but to return [ENOSR].

Linux Fast-STREAMS uses a different approach, utilizing the non-standard BPRI_WAITOK flag to allocb(9). This permits the stream head to block awaiting the availability of message blocks without ever failing due to lack of internal STREAMS resources. Therefore, Linux Fast-STREAMS will not return [ENOSR], but will block indefinitely awaiting the availability of a message block.

BUGS

putmsg() has no known bugs.

COMPATIBILITY

putmsg() is compatible with SVID[1], XID[2], SUSv2[3], SUSv3/POSIX[4], and implementations based on SVR 4.2[5], including AIX®, HP-UX®, IRIX®, LiS, MacOT®, OSF/1®, Solaris®, SUPER-UX®, UnixWare®, UXP/V®, with the following compatibility considerations:

---: putmsg() is compatible with LiS[6] with the following exceptions: LiS[6] incorrectly returns [EINVAL] instead of [EIO] when the internal head queue pointer points to a structure that is not a queue structure, or is mangled. LiS[6] does not return [EIO] when putmsg() is called on a closing stream. LiS[6] incorrectly returns [EAGAIN] instead of [EINTR] when an M_SIG message causes a signal that interrupts the call to putmsg() before any data is written. LiS[6] incorrectly returns [ENODEV] instead of [ENOSTR] when there is no stream associated with fd. LiS[6] incorrectly returns [EINVAL] instead of [ENODEV] when fd refers to a device that does not support the putmsg() system call. putmsg() is not bug-for-bug compatible with LiS in these and possibly other regards.
: Portable STREAMS applications, modules and drivers will expect compatibility with POSIX[4] and not rely upon LiS-specific bugs and behaviour.

Linux Fast-STREAMS provides system calls for __NR_getpmsg and __NR_putpmsg that are used to implement this system call. (glibc has prototypes for this system call.) In addition, Linux Fast-STREAMS recognizes the ``invalid'' buffer length to write(2s) used by LiS to emulate the __NR_getpmsg system call, permitting LiS libraries to be used with Linux Fast-STREAMS.

CONFORMANCE

SVID[1], XID[2], SUSv2[3], SUSv3/POSIX[4].

HISTORY

putmsg() first appeared in SVR 3[7].

REFERENCES

[1]: SVID, System V, Interface Definition, Fourth Edition.
[2]: XBD Issue 5, X/Open System Interface Definitions, Issue 5, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[3]: SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[4]: SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[5]: SVR 4.2 CR, UNIX® System V Release 4.2 Command Reference Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[6]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[7]: SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.