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