2 .\" Copyright (c) 2004-2005
4 .\" All rights reserved.
5 .\" Copyright (c) 2001-2003
6 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
7 .\" All rights reserved.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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
30 .\" Author: Hartmut Brandt <harti@freebsd.org>
32 .\" $Begemot: libunimsg/man/unimsg.3,v 1.4 2005/06/15 11:37:10 brandt_h Exp $
50 .Nm uni_msg_append32 ,
54 .Nd "ATM signalling library - message buffers"
56 Begemot ATM signalling library
57 .Pq libunimsg, -lunimsg
61 .Fn uni_msg_len "const struct uni_msg *msg"
63 .Fn uni_msg_space "const struct uni_msg *msg"
65 .Fn uni_msg_leading "const struct uni_msg *msg"
67 .Fn uni_msg_size "const struct uni_msg *msg"
69 .Fn uni_msg_ensure "struct uni_msg *msg" "size_t bytes"
71 .Fn uni_msg_append "struct uni_msg *msg" "void *buf" "size_t buflen"
73 .Fn uni_msg_extend "struct uni_msg *msg" "size_t bytes"
75 .Fn uni_msg_alloc "size_t space"
77 .Fn uni_msg_build "void *buf" "..."
79 .Fn uni_msg_destroy "struct uni_msg *msg"
81 .Fn uni_msg_strip32 "struct uni_msg *msg"
83 .Fn uni_msg_get32 "struct uni_msg *msg"
85 .Fn uni_msg_append32 "struct uni_msg *msg" "u_int value"
87 .Fn uni_msg_append8 "struct uni_msg *msg" "u_int byte"
89 .Fn uni_msg_trail32 "const struct uni_msg *msg" "int n"
91 .Fn uni_msg_dup "const struct uni_msg *msg"
93 These functions are used to manipulate variable sized message.
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
100 .Bd -literal -offset indent
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 */
111 points to the begin of a memory block that is used to store the actual message
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
119 argument should expect the buffer to be reallocated and hence not hold pointers
120 into the buffer accross call to these functions.
123 points to the first used byte in the message and
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.
129 There are several functions and macros that return various sizes and lengths.
132 returns the actual size of the message (the number of used bytes).
135 returns the number of bytes that are left unused behind the used space.
138 returns the number of bytes that are unused before the used space and the
141 returns the maximum size of the message (that is the size of the allocated
144 Two functions may be used to create new messages: The function
146 allocates the message structure and a buffer to hold at least
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.
153 constructs a new message from a variable number of buffers.
154 The arguments are pairs of
156 pointers to buffers and
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.
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.
171 returns a copy of a message with exact the same leading space.
173 A number of functions are used to add bytes to an existing message.
176 extends the message buffer to have space for at least
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.
185 checks whether the message has space for additional
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.
198 bytes from the buffer pointed to by
203 appends one byte to the message and the function
205 appends a 32-bit value in network byte order to the message
207 needs not to be aligned).
208 All three functions call
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.
215 A number of functions can be used to retrieve parts of the message.
218 returns the last four bytes of the message as a 32-bit integer assumed to
219 be in network byte order.
222 to remove these four bytes from the message.
224 does not need to be aligned.
227 returns the first four bytes of the message as a 32-bit integer assumed to
228 be in network byte order.
231 to remove these four bytes from the message.
233 does not need to be aligned.
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.
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.
249 .An Hartmut Brandt Aq harti@freebsd.org