'\"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