DragonFly On-Line Manual Pages
NETTEST(8) DragonFly System Manager's Manual NETTEST(8)
NAME
nettest, nettestd - Performs client and server functions for timing
data throughput
SYNOPSIS
/etc/nettest [-c] [-C] [-d] [-f] [-F] [-h] [-b bufsize] [-S tos]
[-n conns] [-p tcp|udp|iso] [-sn] [-m] [-w]
[host [count [size [port]]]]
/etc/nettest [-c] [-C] [-d] [-f] [-h] [-b bufsize] -p unix|unixd|pipe
[-n conns] [-w] [count [size [filename]]]
/etc/nettest [-c] [-C] [-d] [-f] [-h] [-b bufsize]
-p file writefile readfile [count [size]]
/etc/nettest -V
/etc/nettestd [-d] [-p tcp|udp|iso] [port]
/etc/nettestd [-d] -p unix|unixd|pipe [filename]
/etc/nettestd [-d] -p file readfile writefile
/etc/nettestd -V
DESCRIPTION
The nettest and nettestd commands invoke client and server programs
that are used for timing data throughput of various methods of
interprocess communication. For TCP and OSI connections, the nettest
program establishes a connection with the nettestd program, and then it
does count writes of size bytes, followed by count reads of size bytes.
For UDP, the nettest program performs only writes; reads are not
performed. The nettestd program, if used with UDP 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 k
(or K) to the size, count, or bufsize value, the number specified is
multiplied by 1024.
The nettest and nettestd commands accept the following arguments:
-c To specify that the data must be checked to verify its accuracy,
use the -c flag. Because this is done by comparing one
character at a time, using the -c 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.
-C Similar to -c, except that the data is written out as a sequence
of sequential 64-bit numbers in network byte order. Because
this is done by comparing one word at a time, it is slightly
faster than the -c 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.
-d For TCP, UDP, and OSI connections, the -d flag turns on the
socket-level debugging flag.
-f Indicates that a full-size read must be issued. Usually, when a
read returns a short count, both nettest and nettestd 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.)
-F For TCP connections, the -F flag turns on the TCP_NODELAY socket
option. The TCP 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
-F flag disables this algorithm.
-h To turn on hash marks to be printed, use the -h flag. Each time
a complete buffer is written or read, a hash mark is printed.
If a read returns a partial count and the -f flag is not
specified, a period is printed. If the -f flag is specified, a
hash mark is printed each time a read completes, regardless of
the amount of data read.
-b bufsize
This option applies only to nettest. For TCP and UDP
connections, use the -b flag to specify the amount of kernel
buffering allowed.
-b This option applies only to nettestd. Run as a background
daemon. In this mode, nettestd will detach itself from its
controlling terminal, and put itself into the background. In
addition, all error messages are logged via syslog(3), instead
of via perror(3). Note that if both the -C and -v options are
used in conjunction with the -b option, any errors that are
detected in the data stream will not be reported.
-S tos For TCP and UDP connections, the -S option can be used to
specify the Type-of-Service (TOS) value for the connection. A
check for the symbolic name tos in /etc/iptos determines the
actual order. (The -t tos option is a valid synonym, for
historical compatibility.)
-n nconns
For TCP, UNIX and ISO connections, the -n option specifies the
number of simultaneous connections to be opened. 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.
-p protocol
Specifies the protocol in use. The valid values for protocol
are tcp, udp, iso, unix, unixd, pipe, and file.
If the -p option is not specified, tcp is the default.
The unix protocol uses UNIX domain stream sockets; filename can
be specified to override the default file name nt_socket.
The unix protocol uses UNIX domain datagram sockets; filename
can be specified to override the default file name nt_dsocket.
For pipe protocol connections, two named pipes are created when
you specify filename, one for reading and one for writing. The
nettest program creates the names of these files by appending R
and W to filename. The default names are nt_pipeR and nt_pipeW.
For file protocols, writefile is the name of the special file to
which information is written; readfile is the name of the
special file that is read. The order of writefile and readfile
is reversed between nettest and nettestd. This allows the same
file names to be specified in the same order for both nettest
and nettestd, because the file to which nettest writes is the
file from which nettestd reads, and vice versa. The intent of
this option is to allow nettest 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.
-sn Increases the maximum TCP window by a factor of 2^n; 1 <= n <=
14.
-m Indicates that for datagram connections (-p udp and -p unixd)
that nettest should use the sendmsg system call insted of the
sendto system call (see send(2)), and that nettestd should use
the recvmsg system call insted of the recvfrom system call (see
recv(2)), For other protocols this option is ignored.
-w Use the MSG_WAITALL flag when calling recv(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 -f option.
-V Print out information about the version of the program.
host For TCP, UDP, and OSI connections, host is the name of the
machine on which the server is running. If this is omitted or
specified as -, the name that gethostname(2) returns is used.
count Specifies the number of read or write operations. A value of -
indicates that the default value must be used. The default
value is 100.
size Specifies the number of bytes to be read or written. A value of
- indicates that the default value must be used. The default
value is 4096.
port For TCP and UDP connections, specify port to select an alternate
port number. The port must be a decimal number.
The output from nettest 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.
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.
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 TCP connections.
FILES
/etc/iptos IP (TOS) database
nt_socket and nt_dsocket Default name for stream and datagram UNIX
domain sockets
nt_pipeW, nt_pipeR Default names for named pipes
BUGS
The -p pipe, -p unix and -p unixd options create named pipes and UNIX
domain sockets, respectively, that remain after the programs exit.
If -p pipe filename is specified and filename is either a relative or
absolute path name, neither nettest nor nettestd insert the W and R
before the final component of the path name; they are always prepended
to the entire file name.
SEE ALSO
gethostname(2), recv(2), and send(2) in
NETTEST(8)