1.\" $OpenBSD: ml_init.9,v 1.2 2015/08/14 05:25:29 dlg Exp $ 2.\" 3.\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: August 14 2015 $ 18.Dt ML_INIT 9 19.Os 20.Sh NAME 21.Nm ml_init , 22.Nm ml_enqueue , 23.Nm ml_dequeue , 24.Nm ml_requeue , 25.Nm ml_dechain , 26.Nm ml_len , 27.Nm ml_empty , 28.Nm MBUF_LIST_INITIALIZER , 29.Nm MBUF_LIST_FOREACH , 30.Nd mbuf list API 31.Sh SYNOPSIS 32.In sys/mbuf.h 33.Fn "ml_init" "struct mbuf_list *ml" 34.Ft void 35.Fn "ml_enqueue" "struct mbuf_list *ml" "struct mbuf *m" 36.Ft struct mbuf * 37.Fn "ml_dequeue" "struct mbuf_list *ml" 38.Ft void 39.Fn "ml_requeue" "struct mbuf_list *ml" "struct mbuf *m" 40.Ft struct mbuf * 41.Fn "ml_dechain" "struct mbuf_list *ml" 42.Ft struct mbuf * 43.Fo ml_filter 44.Fa "struct mbuf_list *ml" 45.Fa "int (*filter)(void *, struct mbuf *)" 46.Fa "void *context" 47.Fc 48.Ft unsigned int 49.Fn "ml_len" "struct mbuf_list *ml" 50.Ft int 51.Fn "ml_empty" "struct mbuf_list *ml" 52.Ft struct mbuf_list 53.Fn "MBUF_LIST_INITIALIZER" 54.Fn "MBUF_LIST_FOREACH" "struct mbuf_list *ml" "VARNAME" 55.Sh DESCRIPTION 56The mbuf list API provides implementions of data structures and operations 57for managing lists of mbufs between contexts. 58.Pp 59mbuf_list structures support the following functionality: 60.Pp 61.Bl -enum -compact -offset indent 62.It 63Insertion of a new mbuf at the end of the list. 64.It 65Removal of an mbuf from the head of the list. 66.It 67Reinsertion of an mbuf at the head of the list. 68.It 69Removal of the entire chain of mbufs on the list. 70.El 71.Bl -tag -width Ds 72.It Fn "ml_init" "struct mbuf_list *ml" 73Initialise the 74.Fa ml 75mbuf_list structure. 76.It Fn "MBUF_LIST_INITIALIZER" 77An initialiser for an mbuf_list structure declaration. 78.It Fn "ml_enqueue" "struct mbuf_list *ml" "struct mbuf *m" 79Enqueue mbuf 80.Fa m 81on the end of the 82.Fa ml 83mbuf list. 84.It Fn "ml_dequeue" "struct mbuf_list *ml" 85Dequeue an mbuf from the front of the 86.Fa ml 87mbuf list. 88.It Fn "ml_requeue" "struct mbuf_list *ml" "struct mbuf *m" 89Enqueue mbuf 90.Fa m 91at the head of the 92.Fa ml 93mbuf list. 94.It Fn "ml_dechain" "struct mbuf_list *ml" 95Dequeues all mbufs from the 96.Fa ml 97mbuf list. 98.It Fo ml_filter 99.Fa "struct mbuf_list *ml" 100.Fa "int (*filter)(void *, struct mbuf *)" 101.Fa "void *context" 102.Fc 103Iterates over the mbufs on the 104.Fa ml 105mbuf list, passing each of them to the 106.Fa filter 107function. 108If the 109.Fa filter 110returns non-zero, the packet is removed from the 111.Fa ml 112mbuf list to be returned as part of an mbuf chain by 113.Fn ml_filter . 114.Fa context 115is passed as the first argument to each call of 116.Fa filter . 117.It Fn "ml_len" "struct mbuf_list *ml" 118Return the number of mbufs on the 119.Fa ml 120mbuf list. 121.It Fn "ml_empty" "struct mbuf_list *ml" 122Return if the 123.Fa ml 124mbuf list is empty. 125.It Fn "MBUF_LIST_FOREACH" "struct mbuf_list *ml" "VARNAME" 126A convenience macro that can be used to iterate over the contents of the 127.Fa ml 128mbuf list. 129.Fa VARNAME 130identifies the name (not the address) of an mbuf pointer that will 131be set to each entry on the list. 132Note that it is unsafe to modify the list while iterating over it. 133.El 134.Sh CONTEXT 135.Fn ml_init , 136.Fn ml_enqueue , 137.Fn ml_dequeue , 138.Fn ml_requeue , 139.Fn ml_dechain , 140.Fn ml_len , 141.Fn ml_empty , 142.Fn MBUF_LIST_INITIALIZER , 143and 144.Fn MBUF_LIST_FOREACH 145can be called during autoconf, from process context, or from interrupt context. 146.Sh RETURN VALUES 147.Fn ml_dequeue 148returns the mbuf that was at the head of its list. 149If the list was empty, 150.Dv NULL 151is returned. 152.Pp 153.Fn ml_dechain 154returns all the mbufs that were on the list via 155a pointer to an mbuf with the chain accessible via m_nextpkt members. 156If the list was empty, 157.Dv NULL 158is returned. 159.Pp 160.Fn ml_filter 161returns the mbufs that were successfully matched by the filter 162function on the list via a pointer to a chain of mbufs. 163If no packets matched the filter, 164.Dv NULL 165is returned. 166.Pp 167.Fn ml_len 168returns the number of mbufs on the list. 169.Pp 170.Fn ml_empty 171return a non-zero value if the list is empty, otherwise 0. 172.Sh SEE ALSO 173.Xr mbuf 9 174