1.\" $OpenBSD: ml_init.9,v 1.13 2016/04/15 05:05:21 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: April 15 2016 $ 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_enlist , 25.Nm ml_dechain , 26.Nm ml_len , 27.Nm ml_empty , 28.Nm ml_purge , 29.Nm MBUF_LIST_INITIALIZER , 30.Nm MBUF_LIST_FIRST , 31.Nm MBUF_LIST_NEXT , 32.Nm MBUF_LIST_FOREACH 33.Nd mbuf list API 34.Sh SYNOPSIS 35.In sys/mbuf.h 36.Ft void 37.Fn ml_init "struct mbuf_list *ml" 38.Ft void 39.Fn ml_enqueue "struct mbuf_list *ml" "struct mbuf *m" 40.Ft struct mbuf * 41.Fn ml_dequeue "struct mbuf_list *ml" 42.Ft void 43.Fn ml_enlist "struct mbuf_list *ml" "struct mbuf_list *src" 44.Ft struct mbuf * 45.Fn ml_dechain "struct mbuf_list *ml" 46.Ft unsigned int 47.Fn ml_len "struct mbuf_list *ml" 48.Ft int 49.Fn ml_empty "struct mbuf_list *ml" 50.Ft unsigned int 51.Fn ml_purge "struct mbuf_list *ml" 52.Ft struct mbuf_list 53.Fn MBUF_LIST_INITIALIZER 54.Ft struct mbuf * 55.Fn MBUF_LIST_FIRST "struct mbuf_list *ml" 56.Ft struct mbuf * 57.Fn MBUF_LIST_NEXT "struct mbuf *m" 58.Fn MBUF_LIST_FOREACH "struct mbuf_list *ml" "VARNAME" 59.Sh DESCRIPTION 60The mbuf list API provides implementations of data structures and operations 61for managing lists of mbufs between contexts. 62.Pp 63mbuf_list structures support the following functionality: 64.Pp 65.Bl -enum -compact -offset indent 66.It 67Insertion of a new mbuf at the end of the list. 68.It 69Removal of an mbuf from the head of 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_enlist "struct mbuf_list *ml" "struct mbuf_list *src" 89Enqueue all the mbufs on the 90.Fa src 91mbuf list on to the end 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 Fn ml_len "struct mbuf_list *ml" 99Return the number of mbufs on the 100.Fa ml 101mbuf list. 102.It Fn ml_empty "struct mbuf_list *ml" 103Return if the 104.Fa ml 105mbuf list is empty. 106.It Fn ml_purge "struct mbuf_list *ml" 107Free all the mbufs on the 108.Fa ml 109mbuf list. 110.It Fn MBUF_LIST_FIRST "struct mbuf_list *ml" 111Access the first mbuf in the 112.Fa ml 113mbuf list for traversal. 114.It Fn MBUF_LIST_NEXT "struct mbuf *m" 115Access the next mbuf in the mbuf list after 116.Fa m . 117.It Fn MBUF_LIST_FOREACH "struct mbuf_list *ml" "VARNAME" 118A convenience macro that can be used to iterate over the contents of the 119.Fa ml 120mbuf list. 121.Fa VARNAME 122identifies the name (not the address) of an mbuf pointer that will 123be set to each entry on the list. 124Note that it is unsafe to modify the list while iterating over it. 125.El 126.Sh CONTEXT 127.Fn ml_init , 128.Fn ml_enqueue , 129.Fn ml_dequeue , 130.Fn ml_enlist , 131.Fn ml_dechain , 132.Fn ml_len , 133.Fn ml_empty , 134.Fn ml_purge , 135.Fn MBUF_LIST_INITIALIZER , 136.Fn MBUF_LIST_FIRST , 137.Fn MBUF_LIST_NEXT , 138and 139.Fn MBUF_LIST_FOREACH 140can be called during autoconf, from process context, or from interrupt context. 141.Sh RETURN VALUES 142.Fn ml_dequeue 143returns the mbuf that was at the head of its list. 144If the list was empty, 145.Dv NULL 146is returned. 147.Pp 148.Fn ml_dechain 149returns all the mbufs that were on the list via 150a pointer to an mbuf with the chain accessible via m_nextpkt members. 151If the list was empty, 152.Dv NULL 153is returned. 154.Pp 155.Fn ml_len 156returns the number of mbufs on the list. 157.Pp 158.Fn ml_empty 159return a non-zero value if the list is empty, otherwise 0. 160.Pp 161.Fn ml_purge 162returns the number of mbufs that were freed. 163.Pp 164.Fn MBUF_LIST_FIRST 165returns the first mbuf in the mbuf list, or 166.Dv NULL 167if the list is empty. 168.Pp 169.Fn MBUF_LIST_NEXT 170returns the next mbuf in the mbuf list, or 171.Dv NULL 172if the end of the list has been reached. 173.Sh SEE ALSO 174.Xr mbuf 9 175