.TH putmsg() "" "" "System Call (libc)"
.PC "Place a message onto a stream"
.B "#include <stropts.h>"
int putmsg (\fIfd\^\fB, \fIctlptr\^\fB, \fIdataptr\^\fB, \fIflags\^\fB)\fR
\fBint \fIfd\^\fB, \fIflags\^\fB; const struct strbuf *\fIctlptr\^\fB, *\fIdataptr\^\fB;\fR
.PP
.B putmsg()
creates a message from user-specified buffer (or buffers), and sends
the message to a \*(ST file.
The message can contain either a data part, a control part, or both.
The data and control parts to be sent
are distinguished by being placed in separate buffers, as described below.
The semantics of each part are defined by the \*(ST module
that receives the message.
.PP
.I fd
gives a file descriptor that identifies an open stream.
.I ctlptr
and
.I dataptr
each point to a structure of tyupe
.BR strbuf ,
which contains the following members:
.DM
	int len;	/* Length of data */
	void *buf;	/* Pointer to buffer */
.DE
.PP
.I ctlptr
points to the structure that describes the control part (if any)
to be included in the message:
.B buf
points to the buffer wherein the control information resides, and
.B len
gives the number of bytes to be sent.
.PP
Likewise,
.I dataptr
specifies the data (if any) to be included in the message.
.I flags
gives the message's type; it is described in detail below.
.PP
To send the data part of a message,
.I dataptr
must not be NULL, and the value of \fIdataptr\fB.len\fR
must be no less than zero.
To send the control part of a message, the corresponding values must be set for
.IR ctlptr .
.B putmsg()
does not send the data portion of the message if
.I dataptr
is set to NULL or
\fIdataptr\^\fB.len\fR equals \-1;
likewise,
.B putmsg()
does not send the control portion of the message if
.I ctlptr
is NULL or \fIctrlptr\fB.len\fR equals \-1.
.PP
If a control part is specified and
.I flags
equals
.BR RS_HIPRI ,
.B putmsg()
sends a high-priority message.
If no control part is specified and
.I flags
equals
.BR RS_HIPRI ,
.B putmsg()
fails and sets
.B errno
to
.BR EINVAL .
If
.I flags
is set to zero,
.B putmsg()
sends a message of normal priority.
If neither the control part nor the data part is specified, and if
flags is set to zero,
.B putmsg()
sends no message and returns zero.
.PP
The stream head guarantees that the control part of a message generated by
.B putmsg()
is at least 64 bytes long.
.PP
.B putmsg()
usually blocks if the
stream head's write queue is full due to internal flow-control
conditions.
For high-priority messages,
.B putmsg()
does not block on this condition.
For other messages,
.B putmsg()
does not block when the write queue is full and you have set the mode on
.I fd
to
.B O_NDELAY
or
.BR O_NONBLOCK .
.B putmsg()
never sends a partial message.
For details on
.B O_NDELAY
and
.BR O_NONBLOCK ,
see the Lexicon entry for
.BR open() .
.PP
Upon successful completion,
.B putmsg()
returns zero.
If something goes wrong,
.B putmsg()
returns \-1 and sets
.B errno
to an appropriate value.
.B putmsg()
fails if any of the following conditions is true:
.IP \(bu 0.3i
A non-priority message was specified, the mode on
.I fd
was set to
.B O_NDELAY
or
.BR O_NONBLOCK ,
and the stream-write queue is full due to internal flow-control conditions.
.B putmsg()
sets
.B errno
to
.BR EAGAIN .
.IP \(bu
.I fd
is not a valid file descriptor.
.B putmsg()
sets
.B errno
to
.BR EBADF .
.IP \(bu
.I ctlptr
or
.I dataptr
contains an illegal address.
.B putmsg()
sets
.B errno
to
.BR EFAULT .
.IP \(bu
Your application caught a signal while it was executing
.BR putmsg() .
.B putmsg()
sets
.B errno
to
.BR EINTR .
.IP \(bu
.I flags
contains an undefined value, or you set
.I flags
.B RS_HIPRI
but did not supply a control part.
.B putmsg()
sets
.B errno
to
.BR EINVAL .
.IP \(bu
The stream referenced by
.I fd
is linked below a multiplexor.
.B putmsg()
sets
.B errno
to
.BR EINVAL .
.IP \(bu
.B putmsg()
could not allocate buffers for the message it was to send
due to insufficient \*(ST memory resources.
.B putmsg()
sets
.B errno
to
.BR ENOSR .
.IP \(bu
.I fd
does not identify a stream.
.B putmsg()
sets
.B errno
to
.BR ENOSTR .
.IP \(bu
A hangup condition was generated downstream for the
specified stream, or the other end of the pipe is closed.
.B putmsg()
sets
.B errno
to
.BR ENXIO .
.IP \(bu
The size of the message's data portion does not fall
within range of legal packet sizes set by topmost stream module,
or its control portion exceeds the maximum configured size.
.B putmsg()
sets
.B errno
to
.BR ERANGE .
.PP
.B putmsg()
also fails if a \*(ST error message had been processed by
the stream head before the call to
.B putmsg()
was executed.
.B putmsg()
returns the 
the value contained in the \*(ST error message.
.SH "See Also"
.Xr "getmsg()," getmsg
.Xr "libc," libc
.Xr "STREAMS" streams
