share/man/man9f/canputnext.9f

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  13 .\"
  14 .Dd "April 9, 2016"
  15 .Dt CANPUTNEXT 9F
  16 .Os
  17 .Sh NAME
  18 .Nm canputnext ,
  19 .Nm bcanputnext
  20 .Nd test for room in next message queue
  21 .Sh SYNOPSIS
  22 .In sys/stream.h
  23 .
  24 .Ft int
  25 .Fo canputnext
  26 .Fa "queue_t *q"
  27 .Fc
  28 .
  29 .Ft int
  30 .Fo bcanputnext
  31 .Fa "queue_t *q"
  32 .Fa "unsigned char pri"
  33 .Fc
  34 .
  35 .Sh DESCRIPTION
  36 The
  37 .Fn canputnext
  38 and
  39 .Fn bcanputnext
  40 functions atomically test for available space in the next
  41 linked queue or priority band.
  42 They are preferable to and safer than calling
  43 .Xr canput 9F
  44 and
  45 .Xr bcanput 9F
  46 directly on the queue linked to by
  47 .Fa q Ns No -> Ns Fa q_next .
  48 .Lp
  49 Drivers and modules should call these routines to ensure that room
  50 on the next queue exists before calling
  51 .Xr putnext 9F .
  52 .Sh INTERFACE LEVEL
  53 Architecture independent (DDI/DDK).
  54 .Sh PARAMETERS
  55 .Bl -tag -width Ds
  56 .It Fa q
  57 STREAMS queue.
  58 .It Fa pri
  59 Priority band to test.
  60 .El
  61 .Sh CONTEXT
  62 These functions may be called in user, kernel, or interrupt
  63 context.
  64 .Sh RETURN VALUES
  65 .Bl -tag -width Ds
  66 .It 1
  67 If the next message queue is not full.
  68 .It 0
  69 If the next message queue is full.
  70 .El
  71 .Sh SEE ALSO
  72 .Rs
  73 .%B "STREAMS Programming Guide"
  74 .Re
  75 .Rs
  76 .%B "Writing Device Drivers"
  77 .Re
  78 .Pp
  79 .Xr bcanput 9F ,
  80 .Xr canput 9F ,
  81 .Xr putnext 9F ,