Shell positional arguments are a numbered list

Mon, 29 Nov 2027 00:00:00 +0000

A shell script receives an ordered argument list, not a single command-line string that it must split again. Positional parameters expose that list as $1, $2, and subsequent entries; $# reports its size. A small fixed interface can use these positions directly. Optional settings and flags benefit from explicit parsing, but either design still needs to define the permitted count, empty values, and failure behavior.

Preserve the list before interpreting it

The script name in $0 is separate from the positional arguments and does not contribute to $#. With bash -c, the first argument after the command string becomes $0, which can surprise wrappers expecting it to become $1. Positions above nine require braces: ${10} means the tenth argument, whereas $10 means the first argument followed by a literal zero.

"$@" preserves one word per supplied argument, including empty arguments and values containing spaces. An unquoted expansion can split values and expand wildcard characters, while "$*" joins the list into one string. Use the quoted list when forwarding or iterating. set -- replaces the current positional list, and shift removes leading entries; neither operation changes the caller’s original list outside the relevant script or function scope.

An empty argument still occupies a position. Checking $# distinguishes an absent argument from one explicitly passed as ''. An expression such as ${1:?message} rejects both missing and empty values, which is appropriate only when the interface requires a nonempty value. Validate the count before reading required positions, then apply any separate rules about allowed contents.

Let getopts report syntax, then validate meaning

The portable getopts interface handles short options. An option character followed by a colon in the option specification takes a value; it does not automatically provide support for long names such as --user. A leading colon selects quiet error reporting: unknown options produce ?, and missing option values produce :, with the offending option available in OPTARG. The script must handle those cases explicitly.

OPTIND tracks parsing progress. Reset it to one before parsing a new argument list in the same shell, and after parsing use shift "$((OPTIND - 1))" to expose the remaining operands. -- ends option processing so a leading-hyphen filename can be an operand. A non-option also ends the ordinary option scan; do not assume options placed after operands will be rearranged automatically.

Parsing an option value does not establish that it is meaningful. An explicitly supplied empty string can satisfy the parser’s requirement for a value while violating the application’s requirement for a name. Likewise, defaults should apply only to omitted optional settings, not hide malformed input. Keep diagnostics on standard error and return a documented nonzero status before performing the requested work.

When it breaks

A common parser accepts the happy path but silently drops surplus operands. Another forgets to reset OPTIND, so a function’s first invocation works while later invocations skip options. Unquoted forwarding can produce the same outward symptom by changing the argument count before the parser sees it. Test the received list and the parsing state separately rather than adding guessed shifts until one invocation works.

The example below deliberately defines a narrow contract: optional -n NAME, optional -v, and exactly one input operand. Its name must be nonempty. The function uses Bash’s local declaration, so the complete example is Bash-specific even though the option parser itself is portable. A script targeting another shell should use that shell’s supported scoping rules instead of assuming local is standardized.

Check it quickly

Run the complete block in Bash. The first part demonstrates the tenth-position boundary and preservation of empty arguments. The parser then exercises valid input and four distinct invalid forms. All operations are local prints; no files or external commands are invoked by the demonstration function.

BASH_ENV= bash --noprofile --norc <<'BASH'
set -- one 2 3 4 5 6 7 8 9 ten
printf 'without-braces=<%s> tenth=<%s>\n' "$10" "${10}"
set -- '' 'two words'
printf 'count=%s\n' "$#"
for demo_arg in "$@"; do printf 'argument=<%s>\n' "$demo_arg"; done
demo_cli() {
 local OPTIND=1 demo_option demo_name=guest demo_verbose=no
 while getopts ':n:v' demo_option; do
 case "$demo_option" in
 n) demo_name=$OPTARG ;;
 v) demo_verbose=yes ;;
 :) printf 'missing value for -%s\n' "$OPTARG" >&2; return 2 ;;
 \?) printf 'unknown option -%s\n' "$OPTARG" >&2; return 2 ;;
 esac
 done
 shift "$((OPTIND - 1))"
 if [ "$#" -ne 1 ] || [ -z "$demo_name" ]; then
 printf 'need a nonempty name and exactly one input\n' >&2
 return 2
 fi
 printf 'name=<%s> verbose=%s input=<%s>\n' "$demo_name" "$demo_verbose" "$1"
}
demo_cli -v -n 'Jane Doe' -- '-input file'
if demo_cli -n 2>/dev/null; then exit 1; else printf 'missing=%s\n' "$?"; fi
if demo_cli -x 2>/dev/null; then exit 1; else printf 'unknown=%s\n' "$?"; fi
if demo_cli -n '' input 2>/dev/null; then exit 1; else printf 'empty=%s\n' "$?"; fi
if demo_cli one two 2>/dev/null; then exit 1; else printf 'extra=%s\n' "$?"; fi
demo_cli second
BASH

Expect one0 versus ten, followed by a count of two and two separately printed arguments. The valid invocation keeps Jane Doe and -input file intact. Missing values, unknown options, an empty name, and extra operands each return status two. The final call restores the defaults and accepts second, proving that repeated parsing starts with fresh state.

These observations verify the interface’s boundaries, not merely that a usage message exists. When extending a real command, add checks for the new option’s meaning and preserve the established treatment of quoting, empty values, and the end-of-options marker.

Sources