---
name: "rbuf_own"
section: "3"
platform: "linux"
package: "libroy-dev"
version: "1.0.8-1"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/rbuf_own"
---

# rbuf\_own(3)

rbuf ownership

## NAME

rbuf\_own, rbuf\_release, rbuf\_owned - rbuf ownership

## SYNOPSIS

\#include \<roy.h\>

void rbuf\_own (RBuf \**buf*);

void rbuf\_release (RBuf \**buf*);

int rbuf\_owned (RBuf \**buf*);

RBuf \* rbuf\_copy\_if\_owned (RBuf \**buf*);

## DESCRIPTION

This is NOT a full-blown refcount system, so multiple calls to [*rbuf\_own*(3)](/rbuf_own/3.md) does NOT increment the number of owners. This system is useful for programmers writing consumer/producer style software and they want to do as little memory frobbing as possible.

If *buf* is already owned by someone else, the programmer should respect that and not change it. Instead, the programmer should make a copy of it, and work with a copy.

After a call to [*rbuf\_own*(3)](/rbuf_own/3.md), *buf* cannot be [*rbuf\_free*(3)](/rbuf_free/3.md)'ed, until after a call to *rbuf\_release*(3). The programmer can find out if *buf* has been owned by calling *rbuf\_owned*(3).

*rbuf\_copy\_if\_owned*(3) is a convenience function that will copy an RBuf if it is already owned.  This allows the consumer to know for certain that it will have a copy it can [*rbuf\_own*(3)](/rbuf_own/3.md).

- CONSUMER/PRODUCER EXAMPLE

  This is the proper way to use the rbuf ownership system.

```
        void start (void)
        {
                producer ();
                finish ();
        }
```

```
        void producer (void)
        {
                RBuf * buf;
```

```
                /* We create a real rbuf here, but we could just as easily
                 * use rbuf_auto().  In our example, the buf will be owned
                 * in the consume function, and free below will be ignored.
                 * Had rbuf_auto() been used, the buf would have been
                 * owned (it is owned by the text segment so to speek), and
                 * a copy would have been made in the consume() function. */
                buf = rbuf_new_with_str ("Produced");
                consume (buf);
```

```
                /* We can blindly call free on the buf here because if it
                 * is owned, the call will be ignored, otherwise, it will
                 * really be free()'d */
                rbuf_free (buf);        /* Consumer might own buf. */
```

```
        }
```

```
        RBuf * saved = NULL;
        void consume (RBuf * buf)
        {
                /* Some made up logic to see if we need to keep a copy of this buf */
                if (keep_this_rbuf (buf))
                {
                        /* Now, if buf is owned by the calling function, we
                         * make a copy.  If it is not, we simply claim ownership
                         * of the buffer, and save it */
                        if (rbuf_owned (buf))
                                buf = rbuf_new_with_rbuf (buf);
                        rbuf_own (buf);
```

```
                        saved = buf;            /* Save off buf. */
                }
        }
```

```
        void finish (void)
        {
                /* Use saved for stuff. */
```

```
                /* Do the cleanup.  rbuf_release() is required before rbuf_free(),
                 * as rbuf_free() is ignored for owned rbufs */
                rbuf_release (saved);
                rbuf_free (saved);
        }
```

## RETURN VALUE

Calls to [*rbuf\_own*(3)](/rbuf_own/3.md) and *rbuf\_release*(3) don't return a value.

A call to *rbuf\_owned*(3) returns TRUE if *buf* is owned because of a previous call to [*rbuf\_own*(3)](/rbuf_own/3.md), or FALSE if there is no owner.

A call to *rbuf\_copy\_if\_owned*(3) will return a pointer to *buf* if *buf* was unowned.  If owned, a copy of *buf* will be created and returned.

## ERRORS

Calls to [*rbuf\_own*(3)](/rbuf_own/3.md), *rbuf\_release*(3), and *rbuf\_owned*(3) never fail.

## MACRO

The rbuf ownership api calls are implemented using macros.

## SEE ALSO

[*rbuf*(3)](/rbuf/3.md), [*rbuf\_append*(3)](/rbuf_append/3.md),  [*rbuf\_append\_char*(3)](/rbuf_append_char/3.md), [*rbuf\_append\_data*(3)](/rbuf_append_data/3.md),  [*rbuf\_append\_rbuf*(3)](/rbuf_append_rbuf/3.md), [*rbuf\_append\_sprintf*(3)](/rbuf_append_sprintf/3.md),  [*rbuf\_append\_str*(3)](/rbuf_append_str/3.md), [*rbuf\_append\_vsprintf*(3)](/rbuf_append_vsprintf/3.md),  [*rbuf\_auto*(3)](/rbuf_auto/3.md), [*rbuf\_down*(3)](/rbuf_down/3.md),  [*rbuf\_empty*(3)](/rbuf_empty/3.md), [*rbuf\_equal*(3)](/rbuf_equal/3.md),  [*rbuf\_equal\_data*(3)](/rbuf_equal_data/3.md), [*rbuf\_equal\_rbuf*(3)](/rbuf_equal_rbuf/3.md),  [*rbuf\_equal\_rbuf\_len*(3)](/rbuf_equal_rbuf_len/3.md), [*rbuf\_equal\_rbufcase*(3)](/rbuf_equal_rbufcase/3.md),  [*rbuf\_equal\_str*(3)](/rbuf_equal_str/3.md), [*rbuf\_equal\_str\_len*(3)](/rbuf_equal_str_len/3.md),  [*rbuf\_equal\_strcase*(3)](/rbuf_equal_strcase/3.md), [*rbuf\_erase*(3)](/rbuf_erase/3.md),  [*rbuf\_float*(3)](/rbuf_float/3.md), [*rbuf\_free*(3)](/rbuf_free/3.md),  [*rbuf\_hash*(3)](/rbuf_hash/3.md), [*rbuf\_insert*(3)](/rbuf_insert/3.md),  [*rbuf\_last*(3)](/rbuf_last/3.md), [*rbuf\_len*(3)](/rbuf_len/3.md),  [*rbuf\_long*(3)](/rbuf_long/3.md), [*rbuf\_new*(3)](/rbuf_new/3.md),  [*rbuf\_new\_with\_sprintf*(3)](/rbuf_new_with_sprintf/3.md), [*rbuf\_prepend*(3)](/rbuf_prepend/3.md),  [*rbuf\_prepend\_char*(3)](/rbuf_prepend_char/3.md), [*rbuf\_prepend\_data*(3)](/rbuf_prepend_data/3.md),  [*rbuf\_prepend\_rbuf*(3)](/rbuf_prepend_rbuf/3.md), [*rbuf\_prepend\_str*(3)](/rbuf_prepend_str/3.md),  [*rbuf\_rdonly*(3)](/rbuf_rdonly/3.md), [*rbuf\_set\_to*(3)](/rbuf_set_to/3.md),  [*rbuf\_split*(3)](/rbuf_split/3.md), [*rbuf\_sprintf*(3)](/rbuf_sprintf/3.md),  [*rbuf\_str*(3)](/rbuf_str/3.md), [*rbuf\_truncate*(3)](/rbuf_truncate/3.md),  [*rbuf\_up*(3)](/rbuf_up/3.md), [*roy*(3)](/roy/3.md)