180 lines
6.7 KiB
Groff
180 lines
6.7 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g2.putmsg @(#)putmsg 41.4 of 5/26/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} putmsg 2 "" "\&"
|
|
.if \nX=1 .ds x} putmsg 2 ""
|
|
.if \nX=2 .ds x} putmsg 2 "" "\&"
|
|
.if \nX=3 .ds x} putmsg "" "" "\&"
|
|
.if \nX=4 .ds x} putmsg "2" "EXTENSION" " "
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4putmsg\f1 \- send a message on a stream
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\f4#include <stropts.h>
|
|
|
|
int putmsg(int fd, const struct strbuf *ctlptr,
|
|
const struct strbuf *dataptr, int flags);
|
|
|
|
int putpmsg(int fd, const struct strbuf *ctlptr,
|
|
const struct strbuf *dataptr, int band, int flags);\fP
|
|
.fi
|
|
.SH DESCRIPTION
|
|
\f4putmsg\fP creates a message
|
|
from user-specified buffer(s) and sends the message to a
|
|
\s-1STREAMS\s0 file.
|
|
The message may contain either a data part, a control part, or both.
|
|
The data and control parts to be sent are distinguished by placement in separate
|
|
buffers, as described below.
|
|
The semantics of each part is defined by the \s-1STREAMS\s0 module that receives
|
|
the message.
|
|
.PP
|
|
The function \f4putpmsg\fP does the same thing as \f4putmsg\fP, but
|
|
provides the user the ability to send messages in different priority bands.
|
|
Except where noted, all information pertaining to \f4putmsg\fP
|
|
also pertains to \f4putpmsg\fP.
|
|
.PP
|
|
\f2fd\f1 specifies a file descriptor referencing an open stream.
|
|
\f2ctlptr\f1 and \f2dataptr\f1 each point to a \f4strbuf\f1 structure,
|
|
which contains the following members:
|
|
.PP
|
|
.RS
|
|
.ft 4
|
|
.nf
|
|
int maxlen; /* not used */
|
|
int len; /* length of data */
|
|
void *buf; /* ptr to buffer */
|
|
.fi
|
|
.ft 1
|
|
.RE
|
|
.PP
|
|
\f2ctlptr\f1 points to the structure describing the control part, if any,
|
|
to be included in the message.
|
|
The \f4buf\f1 field in the \f4strbuf\f1 structure
|
|
points to the buffer where the control information resides,
|
|
and the \f4len\f1 field indicates the number of bytes to be sent.
|
|
The \f4maxlen\f1 field is not used in \f4putmsg\fP [see \f4getmsg\fP(2)].
|
|
In a similar manner, \f2dataptr\f1 specifies the data, if any, to be included in
|
|
the message.
|
|
\f2flags\f1 indicates what type of message should be sent and is described later.
|
|
.PP
|
|
To send the data part of a message, \f2dataptr\f1 must not be \f4NULL\fP and
|
|
the \f4len\f1 field of \f2dataptr\f1 must have a value of 0 or greater.
|
|
To send the control part of a message, the corresponding values must be set for
|
|
\f2ctlptr\f1.
|
|
No data (control) part is sent if either \f2dataptr\f1 (\f2ctlptr\f1) is
|
|
\f4NULL\fP or the \f4len\f1 field of \f2dataptr\f1 (\f2ctlptr\f1) is set to \-1.
|
|
.PP
|
|
For \f4putmsg\f1(), if a control part is specified, and \f2flags\f1 is set to
|
|
\f4RS_HIPRI\fP,
|
|
a high priority message is sent.
|
|
If no control part is specified, and \f2flags\f1 is set to \f4RS_HIPRI\fP,
|
|
\f4putmsg\fP fails and sets \f4errno\f1 to \f4EINVAL\fP.
|
|
If \f2flags\f1 is set to 0, a normal (non-priority) message is sent.
|
|
If no control part and no data part are specified, and \f2flags\f1 is set to 0,
|
|
no message is sent, and 0 is returned.
|
|
.PP
|
|
The stream head guarantees that the control part of a message generated by
|
|
\f4putmsg\fP is at least 64 bytes in length.
|
|
.PP
|
|
For \f4putpmsg\fP, the flags are different.
|
|
\f2flags\f1 is a bitmask with
|
|
the following mutually-exclusive flags defined:
|
|
\f4MSG_HIPRI\f1 and \f4MSG_BAND\f1.
|
|
If \f2flags\f1 is set to 0,
|
|
\f4putpmsg\fP fails and sets \f4errno\f1 to \f4EINVAL\f1.
|
|
If a control part is specified and \f2flags\f1 is set to \f4MSG_HIPRI\f1
|
|
and \f2band\f1 is set to 0, a high-priority message is sent.
|
|
If \f2flags\f1 is set to \f4MSG_HIPRI\f1 and either no control part is
|
|
specified or \f2band\f1 is set to a non-zero value, \f4putpmsg\f1() fails
|
|
and sets \f4errno\f1 to \f4EINVAL\f1.
|
|
If flags is set to \f4MSG_BAND\f1,
|
|
then a message is sent in the priority band specified by \f2band\f1.
|
|
If a control part and data part are not specified and \f2flags\f1 is set to
|
|
\f4MSG_BAND\f1, no message is sent and 0 is returned.
|
|
.P
|
|
Normally, \f4putmsg\f1() will block if the stream write queue is full
|
|
due to internal flow control conditions.
|
|
For high-priority messages,
|
|
\f4putmsg\f1() does not block on this condition.
|
|
For other messages,
|
|
\f4putmsg\f1() does not block when the write queue is full and
|
|
\f4O_NDELAY\f1 or \f4O_NONBLOCK\f1 is set.
|
|
Instead, it fails and sets
|
|
\f4errno\f1 to \f4EAGAIN\f1.
|
|
.PP
|
|
\f4putmsg\fP or \f4putpmsg\fP also blocks,
|
|
unless prevented by lack of internal resources, waiting
|
|
for the availability of message blocks in the stream, regardless of priority
|
|
or whether \f4O_NDELAY\fP or \f4O_NONBLOCK\fP has been specified.
|
|
No partial message is sent.
|
|
.PP
|
|
\f4putmsg\fP fails if one or more of the following are true:
|
|
.TP 13
|
|
\f4EACCES\fP
|
|
\f2fildes\fP is open to a dynamic device, and write permission on the device
|
|
is denied.
|
|
.TP 13
|
|
\f4EAGAIN\fP
|
|
A non-priority message was specified, the \f4O_NDELAY\fP or \f4O_NONBLOCK\fP flag is
|
|
set and the stream write queue is full due to internal flow control conditions.
|
|
.TP
|
|
\f4EBADF\fP
|
|
\f2fd\f1 is not a valid file descriptor open for writing.
|
|
.TP
|
|
\f4EFAULT\fP
|
|
\f2ctlptr\f1 or \f2dataptr\f1 points outside the allocated address space.
|
|
.TP
|
|
\f4EINTR\fP
|
|
A signal was caught during the \f4putmsg\fP system call.
|
|
.TP
|
|
\f4EINVAL\fP
|
|
An undefined value was specified in \f2flags\f1,
|
|
or \f2flags\f1 is set to \f4RS_HIPRI\fP and no control part was supplied.
|
|
.TP
|
|
\f4EINVAL\fP
|
|
The stream referenced by \f2fd\f1 is linked below a multiplexor.
|
|
.TP
|
|
\f4EINVAL\fP
|
|
For \f4putpmsg\fP, if \f2flags\f1 is set to \f4MSG_HIPRI\f1 and \f2band\f1 is
|
|
nonzero.
|
|
.TP
|
|
\f4EIO\fP
|
|
\f2fildes\fP is open to a device that is in the process of closing, or
|
|
the other end of the pipe is closed.
|
|
.TP
|
|
\f4ENOSR\fP
|
|
Buffers could not be allocated for the message that was to be created
|
|
due to insufficient \s-1STREAMS\s0 memory resources.
|
|
.TP
|
|
\f4ENOSTR\fP
|
|
A stream is not associated with \f2fd\f1.
|
|
.TP
|
|
\f4ENXIO\fP
|
|
A hangup condition was generated downstream for the specified stream.
|
|
.TP
|
|
\f4ERANGE\fP
|
|
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
|
|
stream 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 a message is larger than
|
|
the maximum configured size of the data part of a message.
|
|
.PP
|
|
\f4putmsg\fP also fails if a \s-1STREAMS\s0 error message had been processed
|
|
by the stream head before the call to \f4putmsg\fP.
|
|
The error returned is the value contained in the \s-1STREAMS\s0 error
|
|
message.
|
|
.SH "SEE ALSO"
|
|
\f4getmsg\fP(2), \f4intro\fP(2), \f4poll\fP(2), \f4putmsg\fP(2),
|
|
\f4read\fP(2), \f4write\fP(2)
|
|
.SH DIAGNOSTICS
|
|
Upon successful completion, a value of 0 is returned.
|
|
Otherwise, a value of \-1 is returned and \f4errno\f1
|
|
is set to indicate the error.
|
|
.Ee
|