Manpage of TEST-INET_TCP

TEST-INET_TCP

Section: OpenSS7 INET Networking Administration (8)
Updated: 2008-10-31
Index Return to Main Contents

NAME

test-inet_tcp - a test suite executable for the inet(4) STREAMS driver

SYNOPSIS

test-inet_tcp [options] [{-o|--onetest} [TESTCASE]] [{-t|--tests} [RANGE]]
test-inet_tcp [options] {-l|--list} [RANGE]
test-inet_tcp {-h|--help}
test-inet_tcp {-V|--version}
test-inet_tcp {-C|--copying}

DESCRIPTION

test-inet_tcp
is a test suite executable for the inet(4) STREAMS driver. The purpose of the test-inet_tcp test suite executable is to provide a means for development, diagnostic, regression and validation testing of the inet(4) driver. The OpenSS7 INET Networking package also provides an autotest based test suite that uses the test-inet_tcp test case executable to invoke test cases. This test suite can be used for development, diagnostic, regression or validation testing. See the OpenSS7 INET Networking Installation and Reference Manual for more information on how to invoke the autotest test suite.

OPTIONS

test-inet_tcp options fall into several categories as detailed in the subsections below. If test-inet_tcp is executed without any options, it will execute all available test cases and report the progress and results of each test case.

Command Options

These command options determine whether test cases are run or whether an informative function is performed instead. If none of these command options are specified, then it is assumed that all test cases are to be executed. Options --list, --help, --version and --copying will override the --onetest and --tests options.

-o, --onetest [TESTCASE]: Specifies a single test case to run. TESTCASE is the individual test case number. This option may be repeated and is accumulative: that is, each test case added with an occurrence of this option will be added to the other test cases selected with --onetest or with --tests.
-t, --tests [RANGE]: Specifies a range of test cases to run. RANGE specifies the range of test cases and will match all test cases that have this string as an initial substring of the test case number. If RANGE is not specified, then all test cases are selected.
-l, --list [RANGE]: When this option is encountered, print a list of test cases to stdout and exit. When a RANGE of test cases is specified, only the specified range of tests will be listed. When a RANGE is not specified, all test cases will be listed. When used in combination with --verbose this option will print more or less information about each test case. Note that all options specified following this option are ignored.
-h, --help, -?, --?: When this option is encountered, print usage information to stdout and exit. Note that all options specified following this option are ignored.
-V, --version: When this option is encountered, print version information to stdout and exit. Note that all options specified following this option are ignored.
-C, --copying: When this option is encountered, print copying information to stdout and exit. Note that all options specified following this option are ignored.

General Options

The following options are applicable to all command options. For other than test case command options, these general options must appear ahead of the command option.

-q, --quiet: Specifies that the caller is interested only in the return code and error diagnostics and that normal output should be suppressed. The default verbosity level if this option is not specified is 1. This option is equivalent to --verbose=0.
-v, --verbose [LEVEL]: Increases or sets the verbosity level. When this option is given without the LEVEL argument, it specifies that the verbosity level should be increased by one. If the LEVEL argument is specified, the verbosity level is set to that integer value. This option can be repeated. The default verbosity level if this option is not specified is 1. For example, -vvvv is equivalent to --verbose=5.

Test Case Options

The following options are only applicable if a test case command option is in effect. That is, these options are only effective if test cases are being executed and are used to modify the manner in which test cases are executed or test case results reported.

-d, --device DEVICE: Specifies the device name to open for the tests.
-w, --wait: Specifies that the client or server is to wait indefinitely. Normally a test case guard timer is started (40 seconds) that will fire and cause the test case to fail if the test cases waits indefinitely for an event to start or continue. This option suppresses the test cause guard timer and allows the client or server to wait indefinitely from some event to occur. This is paricularly useful when one side of the test case (client or server) is being run manually.
-e, --exit: Specifies that the first test case run that is not successful will cause all remaining test cases to be skipped and the return code will reflect the result of the failed test case. This option is useful in conjunction with option --onetest in that if a single test is being run, the return code will reflect the result of the test case. This is used by the strinet-0.9.2.7 test suite to run individual tests under autotest.
-a, --again: Specifies that the selected test cases are to be repeated in verbose mode if they fail in non-verbose mode. This option is useful for use with autotest test suites.
-R, --repeat: Repeat the selected test cases on success or failure. This option causes the executable to loop through the selected test cases, one after the other, regardless of whether an individual test case succeeds or fails. This option is useful in conjunction with --onetest and --client or --server when the other end of the test is being executed manually.
-r, --repeat-fail: Repeat the selected test cases on failure. This option caues the executable to loop individual test cases when they fail, but allows the test sequence to continue when an individual test case succeeds. This option is useful in conjunction with --onetest and --client or --server when the other end of the test is being executed manually.
-f, --fast [SCALE]: When this option is present, test cases are run faster by the integer scaling factor SCALE. If SCALE is not provided, then the default scale factor is 50. This has the effect of scaling timers both in the implementation under test as well as in the test suite. If the scale factor, SCALE, is too large, test cases may fail that would otherwise pass. This option is useful for long test suite runs that would otherwise take an inordinate amount of time to execute. Timers can be scaled for development, diagnostic or regression testing, however, for full validation testing this option should not be used.
-s, --summary: Print a test case summary with each test case result at the end of the test suite run. The default if this option is not present is to not print a summary.
-m, --messages: Indicates whether messages, in hexadecimal, should be included in the test case output. This is independent of any --verbose setting.

Client Server Options

The following options are applicable to all command options. These options determine whether the test case executes in client mode, server mode, or both and the addresses and port numbers associated with the client and server.

The following two options determine whether the test cases execute in client mode, server mode or both. The default (that is used by autotest) is to execute both the client and server sides in a self-validation test.

-c, --client: Requests that the client side of the test cases be executed (client mode). The default if neither the -c or -S options are specified is to execute both the client and server side of the selected test cases. Specifying both -S and -c has the same effect as the default (specifying neither).
-S, --server: Requests that the server side of the test cases be executed (server mode). The default if neither the -c or -S options are specified is to execute both the client and server side of the selected test cases. Specifying both -S and -c has the same effect as the default (specifying neither).

The following four options determine the IP addresses and port numbers that are used on the client and server sides of the test. The defaults (used by autotest) are localnet addresses 127.0.0.1, 127.0.0.2 and 127.0.0.3 and test case unique port numbers in the range beginning at port number 18000 (to avoid timed waits and connections that have otherwise not yet been shut down).

-p, --client-port [PORT]: Specify the client port number, PORT, from which to connect (client mode) or from which to accept connections (server mode). This option can be specified in both client and server mode. In client mode it identifies the local port; in server mode, the remote port. The default if a port number is not specified is for the client to connect from port number 18000, offset by the index of the test case time three (one for connecting, one for listening and one for responding), resulting in a unique port number for each device file descriptor invoved in each test. So, for example, the first test case will connect from port 18000, the second from port 18003, and so on.
-P, --server-port [PORT]: Specify the server port number, PORT, upon which to listen (server mode) or to which to connect (client mode). This option can be specified in both client and server mode. In client mode it identifies the remote port; in server mode, the local port. The default if a port number is not specified is for the sever to listen on port number 18002, offset by the index of the test case times three (one for connecting, one for listening and one for responding), resulting in a unique port number for each device file descriptor invoked in each test. So, for example, the first test case will listen on port 18002, the second on port 18005, and so on.
-i, --client-host [HOSTNAME[,HOSTNAME]*]: Specify the client hostnames, HOSTNAME, from which to connect (client mode), or from which to accept connections (server mode). Each HOSTNAME can be either a host name or a numbers-and-dots notation IP address. Multiple host names can be specified, separated by commas. This option can be specified in both client and server mode. In client mode it identies the local host; in server mode, the remote host. The default if a host name is not specified is the IP addresses 127.0.0.1, 127.0.0.2 and 127.0.0.3.
-I, --server-host [HOSTNAME[,HOSTNAME]*]: Specify the server hostnames, HOSTNAME, upon which to listen (server mode), or to which to connect (client mode). Each HOSTNAME can be either a host name or a numbers-and-dots notation IP address. Multiple host names can be specified, separated by commas. This option can be specified in both client and server mode. In client mode it identies the remote host; in server mode, the local host. The default if a host name is not specified is the IP addresses 127.0.0.1, 127.0.0.2 and 127.0.0.3.

DIAGNOSTICS

When test-inet_tcp fails, it prints a diagnostic message to stderr and exits with a non-zero return code. The following return codes are generated under the following conditions:

0: Execution was successful. One test case was selected for execution and that test case succeeded or was not applicable (i.e. unsupported). This exit code is interpreted by autotest as a PASS condition.
1: One test case was selected for execution and that test case failed or was inconclusive. More than one test case was selected and abort on failure was specified using the --exit option, and a test case in the selected test cases failed or was inconclusive. This exit code is interpreted by autotest as a FAIL or XFAIL condition.
2: An invalid parameter was provided. Test case execution was specified with options --onetest or --tests, or listing of test cases was specified with option --list, but no test case was selected by these options. More than one test case was selected for execution and a check of the test suite setup failed. This exit code is interpreted by autotest as a FAIL or XFAIL condition.
77: One test case was selected for execution and that test case was skipped. This exit code is interpreted by autotest as a SKIPPED condition.

NOTICES

test-inet_tcp is normally invoked from the strinet-0.9.2.7 test suite.

EXAMPLES

test-inet_tcp --list 0.1: Generates a list of all test cases provided by the test-inet_tcp executable with numbers starting with the initial substring of 0.1.
test-inet_tcp -vv --list: Generates a verbose listing of all test cases provided by the test-inet_tcp executable.
test-inet_tcp --verbose=5 --onetest 0.1: Verbosely executes test case 0.1, and provides a diagnostic return code.
test-inet_tcp --fast --quiet --exit: Executes all test cases with a timer scaling factor of 50 with normal output suppressed and exiting on the first failed or inconclusive test case result.

DRIVERS

inet(4).

FILES

/usr/libexec/strinet/test-inet_tcp: contains the test-inet_tcp command.

BUGS

test-inet_tcp has no known bugs.

COMPATIBILITY

The test-inet_tcp test suite, when run using autotest, is compatible with the POSIX 1003.3 conformance test methodology, with the following mapping of test results:


POSIX 1003.3	test-inet_tcp	autotest

PASS	PASS(0)	PASS
FAIL	FAIL(1)	FAIL
XFAIL	FAIL(1)	XFAIL
UNSUPPORTED	NOT APPLICABLE(0)	PASS
UNRESOLVED	INCONCLUSIVE(1)	FAIL or XFAIL
UNTESTED	SKIPPED(77)	SKIPPED