11.3 Executing a program

This module provides an API to execute a program under the privileges of the current user or under a more or less privileged user; sudo is used run a program as a different user: refer to its documentation for the required configuration; whoami is used to determine to which user the process belongs.

At package configuration time we can specify which sudo and whoami executables to use through the following options for the configuration script configure:

--with-sudo=/path/to/sudo

Allows the selection of the pathname to the executable sudo; this pathname is hard–coded in the library. It defaults to: /usr/bin/sudo.

--with-whoami=/path/to/whoami

Allows the selection of the pathname to the executable whoami; this pathname is hard–coded in the library. It defaults to: /usr/bin/whoami.

The functions described here must be used in the following way:

• To execute a program under the current user privileges:

  mbfl_program_exec ls /bin
  

• To execute a program under a more or less privileged user:

  # At the beginning of the script:
  mbfl_program_enable_sudo
  
  # When executing a program:
  mbfl_program_declare_sudo_user root
  mbfl_program_exec ls /root
  

Every time we execute a program with sudo: we have to select the user under which to execute it; if we do not do it: the internally registered user defaults to nosudo, which tells the function not to use sudo. So the following script works as commented:

mbfl_program_enable_sudo

# This is executed with the privileges of the user that
# launched the script.
mbfl_program_exec ls /bin

mbfl_program_declare_sudo_user root
# This is executed with root privileges.
mbfl_program_exec ls /root

# This is executed with the privileges of the user that
# launched the script.
mbfl_program_exec ls /bin

Function: mbfl_program_exec program

Function: mbfl_program_exec program arg ...

Evaluate a command line. program identifies an executable file: it can be the program name, or a relative or absolute pathname. The optional arg values are command line arguments that are handed to the program unchanged.

If usage of sudo was requested, the command is executed with it; then the sudo request is reset. This means that this function “consumes” a sudo request.

See below for the redirection of the standard error channel.

If the function mbfl_option_test() returns true: instead of evaluation, the command line is sent to stderr.

If the function mbfl_option_show_program() returns true: the command line is sent to stderr, then it is executed.

Function: mbfl_program_execbg inchan ouchan program

Function: mbfl_program_execbg inchan ouchan program arg ...

Does all the same things of mbfl_program_exec(), running the given command line as:

program arg ... <&inchan >&ouchan &

additionally: set the global variable mbfl_program_BGPID to the process ID of the background process; that is: mbfl_program_BGPID is the value of $! right after the process execution.

Using this function is different from calling:

mbfl_program_exec ls <&inchan >&ouchan &

because doing so puts in the background the function call (in a subshell) and then runs the program.

Notice that we must always use numeric file descriptors as inchan and ouchan arguments. Also we can always use the default file descriptors, for example:

mbfl_program_execbg 0 1 /bin/ls

The readable aliases /dev/stdin, /dev/stdout, /dev/fd/0, /dev/fd/1 are not usable as inchan and ouchan arguments (remember that the aliases are not available, for example, when the script is run from a cron job).

Function: mbfl_program_replace program

Function: mbfl_program_replace program [opt …]

Like mbfl_program_exec(), but execute the program through the Bash command exec, so replacing the current process without creating a new one.

Variable: mbfl_program_BGPID

Used by mbfl_program_execbg() to store the process id of the program executed in background.

Function: mbfl_program_enable_sudo

Declare the intention to use sudo and other commands required to use it. The declared programs are: sudo, whoami.

This function does not use mbfl_declare_program().

Function: mbfl_program_declare_sudo_user user

Register user as the user under which to execute the next program through sudo; the user will be selected using the -u option of sudo. The value nosudo means: do not use sudo.

The string user must satisfy the function mbfl_string_is_username(), else the function will print an error message to stderr and exit with exit_because_invalid_sudo_username().

When the time comes: if the selected user name equals the value printed by whoami, sudo is not used.

Function: exit_because_invalid_sudo_username

Function: return_because_invalid_sudo_username

Exit or return with code 90.

Function: mbfl_program_reset_sudo_user

Reset the previously requested sudo user to a value that will cause sudo not to be used in the next program invocation. This is useful to abort a user request.

Function: mbfl_program_sudo_user

Print the current sudo user.

Function: mbfl_program_requested_sudo

Return true if the usage of sudo has been requested for the next command execution.

Function: mbfl_program_declare_sudo_options [opt …]

Select additional command line options to use on the next invocation of sudo. These values are consumed by the first use of mbfl_program_exec().

Function: mbfl_program_reset_sudo_options

Clean the options previously set by mbfl_program_declare_sudo_options().

Executing a subshell

Function: mbfl_program_bash [opt …]

Execute bash with the arg arguments appended. The bash pathname is registered in the library at start up, from the built in variable BASH.

Function: mbfl_program_bash_command command

Execute command in a bash subprocess, using the -c switch. The bash pathname is registered in the library at start up, from the built in variable BASH.

Redirecting the standard error channel

There are programs that output useful informations on their stderr channel (example: the at command).

Function: mbfl_program_redirect_stderr_to_stdout

Just for the next invocation to mbfl_program_exec() redirect stderr to stdout, that is: use the 2>&1 redirection for the executed program.

This is useful because redirecting the output of mbfl_program_exec():

echo ls | \
    mbfl_program_exec at 'now +25 minutes' 2>&1 | \
    while read

redirects also the “show program” output (getopts options for the --show-program option explanation and see the above description of mbfl_program_exec()). Instead By using:

mbfl_program_redirect_stderr_to_stdout
echo ls | \
    mbfl_program_exec at 'now +25 minutes' | \
    while read

the “show program” output goes to stderr and the stderr output of the at command is, internally, redirected to the stdout of mbfl_program_exec().

This document describes version 3.0.0-devel.0 of Marcos Bash Functions Library.