XLBIFF(1)

📦
version 4.6.11 · 5 versions
, in ubuntu stonking

💖 XLBIFF(1) — General Commands Manual 💖

okay bestie, pull up a chair, we're reading the xlbiff manual together and honestly? it's giving ✨essential✨

🌸 NAME 🌸

xlbiff — mail notification pop-up with configurable message scans 🫶

💅 SYNOPSIS 💅

xlbiff [ -option ... ] [ mail_file_or_imap_server ]

🦋 DESCRIPTION 🦋

is "you have mail" just... not enough detail for you? 😭 and is a whole per-message notification too much? bestie, welcome to xlbiff, the X Literate Biff. she's iconic, she's chill, she's exactly the right amount.

xlbiff shows you just enough info to answer the one question that matters: is this new mail worth reading right now? and then she stops distracting you the second you've decided. main character energy fr fr.

here's the vibe: xlbiff hangs out in the background, monitoring your mailbox file or IMAP server (or literally any state-monitoring script you want to configure 👑). when a new message arrives, she invokes the MH scan(1) command (or any status-generating script you like) and pops up a window with the output. if more mail shows up (or the monitored state changes), xlbiff scans again and resizes its preview window to match. she's adaptable like that 💁

you can customize scan(1) to show any header and/or content you want. by default xlbiff displays the From, Subject, and the beginning of the message content. she can also beep, or play a custom sound. 🎵

clicking the left mouse button anywhere in the window makes it vanish. poof. ✨ it'll also vanish if the mailbox becomes empty. xlbiff stays out of your way when there's no new mail and only pops up when something is asking for your attention. respectful queen.

Features: 🌈

  • occupies no screen real estate until mail comes in
  • supports scripts for checking mail
  • has configurable screen location, color, and font
  • can notify by bell, sound file and/or keyboard LED
  • shows all new messages in one, easy-to-dismiss window
  • lets you click anywhere on it; no trying to select a tiny "x"

🎀 GETTING STARTED 🎀

if your new mail arrives in a local mail file in the usual system directory:

xlbiff

if your mail file lives somewhere else, you gotta specify the filename:

xlbiff ~/Mailbox

if your mail is on an IMAP server, just specify the server's name:

xlbiff imap.example.com

whichever way you start xlbiff, if you have new mail, she should pop up a window with summary lines for the new messages 🫶 (and if you don't have new mail, you won't see any window at all — which is literally how xlbiff tries to stay out of your way). the window stays visible until you click it away or read the new mail. periodt.

ngl you may need an entry in ~/.netrc to provide login credentials for the IMAP server of your mail provider. the format of this file is described in mailbox-preview(1). 📝

once you've got the correct options to xlbiff figured out, you'll probably want to run it in the background or start it at the beginning of your X session. set it and forget it bestie 💜

✨ OPTIONS ✨

xlbiff accepts all of the standard X Toolkit command line options along with the additional options listed below:

  • -file file_or_server_name — this one specifies the name of the file or IMAP server that should be monitored 👀. by default, it watches file /var/mail/username, where username is your login name.

if you hand it the name of an IMAP server, xlbiff — assisted by its default checkCommand/scanCommand script mailbox-preview(1) — will peek at your new messages on that server. 🕵️

the -file is optional; a non-option argument will be treated the same. easy.

  • -bottom — tells xlbiff to realize/unrealize() the output window instead of using XtPopup/down(). what does that do? it makes the window manager reposition the window each time it pops up 💃, which is useful when you specify negative Y coordinates, i.e., at the bottom of the screen. running xlbiff in that situation without -bottom would cause new lines to run off the bottom edge of the screen. tragic. don't do that.
  • +bottom — the opposite of -bottom. 🙃
  • -rows height — this option specifies the maximum height, in lines of text, of the xlbiff window. the default is 20.
  • -columns width — this option specifies the maximum width, in characters, of the xlbiff window. the default is 80.
  • -resetSaver — if this option is set, xlbiff will reset the screen saver when new mail comes in 💫. this is useful if you're doing something near your workstation but not on it. iykyk.
  • +resetSaver — opposite of -resetSaver. 🙃
  • -update seconds — specifies the frequency in seconds at which xlbiff should update its display. the default is 15 seconds. ⏰
  • -fade seconds — the number of seconds to wait before popping the window back down. this option can be used to monitor events of non-lasting importance, such as syslog 👻. the default value of 0 disables the fade option.
  • -led ledNum — specifies a keyboard LED to light up when there is mail waiting in the file 💡. the default is zero (do not light a LED).
  • -ledPopdown — indicates that the LED should be turned off when xlbiff is popped down. ordinarily the LED stays lit to remind one of awaiting mail 🌟. this option has no effect if the -led option is disabled.
  • +ledPopdown — opposite of -ledPopdown. 🙃
  • -refresh seconds — specifies the number of seconds to wait before re-posting the mail window after you acknowledge it, and it still contains the same mail 🔁. the default is 0 (no refresh). a useful value for this is 1800 (30 minutes).
  • -mailerCommand command — specifies the command to invoke when the mailer() action, described below, is activated. due to mailbox consistency considerations, the mailerCommand should not exit before it is finished with the mailbox, i.e., it should not run its command in the background ⚠️. no cap, this one matters.

example mailerCommand values:

xterm -e alpine
emacsclient --eval '(mh-rmail)' --suppress-output

there is no default mailerCommand.

  • -scanCommand command — specifies a shell command to be executed to list the contents of mailbox file 📋. the specified string value is used as the argument to a popen(3) call and may therefore contain I/O redirection. the command's stdout is used to generate the window. internally, the command is generated as
sprintf(buf, scanCommand, file, columns, rows)

so a %s, %d and %d respectively in scanCommand will generate the values of file, columns, and rows. the default scanCommand, specified by the XLbiff application resources file, is

mailbox-preview %s --width %d --max-messages %d 2>&1

if a scanCommand is used to change the way the mailbox is accessed (as opposed to change the way the content is displayed), you will need to supply a compatible checkCommand. don't skip that part bestie 🙈

  • -checkCommand command — specifies a shell command to be executed to check for new mail (or some other condition) rather than simply examining the size of the mail file. the specified string value is used as the argument to a popen(3) call, and the output generated is important 👑. like xbiff, an exit status of
    • 0 indicates that a change in condition demands a new evaluation of scanCommand and subsequent popup,
    • 1 indicates no change in status, and
    • 2 indicates that the condition has been cleared and the xlbiff window should pop down.

the default, specified by the XLbiff application resources file, is

mailbox-preview %s --check %d

similarly to scanCommand, the checkCommand is generated internally as

sprintf(buf, checkCommand, file, previous)

previous is the numeric value output by the last time checkCommand was run, or zero the first time. this is useful for allowing the checkCommand to maintain state 🧠.

see the EXAMPLES section, below, for different ways to use checkCommand.

  • -volume percentage — specifies how loud the bell should be beeped when new mail comes in. 🔔

the following standard X Toolkit command line arguments are commonly used with xlbiff:

  • -display display — specifies the X server to contact.
  • -geometry +x+y — specifies the preferred position of the scan window. 📐
  • -bg color — specifies the color to use for the background of the window. 🎨
  • -fg color — specifies the color to use for the foreground of the window. 🎨
  • -xrm resourcestring — specifies a resource string to be used. this is especially useful for setting resources that do not have separate command line options. 🪄
  • -help — indicates that a brief summary of the allowed options should be printed on standard output. 🆘

🌈 RESOURCES 🌈

the application class name is XLbiff. it understands all of the core resource names and classes as well as:

  • bottom (class Bottom) — same as the -bottom option.
  • file (class File) — same as the -file option.
  • mailerCommand (class MailerCommand) — same as the -mailerCommand option.
  • scanCommand (class ScanCommand) — same as the -scanCommand option.
  • checkCommand (class CheckCommand) — same as the -checkCommand option.
  • resetSaver (class ResetSaver) — same as the -resetSaver option.
  • update (class Interval) — same as the -update option.
  • fade (class Fade) — same as the -fade option.
  • columns (class Columns) — same as the -columns option.
  • rows (class Rows) — specifies the maximum height, in lines, of the xlbiff window. the default is 20.
  • led (class Led) — same as the -led option.
  • ledPopdown (class LedPopdown) — same as the -ledPopdown option.
  • refresh (class Refresh) — same as the -refresh option.
  • sound (class Sound) — specify a command to be run in place of a bell when new mail arrives 🎶. for example, on a Sun Sparc you might use:
*sound: /usr/demo/SOUND/play -v %d /usr/demo/SOUND/sounds/doorbell.au

the command is generated internally with sprintf(3), so the characters "%d" will be replaced with the numeric value of the volume resource.

  • volume (class Volume) — same as the -volume option.

bestie this page keeps going, don't you dare close the tab 👀

💖 ACTIONS 💖

bestie, here's the tea: xlbiff gives you these actions so you can wire them into event translations. go off.

  • popdown() — makes the window go poof, vanish, bye bye. 💨
  • mailer() — pops down the main window and runs the mailerCommand you defined (if you defined one, no pressure), and it waits for that command to exit. then xlbiff checks for new mail, and if it needs to, it pops back up. main character behavior fr fr. ✨
  • exit() — xlbiff dips out entirely. periodt.

and the default translations, iconically, are:

<Button1Press>:  popdown()
<Button2Press>:  mailer()
<Button3Press>:  exit()

🎀 CUSTOMIZING 🎀

okay so you're probably gonna wanna tweak some values in an app-defaults file and/or sprinkle some resources into your .Xdefaults or .Xresources file. if you want inspo on what's customizable, go peek at the system app-defaults file /etc/X11/app-defaults/XLbiff — it's literally full of examples. 🦋

you also probably wanna tell your window manager to not put borders or titlebars or whatever around the xlbiff window. let it be free. let it breathe. no cap.

and ngl, a lil something you should know: an MH format file, xlbiff.form, ships with this too. that form:

  • omits the message number, bc it's meaningless in this context 💀
  • omits the message size, since scan -file can't figure it out
  • puts a * next to the message if your name is on the To: list (so you can tell it apart from mailing lists and cc's)
  • displays the date in a friendly format 🌸
  • packs as much subject and body into one line as possible. efficiency queen. 👑

🌈 EXAMPLES 🌈

Bulk maildrops

xlbiff ships with two sample scripts, Bcheck and Bscan, and they're meant to be used in conjunction (they're a package deal, they're a duo 🫶). these are for checking mail in "bulk" maildrops. for more info, see README.bulk.

Laptop fan speed

yes bestie, xlbiff can be used to display your laptop's temperature sensors only when the fan is running. obsessed.

this example uses the sensors(1) program as a scanCommand to display the sensor values. and to make the info pop up only when the laptop is hot, we use a check command that extracts, from the sensors output, whether the fan is running and whether its speed has changed. here's a possible check script:

fan1_speed=$(sensors | sed -E -n '/^fan/{s/.* ([0-9]+).*/\1/p;q}')
echo "$fan1_speed"
[ "$fan1_speed" = 0 ] && exit 2
[ "$fan1_speed" = "$1" ] && exit 1
exit 0

so if the script is called xlbiff-fan-check.sh, you can use it by running xlbiff like this:

xlbiff -checkCommand 'xlbiff-fan-check.sh %d' -scanCommand sensors

🌟 ENVIRONMENT 🌟

DISPLAY is used to get the default host and display number. it's giving "where am I and who am I talking to." 💅

🍓 FILES 🍓

  • /var/mail/$USER — the default mail file to check.
  • /etc/X11/app-defaults/XLbiff — the system app-defaults file for X11 resources. you override entries here in your own app-defaults file, or in your own ~/.Xdefaults or ~/.Xresources file. your house, your rules. 💜
  • ~/.netrc — login info for the IMAP server. see mailbox-preview(1).

✨ SEE ALSO ✨

mailbox-preview(1), scan(1), X(7)

💀 BUGS 💀

specifying dimensions in -geometry causes badness. like, actual badness. don't do it. 😭

also, the led option does not work on Suns before SunOS 4.1/X11R5. very niche, very vintage, but now you know.

👑 AUTHOR 👑

Ed Santiago <ed@edsantiago.com>

🧚 ACKNOWLEDGMENTS 🧚

xlbiff took shape around the xgoodbye sample program in the O'Reilly X Toolkit Intrinsics Programming Manual. a lot of code was copied from xbiff, including this man page. and thanks also to Stephen Gildea (gildea@expo.lcs.mit.edu) for the many, many contributions that made xlbiff grow from a midnight hack to a more mature product. glow up of the century, honestly. 🌱➡️🌳

the xlbiff.form file was copied and hacked from Jerry Peek's excellent Nutshell book MH & xmh: Email for Users & Programmers.

and that's the whole vibe bestie, we're all caught up 💖 this page is version 4.6.11, dated 2026-05-08, and it ate, no crumbs left. go forth and biff. 🎀✨🦋

📦 where this page comes from