GXMESSAGE(1)

📦
version 4.1.1 · 2 versions
, in arch rolling

💅 GXMESSAGE(1) — or like, the gxmessage manual, bestie ✨

Okay so this is the manual page for gxmessage, which lives in section 1 of the manual, and honestly? It's giving useful. Let me walk you through it 🫶

🎀 NAME

gxmessage — a GTK-based xmessage clone. Yes, that's it, that's the whole vibe check 💖

✨ SYNOPSIS

gxmessage [OPTIONS] message ...
gxmessage [OPTIONS] -file FILENAME

🌸 DESCRIPTION

gxmessage pops open a window to show a message, and that message comes from the command line, from a file, or from stdin 🦋 The window has a lil row of buttons, and each one makes the program exit with a different return code. Cute, right?

Press CTRL+F and a search bar appears to help you find words in the displayed message. Literally so handy. CTRL+G and CTRL+SHIFT+G find the Next and Previous matches respectively 🔍

Also, the GNU Info entry for gxmessage has detailed information and examples. Go read it, iykyk 👑

⭐ OPTIONS

gxmessage accepts any option xmessage would, although some — like -bw and -xrm — are silently ignored. Not me getting ghosted by my own flags 💀

  • -bg COLOR — Sets the background color of the message to COLOR. Examples: red, "#c90", "#446a7e".
  • -buttons BUTTON_LIST — Defines the buttons to be created. BUTTON_LIST is a comma-separated list of LABEL:VALUE pairs, one for each button. The LABEL is the text that appears on the button. The VALUE (0..255) is the code the program will exit with if that button is pressed. Commas and colons can be escaped using backslashes (\).

As well as ordinary text, the LABEL can include an underscore (_) to specify a keyboard accelerator. If VALUEs are omitted, they default to 101, 102, 103, etc., in order. If no -buttons option is given, BUTTON_LIST defaults to "okay:0".

gxmessage -buttons "Foo:42,Bar:63" "Example"
echo $?

gxmessage -buttons "_Foo,_Bar" "Example"
echo $?

gxmessage "Example"
echo $?

gxmessage -buttons "Hello\, world" "Example"
  • -default LABEL — Opens the gxmessage window with input focused on the specified button. LABEL is one of the LABELs in BUTTON_LIST (see -buttons, above) 👆
  • -display DISPLAY — Opens the window on the X11 display DISPLAY (for example, :1). This forces GTK to use its X11 backend, so under Wayland it works only if an X server such as XWayland is available. Important caveat, no cap 🫶
  • -fg COLOR — Sets the message text color to COLOR.
  • -file FILENAME — Causes the named file to be used as the message source. If a dash (-) is used in place of FILENAME, the message will be read from stdin.
  • -fn | -font FONT — Specifies the message font, using GTK's font specification system. For example, -font "serif italic 14". (GTK's font system is not compatible with xmessage. See the Compatibility section, below, for a workaround.)
  • -geometry GEOMETRY — Sets the window's size. Example:
-geometry 400x200

Either dimension may be given alone (-geometry 400 or -geometry x200); the other is then chosen to fit the message. Slay, flexible 💅

  • -help — Displays basic usage information then exits.
  • -iconic — Opens the gxmessage window in its iconized (minimized) state. Tiny mode activated 🐜
  • -print — Writes the LABEL of the selected button to stdout.
  • -timeout SECONDS — Automatically closes the gxmessage window with an exit code of 0 if no button is pressed within SECONDS seconds. (The -entry and -entrytext options cause -timeout to be ignored.) So like, they don't play nice together, noted 📝
  • -title TITLE — Sets the gxmessage window's title to TITLE.

🦋 GXMESSAGE SPECIFIC OPTIONS

These ones are specific to gxmessage and are not compatible with xmessage. Main character energy only ✨

  • -borderless — Opens the gxmessage window without the usual window frame.
  • -encoding CHARSET — Specifies the encoding of the message text. By default, the message text is assumed to match the encoding of the current locale.
  • -entry — Adds a text entry box to the gxmessage window. When the window closes, any text in the entry box will be copied to stdout. This option can't be used at the same time as the -print option. Pick a lane bestie 😭
  • -entrytext TEXT — Same as -entry, but sets the default entry box contents to TEXT.
  • -noescape — Prevents the window closing if the ESC key is pressed.
  • -version — Displays the program's version number and Copyright details, then exits.
  • -wrap — Causes lines to wrap rather than exceed the width of the window.

🧚 HISTORIC OPTIONS

These options were supported under GTK2 and GTK3, but no longer have any effect. This is due to changes in modern desktop environments. Rip bozo 😔🪦

  • -center, -nearmouse, -nofocus, -ontop, -sticky, -name NAME

💀 EXIT STATUS

If a button is pressed, the program returns the value assigned to that button. The default "okay" button returns 0. 🎀

If a timeout event occurs, the program returns 0.

If an error occurs, or if the window is closed without a button-press or timeout event, the program exits with code 1. Pressing the ESC key also causes the program to exit with code 1. Not the ESC key catching strays 😭

🌈 COMPATIBILITY WITH XMESSAGE

Fall back to xmessage if gxmessage isn't available:

#!/bin/sh
if command -v gxmessage >/dev/null 2>&1; then
    XMESSAGE=gxmessage
else
    XMESSAGE=xmessage
fi
"$XMESSAGE" "hello, world"

If you specify fonts, check which program you're using:

font="monospace 14"
[ "$XMESSAGE" = xmessage ] && font="fixed"
$XMESSAGE ${font:+-fn "$font"} "hello, world"

Don't use double-dashed command line options:

$XMESSAGE "hello, world" -buttons good
$XMESSAGE "hello, world" --buttons bad

Don't use the gxmessage-specific options:

-entry, -entrytext, -borderless, -wrap,
-encoding, -nofocus, -noescape, -ontop,
-sticky, -version, -h, -?

🙈 BUGS

Command line programs commonly treat the character sequence -- as an end-of-options indicator. Neither xmessage nor gxmessage support this. If there's any chance your message text could be mistaken for a command line option, a work-around is to pad that text with a space character:

gxmessage Please do not '-center ' me

If you discover other bugs in the most recent version of gxmessage, please get in touch. Fr fr, they wanna know 🫶

🔥 SEE ALSO

xmessage(1), zenity(1), dialog(1)

The GNU Info entry for gxmessage contains detailed information and examples. (Said it before, saying it again, it's that good ✨)

👑 AUTHORS

Timothy Musson <trmusson@gmail.com> — icon, legend, the moment 💜

Copyright © 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2012, 2015, 2026 Timothy Richard Musson

Copying and distribution of this file, with or without modification, are permitted provided the copyright notice and this notice are preserved.

Okay that's the whole page bestie, go forth and gxmessage responsibly 💖

October 21st, 2026 — source/version vibes, straight from the GXMESSAGE(1) footer, mwah 😘

📦 where this page comes from