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