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 --- 11 unchanged lines hidden (view full) --- 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 , --- 42 unchanged lines hidden (view full) --- 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 |
93These functions are used to manipulate variable sized message. 94They are |
95inspired by BSD mbufs and SysV stream buffers, but somewhat simplified because |
96signalling generally is a low bandwidth task. 97All the functions operation on a |
98.Li uni_msg 99data structure: 100.Bd -literal -offset indent 101struct 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 109The field 110.Fa b_buf 111points to the begin of a memory block that is used to store the actual message 112and the field 113.Fa b_lim |
114points just to the first byte behind that buffer. 115This buffer is allocated |
116separate from the structure itself and the user calling any of the above 117functions with a non const 118.Vt struct uni_msg 119argument should expect the buffer to be reallocated and hence not hold pointers 120into the buffer accross call to these functions. 121The pointer 122.Fa b_rptr 123points to the first used byte in the message and 124.Fa b_wptr 125to the first unused byte behind all used bytes. 126If the message is empty, both pointers point to the same place somewhere in 127the allocated buffer. 128.Pp 129There are several functions and macros that return various sizes and lengths. 130The macro 131.Fn uni_msg_len |
132returns the actual size of the message (the number of used bytes). 133The macro |
134.Fn uni_msg_space 135returns the number of bytes that are left unused behind the used space. 136The macro 137.Fn uni_msg_leading 138returns the number of bytes that are unused before the used space and the 139macro 140.Fn uni_msg_size 141returns the maximum size of the message (that is the size of the allocated 142buffer). 143.Pp 144Two functions may be used to create new messages: The function 145.Fn uni_msg_alloc 146allocates the message structure and a buffer to hold at least 147.Ar space |
148bytes (In fact it allocates a couple of bytes more). 149If the allocation fails NULL is returned. 150The pointers are setup so that there is no leading space in the buffer. |
151The function 152.Fn uni_msg_build |
153constructs a new message from a variable number of buffers. 154The arguments are pairs of |
155.Vt void * 156pointers to buffers and 157.Vt size_t |
158buffer sizes, terminated by a NULL pointer. 159The function computes the total resulting message size, allocates a message 160and copies all the buffers into the message. 161The message is built to have no leading space. 162If the allocation fails, NULL is returned. |
163.Pp 164The function 165.Fn uni_msg_destroy 166deallocates the buffer pointed to by the message and the message itself. 167It is save to pass a message with a NULL buffer, but not a NULL message. 168.Pp 169The function 170.Fn uni_msg_dup 171returns a copy of a message with exact the same leading space. 172.Pp 173A number of functions are used to add bytes to an existing message. 174The function 175.Fn uni_msg_extend 176extends the message buffer to have space for at least 177.Ar bytes |
178additional byte at the end. 179The leading space does not change. 180This function may reallocate the message buffer. 181The function returns 0 on success and ENOMEM if the reallocation fails. 182In this case the message buffer is not changed. |
183The macro 184.Fn uni_msg_ensure 185checks whether the message has space for additional 186.Ar bytes |
187bytes. 188If not it calls |
189.Fn uni_msg_extend |
190to make the message buffer larger. 191The macro returns 0 on success or ENOMEM |
192if there is not enough space and the reallocation fails. 193In this case the message buffer is not changed. 194The function 195.Fn uni_msg_append 196appends 197.Ar buflen 198bytes from the buffer pointed to by 199.Ar buf 200to the message. 201The function 202.Fn uni_msg_append8 203appends one byte to the message and the function 204.Fn uni_msg_append32 205appends a 32-bit value in network byte order to the message 206.Fa ( b_wptr |
207needs not to be aligned). 208All three functions call |
209.Fn uni_msg_ensure |
210to make sure, that the buffer contents fit into the message. 211They return 0 on success and ENOMEM if the buffer is too small and 212the reallocation fails. 213In this case the message buffer is not changed. |
214.Pp 215A number of functions can be used to retrieve parts of the message. 216The function 217.Fn uni_msg_strip32 218returns the last four bytes of the message as a 32-bit integer assumed to |
219be in network byte order. 220It adjusts |
221.Fa b_wptr 222to remove these four bytes from the message. 223.Fa b_wptr 224does not need to be aligned. 225The function 226.Fn uni_msg_get32 227returns the first four bytes of the message as a 32-bit integer assumed to |
228be in network byte order. 229It adjusts |
230.Fa b_rptr 231to remove these four bytes from the message. 232.Fa b_rptr 233does not need to be aligned. 234The function 235.Fn uni_msg_trail32 236returns the 237.Fa n 'th |
23832-bit integer from the buffer counted from the end of the buffer. 239The integer is assumed to be in network byte order. 240A value of -1 for |
241.Fa n 242returns the last four bytes of the buffer, a value of -2 the four bytes |
243just before the last four bytes and so on. 244All 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 |