1.\" $OpenBSD: evbuffer_new.3,v 1.14 2018/07/26 12:50:04 rob 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: July 26 2018 $ 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.Nm EVBUFFER_LENGTH , 37.Nm EVBUFFER_DATA 38.Nd libevent utility API for buffered input/output 39.Sh SYNOPSIS 40.In event.h 41.Ft "struct evbuffer *" 42.Fn "evbuffer_new" "void" 43.Ft void 44.Fn "evbuffer_free" "struct evbuffer *buf" 45.Ft void 46.Fo evbuffer_setcb 47.Fa "struct evbuffer *buf" 48.Fa "void (*cb)(struct evbuffer *, size_t, size_t, void *)" 49.Fa "void *cbarg" 50.Fc 51.Ft int 52.Fn "evbuffer_expand" "struct evbuffer *buf" "size_t datlen" 53.Ft int 54.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size" 55.Ft int 56.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src" 57.Ft int 58.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..." 59.Ft int 60.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap" 61.Ft void 62.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size" 63.Ft int 64.Fn "evbuffer_remove" "struct evbuffer *buf" "void *data" "size_t datlen" 65.Ft int 66.Fn "evbuffer_write" "struct evbuffer *buf" "int fd" 67.Ft int 68.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size" 69.Ft "u_char *" 70.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size" 71.Ft "char *" 72.Fn "evbuffer_readline" "struct evbuffer *buf" 73.Ft "char *" 74.Fo evbuffer_readln 75.Fa "struct evbuffer *buf" 76.Fa "size_t *read_out" 77.Fa "enum evbuffer_eol_style eol_style" 78.Fc 79.Ft size_t 80.Fn "EVBUFFER_LENGTH" "const struct evbuffer *buf" 81.Ft "u_char *" 82.Fn "EVBUFFER_DATA" "const struct evbuffer *buf" 83.Sh DESCRIPTION 84The evbuffer API provides an implementation of buffering for use with 85libevent. 86.Pp 87.Fn evbuffer_new 88allocates and initialises a new evbuffer structure. 89.Pp 90.Fn evbuffer_free 91deallocates the evbuffer structure 92.Fa buf 93and any referenced storage. 94.Pp 95.Fn evbuffer_setcb 96sets the callback 97.Fa cb 98to be invoked with argument 99.Fa cbarg 100when the data in evbuffer 101.Fa buf 102is modified. 103.Pp 104.Fn evbuffer_expand 105expands the available space in 106.Fa buf 107to at least 108.Fa datlen 109bytes. 110.Pp 111.Fn evbuffer_add 112appends a copy of 113.Fa size 114bytes from buffer 115.Fa data 116to the end of the evbuffer 117.Fa buf . 118.Pp 119.Fn evbuffer_add_buffer 120moves the data off the 121.Fa src 122evbuffer and appends it to 123.Fa dst . 124.Pp 125.Fn evbuffer_add_printf 126appends a 127.Xr printf 3 128style formatted string specified by 129.Fa fmt 130to the end of 131.Fa buf . 132.Pp 133.Fn evbuffer_add_vprintf 134appends a 135.Xr vprintf 3 136style formatted string specified by 137.Fa fmt 138with a va_list 139.Fa ap 140to the end of 141.Fa buf . 142.Pp 143.Fn evbuffer_drain 144deletes 145.Fa size 146bytes from the beginning of the evbuffer 147.Fa buf . 148.Pp 149.Fn evbuffer_remove 150reads and drains up to 151.Fa datlen 152bytes from the beginning of the evbuffer 153.Fa buf 154into 155.Fa data . 156.Pp 157.Fn evbuffer_write 158writes and drains the contents of evbuffer 159.Fa buf 160to the file descriptor 161.Fa fd . 162.Pp 163.Fn evbuffer_read 164appends up to 165.Fa size 166bytes on to the end of the evbuffer 167.Fa buf 168by reading from the file descriptor 169.Fa fd . 170.Pp 171.Fn evbuffer_find 172finds the 173.Fa size 174length string 175.Fa data 176in the evbuffer 177.Fa buf . 178.Pp 179.Fn evbuffer_readline 180reads and drains a single line from the evbuffer 181.Fa buf . 182A line is delimited by "\en", "\er", "\er\en", or "\en\er". 183It is the responsibility of the caller to free the returned line with 184.Xr free 3 . 185.Pp 186.Fn evbuffer_readln 187reads and drains a single line from the evbuffer 188.Fa buf . 189The length of the line will be stored in 190.Fa read_out 191on success. 192It is the responsibility of the caller to free the returned line with 193.Xr free 3 . 194The line delimiter is specified as one of the following: 195.Bl -tag -width xxx -offset indent 196.It Dv EVBUFFER_EOL_ANY 197Any sequence of newline or carriage return characters. 198.It Dv EVBUFFER_EOL_CRLF 199A new line optionally preceded by a carriage return. 200.It Dv EVBUFFER_EOL_CRLF_STRICT 201A carriage return followed by a new line character. 202.It Dv EVBUFFER_EOL_LF 203A new line character. 204.El 205.Pp 206.Fn EVBUFFER_LENGTH 207reports how many bytes are stored in the evbuffer 208.Fa buf . 209.Sh RETURN VALUES 210.Fn evbuffer_new 211returns a pointer to a newly allocated buffer on success, 212or 213.Dv NULL 214on failure and sets 215.Va errno 216to indicate the failure. 217.Pp 218.Fn evbuffer_expand , 219.Fn evbuffer_add , 220and 221.Fn evbuffer_add_buffer 222return 0 on success, 223or -1 on failure and set 224.Va errno 225to indicate the failure. 226.Pp 227.Fn evbuffer_add_printf 228and 229.Fn evbuffer_add_vprintf 230return the number of bytes added on success, 231or -1 on failure. 232.Pp 233.Fn evbuffer_remove 234returns the number of bytes read. 235.Pp 236.Fn evbuffer_write 237returns the number of bytes written and drained on success, 238or -1 on failure and sets 239.Va errno 240to indicate the failure. 241.Pp 242.Fn evbuffer_read 243returns the number of bytes appended to the evbuffer on success, 2440 on an end of file condition, 245or -1 on failure and sets 246.Va errno 247to indicate the failure. 248.Pp 249.Fn evbuffer_find 250returns a pointer to the start of the string within the evbuffer on success, 251or 252.Dv NULL 253on failure. 254.Pp 255.Fn evbuffer_readline 256and 257.Fn evbuffer_readln 258return a pointer to the line on success, 259or 260.Dv NULL 261on failure. 262.Pp 263.Fn EVBUFFER_LENGTH 264returns the number of bytes available in the evbuffer. 265.Pp 266.Fn EVBUFFER_DATA 267returns a pointer to the evbuffer 268.Fa buf 269on success. 270.Sh SEE ALSO 271.Xr errno 2 , 272.Xr event 3 , 273.Xr free 3 , 274.Xr printf 3 275.Sh AUTHORS 276The 277.Nm event 278library was written by 279.An Niels Provos . 280