putmsg, putpmsg - Send a message on a Stream
#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 );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards 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.
Specifies a file descriptor that references an open
Stream. Points to a strbuf structure that describes the
control part, if any, of the message. 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 section. Specifies the priority band. Specifies
the type of message that should be sent.
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 specified, 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. Specifies 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 ctlbuf 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 structure's len field is set to -1.
One of the major differences between the putmsg() and
putpmsg() function, 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 parameter 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() function sends messages as follows:
If you set flags to MSG_BAND, the control 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 generally 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 messages, if
the O_NDELAY or O_NONBLOCK flag is set for the write()
operation, 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 message blocks in the Stream. In
this instance, neither the message priority nor the assertion
of the O_NDELAY or O_NONBLOCK option matter. Partial
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 compatibility.
[Tru64 UNIX] When compiled in the X/Open UNIX environment,
calls to the putmsg() and putpmsg() functions are
internally renamed by prepending _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
standards(5) for further information.
Upon successful completion, the putmsg() functions return
a value of 0 (zero). Otherwise, they return a value of -1
and errno is set to indicate an error.
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 control
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 created. 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 multiplexor. 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 calling 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 control part; or the data part of a message
is larger than the maximum 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.
Functions: getmsg(2), poll(2), read(2), write(2)
Interfaces: streamio(7)
Standards: standards(5)
Network Programmer's Guide
putmsg(2)
[ Back ] |
