#ifndef _WRITEV_H_514ae765_
#define _WRITEV_H_514ae765_

/* This file is in the public domain. */

/*
 * Package for accumulating blocks-to-be-written into struct iovec
 *  arrays, primarily for use with writev().
 */

#include <sys/uio.h>

/*
 * writev_open_cb sets up to accumulate memory blocks.  The argument is
 *  a function which is called when the accumulated blocks are to be
 *  flushed (which happens when various limits are reached, or no later
 *  than writev_close time in any case).  It returns a void * handle
 *  which must be passed as the first argument to the other calls.
 *
 * writev_copy queues a block of data to be written.  The block is
 *  copied; the data pointed to need not remain valid past when
 *  writev_copy returns.  The copy is freed at some indeterminate point
 *  soon after the callback call which flushes it is made (but no later
 *  than the point at which writev_close returns).
 *
 * writev_point queues a block of data to be written.  The block is not
 *  copied; the data pointed to must remain valid until it gets flushed
 *  (and possibly later, depending on what the callback does with it).
 *  (The block actually need not be valid as far as the writev package
 *  is concerned; the pointer and length are simply saved in a struct
 *  iovec, and their validity requirements, if any, are actually
 *  imposed by the callback.)
 *
 * writev_free is just like writev_point except that it frees the
 *  pointed-to block at some indeterminate point soon after the
 *  callback call which flushes it is made (but no later than the point
 *  at which writev_close returns).
 *
 * writev_close closes off the sequence of data blocks.  Any unflushed
 *  accumulated blocks are flushed, then any remaining frees (for
 *  writev_copy or writev_free blocks) are done, then the handle is
 *  destroyed.
 */
extern void *writev_open_cb(void (*)(struct iovec *, int));
extern void writev_copy(void *, const void *, int);
extern void writev_point(void *, const void *, int);
extern void writev_free(void *, void *, int);
extern void writev_close(void *);

#endif