File: functions.html

package info (click to toggle)
abs-guide 10-4
links: PTS, VCS
area: main
in suites: bookworm, bullseye, forky, sid, trixie
size: 6,952 kB
sloc: sh: 14,129; makefile: 81
file content (1940 lines) | stat: -rw-r--r-- 40,351 bytes
parent folder | download | duplicates (3)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Functions</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="Advanced Bash-Scripting Guide"
HREF="index.html"><LINK
REL="UP"
TITLE="Advanced Topics"
HREF="part5.html"><LINK
REL="PREVIOUS"
TITLE="Process Substitution"
HREF="process-sub.html"><LINK
REL="NEXT"
TITLE="Local Variables"
HREF="localvar.html"><META
HTTP-EQUIV="Content-Style-Type"
CONTENT="text/css"><LINK
REL="stylesheet"
HREF="common/kde-common.css"
TYPE="text/css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=iso-8859-1"><META
HTTP-EQUIV="Content-Language"
CONTENT="en"><LINK
REL="stylesheet"
HREF="common/kde-localised.css"
TYPE="text/css"
TITLE="KDE-English"><LINK
REL="stylesheet"
HREF="common/kde-default.css"
TYPE="text/css"
TITLE="KDE-Default"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#AA0000"
VLINK="#AA0055"
ALINK="#AA0000"
STYLE="font-family: sans-serif;"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Advanced Bash-Scripting Guide: An in-depth exploration of the art of shell scripting</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="process-sub.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="localvar.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="FUNCTIONS"
></A
>Chapter 24. Functions</H1
><P
><A
NAME="FUNCTIONREF"
></A
></P
><P
>Like <SPAN
CLASS="QUOTE"
>"real"</SPAN
> programming languages,
	Bash has functions, though in a somewhat limited implementation.
	A function is a subroutine, a <A
HREF="special-chars.html#CODEBLOCKREF"
>code
	block</A
> that implements a set of operations, a <SPAN
CLASS="QUOTE"
>"black
	box"</SPAN
> that performs a specified task.  Wherever there is
	repetitive code, when a task repeats with only slight variations in
	procedure, then consider using a function.</P
><P
><P
><B
CLASS="COMMAND"
>function</B
>   <TT
CLASS="REPLACEABLE"
><I
>function_name</I
></TT
>   { <BR>  <TT
CLASS="REPLACEABLE"
><I
>command</I
></TT
>... <BR>  } <BR></P
>
	or 
	<P
> <TT
CLASS="REPLACEABLE"
><I
>function_name</I
></TT
>   ()   { <BR>  <TT
CLASS="REPLACEABLE"
><I
>command</I
></TT
>... <BR>  } <BR></P
>
      </P
><P
>This second form will cheer the hearts of C programmers
	      (and is more <A
HREF="portabilityissues.html"
>portable</A
>).</P
><P
>As in C, the function's opening bracket may optionally appear
        on the second line.</P
><P
><P
> <TT
CLASS="REPLACEABLE"
><I
>function_name</I
></TT
>   () <BR>  { <BR>  <TT
CLASS="REPLACEABLE"
><I
>command</I
></TT
>... <BR>  } <BR></P
>
      </P
><DIV
CLASS="NOTE"
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/note.png"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>A function may be <SPAN
CLASS="QUOTE"
>"compacted"</SPAN
> into a single
          line.</P
><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;fun () { echo "This is a function"; echo; }
   2&nbsp;#                                 ^     ^</PRE
></TD
></TR
></TABLE
></P
><P
>In this case, however, a <I
CLASS="FIRSTTERM"
>semicolon</I
>
          must follow the final command in the function.</P
><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;fun () { echo "This is a function"; echo } # Error!
   2&nbsp;#                                       ^
   3&nbsp;
   4&nbsp;fun2 () { echo "Even a single-command function? Yes!"; }
   5&nbsp;#                                                    ^</PRE
></TD
></TR
></TABLE
></P
></TD
></TR
></TABLE
></DIV
><P
>Functions are called, <I
CLASS="FIRSTTERM"
>triggered</I
>, simply by
	invoking their names. <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>A function call is equivalent to
	a command.</I
></SPAN
></P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX59"
></A
><P
><B
>Example 24-1. Simple functions</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# ex59.sh: Exercising functions (simple).
   3&nbsp;
   4&nbsp;JUST_A_SECOND=1
   5&nbsp;
   6&nbsp;funky ()
   7&nbsp;{ # This is about as simple as functions get.
   8&nbsp;  echo "This is a funky function."
   9&nbsp;  echo "Now exiting funky function."
  10&nbsp;} # Function declaration must precede call.
  11&nbsp;
  12&nbsp;
  13&nbsp;fun ()
  14&nbsp;{ # A somewhat more complex function.
  15&nbsp;  i=0
  16&nbsp;  REPEATS=30
  17&nbsp;
  18&nbsp;  echo
  19&nbsp;  echo "And now the fun really begins."
  20&nbsp;  echo
  21&nbsp;
  22&nbsp;  sleep $JUST_A_SECOND    # Hey, wait a second!
  23&nbsp;  while [ $i -lt $REPEATS ]
  24&nbsp;  do
  25&nbsp;    echo "----------FUNCTIONS----------&#62;"
  26&nbsp;    echo "&#60;------------ARE-------------"
  27&nbsp;    echo "&#60;------------FUN------------&#62;"
  28&nbsp;    echo
  29&nbsp;    let "i+=1"
  30&nbsp;  done
  31&nbsp;}
  32&nbsp;
  33&nbsp;  # Now, call the functions.
  34&nbsp;
  35&nbsp;funky
  36&nbsp;fun
  37&nbsp;
  38&nbsp;exit $?</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="FUNCTDEFMUST"
></A
></P
><P
>The function definition must precede the first call to
	it. There is no method of <SPAN
CLASS="QUOTE"
>"declaring"</SPAN
> the function,
	as, for example, in C.
	  <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;f1
   2&nbsp;# Will give an error message, since function "f1" not yet defined.
   3&nbsp;
   4&nbsp;declare -f f1      # This doesn't help either.
   5&nbsp;f1                 # Still an error message.
   6&nbsp;
   7&nbsp;# However...
   8&nbsp;
   9&nbsp;	  
  10&nbsp;f1 ()
  11&nbsp;{
  12&nbsp;  echo "Calling function \"f2\" from within function \"f1\"."
  13&nbsp;  f2
  14&nbsp;}
  15&nbsp;
  16&nbsp;f2 ()
  17&nbsp;{
  18&nbsp;  echo "Function \"f2\"."
  19&nbsp;}
  20&nbsp;
  21&nbsp;f1  #  Function "f2" is not actually called until this point,
  22&nbsp;    #+ although it is referenced before its definition.
  23&nbsp;    #  This is permissible.
  24&nbsp;    
  25&nbsp;    # Thanks, S.C.</PRE
></TD
></TR
></TABLE
>
      </P
><DIV
CLASS="NOTE"
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/note.png"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
><A
NAME="EMPTYFUNC"
></A
>Functions may not be empty!
        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# empty-function.sh
   3&nbsp;
   4&nbsp;empty ()
   5&nbsp;{
   6&nbsp;}
   7&nbsp;
   8&nbsp;exit 0  # Will not exit here!
   9&nbsp;
  10&nbsp;# $ sh empty-function.sh
  11&nbsp;# empty-function.sh: line 6: syntax error near unexpected token `}'
  12&nbsp;# empty-function.sh: line 6: `}'
  13&nbsp;
  14&nbsp;# $ echo $?
  15&nbsp;# 2
  16&nbsp;
  17&nbsp;
  18&nbsp;# Note that a function containing only comments is empty.
  19&nbsp;
  20&nbsp;func ()
  21&nbsp;{
  22&nbsp;  # Comment 1.
  23&nbsp;  # Comment 2.
  24&nbsp;  # This is still an empty function.
  25&nbsp;  # Thank you, Mark Bova, for pointing this out.
  26&nbsp;}
  27&nbsp;# Results in same error message as above.
  28&nbsp;
  29&nbsp;
  30&nbsp;# However ...
  31&nbsp;
  32&nbsp;not_quite_empty ()
  33&nbsp;{
  34&nbsp;  illegal_command
  35&nbsp;} #  A script containing this function will *not* bomb
  36&nbsp;  #+ as long as the function is not called.
  37&nbsp;
  38&nbsp;not_empty ()
  39&nbsp;{
  40&nbsp;  :
  41&nbsp;} # Contains a : (null command), and this is okay.
  42&nbsp;
  43&nbsp;
  44&nbsp;# Thank you, Dominick Geyer and Thiemo Kellner.</PRE
></TD
></TR
></TABLE
></P
></TD
></TR
></TABLE
></DIV
><P
>It is even possible to nest a function within another function,
        although this is not very useful.
	  <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;f1 ()
   2&nbsp;{
   3&nbsp;
   4&nbsp;  f2 () # nested
   5&nbsp;  {
   6&nbsp;    echo "Function \"f2\", inside \"f1\"."
   7&nbsp;  }
   8&nbsp;
   9&nbsp;}  
  10&nbsp;
  11&nbsp;f2  #  Gives an error message.
  12&nbsp;    #  Even a preceding "declare -f f2" wouldn't help.
  13&nbsp;
  14&nbsp;echo    
  15&nbsp;
  16&nbsp;f1  #  Does nothing, since calling "f1" does not automatically call "f2".
  17&nbsp;f2  #  Now, it's all right to call "f2",
  18&nbsp;    #+ since its definition has been made visible by calling "f1".
  19&nbsp;
  20&nbsp;    # Thanks, S.C.</PRE
></TD
></TR
></TABLE
>
      </P
><P
>Function declarations can appear in unlikely places, even where a
        command would otherwise go.
          <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;ls -l | foo() { echo "foo"; }  # Permissible, but useless.
   2&nbsp;
   3&nbsp;
   4&nbsp;
   5&nbsp;if [ "$USER" = bozo ]
   6&nbsp;then
   7&nbsp;  bozo_greet ()   # Function definition embedded in an if/then construct.
   8&nbsp;  {
   9&nbsp;    echo "Hello, Bozo."
  10&nbsp;  }
  11&nbsp;fi  
  12&nbsp;
  13&nbsp;bozo_greet        # Works only for Bozo, and other users get an error.
  14&nbsp;
  15&nbsp;
  16&nbsp;
  17&nbsp;# Something like this might be useful in some contexts.
  18&nbsp;NO_EXIT=1   # Will enable function definition below.
  19&nbsp;
  20&nbsp;[[ $NO_EXIT -eq 1 ]] &#38;&#38; exit() { true; }     # Function definition in an "and-list".
  21&nbsp;# If $NO_EXIT is 1, declares "exit ()".
  22&nbsp;# This disables the "exit" builtin by aliasing it to "true".
  23&nbsp;
  24&nbsp;exit  # Invokes "exit ()" function, not "exit" builtin.
  25&nbsp;
  26&nbsp;
  27&nbsp;
  28&nbsp;# Or, similarly:
  29&nbsp;filename=file1
  30&nbsp;
  31&nbsp;[ -f "$filename" ] &#38;&#38;
  32&nbsp;foo () { rm -f "$filename"; echo "File "$filename" deleted."; } ||
  33&nbsp;foo () { echo "File "$filename" not found."; touch bar; }
  34&nbsp;
  35&nbsp;foo
  36&nbsp;
  37&nbsp;# Thanks, S.C. and Christopher Head</PRE
></TD
></TR
></TABLE
>
      </P
><P
><A
NAME="FSTRANGEREF"
></A
>Function names can take strange
      forms.
        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;  _(){ for i in {1..10}; do echo -n "$FUNCNAME"; done; echo; }
   2&nbsp;# ^^^         No space between function name and parentheses.
   3&nbsp;#             This doesn't always work. Why not?
   4&nbsp;
   5&nbsp;# Now, let's invoke the function.
   6&nbsp;  _         # __________
   7&nbsp;#             ^^^^^^^^^^   10 underscores (10 x function name)!  
   8&nbsp;# A "naked" underscore is an acceptable function name.
   9&nbsp;
  10&nbsp;
  11&nbsp;# In fact, a colon is likewise an acceptable function name.
  12&nbsp;
  13&nbsp;:(){ echo ":"; }; :
  14&nbsp;
  15&nbsp;# Of what use is this?
  16&nbsp;# It's a devious way to obfuscate the code in a script.</PRE
></TD
></TR
></TABLE
>
      See also <A
HREF="contributed-scripts.html#GRONSFELD"
>Example A-56</A
></P
><DIV
CLASS="NOTE"
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/note.png"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>What happens when different versions of the same function
        appear in a script?
	<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#  As Yan Chen points out,
   2&nbsp;#  when a function is defined multiple times,
   3&nbsp;#  the final version is what is invoked.
   4&nbsp;#  This is not, however, particularly useful.
   5&nbsp;
   6&nbsp;func ()
   7&nbsp;{
   8&nbsp;  echo "First version of func ()."
   9&nbsp;}
  10&nbsp;
  11&nbsp;func ()
  12&nbsp;{
  13&nbsp;  echo "Second version of func ()."
  14&nbsp;}
  15&nbsp;
  16&nbsp;func   # Second version of func ().
  17&nbsp;
  18&nbsp;exit $?
  19&nbsp;
  20&nbsp;#  It is even possible to use functions to override
  21&nbsp;#+ or preempt system commands.
  22&nbsp;#  Of course, this is *not* advisable.</PRE
></TD
></TR
></TABLE
></P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="COMPLEXFUNCT"
></A
>24.1. Complex Functions and Function Complexities</H1
><P
>Functions may process arguments passed to them and return
	an <A
HREF="exit-status.html#EXITSTATUSREF"
>exit status</A
> to the script
	for further processing.</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;function_name $arg1 $arg2</PRE
></TD
></TR
></TABLE
><P
><A
NAME="PASSEDARGS"
></A
></P
><P
>The function refers to the passed arguments by position (as if they were
	<A
HREF="variables2.html#POSPARAMREF"
>positional parameters</A
>),
	that is, <TT
CLASS="VARNAME"
>$1</TT
>, <TT
CLASS="VARNAME"
>$2</TT
>, and
	so forth.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX60"
></A
><P
><B
>Example 24-2. Function Taking Parameters</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# Functions and parameters
   3&nbsp;
   4&nbsp;DEFAULT=default                             # Default param value.
   5&nbsp;
   6&nbsp;func2 () {
   7&nbsp;   if [ -z "$1" ]                           # Is parameter #1 zero length?
   8&nbsp;   then
   9&nbsp;     echo "-Parameter #1 is zero length.-"  # Or no parameter passed.
  10&nbsp;   else
  11&nbsp;     echo "-Parameter #1 is \"$1\".-"
  12&nbsp;   fi
  13&nbsp;
  14&nbsp;   variable=${1-$DEFAULT}                   #  What does
  15&nbsp;   echo "variable = $variable"              #+ parameter substitution show?
  16&nbsp;                                            #  ---------------------------
  17&nbsp;                                            #  It distinguishes between
  18&nbsp;                                            #+ no param and a null param.
  19&nbsp;
  20&nbsp;   if [ "$2" ]
  21&nbsp;   then
  22&nbsp;     echo "-Parameter #2 is \"$2\".-"
  23&nbsp;   fi
  24&nbsp;
  25&nbsp;   return 0
  26&nbsp;}
  27&nbsp;
  28&nbsp;echo
  29&nbsp;   
  30&nbsp;echo "Nothing passed."   
  31&nbsp;func2                          # Called with no params
  32&nbsp;echo
  33&nbsp;
  34&nbsp;
  35&nbsp;echo "Zero-length parameter passed."
  36&nbsp;func2 ""                       # Called with zero-length param
  37&nbsp;echo
  38&nbsp;
  39&nbsp;echo "Null parameter passed."
  40&nbsp;func2 "$uninitialized_param"   # Called with uninitialized param
  41&nbsp;echo
  42&nbsp;
  43&nbsp;echo "One parameter passed."   
  44&nbsp;func2 first           # Called with one param
  45&nbsp;echo
  46&nbsp;
  47&nbsp;echo "Two parameters passed."   
  48&nbsp;func2 first second    # Called with two params
  49&nbsp;echo
  50&nbsp;
  51&nbsp;echo "\"\" \"second\" passed."
  52&nbsp;func2 "" second       # Called with zero-length first parameter
  53&nbsp;echo                  # and ASCII string as a second one.
  54&nbsp;
  55&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="FSHIFTREF"
></A
></P
><DIV
CLASS="IMPORTANT"
><TABLE
CLASS="IMPORTANT"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/important.png"
HSPACE="5"
ALT="Important"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>The <A
HREF="othertypesv.html#SHIFTREF"
>shift</A
>
        command works on arguments passed to functions (see <A
HREF="assortedtips.html#MULTIPLICATION"
>Example 36-18</A
>).</P
></TD
></TR
></TABLE
></DIV
><P
>But, what about command-line arguments passed to the script? 
        Does a function see them? Well, let's clear up the confusion.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="FUNCCMDLINEARG"
></A
><P
><B
>Example 24-3. Functions and command-line args passed to the script</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# func-cmdlinearg.sh
   3&nbsp;#  Call this script with a command-line argument,
   4&nbsp;#+ something like $0 arg1.
   5&nbsp;
   6&nbsp;
   7&nbsp;func ()
   8&nbsp;
   9&nbsp;{
  10&nbsp;echo "$1"   # Echoes first arg passed to the function.
  11&nbsp;}           # Does a command-line arg qualify?
  12&nbsp;
  13&nbsp;echo "First call to function: no arg passed."
  14&nbsp;echo "See if command-line arg is seen."
  15&nbsp;func
  16&nbsp;# No! Command-line arg not seen.
  17&nbsp;
  18&nbsp;echo "============================================================"
  19&nbsp;echo
  20&nbsp;echo "Second call to function: command-line arg passed explicitly."
  21&nbsp;func $1
  22&nbsp;# Now it's seen!
  23&nbsp;
  24&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
>In contrast to certain other programming languages,
	shell scripts normally pass only value parameters to
	functions. Variable names (which are actually
	<I
CLASS="FIRSTTERM"
>pointers</I
>), if
	passed as parameters to functions, will be treated as string
	literals.  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Functions interpret their arguments
	literally.</I
></SPAN
></P
><P
><A
NAME="FUNCPOINTERS"
></A
></P
><P
><A
HREF="ivr.html#IVRREF"
>Indirect variable
	    references</A
> (see <A
HREF="bash2.html#EX78"
>Example 37-2</A
>) provide a clumsy
	    sort of mechanism for passing variable pointers to
	    functions.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="INDFUNC"
></A
><P
><B
>Example 24-4. Passing an indirect reference to a function</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# ind-func.sh: Passing an indirect reference to a function.
   3&nbsp;
   4&nbsp;echo_var ()
   5&nbsp;{
   6&nbsp;echo "$1"
   7&nbsp;}
   8&nbsp;
   9&nbsp;message=Hello
  10&nbsp;Hello=Goodbye
  11&nbsp;
  12&nbsp;echo_var "$message"        # Hello
  13&nbsp;# Now, let's pass an indirect reference to the function.
  14&nbsp;echo_var "${!message}"     # Goodbye
  15&nbsp;
  16&nbsp;echo "-------------"
  17&nbsp;
  18&nbsp;# What happens if we change the contents of "hello" variable?
  19&nbsp;Hello="Hello, again!"
  20&nbsp;echo_var "$message"        # Hello
  21&nbsp;echo_var "${!message}"     # Hello, again!
  22&nbsp;
  23&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
>The next logical question is whether parameters can be
	  dereferenced <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>after</I
></SPAN
> being passed to a
	  function.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="DEREFERENCECL"
></A
><P
><B
>Example 24-5. Dereferencing a parameter passed to a function</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# dereference.sh
   3&nbsp;# Dereferencing parameter passed to a function.
   4&nbsp;# Script by Bruce W. Clare.
   5&nbsp;
   6&nbsp;dereference ()
   7&nbsp;{
   8&nbsp;     y=\$"$1"   # Name of variable (not value!).
   9&nbsp;     echo $y    # $Junk
  10&nbsp;
  11&nbsp;     x=`eval "expr \"$y\" "`
  12&nbsp;     echo $1=$x
  13&nbsp;     eval "$1=\"Some Different Text \""  # Assign new value.
  14&nbsp;}
  15&nbsp;
  16&nbsp;Junk="Some Text"
  17&nbsp;echo $Junk "before"    # Some Text before
  18&nbsp;
  19&nbsp;dereference Junk
  20&nbsp;echo $Junk "after"     # Some Different Text after
  21&nbsp;
  22&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="REFPARAMS"
></A
><P
><B
>Example 24-6. Again, dereferencing a parameter passed to a function</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# ref-params.sh: Dereferencing a parameter passed to a function.
   3&nbsp;#                (Complex Example)
   4&nbsp;
   5&nbsp;ITERATIONS=3  # How many times to get input.
   6&nbsp;icount=1
   7&nbsp;
   8&nbsp;my_read () {
   9&nbsp;  #  Called with my_read varname,
  10&nbsp;  #+ outputs the previous value between brackets as the default value,
  11&nbsp;  #+ then asks for a new value.
  12&nbsp;
  13&nbsp;  local local_var
  14&nbsp;
  15&nbsp;  echo -n "Enter a value "
  16&nbsp;  eval 'echo -n "[$'$1'] "'  #  Previous value.
  17&nbsp;# eval echo -n "[\$$1] "     #  Easier to understand,
  18&nbsp;                             #+ but loses trailing space in user prompt.
  19&nbsp;  read local_var
  20&nbsp;  [ -n "$local_var" ] &#38;&#38; eval $1=\$local_var
  21&nbsp;
  22&nbsp;  # "And-list": if "local_var" then set "$1" to its value.
  23&nbsp;}
  24&nbsp;
  25&nbsp;echo
  26&nbsp;
  27&nbsp;while [ "$icount" -le "$ITERATIONS" ]
  28&nbsp;do
  29&nbsp;  my_read var
  30&nbsp;  echo "Entry #$icount = $var"
  31&nbsp;  let "icount += 1"
  32&nbsp;  echo
  33&nbsp;done  
  34&nbsp;
  35&nbsp;
  36&nbsp;# Thanks to Stephane Chazelas for providing this instructive example.
  37&nbsp;
  38&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><DIV
CLASS="VARIABLELIST"
><P
><B
><A
NAME="EXITRETURN1"
></A
>Exit and Return</B
></P
><DL
><DT
><B
CLASS="COMMAND"
>exit status</B
></DT
><DD
><P
>Functions return a value, called an <I
CLASS="FIRSTTERM"
>exit
	      status</I
>. This is analogous to the <A
HREF="exit-status.html#EXITSTATUSREF"
>exit status</A
> returned by a
	      command. The exit status may be explicitly specified
	      by a <B
CLASS="COMMAND"
>return</B
> statement, otherwise it
	      is the exit status of the last command in the function
	      (<SPAN
CLASS="RETURNVALUE"
>0</SPAN
> if successful, and a non-zero
	      error code if not). This <A
HREF="exit-status.html#EXITSTATUSREF"
>exit
	      status</A
> may be used in the script by referencing it
	      as <A
HREF="variables2.html#XSTATVARREF"
>$?</A
>.  This mechanism
	      effectively permits script functions to have a <SPAN
CLASS="QUOTE"
>"return
	      value"</SPAN
> similar to C functions.</P
></DD
><DT
><B
CLASS="COMMAND"
>return</B
></DT
><DD
><P
><A
NAME="RETURNREF"
></A
></P
><P
>Terminates a function. A <B
CLASS="COMMAND"
>return</B
> command
	       <A
NAME="AEN18474"
HREF="#FTN.AEN18474"
>[1]</A
>
	      optionally takes an <I
CLASS="FIRSTTERM"
>integer</I
>
	      argument, which is returned to the calling script as
	      the <SPAN
CLASS="QUOTE"
>"exit status"</SPAN
> of the function, and
	      this exit status is assigned to the variable <A
HREF="variables2.html#XSTATVARREF"
>$?</A
>.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="MAX"
></A
><P
><B
>Example 24-7. Maximum of two numbers</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# max.sh: Maximum of two integers.
   3&nbsp;
   4&nbsp;E_PARAM_ERR=250    # If less than 2 params passed to function.
   5&nbsp;EQUAL=251          # Return value if both params equal.
   6&nbsp;#  Error values out of range of any
   7&nbsp;#+ params that might be fed to the function.
   8&nbsp;
   9&nbsp;max2 ()             # Returns larger of two numbers.
  10&nbsp;{                   # Note: numbers compared must be less than 250.
  11&nbsp;if [ -z "$2" ]
  12&nbsp;then
  13&nbsp;  return $E_PARAM_ERR
  14&nbsp;fi
  15&nbsp;
  16&nbsp;if [ "$1" -eq "$2" ]
  17&nbsp;then
  18&nbsp;  return $EQUAL
  19&nbsp;else
  20&nbsp;  if [ "$1" -gt "$2" ]
  21&nbsp;  then
  22&nbsp;    return $1
  23&nbsp;  else
  24&nbsp;    return $2
  25&nbsp;  fi
  26&nbsp;fi
  27&nbsp;}
  28&nbsp;
  29&nbsp;max2 33 34
  30&nbsp;return_val=$?
  31&nbsp;
  32&nbsp;if [ "$return_val" -eq $E_PARAM_ERR ]
  33&nbsp;then
  34&nbsp;  echo "Need to pass two parameters to the function."
  35&nbsp;elif [ "$return_val" -eq $EQUAL ]
  36&nbsp;  then
  37&nbsp;    echo "The two numbers are equal."
  38&nbsp;else
  39&nbsp;    echo "The larger of the two numbers is $return_val."
  40&nbsp;fi  
  41&nbsp;
  42&nbsp;  
  43&nbsp;exit 0
  44&nbsp;
  45&nbsp;#  Exercise (easy):
  46&nbsp;#  ---------------
  47&nbsp;#  Convert this to an interactive script,
  48&nbsp;#+ that is, have the script ask for input (two numbers).</PRE
></TD
></TR
></TABLE
><HR></DIV
><DIV
CLASS="TIP"
><TABLE
CLASS="TIP"
WIDTH="90%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/tip.png"
HSPACE="5"
ALT="Tip"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>For a function to return a string or array, use a
	      dedicated variable.
	        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;count_lines_in_etc_passwd()
   2&nbsp;{
   3&nbsp;  [[ -r /etc/passwd ]] &#38;&#38; REPLY=$(echo $(wc -l &#60; /etc/passwd))
   4&nbsp;  #  If /etc/passwd is readable, set REPLY to line count.
   5&nbsp;  #  Returns both a parameter value and status information.
   6&nbsp;  #  The 'echo' seems unnecessary, but . . .
   7&nbsp;  #+ it removes excess whitespace from the output.
   8&nbsp;}
   9&nbsp;
  10&nbsp;if count_lines_in_etc_passwd
  11&nbsp;then
  12&nbsp;  echo "There are $REPLY lines in /etc/passwd."
  13&nbsp;else
  14&nbsp;  echo "Cannot count lines in /etc/passwd."
  15&nbsp;fi  
  16&nbsp;
  17&nbsp;# Thanks, S.C.</PRE
></TD
></TR
></TABLE
>
	    </P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX61"
></A
><P
><B
>Example 24-8. Converting numbers to Roman numerals</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;
   3&nbsp;# Arabic number to Roman numeral conversion
   4&nbsp;# Range: 0 - 200
   5&nbsp;# It's crude, but it works.
   6&nbsp;
   7&nbsp;# Extending the range and otherwise improving the script is left as an exercise.
   8&nbsp;
   9&nbsp;# Usage: roman number-to-convert
  10&nbsp;
  11&nbsp;LIMIT=200
  12&nbsp;E_ARG_ERR=65
  13&nbsp;E_OUT_OF_RANGE=66
  14&nbsp;
  15&nbsp;if [ -z "$1" ]
  16&nbsp;then
  17&nbsp;  echo "Usage: `basename $0` number-to-convert"
  18&nbsp;  exit $E_ARG_ERR
  19&nbsp;fi  
  20&nbsp;
  21&nbsp;num=$1
  22&nbsp;if [ "$num" -gt $LIMIT ]
  23&nbsp;then
  24&nbsp;  echo "Out of range!"
  25&nbsp;  exit $E_OUT_OF_RANGE
  26&nbsp;fi  
  27&nbsp;
  28&nbsp;to_roman ()   # Must declare function before first call to it.
  29&nbsp;{
  30&nbsp;number=$1
  31&nbsp;factor=$2
  32&nbsp;rchar=$3
  33&nbsp;let "remainder = number - factor"
  34&nbsp;while [ "$remainder" -ge 0 ]
  35&nbsp;do
  36&nbsp;  echo -n $rchar
  37&nbsp;  let "number -= factor"
  38&nbsp;  let "remainder = number - factor"
  39&nbsp;done  
  40&nbsp;
  41&nbsp;return $number
  42&nbsp;       # Exercises:
  43&nbsp;       # ---------
  44&nbsp;       # 1) Explain how this function works.
  45&nbsp;       #    Hint: division by successive subtraction.
  46&nbsp;       # 2) Extend to range of the function.
  47&nbsp;       #    Hint: use "echo" and command-substitution capture.
  48&nbsp;}
  49&nbsp;   
  50&nbsp;
  51&nbsp;to_roman $num 100 C
  52&nbsp;num=$?
  53&nbsp;to_roman $num 90 LXXXX
  54&nbsp;num=$?
  55&nbsp;to_roman $num 50 L
  56&nbsp;num=$?
  57&nbsp;to_roman $num 40 XL
  58&nbsp;num=$?
  59&nbsp;to_roman $num 10 X
  60&nbsp;num=$?
  61&nbsp;to_roman $num 9 IX
  62&nbsp;num=$?
  63&nbsp;to_roman $num 5 V
  64&nbsp;num=$?
  65&nbsp;to_roman $num 4 IV
  66&nbsp;num=$?
  67&nbsp;to_roman $num 1 I
  68&nbsp;# Successive calls to conversion function!
  69&nbsp;# Is this really necessary??? Can it be simplified?
  70&nbsp;
  71&nbsp;echo
  72&nbsp;
  73&nbsp;exit</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
>See also <A
HREF="testbranch.html#ISALPHA"
>Example 11-29</A
>.</P
><DIV
CLASS="IMPORTANT"
><TABLE
CLASS="IMPORTANT"
WIDTH="90%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/important.png"
HSPACE="5"
ALT="Important"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>The largest positive integer a function can return is
	      255. The <B
CLASS="COMMAND"
>return</B
> command is closely tied
	      to the concept of <A
HREF="exit-status.html#EXITSTATUSREF"
>exit
	      status</A
>, which accounts for this particular
	      limitation.  Fortunately, there are various <A
HREF="assortedtips.html#RVT"
>workarounds</A
> for those situations
	      requiring a large integer return value from a
	      function.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="RETURNTEST"
></A
><P
><B
>Example 24-9. Testing large return values in a function</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# return-test.sh
   3&nbsp;
   4&nbsp;# The largest positive value a function can return is 255.
   5&nbsp;
   6&nbsp;return_test ()         # Returns whatever passed to it.
   7&nbsp;{
   8&nbsp;  return $1
   9&nbsp;}
  10&nbsp;
  11&nbsp;return_test 27         # o.k.
  12&nbsp;echo $?                # Returns 27.
  13&nbsp;  
  14&nbsp;return_test 255        # Still o.k.
  15&nbsp;echo $?                # Returns 255.
  16&nbsp;
  17&nbsp;return_test 257        # Error!
  18&nbsp;echo $?                # Returns 1 (return code for miscellaneous error).
  19&nbsp;
  20&nbsp;# =========================================================
  21&nbsp;return_test -151896    # Do large negative numbers work?
  22&nbsp;echo $?                # Will this return -151896?
  23&nbsp;                       # No! It returns 168.
  24&nbsp;#  Version of Bash before 2.05b permitted
  25&nbsp;#+ large negative integer return values.
  26&nbsp;#  It happened to be a useful feature.
  27&nbsp;#  Newer versions of Bash unfortunately plug this loophole.
  28&nbsp;#  This may break older scripts.
  29&nbsp;#  Caution!
  30&nbsp;# =========================================================
  31&nbsp;
  32&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
>A workaround for obtaining large integer <SPAN
CLASS="QUOTE"
>"return
	      values"</SPAN
> is to simply assign the <SPAN
CLASS="QUOTE"
>"return
	      value"</SPAN
> to a global variable.

	        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;Return_Val=   # Global variable to hold oversize return value of function.
   2&nbsp;
   3&nbsp;alt_return_test ()
   4&nbsp;{
   5&nbsp;  fvar=$1
   6&nbsp;  Return_Val=$fvar
   7&nbsp;  return   # Returns 0 (success).
   8&nbsp;}
   9&nbsp;
  10&nbsp;alt_return_test 1
  11&nbsp;echo $?                              # 0
  12&nbsp;echo "return value = $Return_Val"    # 1
  13&nbsp;
  14&nbsp;alt_return_test 256
  15&nbsp;echo "return value = $Return_Val"    # 256
  16&nbsp;
  17&nbsp;alt_return_test 257
  18&nbsp;echo "return value = $Return_Val"    # 257
  19&nbsp;
  20&nbsp;alt_return_test 25701
  21&nbsp;echo "return value = $Return_Val"    #25701</PRE
></TD
></TR
></TABLE
>
            </P
><P
><A
NAME="CAPTURERETVAL"
></A
></P
><P
>A more elegant method is to have the function
              <B
CLASS="COMMAND"
>echo</B
> its <SPAN
CLASS="QUOTE"
>"return
              value to <TT
CLASS="FILENAME"
>stdout</TT
>,"</SPAN
> and
              then capture it by <A
HREF="commandsub.html#COMMANDSUBREF"
>command
	      substitution</A
>. See the <A
HREF="assortedtips.html#RVT"
>discussion
	      of this</A
> in <A
HREF="assortedtips.html"
>Section 36.7</A
>.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="MAX2"
></A
><P
><B
>Example 24-10. Comparing two large integers</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# max2.sh: Maximum of two LARGE integers.
   3&nbsp;
   4&nbsp;#  This is the previous "max.sh" example,
   5&nbsp;#+ modified to permit comparing large integers.
   6&nbsp;
   7&nbsp;EQUAL=0             # Return value if both params equal.
   8&nbsp;E_PARAM_ERR=-99999  # Not enough params passed to function.
   9&nbsp;#           ^^^^^^    Out of range of any params that might be passed.
  10&nbsp;
  11&nbsp;max2 ()             # "Returns" larger of two numbers.
  12&nbsp;{
  13&nbsp;if [ -z "$2" ]
  14&nbsp;then
  15&nbsp;  echo $E_PARAM_ERR
  16&nbsp;  return
  17&nbsp;fi
  18&nbsp;
  19&nbsp;if [ "$1" -eq "$2" ]
  20&nbsp;then
  21&nbsp;  echo $EQUAL
  22&nbsp;  return
  23&nbsp;else
  24&nbsp;  if [ "$1" -gt "$2" ]
  25&nbsp;  then
  26&nbsp;    retval=$1
  27&nbsp;  else
  28&nbsp;    retval=$2
  29&nbsp;  fi
  30&nbsp;fi
  31&nbsp;
  32&nbsp;echo $retval        # Echoes (to stdout), rather than returning value.
  33&nbsp;                    # Why?
  34&nbsp;}
  35&nbsp;
  36&nbsp;
  37&nbsp;return_val=$(max2 33001 33997)
  38&nbsp;#            ^^^^             Function name
  39&nbsp;#                 ^^^^^ ^^^^^ Params passed
  40&nbsp;#  This is actually a form of command substitution:
  41&nbsp;#+ treating a function as if it were a command,
  42&nbsp;#+ and assigning the stdout of the function to the variable "return_val."
  43&nbsp;
  44&nbsp;
  45&nbsp;# ========================= OUTPUT ========================
  46&nbsp;if [ "$return_val" -eq "$E_PARAM_ERR" ]
  47&nbsp;  then
  48&nbsp;  echo "Error in parameters passed to comparison function!"
  49&nbsp;elif [ "$return_val" -eq "$EQUAL" ]
  50&nbsp;  then
  51&nbsp;    echo "The two numbers are equal."
  52&nbsp;else
  53&nbsp;    echo "The larger of the two numbers is $return_val."
  54&nbsp;fi
  55&nbsp;# =========================================================
  56&nbsp;  
  57&nbsp;exit 0
  58&nbsp;
  59&nbsp;#  Exercises:
  60&nbsp;#  ---------
  61&nbsp;#  1) Find a more elegant way of testing
  62&nbsp;#+    the parameters passed to the function.
  63&nbsp;#  2) Simplify the if/then structure at "OUTPUT."
  64&nbsp;#  3) Rewrite the script to take input from command-line parameters.</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
>Here is another example of capturing a function
	      <SPAN
CLASS="QUOTE"
>"return value."</SPAN
> Understanding it requires some
	      knowledge of <A
HREF="awk.html#AWKREF"
>awk</A
>.

	    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;month_length ()  # Takes month number as an argument.
   2&nbsp;{                # Returns number of days in month.
   3&nbsp;monthD="31 28 31 30 31 30 31 31 30 31 30 31"  # Declare as local?
   4&nbsp;echo "$monthD" | awk '{ print $'"${1}"' }'    # Tricky.
   5&nbsp;#                             ^^^^^^^^^
   6&nbsp;# Parameter passed to function  ($1 -- month number), then to awk.
   7&nbsp;# Awk sees this as "print $1 . . . print $12" (depending on month number)
   8&nbsp;# Template for passing a parameter to embedded awk script:
   9&nbsp;#                                 $'"${script_parameter}"'
  10&nbsp;
  11&nbsp;#    Here's a slightly simpler awk construct:
  12&nbsp;#    echo $monthD | awk -v month=$1 '{print $(month)}'
  13&nbsp;#    Uses the -v awk option, which assigns a variable value
  14&nbsp;#+   prior to execution of the awk program block.
  15&nbsp;#    Thank you, Rich.
  16&nbsp;
  17&nbsp;#  Needs error checking for correct parameter range (1-12)
  18&nbsp;#+ and for February in leap year.
  19&nbsp;}
  20&nbsp;
  21&nbsp;# ----------------------------------------------
  22&nbsp;# Usage example:
  23&nbsp;month=4        # April, for example (4th month).
  24&nbsp;days_in=$(month_length $month)
  25&nbsp;echo $days_in  # 30
  26&nbsp;# ----------------------------------------------</PRE
></TD
></TR
></TABLE
></P
><P
>See also <A
HREF="contributed-scripts.html#DAYSBETWEEN"
>Example A-7</A
>
	      and <A
HREF="contributed-scripts.html#STDDEV"
>Example A-37</A
>.</P
><P
><TT
CLASS="USERINPUT"
><B
>Exercise:</B
></TT
> Using what we have
	      just learned, extend the previous <A
HREF="functions.html#EX61"
>Roman numerals example</A
> to accept
	      arbitrarily large input.</P
></TD
></TR
></TABLE
></DIV
></DD
></DL
></DIV
><DIV
CLASS="VARIABLELIST"
><P
><B
><A
NAME="REDSTDINFUNC1"
></A
>Redirection</B
></P
><DL
><DT
><TT
CLASS="REPLACEABLE"
><I
>Redirecting the stdin
	    of a function</I
></TT
></DT
><DD
><P
>A function is essentially a <A
HREF="special-chars.html#CODEBLOCKREF"
>code block</A
>, which means its
	      <TT
CLASS="FILENAME"
>stdin</TT
> can be redirected (as in <A
HREF="special-chars.html#EX8"
>Example 3-1</A
>).</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="REALNAME"
></A
><P
><B
>Example 24-11. Real name from username</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# realname.sh
   3&nbsp;#
   4&nbsp;# From username, gets "real name" from /etc/passwd.
   5&nbsp;
   6&nbsp;
   7&nbsp;ARGCOUNT=1       # Expect one arg.
   8&nbsp;E_WRONGARGS=85
   9&nbsp;
  10&nbsp;file=/etc/passwd
  11&nbsp;pattern=$1
  12&nbsp;
  13&nbsp;if [ $# -ne "$ARGCOUNT" ]
  14&nbsp;then
  15&nbsp;  echo "Usage: `basename $0` USERNAME"
  16&nbsp;  exit $E_WRONGARGS
  17&nbsp;fi  
  18&nbsp;
  19&nbsp;file_excerpt ()    #  Scan file for pattern,
  20&nbsp;{                  #+ then print relevant portion of line.
  21&nbsp;  while read line  # "while" does not necessarily need [ condition ]
  22&nbsp;  do
  23&nbsp;    echo "$line" | grep $1 | awk -F":" '{ print $5 }'
  24&nbsp;    # Have awk use ":" delimiter.
  25&nbsp;  done
  26&nbsp;} &#60;$file  # Redirect into function's stdin.
  27&nbsp;
  28&nbsp;file_excerpt $pattern
  29&nbsp;
  30&nbsp;# Yes, this entire script could be reduced to
  31&nbsp;#       grep PATTERN /etc/passwd | awk -F":" '{ print $5 }'
  32&nbsp;# or
  33&nbsp;#       awk -F: '/PATTERN/ {print $5}'
  34&nbsp;# or
  35&nbsp;#       awk -F: '($1 == "username") { print $5 }' # real name from username
  36&nbsp;# However, it might not be as instructive.
  37&nbsp;
  38&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
>There is an alternate, and perhaps less confusing
	     method of redirecting a function's
	     <TT
CLASS="FILENAME"
>stdin</TT
>.  This involves redirecting the
	     <TT
CLASS="FILENAME"
>stdin</TT
> to an embedded bracketed code
	     block within the function.

	       <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;# Instead of:
   2&nbsp;Function ()
   3&nbsp;{
   4&nbsp; ...
   5&nbsp; } &#60; file
   6&nbsp;
   7&nbsp;# Try this:
   8&nbsp;Function ()
   9&nbsp;{
  10&nbsp;  {
  11&nbsp;    ...
  12&nbsp;   } &#60; file
  13&nbsp;}
  14&nbsp;
  15&nbsp;# Similarly,
  16&nbsp;
  17&nbsp;Function ()  # This works.
  18&nbsp;{
  19&nbsp;  {
  20&nbsp;   echo $*
  21&nbsp;  } | tr a b
  22&nbsp;}
  23&nbsp;
  24&nbsp;Function ()  # This doesn't work.
  25&nbsp;{
  26&nbsp;  echo $*
  27&nbsp;} | tr a b   # A nested code block is mandatory here.
  28&nbsp;
  29&nbsp;
  30&nbsp;# Thanks, S.C.</PRE
></TD
></TR
></TABLE
>
           </P
><DIV
CLASS="NOTE"
><TABLE
CLASS="NOTE"
WIDTH="90%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/note.png"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Emmanuel Rouat's <A
HREF="sample-bashrc.html"
>sample <TT
CLASS="FILENAME"
>bashrc</TT
>
             file</A
> contains some instructive examples of
             functions.</P
></TD
></TR
></TABLE
></DIV
></DD
></DL
></DIV
></DIV
></DIV
><H3
CLASS="FOOTNOTES"
>Notes</H3
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN18474"
HREF="functions.html#AEN18474"
>[1]</A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>The <B
CLASS="COMMAND"
>return</B
> command is a
		 Bash <A
HREF="internal.html#BUILTINREF"
>builtin</A
>.</P
></TD
></TR
></TABLE
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="process-sub.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="localvar.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Process Substitution</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part5.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Local Variables</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>