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 60The 61.Nm 62system is a framework to manage queueing disciplines on network 63interfaces. 64.Nm 65introduces new functions to manipulate output queues. 66The output queue functions are used to abstract queue operations and not to 67touch the internal fields of the output queue structure. 68.Pp 69.Fn ifq_enqueue 70and 71.Fn ifq_handoff 72enqueue a packet 73.Fa _m 74to the queue 75.Fa _ifq . 76The underlying queueing discipline may discard the packet. 77They return 0 on success, or 78.Er ENOBUFS 79if the packet is discarded. 80The packet pointed to by 81.Fa _m 82will be freed by the device driver on success or by the queueing discipline on 83failure, so that the caller should not touch 84.Fa _m 85after calling 86.Fn ifq_enqueue . 87.Fn ifq_handoff 88combines the enqueue operation with statistic generation and calls 89.Fn if_start 90upon successful enqueue to initiate the actual send. 91.Pp 92.Fn ifq_dequeue 93dequeues a packet from the queue. 94It returns the dequeued packet, or 95.Dv NULL 96if no packet is dequeued. 97The caller must always check the return value 98since a non-empty queue could return 99.Dv NULL 100under rate-limiting. 101.Pp 102.Fn ifq_poll 103returns the next packet without removing it from the queue. 104It is guaranteed by the underlying queueing discipline that 105.Fn ifq_dequeue 106immediately after 107.Fn ifq_poll 108returns the same packet. 109.Pp 110.Fn ifq_purge 111discards all the packets in the queue. 112The purge operation is needed since a non-work conserving queue cannot be 113emptied by a dequeue loop. 114.Pp 115.Fn ifq_classify 116classifies a packet to a scheduling class, and returns the result in 117.Fa _pa . 118.Pp 119.Fn ifq_is_empty 120can be used to check if the queue is empty. 121Note that 122.Fn ifq_dequeue 123could still return 124.Dv NULL 125if the queueing discipline is non-work conserving. 126.Pp 127.Fn ifq_set_maxlen 128sets the queue length limit to the default FIFO queue. 129.Pp 130.Fn ifq_set_ready 131sets a flag to indicate that this driver is converted to use the new macros. 132.Nm 133can be enabled only on interfaces with this flag. 134.Pp 135.Fn ifq_is_enabled 136returns 1 if 137.Nm 138is enabled for the queue, 0 if not. 139.Sh QUEUEING DISCIPLINES 140Queueing disciplines need to maintain 141.Fa ifq_len 142.Po 143used by 144.Fn ifq_is_empty 145.Pc . 146Queueing disciplines also need to guarantee that the same mbuf is returned if 147.Fn ifq_dequeue 148is 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 156The 157.Nm 158system first appeared in March 1997 and was imported into 159.Dx 1.1 . 160