Welcome to little lamb

Code » limb » release » tree

[release] / src / doc / buffer.h / buffer_get.3.md 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
% limb manual
% buffer_get(3)
% limb 0.1.0
% 2023-07-24

# NAME

buffer_get, buffer_getv, buffer_getall, buffer_getvall, buffer_getnofill,
buffer_getvnofill, buffer_getallnofill, buffer_getvallnofill - load data into a
reading I/O buffer

# SYNOPSIS

    #include <limb/buffer.h>

```pre hl
ssize_t buffer_get(buffer *<em>buf</em>, char *<em>dst</em>, size_t <em>dlen</em>)
ssize_t buffer_getv(buffer *<em>buf</em>, struct iovec *<em>v</em>, unsigned <em>vlen</em>)

int buffer_getall(buffer *<em>buf</em>, char *<em>dst</em>, size_t <em>dlen</em>, size_t *<em>written</em>)
int buffer_getvall(buffer *<em>buf</em>, const struct iovec *<em>v</em>, unsigned <em>vlen</em>, size_t *<em>written</em>)

size_t buffer_getnofill(buffer *<em>buf</em>, char *<em>dst</em>, size_t <em>dlen</em>)
size_t buffer_getvnofill(buffer *<em>buf</em>, const struct iovec *<em>v</em>, unsigned <em>vlen</em>)

int buffer_getallnofill(buffer *<em>buf</em>, char *<em>dst</em>, size_t <em>dlen</em>)
int buffer_getvallnofill(buffer *<em>buf</em>, const struct iovec *<em>v</em>, unsigned <em>vlen</em>)
```

# DESCRIPTION

The `buffer_get`() function will copy into the memory pointed by `dst` of length
`dlen` data from the buffer pointed by `buf`. It will try to put as much data as
possible, i.e. place `dlen` bytes, filing the buffer if needed. It might copy
less if end-of-file was reached.

Any data copied from the buffer is then "removed" from it, i.e. the
corresponding space in the buffer's internal memory becomes available.

The `buffer_getv`() function is similar to `buffer_get`() only copying data into
the memory as described by the array of vectors pointed by `v` of length `vlen`.

The `buffer_getall`() function is similar to `buffer_get`(), except that it will
copy data into the memory location pointed by `dst` starting at offset whose
value is pointed by `written` (usually 0), updating it as it writes data read
from the buffer.

The `buffer_getvall`() function is similar to `buffer_getall`() only copying
data into the memory as described by the array of vectors pointed by `v` of
length `vlen`.

The `buffer_getnofill`() macro is similar to `buffer_get`() except that it
will *not* fill the buffer, returning the size of data actually copied into the
memory pointed by `dst` - which may or may not be the full `dlen` size.

The `buffer_getvnofill`() macro is similar to `buffer_getnofill`() only copying
data into the memory as described by the array of vectors pointed by `v` of
length `vlen`.

The `buffer_getallnofill`() function is similar to `buffer_getnofill`() except
that if the entirety of the data cannot be copied from the buffer, it fails
without removing /any/ data from it.

The `buffer_getvallnofill`() function is similar to `buffer_getallnofill`() only
copying data into the memory as described by the array of vectors pointed by `v`
of length `vlen`.


# RETURN VALUE

The `buffer_get`() and `buffer_getv`() functions return the size of data read
from the buffer (and copied into the specified location(s)) on success, which
may be less than requested if end-of-file was reached.
Otherwise they return -1 and set `errno` to indicate the error.

The `buffer_getall`() and `buffer_getvall`() functions return 1 when all
requested data have been copied from the buffer. They return 0 when less data
was copied (possibly none) and the buffer couldn't be filled due to *EAGAIN* or
*EWOULDBLOCK* errors from the buffer's operational function.
Otherwise, they return -1 and set `errno` to indicate the error.

The `buffer_getnofill`() and `buffer_getvnofill`() macros return the amount of
data copied from the buffer. They cannot fail, though the returned amount might
be less than requested, even 0 if the buffer if empty.

The `buffer_getallnofill`() and `buffer_getvallnofill`() functions return 1 when
all requested data was copied from the buffer. Otherwise they return 0 set set
`errno` to indicate the error.


# ERRORS

The `buffer_get`() and `buffer_getv`() functions may fail for any of the errors
for their operational function, as set via e.g. [buffer_init](3).

The `buffer_getall`() and `buffer_getvall`() functions may fail if :

: *EINVAL*
:: The value pointed by `written` is more than available in destination (e.g.
:: more than `dlen`).

: *EPIPE*
:: End of file was reached, i.e. the operational function returned 0.

The `buffer_getall`() and `buffer_getvall`() functions may also fail and set
`errno` for any of the errors for their operational function, save *EAGAIN* or
*EWOULDBLOCK* for which they would return 0 instead.

The `buffer_getallnofill`() and `buffer_getvallnofill`() functions may fail if :

: *ENOBUFS*
:: The requested amount of data cannot be read from the buffer, i.e. there
:: isn't that much data in the buffer's internal memory.


# SEE ALSO

[buffer_gethdr](3), [buffer_getuptoc](3), [buffer_patrim_get](3)