i got sick of having to read the source code to know what the

evbuffer_foo functions do. reyk, nicm, jmc, and schwarze seem to
support a manpage as a reasonable solution to this problem.

im putting this in a separate manpage because i find they get too
cumbersome when they get too big. ingo agrees (and suggests even
this might be too big).

the file is evbuffer_new.3 rather than evbuffer.3 because we document
functions.

ok reyk@ nicm@ jmc@ schwarze@
this is rough, everyone has tweaks coming.

3 files changed, 261 insertions, 48 deletions

diff --git a/lib/libevent/Makefile b/lib/libevent/Makefile
index d29913df384..aeea81bd8c1 100644
--- a/lib/libevent/Makefile
+++ b/lib/libevent/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.39 2014/10/31 12:50:31 bluhm Exp $
+#	$OpenBSD: Makefile,v 1.40 2014/11/19 23:50:22 dlg Exp $
 
 .include <bsd.own.mk>
 
@@ -6,7 +6,7 @@ LIB=	event
 SRCS=	buffer.c evbuffer.c event.c event_tagging.c evutil.c kqueue.c \
 	log.c poll.c select.c signal.c
 HDRS=	event.h evutil.h
-MAN=	event.3
+MAN=	event.3 evbuffer_new.3
 MLINKS=	event.3 bufferevent_base_set.3 \
 	event.3 bufferevent_disable.3 \
 	event.3 bufferevent_enable.3 \
@@ -16,17 +16,6 @@ MLINKS=	event.3 bufferevent_base_set.3 \
 	event.3 bufferevent_settimeout.3 \
 	event.3 bufferevent_write.3 \
 	event.3 bufferevent_write_buffer.3 \
-	event.3 evbuffer_add.3 \
-	event.3 evbuffer_add_buffer.3 \
-	event.3 evbuffer_add_printf.3 \
-	event.3 evbuffer_add_vprintf.3 \
-	event.3 evbuffer_drain.3 \
-	event.3 evbuffer_find.3 \
-	event.3 evbuffer_free.3 \
-	event.3 evbuffer_new.3 \
-	event.3 evbuffer_read.3 \
-	event.3 evbuffer_readline.3 \
-	event.3 evbuffer_write.3 \
 	event.3 event_add.3 \
 	event.3 event_base_dispatch.3 \
 	event.3 event_base_free.3 \
@@ -58,7 +47,21 @@ MLINKS=	event.3 bufferevent_base_set.3 \
 	event.3 signal_pending.3 \
 	event.3 signal_set.3 \
 	event.3 event_asr_run.3 \
-	event.3 event_asr_abort.3
+	event.3 event_asr_abort.3 \
+	evbuffer_new.3 evbuffer_add.3 \
+	evbuffer_new.3 evbuffer_add_buffer.3 \
+	evbuffer_new.3 evbuffer_add_printf.3 \
+	evbuffer_new.3 evbuffer_add_vprintf.3 \
+	evbuffer_new.3 evbuffer_drain.3 \
+	evbuffer_new.3 evbuffer_expand.3 \
+	evbuffer_new.3 evbuffer_find.3 \
+	evbuffer_new.3 evbuffer_free.3 \
+	evbuffer_new.3 evbuffer_read.3 \
+	evbuffer_new.3 evbuffer_readline.3 \
+	evbuffer_new.3 evbuffer_readln.3 \
+	evbuffer_new.3 evbuffer_remove.3 \
+	evbuffer_new.3 evbuffer_setcb.3 \
+	evbuffer_new.3 evbuffer_write.3
 
 CFLAGS+= -I${.CURDIR} -DNDEBUG
 
diff --git a/lib/libevent/evbuffer_new.3 b/lib/libevent/evbuffer_new.3
new file mode 100644
index 00000000000..68153bb3c4c
--- /dev/null
+++ b/lib/libevent/evbuffer_new.3
@@ -0,0 +1,243 @@
+.\"	$OpenBSD: evbuffer_new.3,v 1.1 2014/11/19 23:50:22 dlg Exp $
+.\"
+.\" Copyright (c) 2014 David Gwynne <dlg@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: November 19 2014 $
+.Dt EVBUFFER_NEW 3
+.Os
+.Sh NAME
+.Nm evbuffer_new ,
+.Nm evbuffer_free ,
+.Nm evbuffer_setcb ,
+.Nm evbuffer_add ,
+.Nm evbuffer_add_buffer ,
+.Nm evbuffer_add_printf ,
+.Nm evbuffer_add_vprintf ,
+.Nm evbuffer_drain ,
+.Nm evbuffer_remove ,
+.Nm evbuffer_write ,
+.Nm evbuffer_read ,
+.Nm evbuffer_find ,
+.Nm evbuffer_readline ,
+.Nm evbuffer_readln
+.Nd libevent utility API for buffered input/output
+.Sh SYNOPSIS
+.Fd #include <event.h>
+.Ft "struct evbuffer *"
+.Fn "evbuffer_new" "void"
+.Ft void
+.Fn "evbuffer_free" "struct evbuffer *buf"
+.Ft void
+.Fn "evbuffer_setcb" "struct evbufbuffer *buf" "void (*cb)(struct evbuffer *, size_t, size_t, void *)" "void *cbarg"
+.Ft int
+.Fn "evbuffer_expand" "struct evbuffer *buf" "size_t datlen"
+.Ft int
+.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size"
+.Ft int
+.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src"
+.Ft int
+.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..."
+.Ft int
+.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap"
+.Ft void
+.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size"
+.Ft int
+.Fn "evbuffer_remove" "struct evbuffer *buf" "void *data" "size_t datlen"
+.Ft int
+.Fn "evbuffer_write" "struct evbuffer *buf" "int fd"
+.Ft int
+.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size"
+.Ft "u_char *"
+.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size"
+.Ft "char *"
+.Fn "evbuffer_readline" "struct evbuffer *buf"
+.Ft "char *"
+.Fn "evbuffer_readln" "struct evbuffer *buf" "size_t *read_out" "enum evbuffer_eol_style eol_style"
+.Sh DESCRIPTION
+The evbuffer API provides an implementation of buffering for use with
+libevent.
+.Pp
+.Fn evbuffer_new
+allocates and initialises a new evbuffer structure.
+.Pp
+.Fn evbuffer_free
+deallocates the evbuffer structure
+.Fa buf
+and any referenced storage.
+.Pp
+.Fn evbuffer_setcb
+sets the callback
+.Fa cb
+to be invoked with argument
+.Fa cbarg
+when the data in evbuffer
+.Fa buf
+is modified.
+.Pp
+.Fn evbuffer_expand
+expands the available space in
+.Fa buf
+to at least
+.Fa datlen
+bytes.
+.Pp
+.Fn evbuffer_add
+appends a copy of
+.Fa size
+bytes from buffer
+.Fa data
+to the end of the evbuffer
+.Fa buf .
+.Pp
+.Fn evbuffer_add_buffer
+moves the data off the
+.Fa src
+evbuffer and appends it to
+.Fa dst .
+.Pp
+.Fn evbuffer_add_printf
+appends a
+.Xr printf 3
+style formatted string specified by
+.Fa fmt
+to the end of
+.Fa buf .
+.Pp
+.Fn evbuffer_add_vprintf
+appends a
+.Xr vprintf 3
+style formatted string specified by
+.Fa fmt
+with a va_list
+.Fa ap
+to the end of
+.Fa buf .
+.Pp
+.Fn evbuffer_drain
+deletes
+.Fa size
+bytes from the beginning of the evbuffer
+.Fa buf .
+.Pp
+.Fn evbuffer_remove
+reads and drains up to
+.Fa datlen
+bytes from the beginning of the evbuffer
+.Fa buf
+into
+.Fa data .
+.Pp
+.Fn evbuffer_write
+writes and drains the contents of evbuffer
+.Fa buf
+to the file descriptor
+.Fa fd .
+.Pp
+.Fn evbuffer_read
+appends up to
+.Fa size
+bytes on to the end of the evbuffer
+.Fa buf
+by reading from the file descriptor
+.Fa fd .
+.Pp
+.Fn evbuffer_find
+finds the
+.Fa size
+length string
+.Fa data
+in the evbuffer
+.Fa buf .
+.Pp
+.Fn evbuffer_readline
+reads and drains a single line from the evbuffer
+.Fa buf .
+A line is delimited by "\\n", "\\r", "\\r\\n", or "\\n\\r".
+It is the responsibility of the caller to free the returned line with
+.Xr free 3 .
+.Pp
+.Fn evbuffer_readln
+reads and drains a single line from the evbuffer
+.Fa buf .
+The length of the line will be stored in
+.Fa read_out
+on success.
+It is the responsibility of the caller to free the returned line with
+.Xr free 3 .
+The line delimiter is specified as one of the following:
+.Bl -tag -width xxx -offset indent
+.It Dv EVBUFFER_EOL_ANY
+Any sequence of newline or carriage return characters.
+.It Dv EVBUFFER_EOL_CRLF
+A new line optionally preceded by a carriage return.
+.It Dv EVBUFFER_EOL_CRLF_STRICT
+A carriage return followed by a new line character.
+.It Dv EVBUFFER_EOL_LF
+A new line character.
+.El
+.Sh RETURN VALUES
+.Fn evbuffer_new
+returns a pointer to a newly allocated buffer On success,
+or
+.Dv NULL
+on failure and sets errno to indicate the failure.
+.Pp
+.Fn evbuffer_expand ,
+.Fn evbuffer_add ,
+and
+.Fn evbuffer_add_buffer
+return 0 on success,
+or -1 on failure and set errno to indicate the failure.
+.Pp
+.Fn evbuffer_add_printf ,
+and
+.Fn evbuffer_add_vprintf
+returns the number of bytes added on success,
+or -1 on failure.
+.Pp
+.Fn evbuffer_remove
+returns the number of bytes read.
+.Pp
+.Fn evbuffer_write
+returns the number of bytes written and drained on success,
+or -1 on failure and sets errno to indicate the failure.
+.Pp
+.Fn evbuffer_read
+returns the number of bytes appended to the evbuffer on success,
+or -1 on failure and sets errno to indicate the failure.
+.Pp
+.Fn evbuffer_find
+returns a pointer to the start of the string within the evbuffer on success,
+or
+.Dv NULL
+on failure.
+.Pp
+.Fn evbuffer_readline ,
+and
+.Fn evbuffer_readln
+return a pointer to the line on success,
+or
+.Dv NULL
+on failure.
+.Sh SEE ALSO
+.Xr errno 2 ,
+.Xr event 3 ,
+.Xr free 3 ,
+.Xr printf 3
+.Sh AUTHORS
+The
+.Nm event
+library was written by
+.An Niels Provos .
diff --git a/lib/libevent/event.3 b/lib/libevent/event.3
index 112657f7760..290e68d0219 100644
--- a/lib/libevent/event.3
+++ b/lib/libevent/event.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: event.3,v 1.44 2014/11/19 20:29:03 jmc Exp $
+.\"	$OpenBSD: event.3,v 1.45 2014/11/19 23:50:22 dlg Exp $
 .\"
 .\" Copyright (c) 2000 Artur Grabowski <art@openbsd.org>
 .\" All rights reserved.
@@ -66,17 +66,6 @@
 .Nm bufferevent_disable ,
 .Nm bufferevent_settimeout ,
 .Nm bufferevent_base_set ,
-.Nm evbuffer_new ,
-.Nm evbuffer_free ,
-.Nm evbuffer_add ,
-.Nm evbuffer_add_buffer ,
-.Nm evbuffer_add_printf ,
-.Nm evbuffer_add_vprintf ,
-.Nm evbuffer_drain ,
-.Nm evbuffer_write ,
-.Nm evbuffer_read ,
-.Nm evbuffer_find ,
-.Nm evbuffer_readline ,
 .Nm event_asr_run ,
 .Nm event_asr_abort
 .Nd execute a function when a specific event occurs
@@ -161,28 +150,6 @@
 .Fn "bufferevent_settimeout" "struct bufferevent *bufev" "int timeout_read" "int timeout_write"
 .Ft int
 .Fn "bufferevent_base_set" "struct event_base *base" "struct bufferevent *bufev"
-.Ft "struct evbuffer *"
-.Fn "evbuffer_new" "void"
-.Ft void
-.Fn "evbuffer_free" "struct evbuffer *buf"
-.Ft int
-.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size"
-.Ft int
-.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src"
-.Ft int
-.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..."
-.Ft int
-.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap"
-.Ft void
-.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size"
-.Ft int
-.Fn "evbuffer_write" "struct evbuffer *buf" "int fd"
-.Ft int
-.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size"
-.Ft "u_char *"
-.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size"
-.Ft "char *"
-.Fn "evbuffer_readline" "struct evbuffer *buf"
 .Ft "struct event_asr *"
 .Fn event_asr_run "struct asr_query *aq" "void (*fn)(struct asr_result *, void *)" "void *"
 .Ft "void"