share/man/man9/altq.9

   1 .\"     $OpenBSD: altq.9,v 1.4 2001/07/12 12:41:42 itojun Exp $
   2 .\"     $NetBSD: altq.9,v 1.14 2007/06/24 19:26:58 rumble Exp $
   3 .\"
   4 .\" Copyright (C) 2001
   5 .\" Sony Computer Science Laboratories Inc.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY SONY CSL AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL SONY CSL OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd November 18, 2007
  29 .Dt ALTQ 9
  30 .Os
  31 .Sh NAME
  32 .Nm ALTQ
  33 .Nd kernel interfaces for manipulating output queues on network interfaces
  34 .Sh SYNOPSIS
  35 .In sys/types.h
  36 .In sys/socket.h
  37 .In net/if.h
  38 .In net/ifq_var.h
  39 .Ft static int
  40 .Fn ifq_enqueue "struct ifaltq *_ifq" "struct mbuf *_m" "struct altq_pktattr *_pa"
  41 .Ft static int
  42 .Fn ifq_handoff "struct ifnet *_ifp" "struct mbuf *_m" "struct altq_pktattr *_pa"
  43 .Ft struct mbuf *
  44 .Fn ifq_dequeue "struct ifaltq *_ifq" "struct mbuf *_mpolled"
  45 .Ft struct mbuf *
  46 .Fn ifq_poll "struct ifaltq *_ifq"
  47 .Ft void
  48 .Fn ifq_purge "struct ifaltq *_ifq"
  49 .Ft void
  50 .Fn ifq_classify "struct ifaltq *_ifq" "struct mbuf *_m" "uint8_t _af" "struct altq_pktattr *_pa"
  51 .Ft int
  52 .Fn ifq_is_empty "struct ifaltq *_ifq"
  53 .Ft void
  54 .Fn ifq_set_maxlen "struct ifaltq *_ifq" "int _len"
  55 .Ft void
  56 .Fn ifq_set_ready "struct ifaltq *_ifq"
  57 .Ft int
  58 .Fn ifq_is_enabled "struct ifaltq *_ifq"
  59 .Sh DESCRIPTION
  60 The
  61 .Nm
  62 system is a framework to manage queueing disciplines on network
  63 interfaces.
  64 .Nm
  65 introduces new functions to manipulate output queues.
  66 The output queue functions are used to abstract queue operations and not to
  67 touch the internal fields of the output queue structure.
  68 .Pp
  69 .Fn ifq_enqueue
  70 and
  71 .Fn ifq_handoff
  72 enqueue a packet
  73 .Fa _m
  74 to the queue
  75 .Fa _ifq .
  76 The underlying queueing discipline may discard the packet.
  77 They return 0 on success, or
  78 .Er ENOBUFS
  79 if the packet is discarded.
  80 The packet pointed to by
  81 .Fa _m
  82 will be freed by the device driver on success or by the queueing discipline on
  83 failure, so that the caller should not touch
  84 .Fa _m
  85 after calling
  86 .Fn ifq_enqueue .
  87 .Fn ifq_handoff
  88 combines the enqueue operation with statistic generation and calls
  89 .Fn if_start
  90 upon successful enqueue to initiate the actual send.
  91 .Pp
  92 .Fn ifq_dequeue
  93 dequeues a packet from the queue.
  94 It returns the dequeued packet, or
  95 .Dv NULL
  96 if no packet is dequeued.
  97 The caller must always check the return value
  98 since a non-empty queue could return
  99 .Dv NULL
 100 under rate-limiting.
 101 .Pp
 102 .Fn ifq_poll
 103 returns the next packet without removing it from the queue.
 104 It is guaranteed by the underlying queueing discipline that
 105 .Fn ifq_dequeue
 106 immediately after
 107 .Fn ifq_poll
 108 returns the same packet.
 109 .Pp
 110 .Fn ifq_purge
 111 discards all the packets in the queue.
 112 The purge operation is needed since a non-work conserving queue cannot be
 113 emptied by a dequeue loop.
 114 .Pp
 115 .Fn ifq_classify
 116 classifies a packet to a scheduling class, and returns the result in
 117 .Fa _pa .
 118 .Pp
 119 .Fn ifq_is_empty
 120 can be used to check if the queue is empty.
 121 Note that
 122 .Fn ifq_dequeue
 123 could still return
 124 .Dv NULL
 125 if the queueing discipline is non-work conserving.
 126 .Pp
 127 .Fn ifq_set_maxlen
 128 sets the queue length limit to the default FIFO queue.
 129 .Pp
 130 .Fn ifq_set_ready
 131 sets a flag to indicate that this driver is converted to use the new macros.
 132 .Nm
 133 can be enabled only on interfaces with this flag.
 134 .Pp
 135 .Fn ifq_is_enabled
 136 returns 1 if
 137 .Nm
 138 is enabled for the queue, 0 if not.
 139 .Sh QUEUEING DISCIPLINES
 140 Queueing disciplines need to maintain
 141 .Fa ifq_len
 142 .Po
 143 used by
 144 .Fn ifq_is_empty
 145 .Pc .
 146 Queueing disciplines also need to guarantee that the same mbuf is returned if
 147 .Fn ifq_dequeue
 148 is called immediately after
 149 .Fn ifq_poll .
 150 .Sh SEE ALSO
 151 .Xr altq 4 ,
 152 .Xr pf 4 ,
 153 .Xr pf.conf 5 ,
 154 .Xr pfctl 8
 155 .Sh HISTORY
 156 The
 157 .Nm
 158 system first appeared in March 1997 and was imported into
 159 .Dx 1.1 .