Function Arguments and Return Values

Access arguments passed to the function.

function_name() {
    local first="$1"      # First argument
    local second="$2"     # Second argument
    local all=("$@")      # All arguments as an array
    local count=$#        # Number of arguments
}

Return a result as an exit status (0 = success, 1 or more = failure).

return 0
return 1

Return a string value (captured with $()).

echo "value to return"

Capture the return value at the call site.

result=$(function_name arg)

Define a function directly in the terminal and pass arguments to it. After pressing Enter following {, a > prompt appears — this signals that input is still expected. Typing } completes the definition.

greet() {
    echo "Hello, $1!"
    echo "You are $2 years old."
}
greet "Kogami Shinya" 28
Hello, Kogami Shinya!
You are 28 years old.

Use $1 through $9 to access individual arguments, $# to get the count, and $@ to access all arguments.

sample_show_args.sh

#!/bin/bash
show_args() {
    echo "Argument count: $#"
    echo "First argument: $1"
    echo "Second argument: $2"
    echo "All arguments: $@"
}

show_args "Kogami Shinya" "Tsunemori Akane" "Ginoza Nobuchika"

Run the following command:

bash show_args.sh
Argument count: 3
First argument: Kogami Shinya
Second argument: Tsunemori Akane
All arguments: Kogami Shinya Tsunemori Akane Ginoza Nobuchika

Check the argument count and return an error if required arguments are missing. Use ${2:-default} to assign a default value to an optional argument.

sample_create_backup.sh

create_backup() {
    if [ $# -lt 1 ]; then
        echo "Error: please specify a file path" >&2
        return 1
    fi
    local src="$1"
    local dst="${2:-${src}.bak}"   # Use .bak suffix if no second argument is given
    cp "$src" "$dst"
    echo "Backed up $src to $dst"
    return 0
}

create_backup "/etc/hosts" "/tmp/hosts.bak"
echo "Exit status: $?"

create_backup   # No arguments — triggers error
echo "Exit status: $?"

Run the following command:

bash create_backup.sh
Backed up /etc/hosts to /tmp/hosts.bak
Exit status: 0
Error: please specify a file path
Exit status: 1

Use shift to process positional parameters one at a time by shifting them to the left on each iteration.

sample_process_all.sh

process_all() {
    while [ $# -gt 0 ]; do
        echo "Processing: $1"
        shift
    done
}

process_all "Kogami Shinya" "Tsunemori Akane" "Ginoza Nobuchika" "Masaoka Tomomi"

Run the following command:

bash process_all.sh
Processing: Kogami Shinya
Processing: Tsunemori Akane
Processing: Ginoza Nobuchika
Processing: Masaoka Tomomi

Using "$@" preserves arguments that contain spaces.

sample_print_each.sh

print_each() {
    for item in "$@"; do
        echo "  [$item]"
    done
}

print_each "Kogami Shinya" "Tsunemori Akane" "Ginoza Nobuchika"

Run the following command:

bash print_each.sh
  [Kogami Shinya]
  [Tsunemori Akane]
  [Ginoza Nobuchika]

Output a string with echo and capture it at the call site using $().

sample_to_upper.sh

to_upper() {
    echo "${1^^}"
}

result=$(to_upper "hello bash")
echo "Uppercase: $result"

Run the following command:

bash to_upper.sh
Uppercase: HELLO BASH

Common Mistake 1: Trying to return a string with return fails

return can only return an integer exit status (0–255). Trying to return a string causes an error or unexpected behavior.

get_name() {
    return "Tsunemori Akane"
}
bash: return: Tsunemori Akane: numeric argument required

Print the value with echo and capture it with command substitution.

get_name() { echo "Tsunemori Akane"; }
name=$(get_name)
echo "$name"
Tsunemori Akane

Common Mistake 2: Passing "$@" without quotes splits arguments at spaces

Without double quotes, arguments containing spaces are split into multiple words when passed to another function.

show() { for arg in $@; do echo "[$arg]"; done; }
show "Kogami Shinya" "Tsunemori Akane"
[Kogami]
[Shinya]
[Tsunemori]
[Akane]

Always quote "$@" to preserve each argument as a single unit.

show() { for arg in "$@"; do echo "[$arg]"; done; }
show "Kogami Shinya" "Tsunemori Akane"
[Kogami Shinya]
[Tsunemori Akane]

Function arguments (positional parameters) are scoped separately from the script's own arguments. Inside a function, $1 refers to the function's first argument, not the script's. If you need to access the script's arguments inside a function, save them to a variable before calling the function.

"$@" safely handles arguments that contain spaces, so always use "$@" when forwarding arguments to another function or command. Unquoted $* and $@ are split on spaces and may behave unexpectedly.

For the basics of defining functions, see Defining and calling functions.