putmsg(2)putmsg(2)NAME
putmsg, putpmsg - Send a message on a Stream
SYNOPSIS
#include <stropts.h>
int putmsg(
int fd,
const struct strbuf *ctlbuf,
const struct strbuf *databuf,
int flags ); int putpmsg(
int fd,
const struct strbuf *ctlbuf,
const struct strbuf *databuf,
int band,
int flags );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
putmsg(), putpmsg(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies a file descriptor that references an open Stream. Points to
a strbuf structure that describes the control part, if any, of the mes‐
sage. This strbuf structure is described in the DESCRIPTION section.
Points to a strbuf structure that holds the data part, if any, of the
message. This strbuf structure is described in the DESCRIPTION sec‐
tion. Specifies the priority band. Specifies the type of message that
should be sent.
DESCRIPTION
The putmsg() and putpmsg() functions send messages to the STREAMS file.
These messages are generated from user-provided buffer(s), 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 at by cltbuf and databuf respectively. The putpmsg() function
provides more control over how messages are sent. With this function,
you can send messages in different priority bands. Except where speci‐
fied, all information that applies to the putmsg() function also
applies to the putpmsg() function.
The ctlbuf and databuf parameters each point to a strbuf structure that
contains three members. This structure is defined in <sys/stropts.h>
as:
struct strbuf {
int maxlen; /* max buffer length */
int len; /* length of data */
char *buf; /* pointer to buffer */ };
The members are: Specifies the maximum number of bytes buf can hold.
This field is not used by either the putmsg() or putpmsg() function.
Points to the buffer where the control information is to reside. Spec‐
ifies the number of bytes to be sent.
A message can contain a control part or a data part, or both, depending
on what is to be sent. To send one or the other, the corresponding ctl‐
buf 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 struc‐
ture's len field is set to -1.
One of the major differences between the putmsg() and putpmsg() func‐
tion, in addition to the band parameter, is how the flags parameter is
used to send messages. The putmsg() function sends messages as follows:
If you set the flags parameter to a value of 0 (zero), a normal message
(priority band equal to 0 (zero)) is sent. If you set the flags param‐
eter to RS_HIPRI and a control part is specified, the control and data
(if present) is sent as a high priority message. If you set the flags
parameter to RS_HIPRI and a control part is not specified, putmsg()
fails. If you set the flags parameter to 0 (zero) and both the control
part and the data part of not specified, no message is sent and a value
of 0 (zero) is returned.
The putpmsg() function flags parameter is a bitmask with the mutually
exclusive options MSG_HIPRI and MSG_BAND defined. The putpmsg() func‐
tion sends messages as follows: If you set flags to MSG_BAND, the con‐
trol and/or data part is sent on the priority band specified by the
band parameter. If you set the flags parameter to MSG_HIPRI, set the
band parameter to 0 (zero), and specify a control part, the control and
data (if present) is sent as a high-priority message. If you set the
flags parameter to MSG_HIPRI, and either no control part is specified
or band is set to a non-zero value, the putpmsg() function fails. If
you set flags 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
you set the flags parameter to 0 (zero), putpmsg() fails.
Unless the message is a high priority one, the putmsg() function gener‐
ally blocks if the Stream write queue is full. This is because of
internal flow control conditions. The putmsg() function does not block
on this condition for high priority messages. However, for other mes‐
sages, if the O_NDELAY or O_NONBLOCK flag is set for the write() opera‐
tion, the putmsg() function will not block when the write queue is
full. Instead, it fails.
In addition, unless the system runs out of internal resources, the
putmsg() function will block while waiting for the availability of mes‐
sage blocks in the Stream. In this instance, neither the message prior‐
ity nor the assertion of the O_NDELAY or O_NONBLOCK option matter. Par‐
tial messages are not sent.
[Tru64 UNIX] Current industry standards do not define the O_NDELAY
flag. It is included in the preceding paragraphs for System V compati‐
bility.
NOTES
[Tru64 UNIX] When compiled in the X/Open UNIX environment, calls to
the putmsg() and putpmsg() functions are internally renamed by prepend‐
ing _E to the function name. When you are debugging a module that
includes the putmsg() or putpmsg() function and for which
_XOPEN_SOURCE_EXTENDED has been defined, use _Eputmsg to refer to the
putmsg() call, and _Eputpmsg to refer to the putpmsg() call. See stan‐
dards(5) for further information.
RETURN VALUES
Upon successful completion, the putmsg() functions return a value of 0
(zero). Otherwise, they return a value of -1 and errno is set to indi‐
cate an error.
ERRORS
The putmsg() function fails if the Stream head has processed a STREAM
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, the putmsg()
function sets errno to the corresponding value. For a non-priority
message, the O_NDELAY or the O_NONBLOCK flag is set, and the Stream
write queue is determined to be full because of the internal flow con‐
trol conditions.
[Tru64 UNIX] Current industry standards do not define the
O_NDELAY flag. It is included in the preceding paragraphs for
System V compatibility.
The system could not allocate buffers for the message to be cre‐
ated. The fd parameter is not invalid for writing. The
putmsg() function was interrupted by a signal that was caught.
An undefined message was specified in the flags parameter.
For the putmsg() function, the flags parameter is RS_HIPRI or
MSG_HIPRI, and the ctlbuf len parameter is less than 0 (zero).
For the putpmsg() function, the flags parameter is MSG_HIPRI and
the ctlbuf len parameter is less than 0 (zero)
[Tru64 UNIX] For the putpmsg() function, the flags parameter is
MSG_HIPRI and the band parameter is not 0 (zero); or the flags
parameter is MSG_BAND and the band parameter is greater than the
system minimum.
The Stream specified by the fd parameter is linked under a mul‐
tiplexor. The system could not allocate buffers for the message
that was to be created because of insufficient Streams memory
resources. A Stream is not associated with the fd parameter.
The other end of a Streams-based piped referred to by the fd
parameter is closed. A SIGPIPE signal is generated for the call‐
ing process. A hangup condition for the specified Stream was
generated downstream. The size of the control part of a message
is larger than the maximum configured size of the message's con‐
trol part; or the data part of a message is larger than the max‐
imum 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 topmost Stream
module.
SEE ALSO
Functions: getmsg(2), poll(2), read(2), write(2)
Interfaces: streamio(7)
Standards: standards(5)
Network Programmer's Guide
putmsg(2)