Manpage of PUTPMSG

PUTPMSG

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

NAME

putpmsg - put a band message to a STREAMS character device

SYNOPSIS

#include <stropts.h>

int putpmsg(int fd, const struct strbuf *ctlptr, const struct strbuf *dataptr, int band, 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

putpmsg() generates a STREAMS message from the buffer supplied in the specified ctlptr and datapr for the queue band band 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 putpmsg().
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 indiates 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 indiates 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.

band specifies the queue band to which to write data when flags is set to MSG_BAND. When flags is set to other than MSG_BAND, band must be set to zero (0).

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

MSG_HIPRI: Specifies that a high priority message is to be sent if the request contains a control part (ctlptr is not NULL). This results in an M_PCPROTO message being placed on the stream head.
MSG_BAND: Specifies that a normal priority queue band message is to be sent for the specified band. 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 for the specified band is placed on the stream head.

RETURN VALUE

Upon success, putpmsg() returns zero (0).

Upon failure, putpmsg() returns -1 and sets errno to an appropriate error number.

ERRORS

When putpmsg() fails, it returns -1 and sets errno to one of the following:


[EAGAIN]: The stream head is set for non-blocking operation and putpmsg() would block: that is, the message is being sent with flags set to MSG_BAND and the corresponding band is flow controlled.
[EBADF]: fd is not a valid file descriptor, or refers to a stream that is not open for writing.
[ENOSTR]: does not refer to a stream.
[EINVAL]: refers to a stream that is currently linked underneath a STREAMS multiplexing driver. All read or write systems calls will fail with error number [EINVAL] for such a stream.
[EFAULT]: ctlptr, datptr, ctlptr->buf or datptr->buf point outside the caller's address space.
[ERESTARTSYS]: A signal arrived before the operation could begin.
[EINTR]: A signal arrived before the operation could complete.
[EINVAL]: The values of band or flags, or the combination of ctlptr, datptr, and the values of band and flags were invalid, such as when flags is specified as MSG_HIPRI and band is non-zero.
[EINVAL]: fd refers to a stream that is linked under a STREAMS multiplexing driver.
[EIO]: I/O error, or, fd refers to a stream that is open but is in the process of closing.
[EPIPE]: fd refers to a pipe and the other end of the pipe is closed.
[ESTRPIPE]: fd refers to a STREAMS based pipe and there are no readers at the other end of the pipe.
[EISDIR]: fd refers to a directory.
[ENODEV]: fd refers to a device that does not support the putpmsg() system call.
[ENOSR]: STREAMS resources were insufficient to complete the operation.
[ENOSTR]: fd refers to a device that has no stream associated with it.
[ENXIO]: A M_HANGUP message arrived at the stream head for the specified fd.
[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.
[ENOSYS]: The putpmsg() system call is not supported on your system. The occurs when STREAMS is not loaded or you have linked the wrong library.

Other errors may be returned by putpmsg(). If the protocol module sends an M_ERROR(9) message to the stream head, the error returned on all subsequent write operations, including putpmsg(), is specified in the M_ERROR(9) 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

putpmsg() is thread-safe; however, multiple threads performing concurrent partial writes on the same stream will interfere with each other. POSIX mandatory file locks, (see lockf(3)), can be used to avoid interference.

Asynchronous I/O

If the file is set for blocking operation (see fcntl(2)), then putpmsg() will block waiting for the band specified in band (with MSG_BAND set in flags) to permit sending messages under band flow control. (putpmsg() will not wait for a message block to formulate the STREAMS message, but will return [ENOSR] if it cannot allocate the necessary message block). When the file is set for non-blocking operation, putpmsg() will not block, but will return the appropriate error number ([ENOSTR], [EAGAIN], [EWOULDBLOCK]) if the STREAMS message could not be formulated and sent immediately.

BUGS

putpmsg() has no known bugs.

COMPATIBILITY

putpmsg() is compatible with SVID[1], XID[2], SUSv2[3], SUSv3[4], POSIX, and implementations based on SVR 4.2[5], including AIX®, HP-UX®, LiS, OSF/1®, Solaris®, SUPER-UX®, UnixWare®, UXP/V®.

putpmsg() 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 does not return [EIO] when fd refers to a closing stream.
---: LiS incorrectly returns [EIO] when fd refers to a broken pipe.
---: LiS incorrectly returns [EAGAIN] instead of [EINTR] when an M_SIG message causes a signal that interrupts the call to putpmsg() before any data is written.
---: LiS incorrectly returns [ENODEV] instead of [ENOSTR] when there is no stream associated with fd.
---: LiS incorrectly returns [EINVAL] instead of [ENODEV] when fd refers to a device that does not support the putpmsg() system call.

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[4], POSIX.

HISTORY

putpmsg() first appeared in SVR 4[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 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.