NAME

obuffer_attach, obuffer_detach, obuffer_is_attached - manage chains of output buffers

SYNOPSIS

#include <limb/obuffer.h>

int obuffer_attach(obuffer *obuf, obuffer *to)
int obuffer_detach(obuffer *obuf)
int obuffer_is_attached(obuffer *obuf)

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 :

The obuffer_detach() function may fail if :