Appendix C Interface to the external program at ¶

This section documents the interface to the atd daemon; the at service allows a user to schedule commands to be executed at a later time, we may want to read the at(1) manual page. The interface is defined by the library libmbfl-at.bash.

This interface is suitable for scripts that define a unique simple policy to schedule commands; example: at each run they schedule a command in a fixed queue, to be executed at a fixed time in the future. This is good to implement the logic: if a condition does not happen before time T, then execute command C.

We can load this library at run–time with:

mbfl_load_library(/path/to/libmbfl-at.bash)

for details Libraries loading and embedding. Notice that the preprocessor option --print-libmbfl-at will print the file pathname of the installed library, Invoking the preprocessor.

Commands declaration ¶

Function: mbfl_at_enable ¶

Declare the intention to use the at interface. Declaring the intention to use a program.

The declared programs are: at, atq, atrm.

Arguments validation ¶

Function: mbfl_at_validate_queue_letter LETTER ¶

Return true if LETTER is a valid queue identifier, else return false.

Function: mbfl_at_validate_selected_queue ¶

Return true if the currently selected queue identifier is valid, else print an error message and return false. A false return code means that an internal error has corrupted the module’s state.

Commands scheduling ¶

Function: mbfl_at_select_queue LETTER ¶

Select and register in an internal state a queue identifier; invoke mbfl_at_validate_queue_letter() to validate the selection.

Function: mbfl_at_schedule COMMAND TIME ¶

Schedule COMMAND in the currently selected queue; the script will be executed at TIME.

If no error occurs: print to stdout the identifier of the scheduled job; the identifier can be used as argument to mbfl_at_drop().

The at command outputs some text (in which the job is embedded) on its stderr channel, so this function redirects stderr to stdout to return the value; this operation conflicts with the use of the “show program” feature of mbfl_program_exec().

COMMAND must be a string representing the invocation of an external executable program: it is sent unchanged to the at command. TIME is the argument to the at command, see the manual page for its description.

Function: mbfl_at_drop IDENTIFIER ¶

Remove a job; the identifier of a job is unique in all the queues, so this function is not affected by the currently selected queue.

Function: mbfl_at_queue_clean ¶

Remove all the jobs from the currently selected queue.

Inspection ¶

Function: mbfl_at_queue_print_identifiers ¶

Print all the job identifiers in the currently selected queue.

Function: mbfl_at_queue_print_jobs ¶

Print all the job descriptions in the currently selected queue.

Function: mbfl_at_queue_print_queues ¶

Print the letters identifying queues with pending jobs.

Function: mbfl_at_print_queue ¶

Print the currently selected queue letter.