.\"
.\" Copyright 1992 Cray Research, Inc.
.\" All Rights Reserved.
.\"
.\"
.\" Permission to use, copy, modify and distribute this software, in
.\" source and binary forms, and its documentation, without fee is
.\" hereby granted, provided that:  1) the above copyright notice and
.\" this permission notice appear in all source copies of this
.\" software and its supporting documentation; 2) distributions
.\" including binaries display the following acknowledgement:  ``This
.\" product includes software developed by Cray Research, Inc.'' in
.\" the documentation or other materials provided with the distribution
.\" and in all advertising materials mentioning features or use of
.\" this software; 3) the name Cray Research, Inc. may not be used to
.\" endorse or promote products derived from this software without
.\" specific prior written permission; 4) the USMID revision line and
.\" binary copyright notice are retained without modification in all
.\" source and binary copies of this software; 5) the software is
.\" redistributed only as part of a bundled package and not as a
.\" separate product (except that it may be redistibuted separately if
.\" if no fee is charged); and 6) this software is not renamed in any
.\" way and is referred to as Nettest.
.\"
.\" THIS SOFTWARE IS PROVIDED AS IS AND CRAY RESEARCH, INC.
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
.\" PARTICULAR PURPOSE.  IN NO EVENT SHALL CRAY RESEARCH, INC. BE
.\" LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
.\" DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
.TH NETTEST 8
.SH NAME
.QS
\*Cnettest\fR, \*Cnettestd\fR \- Performs client and server functions for timing data throughput
.QE
.SH SYNOPSIS
.QS
\*C/etc/nettest\fR
\%[\*C-c\fR]
\%[\*C-C\fR]
\%[\*C-d\fR]
\%[\*C-f\fR]
\%[\*C-F\fR]
\%[\*C-h\fR]
\%[\*C-b\fR\ \fIbufsize\fR]
\%[\*C-S\fR\ \fItos\fR]
\%[\*C-n\fR\ \fIconns\fR]
\%[\*C-p\fR\ \*Ctcp\fR|\*Cudp\fR|\*Ciso\fR]
\%[\*C-s\fIn\fR]
\%[\*C-m\fR]
\%[\*C-w\fR]
\%[\fIhost\fR\ [\fIcount\fR\ [\fIsize\fR\ [\fIport\fR]]]]
.br
\*C/etc/nettest\fR
\%[\*C-c\fR]
\%[\*C-C\fR]
\%[\*C-d\fR]
\%[\*C-f\fR]
\%[\*C-h\fR]
\%[\*C-b\fR\ \fIbufsize\fR]
\%\*C-p\ unix\fR|\*Cunixd\fR|\*Cpipe\fR
\%[\*C-n\fR\ \fIconns\fR]
\%[\*C-w\fR]
\%[\fIcount\fR\ [\fIsize\fR\ [\fIfilename\fR]]]
.br
\*C/etc/nettest\fR
\%[\*C-c\fR]
\%[\*C-C\fR]
\%[\*C-d\fR]
\%[\*C-f\fR]
\%[\*C-h\fR]
\%[\*C-b\fR\ \fIbufsize\fR]
\%\*C-p\ file\fR\ \fIwritefile\ readfile\fR
\%[\fIcount\fR\ [\fIsize\fR]]
.br
\*C/etc/nettest\fR
\%\*C-V\fR
.sp
\*C/etc/nettestd\fR
\%[\*C-d\fR]
\%[\*C-p\ tcp\fR|\*Cudp\fR|\*Ciso\fR]
\%[\fIport\fR]
.br
\*C/etc/nettestd\fR
\%[\*C-d\fR]
\%\*C-p\ unix\fR|\*Cunixd\fR|\*Cpipe\fR
\%[\fIfilename\fR]
.br
\*C/etc/nettestd\fR
\%[\*C-d\fR]
\%\*C-p\ file\fR\ \fIreadfile\ writefile\fR
.br
\*C/etc/nettestd\fR
\%\*C-V\fR
.QE
.SH DESCRIPTION
The \*Cnettest\fR and \*Cnettestd\fR commands invoke client
and server programs that are used for timing data throughput of various
methods of interprocess communication.  For \s-1TCP\s+1 and \s-1OSI\s+1
connections,
the \*Cnettest\fR program establishes a connection with
the \*Cnettestd\fR program, and then it does \fIcount\fP writes
of \fIsize\fP bytes, followed by \fIcount\fP reads of
\fIsize\fP bytes.  For \s-1UDP\s+1, the \*Cnettest\fR program performs
only writes; reads are not performed.
The \*Cnettestd\fR program, if used with \s-1UDP\s+1 connections, reads
the data packets and prints a message for each data packet it
receives.
The number and size of the reads and writes may not
correlate with the number and size of the actual data packets
that are transferred; it depends on the protocol that is chosen.
If you append an optional \*Ck\fR (or \*CK\fR) to
the \fIsize\fP, \fIcount\fP, or \fIbufsize\fP value,
the number specified is multiplied by 1024.
.PP
The \*Cnettest\fR and \*Cnettestd\fR commands accept the following
arguments:
.QS
.TP
\*C-c\fP
To specify that the data must be checked
to verify its accuracy, use the \*C-c\fR flag.
.QE
Because this is done by comparing one character at a time,
using the \*C-c\fP option can cause noticeable throughput degradation.
The data is verified by filling up the data buffer with a 32-byte repeating
pattern of all the lower case letters and the first 6 upper case
letters of the alphabet.
This option is useful for detecting data that has been corrupted.
If there is a problem with lost or duplicated data, this option
may generate a large number of error messages.
.QS
.TP
\*C-C\fP
Similar to \*C-c\fR, except that the data is written out as
a sequence of sequential 64-bit numbers in network byte order.
.QE
Because this is done by comparing one word at a time,
it is slightly faster than the \*C-c\fR option, but it
can still cause noticeable throughput degradation.
This option is useful for detecting data that has been lost
or duplicated, as it resyncronizes itself when an error is
encountered.  However, if the size of the lost or duplicated
data is not an even multiple of 8, it may not resyncronize
properly.
.QS
.TP
\*C-d\fP
For \s-1TCP\s+1, \s-1UDP\s+1, and \s-1OSI\s+1 connections, the \*C-d\fR flag
turns on the socket-level debugging flag.
.QE
.br
.ift .ne 7vs
.br
.QS
.TP
\*C-f\fP
Indicates that a full-size read must be issued.
.QE
Usually, when a read returns a short count,
both \*Cnettest\fR and \*Cnettestd\fR issue a
read for the remaining data for that buffer,
whether or not a short count was received.
(The total number of bytes is not changed.)
.QS
.TP
\*C-F\fP
For \s-1TCP\s+1 connections,
the \*C-F\fR flag turns on the \*CTCP_NODELAY\fR socket option.
.QE
The \s-1TCP\s+1 code in the kernel usually tries to send only
full-sized packets over the network; this is accomplished
by delaying some writes until a full packet size
accumulates.  The \*C-F\fR flag disables this algorithm.
.QS
.TP
\*C-h\fP
To turn on hash marks to be printed,
.QE
use the \*C-h\fR flag.
Each time a complete buffer is written or read, a hash mark is printed.
If a read returns a partial count and the \*C-f\fR flag
is not specified, a period is printed.
If the \*C-f\fR flag is specified,
a hash mark is printed each time a read completes,
regardless of the amount of data read.
.QS
.TP
\*C-b\fP \fIbufsize\fP
This option applies only to \*Cnettest\fR.
For \s-1TCP\s+1 and \s-1UDP\s+1 connections, use the \*C-b\fR flag 
to specify the amount of kernel buffering allowed.
.QS
.TP
\*C-b\fP
This option applies only to \*Cnettestd\fR.
Run as a background daemon.  In this mode, \*Cnettestd\fR
will detach itself from its controlling terminal, and put itself
into the background.
In addition, all error messages are logged
via \*Csyslog\fR(3), instead of via \*Cperror\fR(3).
Note that if both the \*C-C\fR and \*C-v\fR options are used
in conjunction with the \*C-b\fR option, any errors that are
detected in the data stream will not be reported.
.QE
.QS
.TP
\*C-S \fItos\fP
For \s-1TCP\s+1 and \s-1UDP\s+1 connections, the \*C-S\fR option
can be used to specify the Type-of-Service (\s-1TOS\s+1) value for the
connection.
.QE
A check for the symbolic name \fItos\fR in \*C/etc/iptos\fR
determines the actual order.
(The \*C-t\fR \fItos\fR option is a valid synonym, for historical
compatibility.)
.QS
.TP
\*C-n\fP \fInconns\fP
For \s-1TCP\s+1, \s-1UNIX\s+1 and \s-1ISO\s+1 connections,
the \*C-n\fR option specifies the number of
simultaneous connections to be opened.
.QE
For each connection, a subprocess is created.
Each subprocess, after establishing a connection to the
server and negotiating the options, suspends itself.
When all the connections have been established, a continue
signal is sent to all the subprocesses to start them running
at the same time.
As each subprocess completes, it returns its timing results,
and returns that information to the main process, which
then prints out the individual timing information.
After all the subprocesses have completed, aggregate timing
results given.
The aggregate timings are based on the total amount of data
transferred by all the subprocesses, the start time of the first
subprocess to begin writing its data to its server, and end time
of the last subprocess to complete reading its data from its server.
The syncronization information shows when each subprocess began running,
the duration of the data transfer for each subprocess, and
ending time of each subprocess.
These times are relative to the start time of
the first subprocess to began running.
.br
.ne 10v
.QS
.TP
\*C-p \fIprotocol\fP
Specifies the protocol in use.
.QE
The valid values for \fIprotocol\fR are
\*Ctcp\fR, \*Cudp\fR, \*Ciso\fR, \*Cunix\fR, \*Cunixd\fR, \*Cpipe\fR, and \*Cfile\fR. 
.sp .5
If the \*C-p\fR option is not specified, \*Ctcp\fR is the default.
.sp .5
The \*Cunix\fR protocol uses \s-1UNIX\s+1 domain stream sockets;
\fIfilename\fR can be specified to override
the default file name \*Cnt_socket\fR.
.sp .5
The \*Cunix\fR protocol uses \s-1UNIX\s+1 domain datagram sockets;
\fIfilename\fR can be specified to override
the default file name \*Cnt_dsocket\fR.
.sp .5
For \*Cpipe\fR protocol connections, two named pipes are created when
you specify \fIfilename\fR, one for
reading and one for writing.  The \*Cnettest\fR program creates
the names of these files by appending \*CR\fR and \*CW\fR
to \fIfilename\fR.  The default names are \*Cnt_pipeR\fR and
\*Cnt_pipeW\fR.
.sp .5
For \*Cfile\fR protocols, \fIwritefile\fP is the name of the special file
to which information is written; \fIreadfile\fP is the name of the special file
that is read.  The order of \fIwritefile\fP
and \fIreadfile\fP is reversed between \*Cnettest\fR and \*Cnettestd\fR.
This allows the same file names to be specified in the same order
for both \*Cnettest\fR and \*Cnettestd\fR,
because the file to which \*Cnettest\fR
writes is the file from which \*Cnettestd\fR reads, and vice versa.
The intent of this option is to allow \*Cnettest\fR to be run
across arbitrary devices that have a character-device interface that
can be accessed just by opening up a special character file for
reading or writing.  It is not intended for for reading or writing to
a regular file.
.QS
.TP
\*C-s\fIn\fP
Increases the maximum \s-1TCP\s+1 window by a factor of 2^\fIn\fR;
1 \(<= \fIn\fR \(<= 14.
.QE
.QS	
.TP
\*C-m\fP
Indicates that for datagram connections
(\*C-p udp\fR and \*C-p unixd\fR) that \*Cnettest\fR
should use the \*Csendmsg\fR system call
insted of the \*Csendto\fR system call (see \*Csend\fR(2)),
and that \*Cnettestd\fR
should use the \*Crecvmsg\fR system call
insted of the \*Crecvfrom\fR system call (see \*Crecv\fR(2)),
For other protocols this option is ignored.
.QE
.QS
.TP
\*C-w\fP
Use the MSG_WAITALL flag when calling \*Crecv\fR(2).
This allows the kernel to accumulate incoming data so that
the read buffer is filled before returning control to
the application.
The use of this option negates the
need for the \*C-f\fR option.
.QE
.QS
.TP
\*C-V\fP
Print out information about the version of the program.
.QE
.QS
.TP
\fIhost\fP
For \s-1TCP\s+1, \s-1UDP\s+1, and \s-1OSI\s+1 connections, 
\fIhost\fR is the name
of the machine on which the server is running.
.QE
If this is omitted or specified as \*C-\fR, the
name that \*Cgethostname\fR(2) returns is used.
.QS
.TP
\fIcount\fR
Specifies the number of read or write operations. 
.QE
A value of \*C-\fR
indicates that the default value must be used.  The default value is
\*C100\fR.
.QS
.TP
\fIsize\fR
Specifies the number of bytes to be read or written. 
.QE
A value of \*C-\fR indicates that the default value must be used.
The default value is \*C4096\fR.
.QS
.TP
\fIport\fP
For \s-1TCP\s+1 and \s-1UDP\s+1 connections, specify \fIport\fP 
to select an alternate port number.
.QE
The \fIport\fP must be a decimal number.
.PP
The output from \*Cnettest\fR is timing information and a
histogram of the various sizes that the read operations returned.
System load affects the results because
all throughput times are calculated from wall-clock times.
The percentages listed for system and user times are
percentages of wall-clock time.
.PP
The write time is measured from the time
at which the application starts its first write until the time
it completes its last write.
The read time begins when the last write is complete and ends when
the last read is complete.
Because the kernel may buffer outgoing data,
if everything on the network is working correctly, it
is normal for the write times to be slightly faster than the
read times.  This difference in throughput represents the
amount of buffering in the kernel and the network round-trip
time.
The read and write time is measured from the time the first write
is started to the time the last read is completed; thus, if
the speed of the network is the same in both directions and
both machines have the same processing power and load,
the read and write times are
the most accurate.
.PP
The histogram output shows the sizes that
the read system calls return.
These may not have any correlation to the size and number
of packets that are actually sent and received over the network.
This is especially true for \s-1TCP\s+1 connections.
.SH FILES
.TP 30
\*C/etc/iptos\fP
\s-1IP\s+1 (\s-1TOS\s+1) database
.TP
\*Cnt_socket\fR and \*Cnt_dsocket\fR
Default name for stream and datagram \s-1UNIX\s+1 domain sockets
.TP
\*Cnt_pipeW\fR, \*Cnt_pipeR\fR
Default names for named pipes
.br
.ne 10v
.SH BUGS
The \*C-p pipe\fR, \*C-p unix\fR and \*C-p unixd\fR options create named pipes
and \s-1UNIX\s+1 domain sockets, respectively, that remain after
the programs exit.
.PP
If \*C-p pipe\fR \fIfilename\fP is specified and \fIfilename\fR
is either a relative or absolute path name,
neither \*Cnettest\fR nor \*Cnettestd\fR
insert the \*CW\fR and \*CR\fR before the final component
of the path name; they are always prepended to the entire
file name.
.br
.ift .ne 6vs
.br
.SH SEE ALSO
\*Cgethostname\fR(2), \*Crecv\fR(2), and \*Csend\fR(2) in \*(Cs
.\" KEY WORDS
.\" Principal developer: D.Borman
.UI "USMID @(#)man/man8/nettest.8	80.16	11/09/92 11:30:40"
.FP