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