\

Plugin Run supplies a way to start & kill executables. These actions may be triggered by button press (Keypad, plugin Control) or timer events.\

It doesn't collect any output of these processes. Instead of this it supplies the following features:

- kill processes after a given time - evaluates callback expression after process died - exit code of process - sends SIGTERM & SIGKILL to started processes if lcd4linux terminates

\

This plugin needs no configuration.

\

All functions return -1 on error (e.g. plugin not active, wrong config, wrong indexes, name not found). \

\

run::run(duration, program, [arg1, [arg2, …)

This Function starts a program (forc,exec) with the optional arguments arg1, arg2, … and returns a non-negative id (!= pid most times) on success.\

This id is unique within the whole lifetime of the lcd4linux process and can be used to reference the started process.\

If -1 is returned, the program could not be started for any reasons (logged to syslog).

The started process is set to process group leader (pgid = pid) - see run::kill(…).

If duration was set to 0, the started process may run for unlimited time. Otherwise the process get signal SIGTERM after the number of seconds given by duration. If this doesn't terminate the process, SIGKILL will be sent after the next second.

Example (e.g. in an expression of Widget Timer or in an action within the plugin Layout.):

varId = run::run(0,'beep','-f',varHertz,'-l', varSeconds * 1000)

run::call(callback, duration, program, [arg1, [arg2, …)

This function will do the same as run::run(…) with one addition: If the started process has finished the expression given by callback will be evaluated. This can be used to modify variables, activate a notification LED or switch a layout or to do something else.

The callback will be evaluated after the process died but before its removed from the list with all its values (id, pid, command, exit value). So this is the only place where a call of run::exitval(…) should be used.

Since the plugin is looking for inactive processes in intervals of 1 second, there may be a delay up to 1 second between the time when the process get inactive (finishes) and the time when the callback expression is evaluated.

The callback expression has to be enclosed in single quotes. If the expression includes single quotes itself, these have to be escaped.

Example:

varId = run::call('layout::layout(\'Layout_ready\')',0,'/home/test/some_script.sh')

run::kill(id)

This will send send the signal SIGTERM to the process group of the process referenced by id within this plugin. (This process was set to group leader - see run::run(…).)

One second later SIGKILL follows, if the process is still alive.

returns 0 if process was found and active, else -1

run::pid(id)

returns the process id (PID) if process was found and active, else -1

run::cmd( id* )

returns a string with the command of the process, if it was found and active, else -1

run::exitval( id* )

returns the exit value of the process. If the id doesn't match a known process or if the process is still alive or if the process died without exit value (e.g. by SIGKILL), it returns -1.

This function should only be used within the callback expression of run::call().

\

Download: sample_layout_3.conf

This example is written for a Curses driver. So no real LCD is needed for testing. It also allows the use of the keyboard (arrow keys: left, right, up). If the real display has no keypad the Control plugin may be used.

The example is a little timer. After setting the duration and starting the timer by arrow keys the program sleep will be started and some process infos will be shown. If the process has finished or has been terminated its exit value will be shown and a short notification sound will be made if the program beep is installed.

Use option -f to activate these configuration files.

This example also makes use of plugin Layout. The layout index is displayed in the upper left corner of all layouts, to make it easy to find the matching part in the config file.