| blob | befe47742b543e07803154793039fa35dc300f00 |
1 .\" $NetBSD: mbuf.9,v 1.48 2008/05/31 16:24:59 enami Exp $
2 .\"
3 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This documentation is derived from text contributed to The NetBSD Foundation
7 .\" by S.P.Zeidler (aka stargazer).
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd March 24, 2008
31 .Dt MBUF 9
32 .Os
33 .Sh NAME
34 .Nm mbuf ,
35 .Nm m_get ,
36 .Nm m_getclr ,
37 .Nm m_gethdr ,
38 .Nm m_devget ,
39 .Nm m_copym ,
40 .Nm m_copypacket ,
41 .Nm m_copydata ,
42 .Nm m_copyback ,
43 .Nm m_copyback_cow ,
44 .Nm m_cat ,
45 .Nm m_dup ,
46 .Nm m_makewritable ,
47 .Nm m_prepend ,
48 .Nm m_pulldown ,
49 .Nm m_pullup ,
50 .Nm m_split ,
51 .Nm m_adj ,
52 .Nm m_apply ,
53 .Nm m_free ,
54 .Nm m_freem ,
55 .Nm mtod ,
56 .Nm MGET ,
57 .Nm MGETHDR ,
58 .Nm MEXTMALLOC ,
59 .Nm MEXTADD ,
60 .Nm MCLGET ,
61 .Nm M_COPY_PKTHDR ,
62 .Nm M_MOVE_PKTHDR ,
63 .Nm M_ALIGN ,
64 .Nm MH_ALIGN ,
65 .Nm M_LEADINGSPACE ,
66 .Nm M_TRAILINGSPACE ,
67 .Nm M_PREPEND ,
68 .Nm MCHTYPE ,
69 .Nm MFREE
70 .Nd "functions and macros for managing memory used by networking code"
71 .Sh SYNOPSIS
72 .In sys/mbuf.h
73 .Ft struct mbuf *
74 .Fn m_get "int nowait" "int type"
75 .Ft struct mbuf *
76 .Fn m_getclr "int nowait" "int type"
77 .Ft struct mbuf *
78 .Fn m_gethdr "int nowait" "int type"
79 .Ft struct mbuf *
80 .Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy)(const void *, void *, size_t)"
81 .Ft struct mbuf *
82 .Fn m_copym "struct mbuf *m" "int off0" "int len" "int wait"
83 .Ft struct mbuf *
84 .Fn m_copypacket "struct mbuf *m" "int how"
85 .Ft void
86 .Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp"
87 .Ft void
88 .Fn m_copyback "struct mbuf *m0" "int off" "int len" "void *cp"
89 .Ft struct mbuf *
90 .Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "void *cp" "int how"
91 .Ft int
92 .Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how"
93 .Ft void
94 .Fn m_cat "struct mbuf *m" "struct mbuf *n"
95 .Ft struct mbuf *
96 .Fn m_dup "struct mbuf *m" "int off0" "int len" "int wait"
97 .Ft struct mbuf *
98 .Fn m_prepend "struct mbuf *m" "int len" "int how"
99 .Ft struct mbuf *
100 .Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp"
101 .Ft struct mbuf *
102 .Fn m_pullup "struct mbuf *n" "int len"
103 .Ft struct mbuf *
104 .Fn m_split "struct mbuf *m0" "int len0" "int wait"
105 .Ft void
106 .Fn m_adj "struct mbuf *mp" "int req_len"
107 .Ft int
108 .Fn m_apply "struct mbuf *m" "int off" "int len" "int *f(void *, void *, unsigned int)" "void *arg"
109 .Ft struct mbuf *
110 .Fn m_free "struct mbuf *m"
111 .Ft void
112 .Fn m_freem "struct mbuf *m"
113 .Ft datatype
114 .Fn mtod "struct mbuf *m" "datatype"
115 .Ft void
116 .Fn MGET "struct mbuf *m" "int how" "int type"
117 .Ft void
118 .Fn MGETHDR "struct mbuf *m" "int how" "int type"
119 .Ft void
120 .Fn MEXTMALLOC "struct mbuf *m" "int len" "int how"
121 .Ft void
122 .Fn MEXTADD "struct mbuf *m" "void *buf" "int size" "int type" "void (*free)(struct mbuf *, void *, size_t, void *)" "void *arg"
123 .Ft void
124 .Fn MCLGET "struct mbuf *m" "int how"
125 .Ft void
126 .Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from"
127 .Ft void
128 .Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from"
129 .Ft void
130 .Fn M_ALIGN "struct mbuf *m" "int len"
131 .Ft void
132 .Fn MH_ALIGN "struct mbuf *m" "int len"
133 .Ft int
134 .Fn M_LEADINGSPACE "struct mbuf *m"
135 .Ft int
136 .Fn M_TRAILINGSPACE "struct mbuf *m"
137 .Ft void
138 .Fn M_PREPEND "struct mbuf *m" "int plen" "int how"
139 .Ft void
140 .Fn MCHTYPE "struct mbuf *m" "int type"
141 .Ft void
142 .Fn MFREE "struct mbuf *m" "struct mbuf *n"
143 .Sh DESCRIPTION
144 The
145 .Nm
146 functions and macros provide an easy and consistent way to handle
147 a networking stack's memory management needs.
148 An
149 .Nm
150 consists of a header and a data area.
151 It is of a fixed size,
152 .Dv MSIZE
153 .Pq defined in Aq Pa machine/param.h ,
154 which includes overhead.
155 The header contains a pointer to the next
156 .Nm
157 in the
158 .Sq "mbuf chain" ,
159 a pointer to the next
160 .Sq "mbuf chain" ,
161 a pointer to the data area, the amount of data in this mbuf, its type
162 and a
163 .Dv flags
164 field.
165 .Pp
166 The
167 .Dv type
168 variable can signify:
169 .Bl -tag -compact -offset indent -width "XXXXXXXXXXX"
170 .It Dv MT_FREE
171 the mbuf should be on the ``free'' list
172 .It Dv MT_DATA
173 data was dynamically allocated
174 .It Dv MT_HEADER
175 data is a packet header
176 .It Dv MT_SONAME
177 data is a socket name
178 .It Dv MT_SOOPTS
179 data is socket options
180 .It Dv MT_FTABLE
181 data is the fragment reassembly header
182 .It Dv MT_CONTROL
183 mbuf contains ancillary \&(protocol control\&) data
184 .It Dv MT_OOBDATA
185 mbuf contains out-of-band data.
186 .El
187 .Pp
188 The
189 .Dv flags
190 variable contains information describing the
191 .Nm ,
192 notably:
193 .Bl -tag -compact -offset indent -width "XXXXXXXXXXX"
194 .It Dv M_EXT
195 has external storage
196 .It Dv M_PKTHDR
197 is start of record
198 .It Dv M_EOR
199 is end of record
200 .It Dv M_CLUSTER
201 external storage is a cluster.
202 .El
203 .Pp
204 If an
205 .Nm
206 designates the start of a record
207 .Pq Dv M_PKTHDR ,
208 its
209 .Dv flags
210 field may contain additional information describing the content of
211 the record:
212 .Bl -tag -compact -offset indent -width "XXXXXXXXXXX"
213 .It Dv M_BCAST
214 sent/received as link-level broadcast
215 .It Dv M_MCAST
216 sent/received as link-level multicast
217 .It Dv M_LINK0 ,
218 .It Dv M_LINK1 ,
219 .It Dv M_LINK2
220 three link-level specific flags.
221 .El
222 .Pp
223 An
224 .Nm
225 may add a single
226 .Sq "mbuf cluster"
227 of
228 .Dv MCLBYTES
229 bytes
230 .Pq also defined in Aq Pa machine/param.h ,
231 which has no additional overhead
232 and is used instead of the internal data area; this is done when at least
233 .Dv MINCLSIZE
234 bytes of data must be stored.
235 .Pp
236 When the
237 .Dv M_EXT
238 flag is raised for an mbuf,
239 the external storage area could be shared among multiple mbufs.
240 Be careful when you attempt to overwrite the data content of the mbuf.
241 .Bl -tag -width compact
242 .It Fn m_get "int nowait" "int type"
243 Allocates an mbuf and initializes it to contain internal data.
244 The
245 .Fa nowait
246 parameter is a choice of
247 .Dv M_WAIT / M_DONTWAIT
248 from caller.
249 .Dv M_WAIT
250 means the call cannot fail, but may take forever.
251 The
252 .Fa type
253 parameter is an mbuf type.
254 .It Fn m_getclr "int nowait" "int type"
255 Allocates an mbuf and initializes it to contain internal data, then
256 zeros the data area.
257 The
258 .Fa nowait
259 parameter is a choice of
260 .Dv M_WAIT / M_DONTWAIT
261 from caller.
262 The
263 .Fa type
264 parameter is an mbuf type.
265 .It Fn m_gethdr "int nowait" "int type"
266 Allocates an mbuf and initializes it to contain a packet header and internal
267 data.
268 The
269 .Fa nowait
270 parameter is a choice of
271 .Dv M_WAIT / M_DONTWAIT
272 from caller.
273 The
274 .Fa type
275 parameter is an mbuf type.
276 .It Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy)(const void *, void *, size_t)"
277 Copies
278 .Fa len
279 bytes from device local memory into mbufs using copy routine
280 .Fa copy .
281 If parameter
282 .Fa off
283 is non-zero, the packet is supposed to be trailer-encapsulated and
284 .Fa off
285 bytes plus the type and length fields will be skipped before copying.
286 Returns the top of the mbuf chain it created.
287 .It Fn m_copym "struct mbuf *m" "int off0" "int len" "int wait"
288 Creates a copy of an mbuf chain starting
289 .Fa off0
290 bytes from the beginning, continuing for
291 .Fa len
292 bytes.
293 If the
294 .Fa len
295 requested is
296 .Dv M_COPYALL ,
297 the complete mbuf chain will be copied.
298 The
299 .Fa wait
300 parameter is a choice of
301 .Dv M_WAIT / M_DONTWAIT
302 from caller.
303 .It Fn m_copypacket "struct mbuf *m" "int how"
304 Copies an entire packet, including header (which must be present).
305 This function is an optimization of the common case
306 .Li m_copym(m, 0, Dv M_COPYALL, Fa how ) .
307 .It Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp"
308 Copies
309 .Fa len
310 bytes data from mbuf chain
311 .Fa m
312 into the buffer
313 .Fa cp ,
314 starting
315 .Fa off
316 bytes from the beginning.
317 .It Fn m_copyback "struct mbuf *m0" "int off" "int len" "void *cp"
318 Copies
319 .Fa len
320 bytes data from buffer
321 .Fa cp
322 back into the mbuf chain
323 .Fa m0 ,
324 starting
325 .Fa off
326 bytes from the beginning of the chain, extending the mbuf chain if necessary.
327 .Fn m_copyback
328 can only fail when extending the chain.
329 The caller should check for this kind of failure
330 by checking the resulting length of the chain in that case.
331 It is an error to use
332 .Fn m_copyback
333 on read-only mbufs.
334 .It Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "void *cp" \
335 "int how"
336 Copies
337 .Fa len
338 bytes data from buffer
339 .Fa cp
340 back into the mbuf chain
341 .Fa m0
342 as
343 .Fn m_copyback
344 does.
345 Unlike
346 .Fn m_copyback ,
347 it is safe to use
348 .Fn m_copyback_cow
349 on read-only mbufs.
350 If needed,
351 .Fn m_copyback_cow
352 automatically allocates new mbufs and adjusts the chain.
353 On success, it returns a pointer to the resulting mbuf chain,
354 and frees the original mbuf
355 .Fa m0 .
356 Otherwise, it returns
357 .Dv NULL .
358 The
359 .Fa how
360 parameter is a choice of
361 .Dv M_WAIT / M_DONTWAIT
362 from the caller.
363 Unlike
364 .Fn m_copyback ,
365 extending the mbuf chain isn't supported.
366 It is an error to attempt to extend the mbuf chain using
367 .Fn m_copyback_cow .
368 .It Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how"
369 Rearranges an mbuf chain so that
370 .Fa len
371 bytes from offset
372 .Fa off
373 are writable.
374 When it meets read-only mbufs, it allocates new mbufs, adjusts the chain as
375 .Fn m_copyback_cow
376 does, and copies the original content into them.
377 .Fn m_makewritable
378 does
379 .Em not
380 guarantee that all
381 .Fa len
382 bytes at
383 .Fa off
384 are consecutive.
385 The
386 .Fa how
387 parameter is a choice of
388 .Dv M_WAIT / M_DONTWAIT
389 from the caller.
390 .Fn m_makewritable
391 preserves the contents of the mbuf chain even in the case of failure.
392 It updates a pointer to the mbuf chain pointed to by
393 .Fa mp .
394 It returns 0 on success.
395 Otherwise, it returns an error code, typically
396 .Er ENOBUFS .
397 .It Fn m_cat "struct mbuf *m" "struct mbuf *n"
398 Concatenates mbuf chain
399 .Fa n
400 to
401 .Fa m .
402 Both chains must be of the same type; packet headers will
403 .Em not
404 be updated if present.
405 .It Fn m_dup "struct mbuf *m" "int off0" "int len" "int wait"
406 Similarly to
407 .Fn m_copym ,
408 the function creates a copy of an mbuf chain starting
409 .Fa off0
410 bytes from the beginning, continuing for
411 .Fa len
412 bytes.
413 While
414 .Fn m_copym
415 tries to share external storage for mbufs with
416 .Dv M_EXT
417 flag,
418 .Fn m_dup
419 will deep-copy the whole data content into new mbuf chain
420 and avoids shared external storage.
421 .It Fn m_prepend "struct mbuf *m" "int len" "int how"
422 Lesser-used path for
423 .Fn M_PREPEND :
424 allocates new mbuf
425 .Fa m
426 of size
427 .Fa len
428 to prepend to the chain, copying junk along.
429 The
430 .Fa how
431 parameter is a choice of
432 .Dv M_WAIT / M_DONTWAIT
433 from caller.
434 .It Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp"
435 Rearranges an mbuf chain so that
436 .Fa len
437 bytes from offset
438 .Fa off
439 are contiguous and in the data area of an mbuf.
440 The return value points to an mbuf in the middle of the mbuf chain
441 .Fa m .
442 If we call the return value
443 .Fa n ,
444 the contiguous data region is available at
445 .Li "mtod(n, void *) + *offp" ,
446 or
447 .Li "mtod(n, void *)"
448 if
449 .Fa offp
450 is
451 .Dv NULL .
452 The top of the mbuf chain
453 .Fa m ,
454 and mbufs up to
455 .Fa off ,
456 will not be modified.
457 On successful return, it is guaranteed that the mbuf pointed to by
458 .Fa n
459 does not have a shared external storage,
460 therefore it is safe to update the contiguous region.
461 Returns
462 .Dv NULL
463 and frees the mbuf chain on failure.
464 .Fa len
465 must be smaller or equal than
466 .Dv MCLBYTES .
467 .It Fn m_pullup "struct mbuf *m" "int len"
468 Rearranges an mbuf chain so that
469 .Fa len
470 bytes are contiguous
471 and in the data area of an mbuf (so that
472 .Fn mtod
473 will work for a structure of size
474 .Fa len ) .
475 Returns the resulting
476 mbuf chain on success, frees it and returns
477 .Dv NULL
478 on failure.
479 If there is room, it will add up to
480 .Dv max_protohdr
481 -
482 .Fa len
483 extra bytes to the
484 contiguous region to possibly avoid being called again.
485 .Fa len
486 must be smaller or equal than
487 .Dv MHLEN .
488 .It Fn m_split "struct mbuf *m0" "int len0" "int wait"
489 Partitions an mbuf chain in two pieces, returning the tail,
490 which is all but the first
491 .Fa len0
492 bytes.
493 In case of failure, it returns
494 .Dv NULL
495 and attempts to
496 restore the chain to its original state.
497 .It Fn m_adj "struct mbuf *mp" "int req_len"
498 Shaves off
499 .Fa req_len
500 bytes from head or tail of the (valid) data area.
501 If
502 .Fa req_len
503 is greater than zero, front bytes are being shaved off, if it's smaller,
504 from the back (and if it is zero, the mbuf will stay bearded).
505 This function does not move data in any way, but is used to manipulate the
506 data area pointer and data length variable of the mbuf in a non-clobbering
507 way.
508 .It Fn m_apply "struct mbuf *m" "int off" "int len" "int (*f)(void *, void *, unsigned int)" "void *arg"
509 Apply function
510 .Fa f
511 to the data in an mbuf chain starting
512 .Fa off
513 bytes from the beginning, continuing for
514 .Fa len
515 bytes.
516 Neither
517 .Fa off
518 nor
519 .Fa len
520 may be negative.
521 .Fa arg
522 will be supplied as first argument for
523 .Fa f ,
524 the second argument will be the pointer to the data buffer of a
525 packet (starting after
526 .Fa off
527 bytes in the stream), and the third argument is the amount
528 of data in bytes in this call.
529 If
530 .Fa f
531 returns something not equal to zero
532 .Fn m_apply
533 will bail out, returning the return code of
534 .Fa f .
535 Upon successful completion it will return zero.
536 .It Fn m_free "struct mbuf *m"
537 Frees mbuf
538 .Fa m .
539 .It Fn m_freem "struct mbuf *m"
540 Frees the mbuf chain beginning with
541 .Fa m .
542 This function contains the elementary sanity check for a
543 .Dv NULL
544 pointer.
545 .It Fn mtod "struct mbuf *m" "datatype"
546 Returns a pointer to the data contained in the specified mbuf
547 .Fa m ,
548 type-casted to the specified data type
549 .Fa datatype .
550 Implemented as a macro.
551 .It Fn MGET "struct mbuf *m" "int how" "int type"
552 Allocates mbuf
553 .Fa m
554 and initializes it to contain internal data.
555 See
556 .Fn m_get .
557 Implemented as a macro.
558 .It Fn MGETHDR "struct mbuf *m" "int how" "int type"
559 Allocates mbuf
560 .Fa m
561 and initializes it to contain a packet header.
562 See
563 .Fn m_gethdr .
564 Implemented as a macro.
565 .It Fn MEXTMALLOC "struct mbuf *m" "int len" "int how"
566 Allocates external storage of size
567 .Fa len
568 for mbuf
569 .Fa m .
570 The
571 .Fa how
572 parameter is a choice of
573 .Dv M_WAIT / M_DONTWAIT
574 from caller.
575 The flag
576 .Dv M_EXT
577 is set upon success.
578 Implemented as a macro.
579 .It Fn MEXTADD "struct mbuf *m" "void *buf" "int size" "int type" "void (*free)(struct mbuf *, void *, size_t, void *)" "void *arg"
580 Adds pre-allocated external storage
581 .Fa buf
582 to a normal mbuf
583 .Fa m ;
584 the parameters
585 .Fa size ,
586 .Fa type ,
587 .Fa free
588 and
589 .Fa arg
590 describe the external storage.
591 .Fa size
592 is the size of the storage,
593 .Fa type
594 describes its
595 .Xr malloc 9
596 type,
597 .Fa free
598 is a free routine (if not the usual one), and
599 .Fa arg
600 is a possible argument to the free routine.
601 The flag
602 .Dv M_EXT
603 is set upon success.
604 Implemented as a macro.
605 If a free routine is specified, it will be called when the mbuf is freed.
606 In the case of former, the first argument for a free routine is the mbuf
607 .Fa m
608 and the routine is expected to free it in addition to the external storage
609 pointed by second argument.
610 In the case of latter, the first argument for the routine is NULL.
611 .It Fn MCLGET "struct mbuf *m" "int how"
612 Allocates and adds an mbuf cluster to a normal mbuf
613 .Fa m .
614 The
615 .Fa how
616 parameter is a choice of
617 .Dv M_WAIT / M_DONTWAIT
618 from caller.
619 The flag
620 .Dv M_EXT
621 is set upon success.
622 Implemented as a macro.
623 .It Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from"
624 Copies the mbuf pkthdr from mbuf
625 .Fa from
626 to mbuf
627 .Fa to .
628 .Fa from
629 must have the type flag
630 .Dv M_PKTHDR
631 set, and
632 .Fa to
633 must be empty.
634 Implemented as a macro.
635 .It Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from"
636 Moves the mbuf pkthdr from mbuf
637 .Fa from
638 to mbuf
639 .Fa to .
640 .Fa from
641 must have the type flag
642 .Dv M_PKTHDR
643 set, and
644 .Fa to
645 must be empty.
646 The flag
647 .Dv M_PKTHDR
648 in mbuf
649 .Fa from
650 will be cleared.
651 .It Fn M_ALIGN "struct mbuf *m" "int len"
652 Sets the data pointer of a newly allocated mbuf
653 .Fa m
654 to
655 .Fa len
656 bytes from the end of the mbuf data area, so that
657 .Fa len
658 bytes of data written to the mbuf
659 .Fa m ,
660 starting at the data pointer, will be aligned to the end of the data area.
661 Implemented as a macro.
662 .It Fn MH_ALIGN "struct mbuf *m" "int len"
663 Sets the data pointer of a newly allocated packetheader mbuf
664 .Fa m
665 to
666 .Fa len
667 bytes from the end of the mbuf data area, so that
668 .Fa len
669 bytes of data written to the mbuf
670 .Fa m ,
671 starting at the data pointer, will be aligned to the end of the data area.
672 Implemented as a macro.
673 .It Fn M_LEADINGSPACE "struct mbuf *m"
674 Returns the amount of space available before the current start of valid
675 data in mbuf
676 .Fa m .
677 Returns 0 if the mbuf data part is shared across multiple mbufs
678 .Pq i.e. not writable .
679 Implemented as a macro.
680 .It Fn M_TRAILINGSPACE "struct mbuf *m"
681 Returns the amount of space available after the current end of valid
682 data in mbuf
683 .Fa m .
684 Returns 0 if the mbuf data part is shared across multiple mbufs
685 .Pq i.e. not writable .
686 Implemented as a macro.
687 .It Fn M_PREPEND "struct mbuf *m" "int plen" "int how"
688 Prepends space of size
689 .Fa plen
690 to mbuf
691 .Fa m .
692 If a new mbuf must be allocated,
693 .Fa how
694 specifies whether to wait.
695 If
696 .Fa how
697 is
698 .Dv M_DONTWAIT
699 and allocation fails, the original mbuf chain is freed and
700 .Fa m
701 is set to
702 .Dv NULL .
703 Implemented as a macro.
704 .It Fn MCHTYPE "struct mbuf *m" "int type"
705 Change mbuf
706 .Fa m
707 to new type
708 .Fa type .
709 Implemented as a macro.
710 .It Fn MFREE "struct mbuf *m" "struct mbuf *n"
711 Frees a single mbuf
712 .Fa m
713 and places the successor, if any, in mbuf
714 .Fa n .
715 Implemented as a macro.
716 .El
717 .Sh FILES
718 The
719 .Nm
720 management functions are implemented within the file
721 .Pa sys/kern/uipc_mbuf.c .
722 Function prototypes, and the functions implemented as macros
723 are located in
724 .Pa sys/sys/mbuf.h .
725 Both pathnames are relative to the root of the
726 .Nx
727 source tree,
728 .Pa /usr/src .
729 .Sh SEE ALSO
730 .Pa /usr/share/doc/smm/18.net ,
731 .Xr netstat 1 ,
732 .Xr m_tag 9 ,
733 .Xr malloc 9
734 .Rs
735 .%A Jun-ichiro Hagino
736 .%T "Mbuf issues in 4.4BSD IPv6/IPsec support (experiences from KAME IPv6/IPsec implementation)"
737 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
738 .%D June 2000
739 .Re
740 .Sh AUTHORS
741 .An -nosplit
742 The original mbuf data structures were designed by Rob Gurwitz
743 when he did the initial TCP/IP implementation at BBN.
744 .Pp
745 Further extensions and enhancements were made by Bill Joy, Sam Leffler,
746 and Mike Karels at CSRG.
747 .Pp
748 Current implementation of external storage by
749 .An Matt Thomas
750 .Aq matt@3am-software.com
751 and
752 .An Jason R. Thorpe
753 .Aq thorpej@NetBSD.org .