contrib/ngatm/man/unimsg.3

   1 .\"
   2 .\" Copyright (c) 2004-2005
   3 .\"     Hartmut Brandt.
   4 .\"     All rights reserved.
   5 .\" Copyright (c) 2001-2003
   6 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   7 .\"     All rights reserved.
   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 AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  31 .\"
  32 .\" $Begemot: libunimsg/man/unimsg.3,v 1.4 2005/06/15 11:37:10 brandt_h Exp $
  33 .\"
  34 .Dd June 14, 2005
  35 .Dt UNIMSG 3
  36 .Os
  37 .Sh NAME
  38 .Nm uni_msg_len ,
  39 .Nm uni_msg_space ,
  40 .Nm uni_msg_leading ,
  41 .Nm uni_msg_size ,
  42 .Nm uni_msg_ensure ,
  43 .Nm uni_msg_append ,
  44 .Nm uni_msg_extend ,
  45 .Nm uni_msg_alloc ,
  46 .Nm uni_msg_build ,
  47 .Nm uni_msg_destroy ,
  48 .Nm uni_msg_strip32 ,
  49 .Nm uni_msg_get32 ,
  50 .Nm uni_msg_append32 ,
  51 .Nm uni_msg_append8 ,
  52 .Nm uni_msg_trail32 ,
  53 .Nm uni_msg_dup
  54 .Nd "ATM signalling library - message buffers"
  55 .Sh LIBRARY
  56 Begemot ATM signalling library
  57 .Pq libunimsg, -lunimsg
  58 .Sh SYNOPSIS
  59 .In uni4/unimsg.h
  60 .Ft size_t
  61 .Fn uni_msg_len "const struct uni_msg *msg"
  62 .Ft size_t
  63 .Fn uni_msg_space "const struct uni_msg *msg"
  64 .Ft size_t
  65 .Fn uni_msg_leading "const struct uni_msg *msg"
  66 .Ft size_t
  67 .Fn uni_msg_size "const struct uni_msg *msg"
  68 .Ft int
  69 .Fn uni_msg_ensure "struct uni_msg *msg" "size_t bytes"
  70 .Ft int
  71 .Fn uni_msg_append "struct uni_msg *msg" "void *buf" "size_t buflen"
  72 .Ft int
  73 .Fn uni_msg_extend "struct uni_msg *msg" "size_t bytes"
  74 .Ft struct uni_msg *
  75 .Fn uni_msg_alloc "size_t space"
  76 .Ft struct uni_msg *
  77 .Fn uni_msg_build "void *buf" "..."
  78 .Ft void
  79 .Fn uni_msg_destroy "struct uni_msg *msg"
  80 .Ft u_int
  81 .Fn uni_msg_strip32 "struct uni_msg *msg"
  82 .Ft u_int
  83 .Fn uni_msg_get32 "struct uni_msg *msg"
  84 .Ft int
  85 .Fn uni_msg_append32 "struct uni_msg *msg" "u_int value"
  86 .Ft int
  87 .Fn uni_msg_append8 "struct uni_msg *msg" "u_int byte"
  88 .Ft u_int
  89 .Fn uni_msg_trail32 "const struct uni_msg *msg" "int n"
  90 .Ft struct uni_msg *
  91 .Fn uni_msg_dup "const struct uni_msg *msg"
  92 .Sh DESCRIPTION
  93 These functions are used to manipulate variable sized message.
  94 They are
  95 inspired by BSD mbufs and SysV stream buffers, but somewhat simplified because
  96 signalling generally is a low bandwidth task.
  97 All the functions operation on a
  98 .Li uni_msg
  99 data structure:
 100 .Bd -literal -offset indent
 101 struct uni_msg {
 102         u_char  *b_wptr;        /* tail pointer */
 103         u_char  *b_rptr;        /* head pointer */
 104         u_char  *b_buf;         /* data buffer */
 105         u_char  *b_lim;         /* end of data buffer */
 106 };
 107 .Ed
 108 .Pp
 109 The field
 110 .Fa b_buf
 111 points to the begin of a memory block that is used to store the actual message
 112 and the field
 113 .Fa b_lim
 114 points just to the first byte behind that buffer.
 115 This buffer is allocated
 116 separate from the structure itself and the user calling any of the above
 117 functions with a non const
 118 .Vt struct uni_msg
 119 argument should expect the buffer to be reallocated and hence not hold pointers
 120 into the buffer accross call to these functions.
 121 The pointer
 122 .Fa b_rptr
 123 points to the first used byte in the message and
 124 .Fa b_wptr
 125 to the first unused byte behind all used bytes.
 126 If the message is empty, both pointers point to the same place somewhere in
 127 the allocated buffer.
 128 .Pp
 129 There are several functions and macros that return various sizes and lengths.
 130 The macro
 131 .Fn uni_msg_len
 132 returns the actual size of the message (the number of used bytes).
 133 The macro
 134 .Fn uni_msg_space
 135 returns the number of bytes that are left unused behind the used space.
 136 The macro
 137 .Fn uni_msg_leading
 138 returns the number of bytes that are unused before the used space and the
 139 macro
 140 .Fn uni_msg_size
 141 returns the maximum size of the message (that is the size of the allocated
 142 buffer).
 143 .Pp
 144 Two functions may be used to create new messages: The function
 145 .Fn uni_msg_alloc
 146 allocates the message structure and a buffer to hold at least
 147 .Ar space
 148 bytes (In fact it allocates a couple of bytes more).
 149 If the allocation fails NULL is returned.
 150 The pointers are setup so that there is no leading space in the buffer.
 151 The function
 152 .Fn uni_msg_build
 153 constructs a new message from a variable number of buffers.
 154 The arguments are pairs of
 155 .Vt void *
 156 pointers to buffers and
 157 .Vt size_t
 158 buffer sizes, terminated by a NULL pointer.
 159 The function computes the total resulting message size, allocates a message
 160 and copies all the buffers into the message.
 161 The message is built to have no leading space.
 162 If the allocation fails, NULL is returned.
 163 .Pp
 164 The function
 165 .Fn uni_msg_destroy
 166 deallocates the buffer pointed to by the message and the message itself.
 167 It is save to pass a message with a NULL buffer, but not a NULL message.
 168 .Pp
 169 The function
 170 .Fn uni_msg_dup
 171 returns a copy of a message with exact the same leading space.
 172 .Pp
 173 A number of functions are used to add bytes to an existing message.
 174 The function
 175 .Fn uni_msg_extend
 176 extends the message buffer to have space for at least
 177 .Ar bytes
 178 additional byte at the end.
 179 The leading space does not change.
 180 This function may reallocate the message buffer.
 181 The function returns 0 on success and ENOMEM if the reallocation fails.
 182 In this case the message buffer is not changed.
 183 The macro
 184 .Fn uni_msg_ensure
 185 checks whether the message has space for additional
 186 .Ar bytes
 187 bytes.
 188 If not it calls
 189 .Fn uni_msg_extend
 190 to make the message buffer larger.
 191 The macro returns 0 on success or ENOMEM
 192 if there is not enough space and the reallocation fails.
 193 In this case the message buffer is not changed.
 194 The function
 195 .Fn uni_msg_append
 196 appends
 197 .Ar buflen
 198 bytes from the buffer pointed to by
 199 .Ar buf
 200 to the message.
 201 The function
 202 .Fn uni_msg_append8
 203 appends one byte to the message and the function
 204 .Fn uni_msg_append32
 205 appends a 32-bit value in network byte order to the message
 206 .Fa ( b_wptr
 207 needs not to be aligned).
 208 All three functions call
 209 .Fn uni_msg_ensure
 210 to make sure, that the buffer contents fit into the message.
 211 They return 0 on success and ENOMEM if the buffer is too small and
 212 the reallocation fails.
 213 In this case the message buffer is not changed.
 214 .Pp
 215 A number of functions can be used to retrieve parts of the message.
 216 The function
 217 .Fn uni_msg_strip32
 218 returns the last four bytes of the message as a 32-bit integer assumed to
 219 be in network byte order.
 220 It adjusts
 221 .Fa b_wptr
 222 to remove these four bytes from the message.
 223 .Fa b_wptr
 224 does not need to be aligned.
 225 The function
 226 .Fn uni_msg_get32
 227 returns the first four bytes of the message as a 32-bit integer assumed to
 228 be in network byte order.
 229 It adjusts
 230 .Fa b_rptr
 231 to remove these four bytes from the message.
 232 .Fa b_rptr
 233 does not need to be aligned.
 234 The function
 235 .Fn uni_msg_trail32
 236 returns the
 237 .Fa n 'th
 238 32-bit integer from the buffer counted from the end of the buffer.
 239 The integer is assumed to be in network byte order.
 240 A value of -1 for
 241 .Fa n
 242 returns the last four bytes of the buffer, a value of -2 the four bytes
 243 just before the last four bytes and so on.
 244 All three functions do not check that the message is large enough.
 245 .Sh SEE ALSO
 246 .Xr libunimsg 3 ,
 247 .Xr mbuf 9
 248 .Sh AUTHORS
 249 .An Hartmut Brandt Aq harti@FreeBSD.org