1.\" $OpenBSD: evbuffer_new.3,v 1.12 2014/11/21 06:59:00 dlg Exp $ 2.\" 3.\" Copyright (c) 2014 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: November 21 2014 $ 18.Dt EVBUFFER_NEW 3 19.Os 20.Sh NAME 21.Nm evbuffer_new , 22.Nm evbuffer_free , 23.Nm evbuffer_setcb , 24.Nm evbuffer_expand , 25.Nm evbuffer_add , 26.Nm evbuffer_add_buffer , 27.Nm evbuffer_add_printf , 28.Nm evbuffer_add_vprintf , 29.Nm evbuffer_drain , 30.Nm evbuffer_remove , 31.Nm evbuffer_write , 32.Nm evbuffer_read , 33.Nm evbuffer_find , 34.Nm evbuffer_readline , 35.Nm evbuffer_readln 36.Nd libevent utility API for buffered input/output 37.Sh SYNOPSIS 38.In event.h 39.Ft "struct evbuffer *" 40.Fn "evbuffer_new" "void" 41.Ft void 42.Fn "evbuffer_free" "struct evbuffer *buf" 43.Ft void 44.Fo evbuffer_setcb 45.Fa "struct evbuffer *buf" 46.Fa "void (*cb)(struct evbuffer *, size_t, size_t, void *)" 47.Fa "void *cbarg" 48.Fc 49.Ft int 50.Fn "evbuffer_expand" "struct evbuffer *buf" "size_t datlen" 51.Ft int 52.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size" 53.Ft int 54.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src" 55.Ft int 56.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..." 57.Ft int 58.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap" 59.Ft void 60.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size" 61.Ft int 62.Fn "evbuffer_remove" "struct evbuffer *buf" "void *data" "size_t datlen" 63.Ft int 64.Fn "evbuffer_write" "struct evbuffer *buf" "int fd" 65.Ft int 66.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size" 67.Ft "u_char *" 68.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size" 69.Ft "char *" 70.Fn "evbuffer_readline" "struct evbuffer *buf" 71.Ft "char *" 72.Fo evbuffer_readln 73.Fa "struct evbuffer *buf" 74.Fa "size_t *read_out" 75.Fa "enum evbuffer_eol_style eol_style" 76.Fc 77.Ft size_t 78.Fn "EVBUFFER_LENGTH" "const struct evbuffer *buf" 79.Sh DESCRIPTION 80The evbuffer API provides an implementation of buffering for use with 81libevent. 82.Pp 83.Fn evbuffer_new 84allocates and initialises a new evbuffer structure. 85.Pp 86.Fn evbuffer_free 87deallocates the evbuffer structure 88.Fa buf 89and any referenced storage. 90.Pp 91.Fn evbuffer_setcb 92sets the callback 93.Fa cb 94to be invoked with argument 95.Fa cbarg 96when the data in evbuffer 97.Fa buf 98is modified. 99.Pp 100.Fn evbuffer_expand 101expands the available space in 102.Fa buf 103to at least 104.Fa datlen 105bytes. 106.Pp 107.Fn evbuffer_add 108appends a copy of 109.Fa size 110bytes from buffer 111.Fa data 112to the end of the evbuffer 113.Fa buf . 114.Pp 115.Fn evbuffer_add_buffer 116moves the data off the 117.Fa src 118evbuffer and appends it to 119.Fa dst . 120.Pp 121.Fn evbuffer_add_printf 122appends a 123.Xr printf 3 124style formatted string specified by 125.Fa fmt 126to the end of 127.Fa buf . 128.Pp 129.Fn evbuffer_add_vprintf 130appends a 131.Xr vprintf 3 132style formatted string specified by 133.Fa fmt 134with a va_list 135.Fa ap 136to the end of 137.Fa buf . 138.Pp 139.Fn evbuffer_drain 140deletes 141.Fa size 142bytes from the beginning of the evbuffer 143.Fa buf . 144.Pp 145.Fn evbuffer_remove 146reads and drains up to 147.Fa datlen 148bytes from the beginning of the evbuffer 149.Fa buf 150into 151.Fa data . 152.Pp 153.Fn evbuffer_write 154writes and drains the contents of evbuffer 155.Fa buf 156to the file descriptor 157.Fa fd . 158.Pp 159.Fn evbuffer_read 160appends up to 161.Fa size 162bytes on to the end of the evbuffer 163.Fa buf 164by reading from the file descriptor 165.Fa fd . 166.Pp 167.Fn evbuffer_find 168finds the 169.Fa size 170length string 171.Fa data 172in the evbuffer 173.Fa buf . 174.Pp 175.Fn evbuffer_readline 176reads and drains a single line from the evbuffer 177.Fa buf . 178A line is delimited by "\en", "\er", "\er\en", or "\en\er". 179It is the responsibility of the caller to free the returned line with 180.Xr free 3 . 181.Pp 182.Fn evbuffer_readln 183reads and drains a single line from the evbuffer 184.Fa buf . 185The length of the line will be stored in 186.Fa read_out 187on success. 188It is the responsibility of the caller to free the returned line with 189.Xr free 3 . 190The line delimiter is specified as one of the following: 191.Bl -tag -width xxx -offset indent 192.It Dv EVBUFFER_EOL_ANY 193Any sequence of newline or carriage return characters. 194.It Dv EVBUFFER_EOL_CRLF 195A new line optionally preceded by a carriage return. 196.It Dv EVBUFFER_EOL_CRLF_STRICT 197A carriage return followed by a new line character. 198.It Dv EVBUFFER_EOL_LF 199A new line character. 200.El 201.Pp 202.Fn EVBUFFER_LENGTH 203reports how many bytes are stored in the evbuffer 204.Fa buf . 205.Sh RETURN VALUES 206.Fn evbuffer_new 207returns a pointer to a newly allocated buffer on success, 208or 209.Dv NULL 210on failure and sets 211.Va errno 212to indicate the failure. 213.Pp 214.Fn evbuffer_expand , 215.Fn evbuffer_add , 216and 217.Fn evbuffer_add_buffer 218return 0 on success, 219or -1 on failure and set 220.Va errno 221to indicate the failure. 222.Pp 223.Fn evbuffer_add_printf 224and 225.Fn evbuffer_add_vprintf 226return the number of bytes added on success, 227or -1 on failure. 228.Pp 229.Fn evbuffer_remove 230returns the number of bytes read. 231.Pp 232.Fn evbuffer_write 233returns the number of bytes written and drained on success, 234or -1 on failure and sets 235.Va errno 236to indicate the failure. 237.Pp 238.Fn evbuffer_read 239returns the number of bytes appended to the evbuffer on success, 2400 on an end of file condition, 241or -1 on failure and sets 242.Va errno 243to indicate the failure. 244.Pp 245.Fn evbuffer_find 246returns a pointer to the start of the string within the evbuffer on success, 247or 248.Dv NULL 249on failure. 250.Pp 251.Fn evbuffer_readline 252and 253.Fn evbuffer_readln 254return a pointer to the line on success, 255or 256.Dv NULL 257on failure. 258.Pp 259.Fn EVBUFFER_LENGTH 260returns the number of bytes available in the evbuffer. 261.Sh SEE ALSO 262.Xr errno 2 , 263.Xr event 3 , 264.Xr free 3 , 265.Xr printf 3 266.Sh AUTHORS 267The 268.Nm event 269library was written by 270.An Niels Provos . 271