Documentation - Controller

Standard Parameters

Short	Long	Description
`-h`	`--help`	Print the help message.
`+C`	`++copyright`	Print the copyright.
`+d`	`++dark`	Output using colors that show up better on dark backgrounds.
`+l`	`++light`	Output using colors that show up better on light backgrounds.
`+n`	`++no_color`	Do not print using color.
`+Q`	`++quiet`	Decrease verbosity, silencing most output.
`+E`	`++error`	Decrease verbosity, using only error output.
`+N`	`++normal`	Set verbosity to normal.
`+V`	`++verbose`	Increase verbosity beyond normal output.
`+D`	`++debug`	Enable debugging, significantly increasing verbosity beyond normal output.
`+v`	`++version`	Print only the version number.

The +Q/++quiet parameter silences all output that is not the intent and purpose of the program.
For example, the purpose of the utf8 program is to print the Unicode code point or the UTF-8 byte code.
The +Q/++quiet will not suppress this output.
The new line printed at the end of the program, is however, not printed.
The +Q/++quiet is ideal for using in scripting to help guarantee more consistent and controlled output.

The +N/++no_color simplifies the output to avoid the special color character codes.
The special color character codes tend to take up a lot of extra space and may slow down printing performance.

Program Parameters

Short	Long	Description
`-c`	`--cgroup`	Specify a custom control group file path, such as `/sys/fs/cgroup/`.
`-d`	`--daemon`	Run in daemon only mode (do not process the entry).
`-I`	`--init`	The program will run as an init replacement.
`-i`	`--interruptible`	Designate that this program can be interrupted by a signal.
`-p`	`--pid`	Specify a custom pid file path, such as `controller/run/default.pid`.
`-s`	`--settings`	Specify a custom settings path, such as `controller/`.
`-S`	`--simulate`	Run as a simulation.
`-k`	`--socket`	Specify a custom socket file path, such as `controller/run/default.socket`.
`-U`	`--uninterruptible`	Designate that this program cannot be interrupted by a signal.
`-v`	`--validate`	Validate the settings (entry and rules) without running (does not simulate).

When both the --simulate parameter and the --validate parameter are specified, then additional information on each would be executed rule is printed but no simulation is performed.

The default interrupt behavior is to operate as if the --interruptible parameter is passed.

Specify an empty string for the --pid parameter to disable pid file creation for this program.

Simulate Documentation

This describes the intent and purpose of the simulation and validation parameters.

The controller program is designed to support being run as an alternative to an init program (such as Sysvinit or SystemD).
To help prevent problems, simulation and validation functionality is provided.

The validate functionality:

By itself will simply check the syntax of the Entry and Rule files (for Rule files specified in the Entry or Exit file).
Errors are reported and nothing is executed.
The controller program will return 0 on validation success and 1 on validation failure.
The simulate functionality:

By itself will perform a simulated execution of all Rules designated by an Entry or Exit file.
The simulation is not a true simulation in that no program is ever called to perform any operations.
Furthermore, any script specified inside a Rule is only simulated as a whole and not its individual parts.
Once the Entry file is finished executing, the simulate will continue to run waiting on control commands.
The simulate with validate functionality:

Will perform similar to validate functionality except that additional information of the Rules to be executed will be printed.
There will be neither execution nor simulated execution of any Rule when both simulate and validate are used together.

When a Rule is simulated, an empty script command (generally defaulting to bash) is executed in place of the actual program being executed for each program or script in the Rule file that is to be executed.
This allows for testing the designated permissions and other settings that would be applied when calling some program.
Control Groups are not simulated but are actually created and the simulating process will actually be placed within the Control Group.

Time Documentation

The controller program utilizes the unit of measurement called a Time, represented with uppercase T.
For comparison, a unit of Time is equivalent to a nanosecond, or 10^-9 seconds.
A MegaTime (MT) is therefore equivalent to a millisecond such that a millisecond is 10^-3 seconds.

A unit of Time is intended to represent some unit of Time such that a single 64-bit integer may hold all units of Time for a single calendar year.
This unit of Time does not and must not include Years (unlike Unixtime).
To convert from Time to Unixtime, one must have a year (which could be assumed to be the current year) and then calculate all of those calendar oddities.

A unit of Time by default is assumed to be in UTC.

1 (Earth) year ~= 31536000000000000 Time or 31536000 GT (GigaTime).
1 (Earth) day = 86400000000000 Time or 86400 GT (GigaTime).
1 (Earth) hour = 3600000000000 Time or 3600 GT (GigaTime).
1 (Earth) minute = 60000000000 Time or 60 GT (GigaTime).
1 (Earth) second = 1000000000 Time or 1 GT (GigaTime).

Consequentially, 1 day in units of Time is easily represented as 86.4 TT (TeraTime).

The Time may be stored in its year string format.
In this format, a Year may be prepended to the Time followed by a single colon : to associate a year with the Time.
This Year has no minimum or maximum but may not have decimals.
For example, 2020:86400000000000 would represent: January 02, 2020 0:00 UTC.
For example, 2020:86.4 TT would represent: January 02, 2020 0:00 UTC.

A second unit of Time, called EpochTime, works the same way as Time except it represents seconds.
This unit is designated E.
The format is similar to Time, except there are two colons: 1970::1620874738 would represent: May 13, 2021 2:58:58 UTC.
When the year is not specified, then this is identical to UNIX Epoch.

A unit of EpochTime by default is assumed to be in UTC.

1 (Earth) year ~= 31536000 EpochTime or 31.536 GE (GigaEpochTime).
1 (Earth) day = 86400 EpochTime
1 (Earth) hour = 3600 EpochTime
1 (Earth) minute = 60 EpochTime
1 (Earth) second = 1 EpochTime
1 GT (GigaTime) = 1 EpochTime

Consequentially, 1 day in units of EpochTime is easily represented as 86.4 KE (KiloEpochTime).