Sys::Utmp(3pm)

✨ Sys::Utmp — bestie's guide to UTMP files ✨

okay so real talk: this is the Sys::Utmp page, the "Object(ish) Interface to UTMP files" one, from the User Contributed Perl Documentation. It's a Perl module, it's on 3pm (manual section 3, Perl), and it's genuinely iconic once you get it. Let's go 💅

---

🌸 NAME 🌸

Sys::Utmp — an Object(ish) Interface to UTMP files. Yes, "ish". The author knew. We love the honesty 🫶

---

🎀 SYNOPSIS 🎀

Here's the whole vibe, copied exactly so you can paste it and slay:

use Sys::Utmp;

my $utmp = Sys::Utmp->new();

while ( my $utent =  $utmp->getutent() )
{
   if ( $utent->user_process )
   {
      print $utent->ut_user,"\n";
   }
 }
 $utmp->endutent;

And there's more: peep examples/pwho in the distribution directory 👀 — it's literally right there, go look.

---

🦋 DESCRIPTION 🦋

So Sys::Utmp gives you a vaguely object oriented interface to the Unix user accounting file — sometimes that's /etc/utmp, sometimes /var/run/utmp, depends on the machine, iykyk.

It would prefer to just use the getutent() function from your system's C libraries. Respect. But if those aren't there, bestie, it will attempt to provide its own. DIY queen energy ✨

Okay important heads-up, no cap: this may not be the module that you are looking for. There is a User::Utmp which provides a different procedural interface and may well be more complete for your purposes. Not saying she's better. Just saying she exists 🙈

---

💖 METHODS 💖

• new — the constructor of the class, the main character of entry points 👑. Arguments can be handed over in Key => Value pairs. Right now it takes one argument: 'Filename', which sets the file to be used instead of whatever's defined in _PATH_UTMP. Swapping files like it's nothing.
• getutent — iterates over the records in the utmp file, returning a Sys::Utmp::Utent object for each record in turn. The methods available on those objects are described in the Sys::Utmp::Utent documentation (go read it, bestie). But — if you call it in a list context, it returns a list containing the elements of the Utent entry instead of an object. And if the import flag ':fields' is used, then constants defining the indexes into this list get defined — these are uppercase versions of the methods described in Sys::Utmp::Utent. Two for one, we ate 🍓
• setutent — rewinds the file pointer on the utmp filehandle so you can do repeated searches. Rewind culture 🎀
• endutent — closes the file handle on the utmp file. Clean exit, we love to see it 💅
• utmpname SCALAR filename — sets the file that will be used in place of the one defined in _PATH_UTMP.

⚠️ It is not defined what will happen if this is done between two calls to getutent() — so it is recommended that endutent() is called first. Do not just raw-dog the swap, please 😭

---

🌈 EXPORT 🌈

No methods. No constants. Nothing is exported by default. She's private like that 🙈

---

⭐ Exportable constants ⭐

These constants are exportable under the tag ':constants':

ACCOUNTING
BOOT_TIME
DEAD_PROCESS
EMPTY
INIT_PROCESS
LOGIN_PROCESS
NEW_TIME
OLD_TIME
RUN_LVL
USER_PROCESS

These are the values that will be found in the ut_type field of the Sys::Utmp::Utent object. So when you're checking the type, these are the names you're matching against, fr fr.

And these constants are exported under the tag ':fields':

UT_USER
UT_ID
UT_LINE
UT_PID
UT_TYPE
UT_HOST
UT_TIME

These provide the indexes into the list returned when "getutent" is called in list context. Yes — this is how you index that list. You're welcome 💜

---

💀 BUGS 💀

Probably. 😭 She said it, not me.

This module has been tested on Linux, Solaris, FreeBSD, SCO Openserver and SCO UnixWare and found to work on those platforms. Iconic range actually.

If you have difficulty building the module, or it doesn't behave as expected, then please contact the author — and include your /usr/include/utmp.h if appropriate. That header file is the receipt, bestie 🧾

Patches to make this work better on any platform are always welcome. The source is managed at https://github.com/jonathanstowe/Sys-Utmp so feel free to fork and send a pull request. Fork it, fix it, ship it 🔥

---

👑 AUTHOR 👑

Jonathan Stowe, <jns@gellyfish.co.uk> — writing utmp interfaces before it was cool, honestly. Legends only.

---

🌸 LICENCE 🌸

This Software is Copyright Netscalibur UK 2001, Jonathan Stowe 2001-2013

This Software is published as-is with no warranty express or implied. No promises, no guarantees, just vibes and code 🫶

This is free software and can be distributed under the same terms as Perl itself. Slay.

---

🦋 SEE ALSO 🦋

Go look at these too, bestie:

• perl
• Sys::Utmp::Utent

---

And that's the page, gorgeous ✨ — this was perl v5.42.3, dated 2026-08-19, from the Sys::Utmp(3pm) manual. Take care of your utmp files and they'll take care of you. Mwah 💖