cnet(local)

NAME
cnet (v1.7) - a communications network simulation program

SYNOPSIS
cnet [many options] {TOPOLOGY_FILE | -r nnodes}

DESCRIPTION
cnet is a nwtwork simulator enabling experimentation with various data-link layer, network layer, routing and transport layer networking protocols. In addition, different application and physical layers may be provided which exhibit varying statistical characteristics of message generation and data transmission. Protocols are written in the ANSI-C programming language and, when compiled and linked by cnet, execute natively in a single UNIX/LINUX process. cnet either presents and enables interaction with its simulated network under the Tcl/Tk windowing system, or runs rather less visually on an ASCII terminal.

cnet first accepts a number of command line options and then either reads a network specification from a network topology file or generates a random network of a requested size. Having built and checked the network topology, cnet will compile and dynamically link any source files specified for each node in the topology file, or those files provided via the -A and -P command-line options.

Each node may execute its own network protocols or protocols shared with other nodes, and will access its own set of global and local variables. When executing, each node has access to its own copy of a number of node and link attributes and many of these attributed may be modified, via the windowing interface, while a simulation is running. Each node's node and link attributes are available at run-time in ANSI-C data structures and variables declared in <cnet.h>. Each cnet protocol source file should include this header file. The data structures are initialized when each node is rebooted and updated as each node is scheduled for execution. The contents of these data structures should be considered as readonly values and should not be modified directly by the protocols' C code. They may be successfully modified via the windowing interface.

This manual only describes cnet's command-line options, and does not describe the format of the topology files, nor cnet programming and tracing techniques. All cnet documentation is available from the cnet web-page at http://www.cs.uwa.edu.au/cnet/.

COMMAND-LINE OPTIONS
cnet supports a number of command-line options which should be presented before the name of the topology file or a request for a random topology. Options which themselves accept a following argument expect that argument to appear as a separate word on the command-line (i.e. after a space).

Specifying all of -M mins, -S seed and -T enables a simulation to be replayed.

-A string
    Specify a "compilation string" declaring a new application layer to be used. In its simplest form, the -A option is followed by the name of a single ANSI-C file providing the implementation of the application layer protocol. If -A is not provided, a default (internal) application layer is used. The eventual application layer is the source and sink of all messages.

-c  Normally the time_of_day clocks in each node are initially different (and protocols could be developed to synchronize the clocks). If -c is specified, the clocks in all nodes will initially be synchronized.

-C string
    Specify a "compilation string" which declares each node's "internal" layers to be used. In its simplest form, the -C option is followed by the name of a single ANSI-C file providing the implementation of all "internal" layers. If -C is not provided, the filename ``protocol.c'' is assumed.

-d  Provide some diagnostic/monitoring information while cnet is running. All reported information is sent to cnet's stderr output stream.

-e  Normally, corruption errors on links are not reported by the Physical Layer and must be detected by the receiver. If -e is specified, function read_physical() will detect and report corruption errors by returning -1 and setting cnet_errno to ER_CORRUPTDATA.

-E nevents
    Request that cnet only run for the indicated number of events.

-f secs
    Set the frequency of the diagnostic and statistical summary (in seconds). In combination with -s and -z, cumulative statistics may be periodically reported. All reported information is sent to cnet's stdout output stream.

-F filename
    If cnet has been compiled for Tcl/Tk, the indicated file will be sourced by the Tcl/Tk interpreter. The filename may also be provided via the CNETTCLTK environment variable. If the file cannot be found directly, CNETPATH will be searched to locate the file. If -F is not provided, the filename ``cnet.tcl'' is assumed.

-g  Commence execution (go) as soon as the main window appears (under Tcl/Tk) - implied by -W.

-k  Use ``old'' Kernighan and Ritchie (K&R) C to compile the user supplied source files for the application layer (-A), the ``central'' protocol layers (-C), and the physical layer (-P). The default is to use the ANSI-C compiler, gcc.

-m mins
    To prevent runaway processes choking our teaching machines, a 3 minute time limit is silently imposed on cnet execution. The -m option overrides this limit.

-M mins
    Limit the length of the simulation to -M minutes of 'simulated time' when used in combination with -T.

-n  Simply parse the topology file, compile and link all necessary C source files, and then exit.

-N  Provide the number of nodes in the network in the C variable NNODES. Surprisingly, the default is that each node does not know how many nodes the network contains (NNODES = 0).

-o file_prefix
    Copy the output of each node's calls to printf(), puts() and putchar() to a file with the indicated prefix. For example, the use of -o output will typically create and write to the files output.node0, output.node1, output.node2, ....

-O  Open all node windows on startup (unless overridden by the winopen topology file attribute).

-p  After parsing, checking, and building the network topology, simply print it out and exit cnet.

-P string
    Specify a "compilation string" which declares a new physical layer to be used. In its simplest form, the -P option is followed by the name of a single ANSI-C file providing the implementation of the physical layer protocol. If -P is not provided, a default (internal) physical layer is used. The eventual physical layer is used to deliver and possibly corrupt and lose data frames.

-q  Execute quietly (and more quickly) - all output requested with printf(), puts() and putchar() will not appear in the node output windows. All output produced during an EV_DEBUG? event (a button press) will still appear, as will all output ``mirrored'' in logging files.

-r nnodes
    Request that a random network be generated, consisting of nnodes. Each node will have at least one link and the whole network is guaranteed to be connected. The -r option may be used instead of providing a topology file.

-R function_name
    Use function_name() as the function to first invoke when rebooting each node. By default, the function reboot_node() will be invoked.

-s  Print a summary of the network's activity just before cnet exits.

-S seed
    Provide the seed for random number generation (for message generation and frame corruption). Specifying all of -M mins, -S seed and -T enables a simulation to be replayed.

-t  Trace all events delivered to each network node. A description of all cnet function calls, arguments and return and cnet_errno values is reported via cnet's trace stream. If cnet is running within the Tcl/Tk windowing environment, trace output appears in a subwindow under the network's topology map. Otherwise, any trace output appears via cnet's stderr stream. Any output requested with CNET_trace will also appear on cnet's trace stream.

-T  By default, cnet runs in ``wall-clock'' time, that is, the simulation performs one second of network-work in one second of ``wall-clock'' time. This works well for up to about 20 nodes beyond which cnet ``gets behind''. Using -T forces cnet to ignore the ``wall-clock'' time and to execute as a true discrete-event simulator.

-v  Be very verbose reporting cnet's actions. All reported information is sent to cnet's stderr output stream.

-W  Disable the display of the network using the Tcl/Tk windowing environment (this the default for ASCII terminals!).

-z  Display statistics and event summaries even if they are zero (implies -s).

EXIT STATUS
cnet will exit with a 0 if either the ``Exit cnet'' button is selected or the time limit expires. Any other conditions, such as an error in the topology file or a syntax error in the protocol source files, will result in cnet exiting with a status of 1.

FILES AND ENVIRONMENT
The standard header file, <cnet.h>, which is included by cnet itself and should be included in your protocol files, is in /cslinux/cnetlib. The environment variable CNETPATH may define a colon delimited list of directories in which to find an alternate <cnet.h> file. The filename of the Tcl/Tk commands may be provided via CNETTCLTK. CNETGCC and CNETCC provide the full pathnames of alternate ANSI-C and non-ANSI C compilers, respectively, to be used instead of the precompiled defaults. If defined, CNETCPP similarly provides the full pathname of the C preprecessor if your C compiler does not accept a -E option.

SEE ALSO
WWW-based documentation at
http://www.cs.uwa.edu.au/cnet/

[McD91]    "A Network Specification Language and Execution Environment for Undergraduate Teaching",
C.S. McDonald, Proc. of the ACM Computer Science Education Technical Symposium '91, San Antonio, Texas, Mar 1991, pp25-34.
[McD93]    "Network Simulation Using User-level Context Switching",
C.S. McDonald, Proc. of the Australian UNIX Users' Group Conference '93, Sydney, Sept 1993, pp1-10.
[McD96]    "Teaching Computer Networking Principles Using Simulation",
Handouts from Chris McDonald's ACM-SIGCSE'96 workshop, (http://www.cs.uwa.edu.au/cnet/sigcse96.shar.gz).

LIMITATIONS
cnet refuses to compile files with the word receive spelt incorrectly.

Only one application layer type and one physical layer type may be specified, with -A and -P respectively. It is not possible for each node to use a different application layer or physical layer.

As the Tcl/Tk windowing environment uses the X-windows system under UNIX/LINUX, the protocols should not use the following system and library functions: alarm(3), getitimer(3), ioctl(2), setitimer(2), sigblock(2), sigmask(2), signal(3), sigvec(2), sleep(3), system(3), wait(2), wait3(2) or perform any UNIX/LINUX I/O that may block for long periods.

AUTHOR
Chris McDonald (The University of Western Australia, chris@cs.uwa.edu.au)
Many other contributors are gratefully acknowledged on the cnet web-page at http://www.cs.uwa.edu.au/cnet/.