share/man/man9/mdchain.9

   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 .Dd February 28, 2001
  26 .Dt MDCHAIN 9
  27 .Os
  28 .Sh NAME
  29 .Nm mdchain ,
  30 .Nm md_initm ,
  31 .Nm md_done ,
  32 .Nm md_append_record ,
  33 .Nm md_next_record ,
  34 .Nm md_get_uint8 ,
  35 .Nm md_get_uint16 ,
  36 .Nm md_get_uint16be ,
  37 .Nm md_get_uint16le ,
  38 .Nm md_get_uint32 ,
  39 .Nm md_get_uint32be ,
  40 .Nm md_get_uint32le ,
  41 .Nm md_get_int64 ,
  42 .Nm md_get_int64be ,
  43 .Nm md_get_int64le ,
  44 .Nm md_get_mem ,
  45 .Nm md_get_mbuf ,
  46 .Nm md_get_uio
  47 .Nd "set of functions to dissect an mbuf chain to various data types"
  48 .Sh SYNOPSIS
  49 .Cd options LIBMCHAIN
  50 .Li kldload libmchain
  51 .Pp
  52 .In sys/param.h
  53 .In sys/uio.h
  54 .In sys/mchain.h
  55 .Ft void
  56 .Fn md_initm "struct mdchain *mdp" "struct mbuf *m"
  57 .Ft void
  58 .Fn md_done "struct mdchain *mdp"
  59 .Ft void
  60 .Fn md_append_record "struct mdchain *mdp" "struct mbuf *top"
  61 .Ft int
  62 .Fn md_next_record "struct mdchain *mdp"
  63 .Ft int
  64 .Fn md_get_uint8 "struct mdchain *mdp" "uint8_t *x"
  65 .Ft int
  66 .Fn md_get_uint16 "struct mdchain *mdp" "uint16_t *x"
  67 .Ft int
  68 .Fn md_get_uint16be "struct mdchain *mdp" "uint16_t *x"
  69 .Ft int
  70 .Fn md_get_uint16le "struct mdchain *mdp" "uint16_t *x"
  71 .Ft int
  72 .Fn md_get_uint32 "struct mdchain *mdp" "uint32_t *x"
  73 .Ft int
  74 .Fn md_get_uint32be "struct mdchain *mdp" "uint32_t *x"
  75 .Ft int
  76 .Fn md_get_uint32le "struct mdchain *mdp" "uint32_t *x"
  77 .Ft int
  78 .Fn md_get_int64 "struct mdchain *mdp" "int64_t *x"
  79 .Ft int
  80 .Fn md_get_int64be "struct mdchain *mdp" "int64_t *x"
  81 .Ft int
  82 .Fn md_get_int64le "struct mdchain *mdp" "int64_t *x"
  83 .Ft int
  84 .Fn md_get_mem "struct mdchain *mdp" "caddr_t target" "int size" "int type"
  85 .Ft int
  86 .Fn md_get_mbuf "struct mdchain *mdp" "int size" "struct mbuf **m"
  87 .Ft int
  88 .Fn md_get_uio "struct mdchain *mdp" "struct uio *uiop" "int size"
  89 .Sh DESCRIPTION
  90 These functions are used to decompose mbuf chains to various data types.
  91 The
  92 .Vt mdchain
  93 structure is used as a working context
  94 and should be initialized through a call of the
  95 .Fn mb_initm
  96 function.
  97 It has the following fields:
  98 .Bl -tag -width "md_top"
  99 .It Va "md_top"
 100 .Pq Vt "struct mbuf *"
 101 A pointer to the top of the parsed mbuf chain.
 102 .It Va md_cur
 103 .Pq Vt "struct mbuf *"
 104 A pointer to the currently parsed mbuf.
 105 .It Va md_pas
 106 .Pq Vt int
 107 Offset in the current mbuf.
 108 .El
 109 .Pp
 110 The
 111 .Fn md_done
 112 function disposes of an mbuf chain pointed to by the
 113 .Fa mdp->md_top
 114 field and sets the field to
 115 .Dv NULL .
 116 .Pp
 117 The
 118 .Fn md_append_record
 119 appends a new mbuf chain using
 120 .Va m_nextpkt
 121 field to form a single linked list of mbuf chains.
 122 If the
 123 .Fa mdp->md_top
 124 field is
 125 .Dv NULL ,
 126 then this function behaves exactly as the
 127 .Fn md_initm
 128 function.
 129 .Pp
 130 The
 131 .Fn md_next_record
 132 function extracts the next mbuf chain and disposes the current one, if any.
 133 For a new mbuf chain it calls the
 134 .Fn md_initm
 135 function.
 136 If there is no data left the function returns
 137 .Er ENOENT .
 138 .Pp
 139 All
 140 .Fn md_get_*
 141 functions perform an actual copy of the data from an mbuf chain.
 142 Functions which have
 143 .Cm le
 144 or
 145 .Cm be
 146 suffixes will perform conversion to the little\- or big\-endian data formats.
 147 .Pp
 148 .Fn md_get_mem
 149 function copies
 150 .Fa size
 151 bytes of data specified by the
 152 .Fa source
 153 argument from an mbuf chain.
 154 The
 155 .Fa type
 156 argument specifies the method used to perform a copy,
 157 and can be one of the following:
 158 .Bl -tag -width ".Dv MB_MINLINE"
 159 .It Dv MB_MSYSTEM
 160 Use the
 161 .Fn bcopy
 162 function.
 163 .It Dv MB_MUSER
 164 Use the
 165 .Xr copyin 9
 166 function.
 167 .It Dv MB_MINLINE
 168 Use an
 169 .Dq inline
 170 loop which does not call any function.
 171 .El
 172 .Pp
 173 If
 174 .Fa target
 175 is
 176 .Dv NULL ,
 177 an actual copy is not performed
 178 and the function just skips the given number of bytes.
 179 .Sh RETURN VALUES
 180 All
 181 .Ft int
 182 functions return zero if successful,
 183 otherwise an error code is returned.
 184 .Pp
 185 .Em Note :
 186 after failure of any function,
 187 an mbuf chain is left in the broken state and only the
 188 .Fn md_done
 189 function can safely be called to destroy it.
 190 .Sh EXAMPLES
 191 .Bd -literal
 192 struct mdchain *mdp;
 193 struct mbuf *m;
 194 uint16_t length;
 195 uint8_t byte;
 196
 197 receive(so, &m);
 198 md_initm(mdp, m);
 199 if (md_get_uint8(mdp, &byte) != 0 ||
 200     md_get_uint16le(mdp, &length) != 0)
 201         error = EBADRPC;
 202 mb_done(mdp);
 203 .Ed
 204 .Sh SEE ALSO
 205 .Xr mbchain 9 ,
 206 .Xr mbuf 9
 207 .Sh AUTHORS
 208 This manual page was written by
 209 .An Boris Popov Aq Mt bp@FreeBSD.org .