xref: /freebsd/share/man/man9/mbchain.9 (revision fa1b1bbc3fdf52e20325ea2154b34df8cd0d31a1)
1.\" -*- nroff -*-
2.\"
3.\" Copyright (c) 2001 Boris Popov
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
17.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd February 20, 2001
28.Dt MBCHAIN 9
29.Os
30.Sh NAME
31.Nm mbchain ,
32.Nm mb_init ,
33.Nm mb_initm ,
34.Nm mb_done ,
35.Nm mb_detach ,
36.Nm mb_fixhdr ,
37.Nm mb_reserve ,
38.Nm mb_put_uint8 ,
39.Nm mb_put_uint16be ,
40.Nm mb_put_uint16le ,
41.Nm mb_put_uint32be ,
42.Nm mb_put_uint32le ,
43.Nm mb_put_int64be ,
44.Nm mb_put_int64le ,
45.Nm mb_put_mem ,
46.Nm mb_put_mbuf ,
47.Nm mb_put_uio
48.Nd "set of functions to build an mbuf chain from various data types"
49.Sh SYNOPSIS
50.Cd options LIBMCHAIN
51.Li kldload libmchain
52.Pp
53.Fd #include <sys/param.h>
54.Fd #include <sys/mchain.h>
55.Ft int
56.Fn mb_init "struct mbchain *mbp"
57.Ft void
58.Fn mb_initm "struct mbchain *mbp" "struct mbuf *m"
59.Ft void
60.Fn mb_done "struct mbchain *mbp"
61.Ft struct mbuf *
62.Fn mb_detach "struct mbchain *mbp"
63.Ft int
64.Fn mb_fixhdr "struct mbchain *mbp"
65.Ft caddr_t
66.Fn mb_reserve "struct mbchain *mbp" "int size"
67.Ft int
68.Fn mb_put_uint8 "struct mbchain *mbp" "u_int8_t x"
69.Ft int
70.Fn mb_put_uint16be "struct mbchain *mbp" "u_int16_t x"
71.Ft int
72.Fn mb_put_uint16le "struct mbchain *mbp" "u_int16_t x"
73.Ft int
74.Fn mb_put_uint32be "struct mbchain *mbp" "u_int32_t x"
75.Ft int
76.Fn mb_put_uint32le "struct mbchain *mbp" "u_int32_t x"
77.Ft int
78.Fn mb_put_int64be "struct mbchain *mbp" "int64_t x"
79.Ft int
80.Fn mb_put_int64le "struct mbchain *mbp" "int64_t x"
81.Ft int
82.Fn mb_put_mem "struct mbchain *mbp" "c_caddr_t source" "int size" "int type"
83.Ft int
84.Fn mb_put_mbuf "struct mbchain *mbp" "struct mbuf *m"
85.Ft int
86.Fn mb_put_uio "struct mbchain *mbp" "struct uio *uiop" "int size"
87.Sh DESCRIPTION
88These functions are used to compose mbuf chains from various data types.
89The
90.Vt mbchain
91structure is used as a working context and should be initialized with a call
92to either
93.Fn mb_init
94or
95.Fn mb_initm .
96It has the following fields:
97.Bl -tag -width "mb_count"
98.It Va "mb_top"
99.Vt ( "struct mbuf *" )
100a pointer to the top of constructed mbuf chain
101.It Va mb_cur
102.Vt ( "struct mbuf *" )
103a pointer to the currently filled mbuf
104.It Va mb_mleft
105.Vt ( int )
106number of bytes left in the current mbuf
107.It Va mb_count
108.Vt ( int )
109total number of bytes placed in the mbuf chain
110.It Va mb_copy
111.Vt ( "mb_copy_t *" )
112user-defined function to perform a copy into mbuf;
113useful if any unusual
114data conversion is necessesary
115.It Va mb_udata
116.Vt ( "void *" )
117user-supplied data which can be used in the
118.Va mb_copy
119function
120.El
121.Pp
122.Fn mb_done
123function disposes an mbuf chain pointed to by
124.Fa mbp->mb_top
125field and sets
126the field to
127.Dv NULL .
128.Pp
129.Fn mb_detach
130function returns the value of
131.Fa mbp->mb_top
132field and sets its value to
133.Dv NULL .
134.Pp
135.Fn mb_fixhdr
136recalculates the length of an mbuf chain and updates the
137.Va m_pkthdr.len
138field of the first mbuf in the chain.
139It returns the calculated length.
140.Pp
141.Fn mb_reserve
142ensures that the object of the length specified by the
143.Fa size
144argument will fit in the current mbuf (mbuf allocation is performed if
145necessary), and advances all pointers as if the real data was placed.
146Returned
147value will point to the beginning of the reserved space.
148Note that the size
149of the object should not exceed
150.Dv MLEN
151bytes.
152.Pp
153All
154.Fn mb_put_*
155functions perform an actual copy of the data into mbuf chain.
156Functions which have
157.Cm le
158or
159.Cm be
160suffixes will perform conversion to the little\- or big\-endian data formats.
161.Pp
162.Fn mb_put_mem
163function copies
164.Fa size
165bytes of data specified by the
166.Fa source
167argument to an mbuf chain.
168The
169.Fa type
170argument specifies the method used to perform a copy,
171and can be one of the following:
172.Bl -tag -width "MB_MINLINE"
173.It Dv MB_MSYSTEM
174use
175.Fn bcopy
176function
177.It Dv MB_MUSER
178use
179.Xr copyin 9
180function
181.It Dv MB_MINLINE
182use an
183.Dq inline
184loop which does not call any function
185.It Dv MB_MZERO
186do not copy any data, but just fill the destination with zero bytes
187.It Dv MB_MCUSTOM
188call function specified by the
189.Fa mbp->mb_copy
190field
191.El
192.Sh RETURN VALUES
193All
194.Ft int
195functions except
196.Fn mb_fixhdr
197return zero if successful and an error code otherwise.
198.Pp
199.Em Note :
200after failure of any function, an mbuf chain is left in the broken state,
201and only
202.Fn mb_done
203function can safely be called to destroy it.
204.Sh EXAMPLES
205.Bd -literal
206struct mbchain *mbp;
207struct mbuf *m;
208
209mb_init(mbp);
210mb_put_uint8(mbp, 33);
211mb_put_uint16le(mbp, length);
212m = m_copym(mbp->mb_top, 0, M_COPYALL, M_TRYWAIT);
213send(m);
214mb_done(mbp);
215.Ed
216.Sh SEE ALSO
217.Xr mbuf 9 ,
218.Xr mdchain 9
219.Sh AUTHORS
220This manual page was written by
221.An Boris Popov Aq bp@FreeBSD.org .
222