# info > BASH-BUILTINS

---
type: CommandReference
command: bash-builtins
mode: man
section: 7
source: man-pages
---

## Quick Reference

- `. file [args]` — source file in current shell
- `alias name=value` — define alias
- `bg [jobspec]` — resume job in background
- `cd [-L|-P] [dir]` — change directory (HOME if no dir)
- `echo [-neE] [arg...]` — output args, escapes supported with -e
- `eval [arg...]` — concatenate and execute as command
- `exec [-cl] [-a name] [cmd [args]]` — replace shell or redirect
- `exit [n]` — exit shell with status n
- `export [-fn] [name[=word]]` — mark variables for export
- `fc [-l] [-e editor] [first] [last]` — list/edit/re-execute history
- `fg [jobspec]` — resume job in foreground
- `getopts optstring name [arg...]` — parse positional parameters
- `hash [-lr] [-p filename] [-dt] [name]` — remember/cache command paths
- `history [-c] [-d offset] [n]` — display or manipulate history
- `jobs [-lnprs] [jobspec...]` — list active jobs
- `kill [-s sigspec | -n signum] [pid | jobspec]` — send signal
- `let arg...` — arithmetic evaluation
- `local [option] [name[=value]]` — declare local variable in function
- `popd [-n] [+n] [-n]` — remove directory from stack
- `printf [-v var] format [arguments]` — formatted output (supports %b, %q, %(datefmt)T)
- `pushd [-n] [+n | dir]` — add directory to stack
- `pwd [-LP]` — print current working directory
- `read [-ers] [-a aname] [-d delim] [-i text] [-n nchars] [-p prompt] [-t timeout] [-u fd] [name...]` — read line, split into words
- `readonly [-aAf] [-p] [name[=word]]` — mark variables as readonly
- `return [n]` — exit function with status n
- `set [--abefhkmnptuvxBCEHPT] [-o option-name] [arg...]` — set/unset shell options, assign positional parameters
- `shift [n]` — shift positional parameters
- `shopt [-pqsu] [-o] [optname...]` — toggle shell options
- `source` — same as `.`
- `test expr` or `[ expr ]` — evaluate conditional expression
- `times` — print accumulated user/system times
- `trap [-lp] [[arg] sigspec...]` — set signal handlers
- `type [-aftpP] name...` — describe command type
- `ulimit [-HS] [-abcde...] [limit]` — set/display resource limits
- `umask [-p] [-S] [mode]` — set file creation mask
- `unalias [-a] [name...]` — remove alias
- `unset [-fv] [-n] [name...]` — remove variable or function
- `wait [-fn] [-p varname] [id...]` — wait for child processes

## Name

bash-builtins — bash built-in commands, see [bash(1)](http://localhost/phpMan.php/man/bash/1/markdown)

## Synopsis

bash defines the following built-in commands: `:`, `.`, `[`, `alias`, `bg`, `bind`, `break`, `builtin`, `case`, `cd`, `command`, `compgen`, `complete`, `continue`, `declare`, `dirs`, `disown`, `echo`, `enable`, `eval`, `exec`, `exit`, `export`, `fc`, `fg`, `getopts`, `hash`, `help`, `history`, `if`, `jobs`, `kill`, `let`, `local`, `logout`, `popd`, `printf`, `pushd`, `pwd`, `read`, `readonly`, `return`, `set`, `shift`, `shopt`, `source`, `suspend`, `test`, `times`, `trap`, `type`, `typeset`, `ulimit`, `umask`, `unalias`, `unset`, `until`, `wait`, `while`.

## Builtin Commands

Unless noted, all builtins accept `--` to signify end of options. The `:`, `true`, `false`, and `test`/`[` builtins do not accept options. `exit`, `logout`, `return`, `break`, `continue`, `let`, and `shift` accept `-` arguments without `--`.

- `: [arguments]` — no effect; expands arguments and redirections; returns 0.

- `. filename [arguments]` / `source filename [arguments]` — read and execute commands from filename in current shell. If filename has no slash, PATH is searched. `-T` option affects DEBUG trap inheritance. Returns exit status of last command from filename (0 if none), false if file not found/readable.

- `alias [-p] [name[=value] ...]` — without args or with `-p`, prints aliases in `alias name=value` form. With arguments, defines alias for each name. If value ends with space, next word checked for alias substitution. Returns true unless a name given has no alias.

- `bg [jobspec ...]` — resume each suspended jobspec in background. If no jobspec, uses current job. Returns 0 unless job control disabled or invalid jobspec.

- `bind [-m keymap] [-lpsvPSVX] [-q function] [-u function] [-r keyseq] [-f filename] [-x keyseq:shell-command] keyseq:function-name` — display or modify readline key bindings. Options: `-m keymap` (emacs, vi, etc.), `-l` list functions, `-p` display in reusable format, `-P` list current, `-s` macros, `-v` variables, `-f filename` read bindings, `-q function` query keys, `-u function` unbind, `-r keyseq` remove binding, `-x keyseq:shell-command` bind command, `-X` list shell commands. Returns 0 unless error.

- `break [n]` — exit from for/while/until/select loop. n levels (n≥1). Returns 0 unless n<1.

- `builtin shell-builtin [arguments]` — execute specified shell builtin, bypassing function override. Returns false if not a builtin.

- `caller [expr]` — display call stack context. Without expr: line number and source file. With expr: line number, subroutine name, source file at that frame. Returns 0 unless not in subroutine call.

- `cd [-L|[-P [-e]] [-@]] [dir]` — change directory to dir (default HOME). Uses CDPATH. `-P` resolves symlinks, `-L` follows symlinks after processing `..`. `-e` with `-P` fails if new pwd can't be determined. `-@` presents extended attributes as directory. `-` goes to $OLDPWD. Returns true if successful.

- `command [-pVv] command [arg ...]` — run command suppressing shell function lookup. `-p` uses default PATH. `-V`/`-v` print description of command. Exit status: 0 if found (with -V/-v), 1 if not found, 127 if neither option and error.

- `compgen [option] [word]` — generate completion matches for word using options from `complete` (except -p, -r). Writes matches to stdout. Returns true unless invalid option or no matches.

- `complete [-abcdefgjksuv] [-o comp-option] [-DEI] [-A action] [-G globpat] [-W wordlist] [-F function] [-C command] [-X filterpat] [-P prefix] [-S suffix] name [name ...]` — specify how arguments to each name should be completed. `-p` print specs, `-r` remove, `-D` default, `-E` empty, `-I` initial. `-o` comp-option: bashdefault, default, dirnames, filenames, noquote, nosort, nospace, plusdirs. `-A` action: alias, arrayvar, binding, builtin, command, directory, disabled, enabled, export, file, function, group, helptopic, hostname, job, keyword, running, service, setopt, shopt, signal, stopped, user, variable. `-C` command executes in subshell, output as completions. `-F` function executes in current shell with $1, $2, $3; completions from COMPREPLY. `-G` glob pattern. `-P` prefix, `-S` suffix. `-W` wordlist split by IFS. `-X` filter pattern. Returns true unless invalid option or error.

- `compopt [-o option] [-DEI] [+o option] [name]` — modify completion options for name or current completion. Options same as `complete`. Returns true unless invalid option or no specification.

- `continue [n]` — resume next iteration of enclosing loop. n≥1; if n > number of loops, resume top-level. Returns 0 unless n<1.

- `declare [-aAfFgiIlnrtux] [-p] [name[=value] ...]` / `typeset` — declare variables and attributes. Without names, display values. `-p` display attributes and values. `-f` restrict to functions, `-F` function names only. `-g` global scope in function. `-I` inherit attributes from existing variable. Options: `-a` indexed array, `-A` associative array, `-i` integer, `-l` lowercase, `-n` nameref, `-r` readonly, `-t` trace, `-u` uppercase, `-x` export. Using `+` turns off attribute (except +a, +A, +r). In function, makes local unless -g. Returns 0 unless error.

- `dirs [-clpv] [+n] [-n]` — display directory stack. `-c` clear, `-l` full paths, `-p` one per line, `-v` with indexes. `+n` nth from left, `-n` nth from right. Returns 0 unless invalid option or n out of range.

- `disown [-ar] [-h] [jobspec ... | pid ...]` — remove jobs from active table. Without options, remove current job. `-h` mark to not receive SIGHUP. `-a` all jobs, `-r` running only. Returns 0 unless invalid jobspec.

- `echo [-neE] [arg ...]` — output args separated by spaces, newline at end. `-n` no newline, `-e` enable escape sequences, `-E` disable. Escape sequences: `\a` alert, `\b` backspace, `\c` suppress further output, `\e`/`\E` escape, `\f` form feed, `\n` newline, `\r` carriage return, `\t` tab, `\v` vertical tab, `\\` backslash, `\0nnn` octal, `\xHH` hex, `\uHHHH` Unicode, `\UHHHHHHHH` Unicode. Returns 0 unless write error.

- `enable [-a] [-dnps] [-f filename] [name ...]` — enable/disable builtins. `-n` disable, `-f` load from shared object, `-d` delete loaded builtin, `-p` print list, `-a` all with status, `-s` POSIX special builtins. Returns 0 unless name not a builtin or load error.

- `eval [arg ...]` — concatenate and execute as command. Returns exit status of command. If no args, returns 0.

- `exec [-cl] [-a name] [command [arguments]]` — replace shell with command. `-l` dash at start of arg0, `-c` empty environment, `-a` name as arg0. If command fails, non-interactive shell exits unless `execfail` set. Without command, redirections apply in current shell, return 0.

- `exit [n]` — exit shell with status n (default: last command). EXIT trap executed.

- `export [-fn] [name[=word]] ...` / `export -p` — mark names for export. `-f` for functions, `-n` remove export property. Returns 0 unless error.

- `fc [-e ename] [-lnr] [first] [last]` / `fc -s [pat=rep] [cmd]` — list/edit/re-execute history commands. `-l` list, `-n` suppress numbers, `-r` reverse order. first/last: string or number (negative offset). `-e ename` editor. `-s` substitute pat with rep. Return value: 0 unless error or invalid history line.

- `fg [jobspec]` — resume jobspec in foreground as current job. Returns status of command, or failure if job control disabled or invalid.

- `getopts optstring name [arg ...]` — parse positional parameters. optstring: option characters, colon after requires argument. `:` and `?` not allowed as options. Places next option in name, next index in OPTIND. OPTARG holds argument. If first char of optstring is `:`, silent error reporting. Invalid option: `?` in name, option char in OPTARG (if silent). Missing argument: `?` (non-silent) or `:` (silent) in name, OPTARG set to option char. Returns true if option found, false at end of options or error.

- `hash [-lr] [-p filename] [-dt] [name]` — remember/locate command paths. `-p filename` set full path, `-r` forget all, `-d` forget each name, `-t` print full path, `-l` reusable format. Without args, print remembered commands. Returns true unless name not found.

- `help [-dms] [pattern]` — display help for builtins. `-d` short description, `-m` manpage-like, `-s` short synopsis. Returns 0 unless no match.

- `history [n]` / `history -c` / `history -d offset` / `history -d start-end` / `history -anrw [filename]` / `history -p arg ...` / `history -s arg ...` — display/manipulate history. `-c` clear, `-d offset` delete entry, `-d start-end` delete range, `-a` append new lines to file, `-n` read unread lines, `-r` read file, `-w` write list to file, `-p` perform history substitution on args, `-s` store args as single entry. If HISTTIMEFORMAT set, timestamp displayed. Returns 0 unless error.

- `jobs [-lnprs] [jobspec ...]` / `jobs -x command [args ...]` — list jobs. `-l` include PIDs, `-n` only changed, `-p` only process group leader, `-r` running, `-s` stopped. `-x` replaces jobspec with process group ID in command. Returns 0 unless invalid option/jobspec.

- `kill [-s sigspec | -n signum | -sigspec] [pid | jobspec] ...` / `kill -l|-L [sigspec | exit_status]` — send signal. sigspec: case-insensitive name (with/without SIG) or number. Default SIGTERM. `-l` list names, `-L` same. With argument, list corresponding signal. Returns true if at least one signal sent.

- `let arg [arg ...]` — evaluate arithmetic expression. Returns 1 if last arg evaluates to 0, else 0.

- `local [option] [name[=value] ... | -]` — create local variable in function. Options same as `declare`. If `-` is name, shell options made local. With no operands, list local variables. Error if used outside function. Returns 0 unless error.

- `logout` — exit a login shell.

- `mapfile [-d delim] [-n count] [-O origin] [-s count] [-t] [-u fd] [-C callback] [-c quantum] [array]` / `readarray` — read lines from stdin into array. Options: `-d` delimiter (default newline), `-n` max lines, `-O` start index, `-s` skip lines, `-t` strip trailing delimiter, `-u` file descriptor, `-C` callback, `-c` quantum (default 5000). Default array MAPFILE. Returns success unless error.

- `popd [-n] [+n] [-n]` — remove directory from stack. `-n` no cd. `+n` nth from left, `-n` nth from right. On success, `dirs` is performed. Returns 0 unless invalid option or stack empty or change fails.

- `printf [-v var] format [arguments]` — formatted output. `-v` assign to var. Format supports `%b` (expand escapes), `%q` (reusable shell input), `%(datefmt)T` (date-time from epoch seconds; -1=now, -2=shell invocation). Returns 0 on success.

- `pushd [-n] [+n] [-n]` / `pushd [-n] [dir]` — add to directory stack. Without args, exchange top two. `-n` no cd. `+n` rotate to nth from left, `-n` from right. `dir` add and cd. On success, `dirs` performed. Returns 0 unless failure.

- `pwd [-LP]` — print absolute pathname of current working directory. `-P` no symlinks, `-L` allow symlinks. Returns 0 unless error.

- `read [-ers] [-a aname] [-d delim] [-i text] [-n nchars] [-N nchars] [-p prompt] [-t timeout] [-u fd] [name ...]` — read a line, split into words. Options: `-a aname` array assignment, `-d delim` delimiter (empty = NUL), `-e` use readline, `-i text` initial buffer, `-n nchars` return after n chars (honors delimiter), `-N nchars` read exactly n chars (no splitting), `-p prompt` display on stderr, `-r` raw (backslash not escape), `-s` silent, `-t timeout` seconds (decimal, 0 returns immediately), `-u fd`. If no names, result in REPLY. Exit status: 0 unless EOF, timeout (>128), or error.

- `readonly [-aAf] [-p] [name[=word] ...]` — mark names readonly. `-f` functions, `-a` indexed arrays, `-A` associative arrays. Without names, print list. Returns 0 unless error.

- `return [n]` — exit function with status n (default: last command). If used outside function but in sourced script, stop script. RETURN trap executed. Returns non-zero if non-numeric argument or used outside function/script.

- `set [--abefhkmnptuvxBCEHPT] [-o option-name] [arg ...]` — set/unset shell attributes and positional parameters. Without options, display all variables. Options: `-a` export all, `-b` notify on background job, `-e` exit on error, `-f` disable pathname expansion, `-h` hash commands, `-k` assignment arguments in environment, `-m` monitor mode, `-n` read-only, `-o option-name` (allexport, braceexpand, emacs, errexit, errtrace, functrace, hashall, histexpand, history, ignoreeof, keyword, monitor, noclobber, noexec, noglob, nolog, notify, nounset, onecmd, physical, pipefail, posix, privileged, verbose, vi, xtrace), `-p` privileged mode, `-t` exit after one command, `-u` treat unset as error, `-v` print lines as read, `-x` print commands after expansion, `-B` brace expansion, `-C` no overwrite, `-E` ERR trap inheritance, `-H` history expansion, `-P` physical directory, `-T` DEBUG/RETURN trap inheritance. `--` unsets positional params. `-` ends options, turns off -x and -v. Returns true unless invalid option.

- `shift [n]` — rename positional parameters from n+1. n must be non-negative ≤ $#. Default 1. Returns >0 if n > $# or n < 0; otherwise 0.

- `shopt [-pqsu] [-o] [optname ...]` — toggle shell options. Without options, display all. `-s` enable, `-u` disable, `-q` quiet (return status), `-o` restrict to set -o options. List of shopt options: assoc_expand_once, autocd, cdable_vars, cdspell, checkhash, checkjobs, checkwinsize, cmdhist, compat31–compat44, complete_fullquote, direxpand, dirspell, dotglob, execfail, expand_aliases, extdebug, extglob, extquote, failglob, force_fignore, globasciiranges, globstar, gnu_errfmt, histappend, histreedit, histverify, hostcomplete, huponexit, inherit_errexit, interactive_comments, lastpipe, lithist, localvar_inherit, localvar_unset, login_shell, mailwarn, no_empty_cmd_completion, nocaseglob, nocasematch, nullglob, progcomp, progcomp_alias, promptvars, restricted_shell, shift_verbose, sourcepath, xpg_echo. Returns 0 if all enabled (for -q) or success.

- `suspend [-f]` — suspend shell until SIGCONT. `-f` force for login shell. Returns 0 unless login shell and no -f, or job control disabled.

- `test expr` / `[ expr ]` — evaluate conditional expression. Returns 0 (true) or 1 (false). Uses primaries from CONDITIONAL EXPRESSIONS in bash(1). Operators: `! expr`, `( expr )`, `expr1 -a expr2`, `expr1 -o expr2`. Evaluation rules based on number of arguments. 0: false. 1: true if non-null. 2: if `!`, true if second null; if unary operator, test; else false. 3: binary operator, or `!` + two-arg, or `( expr )`. 4+: parsed with precedence. `<` and `>` use ASCII ordering.

- `times` — print accumulated user and system times for shell and children. Returns 0.

- `trap [-lp] [[arg] sigspec ...]` — set signal handler. If arg absent or `-`, reset to original. If arg is null string, ignore signal. `-p` display current traps. `-l` list signal names. sigspec can be EXIT (0), DEBUG, RETURN, ERR, or signal name/number. Signals ignored on entry cannot be trapped. Returns false if invalid sigspec.

- `type [-aftpP] name [name ...]` — indicate how name would be interpreted. `-t` prints alias, keyword, function, builtin, file. `-p` returns disk file path. `-P` force PATH search. `-a` print all matches (aliases, functions). `-f` suppress function lookup. Returns true if all found.

- `ulimit [-HS] -a` / `ulimit [-HS] [-bcdefiklmnpqrstuvxPRT [limit]]` — get/set resource limits. `-H` hard limit, `-S` soft limit. Without option, both set. limit: number, hard, soft, unlimited. `-a` report all. Options: `-b` socket buffer, `-c` core size, `-d` data segment, `-e` nice, `-f` file size, `-i` pending signals, `-k` kqueues, `-l` locked memory, `-m` resident set, `-n` open files, `-p` pipe size (512-byte blocks), `-q` POSIX message queues, `-r` real-time priority, `-s` stack, `-t` CPU seconds, `-u` processes, `-v` virtual memory, `-x` file locks, `-P` pseudoterminals, `-R` real-time blocking time (microseconds), `-T` threads. Default -f. Values in 1024-byte increments except -t, -R, -p, -P, -T, -b, -k, -n, -u (unscaled). Returns 0 unless error.

- `umask [-p] [-S] [mode]` — set file creation mask. mode: octal number or symbolic (like chmod). Without mode, print current mask. `-S` symbolic, `-p` reusable format. Returns 0 if mode changed or no mode.

- `unalias [-a] [name ...]` — remove aliases. `-a` remove all. Returns true unless name not defined.

- `unset [-fv] [-n] [name ...]` — remove variable or function. `-v` variable, `-f` function, `-n` unset nameref itself. Read-only variables cannot be unset. Special variables lose special properties if unset. Returns true unless name is readonly.

- `wait [-fn] [-p varname] [id ...]` — wait for child processes. id: PID or jobspec. Without id, wait for all background jobs and last process substitution. `-n` wait for any single job, `-p` assign job identifier to varname, `-f` force wait for termination (with job control). Returns 127 if no such child or process, else exit status of last waited process.

## Shell Compatibility Mode

Compatibility levels set via `shopt compatNN` (for bash <5.0) or `BASH_COMPAT` variable. Each level is mutually exclusive. Below are key behavior changes per level:

- **compat31**: quoting rhs of `[[ ... =~ ]]` has no special effect.
- **compat32**: interrupting command list like `a ; b ; c` causes next command to execute (in later versions, interrupt aborts entire list).
- **compat40**: `[[` `<` and `>` use ASCII ordering (not locale). Bash-4.1+ use locale.
- **compat41**: in posix mode, `time` with options still recognized as reserved word; parser requires even number of single quotes in double-quoted parameter expansion.
- **compat42**: replacement string in double-quoted pattern substitution does not undergo quote removal; in posix mode, single quotes are special in word portion of double-quoted parameter expansion.
- **compat43**: no warning on quoted compound assignment to `declare`; word expansion errors non-fatal; executing shell function does not reset loop state (break/continue affect outer loops).
- **compat44**: BASH_ARGV/BASH_ARGC set even without extended debug; subshell inherits loops from parent; variable assignments preceding builtins like `export` affect calling environment even outside posix mode.
- **compat50**: `$RANDOM` generation reverts to bash-5.0 method; `hash -l` suppresses informational message when table empty.

## See Also

- [bash(1)](http://localhost/phpMan.php/man/bash/1/markdown)
- [sh(1)](http://localhost/phpMan.php/man/sh/1/markdown)