SAFE_PARSE_ID_LIST(3)

💅 safe_parse_id_list(3) — ok bestie, let's talk ids 💖

So this is the safe_parse_id_list page from section 3 of the manual, and it's genuinely such a useful little trio of functions. Buckle up 🎀

---

✨ NAME ✨

safe_parse_id_list, safe_parse_uid_list, safe_parse_gid_list — these parse a string for ids and stash them into the safe_id_range_list. Slay.

---

🌸 SYNOPSIS 🌸

#include "safe_id_range_list.h"

struct safe_id_range_list;
typedef struct safe_id_range_list safe_id_range_list;

int safe_parse_id_list(safe_id_range_list list, const char *value);
int safe_parse_uid_list(safe_id_range_list list, const char *value);
int safe_parse_gid_list(safe_id_range_list list, const char *value);

---

🦋 DESCRIPTION 🦋

Okay so these functions add values to the list by parsing the value string. That's the whole vibe. 💫

safe_parse_id_list is the strict one — it only allows numeric values, no cap. Meanwhile safe_parse_uid_list and safe_parse_gid_list are a little more chill and allow non-numeric values, which get converted to user ids and group ids respectively.

Here's the part where they're different from their cousins — these functions differ from safe_strto_id_list(3), safe_strto_uid_list(3), and safe_strto_gid_list(3) by returning an error if non-whitespace exists in value after parsing as much as possible. Translation? The whole string must be a valid id range list. Like, the entire thing. No leftovers. Periodt. 💀

🎀 Parameters 🎀

• list — the safe_id_range_list you're adding values to. Must be non-NULL. Do not test her on this. 🙈
• value — the range list string to parse. Must be non-NULL too. Both of them. Non-negotiable. ✨

🌈 Range List Syntax 🌈

So the syntax of a range list string is a set of ranges, each one separated by colons. Easy enough. Each range is either a single id, or a hyphen ('-') separated set of ids. For that hyphen version: the first must be less than or equal to the second, and the second value may be a valid user or group name depending on which function you used. 👑

Lowkey important detail: if a user or group name is used as the first part of a range, the name must be separated from the hyphen by whitespace, because a hyphen is a legitimate character in a name. So don't come for her about spacing. 🫶

It is an error if the whole string to be parsed is not an id range list with optional whitespace at the end of the string. And if it isn't, or another error happens? -1 gets returned. Bye. 😭

<RANGE_LIST>
       := <RANGE>
       := <RANGE> <whitespace>* ':' <RANGE_LIST>

<RANGE>
       := <ID>
       := <ID> '-' <ID>
       := <ID> '-' <whitespace>* '*'

<ID>   := <whitespace>* <number>
       := <whitespace>* <text_name>

⭐ Example Range Lists ⭐

• 3 — adds the value 3 to the list. Simple. Iconic. 💅
• 0:5:100-103 — adds the values 0, 5, 100, 101, 102, and 103 to the list. Look at all those numbers. Gorgeous.
• root: user1 - user2 : 1000-* — when parsed with safe_parse_uid_list, adds the values 0, 500, 501 and 1000 and greater to the list, assuming the user names root, user1 and user2 have the values 0, 500 and 501 respectively. And yes, the space after user1 is mandatory. Don't skip it bestie, it's not decorative. 🚨

---

🔥 RETURN VALUE 🔥

The function returns 0 if no errors were encountered and only whitespace follows the parsed id range list. -1 is returned otherwise. And errno is set to 0 on success and an appropriate value on error. Clean. ✨

---

💀 ERRORS 💀

• EINVAL — list or value was NULL. An invalid number or non-exist user or group name was encountered. The first element of a range was larger than the second. A value consisting entirely of whitespace was encountered. Or non-whitespace characters follow the parsed id range list. Basically, a whole bouquet of bad vibes. 🥀
• ERANGE — a numeric value was encountered that was too large. Too much. Overflowing. Extra. 😳
• ENOMEM — a memory allocation failed. The malloc said no. 😭

---

👑 AUTHOR 👑

James A. Kupsch. Respect. 🫡

---

🌸 SEE ALSO 🌸

safe_init_id_range_list(3) safe_destroy_id_range_list(3) safe_strto_id_list(3) safe_strto_uid_list(3) safe_strto_gid_list(3)

http://research.cs.wisc.edu/mist/safefile

---

ok that's the whole page bestie, go forth and parse responsibly 💖✨

And as a lil sign-off: this beauty is dated 2011-07-26 and lives in the SAFE_PARSE_ID_LIST(3) manual. Vintage but still serving. 🎀🦋💜