USEX: User-Supplied Command
One of the more convenient and powerful capabilities of usex is the capability to run one or more test programs of the user's choice. All that needs to be done is to enter the desired command string, preceded by an exclamation point (!), during the initial test type selection. The user-supplied command may be an executable program or a shell script.

Here is a screenshot of a usex session running 5 external user-supplied test programs:

usex
********************************************************************************
*  ID  BSIZE  MODE   POINTER   OPERATION         FILE NAME         PASS  STAT  *
*  --  -----  ----  ---------  ---------  -----------------------  ----  ----  *
*   1  xterm -e usex -b  [                                      ]     1   OK   *
*   2  x11perf -all  [                                          ]     1   OK   *
*   3  Bonnie -d /usr/tmp -s 200  [Reading with getc()...done   ]     2   OK   *
*   4  xosview  [                                               ]     1   OK   *
*   5  ls -R /  [font_8x8.c,v                                   ]     1   OK   *
*                                                                              *
*                                                                              *
*                                                                              *
*                                                                              *
*                                                                              *
*                                                                              *
*                                                                              *
********************************************************************************
*  Unix System EXerciser  *  USER SYSTEM IDLE  LOADAVG  TASKS/RUN   TEST TIME  *
*    USEX Version 1.7     *   60%   40%    0%   15.65     228/14    000:09:06  *
*                         *                                                    *
*     anderson - i686     *  PAGE-IN PAGE-OUT  FREEMEM  FREESWAP   CSW   INTR  *
*   Linux 2.2.5-15smp2    *    2776    4000     1.5 mb   121 mb   18189  3566  *
*                         *  SWAP-IN SWAP-OUT  BUFFERS   CACHED   FORKS        *
*    23Apr01  12:02:23    *     0       0      40.0 mb  40.7 mb     56         *
********************************************************************************
In the example session above:
  • Test 1 is running an external xterm that contains another usex session running with the usex -b command line option.
    
    
  • Test 2 is running the x11perf X server performance test, whose output is also being displayed in an external window.
    
    
  • Test 3 is running the Bonnie benchmark. Since the test is running in the foreground mode ("OK" status), the textual output of the program is being displayed in the bracketed box following the command string.
    
    
  • Test 4 is running on xosview, a graphical system performance program whose output is in an external window.
    
    
  • Test 5 is doing a recursive listing on every file accessible by the system. Since the test is running in the foreground mode ("OK" status), each filename will be displayed in the bracketed box following the command string.
    
    
  • Note that tests 1, 2 and 4 have no textual output, since all of them run externally in their own windows.

    Also note that PASS counts will only be incremented if the user-supplied test runs to completion, as opposed to running in a loop, or perhaps requiring intervention to complete. If, however, a test does run to completion, it must return a zero (successful) exit status; if it returns a non-zero test status, the usex test harness will perceive it as an error, and the test will die. This feature may be overridden if the command string is preceded by a caret (^) instead of an exclamation point (!) when specifying the command during invocation.

    The meaning of user-supplied test's display line fields are:

    TEST DISPLAY LINE
    The bin test display line always shows the full command string entered during invocation, without the preceding ! or ^. Following the command string is a [bracketed] space, that will either:
    1. contain any textual output of the command that is running, if the test is running in the verbose foreground ("OK") mode.
    2. be empty, if the command is running in the less-verbose background ("BKGD") mode.
    3. 
      
    PASS A single pass consists of one complete execution of the invoked command. If the command does not exit on its own, then the PASS count will remain at 1.
    
    
    STAT The status field should normally indicate either "OK" or "BKGD", both of which mean the test is running just fine. If the command string was entered preceded by an exclamation point (!), and it exits with a non-zero status, the test will die, and the status will change to "<DEAD>". If the test is explicitly killed by the tk or t<testnum>k interactive command, the status will also change to "<DEAD>". If the test was directed to go into "hold" mode by the th or t<testnum>h interactive command, the status field will indicate "HOLD" until instructed to continue.
    
    
    The following two limitations apply to user-supplied tests:
    1. The test may not accept interactive input. If the test requires input, a shell script should be written that feeds the actual test the proper input, and the name of that shell script should be entered during during invocation.
      
      
    2. The command string may not contain pipes or redirections. As with interactive input, if a pipe or redirection is required, a shell script should be written that performs the pipe or redirection, and the name of the shell script should be entered during invocation.
      
      
    It should be noted that when a shell script is used, it should exit with a status of zero in order to run the script repetitively. Alternatively, the script can be invoked preceded by a caret (^) instead of an exclamation point (!), in which case the exit status will be ignored.