 |
Index for
Section 2 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
putmsg(2)
NAME
putmsg, putpmsg - Send a message on a Stream
LIBRARY
Standard C Library (libc)
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);
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
putmsg(), putpmsg(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
fd Specifies a file descriptor that references an open Stream.
ctlbuf Points to a strbuf structure that describes the control part, if
any, of the message. This strbuf structure is described in the
DESCRIPTION section.
databuf Points to a strbuf structure that holds the data part, if any, of
the message. This strbuf structure is described in the
DESCRIPTION section.
band Specifies the priority band.
flags 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 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:
maxlen Specifies the maximum number of bytes buf can hold. This field
is not used by either the putmsg() or putpmsg() function.
buf Points to the buffer where the control information is to reside.
len 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 flag 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 flags 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 flag 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.
NOTES
[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.
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 indicate
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.
[EAGAIN] 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.
[EBADF] The fd parameter is not invalid for writing.
[EINTR] The putmsg() function was interrupted by a signal that was
caught.
[EINVAL] 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.
[ENOSR] The system could not allocate buffers for the message that was to
be created because of insufficient Streams memory resources.
[ENOSTR] A Stream is not associated with the fd parameter.
[EPIPE] 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.
[ENXIO] A hangup condition for the specified Stream was generated
downstream.
[ERANGE] 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.
RELATED INFORMATION
Functions: getmsg(2), poll(2), read(2), write(2)
Interfaces: streamio(7)
Standards: standards(5)
|
Index for
Section 2 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|