GroupFile(3pm)

💖 GroupFile — the perl module that's your bestie for /etc/group 💖

okay so this is a page from the User Contributed Perl Documentation manual, and it's about Unix::GroupFile — yes that's the (3pm) one, the perl module one, not a command. come sit with me, we're gonna get through this together and it's gonna be so much easier than you think 🫶

---

✨ NAME ✨

Unix::GroupFile — literally just a Perl interface to /etc/group format files. that's it. that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

here's the lil taste test, the whole thing at a glance:

use Unix::GroupFile;

$grp = new Unix::GroupFile "/etc/group";
$grp->group("bozos", "*", $grp->maxgid + 1, @members);
$grp->remove_user("coolgrp", "bgates", "badguy");
$grp->add_user("coolgrp", "joecool", "goodguy");
$grp->remove_user("*", "deadguy");
$grp->passwd("bozos", $grp->encpass("newpass"));
$grp->commit();
undef $grp;

see how clean that is?? no cap. 🎀

---

🦋 DESCRIPTION 🦋

so Unix::GroupFile gives you an abstract interface to /etc/group format files. and bestie, the way it just handles things for you — it deals with file locking, it puts the colons and the commas in the right places, it takes care of all those other niggling little details you'd otherwise be crying about at 2am. 😭

it also handles that genuinely annoying problem (at least on some systems) of trying to create a group line that's longer than 512 characters. the way it does this is by creating multiple lines of groups with the same GID. so when a new GroupFile object is created, all members of groups that share the same GID get merged into a single group, and that group's name is the name corresponding to the first name found in the file for that GID. then when the file is committed, long groups get written out as multiple lines of no more than 512 characters, with numbers appended to the group name for the extra lines. iconic behaviour honestly. 👑

---

🌈 METHODS 🌈

🍓 add_user( GROUP, @USERS )

this one adds the list of users to an existing group. if a user is already a member of that group? silently ignored, no drama, no error, we move on. 💅

and here's the fun part: the special group name * will add the users to every group. every single one. go off.

returns 1 on success or 0 on failure.

🧚 commit( [BACKUPEXT] )

see the Unix::ConfigFile documentation for a description of this method. (iykyk — it's a shared family trait.)

💜 delete( GROUP )

this deletes the named group. if the group you passed in doesn't exist? it has no effect. nothing happens. it's giving chill. 🌸

✨ encpass( PASSWORD )

see the Unix::ConfigFile documentation for a description of this method.

🎀 gid( GROUP [,GID] )

read or modify a group's GID. returns the GID either way, so you always get something back. 🫶

⚠️ real talk: it is illegal to change a group's GID to a GID that is already in use by another group. in that case, the method returns undef. don't do it.

💖 group( GROUP [,PASSWD, GID, @USERS] )

the multi-tool. this method can add, modify, or return information about a group.

• give it just the single group parameter → it returns a list consisting of (PASSWORD, GID, @MEMBERS), or undef if no such group exists.
• give it at least three parameters → the named group gets created, or modified if it already exists. and the list is returned to you in this case too, cute right?

⚠️ also illegal here: specifying a GID that is already in use by another group. in that case, the method returns undef. same energy as above.

🌟 groups( [SORTBY] )

returns a list of all existing groups. by default that list is sorted in order of the GIDs of the groups. but you can also pass "name" as a parameter and get the list sorted by group name instead. your call bestie. 🦋

in scalar context, this method returns the total number of groups.

🔥 maxgid( )

returns the maximum GID in use by all groups. the ceiling. the limit. the final boss of GIDs. 👑

🌸 members( GROUP [,@USERS] )

read or modify the list of members associated with a group. if you specify any users when you call it, all existing members of the group are removed and your list becomes the new set of members. full reset, no survivors, periodt. 💅

in scalar context, this method returns the total number of members in the group.

🎀 new( FILENAME [,OPTIONS] )

see the Unix::ConfigFile documentation for a description of this method.

💜 passwd( GROUP [,PASSWD] )

read or modify a group's password. returns the encrypted password either way. and if all you have is a plaintext password? use the encpass method to encrypt it before you hand it over to this one. do not skip that step bestie. 🙈

⭐ remove_user( GROUP, @USERS )

removes the list of users from an existing group. users who aren't members of the group are silently ignored — no notes, no complaints. 🫶

and again, the special group name * will remove the users from every group.

returns 1 on success or 0 on failure.

🦋 rename_user( OLDNAME, NEWNAME )

changes one username to another in every group. every. single. one. and it returns the number of groups affected, so you know exactly how much chaos you caused. 💀

---

👑 AUTHOR 👑

Steve Snodgrass, ssnodgra@fore.com

---

🌈 SEE ALSO 🌈

• Unix::AliasFile
• Unix::AutomountFile
• Unix::ConfigFile
• Unix::PasswdFile

---

and that's the whole page bestie, we ate that fr fr 💖 this was GroupFile(3pm), perl v5.32.1, dated 2021-08-21 — mwah, go commit your group file, you've got this 🫶✨🎀