var = arg([num|str])
var = env([num|str[,str|0]])
var = run(cmd[,buf])
*** = jump(cmd)
*** = exit([code])
*** = abort()
The terms "program" and "process" are often used interchangeably, but they are not the same thing. A program is the machine code (or in our case JavaScript code) which comprises the set of instructions to be executed. A process is a single running instance of a particular program. There may be many such instances, as the same program may be started over and over again. In fact, programs often start new instances of themselves, using the fork() function. And, even within the same process, a program may replace itself with another program, perhaps written in a different language. This page deals with functions that pertain mostly to programs but, partly, to the run-time environment of the process instances in which they run.
The arg() function provides access to the list of command line arguments passed to a program each time it is executed (as a new process). If no argument is given to the arg() function itself, it returns the number of arguments passed to the program. Otherwise, if a num is provided, it returns a string containing the program argument indexed by num. If this is out of range, or deleted, or any other error is detected, arg() returns a null. The first argument, arg(0), is always present and contains the name (and possibly the path) used to invoke the program.
This is standard for all Unix programs, but JSUS provides additional functionality, similar to that provided by the getopt() function from the C run-time library. A string argument may be provided to identify a specific option in the argument list, by name. If found, the value of that option is returned and the option (and value) is deleted from the argument list. If there is no applicable value, but the option is present, arg() returns boolean true (since an empty string would test false). After all permissable arguments are extracted, only a list of potential file names (or other argument values) should remain. The program can then easily scan the remaining list to identify any invalid command line options (and to extract file names which were not themselves values for specific options). Note, however, that when complete "words" are deleted from the argument list, an arg(num) call upon them will return null (the total number of arguments always remains constant). The named option list may be terminated by a single "word" with either one or two dashes. Any arguments following this can only be referenced by their numeric index (and are not automatically deleted).
The arg() function supports three different types of options, all of which may be freely mixed in the same command line. Traditionally, Unix options consist of a single letter (or digit) immediately preceded by a dash (e.g. "-h" is frequently used to request display of "help" information). Multiple options can be specified either as separate "words" (e.g. "-a -b -c") or they may be combined as a single "word" (e.g. "-abc"). Then, if the next "word" in the argument list does not begin with a dash, it is assumed to be the "value" of the immediately preceding option and that is what is returned to the caller. Both option and value are then deleted from the argument list.
The potential ambiguity of "traditional" options led to the development of so-called "GNU style" or "long" options. These are each entered as a single "word", beginning with a double dash (and optionally enclosed within quotes, to allow embedded spaces). The "name" of the option must be a valid label and may optionally be followed by an equals sign and a value (which is returned to the caller). Our own JSUS style options are similar, but have no leading dashes. The "name" of the option must be a valid JavaScript identifier and must be followed by an equals symbol, even if no value is provided (in which case arg() returns boolean true, not null). It is important to remember that all three methods may be used, interchangeably, to represent the same option: "-f file-path" and "--f=file-path" and "f=file-path" all produce the same result. But, the GNU style option "--f file-path" is not supported by JSUS and neither are arguments whose names begin with a digit.
The env() function provides access to the process' environment — a set of named variables which may be passed from one program to another. Many of these are set automatically at system start up, or when a user logs in to the system. For example, the PATH variable contains a list of directory paths to be searched when another program is run(). If no argument is given, env() returns a count of entries in the environment (some of which may be null, indicating deleted values). If just one numeric argument is given, that is used as an index into the environment, and a string is returned with the complete variable (including its name and equal sign). If a single string is passed, that is used to identify the variable, by name, and a string is returned with just the value of that variable. Like arg(), boolean true is returned if that string is empty. If two strings are passed, the first is used to identify the variable and the second is set as a new value in the environment. If the named variable does not exist, a new variable is created. The number 0, passed as the second argument, causes the entire variable to be deleted. Then, env() returns true if the environment is successfully updated. Returns a null if any errors are detected.
The run() function executes a program command by first forking a child process and then running the underlying execve() function. A complete "command" must be provided within a single JavaScript string, beginning with the name or path of a valid executable program or script. Optionally, this may be followed by a list of program arguments, separated by one or more spaces. Any of these arguments may themselves be strings, enclosed in either double or single quotes, and may contain embedded spaces or quotes of the opposite type. If given, buf specifies a maximum number of UTF-8 bytes to "capture" from the command's stdout and stderr files. This buffer is then returned to the caller as a single string. If buf is omitted, the command's exit code is returned as a number.
The jump() function is similar to run(), above, except no child process is forked and output cannot be captured. This function terminates the current program and starts a new one (which need not be written in JavaScript). All of the process' memory is overwritten with the new program, including the JSUS interpreter and its target program. Only the pid, any open files, and the environment remain available to the new program, just like the exec() function in the runtime library. This function does not return unless there is an error, in which case a null is returned.
The exit() function is the polite way to end a JSUS program. It cleans up any open files, etc., and terminates the process, returning the optional exit code to the operating system. This function does not return unless there is an error, in which case a null is returned. The exit() function is not really necessary. A JSUS program also terminates normally if control flow reaches the end of the program file.
An abort() function call terminates the current process, immediately, usually with a core dump. This function is always successful and never returns.
The ETC configuration database