When Man Pages Go Weird

You may not realize that I got my start in the technology world in the early 1990s learning Unix. From my first Netcom account to my high school allowing me, A JUNIOR, to have and run a Slackware machine directly connected to the Internet. My first Linux kernel was a 1.2.8 kernel, and I vividly remember someone trolling me on IRC to fix some strange problem the best bet was to rm -rf /* as root.

He got me good.

Working through *nix in those days was made easier (and still is today) through Manual Pages, or manpages for short. It’s the thing that people would expect you to go do when they replied “RTFM” when you asked a question that was clearly pointed out in the manpage. You type man <command> and you get a fully formatted text usage guide. Some can be long, some are quite short. By reading the manpage, you should have a good idea on how to use that particular piece of software on your *nix machine.

I recently worked to contribute to an open source package to address and issue I’m having with a remote server and how it phones home. Specifically, when internet connections would go down, sometimes it would get stuck in a loop until it was rebooted, emailing me faithfully—EVERY HOUR—that the task of reconnecting failed because there was already a reconnection in process.

It was stuck.

So I started poking around. Was there a way in a BASH script to put a time limit on the execution of a command so that it could be killed if that time limit exceeded? Why yes, a tool that is part of the GNU CoreUtils package will do exactly this. The tool is called timeout.

So what do I do first? Pull up the manpage. This looks like it will work perfectly! But upon trying it, I got an error message. It was not working. I was attempting to pass the -k flag with a 10 second limit, but no joy. After banging my head on the desk a little bit and honing my Google-fu, I realized that the manpage does not accurately represent the functionality of the tool. When using the -k flag, the first (undocumented) argument is the kill SIGNAL you want to send, THEN the duration. Even using –kill-after= will pass the kill signal into that argument, not the duration of the timeout.

According to the docs, this should work: timeout -k 10s ping example.com

But in order to send a SIGKILL to the command, you have to do this: timeout -k 9 10s ping example.com

Otherwise, timeout will give you this error: timeout: invalid time interval 'ping‘

You can obviously replace ping with the actual command you are trying to run.

I’m posting this not only for my own documentation so I can refer back if I get stuck here again, but also for others who are trying to use that tool and realizing the help docs don’t match the functionality of the tool. Edit: Also yes, I did file a bug report.

Don’t forget to RTFM!

Possibly Related Posts:

*** This is a Security Bloggers Network syndicated blog from Branden R. Williams, Business Security Specialist authored by Branden Williams. Read the original post at: https://www.brandenwilliams.com/blog/2024/04/05/when-man-pages-go-weird/?utm_source=rss&utm_medium=rss&utm_campaign=when-man-pages-go-weird