STREAMS-UX Programmer's Guide (February 2007)

STREAMS Mechanism and System Calls
Writing to a Stream
Chapter 2
23
putmsg(2) and putpmsg(2)
The putmsg (2) and putpmsg (2) calls also write messages to streams. These system calls can handle control
messages and message priority information.
Synopsis
#include <sys/stropts.h>
int putmsg (int fd, struct strbuf *ctlptr, struct strbuf *dataptr, int *priflag);
int putpmsg (int fd, struct strbuf *ctlptr, struct strbuf *dataptr, int *msgband, int *priflag);
fd STREAMS file descriptor.
ctlptr Pointers to strbuf structures containing control information.
dataptr Pointers to strbuf structures containing data.
strbuf A structure defined in <sys/stropts.h> to hold the control and data information to be
written to the stream. The user process issuing the putmsg (2) or putpmsg (2) system calls
uses the following strbuf structure:
struct strbuf {
int maxlen; /* maximum buffer length */
int len; /* actual length of message to be written */
char *buf; /* Pointer to the message buffer */
};
NOTE Unlike the getmsg (2) and getpmsg (2) calls, the maxlen attribute is not used
by putmsg (2).
priflag Priority of the message to be written to the stream (Ordinary or High).
msgband Band priority of the message to be written to the stream (applicable to ordinary messages
only).
Return Values
Upon successful completion, putmsg (2) and putpmsg (2) return 0. Otherwise, they return -1 and set errno
appropriately, as with all UNIX File system I/O.
Writing Control and Data Messages
The putmsg (2) and putpmsg (2) can write the control, data, or both the parts of the message. To write any
part of the buffer, the corresponding buffer pointer (ctlptr or dataptr) must be non-null and the
corresponding len field must be greater than -1. If the buffer pointer (ctlptr or dataptr) is null or the
corresponding len field is -1, then nothing is written for that part of the message.
Message Priority
The priority of a message written to a stream is determined by the control part of the message. In the absence
of a control part (as is the case with write (2)), the message priority is set to normal by default. To explicitly
set the priority of the data part of a message, both the control part and the data part must be present as
arguments to putmsg (2) and putpmsg (2).
For putmsg (2), the priflags argument takes one of two values — RS_HIPRI or 0.
• If the control part is specified and priflags is set to RS_HIPRI, a high priority message will be written to
the stream.
• If no control part is specified, and priflags is set to RS_HIPRI, putmsg (2) fails, and sets errno .