share/man/man9f/bcanput.9f

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (c) 2006, Sun Microsystems, Inc.
   4 .\"  All Rights Reserved
   5 .\" 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.
   6 .\" 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.
   7 .\" 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]
   8 .TH BCANPUT 9F "Jan 16, 2006"
   9 .SH NAME
  10 bcanput \- test for flow control in specified priority band
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/stream.h>
  15
  16
  17
  18 \fBint\fR \fBbcanput\fR(\fBqueue_t *\fR\fIq\fR, \fBunsigned char\fR \fIpri\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Architecture independent level 1 (DDI/DKI).
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIq\fR\fR
  30 .ad
  31 .RS 7n
  32 Pointer to the message queue.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIpri\fR\fR
  39 .ad
  40 .RS 7n
  41 Message priority.
  42 .RE
  43
  44 .SH DESCRIPTION
  45 .sp
  46 .LP
  47 The \fBbcanput()\fR function searches through the stream (starting at \fIq\fR)
  48 until it finds a queue containing a service routine where the message can be
  49 enqueued, or until it reaches the end of the stream. If found, the queue
  50 containing the service routine is tested to see if there is room for a message
  51 of priority \fIpri\fR in the queue.
  52 .sp
  53 .LP
  54 If \fIpri\fR is \fB0\fR, \fBbcanput()\fR is equivalent to a call with
  55 \fBcanput\fR(9F).
  56 .sp
  57 .LP
  58 \fBcanputnext(\fR\fIq\fR\fB)\fR and
  59 \fBbcanputnext(\fR\fIq\fR\fB,\fR\fIpri\fR\fB)\fR should always be used in
  60 preference to \fBcanput(\fR\fIq\fR\fB\(->q_next)\fR and
  61 \fBbcanput(\fR\fIq\fR\fB\(->q_next,\fR\fIpri\fR\fB)\fR respectively.
  62 .SH RETURN VALUES
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fB1\fR\fR
  67 .ad
  68 .RS 5n
  69 If a message of priority \fIpri\fR can be placed on the queue.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fB0\fR\fR
  76 .ad
  77 .RS 5n
  78 If the priority band is full.
  79 .RE
  80
  81 .SH CONTEXT
  82 .sp
  83 .LP
  84 The \fBbcanput()\fR function can be called from user, interrupt, or kernel
  85 context.
  86 .SH SEE ALSO
  87 .sp
  88 .LP
  89 \fBbcanputnext\fR(9F), \fBcanput\fR(9F), \fBcanputnext\fR(9F), \fBputbq\fR(9F),
  90 \fBputnext\fR(9F)
  91 .sp
  92 .LP
  93 \fIWriting Device Drivers\fR
  94 .sp
  95 .LP
  96 \fISTREAMS Programming Guide\fR
  97 .SH WARNINGS
  98 .sp
  99 .LP
 100 Drivers are responsible for both testing a queue with \fBbcanput()\fR and
 101 refraining from placing a message on the queue if \fBbcanput()\fR fails.