- Article pages now have a discussion option at the bottom (moderated/captcha, but no registration needed)

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 kind of "stack trace" for debugging or logging purposes.

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

#!/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

15 f1 ./callertest.sh
19 f2 ./callertest.sh
23 f3 ./callertest.sh
26 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 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

Discussion

Enter your comment. Wiki syntax is allowed:
 
commands/builtin/caller.txt · Last modified: 2012/01/15 10:09 by ormaaj
GNU Free Documentation License 1.3
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0