SD_ID128_TO_STRING(3)

✨ SD_ID128_TO_STRING(3) ✨

okay bestie, pull up a chair 💅 this is the sd_id128_to_string page from section 3 of the manual, and it's literally all about turning 128-bit IDs into strings and back again. no cap, it's more fun than it sounds 🎀

---

🌸 NAME 🌸

sd_id128_to_string, SD_ID128_TO_STRING, SD_ID128_STRING_MAX, sd_id128_to_uuid_string, SD_ID128_TO_UUID_STRING, SD_ID128_UUID_STRING_MAX, sd_id128_from_string — format or parse 128-bit IDs as strings ✨

---

🦋 SYNOPSIS 🦋

#include <systemd/sd-id128.h>

#define SD_ID128_STRING_MAX 33U

#define SD_ID128_UUID_STRING_MAX 37U

#define SD_ID128_TO_STRING(id) ...

#define SD_ID128_TO_UUID_STRING(id) ...

char *sd_id128_to_string(sd_id128_t id, char s[static SD_ID128_STRING_MAX]);

char *sd_id128_to_uuid_string(sd_id128_t id, char s[static SD_ID128_UUID_STRING_MAX]);

int sd_id128_from_string(const char *s, sd_id128_t *ret);

---

💖 DESCRIPTION 💖

So sd_id128_to_string() takes a 128-bit ID and formats it as a character string, periodt. it wants the ID plus a string array that can hold 33 characters (SD_ID128_STRING_MAX). the ID comes out as 32 lowercase hexadecimal digits, and then a NUL byte closes it out 🎀

SD_ID128_TO_STRING() is the macro bestie of sd_id128_to_string() — it wraps the function and hands it an appropriately sized buffer as the second argument, allocated as a C99 compound literal. so every single use implicitly grabs a suitable buffer on the stack, and that buffer stays valid until the end of the current code block. honestly? this is usually the simplest way to get a string representation of a 128-bit ID in a buffer that's valid in the current code block 👑

sd_id128_to_uuid_string() and SD_ID128_TO_UUID_STRING() are basically the same deal as those two, except they format the 128-bit values as RFC4122 UUIDs — as in a series of 36 lowercase hexadecimal digits and dashes, terminated by a NUL byte 🦋

sd_id128_from_string() is the reverse operation, the uno reverse card of the whole situation: it takes a 33-character string with 32 hexadecimal digits (lowercase OR uppercase, terminated by NUL) and parses them back into a 128-bit ID returned in ret. alternatively, this call can also parse a 37-character string with a 128-bit ID formatted as an RFC UUID. and if ret is passed as NULL, the function will validate the passed ID string but not actually return it in parsed form 👀

⚠️ heads up — when formatting and parsing 36-character UUIDs, this is done strictly in Big Endian byte order, i.e. according to RFC4122 Variant 1 rules, even if the UUID encodes a different variant. this matches behaviour in various other Linux userspace tools. it's probably wise to avoid UUIDs of other variant types, fr fr 😭

want more about the sd_id128_t type? see sd-id128(3). and note that these calls operate the same way on all architectures — the results do not depend on endianness 🌈

when you're formatting a 128-bit ID into a string, it's often easier to just use a format string for printf(3). this is easily done using the SD_ID128_FORMAT_STR and SD_ID128_FORMAT_VAL() macros — more on that in sd-id128(3) ✨

---

⭐ RETURN VALUE ⭐

sd_id128_to_string() always succeeds and returns a pointer to the string array you passed in 🫶

sd_id128_from_string() returns 0 on success (and in that case ret gets filled in), or a negative errno-style error code 💀

---

💜 NOTES 💜

the functions described here are available as a shared library, which you can compile against and link to with the libsystemd pkg-config(1) file 🎀

😭 the code described here uses getenv(3), which is declared to be not multi-thread-safe. this means the code calling the functions described here must not call setenv(3) from a parallel thread. it's recommended to only do calls to setenv() from an early phase of the program, when no other threads have been started. like, seriously, keep it early.

---

🕰️ HISTORY 🕰️

sd_id128_to_string() and sd_id128_from_string() were added in version 187 ✨

sd_id128_to_uuid_string() was added in version 251 💫

---

👑 SEE ALSO 👑

systemd(1), sd-id128(3), printf(3)

---

📎 NOTES (the footnote one, iykyk) 📎

1. RFC4122 — https://tools.ietf.org/html/rfc4122

---

aaaand that's the whole page, bestie 🍓 this was systemd 261.3, SD_ID128_TO_STRING(3), and you absolutely ate that reading comprehension 💅✨ go format some IDs, ily 🫶