Welcome to little lamb

Code » limb » release » tree

[release] / src / doc / buffer.h / buffer_put.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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
% limb manual
% buffer_put(3)
% limb 0.1.0
% 2023-07-24

# NAME

buffer_put, buffer_putv, buffer_puts, buffer_putall, buffer_putvall,
buffer_putsall, buffer_putnoflush, buffer_putvnoflush, buffer_putsnoflush,
buffer_putflush, buffer_putvflush, buffer_putsflush, buffer_putallflush,
buffer_putvallflush, buffer_putsallflush, buffer_putallnoflush,
buffer_putvallnoflush, buffer_putsallnoflush - write data into a writing I/O
buffer

# SYNOPSIS

    #include <limb/buffer.h>

```pre hl
ssize_t buffer_put(buffer *<em>buf</em>, const char *<em>data</em>, size_t <em>dlen</em>)
ssize_t buffer_putv(buffer *<em>buf</em>, const struct iovec *<em>v</em>, unsigned <em>vlen</em>)
ssize_t buffer_puts(buffer *<em>buf</em>, const char *<em>str</em>)

int buffer_putall(buffer *<em>buf</em>, const char *<em>data</em>, size_t <em>dlen</em>, size_t *<em>written</em>)
int buffer_putvall(buffer *<em>buf</em>, const struct iovec *<em>v</em>, unsigned <em>vlen</em>, size_t *<em>written</em>)
int buffer_putsall(buffer *<em>buf</em>, const char *<em>str</em>, size_t *<em>written</em>)

size_t buffer_putnoflush(buffer *<em>buf</em>, const char *<em>data</em>, size_t <em>dlen</em>)
size_t buffer_putvnoflush(buffer *<em>buf</em>, const struct iovec *<em>v</em>, unsigned <em>vlen</em>)
size_t buffer_putsnoflush (buffer *<em>buf</em>, const char *<em>str</em>)

ssize_t buffer_putflush(buffer *<em>buf</em>, const char *<em>data</em>, size_t <em>dlen</em>)
ssize_t buffer_putvflush(buffer *<em>buf</em>, const struct iovec *<em>v</em>, unsigned <em>vlen</em>)
ssize_t buffer_putsflush(buffer *<em>buf</em>, const char *<em>str</em>)

int buffer_putallflush(buffer *<em>buf</em>, const char *<em>data</em>, size_t <em>dlen</em>, size_t *<em>written</em>)
int buffer_putvallflush(buffer *<em>buf</em>, const struct iovec *<em>v</em>, unsigned <em>vlen</em>, size_t *<em>written</em>)
int buffer_putsallflush(buffer *<em>buf</em>, const char *<em>str</em>, size_t *<em>written</em>)

int buffer_putallnoflush(buffer *<em>buf</em>, const char *<em>data</em>, size_t <em>dlen</em>)
int buffer_putvallnoflush(buffer *<em>buf</em>, const struct iovec *<em>v</em>, unsigned <em>vlen</em>)
int buffer_putsallnoflush(buffer *<em>buf</em>, const char *<em>str</em>)
```

# DESCRIPTION

The `buffer_put`() function will write data pointed by `data` of length `dlen`
into the buffer pointed by `buf`. Said data are simply copied into the buffer's
internal memory. If the buffer gets full before all data can been copied, it
will be flushed in order to place the remaining data into its internal memory.

The `buffer_putv`() function is similar to `buffer_put`() only reading data from
the array of vectors pointed by `v` of length `vlen`.

The `buffer_puts`() function is similar to `buffer_put`() only reading the
memory pointed by `str`, which must be NUL-terminated.

! INFO: NUL-terminated strings
! Note that for the `buffer_puts*`() family of functions, the data put into
! the buffer is only that /up to/ - and thus excluding - the NUL-terminating
! byte.

The `buffer_putall`() function is similar to `buffer_put`(), except that it will
put into the buffer the data starting at offset whose value is pointed by
`written` (usually 0), updating it as it writes data into the buffer.
As a result, the size written into the buffer will have been added into the
value pointed by `written`.

The `buffer_putvall`() function is similar to `buffer_putall`() only reading
data from the array of vectors pointed by `v` of length `vlen`. Note that as
expected, the value pointed by `written` must the be offset (in bytes) into the
data represented by `v`.

The `buffer_putsall`() function is similar to `buffer_putall`() only reading the
memory pointed by `str`, which must be NUL-terminated.

The `buffer_putnoflush`() macro is similar to `buffer_put`() except that it
will *not* flush the buffer, returning the size of data actually placed into the
buffer - which may or may not be the full `dlen` size.

The `buffer_putvnoflush`() macro is similar to `buffer_putnoflush`() only
reading data from the array of vectors pointed by `v` of length `vlen`.

The `buffer_putsnoflush`() function is similar to `buffer_putnoflush`() only
reading the memory pointed by `str`, which must be NUL-terminated.

The `buffer_putflush`() function is similar to `buffer_put`() but will always
flush the buffer afterwards, leaving it - on success - empty.

The `buffer_putvflush`() function is similar to `buffer_putflush`() only reading
data from the array of vectors pointed by `v` of length `vlen`.

The `buffer_putsflush`() function is similar to `buffer_putflush`() only reading
the memory pointed by `str`, which must be NUL-terminated.

The `buffer_putallflush`() macro is similar to `buffer_putall`() but will always
flush the buffer afterwards.

The `buffer_putvallflush`() macro is similar to `buffer_putallflush`() only
reading data from the array of vectors pointed by `v` of length `vlen`.

The `buffer_putsallflush`() function is similar to `buffer_putallflush`() only
reading the memory pointed by `str`, which must be NUL-terminated.

The `buffer_putallnoflush`() function is similar to `buffer_putnoflush`() except
that if the entirety of the data cannot be placed into the buffer, it fails
without placing /any/ data into it.

The `buffer_putvallnoflush`() function is similar to `buffer_putallnoflush`()
only reading data from the array of vectors pointed by `v` of length `vlen`.

The `buffer_putsallnoflush`() function is similar to `buffer_putallnoflush`()
only reading the memory pointed by `str`, which must be NUL-terminated.


# RETURN VALUE

The `buffer_put`(), `buffer_putv`(), `buffer_puts`(), `buffer_putflush`(),
`buffer_putvflush`() and `buffer_putsflush`() functions return the size of data
placed into the buffer on success. Otherwise, they return -1 and set `errno` to
indicate the error.

The `buffer_putnoflush`(), `buffer_putvnoflush`() and `buffer_putsnoflush`()
functions return the size of data placed into the buffer. They cannot fail,
although the size returned might be less than the full data size if the buffer
lacked space in its internal memory.

The `buffer_put{,v,s}all*` family of functions all return 1 on success.
Otherwise they return 0 and set `errno` to indicate the error.

# ERRORS

These functions may fail and set `errno` for any of the errors specified for
[buffer_flush](3).

The `buffer_put{,v,s}all*` family of functions may also fail if :

: *EINVAL*
:: The value pointed by `written` is more than the full data size.

# SEE ALSO

[buffer_putmsg](3), [buffer_putesc](3), [buffer_puthex](3),
[buffer_putbase32](3), [buffer_putbase64](3), [buffer_puthdr](3),
[buffer_patrim_put](3)