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