1.\"
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.\"
29.\" $Begemot: libunimsg/man/unimsg.3,v 1.3 2005/05/23 12:00:09 brandt_h Exp $
30.\"
31.Dd May 23, 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
90These functions are used to manipulate variable sized message. They are
91inspired by BSD mbufs and SysV stream buffers, but somewhat simplified because
92signalling generally is a low bandwidth task. All the functions operation on
93a
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
110points just to the first byte behind that buffer. This 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
127returns the actual size of the message (the number of used bytes). The
128macro
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
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.
146The function
147.Fn uni_msg_build
148constructs a new message from a variable number of buffers. The arguments
149are pairs of
150.Vt void *
151pointers to buffers and
152.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.
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
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.
175The macro
176.Fn uni_msg_ensure
177checks whether the message has space for additional
178.Ar bytes
179bytes. If not it calls
180.Fn uni_msg_extend
181to make the message buffer larger. The 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
197needs not to be aligned). All three functions call
198.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.
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
207be in network byte order. It 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
215be in network byte order. It 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
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
226.Fa n
227returns 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.
230.Sh SEE ALSO
231.Xr libunimsg 3 ,
232.Xr mbuf 9
233.Sh AUTHORS
234.An Hartmut Brandt Aq harti@freebsd.org
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.\"
29.\" $Begemot: libunimsg/man/unimsg.3,v 1.3 2005/05/23 12:00:09 brandt_h Exp $
30.\"
31.Dd May 23, 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
90These functions are used to manipulate variable sized message. They are
91inspired by BSD mbufs and SysV stream buffers, but somewhat simplified because
92signalling generally is a low bandwidth task. All the functions operation on
93a
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
110points just to the first byte behind that buffer. This 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
127returns the actual size of the message (the number of used bytes). The
128macro
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
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.
146The function
147.Fn uni_msg_build
148constructs a new message from a variable number of buffers. The arguments
149are pairs of
150.Vt void *
151pointers to buffers and
152.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.
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
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.
175The macro
176.Fn uni_msg_ensure
177checks whether the message has space for additional
178.Ar bytes
179bytes. If not it calls
180.Fn uni_msg_extend
181to make the message buffer larger. The 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
197needs not to be aligned). All three functions call
198.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.
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
207be in network byte order. It 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
215be in network byte order. It 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
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
226.Fa n
227returns 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.
230.Sh SEE ALSO
231.Xr libunimsg 3 ,
232.Xr mbuf 9
233.Sh AUTHORS
234.An Hartmut Brandt Aq harti@freebsd.org