putmsg(2) System Calls Manual putmsg(2)
NAME
putmsg, putpmsg - send a message on a stream
SYNOPSIS
DESCRIPTION
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
member is not used by In a similar manner, the argument dataptr specifies the data, if any, to be included in the message. The flags argu-
ment 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
control 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 speci-
fied 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 message 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 supplied, 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 call-
ing 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 maximum configured size of the control part of a message, or if the data part of the
message is larger than the maximum configured size of the data part of a message.
In addition, and will fail if the stream head had processed an asynchronous error before the call. In this case, the value of does not
reflect the result of or but reflects the prior error.
SEE ALSO
getmsg(2), poll(2), read(2), write(2), thread_safety(5), streamio(7), <stropts.h>.
putmsg(2)