Linux Blog

A Manpage Template for your Scripts

Filed under: Shell Script Sundays — TheLinuxBlog.com at 11:44 am on Sunday, June 21, 2009

So, you just finished that killer script and the first thing you want to do is write that man page for it right? Not exactly? What do you mean?
Writing a man page isn’t that hard and will give your users an idea of how to use a script.

Here is a basic template for creating your own man pages:

.\" This is a comment
.\" Contact Owen@thelinuxblog.com
.TH man 1 "21 June 2009" ".1" "Man Page Example"
.SH NAME
Man \- Example Man Page
.SH SYNOPSIS
Example Man Page
.SH DESCRIPTION
This is an example of a man page.
.SH OPTIONS
No options for this man page
.SH SEE ALSO
man(1), groff(1), man.config(5)
.SH BUGS
No known bugs for this template, except you might want to replace the quotes if you copy from my blog.
.SH AUTHOR
Owen (owen@thelinuxblog.com)

When you’re done with the gruelling task of writing documentation (which your users won’t read or thank you for) just plop it the correct man section in /usr/share/man
That’s all there is to it!

Working with CSV files in Bash

Filed under: Shell Script Sundays — TheLinuxBlog.com at 1:25 pm on Sunday, October 19, 2008

CSV files are very common. Using them with Bash to aid in scripting can be very useful. Here are a some methods of using bash to work with CSV files. These are what I sometimes use when dealing with CSV files in bash, they may work for your CSV’s they may not. I accept no responsibility of the accuracy of these, I’m sure there are better ways of accomplishing the same tasks. If anybody finds other ways or knows better please comment and let me know. Don’t run these on production data, its always a good idea to make backups and test them before using in a production environment. Who knows how your precious data could become mangled due to a wrong number of quotes, terminations or bad regex. Jump for the post (Read on …)

timestamps in the shell

Filed under: Shell Script Sundays — TheLinuxBlog.com at 12:02 pm on Sunday, March 2, 2008

Time and Date functions are very important when writing shell scripts. I mostly use them for logging reasons, for example to know when something was run last. As much as I dislike time stamps they are still used (at least for now) and therefore I am giving and example.

I am unsure of a way to get a time stamp in Bash. If you have PHP installed you can do the following to get a UNIX time stamp (suitable for inserting into a DB):

php -r 'echo time()."\n";'

php -r executes PHP code inside quotes. the time() function just creates a time stamp for the current time. If you need to format a string based on a time stamp you can use the date() function. Here is an example of turning a timestamp into a readable string:

bash-3.1$ php -r 'echo date("l dS \of F Y h:i:s A","1204476759")."\n";'
Sunday 02nd of March 2008 11:52:39 AM

Take a look at the date() function page on php.net if you wish to use this method of using time stamps in the shell.

If any one has any other methods of using time stamps in the shell or needs any help as usual leave a comment :)

Creating Dialogs with Dialog

Filed under: Shell Script Sundays — TheLinuxBlog.com at 5:48 pm on Sunday, October 21, 2007

Have you ever seen those pretty dialogs used in Shell Scripts such as the Slackware installation, the slackpkg program or even the NVIDIA driver installer? Well, my friends to display dialog boxes from shell scripts is very easy with… you guessed it – Dialog.

First of all, there are many different types of dialogs that you can create they are as follows: calendar, checklist, fselect, gauge, infobox, inputbox, menu, msgbox (message), password, radiolist, tailbox, tailboxbg, textbox, timebox, and yesno (yes/no).

This blog post is intended to be a primer on using dialog. More examples will be posted in future blog posts in the Shell Script Sunday’s column.

The simplest form of a dialog in a shell script is probably the msgbox. All this really does is displays text. To display text in a dialog you would do the following:

owen@the-linux-blog:$ dialog --msgbox "Hello from the Linux Blog!" 5 50

The numbers after the text in quotes are the widths and heights of the box. The minimum height that I like to use is 5. The width doesn’t really matter as long as it is big enough. It is good to keep the box sizes standard across a whole script because it gets annoying with constantly resizing boxes.
If the text in a message box is too long it will auto wrap around and give you a type of scroll bar. As follows:

owen@the-linux-blog:$ dialog --msgbox "Hello from The Linux Blog. This text is so long it wraps it to a New Line" 5 50

Dialogs can be canceled. Clicking Ok or pressing enter/return returns “true” and pressing escape or Ctrl+C returns a false.
The simple shell scripting syntax shown in Shell Scripting 101

is used for this:

owen@the-linux-blog:$ dialog --msgbox "Dialog Exit Example" 5 50 && echo "ok" || echo "false"

Another simple dialog example is the Yes/No box. The syntax for this is exactly the same as the msgbox example except instead of using –msgbox, –yesno is used. The difference between a msgbox and a yesno box is that there a two buttons. It is pretty obvious as to what they are labeled, but for those in the back, I’ve included an example and some screen shots anyway.

owen@the-linux-blog:$ dialog --yesno "Are you learning anything from this blog" 5 50 && echo "Yes, thanks Owen." || echo "No, Write some better Linux Related Posts"

The Linux Blog - Dialog Example - Yes / No

Thats about all I have time for this week. Check back next week!

Shell Scripting 101

Filed under: Shell Script Sundays — TheLinuxBlog.com at 2:27 am on Sunday, August 5, 2007

In my last shell scripting article I made a script to manipulate images with imagemagick. The script was only five lines long and has saved me endless hours of manual work. The script can be adapted to do anything repetitive on any types of files.

Since this is my first official shell scripting post I am going to introduce some common basic shell scripting. This is intended for people that want to learn the basics of shell scripting, so those that have experience already may want to skip this post.

Basic applications used in this tutorial
In order to teach a little about shell scripting, I need to use a couple of programs other than bash its self. The ones that I will use in this post are:
echo
This program displays a line of text
cat
Cat likes to read files and print what it finds out.
grep
Search through files with an expression to find a line that matches the pattern. Sounds complicated but really is not.
less
A paging utility is used to display data. Its kind of like opening a file in notepad Windows except with most utilities more can be done.
less is probably my favorite pager. There are many of these including tail and more. Less is more is the tag line of this pager because it does more than less but is the same thing.

Basic standard output redirecting
Often abbreviated as stdout or stderr for standard out and standard error.
This is normally used to take the output of one application and direct it somewhere. You can overwrite or append to the stdout. The symbol to do this is > to overwrite and >> to append.
stdin example:

echo "This is the new text" > File_To_Be_Written
echo "This is appended" >> File_To_Be_Written

“This is the new text” (without quotes) is redirected to File_To_Be_Written and overwrites the file.

“This is appended” is appended to the end of the file that was just created. If the file did not exist before hand, the file would have been created.

Redirecting Errors
Redirecting errors is achieved the same way as redirecting stdout except it has a 2 in front of the greater than symbol.
stderror example:

echo "This is the new text" 2> File_To_Be_Written
echo "This is appended" 2>> File_To_Be_Written

To append to stderror just think “To redirect to stderror is to redirect with two” Meaning, to redirect stderror is just to redirect with two in front. Cheesy, but its easy to remember.

Pipes
Piping is a common technique I normally use in all of my scripts. The way this works is to send the stdout of one program to the stdin of another.
Example:

cat Big_File | grep search | less

This basically reads the Big_File and then grep’s the file for lines that have search in them. It then pipes that output into the paging utility less.

Lists
A list is just a sequence of pipes that are separated by control operators. Basically
what that means is you have operators that do specific things depending on return codes

&
This operator puts the command into the background, gives a return status of 1 and moves on to the next task.
Example:

owen@amd:~$ echo "tails" > heads
owen@amd:~$ cat heads & echo "done"
tails
[1] 15385
done
[1]   Done                    cat heads

;
The ; operator waits until the process is finished before moving onto the next task.
Example:

owen@amd:~$ cat heads; echo "done"
tails
done

&&
command1 && command2
command2 will only be executed if command1 returns an exit status of zero
Example:

owen@amd:~$ cat heads && echo "done"
tails
done

Note this works because cat has returned the correct exit status

owen@amd:~$ cat eads && echo "done"
cat: eads: No such file or directory

Notice that this does not work because cat did not return the correct exit status.

||
command1 || command2
command2 will be executed if command1 returns a non zero return code.
Example:

owen@amd:~$ cat heads || echo "Did not work"
tails
Did not work is not printed because cat exited properly
owen@amd:~$ cat eads || echo "Did not work"
cat: eads: No such file or directory
Did not work

Did not work was printed because the eads file does not exist.

Throwing it all together:

echo "This is whats in the output file" > output;
echo "Now that has done, lets add something to the end" >> output;
cat output > normal_output && echo "This is not the error log. Press Q to exit this pager and view the error log" >> normal_output;
cat put >> normal_output 2> error_output;
cat normal_output | less ; cat error_output  | less

This short example basically echos some text to the output file. It then adds some more to the end of the output file. Next it reads from the output file into the normal_output file. If that executes successfully it goes on to echo some instructions to the normal_output file. The script moves on to read the put file (which does not exist) and directs the error of that command to a error_output file. After that, it reads the normal output and sends it to the less pager. The first prompt has instructions for ending the pager, and once the pager has been stopped it reads the error log.

Variables
Variables are used to temporarily store data in memory. To read a variable you can just just the echo command. An example of setting and reading a bash variable is below:

owen@amd:~$ variable='This is my variable'
owen@amd:~$ echo $variable
This is my variable

Flow Control
There are ways of controlling how a script is going to work. This is the logic part of the script, the intelligence if you will. There are many different ways to control flow with bash. The following topics should get you started:
Bash If / Then / Else statements & Cases
Bash Loops For, While and Until
Creating menus in Bash with select

Where to from here?
If you followed this example and understand everything so far then you have got your feet wet in shell scripting. You should now know a little on how to read/write files, redirect output and use conditional operators.
If you would like more help there are plenty of resources on-line and probably on the computer you are using to try the examples. Check the man pages for more help on the utility and “man bash” for bash help. If your looking for more tutorials go to Google and type “bash shell scripting tutorial”.
If you have a specific question that needs answering leave a comment or contact me.