Add evbuffer_copyout to copy data from an evbuffer without draining

The evbuffer_remove() function copies data from the front of an
evbuffer into an array of char, and removes the data from the buffer.
This function behaves the same, but does not remove the data.  This
behavior can be handy for lots of protocols, where you want the
evbuffer to accumulate data until a complete record has arrived.

Lots of people have asked for a function more or less like this, and
though it isn't too hard to code one from evbuffer_peek(), it is
apparently annoying to do it in every app you write.  The
evbuffer_peek() function is significantly faster, but it requires that
the user be able to handle data in separate extents.

This patch also reimplements evbufer_remove() as evbuffer_copyout()
followed by evbuffer_drain().  I am reasonably confident that this
won't be a performance hit: the memcpy() overhead should dominate the
cost of walking the list an extra time.

1 files changed, 10 insertions, 0 deletions

diff --git a/include/event2/buffer.h b/include/event2/buffer.h
index 8fb5c3d0..bd175c25 100644
--- a/include/event2/buffer.h
+++ b/include/event2/buffer.h
@@ -268,6 +268,16 @@ int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
 int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen);
 
 /**
+  Read data from an event buffer, and leave the buffer unchanged.
+
+  @param buf the event buffer to be read from
+  @param data the destination buffer to store the result
+  @param datlen the maximum size of the destination buffer
+  @return the number of bytes read, or -1 if we can't drain the buffer.
+ */
+ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen);
+
+/**
   Read data from an event buffer into another event buffer draining
   the bytes from the src buffer read.  This function avoids memcpy
   as possible.