Bash’s builtin time accepts %E – what’s going on

bashtime

The bash man page lists three and only three format codes recognized by the shell's builtin version of time: %R for the real time, %U for the time spent in userspace, and %S for time spent in system calls. So the following behavior is confusing to say the least:

$ type time
time is a shell keyword
$ TIMEFORMAT="%E %P"
$ time sleep 1
1.002 0.00

Clearly something is being left out of the man page. The builtin time is recognizing %E and %P. However I checked all other uppercase and lowercase letters and none of them are recognized, except l as a modifier:

$ TIMEFORMAT="%lE %lS %lU %lR"
$ time sleep 1
0m1.001s 0m0.000s 0m0.000s 0m1.001s

I'm curious to understand what's going on here – is this really just an omission in the man page, or is there something weird about my bash? Ideally, can anyone point me to some documentation that explains this? I'm using bash 4.2.48(1) on Gentoo amd64 stable, if it matters.

Best Answer

From the section of execute_cmd.c of bash-4.2+dfsg that deals with TIMEFORMAT:

if (*s == 'R' || *s == 'E')
  len = mkfmt (ts, prec, lng, rs, rsf);
else if (*s == 'U')
  len = mkfmt (ts, prec, lng, us, usf);
else if (*s == 'S')
  len = mkfmt (ts, prec, lng, ss, ssf);
else
  {
    internal_error (_("TIMEFORMAT: `%c': invalid format character"), *s);
    free (str);
    return;
  }

So, from the above, it appears that %E means the same as %R: elapsed (real) time.

I have seen something similar in GNU sed. The -r option is documented as enabling sed's extended regular expressions. An undocumented feature is that -E does the same thing. In this case, the purpose is clear: this provides compatibility with the flag that BSD sed uses for extended regex. One possible reason for keeping it undocumented would be that it allows GNU the option to use -E for something else in the future. The reasons for allowing %E in TIMEFORMAT but keeping it undocumented might be similar.

Related Solutions

Bash Shell Builtin – Why Parameters Are Optional

Bash built-ins are inconsistent and poorly documented.

Here's an example:

$ help command
command: command [-pVv] command [arg ...]
    Runs COMMAND with ARGS ignoring shell functions.  If you have a shell
    function called 'ls', and you wish to call the command `ls', you can
    say "command ls".  If the -p option is given, a default value is used
    for PATH that is guaranteed to find all of the standard utilities.  If
    the -V or -v option is given, a string is printed describing COMMAND.
    The -V option produces a more verbose description.
$ command; echo $?
0

Even without command the return code $? -eq 0 and there is no error on std err.

Another one:

$ help disown
disown: disown [-h] [-ar] [jobspec ...]
    By default, removes each JOBSPEC argument from the table of active jobs.
    If the -h option is given, the job is not removed from the table, but is
    marked so that SIGHUP is not sent to the job if the shell receives a
    SIGHUP.  The -a option, when JOBSPEC is not supplied, means to remove all
    jobs from the job table; the -r option means to remove only running jobs.
$ disown; echo $?
-bash: disown: current: no such job
1

All the arguments are optional but it returns $? -eq 1 when there are none.

I've even compiled the newest Bash 4.2 and here are my results:

$ help command
command: command [-pVv] command [arg ...]
    Execute a simple command or display information about commands.

    Runs COMMAND with ARGS suppressing  shell function lookup, or display
    information about the specified COMMANDs.  Can be used to invoke commands
    on disk when a function with the same name exists.

    Options:
      -p    use a default value for PATH that is guaranteed to find all of
        the standard utilities
      -v    print a description of COMMAND similar to the `type' builtin
      -V    print a more verbose description of each COMMAND

    Exit Status:
    Returns exit status of COMMAND, or failure if COMMAND is not found.
$ command; echo $?
0

There's a new section "Exit Status" and command is still an optional argument. Even worse than 3.x. The same for other built-ins.

So, you're right. Bash built-ins are a mess and should be fixed.

Bash – How to match name exactly with Bash’s `help` builtin

It seems by defaul help foo is actually equivalent to help foo*. But if some special globbing characters are used then the ending "*" is not implicitely added.

So, a possibility would be help [r]ead.

The globbing used is the one used by the shell for file matching; afaik there isn't any equivalent of \< nor \>.

Best Answer

Related Solutions

Bash Shell Builtin – Why Parameters Are Optional

Bash – How to match name exactly with Bash’s `help` builtin

Related Question