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