'\"macro stdmacro
.if n .pH ddi_dki.put @(#)put	40.5 of 10/10/89
.\" Copyright 1989 AT&T
.de IX
.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.nr X
.if \nX=0 .ds x} put D2DK "STREAMS" "DDI/DKI" "\&"
.if \nX=1 .ds x} put D2DK "STREAMS" "DDI/DKI"
.if \nX=2 .ds x} put D2DK "" "\&"
.if \nX=3 .ds x} put "" "" "\&"
.TH \*(x}
.IX "\f4put\fP(D2DK)"
.SH "NAME
\f4put\f1 \- receive messages from the preceding queue
.SH "SYNOPSIS"
.nf
.na
\f4#include <sys/types.h>
#include <sys/stream.h>
#include <sys/stropts.h>
.sp 0.5
void \f2prefix\f4rput(\f4queue_t *\f1\f2q, \f4mblk_t\f1 \f2mp\f4);  /* read side */
.sp 0.5
void \f2prefix\f4wput(\f4queue_t *\f1\f2q, \f4mblk_t\f1 \f2mp\f4);  /* write side */
.ad
.fi
.SH "ARGUMENTS"
.RS 0n 5n
.IP "\f2*q\f1" 10n
Pointer to the \f4queue\f1(D4DK) structure.
.IP "\f2mp\f1" 10n
Pointer to the message block.
.RE
.SH "DESCRIPTION"
The primary task of the \f4put\f1 routine is to coordinate the 
passing of messages from one queue to the next in a stream.  
The \f4put\f1 routine is called by the preceding stream component (module,
driver, or stream head).
\f4put\f1 routines are designated ``write'' or ``read'' depending on
the direction of message flow.
.P
With few exceptions, a module or driver must
have a \f4put\f1 routine.
One exception is the read side of a driver, which does not need a
\f4put\f1 routine because there is no component downstream to call it.
The \f4put\f1 routine is always called before the component's corresponding
\f4srv\f1(D2DK) (service) routine, and so \f4put\f1 
should be used for the  immediate
processing of messages.
.P
A \f4put\f1 routine must do at least one of the following
when it receives a message:
.IP
pass the message to the next component on the stream by calling
the \f4putnext\f1(D3DK) function
.IP
process the message, if immediate processing is required (for
example, high priority messages)
.IP
enqueue the message (with the \f4putq\f1(D3DK) function)
for deferred processing by the service \f4srv\f1(D2DK) routine
.P
Typically, a \f4put\f1 routine will switch on message type, which
is contained in the \f4db_type\f1 member of the \f4datab\f1
structure pointed to by \f2mp\f1.
The action taken by the \f4put\f1 routine depends on the message type.
For example, a \f4put\f1 routine might process high priority messages,
enqueue normal messages, and handle an unrecognized
message by changing its type to \f4M_IOCNAK\f1 (negative acknowledgement)
and sending it back to the stream head using the \f4qreply\f1(D3DK)
function.
.P
The \f4putq\f1(D3DK) function can be used as a
module's \f4put\f1 routine when no special processing is required and all
messages are to be enqueued for the \f4srv\f1 routine.
.P
\f4put\f1 routines do not have user context and so may not call
\f4sleep\f1(D3DK).
.SH "SEE ALSO"
The \f2BCI Driver Development Guide\f1, Chapter 7, ``STREAMS''
.P
The \f2STREAMS Programmer's Guide\f1
.P
.na
\f4streamtab\f1(D4DK),
\f4putctl\f1(D3DK),
\f4putctl1\f1(D3DK),
\f4putnext\f1(D3DK),
\f4putq\f1(D3DK),
\f4qreply\f1(D3DK),
\f4srv\f1(D2DK)
.ad
