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