Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / obuffer.h / obuffer_attach.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
% limb manual
% obuffer_attach(3)
% limb 0.1.0
% 2023-07-24

# NAME

obuffer\_attach, obuffer\_detach, obuffer\_is\_attached - manage chains of
output buffers

# SYNOPSIS

    #include <limb/obuffer.h>

```pre hl
int obuffer_attach(obuffer *<em>obuf</em>, obuffer *<em>to</em>)
int obuffer_detach(obuffer *<em>obuf</em>)
int obuffer_is_attached(obuffer *<em>obuf</em>)
```

# DESCRIPTION

The `obuffer_attach`() function will attach the output buffer pointed by `obuf`
to the one pointed by `to`, effectively joining its chain (or creating a new one
with both output buffers if the output buffer `to` wasn't in a chain yet).

The `obuffer_detach`() function will detach the output buffer pointed by `obuf`
from its current chain. It is then possible to attach it to a new chain if
needed.

The `obuffer_is_attached`() macro returns 1 if the output buffer pointed by
`obuf` is attached to another one, and therefore part of a chain. Otherwise it
returns zero.

## Chain of output buffers

In addition to having data only written to their underlying buffer /if/ their
level matches that associated with the data (see [obuffer_level](3) for more),
the other idea behind output buffers is the ability to "link" them together, or
/attach/ one output buffer to another.

Upon creation, an output buffer is "independent", i.e. not attached to any
other, not part of any chain. In such a state, any data sent to it will simply
to written to it (assuming levels match, as hinted above).

However, once attached to another, they form a so-called /chain/. From this
point on, any data sent to either one will also be sent to the other. And
because you can have more than 2 output buffers in a chain, any data sent to
any of the output buffers in the chain will result if all of them getting the
data (again, assuming their own levels allow it).

One output buffer cannot be attached to more than one output buffer, more
precisely only an independent output buffer can be attached to another. After
that, others (independent) can be attached /to/ it, but /it/ cannot be attached
anymore.

In other words, it is not possible to join/attach two chains together.

# RETURN VALUE

The `obuffer_attach`() and `obuffer_detach`() functions return 1 on success.
Otherwise they return 0 and set `errno` to indicate the error.

The `obuffer_is_attached`() macro returns 1 if the output buffer pointed by
`obuf` is attached/part of a chain. Otherwise it returns 0.

# ERRORS

The `obuffer_attach`() may fail if :

: *EINVAL*
:: The output buffer pointed by `obuf` is already attached/part of a chain.

The `obuffer_detach`() function may fail if :

: *EINVAL*
:: The output buffer pointed by `obuf` is not attached/part of a chain.