Care and Feeding of Functions in Shell

Functions are really scripts run in the current context of the shell (this means that a second shell is not forked to run the function; it's run within the current shell.) That means that functions provide a lot more flexibility that aliases.  Here are two simplest functions possible: "do nothing" function and "Hello world" function:

          function quit {
               exit
           }
           function hello {
               print "Hello world !"
           }
           hello
           quit       

Declaring a function is just a matter of writing function my_func { my_code }. Functions can be declared in arbitrary order. But they need to be declared before they are invoked in the script.  Calling a function is just like calling another program, you just write its name and (optionally) arguments.

The best way to create a set of  useful shell functions in a separate file. Then you can source the file with the dot (.) command or in your startup scripts. You can also just enter the function at the command line.

$ psgrep() {
> ps -ef | grep $1
> }

This is a pretty simple function, and could be implemented as an alias as well. Let's try to solve the problem of displayed files over 1K.  awk can be used to find any matching files that are larger than 100K bytes:

oversizela() {
ls -la |  awk ' { if ( $5 gt 100000 ) print $1 } '
}

As in almost any programming language, you can use functions to group pieces of code in a more logical way or practice the divine art of recursion.

Arguments

NOTE: The "$#" macro is expanded to contain the number of arguments.

Here is an example of a function that takes one parameter and prints it:

           function arg1_echo {
                    print "The first argument is:" $1 
           }
	   function all_arg_echo {
                    print "List of argumnets is:" $@ 
           }
           function arg_num_echo {
                    print "Number of arguments is:" $# 
           }                

Example of invocations:  
             arg1_echo test

             all_arg_echo  test 1 test 2

Positional Parameters

There are three methods available to extend Linux scripts using parameters. The first method uses positional parameters. A script can refer to the parameters on the command line by the position (or order) in which they appear. Because the other two methods rely on positional parameters, they are discussed first.

The Bash variable $0 is the pathname of the script. It is not necessarily the full pathname, but rather the path used to specify the script when it was executed.

$ printf "%s\n" "$0"
/bin/bash

In this case, the Bash session was started with the command /bin/bash.

When combined with the basename command, the name of the script is removed from the rest of the pathname.

$ declare -rx SCRIPT='basename $0'
$ printf "%s\n" "$SCRIPT"
bash

A slightly faster version uses Bash's substring features and avoids running an outside program.

$ declare -rx SCRIPT=${0##*/}
$ printf "%s\n" "$SCRIPT"
bash

By finding the name of the script from $0, there is no danger that the wrong name will be printed after the script has been copied or renamed. SCRIPT is always the correct name of the script.

The variable $# contains the number of parameters to a script or a shell session. If there are no parameters, $# is zero. The number doesn't include the script name in $0.

$ printf "%d\n" $#
0

The first nine parameters are placed in the variables $1 through $9. (Parameters beyond nine can be accessed if curly braces surround the number.) When the nounset shell option is used, accessing an undefined parameter results in an error, just as if it were an undeclared variable name.

$ printf "%s\n" $9
bash: $9: unbound variable

The variable ?* (or $@) returns a complete list of all the parameters as a single string.

When using positional parameters, Bash doesn't differentiate between switches and arguments. Each item on the command line is a separate parameter to the script. Consider the following script, shown in Listing 9.1.

Listing 9.1. params.sh

#!/bin/bash
#
# params.sh: a positional parameter demonstration

printf "There are %d parameter(s)\n" "$#"
printf "The complete list is %s\n" "$@"
printf "The first parameter is %s\n" "$1"
printf "The second parameter is %s\n" "$2"

When the script runs using the parameters -c and t2341, $1 refers to -c and $2 refers to t2341.

$ bash parms.sh -c t2341
There are 2 parameter(s)
The complete list is -c t2341
The first parameter is -c
The second parameter is t2341

Although both $@ and $* refer to all the parameters, they differ when they are enclosed in double quotes. $* parameters are separated by the first character of the IFS variable, or by spaces if IFS is empty, or without anything when IFS is unset. $* treats the set of parameters as a single group.

$@, on the other hand, always separates the parameters by spaces and treats the parameters as individual items, even when they are enclosed in double quotes. $@ is often used to transfer the entire set of switches to another command (for example, ls $@).

Although positional parameters are a straightforward way to view switches and arguments, they do not "walk through" the list. There is a built-in shift command that discards the parameter in $1 and moves the remaining parameters down one number to take its place. Using shift, you can check each parameter in turn as if it were the first parameter.

Listing 9.2 shows a complete example, using shift.

Listing 9.2. param2.sh

#!/bin/bash
#
# param2.sh
#
# This script expects the switch -c and a company name.  --help (-h)
# is also allowed.

shopt -s -o nounset

declare -rx SCRIPT=${0##*/}

# Make sure there is at least one parameter or accessing $1
# later will be an error.

if [ $# -eq 0 ] ; then
   printf "%s\n" "Type --help for help."
   exit 192
fi

# Process the parameters

while [ $# -gt 0 ] ; do
  case "$1" in
  -h | --help) # Show help
      printf "%s\n" "usage: $SCRIPT [-h][--help] -c companyid"
      exit 0
      ;;
  -c ) shift
       if [ $# -eq 0 ] ; then
          printf "$SCRIPT:$LINENO: %s\n" "company for -c is missing" >&2
          exit 192
       fi
       COMPANY="$1"
      ;;
  -* ) printf "$SCRIPT:$LINENO: %s\n" "switch $1 not supported" >&2
      exit 192
      ;;
  * ) printf "$SCRIPT:$LINENO: %s\n" "extra argument or missing switch" >&2
      exit 192
      ;;
  esac
  shift
done
if [ -z "$COMPANY" ] ; then
   printf "%s\n" "company name missing" >&2
   exit 192
fi

# <-- begin work here

exit 0


					  

A final parameter-related switch is $_ (dollar underscore). This switch has two purposes. First, it represents the pathname to the shell or shell script when the shell (or shell script) is first started. Second, after each command is executed, the command is placed in the environment as a variable containing the pathname of the command.

$ /bin/date
Fri Jun 29 14:39:58 EDT 2001
$ printf "%s\n" "$_"
/bin/date
$ date
Fri Jun 29 14:40:04 EDT 2001
$ printf "%s\n" "$_"
date

You can use $_ to repeat the last argument.

Local Variables

Variables declared inside a function exist only for the duration of the function. These are called local variables. When the function completes, the variables are discarded, the same way variables are discarded by subscripts. See Listing 14.11.

Listing 14.11. function2.sh

#!/bin/bash
#
# function2.sh: A simple function example with local variables
#
shopt –s –o nounset

declare -rx SCRIPT=${0##*/}
declare -rx TMP="/tmp/temp.$$"

# TRASH FILE
#
# Move the specified file to the trash directory
# The first parameter is the file to move

function trash_file {
        declare -r TRASH_DIR="$HOME/trash"

        if test ! -d "$TRASH_DIR" ; then
                printf "%s\n" "$SCRIPT:$FUNCNAME:$LINENO: trash \
directory $TRASH_DIR is missing" >&2
                return 1
        fi
        if test -f "$1" ; then
                mv $1 "$TRASH_DIR""/"
        fi
        return 0

}
readonly -f trash_file
declare -t trash_file

printf "This is a function test\n" > $TMP
trash_file $TMP
if [ $? -ne 0 ] ; then
   printf "%s\n" "$SCRIPT:$LINENO: unable to trash $TMP-aborting" >&2
   exit 1
fi

exit 0


					  

In function2.sh, the variable TRASH_DIR exists only within the function trash_file. Instead of exiting the script when an error occurs, the function returns a status code to indicate whether it succeeded, allowing the main script to decide whether it should exit.

The local command can also declare local variables inside functions and assign initial values. However, local lacks the other switches used by the declare command. Therefore, it's best to use the declare command instead.

If new variables are not explicitly declared, they are not discarded when the function completes. This behavior is for backward compatibility with the Bourne shell but can cause variables to linger around unexpectedly.

$ function f { COMPANY="NightLight Inc." ; }
$ f
$ printf "%s\n" "$COMPANY"
NightLight Inc.

In this example, the variable COMPANY is not discarded when the tiny f function ends because it is not formally declared inside f.

$ function f { declare COMPANY="Nightlight Inc." ; }
$ f
$ printf "%s\n" "$COMPANY"
$

Create Note or Tag

Recursion and Nested Functions

Functions can be nested or used recursively in Bash. Local variables are shared with the nested functions. See Listing 14.12.

Listing 14.12. factorial.sh

#!/bin/bash
#
# factorial.sh: A recursive function example
#
shopt –s –o nounset

declare -rx SCRIPT=${0##*/}
declare -i REPLY

# FACTORIAL : compute a factorial
#
# $1 is the number to compute the factorial for

function factorial {
   declare -i RESULT=1                # shared with factorial1

   function factorial1 {
     declare -i FACT=$1               # the current number
     let "FACT-"                     # deduct one
     if [ $FACT -gt 1 ] ; then        # greater than 1?
        factorial1 $FACT              # repeat
        let "RESULT=RESULT*FACT"      # and multiply in result
     else                             # otherwise
        RESULT=1                      # factorial of 1 is 1
     fi
     return                           # leave function
   }

   factorial1 $1                      # start with param 1
   printf "%d\n" $RESULT
}
readonly -f factorial
declare -t factorial

printf "Factorial of what number? -> "
read REPLY
factorial $REPLY
exit 0


					  

Unexpected recursions can occur when the name of a function is the same as a built-in command. When functions override built-in commands, use the built-in command command to execute a command instead of the function.

function ls {
  command ls -CFp $*
}
readonly -f ls
declare -t ls

Without the command command, this function would begin a never-ending recursion.

Function Attributes

Like variables, functions have attributes. Because functions are not declared with the declare command, different commands are used to change function attributes.

Functions can be shared with subscripts using the export command with the -f (function) switch.

export -f trash_file

Exported functions created inside a user's start-up profile act as more powerful versions of shell aliases.

Because functions are declared with a command, functions can be redefined "on the fly" or discarded at will using unset -f. In a script, this is a dangerous practice because deleting or redefining functions makes your scripts difficult to debug. It can be hard to know which version of a function was defined when a script stops unexpectedly because of an error.

Well-structured scripts create functions near the top of the script and set the read-only attribute with the readonly command.

readonly -f trash_file

Read-only functions cannot be unset or redefined.

The current functions are listed with declare and with the -F (function) switch. You can list the complete functions, along with all variables, with the -p switch.

Functions can also be created using the older Bourne shell syntax of omitting the word "function" and adding an empty pair of parentheses after the function name.

Checking the loaded functions

the set command displays all the loaded functions available to the shell.

$ set 
USER=dave 
findit=() 
{
if [ $# -lt 1 ]; then 
  echo "usage :findit file"; 
  return 1; 
fi; 
find / -name $1 -print 
} 
...

You can use unset command to remove functions:

unset function_name

The idea of .rcfunc file

Traditionally .bashrc contained aliases (which is clrealy wrong as their proper place in in .bash_profile. As for functions they can be used in .bashrc, but it might be beneficial to use a separate file called, for example, .rcfunc.

Let's consider a very artificial example of creating a function that will call find for each argument so that we can find several different files with one command (useless exercise) The function will now look like this:

$ pg .rcfunct 
#!/bin/sh 
findit() 
{

# findit 
if [ $# -lt 1 ]; then 
  echo "usage :findit file" 
  return 1 
fi 
for member 
do 
  find / -name $member -print 
done 

} 

Now source the file again:

. /.rcfunct 

Using the set command to see that it is indeed loaded, you will notice that the shell has correctly interpreted the for loop to take in all parameters.

$ set 
findit=() 
{
if [ $# -lt 1 ]; then 
  echo "usage :`basename $0` file"; 
  return 1; 
fi; 
for loop in "$@"; 
do 
  find / -name $loop -print; 
done 
} 
... 

Now to execute the changed findit function. Supplying a couple of files to find:

$ findit LPSO.doc passwd 
/usr/local/accounts/LPSO.doc 
/etc/passwd 
... 

NEWS CONTENTS

• 20170930 : Functions
• 20170930 : BigAdmin Submitted Article/ Converting a ksh Function to a ksh Script

Old News

Functions

Like "real" programming languages, bash has functions, though in a somewhat limited implementation. A function is a subroutine, a code block that implements a set of operations, a "black box" that performs a specified task. Whenever there is repetitive code, when a task repeats with only slight variations, then writing a function should be investigated.

function function-name {
command...
}

or

function-name () {
command...
}

This second form will cheer the hearts of C programmers.

The opening bracket in the function may optionally be placed on the second line, to more nearly resemble C function syntax.

function-name ()
{
command...
}

Functions are called, triggered, simply by invoking their names.

Note that the function definition must precede the first call to it. There is no method of "declaring" the function, as, for example, in C.

---

Example 3-80. Simple function

1 #!/bin/bash 2 3 funky () 4 { 5 echo This is a funky function. 6 echo Now exiting funky function. 7 } 8 9 # Note: function must precede call. 10 11 # Now, call the function. 12 13 funky 14 15 exit 0

---

More complex functions may have arguments passed to them and return exit values to the script for further processing.

1 function-name $arg1 $arg2

The function refers to the passed arguments by position (as if they were positional parameters), that is, $1, $2, and so forth.

---

Example 3-81. Function Taking Parameters

1 #!/bin/bash 2 3 func2 () { 4 if [ -z $1 ] 5 # Checks if any params. 6 then 7 echo "No parameters passed to function." 8 return 0 9 else 10 echo "Param #1 is $1." 11 fi 12 13 if [ $2 ] 14 then 15 echo "Parameter #2 is $2." 16 fi 17 } 18 19 func2 20 # Called with no params 21 echo 22 23 func2 first 24 # Called with one param 25 echo 26 27 func2 first second 28 # Called with two params 29 echo 30 31 exit 0

---

In contrast to certain other programming languages, shell scripts permit passing only value parameters to functions. Variable names (which are actually pointers), if passed as parameters to functions, will be treated as string literals and cannot be dereferenced. Functions interpret their arguments literally.

exit status

Functions return a value, called an exit status. The exit status may be explicitly specified by a return statement, otherwise it is the exit status of the last command in the function (0 if successful, and a non-zero error code if not). This exit status may be used in the script by referencing it as $?.

return

Terminates a function. The return statement optionally takes an integer argument, which is returned to the calling script as the "exit status" of the function, and this exit status is assigned to the variable $?.

---

Example 3-82. Converting numbers to Roman numerals

1 #!/bin/bash 2 3 # Arabic number to Roman numeral conversion 4 # Range 0 - 200 5 # It's crude, but it works. 6 7 # Extending the range and otherwise improving the script 8 # is left as an exercise for the reader. 9 10 # Usage: roman number-to-convert 11 12 ARG_ERR=1 13 OUT_OF_RANGE=200 14 15 if [ -z $1 ] 16 then 17 echo "Usage: `basename $0` number-to-convert" 18 exit $ARG_ERR 19 fi 20 21 num=$1 22 if [ $num -gt $OUT_OF_RANGE ] 23 then 24 echo "Out of range!" 25 exit $OUT_OF_RANGE 26 fi 27 28 to_roman () 29 { 30 number=$1 31 factor=$2 32 rchar=$3 33 let "remainder = number - factor" 34 while [ $remainder -ge 0 ] 35 do 36 echo -n $rchar 37 let "number -= factor" 38 let "remainder = number - factor" 39 done 40 41 return $number 42 } 43 44 # Note: must declare function 45 # before first call to it. 46 47 to_roman $num 100 C 48 num=$? 49 to_roman $num 90 LXXXX 50 num=$? 51 to_roman $num 50 L 52 num=$? 53 to_roman $num 40 XL 54 num=$? 55 to_roman $num 10 X 56 num=$? 57 to_roman $num 9 IX 58 num=$? 59 to_roman $num 5 V 60 num=$? 61 to_roman $num 4 IV 62 num=$? 63 to_roman $num 1 I 64 65 echo 66 67 exit 0

---

local variables

A variable declared as local is one that is visible only within the block of code in which it appears. In a shell script, this means the variable has meaning only within its own function.

---

Example 3-83. Local variable visibility

1 #!/bin/bash 2 3 func () 4 { 5 local a=23 6 echo 7 echo "a in function is $a" 8 echo 9 } 10 11 func 12 13 # Now, see if local 'a' 14 # exists outside function. 15 16 echo "a outside function is $a" 17 echo 18 # Nope, 'a' not visible globally. 19 20 exit 0

---

Local variables permit recursion (a recursive function is one that calls itself), but this practice usually involves much computational overhead and is definitely not recommended in a shell script.

---

Example 3-84. Recursion, using a local variable

1 #!/bin/bash 2 3 # factorial 4 # --------- 5 6 7 # Does bash permit recursion? 8 # Well, yes, but... 9 # You gotta have rocks in your head to try it. 10 11 12 MAX_ARG=5 13 WRONG_ARGS=1 14 RANGE_ERR=2 15 16 17 if [ -z $1 ] 18 then 19 echo "Usage: `basename $0` number" 20 exit $WRONG_ARGS 21 fi 22 23 if [ $1 -gt $MAX_ARG ] 24 then 25 echo "Out of range (5 is maximum)." 26 # Let's get real now... 27 # If you want greater range than this, rewrite it in a real programming language. 28 exit $RANGE_ERR 29 fi 30 31 fact () 32 { 33 local number=$1 34 # Variable "number" must be declared as local otherwise this doesn't work. 35 if [ $number -eq 0 ] 36 then 37 factorial=1 38 else 39 let "decrnum = number - 1" 40 fact $decrnum # Recursive function call. 41 let "factorial = $number * $?" 42 fi 43 44 return $factorial 45 } 46 47 fact $1 48 echo "Factorial of $1 is $?." 49 50 exit 0

[Apr1, 2006] BigAdmin Submitted Article/ Converting a ksh Function to a ksh Script by William R. Seppeler, April 2006

Here is a simple way to create a script that will behave both as an executable script and as a ksh function. Being an executable script means the script can be run from any shell. Being a ksh function means the script can be optimized to run faster if launched from a ksh shell. This is an attempt to get the best of both worlds.

Procedure

Start by writing a ksh function. A ksh function is just like a ksh script except the script code is enclosed within a function name { script } construct.

Take the following example:

# Example script

function fun {
  print "pid=$$ cmd=$0 args=$*" opts="$-"
}

Save the text in a file. You'll notice nothing happens if you try to execute the code as a script:

ksh ./example

In order to use a function, the file must first be sourced. Sourcing the file will create the function definition in the current shell. After the function has been sourced, it can then be executed when you call it by name:

.. ./example
fun

To make the function execute as a script, the function must be called within the file. Add the bold text to the example function.

# Example script

function fun {
  print "pid=$$ cmd=$0 args=$*" opts="$-"
}

fun $*

Now you have a file that executes like a ksh script and sources like a ksh function. One caveat is that the file now executes while it is being sourced.

There are advantages and disadvantages to how the code is executed. If the file was executed as a script, the system spawns a child ksh process, loads the function definition, and then executes the function. If the file was sourced, no child process is created, the function definition is loaded into the current shell process, and the function is then executed.

Sourcing the file will make it run faster because no extra processes are created, however, loading a function occupies environment memory space. Functions can also manipulate environment variables whereas a script only gets a copy to work with. In programming terms, a function can use call by reference parameters via shell variables. A shell script is always call by value via arguments.

Advanced Information

When working with functions, it's advantageous to use ksh autoloading. Autoloading eliminates the need to source a file before executing the function. This is accomplished by saving the file with the same name as the function. In the above example, save the example as the file name "fun". Then set the FPATH environment variable to the directory where the file fun is. Now, all that needs to be done is type "fun" on the command line to execute the function.

Notice the double output the first time fun is called. This is because the first time the function is called, the file must be sourced, and in sourcing the file, the function gets called. What we need is to only call the function when the file is executed as a script, but skip calling the function if the file is sourced. To accomplish this, notice the output of the script when executing it as opposed to sourcing it. When the file is sourced, arg0 is always -ksh. Also, note the difference in opts when the script is sourced. Test the output of arg0 to determine if the function should be called or not. Also, make the file a self-executing script. After all, no one likes having to type "ksh" before running every ksh script.

#!/bin/ksh
# Example script

function fun {
  print "pid=$$ cmd=$0 args=$*" opts="$-"
}

 [[ "${0##*/}" == "fun" ]] && fun $*

Now the file is a self-executing script as well as a self-sourcing function (when used with ksh autoloading). What becomes more interesting is that since the file can be an autoload function as well as a stand-alone script, it could be placed in a single directory and have both PATH and FPATH point to it.

# ${HOME}/.profile

FPATH=${HOME}/bin
PATH=${FPATH}:${PATH}

In this setup, fun will always be called as a function unless it's explicitly called as ${HOME}/bin/fun.

Considerations

Even though the file can be executed as a function or a script, there are minor differences in behavior between the two. When the file is sourced as a function, all local environment variables will be visible to the script. If the file is executed as a script, only exported environment variables will be visible. Also, when sourced, a function can modify all environment variables. When the file is executed, all visible environment variables are only copies. We may want to make special allowances depending on how the file is called. Take the following example.

#!/bin/ksh

# Add arg2 to the contents of arg1

function addTo {
  eval $1=$(($1 + $2))
}

if [[ "${0##*/}" == "addTo" ]]; then
  addTo $*
  eval print \$$1
fi

The script is called by naming an environment variable and a quantity to add to that variable. When sourced, the script will directly modify the environment variable with the new value. However, when executed as a script, the environment variable cannot be modified, so the result must be output instead. Here is a sample run of both situations.

# called as a function
var=5
addTo var 3
print $var

# called as a script
var=5
export var
var=$(./addTo var 3)
print $var

Note the extra steps needed when executing this example as a script. The var must be exported prior to running the script or else it won't be visible. Also, because a script can't manipulate the current environment, you must capture the new result.

Extra function-ality

It's possible to package several functions into a single file. This is nice for distribution as you only need to maintain a single file. In order to maintain autoloading functionality, all that needs to be done is create a link for each function named in the file.

#!/bin/ksh

function addTo {
  eval $1=$(($1 + $2))
}

function multiplyBy {
  eval $1=$(($1 * $2))
}

if [[ "${0##*/}" == "addTo" ]] \
|| [[ "${0##*/}" == "multiplyBy" ]]; then
  ${0##*/} $*
  eval print \$$1
fi

if [[ ! -f "${0%/*}/addTo" ]] \
|| [[ ! -f "${0%/*}/multiplyBy" ]]; then
  ln "${0}" "${0%/*}/addTo"
  ln "${0}" "${0%/*}/multiplyBy"
  chmod u+rx "${0}"
fi

Notice the extra code at the bottom. This text could be saved in a file named myDist. The first time the file is sourced or executed, the appropriate links and file permissions will be put in place, thus creating a single distribution for multiple functions. Couple that with making the file a script executable and you end up with a single distribution of multiple scripts. It's like a shar file, but nothing actually gets unpacked.

The only downside to this distribution tactic is that BigAdmin will only credit you for each file submission, not based on the actual number of executable programs...

Time to Run

Try some of the sample code in this document. Get comfortable with the usage of each snippet to understand the differences and limitations. In general, it's safest to always distribute a script, but it's nice to have a function when speed is a consideration. Do some timing tests.

export var=8
time ./addTo var 5
time addTo var 5

If this code were part of an inner-loop calculation of a larger script, that speed difference could be significant.

This document aims to provide the best of both worlds. You can have a script and retain function speed for when it's needed. I hope you have enjoyed this document and its content. Thanks to Sun and BigAdmin for the hosting and support to make contributions like this possible.

Encoding and decoding strings

The purpose of this module is to let an external process invoke a bash script with damncommand line arguments: strings including blanks or strange characters that may trigger quoting rules.

This problem can arise when using scripting languages with some sort of eval command.

The solution is to encode the argument string in hexadecimal or octal format strings, so that all the damn characters are converted to "good" ones. The the bash script can convert them back.

Example:

mbfl_decode_hex 414243
-> ABC

Manipulating files and pathnames

• File Names: Manipulating file names.
• File Commands: Manipulating files with external commands.
• File Testing: Testing file existence and the like.
• File Misc: Miscellaneous commands.

File names

• File Name Parts: Splitting a file name into its components.
• File Name Path: Handling relative pathnames.
• File Name System: Finding pathnames on the system.

Splitting a file name into its components

Handling relative pathnames

Finding pathnames on the system

File Commands

• File Commands Listing: Retrieving informations.
• File Commands Mkdir: Creating directories.
• File Commands Copy: Copying files.
• File Commands Removing: Removing files and directories.
• File Commands Tar: Manipulating tar archives.

Retrieving informations

readlink -fn $pathname

Creating directories

Copying files

Removing files and directories

Files removal is forced: the --force option to rm is always used. It is responsibility of the caller to validate the operation before invoking these functions.

Some functions test the existence of the pathname before attempting to remove it: this is done only if test execution is disabled; if test execution is enabled the command line is echoed to stderr to make it easier to debug scripts.

Manipulating tar archives

Remember that when we execute a script with the --test option: the external commands are not executed: a command line is echoed to stdout. It is recommended to use this mode to fine tune the command line options required by tar.

Testing file existence and the like

Miscellaneous commands

Parsing command line options

The getopt module defines a set of procedures to be used to process command line arguments with the following format:

-a

brief option a with no value;

-a123

brief option a with value 123;

--bianco

long option bianco with no value;

--color=bianco

long option color with value bianco.

Requires the message module (Message for details).

• Arguments:
• Using the module:
• Predefined options:
• Interface functions:
• Querying Options:

Arguments

The module contains, at the root level, a block of code like the following:

ARGC=0
declare -a ARGV ARGV1

for ((ARGC1=0; $# > 0; ++ARGC1)); do
    ARGV1[$ARGC1]="$1"
    shift
done

this block is executed when the script is evaluated. Its purpose is to store command line arguments in the global array ARGV1 and the number of command line arguments in the global variable ARGC1.

The global array ARGV and the global variable ARGC are predefined and should be used by the mbfl_getopts functions to store non-option command line arguments.

Example:

$ script --gulp wo --gasp=123 wa

if the script makes use of the library, the strings wo and wa will go into ARGV and ARGC will be set to 2. The option arguments are processed and some action is performed to register them.

We can access the non-option arguments with the following code:

for ((i=0; $i < $ARGC; ++i)); do
    # do something with ${ARGV[$i]}
done

Using the module

To use this module we have to declare a set of script options; we declare a new script option with the function mbfl_declare_option. Options declaration should be done at the beginning of the script, before doing anything; for example: right after the MBFL library code.

In the main block of the script: options are parsed by invoking mbfl_getopts_parse: this function will update a global variable and invoke a script function for each option on the command line.

Examples

Example of option declaration:

mbfl_declare_option ALPHA no a alpha noarg "enable alpha option"

this code declares an option with no argument and properties:

• global variable script_option_ALPHA, which will be set to no by default and to yes if the option is used;
• brief flag -a;
• long flag --alpha;
• description enable alpha option, to be shown in the usage output.

If the option is used: the function script_option_update_alpha is invoked (if it exists) with no arguments, after the variable script_option_ALPHA has been set to yes. Valid option usages are:

$ script.sh -a
$ script.sh --alpha

Another example:

mbfl_declare_option BETA 123 b beta witharg "select beta value"

this code declares an option with argument and properties:

• global variable script_option_BETA, which will be set to 123 by default and to the value selected on the command line if the option is used;
• brief flag -b;
• long flag --beta;
• description select beta value, to be shown in the usage output.

If the option is used: the function script_option_update_beta is invoked (if it exists) with no arguments, after the variable script_option_BETA has been set to the selected value. Valid option usages are:

$ script.sh -b456
$ script.sh --beta=456

Predefined options

A set of predefined options is recognised by the library and not handed to the user defined functions.

--encoded-args

Signals to the library that the non-option arguments and the option values are encoded in hexadecimal strings. Encoding is useful to avoid quoting problems when invoking a script from another one.

If this option is used: the values are decoded by mbfl_getopts_parse before storing them in the ARGV array and before being stored in the option's specific global variables.

-v

--verbose

Turns on verbose messages. The fuction mbfl_option_verbose returns true (Message, for details).

--silent

Turns off verbose messages. The fuction mbfl_option_verbose returns false.

--verbose-program

If used the --verbose option is added to the command line of external programs that support it. The fuction mbfl_option_verbose_program returns true or false depending on the state of this option.

--show-program

Prints the command line of executed external programs.

--debug

Turns on debugging messages (Message, for details).

--test

Turns on test execution (Program Testing, for details).

--null

Signals to the script that it has to use the null character to separate values, instead of the common newline. The global variable mbfl_option_NULL is set to yes.

-f

--force

Signals to the script that it does not have to query the user before doing dangerous operations, like overwriting files. The global variable mbfl_option_INTERACTIVE is set to no.

-i

--interactive

Signals to the script that it does have to query the user before doing dangerous operations, like overwriting files. The global variable mbfl_option_INTERACTIVE is set to yes.

--validate-programs

Validates the existence of all the programs needed by the script; then exits. The exit code is zero if all the programs were found, one otherwise.

--version

Prints to the standard output of the script the contents of the global variable mbfl_message_VERSION, then exits with code zero. The variable makes use of the service variables (Service Variables, for details).

--version-only

Prints to the standard output of the script the contents of the global variable script_VERSION, then exits with code zero.

--license

Prints to the standard output of the script the contents of one of the global variables mbfl_message_LICENSE_*, then exits with code zero. The variable makes use of the service variables (Service Variables, for details).

-h

--help

--usage

Prints to the standard output of the script: the contents of the global variable script_USAGE; a newline; the string options:; a newline; an automatically generated string describing the options declared with mbfl_declare_option; a string describing the MBFL default options. Then exits with code zero.

The following options may be used to set, unset and query the state of the predefined options.

Interface functions

Querying Options

Some feature and behaviour of the library is configured by the return value of the following set of functions. All of these functions are defined by the Getopts module, but they can be redefined by the script.

Printing messages to the console

This module allows one to print messages on an output channel. Various forms of message are supported.

All the function names are prefixed with mbfl_message_. All the messages will have the forms:

<progname>: <message>
<progname>: [error|warning]: <message>

The following global variables are declared:

mbfl_message_PROGNAME

must be initialised with the name of the script that'll be displayed at the beginning of each message;

mbfl_message_VERBOSE

yes if verbose messages should be displayed, else no;

Using external programs

This module declares a set of global variables all prefixed with mbfl_program_. We have to look at the module's code to see which one are declared.

• Program Testing: Testing a script and running programs.
• Program Checking: Checking programs existence.
• Program Executing: Executing a program.
• Program Declaring: Declaring the intention to use a program.

Testing a script and running programs

MBFL allows a script to execute a "dry run", that is: do not perform any operation on the system, just print messages describing what will happen if the script is executed with the selected options. This implies, in the MBFL model, that no external program is executed.

When this feature is turned on: mbfl_program_exec does not execute the program, instead it prints the command line on standard error and returns true.

Checking programs existence

The simpler way to test the availability of a program is to look for it just before it is used. The following function should be used at the beginning of a function that makes use of external programs.

type -ap program

Executing a program

Declaring the intention to use a program

To make a script model simpler, we assume that the unavailability of a program at the time of its execution is a fatal error. So if we need to execute a program and the executable is not there, the script must be aborted on the spot.

Functions are available to test the availability of a program, so we can try to locate an alternative or terminate the process under the script control. On a system where executables may vanish from one moment to another, no matter how we test a program existence, there's always the possibility that the program is not "there" when we invoke it.

If we just use mbfl_program_exec to invoke an external program, the function will try and fail if the executable is unavailable: the return code will be false.

The vanishing of a program is a rare event: if it's there when we look for it, probably it will be there also a few moments later when we invoke it. For this reason, MBFL proposes a set of functions with which we can declare the intention of a script to use a set of programs; a command line option is predefined to let the user test the availability of all the declared programs before invoking the script.

mbfl_program_validate_declared || mbfl_exit_program_not_found

Catching signals

MBFL provides an interface to the trap builtin that allows the execution of more than one function when a signal is received; this may sound useless, but that is it.

Manipulating strings

• String Quote: Quoted characters.
• String Inspection: Inspecting a string.
• String Splitting: Splitting a string.
• String Case: Converting between upper and lower case.
• String Class: Matching a string with a class.
• String Misc: Miscellaneous functions.

Quoted characters

Inspecting a string

Splitting a string

Example of usage for mbfl_string_chars:

string="abcde\nfghilm"
mbfl_string_chars "${string}"
# Now:
# "${#string}" = $SPLITCOUNT
#  a = "${SPLITFIELD[0]}"
#  b = "${SPLITFIELD[1]}"
#  c = "${SPLITFIELD[2]}"
#  d = "${SPLITFIELD[3]}"
#  e = "${SPLITFIELD[4]}"
#  \n = "${SPLITFIELD[5]}"
#  f = "${SPLITFIELD[6]}"
#  g = "${SPLITFIELD[7]}"
#  h = "${SPLITFIELD[8]}"
#  i = "${SPLITFIELD[9]}"
#  l = "${SPLITFIELD[10]}"
#  m = "${SPLITFIELD[11]}"

Converting between upper and lower case

Matching a string with a class

$'char'

Miscellaneous functions

Interacting with the user

Manipulating variables

• Variables Arrays:
• Variables Colon:

Manipulating arrays

Manipulating colon variables

Main function

MBFL declares a function to drive the execution of the script; its purpose is to make use of the other modules to reduce the size of scripts depending on MBFL. All the code blocks in the script, with the exception of global variables declaration, should be enclosed in functions.

type -t FUNCNAME = function

Building test suites

MBFL comes with a little library of functions that may be used to build test suites; its aim is at building tests for bash functions/commands/scripts.

The ideas at the base of this library are taken from the tcltest package distributed with the TCL core ¹; this package had contributions from the following people/entities: Sun Microsystems, Inc.; Scriptics Corporation; Ajuba Solutions; Don Porter, NIST; probably many many others.

The library tries to do as much as possible using functions and aliases, not variables; this is an attempt to let the user redefine functions to his taste.

• Testing Intro: A way to organise a test suite.
• Testing Config: Configuring the package.
• Testing Running: Running tests.
• Testing Compare: Validating results by comparing.
• Testing Output: Validating results by output.
• Testing Messages: Printing messages from test functions.
• Testing Files: Handling files in tests.

A way to organise a test suite

A useful way to organise a test suite is to split it into a set of files: one for each module to be tested.

The file mbfltest.sh must be sourced at the beginning of each test file.

The function dotest should be invoked at the end of each module in the test suite; each module should define functions starting with the same prefix. A module should be stored in a file, and should look like the following:

# mymodule.test --

source mbfltest.sh
source module.sh

function module-featureA-1.1 () { ... }
function module-featureA-1.2 () { ... }
function module-featureA-2.1 () { ... }
function module-featureB-1.1 () { ... }
function module-featureB-1.2 () { ... }

dotest module-

### end of file

the file should be executed with:

$ bash mymodule.test

To test just "feature A":

$ TESTMATCH=module-featureA bash mymodule.test

Remember that the source builtin will look for files in the directories selected by the PATH environment variables, so we may want to do:

$ PATH="path/to/modules:${PATH}" \
TESTMATCH=module-featureA bash mymodule.test

It is better to put such stuff in a Makefile, with GNU make:

top_srcdir      = ...
builddir        = ...
BASHPROG        = bash
MODULES         = moduleA moduleB

testdir         = $(top_srcdir)/tests
test_FILES      = $(foreach f, $(MODULES), $(testdir)/$(f).test)
test_TARGETS    = test-modules

test_ENV        = PATH=$(builddir):$(testdir):$(PATH) TESTMATCH=$(TESTMATCH)
test_CMD        = $(test_ENV) $(BASHPROG)

.PHONY: test-modules

test-modules:
ifneq ($(strip $(test_FILES)),)
        @$(foreach f, $(test_FILES), $(test_CMD) $(f);)
endif

Configuring the package

Running test functions

compgen -A function "$pattern"

Messages are printed before and after the execution of each function, according to the mode selected with: dotest-set-report-success, dotest-set-report-start, ... (Testing Config for details).

The following environment variables may configure the behaviour of dotest.

TESTMATCH

Overrides the value selected with pattern.

TESTSTART

If yes: it is equivalent to invoking dotest-set-report-start; if no: it is equivalent to invoking dotest-unset-report-start.

TESTSUCCESS

If yes: it is equivalent to invoking dotest-set-report-success; if no: it is equivalent to invoking dotest-unset-report-success.

Validating results by comparing

Example:

function my-func () {
    echo $(($1 + $2))
}
function mytest-1.1 () {
    dotest-result 5 `my-func 2 3`
}
dotest mytest-

another example:

function my-func () {
    echo $(($1 + $2))
}
function mytest-1.1 () {
    dotest-result 5 `my-func 2 3` && \
      dotest-result 5 `my-func 1 4` && \
      dotest-result 5 `my-func 3 2` && \
}
dotest mytest-

Validating results by output

Example of test for a function that echoes its three parameters:

function my-lib-function () {
    echo $1 $2 $3
}
function mytest-1.1 () {
    my-lib-function a b c | dotest-output a b c
}
dotest mytest

Example of test for a function that is supposed to print nothing:

function my-lib-function () {
    test "$1" != "$2" && echo error
}
function mytest-1.1 () {
    my-lib-function a a | dotest-output
}
dotest mytest

Validating input

Here is a small script that asks for a first name then a second name:

$ pg func2 
#!/bin/sh 
# func2 
echo -n "What is your first name :" 
read F_NAME 
echo -n "What is your surname :" 
read S_NAME 

We first assign the $1 variable to a more meaningful name. Awk is then used to test if the whole record passed contains only characters. The output of this command, which is 1 for non-letters and null for OK, is held in the variable _LETTERS_ONLY.

A test on the variable is then carried out. If it holds any value then it's an error, but if it holds no value then it's OK. A return code is then executed based on this test. Using the return code enables the script to look cleaner when the test is done on the function on the calling part of the script.

To test the outcome of the function we can use this format of the if statement if we wanted:

if char_name $F_NAME; then 
  echo "OK" 
else 
  echo "ERRORS" 
fi 

If there is an error we can create another function to echo the error out to the screen:

name_error() 
# name_error 
# display an error message 
{
echo " $@ contains errors, it must contain only letters" 
}

The function name_error will be used to echo out all errors disregarding any invalid entries. Using the special variable $@ allows all arguments to be echoed. In this case it's the value of either F_NAME or S_NAME. Here's what the finished script now looks like, using the functions:

$ pg func2 
!/bin/sh 
char_name() 
# char_name 
# to call: char_name string 
# check if $1 does indeed contain only characters a-z,A-Z 
{
# assign the argurment across to new variable 
_LETTERS_ONLY=$1 
_LETTERS_ONLY=`echo $1|awk '{if($0~/[^a-zA-Z]/) print "1"}'` 
if [ "$_LETTERS_ONLY" != "" ] 
then 
  # oops errors 
  return 1 
else 
  # contains only chars 
  return 0 
fi 
} 

name_error() 
# display an error message 
{
echo " $@ contains errors, it must contain only letters" 
} 

while : 
do 
  echo -n "What is your first name :" 
  read F_NAME 
  if char_name $F_NAME 
  then 
    # all ok breakout 
    break 
  else 
    name_error $F_NAME 
  fi 
done 

while : 
do 
  echo -n "What is your surname :" 
  read S_NAME 
  if char_name $S_NAME 
  then 
    # all ok breakout 
    break 
  else 
    name_error $S_NAME 
  fi 
done

Here's what the output looks like when the script is run:

$ func2 
What is your first name :Davi2d 
 Davi2d contains errors, it must contain only letters 
What is your first name :David 
What is your surname :Tansley1 
Tansley1 contains errors, it must contain only letters 
What is your surname :Tansley 

Reading a single character

When navigating menus, one of the most frustrating tasks is having to keep hitting the return key after every selection, or when a 'press any key to continue' prompt appears. A command that can help us with not having to hit return to send a key sequence is the dd command.

The dd command is used mostly for conversions and interrogating problems with data on tapes or normal tape archiving tasks, but it can also be used to create fixed length files. Here a 1-megabyte file is created with the filename myfile.

dd if=/dev/zero of=myfile count=512 bs=2048

Here's the function:

read_a_char() 
# read_a_char 
{
# save the settings 
SAVEDSTTY=`stty -g` 
# set terminal raw please 
    stty cbreak 
  # read and output only one character 
    dd if=/dev/tty bs=1 count=1 2> /dev/null 
  # restore terminal and restore stty 
    stty -cbreak 
stty $SAVEDSTTY 
}

To call the function and return the character typed in, use command substitution. Here's an example.

echo -n "Hit Any Key To Continue" 
character=`read_a_char` 
echo " In case you are wondering you pressed $character"

Testing for the presence of a directory

Testing for the presence of directories is a fairly common task when copying files around. This function will test the filename passed to the function to see if it is a directory. Because we are using the return command with a succeed or failure value, the if statement becomes the most obvious choice in testing the result.

Here's the function.

isdir() 
{
# is_it_a_directory 

if [ $# -lt 1 ]; then 
  echo "isdir needs an argument" 
  return 1 
fi 
# is it a directory ? 
_DIRECTORY_NAME=$1 
if [ ! -d $_DIRECTORY_NAME ]; then 
  # no it is not 
  return 1 
else 
  # yes it is 
  return 0 
fi 
}

Getting information from a login ID

When you are on a big system, and you want to contact one of the users who is logged in, don't you just hate it when you have forgotten the person's full name? Many a time I have seen users locking up a process, but their user ID means nothing to me, so I have to grep the passwd file to get their full name. Then I can get on with the nice part where I can ring them up to give the user a telling off.

Here's a function that can save you from grep ing the /etc/passwd file to see the user's full name.

On my system the user's full name is kept in field 5 of the passwd file; yours might be different, so you will have to change the field number to suit your passwd file.

The function is passed a user ID or many IDs, and the function just grep s the passwd file.

Here's the function:

whois() 
# whois 
# to call: whois userid 
{
# check we have the right params 
if [ $# -lt 1 ]; then 
  echo "whois : need user id's please" 
  return 1 
fi 

for loop 
do 
  _USER_NAME=`grep $loop /etc/passwd | awk -F: '{print $4}'` 
  if [ "$_USER_NAME" = "" ]; then 
    echo "whois: Sorry cannot find $loop" 
  else 
    echo "$loop is $_USER_NAME" 
  fi 
done 
}

Line numbering a text file

When you are in vi you can number your lines which is great for debugging, but if you want to print out some files with line numbers then you have to use the command nl. Here is a function that does what nl does best – numbering the lines in a file. The original file is not overwritten.

number_file()
# number_file
# to call: number_file filename
{
_FILENAME=$1
# check we have the right params
if [ $# -ne 1 ]; then
echo "number_file: I need a filename to number"
return 1
fi

loop=1
while read LINE
do
echo "$loop: $LINE"
loop=`expr $loop + 1`
done < $_FILENAME
}

String to upper case

You may need to convert text from lower to upper case sometimes, for example to create directories in a filesystem with upper case only, or to input data into a field you are validating that requires the text to be in upper case.

Here is a function that will do it for you. No points for guessing it's tr.

str_to_upper () 
# str_to_upper 
# to call: str_to_upper $1 
{
_STR=$1 
# check we have the right params 
if [ $# -ne 1 ]; then 
  echo "number_file: I need a string to convert please" 
  return 1 
fi 
echo $@ |tr '[a-z]' '[A-Z]' 
}

The variable UPPER holds the newly returned upper case string. Notice the use again of using the special parameter $@ to pass all arguments. The str_to_upper can be called in two ways. You can either supply the string in a script like this:

UPPER=`str_to_upper "documents.live"` 
echo $upper 

or supply an argument to the function instead of a string, like this:

UPPER=`str_to_upper $1` 
echo $UPPER 

Both of these examples use substitution to get the returned function results.

is_upper

The function str_to_upper does a case conversion, but sometimes you only need to know if a string is upper case before continuing with some processing, perhaps to write a field of text to a file. The is_upper function does just that. Using an if statement in the script will determine if the string passed is indeed upper case.

Here is the function.

is_upper() 
# is_upper 
# to call: is_upper $1 
{
# check we have the right params 
if [ $# -ne 1 ]; then 
  echo "is_upper: I need a string to test OK" 
  return 1 
fi 
# use awk to check we have only upper case 
_IS_UPPER=`echo $1|awk '{if($0~/[^A-Z]/) print "1"}'` 
if [ "$_IS_UPPER" != "" ] 
then 
  # no, they are not all upper case 
  return 1 
else 
  # yes all upper case 
  return 0 
fi 
} 

To test if a string is indeed lower case, just replace the existing awk statement with this one inside the function is_upper and call it is_lower.

_IS_LOWER=`echo $1|awk '{if($0~/[^a-z]/) print "1"}'` 

Now I've done it. Because I have shown you the str_to_upper, I'd better show you its sister function str_to_lower. No guesses here please on how this one works.

str_to_lower () 
# str_to_lower 
# to call: str_to_lower $1 
{
# check we have the right params 
if [ $# -ne 1 ]; then 
  echo "str_to_lower: I need a string to convert please" 
  return 1 
fi 
echo $@ |tr '[A-Z]' '[a-z]' 
} 

The variable LOWER holds the newly returned lower case string. Notice the use again of using the special parameter $@ to pass all arguments. The str_to_lower can be called in two ways. You can either supply the string in a script like this:

LOWER=`str_to_lower "documents.live"` 
echo $LOWER 

Length of string

Validating input into a field is a common task in scripts. Validating can mean many things, whether it's numeric, character only, formats, or the length of the field.

Suppose you had a script where the user enters data into a name field via an interactive screen. You will want to check that the field contains only a certain number of characters, say 20 for a person's name. It's easy for the user to input up to 50 characters into a field. This is what this next function will check. You pass the function two parameters, the actual string and the maximum length the string should be.

Here's the function:

check_length() 
# check_length 
# to call: check_length string max_length_of_string 
{
_STR=$1 
_MAX=$2 
# check we have the right params 
if [ $# -ne 2 ]; then 
  echo "check_length: I need a string and max length the string should be" 
  return 1 
fi 
# check the length of the string 
_LENGTH=`echo $_STR |awk '{print length($0)}'` 
if [ "$_LENGTH" -gt "$_MAX" ]; then 
  # length of string is too big 
  return 1 
else 
  # string is ok in length 
  return 0 
fi 
} 

You could call the function check_length like this:

$ pg test_name 
# !/bin/sh 
# test_name 
while : 
do 
  echo -n "Enter your FIRST name :" 
  read NAME 
  if check_length $NAME 10 
  then 
    break 
    # do nothing fall through condition all is ok 
  else 
    echo "The name field is too long 10 characters max" 
  fi 
done 

Using the above piece of code this is how the output could look.

$ val_max 
Enter your FIRST name :Pertererrrrrrrrrrrrrrr 
The name field is too long 10 characters max 
Enter your FIRST name :Peter 

You could use the wc command to get the length of the string, but beware: there is a glitch when using wc in taking input from the keyboard. If you hit the space bar a few times after typing in a name, wc will almost always retain some of the spaces as part of the string, thus giving a false length size. Awk truncates end of string spaces by default when reading in via the keyboard.

Here's an example of the wc glitch (or maybe it's a feature):

echo -n "name :" 
read NAME 
echo $NAME | wc -c 

chop

The chop function chops off characters from the beginning of a string. The function chop is passed a string; you specify how many characters to chop off the string starting from the first character. Suppose you had the string MYDOCUMENT.DOC and you wanted the MYDOCUMENT part chopped, so that the function returned only .DOC. You would pass the following to the chop function:

MYDOCUMENT.DOC 10 

Here's the function chop:

# check we have the right params
if [ $# -ne 2 ]; then
echo "check_length: I need a string and how many characters to chop"
return 1
fi
# check the length of the string first
# we can't chop more than what's in the string !!
_LENGTH=`echo $_STR |awk '{print length($0)}'`
if [ "$_LENGTH" -lt "$_CHOP" ]; then
echo "Sorry you have asked to chop more characters than there are in
the string"
return 1
fi
echo $_STR |awk '{print substr($1,'$_CHOP')}'
}

The returned string newly chopped is held in the variable CHOPPED. To call the function chop, you could use:

or you could call this way:

Months

When generating reports or creating screen displays, it is sometimes convenient to the programmer to have a quick way of displaying the full month. This function, called months, will accept the month number or month abbreviation and then return the full month.

For example, passing 3 or 03 will return March. Here's the function.

months() 
{
# months 
_MONTH=$1 
# check we have the right params 
if [ $# -ne 1 ]; then 
  echo "months: I need a number 1 to 12 " 
  return 1 
fi 

case $_MONTH in 
1|01|Jan)_FULL="January" ;; 
2|02|Feb)_FULL="February" ;; 
3|03|Mar)_FULL="March";; 
4|04|Apr)_FULL="April";; 
5|05|May)_FULL="May";; 
6|06|Jun)_FULL="June";; 
7|07|Jul)_FULL="July";; 
8|08|Aug)_FULL="August";; 
9|10|Sep|Sept)_FULL="September";; 
10|Oct)_FULL="October";; 
11|Nov)_FULL="November";; 
12|Dec)_FULL="December";; 
*) echo "months: Unknown month" 
  return 1 
  ;; 
esac 
echo $_FULL 
} 

To call the function months you can use either of the following methods.

months 04

The above method will display the month April; or from a script:

MY_MONTH=`months 06` 
echo "Generating the Report for Month End $MY_MONTH" 
...

which would output the month June.

Calling functions inside a script

To use a function in a script, create the function, and make sure it is above the code that calls it. Here's a script that uses a couple of functions. We have seen the script before; it tests to see if a directory exists.

### END OF FUNCTIONS

echo -n "enter destination directory :"
read DIREC
if is_it_a_directory $DIREC
then :
else
error_msg "$DIREC does not exist...creating it now"
mkdir $DIREC > /dev/null 2>&1
if [ $? != 0 ]
then
error_msg "Could not create directory:: check it out!"
exit 1
else :
fi
fi # not a directory
echo "extracting files..."

In the above script two functions are declared at the top of the script and called from the main part of the script. All functions should go at the top of the script before any of the main scripting blocks begin. Notice the error message statement; the function error_msg is used, and all arguments passed to the function error_msg are just echoed out with a couple of bleeps.

Calling functions from a function file

We have already seen how to call functions from the command line; these types of functions are generally used for system reporting utilities.

Let's use the above function again, but this time put it in a function file. We will call it functions.sh, the sh meaning shell scripts.

#---------------------------------------------

error_msg()
{
echo -e "\007"
echo $@
echo -e "\007"
return 0
}

Now let's create the script that will use functions in the file functions.sh. We can then use these functions. Notice the functions file is sourced with the command format:

. /<path to file> 

# now we can use the function(s)

echo -n "enter destination directory :"
read DIREC
if is_it_a_directory $DIREC
then :
else
error_msg "$DIREC does not exist...creating it now"
mkdir $DIREC > /dev/null 2>&1
if [ $? != 0 ]
then
error_msg "Could not create directory:: check it out!"
exit 1
else :
fi
fi # not a directory
echo "extracting files..."

When we run the above script we get the same output as if we had the function inside our script:

$ direc_check 
enter destination directory :AUDIT 
AUDIT does not exist...creating it now 
extracting files... 

Sourcing files is not only for functions

To source a file, it does not only have to contain functions – it can contain global variables that make up a configuration file.

Suppose you had a couple of backup scripts that archived different parts of a system. It would be a good idea to share one common configuration file. All you need to do is to create your variables inside a file then when one of the backup scripts kicks off it can load these variables in to see if the user wants to change any of the defaults before the archive actually begins. It may be the case that you want the archive to go to a different media.

Of course this approach can be used by any scripts that share a common configuration to carry out a process. Here's an example. The following configuration contains default environments that are shared by a few backup scripts I use.

Here's the file.

$ pg backfunc 
#!/bin/sh 
# name: backfunc 
# config file that holds the defaults for the archive systems 
_CODE="comet" 
_FULLBACKUP="yes" 
_LOGFILE="/logs/backup/" 
_DEVICE="/dev/rmt/0n" 
_INFORM="yes" 
_PRINT_STATS="yes" 

The descriptions are clear. The first field _CODE holds a code word. To be able to view this and thus change the values the user must first enter a code that matches up with the value of _CODE, which is "comet".

Here's the script that prompts for a password then displays the default configuration:

$ pg readfunc 
#!/bin/sh 
# readfunc 

if [ -r backfunc ]; then 
  # source the file 
  . /backfunc 
else 
  echo "$`basename $0` cannot locate backfunc file" 
fi 

echo -n "Enter the code name :" 
# does the code entered match the code from backfunc file ??? 
if [ "${CODE}" != "${_CODE}" ]; then 
  echo "Wrong code...exiting..will use defaults" 
  exit 1 
fi 

echo " The environment config file reports" 
echo "Full Backup Required            : $_FULLBACKUP" 
echo "The Logfile Is                  : $_LOGFILE" 
echo "The Device To Backup To is      : $_DEVICE" 
echo "You Are To Be Informed by Mail  : $_INFORM" 
echo "A Statistic Report To Be Printed: $_PRINT_STATS" 

When the script is run, you are prompted for the code. If the code matches, you can view the defaults. A fully working script would then let the user change the defaults.

$ readback 
Enter the code name :comet 

The environment config file reports 
Full Backup Required            : yes 
The Logfile Is                  : /logs/backup/ 
The Device To Backup To is      : /dev/rmt/0n 
You Are To Be Informed by Mail  : yes 
A Statistic Report To Be Printed: yes 

When you have got a set of functions you like, put them in a functions file, then other scripts can use the functions as well.

Etc

Society

Groupthink : Two Party System as Polyarchy : Corruption of Regulators : Bureaucracies : Understanding Micromanagers and Control Freaks : Toxic Managers :   Harvard Mafia : Diplomatic Communication : Surviving a Bad Performance Review : Insufficient Retirement Funds as Immanent Problem of Neoliberal Regime : PseudoScience : Who Rules America : Neoliberalism  : The Iron Law of Oligarchy : Libertarian Philosophy

Quotes

War and Peace : Skeptical Finance : John Kenneth Galbraith :Talleyrand : Oscar Wilde : Otto Von Bismarck : Keynes : George Carlin : Skeptics : Propaganda  : SE quotes : Language Design and Programming Quotes : Random IT-related quotes :  Somerset Maugham : Marcus Aurelius : Kurt Vonnegut : Eric Hoffer : Winston Churchill : Napoleon Bonaparte : Ambrose Bierce :  Bernard Shaw : Mark Twain Quotes

Bulletin:

Vol 25, No.12 (December, 2013) Rational Fools vs. Efficient Crooks The efficient markets hypothesis : Political Skeptic Bulletin, 2013 : Unemployment Bulletin, 2010 :  Vol 23, No.10 (October, 2011) An observation about corporate security departments : Slightly Skeptical Euromaydan Chronicles, June 2014 : Greenspan legacy bulletin, 2008 : Vol 25, No.10 (October, 2013) Cryptolocker Trojan (Win32/Crilock.A) : Vol 25, No.08 (August, 2013) Cloud providers as intelligence collection hubs : Financial Humor Bulletin, 2010 : Inequality Bulletin, 2009 : Financial Humor Bulletin, 2008 : Copyleft Problems Bulletin, 2004 : Financial Humor Bulletin, 2011 : Energy Bulletin, 2010 : Malware Protection Bulletin, 2010 : Vol 26, No.1 (January, 2013) Object-Oriented Cult : Political Skeptic Bulletin, 2011 : Vol 23, No.11 (November, 2011) Softpanorama classification of sysadmin horror stories : Vol 25, No.05 (May, 2013) Corporate bullshit as a communication method  : Vol 25, No.06 (June, 2013) A Note on the Relationship of Brooks Law and Conway Law

History:

Fifty glorious years (1950-2000): the triumph of the US computer engineering : Donald Knuth : TAoCP and its Influence of Computer Science : Richard Stallman : Linus Torvalds  : Larry Wall  : John K. Ousterhout : CTSS : Multix OS Unix History : Unix shell history : VI editor : History of pipes concept : Solaris : MS DOS :  Programming Languages History : PL/1 : Simula 67 : C : History of GCC development :  Scripting Languages : Perl history   : OS History : Mail : DNS : SSH : CPU Instruction Sets : SPARC systems 1987-2006 : Norton Commander : Norton Utilities : Norton Ghost : Frontpage history : Malware Defense History : GNU Screen : OSS early history

Classic books:

The Peter Principle : Parkinson Law : 1984 : The Mythical Man-Month :  How to Solve It by George Polya : The Art of Computer Programming : The Elements of Programming Style : The Unix Hater’s Handbook : The Jargon file : The True Believer : Programming Pearls : The Good Soldier Svejk : The Power Elite

Most popular humor pages:

Manifest of the Softpanorama IT Slacker Society : Ten Commandments of the IT Slackers Society : Computer Humor Collection : BSD Logo Story : The Cuckoo's Egg : IT Slang : C++ Humor : ARE YOU A BBS ADDICT? : The Perl Purity Test : Object oriented programmers of all nations : Financial Humor : Financial Humor Bulletin, 2008 : Financial Humor Bulletin, 2010 : The Most Comprehensive Collection of Editor-related Humor : Programming Language Humor : Goldman Sachs related humor : Greenspan humor : C Humor : Scripting Humor : Real Programmers Humor : Web Humor : GPL-related Humor : OFM Humor : Politically Incorrect Humor : IDS Humor : "Linux Sucks" Humor : Russian Musical Humor : Best Russian Programmer Humor : Microsoft plans to buy Catholic Church : Richard Stallman Related Humor : Admin Humor : Perl-related Humor : Linus Torvalds Related humor : PseudoScience Related Humor : Networking Humor : Shell Humor : Financial Humor Bulletin, 2011 : Financial Humor Bulletin, 2012 : Financial Humor Bulletin, 2013 : Java Humor : Software Engineering Humor : Sun Solaris Related Humor : Education Humor : IBM Humor : Assembler-related Humor : VIM Humor : Computer Viruses Humor : Bright tomorrow is rescheduled to a day after tomorrow : Classic Computer Humor

The Last but not Least Technology is dominated by two types of people: those who understand what they do not manage and those who manage what they do not understand ~Archibald Putt. Ph.D

The statements, views and opinions presented on this web page are those of the author (or referenced source) and are not endorsed by, nor do they necessarily reflect, the opinions of the Softpanorama society. We do not warrant the correctness of the information provided or its fitness for any purpose. The site uses AdSense so you need to be aware of Google privacy policy. You you do not want to be tracked by Google please disable Javascript for this site. This site is perfectly usable without Javascript.

Last modified: September 29, 2017