DC_SERIAL_ITERATOR_NEW(3)

💅 DC_SERIAL_ITERATOR_NEW(3)

okay so this is a page from the Library Functions Manual (section 3, the "these are functions bestie" section) and it's literally all about spinning up an iterator for your serial devices. it's giving "let me introduce you to your ports" energy 🦋

✨ NAME ✨

dc_serial_iterator_new — create an iterator to enumerate the serial devices 💖

📚 LIBRARY 📚

you'll find this in the library “libdivecomputer”. that's the one. that's the girl. 👑

🌸 SYNOPSIS 🌸

#include <libdivecomputer/serial.h>

dc_status_t
dc_serial_iterator_new(dc_iterator_t **iterator, dc_context_t *context,
    dc_descriptor_t *descriptor);

💫 DESCRIPTION 💫

So what this does is: it iterates through the available serial devices that match the descriptor you gave it. no cap, that's the whole vibe. 🎀

It takes a context opened with dc_context_new(3), and a descriptor that you usually found by searching through dc_descriptor_iterator_new(3). those two are your besties going into this function, fr fr.

On returning DC_STATUS_SUCCESS the iterator gets set to a dc_iterator_t — and that's the thing you use to iterate the available serial devices with dc_iterator_next(3). slay. ✨

The value type of the iterator is of type dc_serial_device_t. and ooh, you can use that value in functions to extract info about this specific serial device, namely dc_serial_device_get_name(3). iconic. 🫶

When you're done, the serial device needs to be freed with dc_serial_device_free(3). don't ghost it, free it. 😭

And after iterating, the iterator itself needs to be freed using dc_iterator_free(3). both of them. cleanup era. 🧚

💀 reminder: there are two things to free here — the dc_serial_device_t values you get out (each one, with dc_serial_device_free(3)) and the iterator at the end (dc_iterator_free(3)). no leaving them lying around.

🔥 RETURN VALUES 🔥

Returns DC_STATUS_SUCCESS on success, or another dc_status_t code on failure. that's it, that's the tea. ⭐

On DC_STATUS_SUCCESS the returned iterator needs to be freed when done using dc_iterator_free(3). we said it in DESCRIPTION and we're saying it again because it matters, bestie. 💜

🌈 SEE ALSO 🌈

• dc_context_new(3)
• dc_usbhid_iterator_new(3)
• dc_irda_iterator_new(3)
• dc_bluetooth_iterator_new(3)
• dc_serial_device_get_name(3)
• dc_serial_device_free(3)

(the whole iterator friend group 😌 go read them, iykyk)

👑 AUTHORS 👑

The library “libdivecomputer” library was written by Jef Driesen, jef@libdivecomputer.org. legend behaviour honestly. 🫡

This manpage is written by Vincent Hagen, vinnie@script4web.nl. also iconic. 💖

---

and that's the page!! 🎀 this version came from Debian, dated June 5, 2020, and it's DC_SERIAL_ITERATOR_NEW(3) — go forth and enumerate your serial devices, bestie, you're gonna ate 💅✨