putmsg(2) DG/UX 5.4.2 putmsg(2)
NAME
putmsg, putpmsg - pass a message down a stream
SYNOPSIS
#include <stropts.h>
int putmsg(filedes, controlinfoptr, datainfoptr, flags)
int filedes;
struct strbuf * controlinfoptr;
struct strbuf * datainfoptr;
int flags;
int putpmsg(filedes, controlinfoptr, datainfoptr, band, flags)
int filedes;
struct strbuf * controlinfoptr;
struct strbuf * datainfoptr;
int band;
int flags;
where:
filedes A valid, active descriptor referring to an open
streams file
controlinfoptr A pointer to a structure describing the control
buffer or NULL, if there is no control buffer
datainfoptr A pointer to a structure describing the data
buffer or NULL, if there is no data buffer
band The priority band the message is to be sent in.
flags Indicates the type of message to be sent.
DESCRIPTION
putmsg creates a message from user-specified buffer(s) and sends the
message to a STREAMS file. The message may contain either a data
part, a control part, or both. The data and control parts to be sent
are distinguished by placement in separate buffers, as described
below. The semantics of each part is defined by the STREAMS module
that receives the message.
The function putpmsg does the same thing as putmsg, but provides the
user the ability to send messages in different priority bands.
Except where noted, all information pertaining to putmsg also
pertains to putpmsg.
fd specifies a file descriptor referencing an open stream. ctlptr
and dataptr each point to a strbuf structure, which contains the
following members:
buf Pointer to the first byte of the control or data
information.
len The number of bytes of information in the buffer.
Licensed material--property of copyright holder(s) 1
putmsg(2) DG/UX 5.4.2 putmsg(2)
maxlen Ignored [see getmsg(2)].
To send the data part of a message, datainfoptr must not be NULL
and the len field of datainfoptr must have a value of 0 or greater.
To send the control part of a message, the corresponding values must
be set for controlinfoptr. No data (control) part is sent if
either datainfoptr (controlinfoptr) is NULL or the len field of
datainfoptr (controlinfoptr) is set to -1.
For putmsg(), if a control part is specified, and flags is set to
RSHIPRI, a high priority message is sent. If no control part is
specified, and flags is set to RSHIPRI, putmsg fails and sets errno
to EINVAL. If flags is set to 0, a normal (non-priority) message is
sent. If no control part and no data part are specified, and flags
is set to 0, no message is sent, and 0 is returned.
The stream head guarantees that the control part of a message
generated by putmsg is at least 64 bytes in length.
For putpmsg, the flags are different. flags is a bitmask with the
following mutually-exclusive flags defined: MSGHIPRI and MSGBAND.
If flags is set to 0, putpmsg fails and sets errno to EINVAL. If a
control part is specified and flags is set to MSGHIPRI and band is
set to 0, a high-priority message is sent. If flags is set to
MSGHIPRI and either no control part is specified or band is set to a
non-zero value, putpmsg() fails and sets errno to EINVAL. If flags
is set to MSGBAND, then a message is sent in the priority band
specified by band. If a control part and data part are not specified
and flags is set to MSGBAND, no message is sent and 0 is returned.
Normally, putmsg() will block if the stream write queue is full due
to internal flow control conditions. For high-priority messages,
putmsg() does not block on this condition. For other messages,
putmsg() does not block when the write queue is full and ONDELAY or
ONONBLOCK is set. Instead, it fails and sets errno to EAGAIN.
putmsg or putpmsg also block, unless prevented by lack of internal
resources, waiting for the availability of message blocks in the
stream, regardless of priority or whether ONDELAY or ONONBLOCK has
been specified. No partial message is sent.
ACCESS CONTROL
Fildes must be open for writing.
RETURN VALUE
0 The message was successfully sent.
-1 The message was not sent. errno is set to indicate the error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EAGAIN The O_NDELAY or O_NONBLOCK flag was set, a non-priority
message was specified, and the stream write queue is full
Licensed material--property of copyright holder(s) 2
putmsg(2) DG/UX 5.4.2 putmsg(2)
due to internal flow control conditions; or streams buffers
could not be allocated for the message.
EBADF Fildes is not a valid, active descriptor open for writing.
EFAULT The arguments pointed to by controlinfoptr, or
datainfoptr do not lie entirely within the caller's
readable address space.
EINTR A signal was caught during the putmsg call.
EINVAL An illegal value was specified by flags or flags was
RS_HIPRI and there was no control part of the message; or
the stream referred to by fildes is linked under a
multiplexor.
ENXIO A hangup condition was generated downstream for the
specified stream.
ERANGE The size of the data part of the message does not fall
within the range specified by the minimum and maximum
packet sizes of the write side of the topmost module on the
stream; or the control or data part of the message exceeded
the configured maximum for that part of a message.
ENOSR If a stream is not associated with filedes.
SEE ALSO
getmsg(2), poll(2).
NOTE
The user should avoid using ONDELAY and instead should use
ONONBLOCK.
Licensed material--property of copyright holder(s) 3