putmsg(2)

NAME

putmsg, putpmsg - Sends a message on a stream.

SYNOPSIS

#include <stropts.h>

int putmsg(fd, ctlbuf, databuf, options);
int fd;
struct strbuf *ctlbuf;
struct strbuf *databuf;
long options;
int putpmsg(fd, ctlbuf, databuf, band, options);
int fd;
struct strbuf *ctlbuf;
struct strbuf *databuf;
int band;
long options;

DESCRIPTION

putmsg() and putpmsg() send messages to the STREAMS file. These messages are generated from a user-provided buffer or buffers, 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 to by ctlbuf and databuf respectively. putpmsg() provides more control over how messages are sent by sending messages in different priority bands. Except where specified, all information that applies to putmsg() also applies to putpmsg().

Parameters

The following parameters are used as indicated:

fd Specifies a file descriptor that references an open stream.

ctlbuf Points to a strbuf structure that describes the control part, if any, of the message. This strbuf structure is described below.

databuf Points to a strbuf structure that holds the data part, if any, of the message. This strbuf structure is described below.

band Specifies the priority band.

options Specifies the type of message that should be sent.

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

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

The members are:

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

buf Points to the buffer where the control or data information is to reside.

len Specifies 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 putmsg() and putpmsg(), in addition to the band parameter, is how the option parameter is used to send messages. putpmsg() sends messages as follows:

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

• If options is set to RS_HIPRI, and a control part is specified, the control and data (if present) is sent as a high priority message. If options is set to RS_HIPRI, and a control part is not specified, putmsg() fails.

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

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

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

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

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

• If options is set 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 options is set to 0 (zero), putpmsg() fails.

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

In addition, unless the system runs out of internal resources, putmsg() and putpmsg() 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 option matter. Partial messages are not sent.

RETURN VALUE

Upon successful completion, putmsg() and putpmsg() return a zero; otherwise, they return a value of −1 and set errno to indicate an error.

ERRORS

Both putmsg() and putpmsg() fail if the stream head has processed a STREAMS 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, putmsg() or putpmsg() sets errno to the corresponding value.

[EAGAIN] For a non-priority message, the O_ONDELAY or the O_NONBLOCK option 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 valid for writing.

[EINTR] putmsg() or putpmsg() was interrupted by a signal that was caught.

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

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

[EINVAL] For putpmsg(), the options parameter is MSG_HIPRI and the ctlbuf len parameter is less than 0 (zero) or the band parameter is not 0 (zero); or the options parameter is MSG_BAND and the band parameter is greater than the system maximum (0-255).

[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 top-most stream module. This is explained in more detail in Chapter 3 of the STREAMS manual.

NOTES

For portability purposes, it is recommended that O_NONBLOCK be used instead of O_NDELAY.

Museum

Related Articles