% limb manual
% buffer_wpeek(3)
% limb 0.1.0
% 2023-07-24

# NAME

buffer_wpeek, buffer_wseek - peek/seek into a writing I/O buffer

# SYNOPSIS

    #include <limb/buffer.h>

```pre hl
void buffer_wpeek(buffer *<em>buf</em>, struct iovec <em>v</em>[2])
size_t buffer_wseek(buffer *<em>buf</em>, size_t <em>len</em>)
```

# DESCRIPTION

The `buffer_wpeek`() macro allows to peek into a writing buffer's available
space. The array of vectors pointed by `v` will be set to the available space
inside the memory of the buffer pointed by `buf` currently unused (and which
could therefore can be written into).

The `buffer_wseek`() macro will update the internals of the buffer pointed by
`buf` to add the next `len` bytes of data from its internal memory space.

! NOTE:
! Because a buffer's internal memory is kept as a circular buffer (see
! [cbuffer.h](0) for more), the data might not be stored as a continuous block
! and requires a couple of vectors to possibly get the full space. Note than it
! is possible the second vector will be set to zero if not needed, however `v`
! should always point to an array of 2 elements.

Typically, one would use `buffer_wpeek`() to get the locations where to write
data, and after all went well use `buffer_wseek`() to have said data
"incorporated" into the buffer.

# RETURN VALUE

The `buffer_wseek`() function returns the amount of bytes in use by which its
internal buffer grew, which may be less than `len` (even 0 if the buffer was
full).

# SEE ALSO

[buffer_unput](3)