putmsg(2)putmsg(2)NAME
putmsg, putpmsg - send a message on a stream
SYNOPSISDESCRIPTION
The function creates a message from a process 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 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 does the same things as but the process can send messages
in different priority bands. Except where noted, all requirements on
also pertain to
The fildes argument specifies a file descriptor referencing an open
stream. The ctlptr and dataptr arguments each point to a structure.
The ctlptr argument points to the structure describing the control
part, if any, to be included in the message. The buf member in the
structure points to the buffer where the control information resides,
and the len member indicates the number of bytes sent. The maxlen mem‐
ber is not used by In a similar manner, the argument dataptr specifies
the data, if any, to be included in the message. The flags argument
indicates what type of message should be sent and is described further
below.
To send the data part of a message, dataptr must not be a null pointer
and the len member of dataptr must be 0 or greater. To send the con‐
trol part of a message, the corresponding values must be set for
ctlptr. No data (control) part will be sent if either dataptr (ctlptr)
is a null pointer or the len member of dataptr (ctlptr) is set to −1.
For if a control part is specified and flags is set to a high priority
message is sent. If no control part is specified, and flags is set to
fails and sets to If flags is set to a normal message (priority band
equal to is sent. If a control part and data part are not specified
and flags is set to no message is sent and is returned.
The stream head guarantees that the control part of a message generated
by is at least 64 bytes in length.
For the flags are different. The flags argument is a bitmask with the
following mutually-exclusive flags defined: and If flags is set to
fails and sets to If a control part is specified and flags is set to
and band is set to a high-priority message is sent. If flags is set to
and either no control part is specified or band is set to a non-zero
value, fails and set to If flags is set to 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 no message is sent and is
returned.
The function blocks if the stream write queue is full due to internal
flow control conditions. For high-priority messages, does not block on
this condition. For other messages, does not block when the write
queue is full and is set.
The function also blocks, unless prevented by lack of internal
resources, while for the availability of message blocks in the stream,
regardless of priority of whether has been specified. No partial mes‐
sage is sent.
RETURN VALUE
and return the following values:
Successful completion.
Error. is set to indicate the error.
ERRORS
On failure, may be set to one of the following values:
A non-priority message was specified, the
flag is set, and the stream write queue is full due to
internal flow control conditions, or buffers could not
be allocated for the message that was to be created.
fildes is not a valid file descriptor open for writing.
A signal was caught during
or
An undefined value is specified in
flags, or flags is set to or and no control part is sup‐
plied, or the stream or multiplexor referenced by fildes
is linked (directly or indirectly) downstream from a
multiplexor, or flags is set to and band is non-zero
(for only).
See
A stream is not associated with
fildes.
A hangup condition was generated downstream for the specified
stream.
The fildes argument refers to a STREAMS-based pipe and the
other end of the pipe is closed. A signal is generated
for the calling process.
The size of the data part of the message does not fall within the range
specified by the maximum and minimum packet sizes of the
topmost STREAMS module. This value is also returned if
the control part of the message is larger than the maxi‐
mum configured size of the control part of a message, or
if the data part of the message is larger than the maxi‐
mum configured size of the data part of a message.
In addition, and will fail if the stream head had processed an asyn‐
chronous error before the call. In this case, the value of does not
reflect the result of or but reflects the prior error.
SEE ALSOgetmsg(2), poll(2), read(2), write(2), thread_safety(5), streamio(7),
<stropts.h>.
putmsg(2)