usr/src/man/man9e/put.9e

   1 '\" te
   2 .\" Copyright (c) 1992, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH PUT 9E "Nov 12, 1992"
   8 .SH NAME
   9 put \- receive messages from the preceding queue
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/stream.h>
  15 #include <sys/stropts.h>
  16 #include <sys/ddi.h>
  17 #include <sys/sunddi.h>
  18
  19
  20
  21 \fBint prefix\fR\fBrput\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t\fR \fI*mp\fR/* read side */
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint prefix\fR\fBwput\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t\fR \fI*mp\fR/* write side */
  27 .fi
  28
  29 .SH INTERFACE LEVEL
  30 .sp
  31 .LP
  32 Architecture independent level 1 (DDI/DKI). This entry point is required for
  33 \fBSTREAMS. \fR
  34 .SH ARGUMENTS
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIq\fR \fR
  39 .ad
  40 .RS 7n
  41 Pointer to the \fBqueue\fR(9S) structure.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fImp\fR \fR
  48 .ad
  49 .RS 7n
  50 Pointer to the message block.
  51 .RE
  52
  53 .SH DESCRIPTION
  54 .sp
  55 .LP
  56 The primary task of the \fBput()\fR routine is to coordinate the passing of
  57 messages from one queue to the next in a stream. The \fBput()\fR routine is
  58 called by the preceding stream component (stream module, driver, or stream
  59 head). \fBput()\fR routines are designated ``write'' or ``read'' depending on
  60 the direction of message flow.
  61 .sp
  62 .LP
  63 With few exceptions, a streams module or driver must have a \fBput()\fR
  64 routine. One exception is the read side of a driver, which does not need a
  65 \fBput()\fR routine because there is no component downstream to call it. The
  66 \fBput()\fR routine is always called before the component's corresponding
  67 \fBsrv\fR(9E) (service) routine, and so \fBput()\fR should be used for the
  68 immediate processing of messages.
  69 .sp
  70 .LP
  71 A \fBput()\fR routine must do at least one of the following when it receives a
  72 message:
  73 .RS +4
  74 .TP
  75 .ie t \(bu
  76 .el o
  77 pass the message to the next component on the stream by calling the
  78 \fBputnext\fR(9F) function;
  79 .RE
  80 .RS +4
  81 .TP
  82 .ie t \(bu
  83 .el o
  84 process the message, if immediate processing is required (for example, to
  85 handle high priority messages); or
  86 .RE
  87 .RS +4
  88 .TP
  89 .ie t \(bu
  90 .el o
  91 enqueue the message (with the \fBputq\fR(9F) function) for deferred processing
  92 by the service \fBsrv\fR(9E) routine.
  93 .RE
  94 .sp
  95 .LP
  96 Typically, a \fBput()\fR routine will switch on message type, which is
  97 contained in the \fBdb_type\fR member of the \fBdatab\fR structure pointed to
  98 by \fImp\fR. The action taken by the \fBput()\fR routine depends on the message
  99 type. For example, a \fBput()\fR routine might process high priority messages,
 100 enqueue normal messages, and handle an unrecognized \fBM_IOCTL\fR message by
 101 changing its type to \fBM_IOCNAK\fR (negative acknowledgement) and sending it
 102 back to the stream head using the \fBqreply\fR(9F) function.
 103 .sp
 104 .LP
 105 The \fBputq\fR(9F) function can be used as a module's \fBput()\fR routine when
 106 no special processing is required and all messages are to be enqueued for the
 107 \fBsrv\fR(9E) routine.
 108 .SH RETURN VALUES
 109 .sp
 110 .LP
 111 Ignored.
 112 .SH CONTEXT
 113 .sp
 114 .LP
 115 \fBput()\fR routines do not have user context.
 116 .SH SEE ALSO
 117 .sp
 118 .LP
 119 \fBsrv\fR(9E), \fBputctl\fR(9F), \fBputctl1\fR(9F), \fBputnext\fR(9F),
 120 \fBputnextctl\fR(9F), \fBputnextctl1\fR(9F), \fBputq\fR(9F), \fBqreply\fR(9F),
 121 \fBqueue\fR(9S), \fBstreamtab\fR(9S)
 122 .sp
 123 .LP
 124 \fIWriting Device Drivers\fR
 125 .sp
 126 .LP
 127 \fISTREAMS Programming Guide\fR