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

# NAME

siov_gather, siov_gather0, siov_seek_gather, siov_seek_gather0 - gather data
from an array of vectors into a byte array

# SYNOPSIS

    #include <limb/siovec.h>

```pre hl
size_t siov_gather(char *<em>dst</em>, size_t <em>dlen</em>, const struct iovec *<em>v</em>, unsigned int <em>n</em>)
size_t siov_gather0(char *<em>dst</em>, size_t <em>dlen</em>, const struct iovec *<em>v</em>, unsigned int <em>n</em>)

size_t siov_seek_gather(char *<em>dst</em>, size_t <em>dlen</em>, const struct iovec *<em>v</em>, unsigned int <em>n</em>, size_t <em>offset</em>)
size_t siov_seek_gather0(char *<em>dst</em>, size_t <em>dlen</em>, const struct iovec *<em>v</em>, unsigned int <em>n</em>, size_t <em>offset</em>)
```

# DESCRIPTION

The `siov_gather`() function gathers data scattered across the array `v` of `n`
vectors into the byte array pointed by `dst` of `dlen` bytes.

You can think of it as the opposite of [siov_scatter](3).

The `siov_gather0`() function is similar to `siov_gather`() but ensures that the
data placed into `s` is NUL-terminated, meaning that it /ends/ with a NUL byte
(not checking whether there were in the middle of it).

If a trailing NUL byte was already present, it does nothing more than
`siov_gather`(), else it will add one - possibly overwriting the last character
gathered if `dlen` was reached.

The `siov_seek_gather`() function is similar to `siov_gather`() only skipping
the first `offset` bytes of data.

The `siov_seek_gather0`() function is similar to `siov_seek_gather`() but
similarly ensures the data placed into `s` is NUL terminated.

# RETURN VALUE

These functions return the number of bytes copied into `dst` (including the
added terminating NUL byte, if any).

# SEE ALSO

[siov_seek](3), [siov_scatter](3), [siov_deal](3)