Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ratmen(1)							     ratmen(1)

       ratmen -	create a menu to run commands

       ratmen [OPTION]... MENUITEM COMMAND...

       ratmen [OPTION]... {-d##|--delimiter ##}	MENUITEM##COMMAND ...

       Ratmen is a simple program that accepts a list of MENUITEM and COMMAND
       pairs on	the command line. It creates a window that consists of nothing
       but a menu.  When a particular MENUITEM is selected by the user,	the
       corresponding COMMAND is	executed or (using --print) printed on
       standard	output.

       Menu items and commands may either be given separately (as in ratmenu)
       using two arguments for each menu option, or, optionally	you may
       specify a delimiter (using the --delimiter option) and specify both
       menu item and command in	the same argument (similar to 9menu). The
       delimiter may be	of any length.

       If the command is omitted (or if	an empty command is supplied when not
       using --delimiter) then the menu	item text will be used as the command.

       Some options may	be specified using X resouces (allowing	you to define
       some defaults you like in your in you ~/.Xresources, ~/.Xdefaults or
       similar).  To make this mechanism as useful as possible I would suggest
       that you	refrain	from using such	options	on the command line, unless
       you really need to, and instead enable/disable the corresponding	X
       resource	setting.

       ratmen's	default	resource class is the name of the executed file,
       either ratmen or, if the	executable was called through a	link, the name
       of the link in question.	The command line option	--class	may be used to
       override	the default X resource class name.

       --align {left|center|right}  (X resource: align)
	       Aligns the text of the menu entries to the left,	center or
	       right.  Defaults	to left. (Short	options	-l, -c and -r may also
	       be used for left, center	and right respectivelly.)

       -b, --back PREVMENU
	       Run command PREVMENU when user goes back	in the menu hierarchy.
	       Useful when using nested	menus; it gives	the user a way to back
	       out and return to the previous menu. Note that you can use this
	       option for other	things too. The	command	specified by the
	       --back option is	executed when the user hits one	of the "back"

       --background BGCOLOR  (X	resource: background)
	       Set the background color	to BGCOLOR. By default,	the background
	       color is	black.	BGCOLOR	may be the name	of any color accepted
	       by your X server.

       -C, --class CLASSNAME
	       This option allows you to override ratmen's resource class.
	       Normally	it is "ratmen",	but it can be set to another class
	       such as "ratmenu" to override selected resources.

       --debug Makes ratmen talk quite a lot on	standard error.

       -d, --delimiter DELIM
	       This changes the	behaviour when parsing subsequent
	       menuitem/command	pairs.

	       Normally	the command line argumens are taken to be alternately
	       menu items and their related commands, thus requiring an	even
	       number of arguments to be passed	to ratmen. (If a command is
	       given as	"" it is taken to be the same as the menu item.) This
	       behaviour can make it somewhat difficult	to distinguish between
	       menu item arguments and command arguments in cases where	the
	       menu grow quite big (e.g. in a script). Therefore an
	       alternative is provided...

	       If you specify a	delimiter (using --delimiter) this behaviour
	       is changed and the menu item and	command	are both expected to
	       occur in	the same argument, separated by	whatever delimiter
	       you've specified. This makes the	command	line easier to read
	       (for a human) but is sometimes disadvantageous, especially in
	       autogenerated menus, since the delimiter	in question cannot
	       occur in	the menu item text. (See also "EXAMPLES" below.)

       -D, --display DISPLAYNAME
	       Use the X display DISPLAYNAME, instead of the default display.
	       Normally	you won't need to use this.

       --foreground FGCOLOR  (X	resource: foreground)
	       Set the foreground color	to FGCOLOR. By default,	the foreground
	       color is	black.	FGCOLOR	may be the name	of any color accepted
	       by your X server.

       -F, --font FONTNAME  (X resource: font)
	       Use the font FONTNAME instead of	the default font.

       -h, --help
	       Output a	brief help message.

       --mouse	(X resource: mouse)
	       Enable/disable mouse support in ratmen. The mouse support is
	       quite limited (you can't	scroll a large menu using the mouse)
	       and is only intended for	those moments when you instinctively
	       want to click on	something you see in order to select it. See
	       also "MOUSE SUPPORT".

	       Use "ratmen.mouse: false" (or `no' or `off') in your X resource
	       file to disable mouse support as	a default, and "ratmen.mouse:
	       true" (or `yes' or `on) to enable it.

       -i, --item POSITION
	       Pre-select menu item number POSITION, instead of	the first menu
	       item, upon opening the menu. Menu items are numbered from 1.
	       This is sometimes useful	in scripts.

	       If POSITION is 0, then no item is selected initially. Going up
	       one item	will make the menu jump	to the last item, going	down
	       will jump to the	first item.  Pressing enter while no item is
	       selected	is the same as aborting. There is no way to zero
	       entries,	other than this, so if you move	about you cannot
	       return to the state where no item is selected (but why should
	       you ever	want that?).

	       The described behavior is useful	when the initially selected
	       item denotes a `current'	value (useful when called from a
	       script) and the absence of a selected item may be used to
	       indicate	that there is no such `current'	value.

       -p, --print
	       Prints the COMMAND associated with the selected MENUITEM	on
	       standard	output instead of running it.

	       Using this option you can use a menu for	all kinds of
	       selections, and not only	for running a program. When using this
	       option COMMAND no longer	need to	be a valid command at all --
	       any string will work. See also "EXAMPLES" below.

       -o, --scroll-offset ITEMS  (X resource: scrollOffset)
	       If a menu is too	large to fit in	one window, it will become
	       scrollable.  Ratmen will	try to keep at least ITEMS number of
	       items between the current position and the top or bottom	of the
	       menu. If	you get	closer than this, the menu will	scroll.	As you
	       get close to the	top or bottom of the menu scrolling will
	       cease. (Default scroll offset is	3.)

	       Scroll offset may not be	larger than half of the	menu. If it is
	       it will be cut down to that value.

       -S, --shell PROG
	       Use PROG	as the shell to	run commands, instead of /bin/sh. A
	       popular alternative shell is rc(1). If the shell	cannot be
	       executed, ratmen	will silently fall back	to using /bin/sh.

       -s, --style {snazzy|dreary}  (X resource: style)
	       The default style is dreary, where the highlight	bar moves up
	       and down	the menu as it does on all conventional	keyboard
	       controlled menus.  In dreary mode, the highlight	bar, which
	       shows the currently selected item, remains stationary while all
	       the menu	items are rotated up or	down when the cursor keys are

       -t, --title NAME
	       Change the title	of the menu window to NAME. The	default	title
	       is the last component of	the path used to run ratmen,
	       typically, "ratmen".

       --unfocus-exit  (X resource: unfocusExit)
	       FIXME: Currently	a `BadWindow' error message is generated by X
	       when the	current	instance of ratmen dies	of unfocus. Does
	       anyone know how to fix this?

	       --unfocus-exit causes ratmen to die (without any	option being
	       selected) if its	window loses focus (it's probably not a	good
	       to use in combination with a window manager that	automatically
	       focuses the window under	your pointer).

	       --no-unfocus-exit makes ratmen survive unfocusing. This can be
	       confusing in some cases as it makes it possible to have start
	       several menus at	once (normally the previous menu would die
	       from unfocus).

	       Use "ratmen.unfocusExit:	false" (or `no'	or `off') in your X
	       resource	file to	disable	unfocus	deaths as a default, and
	       "ratmen.unfocusExit: true" (or `yes' or `on) to enable it.

       -V, --version
	       This option prints the version of ratmen	on the standard
	       output, and then	exits with  an exit value of zero.

       The Up keystrokes move the selection to the next	item up. The Down
       keystrokes move the selection to	the next item down. When the selection
       reaches the top or bottom, it scrolls around to the other side on
       pressing	of the appropriate keystroke. The Select keystrokes execute
       the command corresponding to the	currently selected menu	item, and exit
       ratmen. The Back	keystrokes does	nothing	unless the --back option was
       used, in	which case it will run the command specified by	that option
       and exit	ratmen.	The Exit keystrokes quit ratmen	without	doing

	   Up	   "k",	Up_arrow, BackSpace, "-"
	   Down	   "j",	Down_arrow, Space, Tab,	"+"
	   Select  "l",	Right_arrow, Return
	   Back	   "h",	Left_arrow
	   Exit	   "q",	Escape

       Ratmen implements limited support for the rodent, you may select	an
       item (left), go to any previous menu, given by --back, (right) or abort
       the menu	(any other; usually middle). The mouse cannot be used to
       scroll the menu.

       Your rodent won't interfere with	the normal operation. If you place the
       pointer on the menu by mistake, simply move it outside of the menu to
       restore the selection. You may, however,	use the	keys to	manipulate an
       entry selected with the mouse, in this case the key based selection

       Actions are performed upon releasing a mouse butten. To cancel an
       action after the	button has been	pressed, move it outside the menu
       window and release the button (this goes	for all	the buttons).

       How about creating a little remote shell	menu? The ratmenuish approach
       would be

	   ratmen --label Remotes xterm	"" acme	"rsh acme xterm" herman	"rsh herman 9term" &

       and to do it the	9menu way, type	something like

	   ratmen --label Remotes -d: xterm "acme:rsh acme xterm" "herman:rsh herman 9term" &

       to do the trick.	You could also make a menu containing some nice	X
       programs	to run.	Like this:

	   ratmen --label "X progs" ghostview "" xdvi "" xeyes "" xneko	"" &

       Or like this:

	   ratmen --label -d: "X progs"	ghostview xdvi xeyes xneko &

       That last one is	a bit easier on	the eyes, don't	you think? If you
       want, you can use the --back to call an "earlier" menu, like this:

	   ratmen --back ~/bin/mypreviousmenu "X Eyes" xeyes &

       If you'd	like to	use a menu from	within a shell script (a similar
       technique may of	course be employed from	any other programming
       language, such as perl) you could use the following:

	   choice=`ratmen -pd: Abort Retry Ignore`

       Now any of the options selected will be put into	the environment
       variable	`$choice' (note, though, that this may also be empty if	the
       user cancelled the

       menu). Here -p (or --print) option is used to print the selected
       COMMAND to standard out instead of running it, and -d (or --delimiter)
       is used simply to avoid having to fill out the command line with	a lot
       of ugly "" arguments. (You could, of course, replace the	colon in the
       command line with any character that you	don't use in the menu.)

       And here	are some lines from my ~/.Xresources file, for those

       ! ratmen	ratmen*foreground:    yellow ratmen*font:
       ratmen*unfocusExit:   true

       This makes my menus easily distinguishable (since not much else is
       yellow in my system configuration), easily readable (since I like
       courier)	and doesn't clutty my screen too much in case I	happen to
       forget about them and go	about doing something else instead of choosing
       and item	from the menu.

       /etc/X11/rgb.txt	where you may find the names of	appropriate colours to
       use with	the --background and --forground options and X resources.

       The initial idea	for this program was by	Arnold Robbins,	after having
       worked with John	Mackin's GWM Blit emulation. Matty Farrow wrote	a
       version using libXg, from which some ideas were borrowed. This code was
       written by David	Hogan and Arnold Robbins. Rich Salz motivated the
       -shell option. Jonathan Walther modified	this code to play nicely with
       the ratpoison window manager by removing	handling of mouse events and

       Zrajm C Akfogh <> changed command line	syntax
       into the	more standard getopts, added scrolling capacity	if menu	is to
       large to	fit all	at once, added --delimiter, --item, --print,
       --scroll-offset and --unfocus-exit options and X	resource support (Yay!
       No need to specify those	longish	font-thingies on the command line any

       The name	`ratmen' is both an abbreviation of `ratmenu' (from which this
       program is heavily derived) and a reference to the fact that *I*	don't
       have any	religious reasons for not using	the rodent (I like the
       keyboard, but I also like freedom of choice).

       I have not activelly made any changes to	this program for several
       years, though it	was originally my intention to write a program that
       works both under	X, and in the console.

       I later wrote termmen, which much closer	resembles my intentions	for
       ratmen, but unfortunately only works in the console or terminal (i.e.
       does not	pop up a window	of its own under X). Both termmen and this
       program is available from <>.

       This program is written in C, which is not my native language, while
       Termmen is written as a zsh script. If anyone would like	to continue
       development of ratmen, or a have	a patch	they'd like applied. Please
       feel free to send it to me at

       [2003-02-21, 12:47-16:18] Implemented `--item' for choosing initially
       selected	item. Menu item	and command is now given in the	same string,
       separated with :, which makes for nicer error detection and lesser
       errors since it is a bit	easier to keep track of	what does which	on the
       command line.

       [2003-02-22, 15:38-16:43]

       [2003-02-23, 02:19-02:36] Implemented `--delimiter' which now must be
       used to get the "menuitem:command" (as opposed to "menuitem" "command")
       behaviour.  This, because I realised that when called from a script
       using an	on-the-fly generated menu it can be quite tedious to make sure
       that the	delimiter does not occur in the	`menuitem' string (and thus
       fuck up the menu). Of course in handwritten menus the delimiter
       approach	is easier to handle, hence I allow for both. Delimiter now
       also may	be more	than one character long.

       [2003-02-23, 19:08-20:30] Implemented --unfocus-exit which exits	the
       menu if it's window is unfocused.

       [2003-02-23, 21:12-21:22]

       [2003-02-24, 00:22-00:49]

       [2003-02-24, 11:38-17:47] Now reads some	options	regulating appearance
       and behaviour from X resources in addition to the command line.

       [2003-02-25, 18:47-22:20] Wrote POD. At last found a really good	name
       for the product.	The ratmen.

       [2003-02-26, 01:38-09:15] Now reads command line	option using getopt;
       thusly supports both --long-options and short ones (and bundles of
       short ones). Yay!  Still	haven't	been able to get the --unfocus-exit to
       work properly.

       [2003-02-26, 13:27-14:34] Fixxed	--unfocus-exit so that it now really
       makes the menu die of unfocus. Unfortunately, however a `BadWindow'
       message is generated by X when doing so,	which looks quite ugly in
       ratpoison (which	faithfully reports the error). I simply	haven't	been
       able to figure out what command is causing this,	but my best guess is
       that there's some unlucky X function still queued which tries to
       manipulate the window after it has been closed.

       [2003-03-03, 00:13-01:54] Added the --print option, which can be
       extremely useful	in scripts and other programs where you	want to	use a
       menu for	some kind of input, rather than	for a platform from which to
       fire off	some program. Added "BUGS" section below. Added	the --debug
       option which (as	of now)	dumps some info	on the events (key/mouse
       clicks focusing etc.) intercepted from X.

       [2003-03-08, 11:21-11:29] Added a declaration of	the subroutine
       `strcasecmp' and	thus eliminating a compiler warning. Program worked
       flawlessy even before (and still	does) but with less annoyance for me..
       =|:-) The declaration thingy was	found on the 'net by googling for
       "strcasetmp introduction". Made arguments to --align and	--style	case

       [2003-03-08, 20:27-22:58] Found and killed a bug	which made X resources
       override	the command line options.

       [2003-03-09, 07:04-10:15] Totally fixed the bug mentioned in previous
       comment.	 Added short options -l, -c and	-r (for	left, center and right
       aligning	of the menu text), and changed --label to --title. Also
       changed the size	of the menu window so that it will always be an	even
       number of text lines (looks pretty ogly when only half or a third of
       the last	item can be seen).  Opening of window could be still more
       optimal though (the problem still arises	when X refuses to open the
       window with the requested height, e.g. when one uses frames in

       [2003-03-10, 00:53-04:07] v2.0 -	Optimized menu redrawing routine for
       the non-scrolling case (used to flicker quite nastily when moving down
       large menus fast). Also finally got around to add scrolling capacity
       for menus too large to fit all at once. Added the related
       --scroll-offset option and X resource as	well.

       [2003-03-10, 22:10-23:00] v2.0.1	- Begun	fixxing	window size bug
       (interrupted by Buffy - The Vampire Slayer).

       [2003-03-11, 00:31-04:25]

       [2003-03-12, 00:13-01:14] v2.0.2	- Fixed	weird update/redraw bug
       thingy. Used to get a totally black empty menu sometimes. Bug probably
       introduced in last session, and now deceased.

       [2003-03-19, 10:48-12:38]

       [2003-03-19, 14:17-20:18] v2.1 -	Wrote better handling of X resources,
       comlete with readable --debug output and	all.

       [2003-03-19, 22:40-09:05] v2.2 -	Implemented mouse support. Made
       --item=0	special. Bugfix: Now opens a window of the correct size	by
       telling X that it wants a window	whose vertical size should be any
       number of pixels	evenly dividable by the	font height. (Rxvt served as a
       source of inspiration for this feature.)	Also added keys	Home/PgUp for
       going to	the first item in the menu and End/PgDn	to go to the last.
       --class now really works.

       [2003-03-24, 15:41-16:32] v2.2.1	- Added	options	--mouse	and --no-mouse
       and the corresponding X resource	ratmen.mouse --	mouse is enabled by
       default.	Removed	the short options -u and -U (synonyms for
       --unfocus-exit and --no-unfocus-exit) as	to not encourage the useage of
       those options on	the command line (should be set	using X	resources).

       [2003-03-28, 11:29-11:32] v2.2.2	- Killed bug which didn't allow	spaces
       to be used in font names	(this little bugfix also makes it quite
       necessary not to	end your X resources in	any extraneous spaces).

       [2007-10-25, 11:23-14:13] v2.2.3	-- Bugfix. Changed a couple of latin-1
       characters 173 (soft hyphens) to	the minus signs	the should have	been
       all the time. Added the "FUTURE"	heading	above. Rewrote the Makefile.

       o   When	no item	is selected (i.e. on startup with -i0) and you hover
	   the menu with the pointer, and then remove the pointer, the first
	   item	becomes	selected.

       o   The snazzy mode. I'm	probably going to remove it sometime in	the
	   future.  I don't use	it and I don't see any reason why anybody else
	   should want to either... (Especially	not now	that we	got scrollable
	   dreary mode..)

       o   Generates a `BadWindow' when	dying of unfocus under the
	   --unfocus-exit option.

	   This	should be curable by means of XSetErrorHandler(), at least if
	   it is not ratpoison causing these things.

       o   Memory leaks? There are probably several (me	being totally new to
	   C) but since	the execution time should never	really accumulate I
	   haven't made	it a priority to kill 'em. Please tell me if you find

       o   When	using --item=0 and --style=snazzy one must press arrow down
	   *twice* to select the first item on the menu. (I'll probably	fix
	   this	by removing the	`snazzy' mode.)

       These are the things a want to do next in approximate order of

       o   Parsing of standard input (so one may use ratmen as a magic number)
	   for interpreting menu files.	If this	is to work, maybe some special
	   command line	argument parsing is needed? (I strongly	suspect	that
	   magic number	arguments are not passed in the	same fashion, as if
	   given on the	command	line..)

       o   Option for outputting number	of selected menu item
	   (--print-number/-P maybe?).

       o   Change --print behaviour to include -d: or something	automatically
	   (so that menu item text is default output).

       o   User-configurable keys for up/down choose etc.

       o   Menu	shortcuts (defined in the menu)	-- if autogenerated shortcuts
	   are good enough, this might not be needed.

       o   Automatically generated key shortcuts (E.g. numbers 0-9 for items
	   1-10, or letter 'a' letter to loop through all items	begginning
	   with	an 'a',	or "/" and "?" to do incremental forward/backward

       o   Multiple selection mode (space=select; enter=finalize) (introduce
	   colors for marked entry and marked &	selected entry).

       o   Incremental search in menu (using bottom item space for input).

       o   Replacing top/bottom	item with arrow	(or something) if scrollable
	   in that direction.

Zrajm C	Akfohg			  2021-11-06			     ratmen(1)


Want to link to this manual page? Use this URL:

home | help