bash documentation about BASH_LINENO and BASH_SOURCE is vague and inconsistent

[Heiko Scheit]

Binary package hint: bash

The bash manual should be updated with something like the following. For more details see

  https://bugs.launchpad.net/ubuntu/+source/bash/+bug/318678

`BASH_SOURCE'

     An array variable whose members are the source filenames where
     the corresponding elements in the `FUNCNAME' array variable are
     defined. For instance the function `${FUNCNAME[$i]}' is defined
     in the file `${BASH_SOURCE[$i]}' (and was called from file
     `${BASH_SOURCE[$i+1]}'. See `FUNCNAME'.

`BASH_LINENO'

     An array variable whose members are the line numbers in source
     files where the corresponding members of FUNCNAME were called.
     For instance the function `${FUNCNAME[$i]}' was called at line
     number `${BASH_LINENO[$i]}' (in the file `${BASH_SOURCE[$i+1]}').
     Use `LINENO' to obtain the current line number. See `FUNCNAME'.

`FUNCNAME'

     An array variable containing the names of all shell functions
     currently in the execution call stack. The element with index 0
     is the name of any currently-executing shell function. The
     bottom-most element is `"main"'. This variable exists only when a
     shell function is executing. Assignments to `FUNCNAME' have no
     effect and return an error status. If `FUNCNAME' is unset, it
     loses its special properties, even if it is subsequently reset.

     This variable is most useful together with `BASH_SOURCE' and
     `BASH_LINENO'. For instance `${FUNCNAME[0]}' is the name of the
     currently running function, it was called in file
     `${BASH_SOURCE[1]}' at line number `${BASH_LINENO[0]}'. To print
     a back trace of the call stack to stderr use the following
     function

     BT () {
     i=1 # leave out BT from the call stack; set to 0 to include BT
     until test "${FUNCNAME[$i]}" = "main" -o "${FUNCNAME[$i]}"
     do
        echo "${FUNCNAME[$i]} called from ${BASH_SOURCE[$i+1]}:${BASH_LINENO[$i]}" >&2
        let i++
     done
     }

[Heiko Scheit (h-scheit)]

Why is this still marked as 'new'? It is a simple clarification of the bash info-pages.

[Phil (philip-olson-m)]

The documentation should also note that these 3 arrays along with the builtin 'caller' do not work properly if called from a function exported from the interactive shell

++file: .bashrc

myGlobal () {
  for i in $(seq 0 ${#FUNCNAME[@]}); do
    echo "function: ${FUNCNAME[$i]}"
    echo "source: ${BASH_SOURCE[$i]}"
    echo "lineno: ${BASH_LINENO[$i]}"
  done
}
export -f import

++file: ~/delme

f1 () {
  myGlobal
}

f2 () {
  f1
}

f2

Personally I had an issue getting a call-stack while attempting to export a function that would dynamically "import" (source) files in depending on if they were already defined (c-like). The above was the root cause.

[Phil (philip-olson-m)]

And that's what I get for copy/pasting.

export -f import

is supposed to be

export -f myGlobal

I find it odd I can't edit my comment above.