duplication and extended reporting support.

filters data streams, much like the UNIX tool dd(1) . It has a more traditional commandline syntax, support for precise bandwidth limiting and reporting and support for FIFOs. Data limits and throughput rate calculation will work for files > 4 GB.

Cstream reads from the standard input and writes to the standard output, if no filenames are given. It will also 'generate' or 'sink' data if desired.

Options:

-b num

Set the block size used for read/write to num . The default is 8192 bytes.

-B num

Buffer input up to num bytes before writing. The default is the blocksize. It is an error to set this to anything below the blocksize. Useful when writing tapes and simlilar that prefer few large writes of many small.

-c num

Concurrent operation. Use a seperate process for outout. This is especially useful in combination with the -B option.

0 = use one process only (default)

1 = read process will buffer

2 = write process will buffer

3 = both processes will buffer.

In combination with a large buffer size this will often load your memory heavily, everytime the reader transfers the buffer it collected to the writer. If you use -c 3 and have a buffer size of 128 Megabytes 256 MB of memory will be touched at once.

-i num

-o num

Set the file names to use for input or output, respectivly. If the output file name is "-", data will just be discarded. If the input file name is "-", data will be generated 'out of the void'. If these options aren't given, stdin/stout will be used. If you need to give -o or -i options and want stdin/stdout, specify the empty string, like this: cstream -i'' If TCP support has been compiled in (default), hostname:portnumber will try to connect to the specified host at the specified port and :portnumber will open a TCP socket on the local machine and wait for a connection to arrive. SECURITY NOTE: cstream includes no mechanism to restrict the hosts that may connect to this port. Unless your machine has other network filters, anyone will be able to connect.

-I string

-O string

Specify the type of input and output file, respectivly.

If string

includes 'f', a fifo will be created.

If string

includes 'a', the file will be assumed to be a opensound-compatible audio device and will be switched to CD-like settings.

If string

includes 't', a copy of the stream will be sent to file descriptor 3.

If string

includes 'N', TCP will not be used for that file even if the name has a ":".

-l

Include line count in statistics.

-n num

Limit the total amount of data to num . If there is more input available, it will be discarded, cstream will exit after the limit has been reached. If there is less input, the limit will not be reached and no error will be signaled. num may have a trailing 'k', 'm' or 'g' which means Kilobytes, Megabytes or Gigabytes (where Kilo = 1024). This applies to all numeric options.

-p filename

Write the process id of cstream to filename . If cstream uses a seperate writer process (option -c), this is the pid of the parent (reader) process.

-t num

Limit the throughput of the data stream to num bytes/second. Limiting is done at the input side, you can rely on cstream not accepting more than this rate. If the number you give is positive, cstream accumulates errors and tries to keep the overall rate at the specified value, for the whole session. If you give a negative number, it is an upper limit for each read/write system call pair. In other words: the negative number will never exceed that limit, the positive number will exceed it to make good for previous underutilization.

-T num

Report throughput every num seconds.

-v num

Set verbose level to num . By default, it is set to 0, which means no messages are displayed as long as no errors occur. A value of 1 means that total amount of data and throughput will be displayed at the end of program run. A value of 2 means the transfer rate since the end of the first read/write pair will also be reported (useful when there is an initial delay). A value of 3 means there will also be seperate measurements for read and write. This option is resource-consuming and currently isn't implemented. A value of 4 means that notices about each single read/write will be displayed. High values include all message types of lower values.

-V

Print version number to stdout and exit with 0.

filename

A single filename as the last argument without an option switch will be used as input file if -i has not been used.

SIGUSR1

SIGINFO

Sending SIGUSR1 (or SIGINFO, which is usually mappend to Control-T on you keyboard) to cstream causes it to display throughput rates to stderr. The stream will continue as if nothing happend.

SIGUSR2

Exit and report throughput rates, if requested.

SIGHUP

I found myself sending SIGHUP accidentially too often. But ignoring or misusing SIGHUP is not an option for me. Thus, when cstream received SIGHUP, it will wait 5 seconds for another SIGHUP, to give users a chance to correct a possible mistake. If no additional SIGHUP is received, cstream kills itself with SIGHUP.

cstream -o tmpfile -v 1 -n 384m -i -

Writes 384 Megabytes of unspecified data to file tmpfile and display verbose throughput rate. Makes a good benchmark, the speed of /dev/null varies too much from system to system.

cstream -i tmpfile -v 1 -n 384m -o -

Read the same file back in and discard data.

cstream -b 2000 -t 10000 /var/log/messages

Will display the file in a more or less watchable speed.

dump 0sf 400000 - / | cstream -v 1 -b 32768 -o /dev/rst0 -p pidfile

kill -USR1 `cat pidfile`

Write the output from dump(1) to tape. Each time the signal is sent, the throughput and data rate so far will be displayed.

cstream -t 176400 -i /dev/dsp0 -I f -o -

Makes kind of a soundcard emulator which may be used to test audio applications that need something to write to that limits the data rate as a real soundcard does. This obviously doesn't work when the application tries to write data using mmap(2) and the application has to ignore errors when it tries to set soundcard parameters using ioctl(2).

cstream -t 176400 -i /dev/dsp0 -I f -o /dev/dsp1 -O f

Similar soundcard emulator, except that it allows you to grab the data your applications sends to it from the other fifo, while still having precise timing.

cstream -Oa -o /dev/dsp0 myhost.mydomain.com:17324

Connects port 3333 on host myhost.mydomain.com and whatever data it finds there will be sent to the soundcard, with appropriate settings for CD quality stero play.

cstream -i myaudiofile.raw -o :17324

This will open a TCP server on port 17324 and waits until someone connects (for example, the commandline from the previous example). Then it will send the contents of myaudiofile.raw down the TCP stream (for the previous audio example, typically a CD audiotrack like you get from the tosha or cdparanoia utilities).

Exit code 0 means success.

Exit code 1 means a commandline syntax usage error.

Exit code 2 means other errors, especially system errors.

There should be an option to begin writing directly after the first read ended and then fill the buffer with reads in the background. Right now writing will not begin before the reader has filled the buffer completely for the first time.

was initially written by Martin Cracauer in 1998. For updates and more information see http://www.cons.org/cracauer/cstream.html