# The caller builtin command

## Synopsis

    caller [FRAMENUMBER]

## Description

The `caller` builtin command is used to print execution frames of
subroutine calls. Without giving a framenumber, the topmost execution
frame information is printed ("who called me") wile linenumber and
filename.

When an execution frame number is given (0 - topmost), the linenumber,
the subroutine (function) and the filename is printed. When an invalid
execution frame number is given, it exists `FALSE`. This way it can be
used in a loop (see the examples section below).

## Examples

### Simple stack trace

The code below defines a function `die` that is used to exit the
program. It prints a list of execution frames, starting with the topmost
frame (0). The topmost frame is the "caller of the die function", in
this case function "f1".

This way, you can print a "stack trace" for debugging or logging
purposes.

The code is made very simple, just to show the basic purposes.

``` bash
#!/bin/bash

die() {
  local frame=0
  while caller $frame; do
    ((++frame));
  done
  echo "$*"
  exit 1
}

f1() { die "*** an error occured ***"; }
f2() { f1; }
f3() { f2; }

f3
```

**Output**

    12 f1 ./callertest.sh
    13 f2 ./callertest.sh
    14 f3 ./callertest.sh
    16 main ./callertest.sh
    *** an error occured ***

## Notes

-   `caller` produces no output unless used within a script that's run
    from a real file. It isn't particularly useful for interactive use,
    but can be used to create a decent `die` function to track down
    errors in moderately complex scripts.
    `{ bash /dev/stdin; } <<<$'f(){ g; }\ng(){ h; }\nh(){ while caller $((n++)); do :; done; }\nf'`
-   For more sophisticated debugging, Bash extended debugging features
    are available and a number of special parameters that give more
    detail than caller (e.g. BASH_ARG{C,V}). Tools such as
    [Bashdb](http://bashdb.sourceforge.net/) can assist in using some of
    Bash's more advanced debug features.
-   The Bash manpage and help text specifies that the argument to
    `caller` is an "expr" (whatever that means). Only an integer is
    actually allowed, with no special interpretation of an
    "expression" as far as we can tell.

## Portability considerations

-   `caller` is not specified by POSIX(R)
-   the `caller` builtin command appeared in Bash version 3.0

## See also