Bash declare builtin command

On Unix-like operating systems, declare is a builtin command of the Bash shell. It declares shell variables and functions, sets their attributes, and displays their values.

Description

In bash, variables can have a value (such as the number 3). Optionally, variables can also be assigned attributes (such as integer).

For instance, a "read-only" variable (declare -r) cannot be unset, and its value and other attributes cannot be modified. An "indexed array" variable (declare -a) is an array of values that are indexed by number, starting at zero. An "associative array" variable (declare -A) is an array of key-value pairs whose values are indexed by a keyword. (For more information, see arrays in bash).

In addition to variables, bash functions can be assigned attributes which affect their behavior. See the -f and -F options below for more information.

Syntax

declare [-a] [-A] [-f] [-F] [-g] [-i] [-l] [-n] [-r]
        [-t] [-u] [-x] [-p] [name[=value]] [name[=value]] ...

Options

The declare builtin command takes the following general options:

The remaining options, listed below, cause declare to set an attribute if the option letter is preceded with a dash. If preceded with a plus sign, declare will unset the attribute instead.

Lexical scope

When declare is used inside a shell function, all named items are declared in a local scope, unless the -g option is used. This behavior is the same as using the local builtin command.

Exit status

The exit status of declare is success (zero), unless an invalid option is specified or an error occurs, in which case the status is failure (non-zero).

Examples

Declaring and listing variables

declare -p

List all declared variables, their attributes, and their values.

declare myvar

Declare a variable, myvar, and assign it no value. Now run the first command again:

declare -p

This time, notice in the output that myvar is listed after all other variables as:

declare -- myvar

The double dash is equivalent to "no options." This means that myvar is declared, and has no attributes. If it had an assigned value, the value would be listed here.

myvar=33

Assign the value 33 to myvar.

declare myvar=33

Same as the above command.

declare -- myvar=33

Same as the above two commands.

declare -- myvar="33"

Same as the above three commands; this is the proper form, including the value being enclosed in double-quotes. However, any of the above four commands have the same effect.

Now, list all variables again:

declare -p

You'll see that this time, the output lists myvar with its value assignment:

declare -- myvar="33"

The key thing to notice here is, when you run declare -p, variables are listed as the complete declare command and you need to set the variable to its current attributes and value.

Setting and unsetting attributes

The next commands modify the variable's attributes:

declare -x myvar

Declare that myvar should be exported to any child shell processes. This is the equivalent of using the export command:

export myvar

Now, list variable declarations:

declare -p

Notice that in the output, the double dash (no options) has been replaced with -x:

declare -x myvar="33"

To remove the export attribute, use +x instead:

declare +x myvar

After running the above command, myvar will no longer be exported to subshell processes.

Integers, and integer evaluation

Bash lets you declare a variable to have the integer attribute, which guarantees that the variable always holds an integer value. It also permits arithmetic evaluation when assigning a value.

declare -i myvar

Declare that myvar should be treated an integer.

myvar="test"

The string "test" is a non-integer value, so the value 0 (zero) is assigned instead. You can verify this if you echo the value:

echo $myvar

0

Any positive or negative integer value can be assigned, though. (The maximum possible value depends on your computer, but it's huge):

myvar=-33; echo $myvar

-33

If a string containing an arithmetic operation is assigned to an integer variable, the result of the operation is assigned. For example:

myvar="2*11"; echo $myvar

22

The above command assigns myvar the value of 2 times 11.

If the mathematical operation results in a number with a decimal point, the result is rounded down to the next-lowest integer. For instance:

myvar="33/5"; echo $myvar

6

The precise result of 33 divided by 5 (33/5) is 6.6, but bash rounds it down to the integer 6.

If you try to use decimal values as operands, bash returns an error, stating that the decimal point is an unknown operator:

myvar="33.1/5"; echo $myvar

bash: 33.1/5: syntax error: invalid arithmetic operator (error token is ".1/5")

To unset the integer attribute, use the option +i:

declare +i myvar

Now, myvar no longer has the integer attribute. Strings containing mathematical operations are be assigned to myvar literally, rather than evaluated. For example:

myvar="33.1/5"; echo $myvar

33.1/5

Indexed arrays

To declare an indexed array, use -a:

declare -a myvar

If myvar already had an assigned value, this value is indexed as the first element, numbered zero:

echo ${myvar[0]}

33.1/5

You can now assign values to elements of the array myvar using integers as the indices:

myvar[1]="Hello"

myvar[2]="World!"

The elements can be accessed by index number using the following syntax:

echo ${myvar[2]}

World!

If you use a negative integer as the index, bash counts from the last element, rather than the first. To access the last element, use index -1:

echo ${myvar[-1]}

World!

An index of -2 would access the second-to-last array element, etc.:

echo ${myvar[-2]}

Hello

To display all elements in an array, you can use an asterisk ("*") as the index. Individual elements are separated with a space:

echo ${myvar[*]}

33.1/5 Hello World!

declare +a myvar

bash: declare: myvar: cannot destroy array variables in this way

Check if a variable is declared

If you're writing a bash script, and you need to check if a variable is declared, this is the proper way to do it:

if [ -z ${myvar+x} ]; then echo "not set"; else echo "set"; fi

This script performs "Assign Alternate Value" parameter expansion, which tests if myvar has been set, and if its value is null. If myvar is unset, it will echo "not set". Otherwise, it will echo "set". Note that the letter x can be anything you'd like, but is required for the comparison to occur.

Related commands

export — Mark variables and functions to be exported to child processes.