Chapter 23. 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. Wherever there is repetitive code, when a task repeats with only slight variations, then consider using a function.

function function_name { command...

}

or

function_name () { command...

}

This second form will cheer the hearts of C programmers (and is more portable).

As in C, the function's opening bracket may optionally appear on the second line.

function_name ()

{

command...

}

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

Example 23−1. Simple function

#!/bin/bash

funky ()

{

echo "This is a funky function." echo "Now exiting funky function."

} # Function declaration must precede call.

# Now, call the function.

funky

exit 0

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

#f1

#Will give an error message, since function "f1" not yet defined.

#However...

Advanced Bash−Scripting Guide

f1 ()

{

echo "Calling function \"f2\" from within function \"f1\"." f2

}

f2 ()

{

echo "Function \"f2\"."

}

f1 # Function "f2" is not actually called until this point,

#although it is referenced before its definition.

#This is permissable.

#Thanks, S.C.

It is even possible to nest a function within another function, although this is not very useful.

f1 ()

{

f2 () # nested

{

echo "Function \"f2\", inside \"f1\"."

}

}

#f2

#Gives an error message.

f1 # Does nothing, since calling "f1" does not automatically call "f2". f2 # Now, it's all right to call "f2",

#since its definition has been made visible by calling "f1".

#Thanks, S.C.

Function declarations can appear in unlikely places, even where a command would otherwise go.

ls −l | foo() { echo "foo"; } # Permissable, but useless.

if [ "$USER" = bozo ] then

bozo_greet () # Function definition embedded in an if/then construct.

{

echo "Hello, Bozo."

}

Advanced Bash−Scripting Guide

#If $NO_EXIT is 1, declares "exit ()".

#This disables the "exit" builtin by aliasing it to "true".

exit # Invokes "exit ()" function, not "exit" builtin.

# Thanks, S.C.

23.1. Complex Functions and Function Complexities

Functions may process arguments passed to them and return an exit status to the script for further processing.

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 23−2. Function Taking Parameters

then

echo "−Parameter #1 is zero length.−" # Also if no parameter is passed. else

echo "−Param #1 is \"$1\".−"

fi

if [ "$2" ] then

echo "−Parameter #2 is \"$2\".−"

fi

return 0

echo "Null parameter passed."

func2 "$uninitialized_param" # Called with uninitialized param echo

echo "One parameter passed."

exit 0

In contrast to certain other programming languages, shell scripts normally pass only value parameters to functions. [50] 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 and Return

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 $?. This mechanism effectively permits script functions to have a "return value" similar to C functions.

return

Terminates a function. A return command [51] 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 23−3. Maximum of two numbers

#!/bin/bash

# max.sh: Maximum of two integers.

return $E_PARAM_ERR

fi

if [ "$1" −eq "$2" ] then

return $EQUAL else

if [ "$1" −gt "$2" ] then

Advanced Bash−Scripting Guide

return $1 else

return $2

fi

fi

}

max2 33 34 return_val=$?

if [ "$return_val" −eq $E_PARAM_ERR ] then

echo "Need to pass two parameters to the function." elif [ "$return_val" −eq $EQUAL ]

then

echo "The two numbers are equal."

else

echo "The larger of the two numbers is $return_val."

fi

exit 0

#Exercise for the reader (easy):

#Convert this to an interactive script,

#that is, have the script ask for input (two numbers).

For a function to return a string or array, use a dedicated variable.

count_lines_in_etc_passwd()

{

[[ −r /etc/passwd ]] && REPLY=$(echo $(wc −l < /etc/passwd))

#If /etc/passwd is readable, set REPLY to line count.

#Returns both a parameter value and status information.

}

if count_lines_in_etc_passwd then

echo "There are $REPLY lines in /etc/passwd." else

echo "Cannot count lines in /etc/passwd."

fi

# Thanks, S.C.

Example 23−4. Converting numbers to Roman numerals

#!/bin/bash

#Arabic number to Roman numeral conversion

#Range: 0 − 200

#It's crude, but it works.

#Extending the range and otherwise improving the script

#is left as an exercise for the reader.

#Usage: roman number−to−convert

LIMIT=200

Advanced Bash−Scripting Guide

E_ARG_ERR=65

E_OUT_OF_RANGE=66

if [ −z "$1" ] then

echo "Usage: `basename $0` number−to−convert" exit $E_ARG_ERR

fi

num=$1

if [ "$num" −gt $LIMIT ] then

echo "Out of range!" exit $E_OUT_OF_RANGE

fi

number=$1 factor=$2 rchar=$3

let "remainder = number − factor" while [ "$remainder" −ge 0 ]

do

echo −n $rchar

let "number −= factor"

let "remainder = number − factor" done

return $number

#Exercise for the reader:

#Explain how this function works.

#Hint: division by successive subtraction.

}

to_roman $num 100 C num=$?

to_roman $num 90 LXXXX num=$?

to_roman $num 50 L num=$?

to_roman $num 40 XL num=$?

to_roman $num 10 X num=$?

to_roman $num 9 IX num=$?

to_roman $num 5 V num=$?

to_roman $num 4 IV num=$?

to_roman $num 1 I

echo

exit 0

See also Example 10−26.

Advanced Bash−Scripting Guide

The largest positive integer a function can return is 256. The return command is closely tied to the concept of exit status, which accounts for this particular limitation. Fortunately, there are workarounds for those situations requiring a large integer return value from a function.

Example 23−5. Testing large return values in a function

#!/bin/bash

#return−test.sh

#The largest positive value a function can return is 256.

exit 0

As we have seen, a function can return a large negative value. This also permits returning large positive integer, using a bit of trickery.

An alternate method of accomplishing this is to simply assign the "return value" to a global variable.

Advanced Bash−Scripting Guide

echo "return value = $Return_Val" #25701

Example 23−6. Comparing two large integers

#!/bin/bash

#max2.sh: Maximum of two LARGE integers.

#This is the previous "max.sh" example,

#modified to permit comparing large integers.

return $E_PARAM_ERR

fi

if [ "$1" −eq "$2" ] then

return $EQUAL else

if [ "$1" −gt "$2" ] then

retval=$1 else

retval=$2

fi

fi

#−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− #

#This is a workaround to enable returning a large integer

#from this function.

#Large *negative* return values permitted, fortunately.

#−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− #

return $retval

}

max2 33001 33997 return_val=$?

# −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− #

# −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− #

if [ "$return_val" −eq "$E_NPARAM_ERR" ]

then # Parameter error "flag" gets sign changed, too.

Advanced Bash−Scripting Guide

echo "Error: Too few parameters." elif [ "$return_val" −eq "$EQUAL" ]

then

echo "The two numbers are equal."

else

echo "The larger of the two numbers is $return_val."

fi

exit 0

See also Example A−6.

Exercise for the reader: Using what we have just learned, extend the previous Roman numerals example to accept arbitrarily large input.

Redirection

Redirecting the stdin of a function

A function is essentially a code block, which means its stdin can be redirected (as in Example 4−1).

Example 23−7. Real name from username

#!/bin/bash

# From username, gets "real name" from /etc/passwd.

ARGCOUNT=1 # Expect one arg.

E_WRONGARGS=65

file=/etc/passwd pattern=$1

if [ $# −ne "$ARGCOUNT" ] then

echo "Usage: `basename $0` USERNAME" exit $E_WRONGARGS

do

echo "$line" | grep $1 | awk −F":" '{ print $5 }' # Have awk use ":" delimiter. done

} <$file # Redirect into function's stdin.

file_excerpt $pattern

#Yes, this entire script could be reduced to

#grep PATTERN /etc/passwd | awk −F":" '{ print $5 }'

#or

#awk −F: '/PATTERN/ {print $5}'

#or

#awk −F: '($1 == "username") { print $5 }' # real name from username

#However, it might not be as instructive.