Welcome to little lamb

Code » limb » release » tree

[release] / src / doc / stralloc.h / stralloc_ready_tuned.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
% limb manual
% stralloc_ready(3)
% limb 0.1.0
% 2023-07-24

# NAME

stralloc_ready_tuned, stralloc_readyplus_tuned, stralloc_ready,
stralloc_readyplus, stralloc_free, stralloc_shrink - allocate and free memory
associated with a stralloc

# SYNOPSIS

    #include <limb/stralloc.h>

```pre hl
int stralloc_ready_tuned(stralloc *<em>sa</em>, size_t <em>len</em>, size_t <em>base</em>, size_t <em>a</em>, size_t <em>b</em>)
int stralloc_readyplus_tuned(stralloc *<em>sa</em>, size_t <em>len</em>, size_t <em>base</em>, size_t <em>a</em>, size_t <em>b</em>)
int stralloc_ready(stralloc *<em>sa</em>, size_t <em>len</em>)
int stralloc_readyplus(stralloc *<em>sa</em>, size_t <em>len</em>)

void stralloc_free(stralloc *<em>sa</em>)
int stralloc_shrink(stralloc *<em>sa</em>)
```

# DESCRIPTION

The `stralloc_ready`() macro ensure that at least `len` bytes are allocated in
stralloc `sa`, reallocating memory if needed. This does not mean as much is
available, as there might be data in use already.

The `stralloc_readyplus`() macro ensure that at least `len` bytes are available
in stralloc `sa`, reallocating memory if needed. Available here means space
that is allocated but not yet in use, making this the most commonly used way to
prepare a *stralloc* before writing data into it.

The `stralloc_ready_tuned`() is similar to `stralloc_ready`() but with more
fine-tuning settings.

The `stralloc_readyplus_tuned`() is similar to `stralloc_ready_tuned`() but for
adding `len` bytes to the currently in-use size.

Note that this is only needed when writing into the *stralloc* directly, as all
functions of the *stralloc* API (e.g. [stralloc_catb](3)) handles that
automatically.

The `stralloc_shrink`() function will ensure that the allocated memory is only
as large as is in use in stralloc `sa`.

The `stralloc_free`() function will free all memory associated with the stralloc
`sa`.

# RETURN VALUE

These functions (except for `stralloc_free`()) return 1 on success. Otherwise
they return 0 and set `errno` to indicate the error.

# ERRORS

These functions (except for `stralloc_free`()) may fail if :

: *ENOMEM*
:: Out of memory.

The `stralloc_ready_tuned`(), `stralloc_ready`(), `stralloc_readyplus_tuned`()
and `stralloc_readyplus`() functions may also fail if :

: *EINVAL*
:: The `base` is zero.

: *ERANGE*
:: Overflow.

# SEE ALSO

[stralloc_remove](3)