bash-hackers-wiki/original_source/commands/builtin/caller.txt

====== The caller builtin command ======

===== Synopsis =====
<code>caller [FRAMENUMBER]</code>

===== 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.

<code 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
</code>

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

===== 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. <code>{ bash /dev/stdin; } <<<$'f(){ g; }\ng(){ h; }\nh(){ while caller $((n++)); do :; done; }\nf'</code>
  * 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 [[ http://bashdb.sourceforge.net/|Bashdb ]] 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 =====