NAME

putmsg, putpmsg − Send a message on a Stream

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <stropts.h> int putmsg(
int fd,
const struct strbuf ∗ctlbuf,
const struct strbuf ∗databuf,
int flags); int putpmsg(
int fd,
const struct strbuf ∗ctlbuf,
const struct strbuf ∗databuf,
int band,
int flags);

PARAMETERS

fdSpecifies a file descriptor that references an open Stream. 

ctlbufPoints to a strbuf structure that describes the control part, if any, of the message. This strbuf structure is described in the DESCRIPTION section. 

databufPoints to a strbuf structure that holds the data part, if any, of the message. This strbuf structure is described in the DESCRIPTION section. 

bandSpecifies the priority band. 

flagsSpecifies the type of message that should be sent. 

DESCRIPTION

The putmsg() and putpmsg() functions send messages to the STREAMS file.  These messages are generated from user-provided buffer(s), and must contain a control part and/or a data part.  The open Stream specifies the format and semantics of the message’s control and data parts.  The control and data parts of the message are placed into separate buffers, pointed at by cltbuf and databuf respectively.  The putpmsg() function provides more control over how messages are sent.  With this function, you can send messages in different priority bands.  Except where specified, all information that applies to the putmsg() function also applies to the putpmsg() function. 

The ctlbuf and databuf parameters each point to a strbuf structure that contains three members.  This structure is defined in <sys/stropts.h> as:

struct strbuf {
    int maxlen;/∗ max buffer length ∗/
    int len;/∗ length of data ∗/
    char ∗buf/∗ pointer to buffer ∗/
};

The members are:

maxlenSpecifies the maximum number of bytes buf can hold.  This field is not used by either the putmsg() or putpmsg() function. 

bufPoints to the buffer where the control information is to reside. 

lenSpecifies the number of bytes to be sent.  A message can contain a control part and/or a data part, depending on what is to be sent.  To send one or the other, the corresponding ctlbuf or databuf parameter must be a non-null pointer and the len field of the corresponding strbuf structure must have a value of 0 (zero) or greater.  A data or control part is not sent if its respective databuf or ctlbuf parameter is a null pointer, or if the corresponding structure’s len field is set to -1. 

One of the major differences between the putmsg() and putpmsg() function, in addition to the band parameter, is how the flag parameter is used to send messages.  The putpmsg() function sends messages as follows:

       •If you set the flags parameter to a value of 0 (zero), a normal message (priority band equal to 0 (zero)) is sent. 

       •If you set the flags parameter to RS_HIPRI, and a control part is specified, the control and data (if present) is sent as a high priority message. 

       •If you set the flags parameter to RS_HIPRI, and a control part is not specified, putmsg() fails. 

       •If you set the flags parameter to 0 (zero), and both the control part and the data part of not specified, no message is sent and a value of 0 (zero) is returned. 

The putpmsg() function flags parameter is a bitmask with the mutually exclusive flags MSG_HIPRI and MSG_BAND defined.  The putpmsg() function sends messages as follows:

       •If you set flags to MSG_BAND, the control and/or data part is sent on the priority band specified by the band parameter. 

       •If you set the flags parameter to MSG_HIPRI, and set the band parameter to 0 (zero), and if a control part is specified, the control and data (if present) is sent as a high-priority message. 

       •If you set the flags parameter to MSG_HIPRI, and either no control part is specified or band is set to a non-zero value, the putpmsg() function fails. 

       •If you set flags to MSG_BAND, and both a control part and data are not specified, no message is sent and a value of 0 (zero) is returned. 

       •If you set the flags parameter to 0 (zero), putpmsg() fails. 

Unless the message is a high priority one, the putmsg(0 function generally blocks if the Stream write queue is full.  This is because of internal flow control conditions.  The putmsg() function does not block on this condition for high priority messages.  However, for other messages, if the  O_NDELAY or O_NONBLOCK flag is set for the write() operation, the putmsg() function will not block when the write queue is full.  Instead, it fails. 

In addition, unless the system runs out of internal resources, the putmsg() and putpmsg() functions will block while waiting for the availability of message blocks in the Stream.   In this instance, neither the message priority nor the assertion of the O_NDELAY or O_NONBLOCK flag matter.  Partial messages are not sent. 

RETURN VALUES

Upon successful completion, the putmsg() and putpmsg() functions return a value of 0 (zero). Otherwise, they return a value of -1 and errno is set to indicate an error. 

ERRORS

Both the putmsg() and putpmsg() functions fail if the Stream head has processed a STREAM error message before either of these functions is called.  In this instance, the STREAMS error message contains the value of the returned error. 

In addition, if any of the following conditions occurs, the putmsg() or putpmsg() function sets errno to the corresponding value. 

[EAGAIN]For a non-priority message, the O_ONDELAY or the O_NONBLOCK flag is set, and the Stream write queue is determined to be full because of the internal flow control conditions. 

[EBADF]The fd parameter is not invalid for writing. 

[EINTR]The putmsg() and putpmsg() function was interrupted by a signal that was caught. 

[EINVAL]An undefined message was specified in the flags parameter. 

[EINVAL]For the putmsg() function, the flags parameter is RS_HIPRI and the ctlbuf len parameter is less than 0 (zero). 

[EINVAL]For the putpmsg() function, the flags parameter is MSG_HIPRI and the ctlbuf len parameter is less than 0 (zero) or the band parameter is not 0 (zero); or the flags parameter is MSG_BAND and the band parameter is greater than the system minimum. 

[EINVAL]The Stream specified by the fd parameter is linked under a multiplexor. 

[ENOSTR]A Stream is not associated with the fd parameter. 

[ENXIO]A hangup condition for the specified Stream was generated downstream. 

[ERANGE]The size of the control part of a message is larger than the maximum configured size of the message’s control part; or the data part of a message is larger than the maximum configured size of the message’s data part; or the data part size of the message does not conform to the range indicated by the maximum and minimum packet sizes of the topmost Stream module. 

RELATED INFORMATION

Functions: getmsg(2), poll(2), read(2), write(2). 
Interfaces: streamio(7).