jose_io(3)

✨ jose_io — IO Chaining ✨

okay bestie, welcome to jose_io 💖 this is the page from the José library's manual (section 3, library functions — iykyk), and it's literally all about IO Chaining. that's it, that's the whole vibe. let's get into it 🫶

---

🌸 SYNOPSIS 🌸

🎀 Data Structures

• struct jose_io_t — the interface for chained IO. the main character, honestly 👑

🦋 Typedefs

• typedef jose_io_t jose_io_auto_t — defines a jose_io_t which calls jose_io_decref() at end of scope. so it cleans up after itself, no cap ✨

🌈 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. that's it. that's the description. short king energy but we love it 💅

---

🧚 Typedef Documentation 🧚

typedef jose_io_t jose_io_auto_t

Defines a jose_io_t which calls jose_io_decref() at end of scope. it's giving "set it and forget it" ✨ 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
}

see how the jose_io_decref() is just implicitly called for you? obsessed 😭 no manual cleanup, we're thriving.

---

💜 Function Documentation 💜

jose_io_t* jose_io_incref (jose_io_t * io)

Increases the reference count of an IO object. and the best part? this function always succeeds. no error path, no drama, just vibes 🌸

Parameters:

• io — the jose_io_t entity you are using.

Returns:

• the value of io (for convenience). cute of them tbh.

---

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. so like, that's the moment it all wraps up 👑

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. 🍓

heads up bestie: the pointer referenced by buf must remain valid for the entire duration of the returned IO object. do not let it wander off, fr fr.

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. iconique behavior honestly 💅

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. like, grab and go 🧚 it is literally that simple.

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. so it's giving size-in, length-out ✨

unlike jose_io_malloc(), you own the buffer and it is not zeroed or freed when the IO object is freed. it's yours, bestie 🫶

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. don't forget, or it's on you 😭

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. so it's like, one flop is allowed unless all says otherwise 🔥

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. so nobody hand-wrote this, the robot did it and honestly it ate 🤖💖

---

that's the whole page bestie, you're officially fluent in jose_io now ⭐ this cutie came from the José library, dated Tue May 30 2017, and it lives at jose_io(3) in section 3 of the manual. go chain some IO, you main character 🌈💜