---
name: "jose_io"
section: "3"
platform: "linux"
package: "jose"
version: "15-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/jose_io"
---

# jose\_io(3)

IO Chaining.

## NAME

jose\_io - IO Chaining.

## SYNOPSIS

### Data Structures

struct **jose\_io\_t**\
 The interface for chained IO.

### Typedefs

typedef **jose\_io\_t** **jose\_io\_auto\_t**\
 Defines a **jose\_io\_t** which calls **jose\_io\_decref()** at end of scope.

### Functions

**jose\_io\_t** \* **jose\_io\_incref** (**jose\_io\_t** \*io)\
 Increases the reference count of an IO object.  void **jose\_io\_decref** (**jose\_io\_t** \*io)\
 Decreases the reference count of an IO object.  **jose\_io\_t** \* **jose\_io\_malloc** (jose\_cfg\_t \*cfg, void \*\*buf, size\_t \*len)\
 Creates a new IO object which collects data into a dynamic buffer.  void \* **jose\_io\_malloc\_steal** (void \*\*buf)\
 Steals the buffer created by the **jose\_io\_malloc()** IO object.  **jose\_io\_t** \* **jose\_io\_buffer** (jose\_cfg\_t \*cfg, void \*buf, size\_t \*len)\
 Creates a new IO object which collects data into a static buffer.  **jose\_io\_t** \* **jose\_io\_file** (jose\_cfg\_t \*cfg, FILE \*file)\
 Creates a new IO object which writes data into a FILE.  **jose\_io\_t** \* **jose\_io\_multiplex** (jose\_cfg\_t \*cfg, **jose\_io\_t** \*\*nexts, bool all)\
 Creates a new IO object which multiplexes data into multiple IO objects.

## Detailed Description

IO Chaining.

## Typedef Documentation

### typedef jose\_io\_t jose\_io\_auto\_t

Defines a **jose\_io\_t** which calls **jose\_io\_decref()** at end of scope. For example:

```
void foo() {
    uint8_t *buf = NULL;
    size_t len = 0;
    jose_io_auto_t *io = jose_io_malloc(NULL, &buf, &len);
    // jose_io_decref() implicitly called
}
```

## Function Documentation

### jose\_io\_t\* jose\_io\_incref (jose\_io\_t \* io)

Increases the reference count of an IO object. This function always succeeds.

**Parameters:**

*io* The **jose\_io\_t** entity you are using.

**Returns:**

The value of `io` (for convenience).

### void jose\_io\_decref (jose\_io\_t \* io)

Decreases the reference count of an IO object. When the reference count reaches zero, io-\>free() is called.

**Parameters:**

*io* The **jose\_io\_t** entity you are using.

### jose\_io\_t\* jose\_io\_malloc (jose\_cfg\_t \* cfg, void \*\* buf, size\_t \* len)

Creates a new IO object which collects data into a dynamic buffer. The dynamic buffer is allocated into the `buf` pointer you provided and the length of the buffer is stored in `len`. The pointer referenced by `buf` must remain valid for the entire duration of the returned IO object.

The default behavior is for the IO object to zero and free the buffer when it is freed. This means that, by default, you own the buffer pointer but the buffer itself is owned by the IO object. You can, however, steal the buffer by setting the buffer pointer to NULL.

**See also:**

**jose\_io\_malloc\_steal()**

**Parameters:**

*cfg* The configuration context (optional). \
 *buf* A buffer pointer pointer. \
 *len* A pointer to the length of the buffer.

**Returns:**

The new IO object or NULL on error.

### void\* jose\_io\_malloc\_steal (void \*\* buf)

Steals the buffer created by the **jose\_io\_malloc()** IO object. This convenience function simply returns the value of `*buf` and then sets `*buf` to NULL.

**See also:**

**jose\_io\_malloc()**

**Parameters:**

*buf* A pointer to the buffer pointer.

**Returns:**

The value of `*buf` before it is set to NULL.

### jose\_io\_t\* jose\_io\_buffer (jose\_cfg\_t \* cfg, void \* buf, size\_t \* len)

Creates a new IO object which collects data into a static buffer. The size of `buf` MUST be specified in the variable pointed to by `len`. This will be the maximum data written. However, after the function returns, the variable pointed to by `len` will contain the current length of data in the buffer.

Unlike **jose\_io\_malloc()**, you own the buffer and it is not zeroed or freed when the IO object is freed.

**Parameters:**

*cfg* The configuration context (optional). \
 *buf* A buffer pointer. \
 *len* A pointer to the length of the buffer.

**Returns:**

The new IO object or NULL on error.

### jose\_io\_t\* jose\_io\_file (jose\_cfg\_t \* cfg, FILE \* file)

Creates a new IO object which writes data into a FILE. This function DOES NOT take ownership of the FILE. You are still responsible for calling fclose() at the appropriate time.

**Parameters:**

*cfg* The configuration context (optional). \
 *file* The output file which MUST be opened for writing or appending.

**Returns:**

The new IO object or NULL on error.

### jose\_io\_t\* jose\_io\_multiplex (jose\_cfg\_t \* cfg, jose\_io\_t \*\* nexts, bool all)

Creates a new IO object which multiplexes data into multiple IO objects. If `all` is true, the success of all `nexts` is required. Otherwise, all but one of the `nexts` can fail before the error is propagated upward.

**Parameters:**

*cfg* The configuration context (optional). \
 *nexts* A NULL-terminated array of IO object pointers. \
 *all* Whether or not the success of all `nexts` is required.

**Returns:**

The new IO object or NULL on error.

## Author

Generated automatically by Doxygen for José from the source code.