putmsg(2) DG/UX 4.30 putmsg(2)
NAME
putmsg - Pass a message down a stream.
SYNOPSIS
#include <stropts.h>
int putmsg (filedes, control_info_ptr, data_info_ptr, priority)
int filedes;
struct strbuf * control_info_ptr;
struct strbuf * data_info_ptr;
int priority;
PARAMETERS
filedes File descriptor
control_info_ptr
A pointer to a structure describing the
control buffer or NULL, if there is no
control buffer.
data_info_ptr A pointer to a structure describing the data
buffer or NULL, if there is no data buffer.
priority The type of the message to put.
DESCRIPTION
Fildes is a valid, active descriptor referring to an open
streams file. This function creates a message containing a
control part, a data part, or both, and sends the message
down the stream whose handle is given. Control_info_ptr and
Data_info_ptr point to strbuf structures that contain the
following fields:
* buf - Pointer to the first information.
* len - The number of bytes
* maxlen - Ignored.
If an strbuf pointer is NULL or len is negative, there is no
information of that type and there is no corresponding part
of the message. If neither type of information is
specified, no message is sent.
If there is control information, it occupies the first
message block. The block has type M_PCPROTO if priority is
RS_HIPRI and M_PROTO otherwise. If there is no control
information and priority is RS_HIPRI, the putmsg fails. The
control len must be less than or equal to the configuration
limit on the control part of a message.
If there is data information, it occupies subsequent blocks.
Licensed material--property of copyright holder(s) Page 1
putmsg(2) DG/UX 4.30 putmsg(2)
Each block has type M_DATA. The data len must fall between
the minimum and maximum packet sizes (inclusive) accepted by
the module or driver directly below the stream head.
Modules and drivers should not assume anything about the
sizes of the individual message blocks that make up the data
part of the message. If the stream's write offset is non-
zero, that many bytes are skipped in the first of the data
message blocks before copying in the caller's data. The
read position of that block is set to the beginning of the
caller's data, instead of to the beginning of the data
buffer, as it is with the rest of the message blocks.
The message is sent downstream by calling the write put
procedure of the module or driver directly below the stream
head. If priority is not RS_HIPRI and neither the O_NDELAY
nor O_NONBLOCK flag of fildes is set, this function blocks
if that write queue is full due to flow control conditions.
The message is passed when the queue is no longer full. If
the O_NDELAY or O_NONBLOCK flag is set, the putmsg fails and
errno is set to EAGAIN. If priority is RS_HIPRI, the
message is always passed.
Putmsg fails if a M_ERROR message was processed by the
stream head before the call to putmsg. The errno returned
is the value contained in the error message.
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.
EXCEPTIONS
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 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 control_info_ptr,
or data_info_ptr do not lie entirely within
the caller's readable address space.
EINTR A signal was caught during the putmsg call.
Licensed material--property of copyright holder(s) Page 2
putmsg(2) DG/UX 4.30 putmsg(2)
EINVAL An illegal value was specified by priority or
priority 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.
SEE ALSO
getmsg(2), poll(2).
Licensed material--property of copyright holder(s) Page 3